@oharness/server 0.1.0

package/dist/analytics.d.ts

@@ -0,0 +1,47 @@
+export interface AnalyticsState {
+    /** True only when this build carries a vendor and the user has opted in. */
+    enabled: boolean;
+    /**
+     * Whether this build carries either vendor at all — the difference between
+     * "off" and "absent". One switch covers both: a person consenting to usage
+     * analytics is not being asked to arbitrate between two vendors they did not
+     * choose, and a build that carries only one is the normal case.
+     */
+    available: boolean;
+    /** PostHog, present only when enabled and this build carries a key. */
+    key?: string;
+    host?: string;
+    options?: Record<string, unknown>;
+    /** DataFast, present only when enabled and this build carries an id. */
+    datafast?: {
+        id: string;
+        domain: string;
+        src: string;
+    };
+}
+/**
+ * What `GET /analytics` answers.
+ *
+ * `available` is reported separately so Settings can say "this build carries
+ * no analytics" rather than showing a switch that would do nothing — a control
+ * that silently does nothing is worse than no control.
+ */
+export declare function analyticsState(): Promise<AnalyticsState>;
+/**
+ * The queue, for the document head.
+ *
+ * Boot fires events before anything could have decided whether to send them,
+ * so they wait here. Nothing in this stub touches the network: it exists only
+ * so that `track()` reads the same whether analytics end up on or off, and so
+ * that no caller has to remember which branch it is writing in.
+ */
+export declare const ANALYTICS_STUB = "<script>\nwindow.__ANALYTICS_QUEUE = [];\nwindow.__TRACK = function (event, props) {\n  // Bounded: a queue nothing will ever drain is a leak in a page left open all\n  // day, and the events worth having are the early ones anyway.\n  if (window.__ANALYTICS_QUEUE.length < 100) window.__ANALYTICS_QUEUE.push([event, props]);\n};\n</script>";
+/**
+ * The loader, appended to the client script where the token already exists.
+ *
+ * One request to `/analytics` answers for both vendors, and one consent
+ * decides both — so a person who has not opted in has neither vendor's key in
+ * their page source, which is the property that made the key server-served in
+ * the first place.
+ */
+export declare const ANALYTICS_CLIENT: string;

package/dist/analytics.js

