HTML runtime

This contract is returned by worktable_guidance with topic html. It matches the server runtime that handles the HTML Doc.

HTML Docs are complete, self-contained documents rendered in a sandbox inside a Worktable Space. Each document includes doctype, html, head, viewport metadata, and body. External scripts, stylesheets, fonts, images, and other http/https assets are not supported; ordinary links are supported, and inline SVG, CSS, data URLs, and local HTML/JavaScript remain inside the artifact.

Runtime and data contract

Records hold canonical shared data. worktable.state holds HTML-Doc-local UI state such as filters, drafts, preferences, and selections. Browser storage is not a supported persistence contract, and direct /api fetches are not a supported Worktable data interface.

The parent theme is available through these semantic variables: –ad-bg, –ad-surface, –ad-surface-2, –ad-text, –ad-muted, –ad-border, –ad-accent, –ad-accent-soft, –ad-danger, –ad-warning, –ad-success, –ad-radius, –ad-shadow.

Documents can define default/light values and html[data-theme=“dark”] overrides, and can declare color-scheme: light dark.

Available APIs:

• worktable.records.query(collectionId, query?)
• worktable.records.queryDetailed(collectionId, query?)
• worktable.records.create(collectionId, data, options?) (options.id never overwrites: an id that already exists rejects with CONFLICT; use update)
• worktable.records.update(collectionId, recordId, patch)
• worktable.records.delete(collectionId, recordId)
• worktable.records.subscribe(collectionId, query?, callback)
• worktable.records.subscribeDetailed(collectionId, query?, callback)
• worktable.state.get(key?)
• worktable.state.set(key, value) or worktable.state.set(patch)
• worktable.state.update(async current => nextState)
• worktable.navigation.openDocument(path)
• worktable.ui.notify(message, options?)
• worktable.ui.getTheme()
• worktable.ui.getViewport()
• worktable.diagnostics.report({ level, code, message, hint, detail })

Every worktable.records call requires explicit per-collection permissions. Cross-collection expansion, backlinks, and relation-path filters also require read permission on target collections. Worktable warns when literal calls reveal missing permissions; dynamic collection ids require explicit coverage.

Outbound fetch requires network permission. Without permission, the sandbox blocks it. Runtime APIs are brokered through the parent and do not need network permission.

openDocument accepts a Space-root document path such as plans/brief and must be called from a button or link click. Worktable follows moved-path aliases and opens the canonical document. Docs with registered viewers use their specialized view; other supported formats open a read-only download fallback. Missing or conflicting documents reject without leaving the current HTML Doc.

addEventListener is supported for interaction. Buttons default to form submission unless type=“button” is set. Forms cannot navigate the sandbox safely; submit handlers can persist through Records or state. Inline event handlers are accepted with a warning.

Narrative Doc writes validate Mermaid automatically. HTML cannot reliably expose Mermaid embedded in arbitrary markup or JavaScript. worktable_mermaid validates raw Mermaid source; with preview: true it also returns an SVG that can be embedded.

Share links

Someone can share an HTML Doc by link with people outside the team, including its live data. Visitors run the same HTML with the same SDK, read-only: records create, update and delete reject with LINK_READ_ONLY, state writes last only for that visitor’s browser tab, and openDocument is unavailable. Visitors can read only the collections and fields the link grants, so handle a rejected query the way you handle a missing permission. Write one tool for members and visitors; don’t detect visitors or build a separate version.

Visual inspection

Use worktable_files_render with the HTML Doc’s path to receive a PNG of the saved document alongside revision, font/renderer versions, and diagnostics. HTML create/update can request an opt-in preview object; omit it to save without rendering. Preview controls are theme, width, height, fullPage, clip in document CSS pixels, and timeoutMs. Request a narrow and a wide viewport to inspect responsive layouts.

Previews run the same HTML runtime with read-only data authority: permitted state reads and Records query POSTs work, but persistent state/Records writes, navigation, and external network are blocked. Records reads require both caller records:read scope and document collection permissions, including related collections. State is frozen; Records are live observations during capture, not a historical database snapshot. An app that writes during initialization may produce a partial preview.

A preview reports ready, partial, failed, or unavailable. Inspect diagnostics rather than treating an image as proof that every asynchronous task completed. A saved write remains successful even if its preview fails; retry worktable_files_render, not the write. The preview identifies the exact saved source revision, and state/data capture metadata explains why identical HTML can look different later.