Let third parties build full-page apps that run inside a Seed site — a site dashboard, a kanban board over a set of
documents, a custom directory — on both the web app and the desktop app, with these properties:

The extension is ordinary HTML/JS/CSS in a sandboxed iframe. Any framework works.

The extension can read hypermedia data and sign as the current user (comments, document changes, arbitrary

data) through a bridge; it never sees a key.

The extension is distributed as hypermedia data: a signed, versioned, content-addressed document that syncs

peer-to-peer like everything else.

A site installs an extension by writing a record into its home document. Installation is therefore also just

signed data.

Developers get a hot-reload loop against the real host app.

Everything here is designed so the same packaging, install and bridge layers can later host other extension kinds
(custom blocks, attribute editors, themes).

All schemas live in frontend/packages/client/src/extensions.ts (published in @seed-hypermedia/client). That file is
normative; this section summarises it.

3.1 Manifest — metadata.seedExtension on the extension document

{
  "manifestVersion": 1,
  "kind": "page", // page | block | attribute | theme (only page implemented)
  "version": "0.1.0", // informational semver
  "entry": "ipfs://bafk...", // single self-contained HTML file
  "description": "Kanban board over site documents",
  "permissions": ["sign", "navigate", "storage"],
  "defaultMountPath": "board",
  "homepage": "https://github.com/..."
}

3.2 Install record — metadata.extensions on the site home document

{
  "extensions": {
    "board": {
      "ext": "hm://z6MkAuthor.../kanban",
      "version": "bafy...", // pinned extension document version (default)
      "title": "Board", // optional nav title
      "nav": true, // optional, default true
      "settings": {"columns": 4} // optional, passed to the extension context
    }
  }
}

3.3 Resolution

Both hosts already render "site header + custom body" through PageWrapper in
frontend/packages/ui/src/resource-page-common.tsx (feed-page-common.tsx is the reference). Extension pages reuse it.

4.1 @shm/ui — extensions/

export type ExtensionHostAdapter = {
  platform: 'web' | 'desktop'
  /** Signed-in viewer for this site, or null. Re-render the provider when it changes. */
  user: {accountId: string; name?: string} | null
  theme: 'light' | 'dark'
  /** Public origin of the site when known (web only). */
  siteOrigin?: string
  /** Fetch the entry HTML by CID. web: /hm/api/file/<cid>; desktop: <daemon http>/ipfs/<cid>. */
  fetchEntryHtml: (cid: string) => Promise<string>
  /** URL an iframe can use for a CID (web: absolute /hm/api/file/<cid>; desktop: daemon URL). */
  fileUrl: (cid: string) => string
  /** Read a file's bytes through the host. */
  readFile: (cid: string, maxBytes: number) => Promise<{bytes: Uint8Array; contentType?: string}>
  /** Navigate the host app (hm:// or site-relative). */
  navigate: (url: string, opts: {replace?: boolean}) => void
  openExternal: (url: string) => void
  /** Update the URL beneath the mount without leaving the page. */
  setRoute: (subPath: string[], query: Record<string, string> | undefined, opts: {replace?: boolean}) => void
  toast: (message: string, kind: 'info' | 'success' | 'error') => void
  /** Storage namespace (defaults to localStorage on both platforms). */
  storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem' | 'key' | 'length'>
}

4.2 Web (frontend/apps/web)

4.3 Desktop (frontend/apps/desktop)

Normative types: ExtensionMethods, ExtensionEvents, message shapes in extensions.ts. Summary:

Transport: postMessage. Iframe→host targets window.parent with '*' (opaque origin has no usable origin string).

Host→iframe targets iframe.contentWindow with '*' for the same reason; the host trusts only
event.source === iframe.contentWindow.

Every message: { "seed-extension": 1, type: 'request'|'response'|'event', ... }.

Handshake: SDK sends hello (retrying until answered); host replies with the ExtensionContext. Host pushes

context events on any change (user, theme, route).

Reads: api.query {key, input} restricted to EXTENSION_READ_QUERY_KEYS. The host accepts hm:// strings for

id fields in Resource and ResourceMetadata inputs (and the nested id fields listed in ID_FIELDS) and unpacks
them (the SDK stays dependency-free); Query, Search and ListEvents take no ids and are validated whole with
their zod schemas.

