@hienlh/ppm 0.22.11 → 0.23.1

package/src/server/ws/chat.ts

@@ -3,7 +3,8 @@ import { providerRegistry } from "../../providers/registry.ts";
 import { resolveProjectPath } from "../helpers/resolve-project.ts";
 import { logSessionEvent } from "../../services/session-log.service.ts";
 import { listSessions as sdkListSessions } from "@anthropic-ai/claude-agent-sdk";
-import { getSessionTitle, incrementSessionUnread, clearSessionUnread, getSessionModel, setSessionModel, getSessionProvider, getSessionEffort, setSessionEffort, getSessionThinking, setSessionThinking, setSessionMigratedTo } from "../../services/db.service.ts";
+import { getSessionTitle, incrementSessionUnread, clearSessionUnread, getSessionModel, setSessionModel, getSessionProvider, getSessionEffort, setSessionEffort, getSessionThinking, setSessionThinking, setSessionMigratedTo, getSessionDesignSlug, setSessionPermissionMode } from "../../services/db.service.ts";
+import { VALID_PERMISSION_MODES } from "../../types/config.ts";
 import { VALID_EFFORT_VALUES, THINKING_ADAPTIVE, isThinkingEnabled } from "../../providers/claude-agent-sdk-query-options.ts";
 import type { ChatWsClientMessage, SessionPhase } from "../../types/api.ts";
 // File watching and app-wide broadcasts are owned by the global WS (`./global.ts`)
