@zackbart/connecta 0.26.0 → 0.26.2

package/CHANGELOG.md

@@ -4,6 +4,147 @@ All notable changes to this package are documented here.
 
 ## Unreleased
 
+## 0.26.2 — 2026-09-27
+
+This patch restores named client tokens as an optional auth module. Deployments
+upgrading from v0.23 can keep their existing stored records and client secrets,
+without rotation, by configuring `accessTokens(storage)` with the same storage
+namespace and preserving their identity grants. The old boolean configuration
+must be replaced. Deployments that omit the module are unchanged. The eight MCP
+tools remain unchanged, and the Node template now pins 0.26.2.
+
+### Added
+
+- `@zackbart/connecta/auth/access-tokens` verifies v0.23 `cta_…` tokens and
+  restores create, show-once, list, rename, and revoke in the operator UI.
+  `identity.accessTokenManagement` explicitly permits interactive operators;
+  client tokens cannot administer tokens or connection credentials. New issuance
+  requires atomic storage and reserves capacity across concurrent instances.
+
+### Fixed
+
+- Existing token ids, activity labels, and principal bindings survive the upgrade.
+  Malformed or corrupt records fail closed, including principal fields that
+  JavaScript regular expressions previously coerced into strings. Revocation
+  deletes the admission lookup before updating metadata.
+
+
+## 0.26.1 — 2026-09-26
+
+This patch fixes slow OAuth restarts, unbounded downstream authorization waits,
+and operator pages that signed people out after a temporary load failure.
+Connect now opens consent in one click, and browser-facing pages share the
+configured theme. Agent guidance preserves one-time write results and keeps
+an authorized batch in one resumable program. Approval defaults and the eight
+MCP tools are unchanged. No configuration or storage migration is required;
+deployments without the operator UI can ignore the page changes. OAuth starts
+abort downstream work after 30 seconds, but uncancellable storage resets and
+cleanup must finish before the response. Restart reuses a matching client
+registration; a revoked client may still fail at consent or callback and need
+another restart. The Node template now pins 0.26.1.
+
+### Added
+
+- **Continue or restart an operator OAuth start.** `POST /ui/oauth/<id>`
+  takes `?mode=continue` or `?mode=restart`. `restart`, still the default
+  when `mode` is absent, creates a new epoch and clears the grant and
+  discovery while retaining a matching issuer-bound client registration. `continue` hands back the pending
+  authorization URL when it was written in the last ten minutes. Otherwise it
+  starts a flow in the current epoch, reusing a stored registration when one
+  exists. A first connection still registers dynamically. A disconnected
+  connector resets first. A response with a URL now carries `reused`. A continue that reused a
+  URL or found the connection healthy leaves the cached catalog alone. Any
+  other `mode` is a 400. After a `publicUrl` change, continue keeps a client
+  registered for the old callback, which the authorization server refuses;
+  restart recovers. `ConnectorStatus` gains the optional
+  `authorizationReused`, set by `remoteMcp()`'s `startAuth`.
+
+### Changed
+
+- **Pending authorization URLs expire for reuse.** A non-forced `startAuth`,
+  including `authorize_connector` without `force`, reissues a pending URL only
+  when it is under ten minutes old. The pending URL's envelope now records its
+  write time, which older readers ignore. A URL written before this release,
+  or under a pre-epoch generation, starts a fresh flow instead.
+- **OAuth cleanup deletes run concurrently.** A restart's epoch cleanup,
+  `clearPending`, and `invalidateCredentials("all")` keep up to six deletes
+  in flight, the Workers limit on simultaneous connections. Every delete is
+  still attempted, and a falsy rejection now counts as a failure. A retired
+  epoch's manifest is still removed only after all of its values. Catalog
+  invalidation deletes the root and its chunks together under the registry's
+  chunk I/O bound, so a failed root delete no longer skips the chunks.
+
+- Every page connecta renders for a person now shares one token layer and one
+  layout: the operator shell, the OAuth callback, a browser's 404, and the
+  artifact frame follow `branding.theme` and light or dark. The OAuth callback
+  names the outcome in its heading with a status mark, names the connector by
+  title only after the state check, uses `branding.productName` in its copy,
+  and folds the agent fix prompt under "Details for the operator". Refusals
+  stay byte-identical across connectors and paths.
+- A request whose `Accept` names `text/html` gets a themed 404 page; every
+  other client keeps the plain `Not Found` body.
+- Markdown artifacts take the deployment's resolved scheme and tokens instead
+  of the OS palette, and drop an opening `# Heading` that only repeats the
+  title the viewer already shows. The frame waits on the viewer's surface with
+  a loading line, and says so if the page never arrives.
+- Without the operator UI, callback and 404 pages no longer link the default
+  `/favicon.svg`, which only the UI serves.
+- The operator UI starts OAuth in one click. Connect opens the provider's
+  page in a new tab straight away and asks the server to continue a pending
+  authorization rather than restart it; only Reconnect on a healthy
+  connection restarts, behind an in-page confirm. A tab returning to the page
+  quietly re-reads the status of connectors waiting on authorization.
+- Operator UI notices appear in the card that caused them, in fixed
+  sentences rather than the route's error text; problems fixed by authorizing
+  or adding a credential are warnings rather than errors, with one primary
+  action per row. Activity and artifact states, the confirm dialogs, the
+  mobile masthead, and the vocabulary shown to people (outcomes, actors,
+  timestamps) now read the same across pages and use `branding.productName`.
+
+### Fixed
+
+- Operator OAuth starts now abort downstream discovery and registration after
+  30 seconds or browser cancellation, with a fixed timeout response. Every
+  reset already started by the request, including issuer-mismatch recovery,
+  drains before catalog invalidation and response so a delayed generation
+  write cannot replace a later flow. These uncancellable storage waits can
+  exceed the deadline. Disconnect still finishes after browser cancellation.
+- Forced OAuth restarts reuse registrations bound to the issuer, redirect URI,
+  client metadata, connector settings, and owner partition. Credentials are
+  re-sealed for the replacement epoch, and fresh discovery detects issuer
+  changes. Disconnect and issuer-mismatch recovery discard the registration.
+  The SDK cannot detect a revoked client while constructing a consent URL;
+  a callback refusal clears it so the next restart can register again.
+- Agent sampling advice now applies to reads. For a one-time write, agents
+  reduce the full result in the program or page a direct-call result through
+  `get_result`, without repeating the write to recover discarded output.
+- Authorized batches stay in one resumable program. Guidance explains how
+  tool-scoped approval covers repeated calls to one address while other
+  approval-required writes retain their own approvals. The call-scoped
+  default and host enforcement are unchanged.
+- **A restart's cleanup no longer grows with every earlier restart.** Each
+  OAuth restart re-deleted every epoch the connector had ever retired, one key
+  at a time, and restart 1,001 failed forever with a full cleanup backlog. A
+  restart now deletes the epoch it retires, retries any of the eight most
+  recent epochs whose cleanup failed (their manifest outlives their values),
+  and sweeps at most 16 epochs retired more than 24 hours ago, dropping each
+  from the lineage only when all of its keys are gone. A Disconnect that
+  reported a failed cleanup still deletes the old grant when retried. The
+  cleanup work stays bounded independently of earlier resets. Residue a late
+  writer leaves in a younger epoch stays unreadable behind the fence until the
+  sweep reaches it. A late writer whose cleanup fails in an epoch already
+  listed now restarts that epoch's grace. The accepted assumption is that no
+  request holds a retired epoch for a day. The lineage records retirement
+  times in a sibling record older releases ignore, and its cap rises to 5,000
+  epochs. A connector stuck at the old 1,000 wall restarts the day it
+  upgrades. Rolling back is clean unless a lineage has grown past 1,000. See
+  [auth](./documentation/auth.md#starting-restarting-and-retiring-an-oauth-epoch).
+- A failed or unreachable `/ui/data` no longer signs the operator out. Only a
+  401 or 403 on that read returns to the token gate; anything else keeps the
+  page and offers Retry. A connector whose details fail to load says whether
+  the session, the browser's connection, or the downstream service is at
+  fault, and only the last offers the fix prompt.
+
 ## 0.26.0 — 2026-09-25
 
 Programs can now write with host approval. When a program reaches a tool that

package/README.md

@@ -132,3 +132,14 @@ breaks and what a deployment can ignore.
 Built for its author's deployments first and published openly. Breaking
 changes are expected before 1.0. See the [changelog](./CHANGELOG.md) and
 [security policy](./SECURITY.md).
+
+### Existing client tokens
+
+Upgrading from v0.23 does not require rotating managed `cta_…` tokens. Import
+`accessTokens` from `@zackbart/connecta/auth/access-tokens`, replace the old
+`accessTokens: true` with `accessTokens: accessTokens(storage)`, and keep the
+same persistent storage namespace and identity/tool/pool grant rules. Enable
+`identity.accessTokenManagement` only for the interactive operators who should
+manage tokens. New issuance needs storage with atomic `compareAndSet`; older
+storage adapters can still verify existing tokens. See the package's
+`documentation/auth.md` for the migration and storage requirements.

package/dist/access-tokens.d.ts

@@ -0,0 +1,38 @@
+import type { IdentityReference, InboundAuth, KVStorage } from "./types.js";
+import type { AccessTokensModule } from "./module-contracts.js";
+export interface AccessTokenMetadata {
+    id: string;
+    name: string;
+    tokenPrefix: string;
+    createdAt: string;
+    revokedAt?: string;
+}
+export interface CreatedAccessToken {
+    token: string;
+    accessToken: AccessTokenMetadata;
+}
+/**
+ * Deployment-scoped personal access tokens. Secret material is never
+ * recoverable: authentication indexes a SHA-256 digest of a random 256-bit
+ * token, while separately enumerable metadata powers operator management.
+ */
+export declare class AccessTokenManager {
+    private readonly storage;
+    readonly auth: InboundAuth;
+    private readonly maxActive;
+    constructor(storage: KVStorage, options?: {
+        maxActive?: number;
+    });
+    private read;
+    list(): Promise<AccessTokenMetadata[]>;
+    create(name: unknown, createdBy: string | IdentityReference): Promise<CreatedAccessToken>;
+    rename(id: string, name: unknown): Promise<AccessTokenMetadata | null>;
+    revoke(id: string, revokedBy: string): Promise<AccessTokenMetadata | null>;
+    private updateRecord;
+    private updateActive;
+    private authorize;
+}
+/** Opt in using the same storage namespace that held the v0.23 records. */
+export declare function accessTokens(storage: KVStorage, options?: {
+    maxActive?: number;
+}): AccessTokensModule;

package/dist/access-tokens.js

@@ -0,0 +1,294 @@
+import { routeAccessTokens } from "./routes/access-tokens.js";
+import { validIdentityReference } from "./identity.js";
+const TOKEN_PREFIX = "cta_";
+const TOKEN_BYTES = 32;
+const TOKEN_VALUE_RE = /^cta_[A-Za-z0-9_-]{43}$/;
+const RECORD_PREFIX = "access-token:v1:record:";
+const LOOKUP_PREFIX = "access-token:v1:lookup:";
+const MAX_NAME_CHARACTERS = 80;
+const DEFAULT_MAX_ACTIVE = 100;
+const MAX_CONFIGURED_ACTIVE = 1_000;
+const ACTIVE_KEY = "access-token:v1:active";
+const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+const encoder = new TextEncoder();
+function recordKey(id) {
+    return `${RECORD_PREFIX}${id}`;
+}
+function lookupKey(hash) {
+    return `${LOOKUP_PREFIX}${hash}`;
+}
+function bytesToBase64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary)
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/u, "");
+}
+function bytesToHex(bytes) {
+    return [...bytes]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+async function hashToken(token) {
+    return bytesToHex(new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(token))));
+}
+function normalizeName(value) {
+    if (typeof value !== "string") {
+        throw new Error("Token name must be a string");
+    }
+    const compact = value.replace(/\s+/gu, " ").trim();
+    if (!compact)
+        throw new Error("Token name cannot be empty");
+    if (Array.from(compact).length > MAX_NAME_CHARACTERS) {
+        throw new Error(`Token name cannot exceed ${MAX_NAME_CHARACTERS} characters`);
+    }
+    return compact;
+}
+function parseRecord(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (value.version !== 1 ||
+            typeof value.id !== "string" ||
+            !ID_RE.test(value.id) ||
+            typeof value.name !== "string" ||
+            !value.name.trim() ||
+            Array.from(value.name).length > MAX_NAME_CHARACTERS ||
+            typeof value.tokenHash !== "string" ||
+            !/^[0-9a-f]{64}$/u.test(value.tokenHash) ||
+            typeof value.tokenPrefix !== "string" ||
+            !/^cta_[A-Za-z0-9_-]{8}$/u.test(value.tokenPrefix) ||
+            typeof value.createdAt !== "string" ||
+            !Number.isFinite(Date.parse(value.createdAt)) ||
+            typeof value.createdBy !== "string" ||
+            (value.principal !== undefined &&
+                !validIdentityReference(value.principal)) ||
+            (value.revokedAt !== undefined &&
+                (typeof value.revokedAt !== "string" || !value.revokedAt || !Number.isFinite(Date.parse(value.revokedAt)))) ||
+            (value.revokedBy !== undefined &&
+                typeof value.revokedBy !== "string")) {
+            throw new Error("invalid token record");
+        }
+        return value;
+    }
+    catch {
+        throw new Error("Stored access token metadata is invalid or corrupted");
+    }
+}
+function parseLookup(raw) {
+    try {
+        const value = JSON.parse(raw);
+        return value.version === 1 && typeof value.id === "string" && ID_RE.test(value.id)
+            ? { version: 1, id: value.id }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function metadata(record) {
+    return {
+        id: record.id,
+        name: record.name,
+        tokenPrefix: record.tokenPrefix,
+        createdAt: record.createdAt,
+        ...(record.revokedAt ? { revokedAt: record.revokedAt } : {}),
+    };
+}
+function unauthorized() {
+    return {
+        ok: false,
+        response: new Response(JSON.stringify({ error: "unauthorized" }), {
+            status: 401,
+            headers: {
+                "Content-Type": "application/json",
+                "WWW-Authenticate": "Bearer",
+            },
+        }),
+    };
+}
+/**
+ * Deployment-scoped personal access tokens. Secret material is never
+ * recoverable: authentication indexes a SHA-256 digest of a random 256-bit
+ * token, while separately enumerable metadata powers operator management.
+ */
+export class AccessTokenManager {
+    storage;
+    auth;
+    maxActive;
+    constructor(storage, options = {}) {
+        this.storage = storage;
+        if (!storage.list) {
+            throw new Error("accessTokens requires a storage adapter that implements list(prefix)");
+        }
+        const maxActive = options.maxActive ?? DEFAULT_MAX_ACTIVE;
+        if (!Number.isInteger(maxActive) ||
+            maxActive < 1 ||
+            maxActive > MAX_CONFIGURED_ACTIVE) {
+            throw new Error(`accessTokens.maxActive must be a whole number from 1 to ${MAX_CONFIGURED_ACTIVE}`);
+        }
+        this.maxActive = maxActive;
+        this.auth = {
+            kind: "access_token",
+            activityActorNamespace: "connecta:access-tokens:v1",
+            activityActorLabel: async (id) => {
+                try {
+                    return (await this.read(id))?.name;
+                }
+                catch {
+                    return undefined;
+                }
+            },
+            authorize: (request) => this.authorize(request).catch(() => unauthorized()),
+        };
+    }
+    async read(id) {
+        if (!ID_RE.test(id))
+            return null;
+        const raw = await this.storage.get(recordKey(id));
+        const record = raw ? parseRecord(raw) : null;
+        if (record && record.id !== id)
+            throw new Error("Stored access token id mismatch");
+        return record;
+    }
+    async list() {
+        const keys = await this.storage.list(RECORD_PREFIX);
+        const records = await Promise.all(keys.map(async (key) => {
+            const raw = await this.storage.get(key);
+            return raw ? parseRecord(raw) : null;
+        }));
+        return records
+            .filter((record) => Boolean(record))
+            .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+            .map(metadata);
+    }
+    async create(name, createdBy) {
+        const normalizedName = normalizeName(name);
+        if (!this.storage.compareAndSet) {
+            throw new Error("Creating access tokens requires atomic compareAndSet storage");
+        }
+        if (typeof createdBy !== "string" && !validIdentityReference(createdBy)) {
+            throw new Error("Invalid token owner");
+        }
+        const secretBytes = crypto.getRandomValues(new Uint8Array(TOKEN_BYTES));
+        const token = TOKEN_PREFIX + bytesToBase64Url(secretBytes);
+        const hash = await hashToken(token);
+        if (await this.storage.get(lookupKey(hash))) {
+            throw new Error("Access token collision; create another token");
+        }
+        const record = {
+            version: 1,
+            id: crypto.randomUUID(),
+            name: normalizedName,
+            tokenHash: hash,
+            tokenPrefix: token.slice(0, 12),
+            createdAt: new Date().toISOString(),
+            createdBy: typeof createdBy === "string"
+                ? createdBy
+                : `${createdBy.namespace}:${createdBy.id}`,
+            ...(typeof createdBy === "string"
+                ? {}
+                : { principal: { ...createdBy } }),
+        };
+        await this.updateActive(record.id, true);
+        await this.storage.set(recordKey(record.id), JSON.stringify(record));
+        // A failed lookup write may have committed. Keep its reservation and
+        // metadata, so a manager can revoke it without ever returning the secret.
+        await this.storage.set(lookupKey(hash), JSON.stringify({ version: 1, id: record.id }));
+        return { token, accessToken: metadata(record) };
+    }
+    async rename(id, name) {
+        const normalized = normalizeName(name);
+        const record = await this.updateRecord(id, current => ({ ...current, name: normalized }));
+        return record ? metadata(record) : null;
+    }
+    async revoke(id, revokedBy) {
+        const record = await this.read(id);
+        if (!record)
+            return null;
+        // Remove admission first. A metadata failure cannot leave a successful
+        // revocation's lookup alive. Retry deletion even if already marked revoked.
+        await this.storage.delete(lookupKey(record.tokenHash));
+        const updated = await this.updateRecord(id, current => current.revokedAt ? current : {
+            ...current, revokedAt: new Date().toISOString(), revokedBy,
+        });
+        if (this.storage.compareAndSet)
+            await this.updateActive(id, false);
+        return updated ? metadata(updated) : null;
+    }
+    async updateRecord(id, update) {
+        if (!ID_RE.test(id))
+            return null;
+        for (let attempt = 0; attempt < 32; attempt++) {
+            const raw = await this.storage.get(recordKey(id));
+            if (!raw)
+                return null;
+            const record = parseRecord(raw);
+            if (record.id !== id)
+                throw new Error("Stored access token id mismatch");
+            const next = update(record);
+            if (this.storage.compareAndSet) {
+                // A rename racing revocation must retain revokedAt, including when
+                // an in-flight create has not yet published its lookup.
+                if (!await this.storage.compareAndSet(recordKey(id), raw, JSON.stringify(next)))
+                    continue;
+            }
+            else {
+                // Legacy adapters cannot create, so no late lookup writer exists.
+                // Revocation's deleted lookup still refuses a stale metadata write.
+                await this.storage.set(recordKey(id), JSON.stringify(next));
+            }
+            return next;
+        }
+        throw new Error("Access token metadata is busy; retry the operation");
+    }
+    async updateActive(id, adding) {
+        const cas = this.storage.compareAndSet;
+        if (!cas)
+            throw new Error("Creating access tokens requires atomic compareAndSet storage");
+        for (let attempt = 0; attempt < 32; attempt++) {
+            const raw = await this.storage.get(ACTIVE_KEY);
+            const ids = raw === null
+                ? (await this.list()).filter(token => !token.revokedAt).map(token => token.id)
+                : JSON.parse(raw);
+            if (!Array.isArray(ids) || !ids.every(value => typeof value === "string" && ID_RE.test(value)) || new Set(ids).size !== ids.length) {
+                throw new Error("Stored access token capacity is invalid");
+            }
+            if (adding && ids.length >= this.maxActive)
+                throw new Error(`This deployment already has the maximum of ${this.maxActive} active access tokens`);
+            const next = adding ? [...ids, id] : ids.filter(value => value !== id);
+            if (await cas.call(this.storage, ACTIVE_KEY, raw, JSON.stringify(next)))
+                return;
+        }
+        throw new Error("Access token capacity is busy; retry the operation");
+    }
+    async authorize(request) {
+        const header = request.headers.get("authorization") ?? "";
+        const match = /^Bearer\s+(.+)$/iu.exec(header);
+        const token = match?.[1];
+        if (!token || !TOKEN_VALUE_RE.test(token))
+            return unauthorized();
+        const hash = await hashToken(token);
+        const lookupRaw = await this.storage.get(lookupKey(hash));
+        if (!lookupRaw)
+            return unauthorized();
+        const lookup = parseLookup(lookupRaw);
+        if (!lookup)
+            return unauthorized();
+        const record = await this.read(lookup.id);
+        if (!record || record.revokedAt || record.tokenHash !== hash || record.tokenPrefix !== token.slice(0, 12)) {
+            return unauthorized();
+        }
+        return {
+            ok: true,
+            subjectId: record.id,
+            ...(record.principal ? { principal: { ...record.principal } } : {}),
+        };
+    }
+}
+/** Opt in using the same storage namespace that held the v0.23 records. */
+export function accessTokens(storage, options = {}) {
+    const manager = new AccessTokenManager(storage, options);
+    return { auth: manager.auth, handle: context => routeAccessTokens(context, manager) };
+}

package/dist/artifacts/document.js

@@ -42,19 +42,23 @@ const DEFINE_GLOBAL = '(()=>{const f=(o)=>{if(o!==null&&typeof o==="object"){for
 /**
  * The complete document a viewer or render check loads. `data` maps document
  * names to their stored, script-safe JSON text, which is spliced in as-is.
+ *
+ * `theme` reaches a Markdown page only, whose styling is connecta's own. An
+ * HTML page is the author's, down to its colors, and is never restyled; the
+ * frame around it is what follows the deployment's scheme.
  */
 export function buildFrameDocument(input) {
     let page = input.source;
     if (input.kind === "markdown") {
         try {
-            page = markdownPage(input.source, input.global.title);
+            page = markdownPage(input.source, input.global.title, input.theme);
         }
         catch (error) {
             if (!(error instanceof MarkdownNestingError))
                 throw error;
             // Old or externally populated stores may hold a page that today's
             // validator would reject. Render fixed text instead of throwing here.
-            page = markdownPage("This page has too many nested block quotes or lists to display.", input.global.title);
+            page = markdownPage("This page has too many nested block quotes or lists to display.", input.global.title, input.theme);
         }
     }
     const meta = scriptSafeJson(input.global);

package/dist/artifacts/markdown.js

@@ -13,6 +13,8 @@
 // of text, a delimiter that found no closer is never searched for again, and
 // nesting stops at a fixed depth. A megabyte of `[[[[` or `**` renders in
 // linear time, because this runs on every page view.
+import { resolveTheme, schemeAttribute, themeCss, } from "../branding.js";
+import { TOKENS_CSS } from "../page-styles.js";
 const escapeHtml = (text) => text.replace(/[&<>"']/g, (c) => c === "&" ? "&amp;" : c === "<" ? "&lt;" : c === ">" ? "&gt;" : c === '"' ? "&quot;" : "&#39;");
 const PUNCTUATION = /^[!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{|}~]$/;
 const MAX_INLINE_DEPTH = 8;
@@ -430,20 +432,47 @@ export function renderMarkdown(source) {
         .map((line) => line.replace(/^\t+/, (tabs) => "    ".repeat(tabs.length)));
     return blocks(lines);
 }
-const MARKDOWN_STYLE = ":root{color-scheme:light dark}body{margin:0;font:16px/1.6 system-ui,-apple-system,'Segoe UI',sans-serif;" +
-    "color:#1f2328;background:#fff}main{max-width:820px;margin:0 auto;padding:40px 24px}" +
+/**
+ * Every color, font, and radius comes from the shared tokens, so a Markdown
+ * page reads as part of the viewer around it: the deployment's accent and
+ * fonts, and the palette of the scheme the page was given rather than whatever
+ * the OS prefers. The background is the frame's `--surface`, so the page sits
+ * flush in its card instead of painting a second one.
+ */
+const MARKDOWN_STYLE = "body{margin:0;font:16px/1.6 var(--sans);color:var(--text);background:var(--surface)}" +
+    "main{max-width:820px;margin:0 auto;padding:32px 24px}main>:first-child{margin-top:0}" +
     "h1,h2,h3,h4{line-height:1.25;margin:1.6em 0 .6em}h1{font-size:2em}h2{font-size:1.5em}" +
-    "a{color:#0969da}code{font:0.9em ui-monospace,SFMono-Regular,Menlo,monospace;background:#f3f4f6;padding:.1em .3em;border-radius:4px}" +
-    "pre{overflow:auto;padding:16px;background:#f3f4f6;border-radius:8px}pre code{background:none;padding:0}" +
-    "blockquote{margin:0;padding:0 1em;color:#59636e;border-left:4px solid #d1d9e0}" +
-    "table{border-collapse:collapse;display:block;overflow:auto}th,td{padding:6px 12px;border:1px solid #d1d9e0}" +
-    "img{max-width:100%}hr{border:0;border-top:1px solid #d1d9e0}" +
-    "@media (prefers-color-scheme:dark){body{color:#e6edf3;background:#0d1117}a{color:#4493f8}" +
-    "code,pre{background:#161b22}blockquote{color:#9198a1;border-color:#3d444d}th,td,hr{border-color:#3d444d}}";
-/** A complete page for a Markdown artifact: the rendered body in `<main id="artifact-root">`. */
-export function markdownPage(source, title) {
-    return (`<!doctype html><html lang="en"><head><meta charset="utf-8">` +
+    "a{color:var(--link)}code{font:.9em var(--mono);background:var(--surface-2);padding:.1em .3em;border-radius:4px}" +
+    "pre{overflow:auto;padding:16px;background:var(--surface-2);border-radius:calc(var(--radius) - 2px)}pre code{background:none;padding:0}" +
+    "blockquote{margin:0;padding:0 1em;color:var(--muted);border-left:4px solid var(--border-strong)}" +
+    "table{border-collapse:collapse;display:block;overflow:auto}th,td{padding:6px 12px;border:1px solid var(--border-strong)}" +
+    "th{background:var(--surface-2)}img{max-width:100%}hr{border:0;border-top:1px solid var(--border)}";
+const collapse = (text) => text.replace(/\s+/g, " ").trim().toLowerCase();
+/**
+ * The source without a leading `# Heading` that only repeats the title. The
+ * viewer shows the title as the page's heading directly above the frame, so a
+ * page opening with the same words would say them twice. Any other opening
+ * heading is the author's and stays.
+ */
+function withoutRepeatedTitle(source, title) {
+    const lines = source.replace(/\r\n?/g, "\n").split("\n");
+    const first = lines.findIndex((line) => line.trim() !== "");
+    const heading = first < 0 ? undefined : HEADING.exec(lines[first] ?? "");
+    if (heading?.[1] !== "#" || !collapse(title) || collapse(heading[2] ?? "") !== collapse(title)) {
+        return source;
+    }
+    return lines.slice(first + 1).join("\n");
+}
+/**
+ * A complete page for a Markdown artifact: the rendered body in
+ * `<main id="artifact-root">`. `theme` is the deployment's resolved theme; the
+ * viewer passes it so a pinned scheme and the operator's tokens reach the
+ * frame. Without one the page follows the OS scheme with default tokens.
+ */
+export function markdownPage(source, title, theme) {
+    const resolved = theme ?? resolveTheme();
+    return (`<!doctype html><html lang="en"${schemeAttribute(resolved)}><head><meta charset="utf-8">` +
         `<meta name="viewport" content="width=device-width,initial-scale=1">` +
-        `<title>${escapeHtml(title)}</title><style>${MARKDOWN_STYLE}</style></head>` +
-        `<body><main id="artifact-root">\n${renderMarkdown(source)}\n</main></body></html>`);
+        `<title>${escapeHtml(title)}</title><style>${TOKENS_CSS}${themeCss(resolved)}${MARKDOWN_STYLE}</style></head>` +
+        `<body><main id="artifact-root">\n${renderMarkdown(withoutRepeatedTitle(source, title))}\n</main></body></html>`);
 }

package/dist/artifacts/routes.js

@@ -11,6 +11,8 @@
 // could call — and the fetch directives leave it no network.
 import { resolveActorLabels, actorKey } from "../routes/actor-labels.js";
 import { authorize, mayViewArtifacts, privateJson, validateAuthPermissions, } from "../routes/shared.js";
+import { resolveBranding, schemeAttribute, themeCss } from "../branding.js";
+import { TOKENS_CSS } from "../page-styles.js";
 import { buildFrameDocument, frameCsp } from "./document.js";
 import { scriptSafeJson } from "./json.js";
 import { freshnessOf } from "./refresh.js";
@@ -20,19 +22,38 @@ const MAX_QUERY_CHARS = 200;
 const MAX_PINS = 32;
 const PIN = /^([A-Za-z_][A-Za-z0-9_]{0,63}):(\d{1,9})$/;
 const notFound = () => privateJson({ error: "not found" }, { status: 404 });
-/** The frame's bootstrap: wait for exactly one document from the parent, then become it. */
-function frameBootstrap(expectedOrigin) {
+/** How long the frame waits for its document before saying it did not come. */
+const FRAME_STALL_MS = 15_000;
+/**
+ * The frame's bootstrap: wait for exactly one document from the parent, then
+ * become it.
+ *
+ * Until the document arrives the frame shows one quiet line on the viewer's
+ * own surface, in the deployment's scheme and tokens, instead of a blank white
+ * box; if the handshake never completes, the line says so. None of it is page
+ * data — the scheme and tokens are deployment configuration — and all of it is
+ * gone the moment `document.open` replaces this document with the page.
+ */
+function frameBootstrap(expectedOrigin, theme) {
     return `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><meta name="referrer" content="no-referrer"></head><body>
+<html lang="en"${schemeAttribute(theme)}><head><meta charset="utf-8"><meta name="referrer" content="no-referrer">
+<style>${TOKENS_CSS}${themeCss(theme)}html{background:var(--surface)}body{color:var(--muted);font:.875rem/1.5 var(--sans);margin:0;padding:1.25rem 1.5rem}</style>
+</head><body>
+<p id="frame-status" role="status">Loading page…</p>
 <script>
 (() => {
   const expected = ${scriptSafeJson(expectedOrigin)};
   if (window.parent === window) return;
+  const status = document.getElementById("frame-status");
+  const stalled = setTimeout(() => {
+    status.textContent = "This page did not load. Reload to try again.";
+  }, ${FRAME_STALL_MS});
   const receive = (event) => {
     if (event.source !== window.parent || event.origin !== expected) return;
     const message = event.data;
     if (!message || message.type !== "document" || typeof message.html !== "string") return;
     window.removeEventListener("message", receive);
+    clearTimeout(stalled);
     document.open();
     document.write(message.html);
     document.close();
@@ -152,6 +173,7 @@ export function artifactRoutes(options) {
             document: buildFrameDocument({
                 kind: page.head.kind,
                 source: page.source,
+                theme: resolveBranding(context.opts.branding).theme,
                 global: {
                     id,
                     title: page.head.title,
@@ -169,7 +191,8 @@ export function artifactRoutes(options) {
         if (path === "/artifacts/_frame") {
             if (!read)
                 return privateJson({ error: "method not allowed" }, { status: 405 });
-            return new Response(request.method === "HEAD" ? null : frameBootstrap(new URL(context.baseUrl).origin), {
+            const bootstrap = frameBootstrap(new URL(context.baseUrl).origin, resolveBranding(context.opts.branding).theme);
+            return new Response(request.method === "HEAD" ? null : bootstrap, {
                 headers: {
                     "Content-Type": "text/html; charset=utf-8",
                     "Content-Security-Policy": csp,