--- name: kandev-canvas-authoring version: "1" description: Author a Kandev task canvas as a self-contained web application. --- # Kandev canvas authoring Use one `read_canvas_authoring_skill_kandev` call without `path` when you need the authoring contract. That response is the complete core bundle. It includes this workflow, the manifest and browser protocol summary, appearance rules, the minimal scaffold, and the exact supporting-file inventory. Do not read the core bundle again during the same authoring task. ## Required workflow 1. Call `create_canvas_kandev` with a short title and an application summary. It creates an inactive task canvas and returns its source directory, manifest scaffold, initial permission policy, and exact scaffold inventory. 2. Use native file tools in that returned directory. The initial files are `manifest.yaml`, `index.html`, `appearance.js`, `script.js`, and `styles.css`. Replace or extend them in the same directory. 3. Keep every source path relative to the returned directory. Do not write outside it. Bundle executable dependencies. Node, a package manager, and a network build step are not available at runtime. 4. Run local checks, then call `publish_canvas_kandev` with the returned canvas ID and source path. Read validation diagnostics and correct rejected source before publishing again. The first valid release of a new owner-authorized task canvas uses the returned initial permission policy. It can activate without a second approval for its declared supported permissions. Kandev data access is limited to the current workspace, while the canvas remains placed in its creating task. Imported packages and later permission increases need human review. Promotion changes workspace navigation. Do not add a trust flag to the manifest, and do not request permissions outside the policy. ## Core application contract - Include ``. - Use relative `./_kandev/v1` paths for Kandev data, state, actions, and events. - Treat Kandev domain data as the source of truth. Derive filters and summaries in memory instead of storing a second copy of domain records. - Store only small application-specific shared values in instance state. Keep temporary input in memory and use conditional revisions for writes. - The canvas runs in a trusted same-origin iframe. Treat its source as trusted user-session code: it can use same-origin browser storage and cookies and can access the host DOM. It has the viewing user's ordinary API authority. - Keep Kandev protocol requests relative and do not copy capability URLs or tokens into source, URLs, query strings, logs, or client state. Same-origin cookies do not replace capability validation or the grants on protocol routes. - Render loading, empty, error, and retry states. Keep destructive actions explicit and explain their result. - Use accessible labels, keyboard operation, visible focus, and touch targets. Kandev injects a reserved startup bootstrap into the entry document before authored scripts. It reports early document errors and checks the relative context route after document load. The host reveals the frame only after a versioned acknowledgement for the current attempt. A missing acknowledgement or context failure becomes recoverable after 15 seconds. Keep the entry valid HTML and render loading, empty, error, and retry states in the app. ## Minimal manifest Use the returned `manifest_scaffold` as the starting point. New manifests use `api_version: 2`, one lowercase web-app key, a package-relative `entry`, and at least one `task-canvas` or `workspace-canvas` placement. Declare only the `api_read`, `api_write`, `events`, `state`, and `network_origins` permissions that the application needs. The owner-authorized first release can receive only its declared supported permissions, with Kandev data limited to the current workspace. The entry and all relative assets must be in the published package. ## Browser protocol summary Resolve all routes from the application document with `./_kandev/v1`. Use `context`, the paginated `data` routes, `state/{key}` with `If-Match`, and the bounded `events` stream as documented by the optional references. Events are hints that invalidate a read. Refetch authoritative data after an event, reconnect with `Last-Event-ID`, and perform a full refetch after `runtime.resync_required`. ## Appearance protocol The host may send the public presentation-only message `kandev.web_app.appearance` with `version: 1`, `mode: light|dark`, and exactly these color tokens: `background`, `foreground`, `card`, `cardForeground`, `muted`, `mutedForeground`, `border`, `primary`, `primaryForeground`, `accent`, `accentForeground`, `destructive`, `destructiveForeground`, and `ring`. Accept it only when `event.source === window.parent`, the type and version match, the keys are exact, and each serialized color is bounded. Map the tokens to the same-name kebab-case CSS variables. Keep light and dark fallbacks so the app remains usable before the first message. The message has no identity, capability, data, storage, navigation, or action fields. The generated `appearance.js` implements this listener. It is optional, but copy its pattern when replacing the scaffold. Read a supporting reference only when its topic is needed: - `references/browser-api.md` for detailed browser routes and errors. - `references/manifest.md` for the full manifest shape and validation rules. - `references/data-and-state.md` for domain data and instance state. - `references/events-and-recovery.md` for events, reconnect, and retries. - `references/security.md` for same-origin trust and source safety rules. - `references/ui-patterns.md` for responsive and accessible UI patterns. ## Distribution checklist When the user asks for a portable canvas, keep the distribution boundary separate from authoring and runtime state: 1. Add `distribution.schema_version: 1`, `distribution.kind: canvas`, a license, and `source_mode: static` or `source_mode: project`. 2. Keep `README.md`, the manifest, the application entry, and every local asset in the package. Use project mode only when the retained project is complete and bounded below `distribution/source/`. 3. Publish a valid release before offering a bundle or source download. The host prepares both archives from that immutable release and does not include screenshots. 4. Add screenshots later as ordered `previews` objects in a registry entry. The first preview is the cover, canvas entries require one to eight images, and plugin entries may omit images. The authoring tools do not create repositories, releases, registry entries, or pull requests. Report those manual follow-up steps to the user. Do not claim that a local archive or build is published until the Kandev release flow confirms it.