@jxsuite/studio 2.0.0 → 2.1.0

package/src/services/notify.ts

@@ -0,0 +1,271 @@
+/**
+ * Notify.ts — the third record type (plan §1), and the app's only way to say what happened.
+ *
+ * What this replaces: 78 `statusMessage()` call sites — 26 failures and 52 successes — rendered in
+ * identical 11px grey text in a 24px strip and destroyed after 3000 ms. A failure and a save looked
+ * the same, neither could be acted on, and both were gone before a reader who had looked away could
+ * read them. `statusMessage` is deleted, not wrapped; `scripts/check-styles.ts` bans the name from
+ * `src/` so it cannot regrow.
+ *
+ * **A notification is a record, and its lifetime is chosen by the action it requires** (§7.1):
+ *
+ * | Tier      | Host                       | Lifetime           | Use when                       |
+ * | --------- | -------------------------- | ------------------ | ------------------------------ |
+ * | `toast`   | the fourth overlay layer   | timed, dismissible | reversible, or needs no action |
+ * | `problem` | the Bottom dock's Problems | until it is fixed  | it must be fixed               |
+ *
+ * §7.1 names a third tier — **inline**, the `error` slot on `ui/field-row.ts`'s `renderFieldRow`.
+ * It is deliberately NOT a member of {@link NotificationTier}: an inline error is a value a control
+ * renders next to the field the user is editing, not a record the app posts to a host, and it has
+ * no store to live in. Declaring a tier here whose only possible outcome is being dropped on the
+ * floor would be exactly the silence this module exists to end, so the union has two members and
+ * the third tier arrives as `renderFieldRow`'s own parameter (P4.4).
+ *
+ * **Recovery is a command id, not a per-call-site closure.** `notify.error("Save failed", { action:
+ * "file.save" })` gives the toast and the Problems row a Retry button whose label, availability,
+ * disabled reason and keyboard chord all come off the command record — which is why this lives
+ * beside the registry rather than inside any one surface. A call site that wanted a Retry used to
+ * have to invent a button; now it names a capability that already exists.
+ *
+ * Nothing here renders. `ui/layers.ts` hosts the toasts and the Bottom dock hosts the Problems
+ * list; both read the two reactive arrays below, so a new surface can render notifications without
+ * this module learning it exists.
+ */
+
+import { reactive } from "../reactivity";
+import { announce } from "./announce";
+import { now } from "./clock";
+
+/** How bad it is. Chooses the icon, the colour, and the default tier. */
+export const SEVERITIES = ["success", "info", "warn", "error"] as const;
+
+export type Severity = (typeof SEVERITIES)[number];
+
+/**
+ * The two hosted lifetimes.
+ *
+ * A tier is a HOST, not a rendering preference: a record whose tier is `problem` is one the app
+ * promises to keep until somebody fixes it, and a record whose tier is `toast` is one it promises
+ * to take away. See the module doc for why `inline` is not here.
+ */
+export const TIERS = ["toast", "problem"] as const;
+
+export type NotificationTier = (typeof TIERS)[number];
+
+/** The default tier per severity. A failure must be fixed; everything else may be taken away. */
+const DEFAULT_TIER: Readonly<Record<Severity, NotificationTier>> = {
+  error: "problem",
+  info: "toast",
+  success: "toast",
+  warn: "toast",
+};
+
+/**
+ * How long a toast rests before it is taken away, by severity.
+ *
+ * §7.1 caps the band at 4–8s. A warning that nobody has to act on still deserves the long end of
+ * it, because it is the one a reader is most likely to have looked away from.
+ */
+export const TOAST_LIFETIME_MS: Readonly<Record<Severity, number>> = {
+  error: 8000,
+  info: 4000,
+  success: 4000,
+  warn: 8000,
+};
+
+/** What a caller may say about an outcome beyond its severity and its one line. */
+export interface NotifyOptions {
+  /**
+   * Command id offering recovery — the Retry / Fix button.
+   *
+   * A command id rather than a callback so the button's LABEL is the command's title, its enabled
+   * state is the command's `enablement`, and its refusal sentence is the command's `requires`. Four
+   * facts a closure could carry none of.
+   */
+  action?: string;
+  /** Args passed to {@link NotifyOptions.action} when it runs. */
+  actionArgs?: Record<string, unknown>;
+  /** The long form — a stack, a captured log, a validator's output. Rendered in Problems only. */
+  detail?: string;
+  /** Who reported it: "Save", "Source Control", "Canvas", "Assistant". Groups the Problems list. */
+  source?: string;
+  /** The file or document the outcome is about, so Problems can click through to it. */
+  path?: string;
+  /** Override the tier {@link DEFAULT_TIER} would pick — a warning that MUST be fixed. */
+  tier?: NotificationTier;
+  /**
+   * Deduplication key. A second notification with the same key REPLACES the first rather than
+   * stacking beside it — the file watcher that fails once a second is one problem, not sixty.
+   */
+  key?: string;
+  /** Override the toast's rest time. Ignored for the `problem` tier, which has no timer. */
+  timeoutMs?: number;
+}
+
+/** One outcome, as recorded. Frozen: a host renders it, nothing edits it after the fact. */
+export interface Notification {
+  readonly id: string;
+  readonly severity: Severity;
+  readonly message: string;
+  readonly tier: NotificationTier;
+  /** Epoch ms from {@link now}, so a pinned clock pins the "2m ago" a Problems row renders. */
+  readonly at: number;
+  readonly action?: string;
+  readonly actionArgs?: Record<string, unknown>;
+  readonly detail?: string;
+  readonly source?: string;
+  readonly path?: string;
+  readonly key?: string;
+  /** Rest time for a toast; `0` means "hold until dismissed". Absent on a problem. */
+  readonly timeoutMs?: number;
+}
+
+let _seq = 0;
+
+/** Monotonic within a page load, and stable enough to be a lit `repeat` key. */
+function nextId(): string {
+  _seq += 1;
+  return `n${_seq}`;
+}
+
+/**
+ * The live toast stack, oldest first. Reactive, so the host repaints by reading it.
+ *
+ * Exported as the array rather than behind a getter because that is what makes it trackable: a lit
+ * render effect that reads `toasts.length` re-runs when one arrives, with no subscription to
+ * remember to release.
+ */
+export const toasts: Notification[] = reactive([]);
+
+/**
+ * Everything that must be fixed, oldest first — what the Bottom dock's Problems tab renders and
+ * what the rail badge and the status bar count.
+ *
+ * The shape is the contract for that surface: each entry has an `id` to key on, a `severity` to
+ * sort and colour by, a `source` to group by, a `path` to click through to, an optional `detail`
+ * for the expanded row, and an optional `action` command id for its Fix / Retry button.
+ */
+export const problems: Notification[] = reactive([]);
+
+/** The most toasts on screen at once; the oldest is retired to make room. */
+export const MAX_TOASTS = 4;
+
+/** Which array a tier lives in. */
+function storeFor(tier: NotificationTier): Notification[] {
+  return tier === "problem" ? problems : toasts;
+}
+
+/**
+ * Record an outcome and return it.
+ *
+ * The record is returned so a caller that owns the outcome's life — an operation that retries and
+ * succeeds — can {@link dismiss} its own problem instead of leaving a fixed thing on the list.
+ */
+export function notify(
+  severity: Severity,
+  message: string,
+  options: NotifyOptions = {},
+): Notification {
+  const tier = options.tier ?? DEFAULT_TIER[severity];
+  const record: Notification = {
+    at: now(),
+    id: nextId(),
+    message,
+    severity,
+    tier,
+    ...(options.action === undefined ? {} : { action: options.action }),
+    ...(options.actionArgs === undefined ? {} : { actionArgs: options.actionArgs }),
+    ...(options.detail === undefined ? {} : { detail: options.detail }),
+    ...(options.source === undefined ? {} : { source: options.source }),
+    ...(options.path === undefined ? {} : { path: options.path }),
+    ...(options.key === undefined ? {} : { key: options.key }),
+    ...(tier === "toast" ? { timeoutMs: options.timeoutMs ?? TOAST_LIFETIME_MS[severity] } : {}),
+  };
+
+  const store = storeFor(tier);
+  if (record.key !== undefined) {
+    const at = store.findIndex((existing) => existing.key === record.key);
+    if (at !== -1) {
+      store.splice(at, 1);
+    }
+  }
+  store.push(record);
+  if (tier === "toast") {
+    while (toasts.length > MAX_TOASTS) {
+      toasts.shift();
+    }
+  }
+  /*
+   * Announce from HERE, not from a host.
+   *
+   * The `role="status"` region lived on the toast host, and `error` defaults to the `problem` tier —
+   * so a failure reached no live region at all, and a Problems-panel region would still announce
+   * nothing while another Bottom-dock tab was showing. One call site is what makes "posted" and
+   * "announced" the same event: a new host gets announcements without knowing this module exists.
+   *
+   * `source` is included because a screen-reader user has no visual grouping to tell them where the
+   * message came from, which is exactly what the panel's own column shows everyone else.
+   */
+  announce(
+    record.source === undefined ? record.message : `${record.source}: ${record.message}`,
+    severity === "error" ? "assertive" : "polite",
+  );
+  return record;
+}
+
+/** `notify.success(msg, opts)` and its three siblings — the shape §7.1 names. */
+function severityHelper(severity: Severity) {
+  return (message: string, options: NotifyOptions = {}) => notify(severity, message, options);
+}
+
+notify.success = severityHelper("success");
+notify.info = severityHelper("info");
+notify.warn = severityHelper("warn");
+notify.error = severityHelper("error");
+
+/**
+ * Take one notification off whichever list holds it. Returns whether it was there.
+ *
+ * One function for both stores because a caller holding a record should not have to remember which
+ * tier it landed in — the record says so.
+ */
+export function dismiss(id: string): boolean {
+  for (const store of [toasts, problems]) {
+    const at = store.findIndex((record) => record.id === id);
+    if (at !== -1) {
+      store.splice(at, 1);
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Drop every problem a predicate accepts (all of them with no predicate). Returns how many went.
+ *
+ * The predicate form is what lets an operation clear its own previous failures when it starts again
+ * — `clearProblems((p) => p.source === "Save")` — so a fixed problem stops being listed without the
+ * fixer having kept the record's id.
+ */
+export function clearProblems(match?: (record: Notification) => boolean): number {
+  const kept = match ? problems.filter((record) => !match(record)) : [];
+  const removed = problems.length - kept.length;
+  problems.splice(0, problems.length, ...kept);
+  return removed;
+}
+
+/** How many problems are outstanding, optionally of one severity — the badge and the status bar. */
+export function problemCount(severity?: Severity): number {
+  return severity === undefined
+    ? problems.length
+    : problems.filter((record) => record.severity === severity).length;
+}
+
+/**
+ * Clear both stores. For tests and for the "close project" path — a problem is about a project, and
+ * carrying one across a project switch would attribute it to the wrong repository.
+ */
+export function resetNotifications(): void {
+  toasts.splice(0);
+  problems.splice(0);
+}

package/src/services/profile.ts

@@ -0,0 +1,155 @@
+/**
+ * Startup profiles — a named, defined cold start.
+ *
+ * "What does Studio look like to someone who has never opened it?" currently has no answer inside
+ * the app. Every consumer of that question reaches _around_ it: the screenshot runner injects
+ * `localStorage.clear()` before the first navigation, the verify recipe says "use a fresh browser
+ * profile", and a support thread says "try a private window". All three clear the whole ORIGIN —
+ * including keys Studio does not own — and none of them can be invoked from inside the running
+ * app.
+ *
+ * Three shipped things need it to be a real, addressable state:
+ *
+ * - **Per-project layout and session persistence** cannot be tested without a defined starting point;
+ *   "whatever was in storage" is not one.
+ * - **Preferences: Reset Layout** is `applyProfile("fresh")` scoped to the layout keys, and the plan
+ *   promises it is "always one action away".
+ * - **Support** wants "reproduce with a clean profile" to be a URL, not an instruction.
+ *
+ * The profile is selected by `?profile=<id>` and applied ONCE, at import time, before anything
+ * reads persisted state — {@link import("../shell").shell} calls this above its own `localStorage`
+ * read for exactly that reason. `?clock=` rides alongside because it is the other boot-time knob:
+ * both describe the world the app wakes up in, and neither changes behaviour after.
+ */
+
+import { pinClock } from "./clock";
+
+/** What a profile resets. */
+export type ProfileReset = "none" | "app-state";
+
+export interface StartupProfile {
+  id: string;
+  /** Shown wherever a profile is offered (Preferences, the palette). */
+  description: string;
+  reset: ProfileReset;
+}
+
+/**
+ * The profiles Studio declares.
+ *
+ * `default` is not a no-op by omission — it is a named state, so "the app started normally" and
+ * "the profile was unrecognised" are different outcomes and the second one is loud.
+ */
+export const STARTUP_PROFILES: Readonly<Record<string, StartupProfile>> = {
+  default: {
+    description: "Resume whatever was persisted — layout, recents, settings, chat history.",
+    id: "default",
+    reset: "none",
+  },
+  fresh: {
+    description: "A first-run app: no layout, no recents, no settings, no history.",
+    id: "fresh",
+    reset: "app-state",
+  },
+};
+
+export const DEFAULT_PROFILE_ID = "default";
+
+/**
+ * Studio's own persisted keys, by prefix.
+ *
+ * Scoped rather than `localStorage.clear()`: the dev server, the docs site and Studio share an
+ * origin, and a profile that wipes a neighbour's state is a worse bug than the one it fixes. Every
+ * key Studio writes begins with `jx` followed by one of these separators — the panel widths, the
+ * recents, the GitHub token, the AI and Cloudflare settings, the chat sessions, the update
+ * dismissals and the canvas debug flag.
+ */
+const OWNED_KEY_PATTERN = /^jx[-._:]/;
+
+/** Whether a storage key belongs to Studio and is therefore a profile's to clear. */
+export function isStudioStorageKey(key: string): boolean {
+  return OWNED_KEY_PATTERN.test(key);
+}
+
+/**
+ * Drop every Studio-owned key from `localStorage`.
+ *
+ * @returns The keys removed, so a caller (Preferences, a test) can report what it did.
+ */
+export function clearStudioStorage(): string[] {
+  const store = globalThis.localStorage as Storage | undefined;
+  if (!store) {
+    return [];
+  }
+  const doomed: string[] = [];
+  try {
+    for (let i = 0; i < store.length; i++) {
+      const key = store.key(i);
+      if (key && isStudioStorageKey(key)) {
+        doomed.push(key);
+      }
+    }
+    for (const key of doomed) {
+      store.removeItem(key);
+    }
+  } catch {
+    // Storage unavailable (private mode, disabled cookies) — there is nothing persisted to reset.
+  }
+  return doomed;
+}
+
+/**
+ * Apply a profile by id.
+ *
+ * @throws {RangeError} When the id is not declared. A misspelled profile that silently fell back to
+ *   `default` would start the app in the state the caller was trying to avoid.
+ */
+export function applyProfile(id: string): StartupProfile {
+  const profile = STARTUP_PROFILES[id];
+  if (!profile) {
+    throw new RangeError(
+      `unknown startup profile "${id}"; declared: ${Object.keys(STARTUP_PROFILES).join(", ")}`,
+    );
+  }
+  if (profile.reset === "app-state") {
+    clearStudioStorage();
+  }
+  return profile;
+}
+
+/** What {@link applyStartupProfile} resolved. */
+export interface StartupState {
+  profile: StartupProfile;
+  /** The instant the clock was pinned to, or `null` when it follows the wall clock. */
+  clock: number | null;
+}
+
+let _startup: StartupState | null = null;
+
+/**
+ * Read `?profile=` and `?clock=` and apply them. Idempotent — the first call wins, so importing
+ * this from a second module cannot re-clear storage the app has already written to.
+ *
+ * @param search The query string to read. Defaults to the live location, and is passed explicitly
+ *   by the tests, which have no navigation.
+ */
+export function applyStartupProfile(search?: string): StartupState {
+  if (_startup) {
+    return _startup;
+  }
+  const query = new URLSearchParams(search ?? globalThis.location?.search ?? "");
+  const profile = applyProfile(query.get("profile") ?? DEFAULT_PROFILE_ID);
+  const clockParam = query.get("clock");
+  _startup = { clock: clockParam === null ? null : pinClock(clockParam), profile };
+  return _startup;
+}
+
+/** What the app started as. `null` until {@link applyStartupProfile} has run. */
+export function startupState(): StartupState | null {
+  return _startup;
+}
+
+/** Forget the resolved startup state, so the next call re-reads the query. Tests only. */
+export function resetStartupProfile(): void {
+  _startup = null;
+}

package/src/services/token-lint.ts

@@ -6,6 +6,7 @@
  */
 
 import type { JxMutableNode } from "@jxsuite/schema/types";
+import { displayTagName } from "@jxsuite/schema/guards";
 
 interface TokenLintFinding {
   path: string;
@@ -112,14 +113,14 @@ export function flagHardcodedTokens(
       for (let i = 0; i < el.children.length; i++) {
         const child = el.children[i];
         if (child && typeof child === "object") {
-          walk(child, `${pathPrefix} > ${child.tagName || `[${i}]`}`);
+          walk(child, `${pathPrefix} > ${displayTagName(child.tagName) || `[${i}]`}`);
         }
       }
     }
   }
 
   const tag = doc.tagName || "root";
-  walk(doc, tag);
+  walk(doc, displayTagName(tag));
   return findings;
 }
 

package/src/services/tool-executor.ts

@@ -5,6 +5,19 @@
  * `transactDoc()`), feeds the results back as `tool` messages, and re-streams — up to a capped
  * number of rounds (spec §10.2, ADR docs/ai-assistant-decision.md §6a).
  *
+ * Two §7.4 honesty rules live here rather than in the panel, because they are properties of the RUN
+ * and a panel can only render what the run recorded:
+ *
+ * - **A partial success is not a failure.** Running out of rounds called `setError`, which paints
+ *   the turn red and — in `chat-state.ts` — DELETES the streaming message, so a turn that applied
+ *   four edits and then hit the cap reported as an error that had also erased its own account of
+ *   the four edits. The cap is now an ordinary assistant message whenever anything was applied, and
+ *   an error only when nothing was.
+ * - **A batch belongs to the tab it edits.** `beginBatch(getTab())` ran once, against whichever tab
+ *   happened to be active when the loop started. A turn that then moved to a second document closed
+ *   its batch against the FIRST tab, so the second document's edits got neither a history snapshot
+ *   nor a collab publish. The loop re-anchors the batch whenever the active tab changes under it.
+ *
  * @license MIT
  */
 
@@ -13,7 +26,8 @@ import type { StreamingClient } from "@jxsuite/ai/streaming-client";
 import type { ToolRegistry } from "@jxsuite/ai/tools";
 
 import type { Tab } from "../tabs/tab";
-import { beginBatch, endBatch } from "../tabs/transact";
+import { batchTab, beginBatch, endBatch } from "../tabs/transact";
+import { beginTurn, endTurn } from "./ai-writes";
 
 const MAX_ROUNDS = 5;
 
@@ -41,11 +55,33 @@ export async function runAgentLoop({
   const allErrors: string[] = [];
   const appliedSummaries: string[] = [];
 
-  // Batch all tool-call mutations into a single undo step
+  /** The ledger is filed under the assistant message the turn ends on — see services/ai-writes. */
+  const turnId = () => chatState.messages.at(-1)?.id ?? "";
+  beginTurn(`turn:${chatState.messages.length}`);
+
+  // Batch all tool-call mutations into a single undo step, anchored on the tab being edited.
   if (getTab) {
     beginBatch(getTab());
   }
 
+  /**
+   * Close the batch and re-open it when the tools have moved to a different document.
+   *
+   * Runs after every tool execution rather than only inside `open_document`, because a tool is not
+   * the only thing that can change the active tab: project adoption replaces every tab in the
+   * workspace, and the user is free to click another tab while the model is still streaming.
+   */
+  const reanchorBatch = () => {
+    if (!getTab) {
+      return;
+    }
+    const current = getTab();
+    if (current !== batchTab()) {
+      endBatch();
+      beginBatch(current);
+    }
+  };
+
   try {
     for (let round = 1; round <= MAX_ROUNDS; round++) {
       const messages = chatState.toMessagesArray();
@@ -119,6 +155,7 @@ export async function runAgentLoop({
             error: `Failed to parse arguments: ${(error as Error).message}`,
           };
         }
+        reanchorBatch();
         if (!result.success && result.error) {
           allErrors.push(result.error);
         }
@@ -135,8 +172,9 @@ export async function runAgentLoop({
     }
 
     /*
-     * Surface the actual errors so the user knows what went wrong, not just a generic
-     * "I couldn't do it" message.
+     * The round cap. Surface the actual errors so the user knows what went wrong, not just a
+     * generic "I couldn't do it" — and, when anything was applied, say it as the ASSISTANT rather
+     * than as a failure (§7.4). A partial success is not a failure.
      */
     const uniqueErrors = [...new Set(allErrors)];
     const applied =
@@ -147,10 +185,18 @@ export async function runAgentLoop({
       uniqueErrors.length > 0
         ? `\n\nErrors encountered:\n${uniqueErrors.map((e) => `- ${e}`).join("\n")}`
         : "";
-    chatState.setError(
-      `I ran out of tool-call rounds (${MAX_ROUNDS}) before finishing.${applied}${errors}\n\nYou can continue by sending another message, or try a more specific request.`,
-    );
+    const tail =
+      `I ran out of tool-call rounds (${MAX_ROUNDS}) before finishing.${applied}${errors}` +
+      `\n\nYou can continue by sending another message, or try a more specific request.`;
+    if (appliedSummaries.length > 0) {
+      chatState.beginAssistantTurn();
+      chatState.appendDelta(tail);
+      chatState.finishStream("length");
+      return;
+    }
+    chatState.setError(tail);
   } finally {
     endBatch();
+    endTurn(turnId());
   }
 }

package/src/services/trusted-types.ts

@@ -0,0 +1,123 @@
+/**
+ * The one place a string becomes markup in the Studio shell — Trusted Types (W3C).
+ *
+ * **What the standard actually gates, verified rather than assumed.** The tempting reading is that
+ * `require-trusted-types-for 'script'` governs DOM injection sinks and leaves `eval` to
+ * `script-src`. That is wrong: under Trusted Types, `eval()` and `new Function()` are gated too,
+ * and throw when no default policy exists. Getting that backwards produces a plan that cannot be
+ * executed — which is why the shell does **not** enforce Trusted Types yet, and why this module
+ * ships the policy first (see `spec.md` §21.5).
+ *
+ * **This policy refuses to be a rubber stamp.** A `createHTML` that returns its input unchanged
+ * satisfies the API and defends nothing; it converts a real control into a type-level ceremony. So
+ * `createHTML` asserts, and throws on anything that looks like an injection — the value is meant to
+ * have come from `markdownToHtml`, which already drops raw HTML and `javascript:` URLs, and this is
+ * the check that says so out loud rather than trusting a call site to have remembered.
+ *
+ * **`createScript` and `createScriptURL` throw.** Nothing in the shell builds either from a string.
+ * The canvas interpreter does evaluate expressions, but it runs in the canvas iframe under its own
+ * policy — a permissive `createScript` here would re-permit evaluation for the whole shell to buy
+ * something the shell does not use.
+ *
+ * @docs studio/interface/problems-and-progress
+ */
+
+/** The subset of the Trusted Types API this module uses — typed here so no DOM lib is required. */
+interface TrustedTypesApi {
+  createPolicy: (
+    name: string,
+    rules: {
+      createHTML?: (input: string) => string;
+      createScript?: (input: string) => string;
+      createScriptURL?: (input: string) => string;
+    },
+  ) => { createHTML: (input: string) => unknown };
+}
+
+/** The policy name, which a CSP `trusted-types` directive would have to allow. */
+export const STUDIO_POLICY_NAME = "jx-studio";
+
+/**
+ * Patterns that must never survive sanitization.
+ *
+ * Deliberately a small, explicit list rather than a parser: this is an **assertion** over output
+ * that is already sanitized, not a sanitizer of its own. A second sanitizer here would be a second
+ * thing to keep correct, and the failure mode of a wrong one is a false sense of safety.
+ */
+const FORBIDDEN: readonly { pattern: RegExp; what: string }[] = [
+  { pattern: /<\s*script\b/i, what: "a <script> element" },
+  { pattern: /<\s*iframe\b/i, what: "an <iframe> element" },
+  { pattern: /<\s*object\b/i, what: "an <object> element" },
+  { pattern: /<\s*embed\b/i, what: "an <embed> element" },
+  { pattern: /\son[a-z]+\s*=/i, what: "an inline event handler attribute" },
+  { pattern: /javascript:/i, what: "a javascript: URL" },
+  { pattern: /data:text\/html/i, what: "a data: URL carrying HTML" },
+];
+
+/**
+ * Assert that a string is markup this app is willing to inject.
+ *
+ * @param {string} value
+ * @returns {string} The same string, when it passes.
+ * @throws {Error} Naming what it found, so the failure is diagnosable rather than a blank refusal.
+ */
+export function assertSanitized(value: string): string {
+  for (const { pattern, what } of FORBIDDEN) {
+    if (pattern.test(value)) {
+      throw new Error(
+        `Refusing to inject markup containing ${what}. This value should have come from ` +
+          "markdownToHtml, which removes it — a value that reaches here with it still present " +
+          "means the sanitizer was bypassed, not that this check is too strict.",
+      );
+    }
+  }
+  return value;
+}
+
+/** Created once. A second `createPolicy` with the same name throws when policies are restricted. */
+let policy: { createHTML: (input: string) => unknown } | null = null;
+
+/**
+ * The shell's Trusted Types policy, or null where the API does not exist.
+ *
+ * @returns {{ createHTML: (input: string) => unknown } | null}
+ */
+export function studioPolicy(): { createHTML: (input: string) => unknown } | null {
+  if (policy) {
+    return policy;
+  }
+  const api = (globalThis as unknown as { trustedTypes?: TrustedTypesApi }).trustedTypes;
+  if (!api) {
+    return null;
+  }
+  policy = api.createPolicy(STUDIO_POLICY_NAME, {
+    createHTML: assertSanitized,
+    createScript: () => {
+      throw new Error("The Studio shell does not build scripts from strings.");
+    },
+    createScriptURL: () => {
+      throw new Error("The Studio shell does not build script URLs from strings.");
+    },
+  });
+  return policy;
+}
+
+/**
+ * Turn already-sanitized markup into something an injection sink accepts.
+ *
+ * Returns a `TrustedHTML` where the API exists and the plain string where it does not — and in
+ * **both** cases the assertion has run, so the check is not contingent on a browser feature. A
+ * guard that only fires under Trusted Types would be a guard that never fires in the tests.
+ *
+ * @param {string} value Markup from `markdownToHtml`.
+ * @returns {unknown} A `TrustedHTML`, or the asserted string.
+ */
+export function trustedHtml(value: string): unknown {
+  const active = studioPolicy();
+  return active ? active.createHTML(value) : assertSanitized(value);
+}
+
+/** Forget the memoized policy. Tests only — each one installs its own `trustedTypes` stub. */
+export function resetStudioPolicy(): void {
+  policy = null;
+}