Skip to content
Worktable Docs

HTML doc runtime

This is the runtime profile returned by worktable_html_read with action guide and profile runtime. Agents should prefer that tool response while authoring because it matches the server they are connected to.

HTML docs are self-contained pages rendered in a sandbox inside a Worktable space. Return one complete document with doctype, html, head, viewport metadata, and body. Do not load external scripts, stylesheets, fonts, images, or other http/https assets; use inline SVG, CSS, data URLs, and local HTML/JavaScript.

Design mobile first and remain responsive. Use semantic headings and controls, readable contrast, visible focus states, and comfortable click/touch targets. Follow the parent theme with semantic CSS variables and light/dark overrides. Treat validation warnings and runtime diagnostics as repair instructions and fix them before handoff when possible.

Runtime and data contract

Section titled “Runtime and data contract”

Use Records for canonical shared data and worktable.state for HTML-doc-local UI state such as filters, drafts, preferences, and selections. Do not use localStorage, sessionStorage, or indexedDB for important state. Avoid direct /api fetches.

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.ui.notify(message, options?)
  • worktable.ui.getTheme()
  • worktable.ui.getViewport()
  • worktable.diagnostics.report({ level, code, message, hint, detail })

Grant explicit per-collection permissions for every worktable.records call. Cross-collection expansion, backlinks, and relation-path filters also need read permission on target collections. Worktable warns when literal calls reveal missing permissions; dynamic collection ids must be covered explicitly.

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

Use addEventListener for interaction. Buttons should use type=“button” unless handling a form submit. Forms cannot navigate the sandbox safely; attach a submit handler and 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, so validate each Mermaid source with worktable_mermaid action “validate” before saving; use action “preview” when rendering needs inspection or embed the returned SVG.