@@ -0,0 +1,323 @@
+import { readPrefs } from "./prefs.js";
+/**
+ * Usage analytics for the browser frontend. Off until the person using it says
+ * otherwise, and absent entirely from a build nobody published.
+ *
+ * This is not the website. The page this feeds runs on the user's own machine,
+ * in front of an agent that has a shell there, and its address carries the
+ * token that grants that shell. So it is gated twice, and the two gates answer
+ * different questions:
+ *
+ *   A key, which only an official build carries. It is injected at packaging
+ *   time and is not in this repository — deliberately, because a default
+ *   compiled into the source would mean every fork and every self-hosted
+ *   install reporting into the publisher's dashboard. Someone who builds this
+ *   themselves gets a build that cannot report anywhere, and gets it without
+ *   having to configure anything.
+ *
+ *   Consent, which only the user grants. Stored in prefs, absent by default,
+ *   and revocable from Settings.
+ *
+ * Neither implies the other, and the page loads nothing until both are true —
+ * which is why the key is served from `/analytics` rather than inlined into
+ * the HTML. A user who never opts in never has it in their page source at all.
+ *
+ * What it sends: named events for actions taken — a panel opened, a prompt
+ * submitted, a permission answered, a model switched — and nothing about their
+ * content. No prompts, no file paths, no diffs, no transcript. Autocapture is
+ * off, so a click is never recorded by the text on the button; session replay
+ * is off; and URL properties are stripped, because the URL is where the token
+ * is. See `track()` in page.ts for the calls themselves.
+ */
+/**
+ * The published build's key, or nothing.
+ *
+ * Read from the environment so that the desktop shell can set it from the file
+ * packaging injects, and so that `oharness-web` run from a checkout can be
+ * pointed at a project of its own for a day without editing anything.
+ */
+const KEY = process.env["OHARNESS_POSTHOG_KEY"] ?? "";
+/** US cloud unless told otherwise. EU is https://eu.i.posthog.com. */
+const HOST = process.env["OHARNESS_POSTHOG_HOST"] ?? "https://us.i.posthog.com";
+/**
+ * DataFast, alongside PostHog and under the same two gates.
+ *
+ * The site runs both for the reason written in the website's own
+ * `lib/analytics.ts`: PostHog answers product questions, DataFast answers "how
+ * many, from where" without anyone learning a query language. Here it answers
+ * one question PostHog also answers — how many launches, from which country —
+ * and it is here so that the desktop app and the site show up on the same
+ * dashboard rather than in two places that have to be added up by hand.
+ *
+ * Both shells, and gated on the one thing that actually matters: whether this
+ * page's address carries the token.
+ *
+ * DataFast's script reads `window.location.href` unconditionally and has no
+ * hook to filter what it sends — its entire configuration surface is six
+ * `data-*` attributes, none of which redacts anything. PostHog has
+ * `property_denylist` and `before_send`; DataFast has nothing, so the URL has
+ * to be clean before the script is allowed to exist.
+ *
+ * Today that means the desktop shell and not `oharness-web`, which is where
+ * this landed anyway — but by measuring the thing itself rather than by asking
+ * which shell it is. `IS_DESKTOP` would be a proxy for the real question and
+ * would silently become wrong the day a third shell appears, or the day the
+ * desktop window is handed a URL with a query string on it.
+ *
+ * Taking the token out of the browser's address bar was tried and does not
+ * work: the document request on a reload is the one the page cannot influence,
+ * so a scrubbed URL means F5 returns 401. The desktop shell gets around that
+ * with `onBeforeSendHeaders`; a browser tab has no equivalent. Anyone
+ * revisiting this should read that as the constraint it is — browser-mode
+ * DataFast needs the credential to stop travelling in the URL, and that is an
+ * authentication change, not an analytics one.
+ */
+const DATAFAST_ID = process.env["OHARNESS_DATAFAST_ID"] ?? "";
+/**
+ * The site this files under. `oharness.ai`, not the page's own hostname —
+ * the page's hostname is `127.0.0.1`, which is nobody's site.
+ */
+const DATAFAST_DOMAIN = process.env["OHARNESS_DATAFAST_DOMAIN"] ?? "oharness.ai";
+/** Served from DataFast's own origin. There is nothing here to proxy it through. */
+const DATAFAST_SRC = "https://datafa.st/js/script.js";
+/**
+ * Every property PostHog would otherwise attach that carries the address of
+ * this page.
+ *
+ * The address is `http://127.0.0.1:<port>/?token=<uuid>`, and that token is
+ * the whole of the server's authentication. It must not travel, and "the
+ * analytics vendor is trustworthy" is not the argument to rely on — a property
+ * that is never collected cannot be leaked by anyone's later mistake.
+ *
+ * The `$session_entry_` family is easy to miss and was: it is filled in once
+ * when a session starts and then rides along on every event afterwards, so
+ * denying `$current_url` alone still sent the URL — with the token in it — on
+ * all of them. Anything added to this list wants checking against a real
+ * payload rather than against the documentation.
+ */
+const URL_PROPERTIES = [
+    "$current_url",
+    "$pathname",
+    "$host",
+    "$referrer",
+    "$referring_domain",
+    "$initial_current_url",
+    "$initial_pathname",
+    "$initial_host",
+    "$initial_referrer",
+    "$initial_referring_domain",
+    "$session_entry_url",
+    "$session_entry_host",
+    "$session_entry_pathname",
+    "$session_entry_referrer",
+    "$session_entry_referring_domain",
+];
+const OPTIONS = {
+    api_host: HOST,
+    // Autocapture records clicks by the element they landed on, including the
+    // text of the button. In this page that text is session titles, file names
+    // and model ids the user typed. Named events only.
+    autocapture: false,
+    capture_pageview: false,
+    capture_pageleave: false,
+    rageclick: false,
+    disable_session_recording: true,
+    disable_surveys: true,
+    // Nothing here reads a flag or shows a survey, so PostHog never needs to
+    // fetch a second script — and with this set it cannot. A page that can be
+    // reached with the token is not a page to leave an open script channel in.
+    disable_external_dependency_loading: true,
+    advanced_disable_feature_flags: true,
+    // Counting installs, not people: no profile is created, and the identifier
+    // is a random id in this browser's local storage that is never joined to
+    // anything. Nothing in the app calls `identify`.
+    person_profiles: "never",
+    persistence: "localStorage",
+    property_denylist: URL_PROPERTIES,
+    // Someone who has asked their browser not to be tracked has answered this
+    // question already.
+    respect_dnt: true,
+};
+/**
+ * What `GET /analytics` answers.
+ *
+ * `available` is reported separately so Settings can say "this build carries
+ * no analytics" rather than showing a switch that would do nothing — a control
+ * that silently does nothing is worse than no control.
+ */
+export async function analyticsState() {
+    const available = KEY !== "" || DATAFAST_ID !== "";
+    const consented = (await readPrefs()).analytics === true;
+    if (!available || !consented)
+        return { enabled: false, available };
+    // Each vendor is reported only if this build carries it. A build with one
+    // and not the other is not a broken build — it is what a fork gets, and what
+    // an official build gets if only one id made it into the packaging step.
+    const state = { enabled: true, available };
+    if (KEY !== "") {
+        state.key = KEY;
+        state.host = HOST;
+        state.options = OPTIONS;
+    }
+    if (DATAFAST_ID !== "") {
+        state.datafast = { id: DATAFAST_ID, domain: DATAFAST_DOMAIN, src: DATAFAST_SRC };
+    }
+    return state;
+}
+/**
+ * The queue, for the document head.
+ *
+ * Boot fires events before anything could have decided whether to send them,
+ * so they wait here. Nothing in this stub touches the network: it exists only
+ * so that `track()` reads the same whether analytics end up on or off, and so
+ * that no caller has to remember which branch it is writing in.
+ */
+export const ANALYTICS_STUB = `<script>
+window.__ANALYTICS_QUEUE = [];
+window.__TRACK = function (event, props) {
+  // Bounded: a queue nothing will ever drain is a leak in a page left open all
+  // day, and the events worth having are the early ones anyway.
+  if (window.__ANALYTICS_QUEUE.length < 100) window.__ANALYTICS_QUEUE.push([event, props]);
+};
+</script>`;
+/**
+ * What a build carrying neither vendor ships instead of the loader.
+ *
+ * Not the loader with a disabled flag: a page that cannot report anywhere
+ * should not carry the code for reporting, and `PAGE` should not so much as
+ * contain either vendor's name. The suite asserts exactly that, which is how a
+ * later change that quietly starts shipping the loader to everyone gets
+ * caught. It still drains the queue, because `track()` calls are unconditional
+ * and a queue nobody empties grows all day.
+ */
+const NO_ANALYTICS_CLIENT = String.raw `
+function startAnalytics() {
+  window.__TRACK = function () {};
+  window.__ANALYTICS_QUEUE = [];
+}
+`;
+/**
+ * The DataFast tag, or a no-op where this build carries no id.
+ *
+ * Two conditions, and the second is the load-bearing one. `config.datafast`
+ * says this build carries an id and the user has consented; the `href` check
+ * says this page's address has no token in it. See the comment on
+ * `DATAFAST_ID` for why the second cannot be relaxed — the script reads
+ * `location.href` and offers nothing to filter it with.
+ *
+ * Checked against the live `href` rather than against which shell this is, so
+ * that a regression in the token scrub turns this off rather than turning it
+ * into a leak. It is the last gate before a third party sees the address, and
+ * the only one that cannot be wrong about what the address contains.
+ *
+ * `data-allow-localhost` because the page is served from 127.0.0.1 and the
+ * script drops every event from a loopback host unless told not to. That flag
+ * is the only reason this reports at all, and it is also the reason the check
+ * above has to hold.
+ */
+const DATAFAST_CLIENT = DATAFAST_ID === "" ? String.raw `
+function startDataFast() {}
+` : String.raw `
+function startDataFast(config) {
+  if (!config.datafast) return;
+  if (location.href.indexOf("token=") !== -1) return;
+  try {
+    const script = document.createElement("script");
+    script.src = config.datafast.src;
+    script.defer = true;
+    script.setAttribute("data-website-id", config.datafast.id);
+    script.setAttribute("data-domain", config.datafast.domain);
+    script.setAttribute("data-allow-localhost", "true");
+    document.head.appendChild(script);
+  } catch (err) {
+    // Analytics that fail must never be something a person notices while
+    // trying to work. There is nothing to retry and nothing to report.
+  }
+}
+`;
+/**
+ * PostHog, or a no-op where this build carries no key.
+ *
+ * `array.js` loaded on its own rather than PostHog's inlined snippet: the
+ * snippet is a minified blob whose job is to queue calls made before the
+ * library arrives, and this does that job in code that can be read — which is
+ * the bar for anything that runs in this page.
+ *
+ * This is the half that drains the queue in every branch, because `track()` is
+ * PostHog's alone — DataFast counts launches and has no named events to send.
+ *
+ * A failure at any point is silence. Analytics that cannot reach their server
+ * must never be something a person notices while trying to work.
+ */
+const POSTHOG_CLIENT = KEY === "" ? String.raw `
+function startPostHog() {
+  window.__TRACK = function () {};
+  window.__ANALYTICS_QUEUE = [];
+}
+` : String.raw `
+function startPostHog(config) {
+  if (!config.key) {
+    window.__TRACK = function () {};
+    window.__ANALYTICS_QUEUE = [];
+    return;
+  }
+
+  const script = document.createElement("script");
+  script.src = config.host + "/static/array.js";
+  script.async = true;
+  script.onload = function () {
+    try {
+      window.posthog.init(config.key, Object.assign({}, config.options, {
+        // The denylist names the properties known to carry this page's address
+        // today. This catches the ones a future version of the library adds:
+        // whatever the property is called, if its value contains the token
+        // then it is the URL, and it does not leave.
+        before_send: function (event) {
+          const props = event && event.properties;
+          for (const key in props) {
+            if (typeof props[key] === "string" && props[key].indexOf("token=") !== -1) {
+              delete props[key];
+            }
+          }
+          return event;
+        },
+      }));
+      window.__TRACK = function (event, props) { window.posthog.capture(event, props); };
+      for (const queued of window.__ANALYTICS_QUEUE) window.__TRACK(queued[0], queued[1]);
+    } catch (err) {
+      window.__TRACK = function () {};
+    }
+    window.__ANALYTICS_QUEUE = [];
+  };
+  script.onerror = function () {
+    window.__TRACK = function () {};
+    window.__ANALYTICS_QUEUE = [];
+  };
+  document.head.appendChild(script);
+}
+`;
+/**
+ * The loader, appended to the client script where the token already exists.
+ *
+ * One request to `/analytics` answers for both vendors, and one consent
+ * decides both — so a person who has not opted in has neither vendor's key in
+ * their page source, which is the property that made the key server-served in
+ * the first place.
+ */
+export const ANALYTICS_CLIENT = KEY === "" && DATAFAST_ID === "" ? NO_ANALYTICS_CLIENT : String.raw `
+${DATAFAST_CLIENT}
+${POSTHOG_CLIENT}
+async function startAnalytics() {
+  const config = await getJson("/analytics");
+  if (!config || config.error || !config.enabled) {
+    // Off, or this build carries nothing. Drop the queue rather than hold it:
+    // the answer will not change without a reload.
+    window.__TRACK = function () {};
+    window.__ANALYTICS_QUEUE = [];
+    return;
+  }
+  startDataFast(config);
+  startPostHog(config);
+}
+`;
+//# sourceMappingURL=analytics.js.map