Writes: sign.comment, sign.document, sign.data — each requires the sign permission, a signed-in user, and user

confirmation.

sign.comment derives the thread root from the parent comment: when replyCommentVersion is given without

rootReplyCommentVersion, the host fetches the parent and uses its threadRoot, falling back to the parent itself
when the parent is a root — the same rule as the daemon's CreateComment and the other clients.

sign.document builds the Change client-side with metadata set-attribute ops (null → delete) and optional full

body replace via blocks (createChangeOps, createChange), signs a Version Ref (createVersionRef) and
publishes the blobs with universalClient.publish. The result version is the CID of the signed Change. When
nothing differs from the published document the call resolves with the current version without a dialog. Metadata
changes to extensions or seedExtension are always confirmed, even with a session grant.

sign.data signs buildSignDataPayload(extensionId, bytes) — a domain separated prefix so an extension signature

can never be replayed as a protocol blob. Returns signature, signer principal and account id.

Errors: {code, message} with codes

permission_denied | user_rejected | not_signed_in | unknown_method | invalid_params | not_supported | internal.

Sandbox. Opaque origin, no cookies/storage of the host, no DOM access, no same-origin fetch. The entry HTML is

inert bytes until loaded into the sandbox; the host never evals it.

Keys never cross the bridge. Signing goes through HMSigner on the host (web: non-extractable WebCrypto device

key holding a vault delegation; desktop: daemon SignData). The iframe gets bytes back, never key material.

Every signature is confirmed by a native dialog naming the extension, the account and the effect. The dialog warns

when a dev override is active, and its Approve button is inert for ~500 ms after opening so an in-flight click
cannot approve. A session-scoped "always allow" exists for convenience; it is never persisted, it is keyed on
(extension, site, account, code source), and it never covers changes to the extensions install records or a
seedExtension manifest — those are always confirmed.

Domain separation for raw signatures (sign.data).

Version pinning by document version CID: the site owner chooses when the code they run changes. Dev overrides are

the only exception and are per browser: ?extdev= accepts loopback URLs only, everything else is ignored.

Permissions are declared in the manifest and enforced per method; the install UI shows them.

Install is signed data — only holders of write capability on the site's home document can install.

Non-goals for v1: network egress control (the iframe can fetch any CORS endpoint), resource limits, cross-extension

isolation beyond separate iframes.

pnpm create a vite project (or copy extensions/examples/hello-signer). Build to one file with

vite-plugin-singlefile.

pnpm dev (fixed port). Open the extension page in the host with ?extdev=http://localhost:5181 (web) or set the

override in desktop Settings → Advanced. The iframe now loads the dev server with HMR.

seed-cli extension publish ./ --key mykey -p my-ext → uploads dist/index.html to IPFS, writes the manifest into

the extension document's metadata, README as body.

seed-cli extension install hm://<me>/my-ext --path board --key sitekey (or desktop Site settings → Extensions).

Iterate: publish a new version; sites that pinned see "update available".

Unit: client/src/extensions.test.ts; SDK tests (fake parent window); ui bridge-server tests (permission

enforcement, error mapping, hm:// id unpacking, confirm flow).

CLI fixture test: publish an extension from a fixture dir, install on the fixture site, document get shows the

record, GET /<mount> on the web server returns the extension page shell.

Browser test (Playwright, tests/): load the mounted page, assert the sandboxed iframe exists, that hello completes

(the hello-signer example renders the context), and that a sign.data request opens the confirmation dialog and
resolves after approval.

Manual: desktop + web against mainnet with the examples published under the starlight space.

The packaging (document + manifest), install records, resolution, bridge, permission model, confirmation dialog, dev
overrides and CLI are all kind-agnostic. To add:

Custom block — kind: 'block', contributes.blocks[], the same ExtensionFrame mounted per block with

ui.resize honoured, block attributes passed in context, block.setAttributes bridge method.

Attribute UI — kind: 'attribute', frame mounted inside the metadata editor.

Theme — kind: 'theme', no code; manifest carries CSS variables.

Template UI modality — a second host implementing the same bridge with native components instead of an iframe

(mobile).