Projects and runnable packages

An authoring project may contain source files, dependencies and build tools. Users receive a built static directory and do not install Node.js or run author install/build commands.

Package boundary

Include manifest.json and the local HTML referenced by entry, defaulting to index.html. A missing implicit preview.png uses a placeholder; an explicitly declared PNG must exist. Resources use safe package-relative paths, without traversal, absolute paths, links or remote scripts.

window declares initial/minimum dimensions, initial layer and surface. Opaque is the default. Transparent work must explicitly handle native input mode and recovery; CSS cannot implement native click-through. Authors control size through the manifest and window.setSize; layouts do not override author size.

Declare runtime compatibility

Component version identifies the work release. SDK release versions identify development references; neither replaces runtime compatibility checks. hostApiMajor identifies the interface and behavior generation. Published contracts remain compatible within a generation; cross-generation support requires an explicitly implemented and verified host. The current supported generation is 1.

Declare mandatory host features in the manifest, for example "requiredFeatures": ["saves.load", "saves.commit"]. The default is an empty array. Identifiers match handshake features exactly: at most 256 unique entries, each containing 1–128 ASCII letters, digits, dots, underscores or hyphens. Require only features without which the component cannot run; probe optional features after ready and provide fallbacks. Supporting an interface does not grant permission. Handle denied capabilities independently.

Missing mandatory features or an unsupported API generation cause package checks and installation to return PROTOCOL_UNSUPPORTED. Failed updates preserve the active version. If an installed component becomes incompatible with the host, the UI shows an Incompatible badge and a plain-language notice, and disables the enable switch. Execution stops while personal data and enabled intent are preserved. Compatibility recovery automatically restores enabled components; components explicitly disabled during the block remain disabled. Incompatible layout dependencies prevent applying or restoring the layout. Bundling an older SDK cannot bypass the checks: the host provides the SDK.

See runtime compatibility for the contract.

Frontend tooling and types

Build locally resolvable assets and copy the manifest into the final directory. Bind that runnable output directory on the Development page. A development server URL is not a component package.

Use docs/public/sdk/widget-host.d.ts outside the package for editor/compiler types. TypeScript uses ES2020, DOM, strict and noEmit; do not conceal declaration problems with skipLibCheck. Confirm that the final package contains none of the three SDK filenames.

Copies, reloads and identity

The host runs a validated immutable copy, not the author directory directly. Development reloads use content hashes, allowing the declared version to stay unchanged; invalid input preserves the last successful version. Formal versions use three nonnegative integers.

Ordinary local import does not watch source files or offer directory updates. Add a development component explicitly; after moving the directory, remove the development installation and add it again from the new location. Removing development installation preserves author source but cleans installation-owned data.

See the package contract for exact fields, path and size budgets, and development behavior for reloads and draft protection.