kdlbs/kandev/files

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.

1. 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.

1. 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.

1. 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 <meta name="viewport" content="width=device-width, initial-scale=1">.
• 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.

1. 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/.

1. 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.

1. 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.