Skip to content
Worktable Docs

HTML doc runtime

This contract is returned by worktable_html_read with action guide. 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

Section titled “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?)
  • 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 action “validate” accepts raw Mermaid source, while action “preview” also returns an SVG that can be embedded.

Privacy