package/dist/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"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"}

package/dist/artifacts.d.ts

@@ -0,0 +1,53 @@
+import type { ServerResponse } from "node:http";
+import type { Artifact, ArtifactVersion } from "@oharness/engine/artifacts/store.ts";
+/**
+ * Serving an artifact's body to a browser that is going to execute it.
+ *
+ * The rest of this server renders untrusted text by building DOM nodes, never
+ * by handing markup to the browser — see markdown.ts, where that is the whole
+ * design. An HTML artifact is the one case that cannot work that way: its
+ * value *is* the browser executing it. So instead of loosening the renderer,
+ * this puts the execution somewhere it can do no harm, and the isolation is
+ * built from three independent layers because any one of them alone has a
+ * known hole:
+ *
+ *   1. `sandbox="allow-scripts"` on the iframe, without `allow-same-origin`.
+ *      Those two together are famously equivalent to no sandbox at all, since
+ *      the frame can then reach up and remove its own sandbox attribute.
+ *      Without it the document gets an opaque origin and cannot touch the
+ *      page, its storage, or its cookies.
+ *   2. The CSP below, delivered as a header. `connect-src 'none'` is the load
+ *      bearing one — an opaque origin still stops nothing from *sending* a
+ *      request, and this server is a loopback endpoint that drives an agent
+ *      which runs shell commands. A `fetch(..., {mode:'no-cors'})` reads
+ *      nothing but arrives all the same.
+ *   3. A separate credential (see `artifactToken` in server.ts). The frame can
+ *      read its own URL, so whatever authorises this route is readable by the
+ *      content it serves. Making that a different secret from the session
+ *      token means the worst case is an artifact being readable, not an agent
+ *      being drivable.
+ */
+declare const CSP: string;
+/**
+ * The document an iframe loads.
+ *
+ * `page` artifacts are served as they were written — the model authored a
+ * complete document and wrapping it would break any `<!doctype>` or `<head>`
+ * it set up. Everything else is wrapped in a minimal shell, because a bare
+ * SVG or a bare text file rendered as a top-level document inherits the
+ * browser's defaults and looks broken next to the rest of the UI.
+ */
+export declare function artifactDocument(artifact: Artifact, revision: ArtifactVersion): {
+    body: string;
+    contentType: string;
+};
+export declare function sendArtifact(res: ServerResponse, artifact: Artifact, revision: ArtifactVersion): void;
+/**
+ * Escaping for the wrapper above.
+ *
+ * Only ever applied to the non-executable kinds. The `page` kind is
+ * deliberately *not* escaped — escaping it would defeat its purpose — which is
+ * exactly why that kind is the one the sandbox and the CSP exist for.
+ */
+export declare function escapeHtml(text: string): string;
+export { CSP as ARTIFACT_CSP };

