{"contextKind":"public_baseline","language":"en","id":"interactive-html","version":null,"contractDigest":"sha256:96433212233224233944eba6ba33eced1f1d2118ae574825df1b6426259894ba","title":"Interactive HTML authoring","kind":"current-guidance","files":[{"path":"docs/guides/authoring-interactive-html-artifacts.md","digest":"sha256:d3ae575507b237fbf41c0aec9dce233bb96c2fd2d94a833e9a73f42ecc70351d","mediaType":"text/markdown","content":"---\nrole: guidance\nlifecycle: current\nlanguage: en\n---\n# Authoring Interactive HTML Artifacts\n\n## Purpose\n\nThis guide defines the authoring contract for HTML knowledge views executed by OrivelaIQ under the source policy `interactive`.\n\nInteractive artifacts are executable repository content. They run JavaScript in every viewer's browser, but only inside an isolated sandbox. The optional `orivelaiq.artifact.v1` protocol provides mediated navigation into the current OrivelaIQ workspace.\n\n## Required artifact shape\n\nAn interactive artifact must be a self-contained single HTML file containing all required:\n\n- HTML;\n- CSS;\n- JavaScript;\n- data;\n- images;\n- fonts;\n- libraries.\n\nThe artifact must not depend on a CDN, external stylesheet, external font, remote image, API or other network resource.\n\n## Supported capabilities\n\nAuthors may use JavaScript to:\n\n- filter and sort embedded data;\n- implement local search;\n- switch categories and views;\n- expand details;\n- render embedded charts;\n- perform client-side calculations;\n- maintain transient in-memory UI state;\n- request viewer-mediated navigation through the versioned `orivelaiq.artifact.v1` message contract when a host handshake advertises the `navigate` capability.\n\nNative HTML and CSS should be preferred where they are sufficient.\n\n## Unsupported capabilities\n\nArtifacts must not depend on:\n\n- `fetch`, `XMLHttpRequest`, WebSocket or EventSource;\n- cookies;\n- `localStorage`, `sessionStorage` or IndexedDB;\n- form submission;\n- popup windows;\n- direct top-level navigation;\n- parent DOM, router, index or workspace-data access;\n- runtime credentials, secrets or tokens;\n- external scripts, styles, fonts, images or CDNs.\n\nA narrow `window.parent.postMessage()` request channel is permitted only through the `orivelaiq.artifact.v1` navigation contract. This does not grant parent DOM access or direct navigation rights.\n\nDo not embed secrets in source code, inline data, comments or generated output.\n\n## Asset strategy\n\n### Fonts\n\n- Use a system font stack as the default or fallback.\n- Embedded fonts must use a license that permits embedding.\n- Prefer subsetted WOFF2 data URIs.\n- Avoid embedding complete font families when only one or two weights are needed.\n\n### Images\n\n- Prefer inline SVG for diagrams and icons.\n- Use `data:` URIs for raster images when needed.\n- Provide meaningful alternative text.\n\n### Libraries\n\n- Vendor only the required production code.\n- Inline the library in the artifact.\n- Remove unused modules and development helpers.\n- Record the library name, version and license in a source comment or adjacent repository documentation.\n\n## Mediated navigation\n\nInteractive artifacts may act as maps, indexes or dashboards that request navigation into the current workspace.\n\nThe artifact must wait for this host handshake:\n\n```json\n{\n  \"protocol\": \"orivelaiq.artifact.v1\",\n  \"type\": \"host-ready\",\n  \"capabilities\": [\"navigate\"]\n}\n```\n\nIf no handshake arrives, the artifact must remain usable standalone.\n\nSupported navigation targets are:\n\n```js\n{ kind: \"artifactPath\", path: \"docs/service-handover.md\" }\n{ kind: \"artifactId\", id: \"artifact-example\" }\n{ kind: \"search\", query: \"service handover\" }\n```\n\nAuthoring rules:\n\n- Call navigation only from a real user event handler.\n- Always render the target reference as visible text where practical.\n- Treat host navigation as progressive enhancement, never as the only route to information.\n- On `not-found`, `denied`, `no-host` or timeout, show the visible reference or a local fallback instead of a blocking error dialog.\n- Prefer `search` when the exact artifact path is uncertain or likely to change.\n- Do not send requests automatically during load.\n- Do not create request loops or repeated retries.\n- Keep `requestId` opaque and at most 64 characters.\n- Keep search queries at most 200 characters.\n- Do not infer authorization or target existence beyond the returned status.\n\nArtifacts receive only `accepted`, `not-found` or `denied`. They must not expect content, user information, workspace metadata or resolved target details in the reply.\n\n## Accessibility requirements\n\n- Use semantic landmarks and controls.\n- Ensure complete keyboard operation.\n- Provide visible focus indicators.\n- Use table headers and captions for tabular content.\n- Do not communicate information through color alone.\n- Maintain sufficient contrast.\n- Respect `prefers-reduced-motion`.\n- Use ARIA only where native HTML does not provide the required semantics.\n- Ensure interactive controls have clear labels and state.\n- Navigation controls must expose a readable target or purpose independent of host availability.\n\n## Resilience and fallback\n\nThe initial HTML should contain meaningful structure and content before JavaScript enhancement where practical.\n\nA script failure should not produce an empty page. Prefer progressive enhancement and provide a controlled in-artifact error state for essential initialization failures.\n\nHost-integrated navigation is optional. A missing handshake, negative result or timeout must not make the artifact unusable.\n\n## Performance and size\n\nInteractive artifacts may be larger than Markdown or static HTML because libraries, fonts and images are embedded.\n\nAuthors must:\n\n- minimize and compress embedded code;\n- subset fonts;\n- avoid duplicate data and assets;\n- remove source maps and development bundles;\n- stay below the centrally configured artifact-size limit;\n- test loading and interaction on typical workspace devices.\n\nThe configured limit is authoritative. Oversized artifacts are treated fail-closed: their content is not persisted, truncated, or served for execution. A candidate rejected with controlled reason `too_large` is omitted from the new Artifact descriptors, Navigation and Search documents; no placeholder artifact is created. Controlled diagnostics appear in Index Job/report evidence so source owners can reduce the file, split the report, or adjust include patterns before rerunning the index job. Other unsafe loading or integrity failures remain fatal and preserve the previous successful projection.\n\n## Security review checklist\n\nBefore enabling or updating an interactive artifact, verify:\n\n1. The artifact is stored in a source explicitly configured as `interactive`.\n2. No external URLs are required for normal operation.\n3. No credentials or confidential runtime values are embedded.\n4. No parent DOM, router, index or workspace-data access is attempted.\n5. Any `postMessage` use conforms exactly to the `orivelaiq.artifact.v1` navigation contract.\n6. No browser storage is required.\n7. No forms, popups or direct top-level navigation are required.\n8. The artifact remains useful when network access is unavailable.\n9. The artifact remains useful when no host handshake is received.\n10. Navigation requests originate only from user event handlers and have visible fallback references.\n11. Keyboard and screen-reader behavior has been checked.\n12. Embedded third-party code and fonts have acceptable licenses.\n13. File size remains within the configured budget.\n\n## Repository governance\n\nInteractive HTML is code and must be reviewed accordingly.\n\nRecommended repository controls:\n\n- pull-request review;\n- protected branches;\n- explicit ownership for generated artifacts and generators;\n- reproducible generation where possible;\n- dependency/version records for embedded libraries;\n- validation against external references and prohibited patterns;\n- tests for standalone degradation and mediated navigation where used;\n- documented rollback to the previous artifact or to source policy `static`.\n\nAI-generated HTML is subject to the same review and trust requirements as manually authored HTML.\n\n## Requesting mediated viewer navigation\n\nInteractive artifacts may progressively enhance visible links or buttons by waiting for the host handshake and then sending `window.parent.postMessage()` messages using protocol `orivelaiq.artifact.v1`. Send requests only from real click/keyboard handlers and keep a standalone fallback when no `host-ready` message arrives.\n\n```js\nlet orivelaReady = false;\nwindow.addEventListener('message', (event) => {\n  if (window.parent === window || event.source !== window.parent) return;\n  const data = event.data;\n  if (data && data.protocol === 'orivelaiq.artifact.v1' && data.type === 'host-ready' && Array.isArray(data.capabilities) && data.capabilities.includes('navigate')) {\n    orivelaReady = true;\n  }\n});\n\ndocument.querySelector('[data-open-overview]')?.addEventListener('click', () => {\n  if (!orivelaReady) return;\n  window.parent.postMessage({\n    protocol: 'orivelaiq.artifact.v1',\n    type: 'navigate',\n    requestId: crypto.randomUUID().slice(0, 64),\n    userActivated: true,\n    target: { kind: 'artifactPath', path: 'docs/service-handover.md' }\n  }, '*');\n});\n```\n\nThe artifact does not receive index access, workspace data, user data, credentials, resolved paths, search results or detailed error reasons. Result statuses are only `accepted`, `not-found` and `denied`. Do not loop automatically on failures or timeouts. The parent DOM, router, top-level navigation, forms, popups and external network calls remain unavailable.\n\n## Source activation for authors\n\nAuthors cannot enable interactive execution from an artifact file. Interactive HTML is a source-level Admin opt-in. The source must include HTML artifacts through its configured include/exclude rules, an administrator must select `Interactive HTML`, and escalation from `static` requires a save-time confirmation. The confirmation is not an approval of artifact contents; it only activates isolated script execution for HTML artifacts indexed from that source.\n\nKeep authored HTML self-contained and portable. Do not rely on external network calls, Same-Origin access, forms, popups, downloads, top-level navigation or OrivelaIQ APIs. If a source is downgraded to `static`, scripts are disabled after the affected artifacts are represented in a refreshed index and viewer sessions reload that index.\n"}]}