@@ -1210,6 +1211,12 @@ export const chatWebSocket = {
       // Store permission mode — sticky for this session
       if (parsed.permissionMode) {
         entry.permissionMode = parsed.permissionMode;
+        // A design session keeps its mode for callers that pass none (CLI, scheduler), so
+        // the one the user picked here is written back rather than living in this socket.
+        if (VALID_PERMISSION_MODES.includes(parsed.permissionMode as typeof VALID_PERMISSION_MODES[number])
+          && getSessionDesignSlug(sessionId)) {
+          setSessionPermissionMode(sessionId, parsed.permissionMode);
+        }
       }
       // Store model override — sticky for this session
       if (parsed.model) {

package/src/server/ws/global.ts

@@ -10,7 +10,7 @@
  *     file watching at all — silently breaking editor live-reload, docx/pdf
  *     preview reload, and file-tree invalidation.
  *  2. **Cross-cutting broadcasts** (`file:changed`, `session:unread_changed`,
- *     `session:phase_changed`, `jira:*`). These are app-wide, not session-scoped,
+ *     `session:phase_changed`, `jira:*`, `design:*`). These are app-wide, not session-scoped,
  *     so they belong on an app-wide channel.
  *
  * Events go to global clients only — never also to chat clients — so a client
@@ -19,6 +19,8 @@
  */
 import { startWatching, stopWatching, onFileChange } from "../../services/file-watcher.service.ts";
 import { configService } from "../../services/config.service.ts";
+import { onDesignEvent } from "../../services/design/design-events.ts";
+import { resolve } from "node:path";
 
 type GlobalWsSocket = {
   data: { type: string };
@@ -67,6 +69,25 @@ onFileChange((projectName, path) => {
   broadcastGlobalEvent({ type: "file:changed", projectName, path });
 });
 
+/** Registered project whose folder is `projectPath`, or null. Case-folded on Windows. */
+function projectNameForPath(projectPath: string): string | null {
+  const fold = (p: string) => (process.platform === "win32" ? resolve(p).toLowerCase() : resolve(p));
+  const target = fold(projectPath);
+  return configService.get("projects").find((p) => fold(p.path) === target)?.name ?? null;
+}
+
+// Design history/comment changes: `.design/` is not watched, so these are the only signal.
+// Services know the project path; browsers address projects by name, and a path no
+// registered project owns is dropped rather than broadcast.
+onDesignEvent((type, { projectPath, slug, requestId, screenshot }) => {
+  const projectName = projectNameForPath(projectPath);
+  if (!projectName) return;
+  broadcastGlobalEvent({
+    type: `design:${type}`, projectName, slug,
+    ...(requestId ? { requestId, screenshot: screenshot === true } : {}),
+  });
+});
+
 export const globalWebSocket = {
   open(ws: GlobalWsSocket) {
     clients.add(ws);

package/src/services/chat.service.ts

@@ -12,6 +12,23 @@ import type {
   SendMessageOpts,
 } from "../providers/provider.interface.ts";
 import { compareSessionsByActivity } from "../types/chat.ts";
+import { buildDesignInstructions } from "./design/design-instructions.ts";
+import { isValidDesignSlug } from "./design/design-slug.ts";
+import { scheduleTurnSnapshot } from "./design/design-turn-snapshot.ts";
+import { designMcpAccessFor } from "./design/mcp/design-mcp-access.ts";
+import { designMcpTokens } from "./design/mcp/design-mcp-tokens.ts";
+import { isTerminalAgentStatus } from "../shared/background-agent-status.ts";
+
+/**
+ * Events after which a design session's files may have settled: the end of a turn, and a
+ * background task (which can keep writing after the turn's `done`) reaching a final state.
+ */
+function endsDesignWork(event: ChatEvent): boolean {
+  if (event.type === "done") return true;
+  if (event.type !== "system" || event.subtype !== "task_notification") return false;
+  const status = (event as { taskStatus?: string }).taskStatus;
+  return isTerminalAgentStatus(status) || status === "killed";
+}
 
 class ChatService {
   // Delivery hints only: a restart/eviction safely sends a fresh snapshot.
@@ -86,6 +103,7 @@ class ChatService {
     const provider = providerRegistry.get(providerId);
     if (!provider) throw new Error(`Provider "${providerId}" not found`);
     this.invalidateSharedContext(providerId, sessionId);
+    designMcpTokens.revoke(sessionId);
     return provider.deleteSession(sessionId);
   }
 
@@ -111,6 +129,17 @@ class ChatService {
         if (event.type === "error" || (event.type === "done" && event.resultSubtype?.startsWith("error")) || (event.type === "system" && event.subtype === "compact_done")) {
           this.invalidateSharedContext(providerId, activeSessionId);
         }
+        if (event.type === "session_migrated" && event.newSessionId !== event.oldSessionId) {
+          // Carries the design slug and stored mode (with model/effort) to the provider's
+          // real id for callers that are not the WebSocket, which records this itself —
+          // the copy keeps whatever the destination already has, so doing both is safe.
+          try {
+            const { setSessionMigratedTo } = await import("./db.service.ts");
+            setSessionMigratedTo(event.oldSessionId, event.newSessionId);
+          } catch (e) {
+            console.warn(`[chat] could not record session migration: ${(e as Error).message}`);
+          }
+        }
         const migratedId = event.type === "session_migrated" ? event.newSessionId : event.type === "done" ? event.sessionId : undefined;
         if (migratedId && migratedId !== activeSessionId) {
           const snapshot = this.sharedSnapshots.get(`${providerId}:${activeSessionId}`);
@@ -120,6 +149,10 @@ class ChatService {
           }
           activeSessionId = migratedId;
         }
+        if (endsDesignWork(event)) {
+          // Not awaited: the snapshot is debounced and must never hold up or fail the turn.
+          scheduleTurnSnapshot(activeSessionId, this.getSession(activeSessionId)?.projectPath);
+        }
         yield event;
       }
       finished = true;
@@ -136,6 +169,7 @@ class ChatService {
     opts?: SendMessageOpts,
   ): Promise<SendMessageOpts> {
     if (!providerRegistry.get(providerId)) throw new Error(`Provider "${providerId}" not found`);
+    const design = await this.resolveDesignOptions(sessionId, opts);
     let sharedContext: string | undefined;
     if (configService.get("ai").share_provider_context === false || /^\s*\/(compact|clear|new)(\s|$)/i.test(message)) {
       this.invalidateSharedContext(providerId, sessionId);
@@ -155,7 +189,36 @@ class ChatService {
         if (this.sharedSnapshots.get(`${providerId}:${sessionId}`) === hash) sharedContext = undefined;
       }
     }
-    return { ...opts, sharedContext };
+    return { ...design, sharedContext };
+  }
+
+  /**
+   * Design identity for this turn, resolved here because every caller — the WebSocket, the
+   * CLI, the scheduler, group chat, the bots — sends through this service, and a design
+   * session reached by any of them must get its instructions.
+   *
+   * Instruction text is only ever built from the stored slug: anything a caller put in
+   * `designInstructions`/`designSession` is discarded, so no client text reaches the
+   * system prompt. A design session has no permission default of its own — an agent that
+   * has to read and search the project to design for it would otherwise ask on every file.
+   * An explicit caller mode wins (the user picked it), then the mode stored for the session,
+   * then the provider's configured default, exactly as for any other chat.
+   */
+  private async resolveDesignOptions(sessionId: string, opts?: SendMessageOpts): Promise<SendMessageOpts> {
+    const { designInstructions: _instructions, designSession: _flag, designMcp: _mcp, ...rest } = opts ?? {};
+    const { getSessionDesignSlug, getSessionPermissionMode, getSessionProjectPath } = await import("./db.service.ts");
+    const slug = getSessionDesignSlug(sessionId);
+    if (!slug || !isValidDesignSlug(slug)) return rest;
+    const permissionMode = opts?.permissionMode ?? getSessionPermissionMode(sessionId) ?? undefined;
+    const projectPath = this.getSession(sessionId)?.projectPath ?? getSessionProjectPath(sessionId);
+    const designMcp = designMcpAccessFor(sessionId, projectPath, slug);
+    return {
+      ...rest,
+      designInstructions: buildDesignInstructions(slug, { checkTool: !!designMcp }),
+      designSession: true,
+      ...(designMcp ? { designMcp } : {}),
+      ...(permissionMode ? { permissionMode } : {}),
+    };
   }
 
   /** Push a live follow-up through the same context policy as sendMessage. */

package/src/services/db.service.ts

@@ -6,7 +6,9 @@ import { getPpmDir } from "./ppm-dir.ts";
 import { assertProdDbAccessAllowed } from "./prod-db-guard.ts";
 import { backupDbSync } from "./db-backup/db-backup-sync.ts";
 import { CODEX_DEFAULT_MODEL } from "../types/config.ts";
-export const CURRENT_SCHEMA_VERSION = 47;
+// Must equal the last `PRAGMA user_version` below: the pre-migration snapshot is skipped for
+// any database already at this version, so a stale value silently drops that backup.
+export const CURRENT_SCHEMA_VERSION = 50;
 
 let db: Database | null = null;
 let dbProfile: string | null = null;
@@ -1135,6 +1137,16 @@ export function runMigrations(database: Database): void {
     database.exec(`UPDATE codex_accounts SET daily_guard_enabled = 1`);
     database.exec(`PRAGMA user_version = 49;`);
   }
+
+  if (current < 50) {
+    // A design session is an ordinary session carrying the slug of the design it works on,
+    // plus the permission mode it runs under. The mode is stored per session because
+    // callers without a UI (CLI, scheduler, bots) pass none, and a design session must not
+    // fall back to the provider-wide default (usually bypass). NULL = an ordinary session.
+    try { database.exec("ALTER TABLE session_metadata ADD COLUMN design_slug TEXT"); } catch { /* exists */ }
+    try { database.exec("ALTER TABLE session_metadata ADD COLUMN permission_mode TEXT"); } catch { /* exists */ }
+    database.exec(`PRAGMA user_version = 50;`);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -1321,12 +1333,14 @@ export function setSessionMigratedTo(oldSessionId: string, newSessionId: string)
     // Carry explicit choices with it before reconnect reads session_state.
     // Keep any choices already made on the destination (including thinking OFF).
     database.query(`
-      INSERT INTO session_metadata (session_id, model, effort, thinking_budget)
-      SELECT ?, model, effort, thinking_budget FROM session_metadata WHERE session_id = ?
+      INSERT INTO session_metadata (session_id, model, effort, thinking_budget, design_slug, permission_mode)
+      SELECT ?, model, effort, thinking_budget, design_slug, permission_mode FROM session_metadata WHERE session_id = ?
       ON CONFLICT(session_id) DO UPDATE SET
         model = COALESCE(session_metadata.model, excluded.model),
         effort = COALESCE(session_metadata.effort, excluded.effort),
-        thinking_budget = COALESCE(session_metadata.thinking_budget, excluded.thinking_budget)
+        thinking_budget = COALESCE(session_metadata.thinking_budget, excluded.thinking_budget),
+        design_slug = COALESCE(session_metadata.design_slug, excluded.design_slug),
+        permission_mode = COALESCE(session_metadata.permission_mode, excluded.permission_mode)
     `).run(newSessionId, oldSessionId);
     database.query(
       "INSERT INTO session_metadata (session_id, migrated_to) VALUES (?, ?) " +
@@ -1434,6 +1448,61 @@ export function setSessionThinking(sessionId: string, budget: number | null): vo
   ).run(sessionId, budget);
 }
 
+/** Design this session works on (`designs/<slug>/`); null for an ordinary chat. */
+export function getSessionDesignSlug(sessionId: string): string | null {
+  const row = getDb().query("SELECT design_slug FROM session_metadata WHERE session_id = ?").get(sessionId) as { design_slug: string | null } | null;
+  return row?.design_slug ?? null;
+}
+
+export function setSessionDesignSlug(sessionId: string, slug: string): void {
+  getDb().query(
+    "INSERT INTO session_metadata (session_id, design_slug) VALUES (?, ?) ON CONFLICT(session_id) DO UPDATE SET design_slug = excluded.design_slug",
+  ).run(sessionId, slug);
+}
+
+/** Design slugs for many sessions at once (history lists); sessions without one are absent. */
+export function getSessionDesignSlugs(sessionIds: string[]): Record<string, string> {
+  const result: Record<string, string> = {};
+  // Chunked well under SQLite's bound-parameter limit, which a long history page can reach.
+  for (let i = 0; i < sessionIds.length; i += 500) {
+    const chunk = sessionIds.slice(i, i + 500);
+    const placeholders = chunk.map(() => "?").join(", ");
+    const rows = getDb().query(
+      `SELECT session_id, design_slug FROM session_metadata WHERE design_slug IS NOT NULL AND session_id IN (${placeholders})`,
+    ).all(...chunk) as { session_id: string; design_slug: string }[];
+    for (const r of rows) result[r.session_id] = r.design_slug;
+  }
+  return result;
+}
+
+/** Permission mode stored for this session; null = the caller's or provider's default applies. */
+export function getSessionPermissionMode(sessionId: string): string | null {
+  const row = getDb().query("SELECT permission_mode FROM session_metadata WHERE session_id = ?").get(sessionId) as { permission_mode: string | null } | null;
+  return row?.permission_mode ?? null;
+}
+
+export function setSessionPermissionMode(sessionId: string, mode: string): void {
+  getDb().query(
+    "INSERT INTO session_metadata (session_id, permission_mode) VALUES (?, ?) ON CONFLICT(session_id) DO UPDATE SET permission_mode = excluded.permission_mode",
+  ).run(sessionId, mode);
+}
+
+/**
+ * Give a fork the design identity of its source, so forking a design chat yields another
+ * design chat rather than an ordinary one that has quietly lost its instructions and its
+ * safer permission default. A no-op for a source that is not a design session.
+ */
+export function copySessionDesignSettings(sourceSessionId: string, targetSessionId: string): void {
+  if (sourceSessionId === targetSessionId) return;
+  const slug = getSessionDesignSlug(sourceSessionId);
+  if (!slug) return;
+  getDb().transaction(() => {
+    setSessionDesignSlug(targetSessionId, slug);
+    const mode = getSessionPermissionMode(sourceSessionId);
+    if (mode) setSessionPermissionMode(targetSessionId, mode);
+  })();
+}
+
 // ---------------------------------------------------------------------------
 // Unread tracking
 // ---------------------------------------------------------------------------

package/src/services/design/bridge/bridge-anchor-resolve.ts

@@ -0,0 +1,96 @@
+import type { CommentQuote } from "../../../shared/design-comment-types.ts";
+
+/**
+ * Finding a comment's element again after the file changed.
+ *
+ * An id is exact only while `gen` is unchanged: once the AI edits text above an element,
+ * every later start-tag offset moves and an old id may now name a *different* element. So
+ * the id is trusted only when the gen matches and the tag agrees. Otherwise every element
+ * of the same tag is scored by its text quote and the best one at or above 0.55 wins; the
+ * CSS path only breaks ties. No qualifying candidate means `orphaned` — a detached comment
+ * is always preferred to a pin on the wrong element.
+ *
+ * Shipped into the design frame as source (`ppm.lib.*`), so both functions are
+ * self-contained, and the similarity function is passed in rather than referenced. The
+ * server runs the same code to re-check a re-anchor the frame reports.
+ */
+
+export interface AnchorLike {
+  ppmId: number | null;
+  gen: string | null;
+  tag: string;
+  cssPath: string;
+  quote: CommentQuote;
+}
+
+export interface AnchorCandidate {
+  ppmId: number | null;
+  tag: string;
+  cssPath: string;
+  quote: CommentQuote;
+}
+
+export type AnchorResolution =
+  | { status: "exact" | "reanchored"; index: number; score: number }
+  | { status: "orphaned"; index: -1; score: number };
+
+/** Bigram Dice coefficient over lowercased, whitespace-collapsed text, in [0, 1]. */
+export function diceSimilarity(a: string, b: string): number {
+  const x = a.replace(/\s+/g, " ").trim().toLowerCase();
+  const y = b.replace(/\s+/g, " ").trim().toLowerCase();
+  if (x === y) return 1;
+  if (x.length < 2 || y.length < 2) return 0;
+  const counts = new Map<string, number>();
+  for (let i = 0; i < x.length - 1; i++) {
+    const g = x.slice(i, i + 2);
+    counts.set(g, (counts.get(g) || 0) + 1);
+  }
+  let shared = 0;
+  for (let i = 0; i < y.length - 1; i++) {
+    const g = y.slice(i, i + 2);
+    const n = counts.get(g) || 0;
+    if (n > 0) {
+      shared++;
+      counts.set(g, n - 1);
+    }
+  }
+  return (2 * shared) / (x.length - 1 + (y.length - 1));
+}
+
+export function resolveAnchor(
+  anchor: AnchorLike,
+  candidates: readonly AnchorCandidate[],
+  currentGen: string | null,
+  similarity: (a: string, b: string) => number,
+): AnchorResolution {
+  const MIN_SCORE = 0.55;
+  if (anchor.ppmId !== null && currentGen !== null && anchor.gen === currentGen) {
+    for (let i = 0; i < candidates.length; i++) {
+      const c = candidates[i]!;
+      if (c.ppmId === anchor.ppmId && c.tag === anchor.tag) return { status: "exact", index: i, score: 1 };
+    }
+  }
+  const q = anchor.quote;
+  // An element with no text of its own (an image, an empty cell) is recognised by its
+  // surroundings alone, and only matches another element with no text.
+  const textless = q.exact === "";
+  let best = -1;
+  let bestScore = 0;
+  for (let i = 0; i < candidates.length; i++) {
+    const c = candidates[i]!;
+    if (c.tag !== anchor.tag) continue;
+    if (textless && c.quote.exact !== "") continue;
+    let score = textless
+      ? 0.5 * similarity(q.prefix, c.quote.prefix) + 0.5 * similarity(q.suffix, c.quote.suffix)
+      : 0.7 * similarity(q.exact, c.quote.exact) + 0.15 * similarity(q.prefix, c.quote.prefix)
+        + 0.15 * similarity(q.suffix, c.quote.suffix);
+    if (anchor.cssPath !== "" && c.cssPath === anchor.cssPath) score += 0.05;
+    if (score > bestScore) {
+      best = i;
+      bestScore = score;
+    }
+  }
+  return best >= 0 && bestScore >= MIN_SCORE
+    ? { status: "reanchored", index: best, score: bestScore }
+    : { status: "orphaned", index: -1, score: bestScore };
+}

package/src/services/design/bridge/bridge-core.ts

@@ -0,0 +1,205 @@
+/**
+ * The bridge's core, running inside the sandboxed design document.
+ *
+ * This function is shipped to the frame as source (`toString()`, see bridge-script.ts), so
+ * it may not reference anything in this module's scope: every constant is written inline,
+ * and the window it runs in is passed in rather than read from a global. It is the first
+ * script in `<head>`, so every listener here is registered before the page's own.
+ *
+ * What it gives the feature modules (`ppm`): `post` (to the parent, nonce attached), `on`
+ * (handlers for parent messages, which are only ever accepted from `window.parent`), `byId`
+ * (the element carrying a `data-ppm-id`), and `issue` (errors, failed loads and CSP
+ * violations, at most 20 per load). It posts `ready` once the document is parsed and
+ * `scroll` as the page scrolls, and applies `restore-scroll`.
+ */
+
+import type { anchorOf, cssPathOf, describeElement, domTreeAccess, elementQuote } from "./bridge-element-info.ts";
+import type { diceSimilarity, resolveAnchor } from "./bridge-anchor-resolve.ts";
+import type { createPickerOverlay } from "./bridge-picker-overlay.ts";
+import type { applyDrag, formatPx, parseTranslate, zoneAt } from "./bridge-transform-math.ts";
+import type { createTransformOverlay } from "./bridge-transform-overlay.ts";
+import type { createTransformStyle } from "./bridge-transform-style.ts";
+import type { extractTextRuns, mergeTextRuns, parseCssColor } from "./bridge-extract-text.ts";
+import type { blockItems, cssRotation } from "./bridge-extract-blocks.ts";
+import type { imageDataUrl } from "./bridge-extract-images.ts";
+import type { checkLabel, gridImplicitFindings } from "./bridge-layout-grid.ts";
+import type { boxFindings } from "./bridge-layout-boxes.ts";
+import type { captureScreenshot } from "./bridge-layout-screenshot.ts";
+
+export interface BridgeBoot {
+  nonce: string | null;
+  gen: string;
+  cssGens: Record<string, string>;
+  file: string;
+  instrumented: boolean;
+}
+
+export type BridgeHandler = (message: Record<string, unknown>) => void;
+
+/**
+ * Helpers several features share, installed by the assembly as `ppm.lib` from their own
+ * source. Keyed by string names the assembly writes, so a bundler renaming the functions
+ * cannot break a feature that calls one.
+ */
+export interface BridgeLib {
+  elementQuote: typeof elementQuote;
+  domTreeAccess: typeof domTreeAccess;
+  cssPathOf: typeof cssPathOf;
+  anchorOf: typeof anchorOf;
+  describeElement: typeof describeElement;
+  diceSimilarity: typeof diceSimilarity;
+  resolveAnchor: typeof resolveAnchor;
+  createPickerOverlay: typeof createPickerOverlay;
+  parseTranslate: typeof parseTranslate;
+  formatPx: typeof formatPx;
+  applyDrag: typeof applyDrag;
+  zoneAt: typeof zoneAt;
+  createTransformOverlay: typeof createTransformOverlay;
+  createTransformStyle: typeof createTransformStyle;
+  parseCssColor: typeof parseCssColor;
+  mergeTextRuns: typeof mergeTextRuns;
+  extractTextRuns: typeof extractTextRuns;
+  cssRotation: typeof cssRotation;
+  blockItems: typeof blockItems;
+  imageDataUrl: typeof imageDataUrl;
+  checkLabel: typeof checkLabel;
+  gridImplicitFindings: typeof gridImplicitFindings;
+  boxFindings: typeof boxFindings;
+  captureScreenshot: typeof captureScreenshot;
+}
+
+export interface BridgeApi {
+  win: Window;
+  doc: Document;
+  boot: BridgeBoot;
+  lib: BridgeLib;
+  post(type: string, payload?: Record<string, unknown>): void;
+  on(type: string, handler: BridgeHandler): void;
+  byId(ppmId: unknown): Element | null;
+  issue(kind: "error" | "rejection" | "resource" | "csp", message: string, source?: string, line?: number): void;
+  /** Called by the assembly once every feature is installed; schedules `ready`. */
+  start(): void;
+}
+
+export function installBridgeCore(win: Window): BridgeApi {
+  const doc = win.document;
+  const script = (doc.currentScript || doc.querySelector("script[data-ppm-bridge]")) as HTMLScriptElement | null;
+  const data: DOMStringMap = script ? script.dataset : {};
+  let cssGens: Record<string, string> = {};
+  try {
+    const parsed = JSON.parse(data.cssGens || "{}");
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) cssGens = parsed;
+  } catch (e) {
+    cssGens = {};
+  }
+  const nonce = data.nonce && /^[A-Za-z0-9_-]{16,64}$/.test(data.nonce) ? data.nonce : null;
+  const boot: BridgeBoot = {
+    nonce, gen: data.gen || "", cssGens, file: data.file || "", instrumented: data.instrumented === "1",
+  };
+  // Out of the DOM once read, so the page's own markup (and anything describing it) never
+  // includes the bridge.
+  if (script && script.parentNode) script.parentNode.removeChild(script);
+
+  const parent = win.parent;
+  const handlers = new Map<string, BridgeHandler[]>();
+  let issues = 0;
+
+  function post(type: string, payload?: Record<string, unknown>): void {
+    // Envelope fields are assigned last, so a payload cannot overwrite the nonce or type.
+    const message = Object.assign({}, payload || {}, { ppm: "design-bridge", v: 1, nonce, type });
+    try {
+      parent.postMessage(message, "*");
+    } catch (e) {
+      // An uncloneable payload is the feature's bug; the page must keep working.
+    }
+  }
+
+  function issue(kind: "error" | "rejection" | "resource" | "csp", message: string, source?: string, line?: number): void {
+    if (issues >= 20) return;
+    issues++;
+    post("issue", { kind, message: String(message).slice(0, 500), source: source ? String(source).slice(0, 1024) : undefined, line });
+  }
+
+  win.addEventListener("message", (event: MessageEvent) => {
+    // `event.source` is set by the browser to the sender's own window, which nothing but
+    // `window.parent` itself can ever equal — so this alone authenticates the message as
+    // parent-originated, and the nonce (which the parent no longer sends anyway) adds nothing.
+    if (parent === win || event.source !== parent) return;
+    const m = event.data;
+    if (!m || typeof m !== "object" || m.ppm !== "design-bridge" || m.v !== 1 || typeof m.type !== "string") return;
+    const list = handlers.get(m.type);
+    if (!list) return;
+    for (let i = 0; i < list.length; i++) {
+      try {
+        list[i]!(m);
+      } catch (e) {
+        issue("error", "bridge handler " + m.type + ": " + (e && (e as Error).message));
+      }
+    }
+  });
+
+  win.addEventListener("error", (event: Event) => {
+    const target = event.target as (Element & { src?: string; href?: string }) | null;
+    if (target && target !== (win as unknown) && target.tagName) {
+      issue("resource", "Failed to load <" + target.tagName.toLowerCase() + ">", target.src || target.href || "");
+      return;
+    }
+    const e = event as ErrorEvent;
+    issue("error", e.message || "Script error", e.filename, e.lineno);
+  }, true);
+  win.addEventListener("unhandledrejection", (event: PromiseRejectionEvent) => {
+    const reason = event.reason;
+    issue("rejection", reason && reason.message ? reason.message : String(reason));
+  });
+  doc.addEventListener("securitypolicyviolation", (event: SecurityPolicyViolationEvent) => {
+    issue("csp", event.violatedDirective + " blocked " + (event.blockedURI || "inline"), event.sourceFile, event.lineNumber);
+  });
+
+  let scrollTimer: number | null = null;
+  win.addEventListener("scroll", () => {
+    if (scrollTimer !== null) return;
+    scrollTimer = win.setTimeout(() => {
+      scrollTimer = null;
+      post("scroll", { x: win.scrollX, y: win.scrollY });
+    }, 100);
+  }, { passive: true });
+
+  const ppm: BridgeApi = {
+    win,
+    doc,
+    boot,
+    // Filled in by the assembly before any feature runs.
+    lib: {} as BridgeLib,
+    post,
+    issue,
+    on(type: string, handler: BridgeHandler): void {
+      const list = handlers.get(type) || [];
+      list.push(handler);
+      handlers.set(type, list);
+    },
+    byId(ppmId: unknown): Element | null {
+      if (typeof ppmId !== "number" || !Number.isInteger(ppmId) || ppmId < 0) return null;
+      return doc.querySelector('[data-ppm-id="' + ppmId + '"]');
+    },
+    start(): void {
+      const ready = (): void => {
+        post("ready", {
+          gen: boot.gen,
+          cssGens: boot.cssGens,
+          file: boot.file,
+          instrumented: boot.instrumented,
+          title: String(doc.title || "").slice(0, 200),
+          docHeight: doc.documentElement ? doc.documentElement.scrollHeight : 0,
+        });
+      };
+      if (doc.readyState === "loading") doc.addEventListener("DOMContentLoaded", ready, { once: true });
+      else ready();
+    },
+  };
+
+  ppm.on("restore-scroll", (m) => {
+    const x = m.x, y = m.y;
+    if (typeof x === "number" && typeof y === "number" && isFinite(x) && isFinite(y)) win.scrollTo(x, y);
+  });
+  return ppm;
+}