package/dist/artifacts.js

@@ -0,0 +1,129 @@
+import { isCanvas } from "@oharness/engine/artifacts/store.ts";
+import { canvasDocument } from "./canvas.js";
+/**
+ * Serving an artifact's body to a browser that is going to execute it.
+ *
+ * The rest of this server renders untrusted text by building DOM nodes, never
+ * by handing markup to the browser — see markdown.ts, where that is the whole
+ * design. An HTML artifact is the one case that cannot work that way: its
+ * value *is* the browser executing it. So instead of loosening the renderer,
+ * this puts the execution somewhere it can do no harm, and the isolation is
+ * built from three independent layers because any one of them alone has a
+ * known hole:
+ *
+ *   1. `sandbox="allow-scripts"` on the iframe, without `allow-same-origin`.
+ *      Those two together are famously equivalent to no sandbox at all, since
+ *      the frame can then reach up and remove its own sandbox attribute.
+ *      Without it the document gets an opaque origin and cannot touch the
+ *      page, its storage, or its cookies.
+ *   2. The CSP below, delivered as a header. `connect-src 'none'` is the load
+ *      bearing one — an opaque origin still stops nothing from *sending* a
+ *      request, and this server is a loopback endpoint that drives an agent
+ *      which runs shell commands. A `fetch(..., {mode:'no-cors'})` reads
+ *      nothing but arrives all the same.
+ *   3. A separate credential (see `artifactToken` in server.ts). The frame can
+ *      read its own URL, so whatever authorises this route is readable by the
+ *      content it serves. Making that a different secret from the session
+ *      token means the worst case is an artifact being readable, not an agent
+ *      being drivable.
+ */
+const CSP = [
+    // Nothing loads unless a directive below says otherwise.
+    "default-src 'none'",
+    // Inline only: an artifact is one self-contained document by construction,
+    // and allowing an origin here would be allowing exfiltration through it.
+    "script-src 'unsafe-inline'",
+    "style-src 'unsafe-inline'",
+    // Data URIs only. A remote image URL is a GET with an attacker-chosen path,
+    // which is all exfiltration needs.
+    "img-src data:",
+    "font-src data:",
+    // The three egress channels that are not covered by the source directives.
+    "connect-src 'none'",
+    "form-action 'none'",
+    "base-uri 'none'",
+    // An artifact has no business nesting frames of its own, and a frame it
+    // controls is a place to render something that looks like the app.
+    "frame-src 'none'",
+    "child-src 'none'",
+    // Only this server's own page may frame an artifact.
+    "frame-ancestors 'self'",
+].join("; ");
+/** Headers for any artifact body, whether it executes or not. */
+function isolationHeaders(contentType) {
+    return {
+        "content-type": contentType,
+        "content-security-policy": CSP,
+        // Belt and braces for browsers that honour the older header, and for the
+        // case where a proxy strips CSP.
+        "x-content-type-options": "nosniff",
+        "referrer-policy": "no-referrer",
+        // This body is a session scratch surface; caching it would outlive both
+        // the session and the credential that authorised reading it.
+        "cache-control": "no-store",
+    };
+}
+/**
+ * The document an iframe loads.
+ *
+ * `page` artifacts are served as they were written — the model authored a
+ * complete document and wrapping it would break any `<!doctype>` or `<head>`
+ * it set up. Everything else is wrapped in a minimal shell, because a bare
+ * SVG or a bare text file rendered as a top-level document inherits the
+ * browser's defaults and looks broken next to the rest of the UI.
+ */
+export function artifactDocument(artifact, revision) {
+    // Checked before `page`, which a canvas also is: the difference is that the
+    // stored content is a fragment of artboards, not a document, and serving it
+    // as one would render unstyled boxes with no editor and no explanation.
+    if (isCanvas(artifact.mime)) {
+        return { body: canvasDocument(artifact, revision), contentType: "text/html; charset=utf-8" };
+    }
+    if (artifact.kind === "page") {
+        return { body: revision.content, contentType: "text/html; charset=utf-8" };
+    }
+    if (artifact.kind === "vector") {
+        // Served as its own content type rather than embedded in HTML: an SVG
+        // document scales to the frame on its own, and embedding it would mean
+        // deciding on a size here that the artifact panel is better placed to pick.
+        return { body: revision.content, contentType: "image/svg+xml; charset=utf-8" };
+    }
+    // text, markdown, code, image — shown as source in a readable shell. The
+    // panel renders these itself in the common case; this route exists so
+    // "open in a new tab" works for every kind, not just the executable ones.
+    return {
+        body: [
+            "<!doctype html><meta charset=utf-8>",
+            `<title>${escapeHtml(artifact.title)}</title>`,
+            "<style>",
+            "html{color-scheme:light dark}",
+            "body{margin:0;padding:16px;font:13px/1.6 ui-monospace,SFMono-Regular,Menlo,monospace;",
+            "white-space:pre-wrap;word-break:break-word}",
+            "</style>",
+            `<body>${escapeHtml(revision.content)}</body>`,
+        ].join(""),
+        contentType: "text/html; charset=utf-8",
+    };
+}
+export function sendArtifact(res, artifact, revision) {
+    const { body, contentType } = artifactDocument(artifact, revision);
+    res.writeHead(200, isolationHeaders(contentType));
+    res.end(body);
+}
+/**
+ * Escaping for the wrapper above.
+ *
+ * Only ever applied to the non-executable kinds. The `page` kind is
+ * deliberately *not* escaped — escaping it would defeat its purpose — which is
+ * exactly why that kind is the one the sandbox and the CSP exist for.
+ */
+export function escapeHtml(text) {
+    return text
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+export { CSP as ARTIFACT_CSP };
+//# sourceMappingURL=artifacts.js.map

package/dist/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"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"}

package/dist/canvas.d.ts

@@ -0,0 +1,28 @@
+import type { Artifact, ArtifactVersion } from "@oharness/engine/artifacts/store.ts";
+/**
+ * The document a canvas artifact is served as.
+ *
+ * This is the half of a canvas the model does not write. It authors artboards;
+ * everything that makes them a canvas — the pan/zoom stage, selection, the
+ * properties panel, undo, and the save protocol — is authored here, once.
+ *
+ * That split is the whole reason a canvas is worth a mime of its own rather
+ * than being "a `page` the model happened to put an editor in":
+ *
+ *   - Size. An editor written into every artifact would be tens of kilobytes
+ *     of model output on every revision, re-derived and subtly different each
+ *     time, and counted against MAX_ARTIFACT_BYTES.
+ *   - Round-tripping. Saving means reading the artboards back out of the DOM.
+ *     That only works if something knows exactly which markup it put in, which
+ *     a model improvising an editor per artifact cannot promise.
+ *   - Trust. The save path writes a new revision of a stored artifact. What
+ *     decides the bytes that get sent should not itself be model output.
+ *
+ * The document stays inside the same CSP as any other artifact: everything
+ * here is inline, nothing is fetched, and the only channel out is postMessage
+ * to the parent frame — which no CSP directive covers, and which carries no
+ * credential. A canvas opened with no parent that speaks the protocol (a new
+ * tab, a published copy) settles into a read-only board rather than showing a
+ * Save button that silently does nothing.
+ */
+export declare function canvasDocument(artifact: Artifact, revision: ArtifactVersion): string;