@hienlh/ppm 0.22.11 → 0.23.1

package/src/services/file-watcher/ignore-rules.ts

@@ -8,8 +8,16 @@
  * `fs.inotify.max_user_watches` for the whole machine.
  */
 
-/** Dependency trees, build output and tool caches — high directory count, no value to the UI. */
+/**
+ * Dependency trees, build output and tool caches — high directory count, no value to the UI.
+ *
+ * `.design` is a design's snapshot history and comments (`designs/<slug>/.design/`): one
+ * design with a hundred snapshots of a nested asset tree could spend thousands of the
+ * per-project watch budget and fan out a `file:changed` per copied file. Its changes are
+ * announced as `design:*` events instead.
+ */
 export const IGNORED_DIRS = new Set([
+  ".design",
   ".git",
   ".gradle",
   ".idea",

package/src/services/server-listen-address.ts

@@ -0,0 +1,25 @@
+/**
+ * Where this process's HTTP server actually listens, for URLs PPM hands to its own child
+ * processes (the design MCP endpoint a Claude or Codex subprocess calls back into).
+ *
+ * The configured port is not good enough: the supervisor starts the server on port 0 and
+ * the OS picks one, and a dev server runs on whatever port it was given — a URL built from
+ * `configService.get("port")` then reaches another instance, or nothing. The server records
+ * the bound port here once `Bun.serve` returns; a process that never serves (the CLI) has
+ * none, and callers must treat that as "no callback available".
+ */
+
+let address: { port: number; hostname: string } | null = null;
+
+export function setServerListenAddress(port: number, hostname: string): void {
+  address = Number.isInteger(port) && port > 0 && port < 65536 ? { port, hostname } : null;
+}
+
+/** Base URL a local child process can reach this server on, or null when nothing listens. */
+export function localServerBaseUrl(): string | null {
+  if (!address) return null;
+  const host = address.hostname;
+  // A wildcard bind is reachable on loopback; a specific address only on itself.
+  const reachable = !host || host === "0.0.0.0" || host === "::" || host === "localhost" ? "127.0.0.1" : host;
+  return `http://${reachable.includes(":") ? `[${reachable}]` : reachable}:${address.port}`;
+}

package/src/shared/design-bridge-messages-check.ts

@@ -0,0 +1,44 @@
+import { CHECK_REQUEST_ID_RE, parseLayoutCheckReport } from "./design-canvas-check";
+
+/**
+ * Bridge messages for the canvas self-check, spread into the protocol's registries.
+ *
+ * Parent → frame: `check-run`, asking the bridge to measure the live document. `screenshot`
+ * asks for an image too, and then `lib` carries the screenshot library's source: the frame
+ * can load nothing from PPM's origin but its own design files, so the parent hands the code
+ * over and the frame runs it (its CSP allows eval). Frame → parent: `check-result` (the
+ * report, validated whole) or `check-error`. Both echo the parent's `requestId`, so an answer
+ * to an earlier request — or one a page script invents — is not taken for the current one.
+ * A report only ever becomes text an agent reads, never a write.
+ */
+
+/** Generous for the library's ~30 KB; anything bigger is not the library. */
+export const MAX_CHECK_LIB_CHARS = 256 * 1024;
+
+type Raw = Record<string, unknown>;
+const requestId = (v: unknown): string | null => (typeof v === "string" && CHECK_REQUEST_ID_RE.test(v) ? v : null);
+
+export const CHECK_CHILD_VALIDATORS = {
+  "check-result": (m: Raw) => {
+    const id = requestId(m.requestId);
+    const report = id ? parseLayoutCheckReport(m.report) : null;
+    return id && report ? { type: "check-result" as const, requestId: id, report } : null;
+  },
+  "check-error": (m: Raw) => {
+    const id = requestId(m.requestId);
+    if (!id || typeof m.message !== "string") return null;
+    return { type: "check-error" as const, requestId: id, message: m.message.slice(0, 300) };
+  },
+};
+
+export const CHECK_PARENT_VALIDATORS = {
+  "check-run": (m: Raw) => {
+    const id = requestId(m.requestId);
+    if (!id || typeof m.screenshot !== "boolean") return null;
+    if (m.lib !== undefined && (typeof m.lib !== "string" || m.lib.length > MAX_CHECK_LIB_CHARS)) return null;
+    return {
+      type: "check-run" as const, requestId: id, screenshot: m.screenshot,
+      ...(typeof m.lib === "string" ? { lib: m.lib } : {}),
+    };
+  },
+};

package/src/shared/design-bridge-messages-picker.ts

@@ -0,0 +1,142 @@
+import { DESIGN_GEN_RE } from "./design-types";
+import {
+  COMMENT_ID_RE, COMMENT_LIMITS, CSS_PATH_RE, ELEMENT_TAG_RE, parseCommentAnchor, parseCommentQuote, parsePpmId,
+  type CommentAnchor, type CommentQuote,
+} from "./design-comment-types";
+
+/**
+ * Bridge messages for the element picker and comment pins, spread into the protocol's
+ * registries.
+ *
+ * Frame → parent: `hover` (what the pointer or a first tap outlines), `select` (a click, a
+ * second tap), `element-menu` (a long-press: select and open the composer), `picker-exit`
+ * (Esc inside the frame) and `pins-rects` (where each pinned element is right now).
+ * Parent → frame: `picker`, `pins-set`, `select-parent`, `clear-selection`.
+ *
+ * All of it is untrusted: the page's scripts can post the same shapes. Rects are clamped
+ * to finite numbers, ids are integers or null, strings are capped. Nothing here causes a
+ * write by itself — a re-anchor report only makes the parent *ask* the server, which
+ * re-checks it against the source.
+ */
+
+export interface BridgeRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface PickedElement {
+  ppmId: number | null;
+  gen: string | null;
+  file: string;
+  tag: string;
+  rect: BridgeRect;
+  cssPath: string;
+  /** The page's own markup for the element, for display only; never sent to the server or a prompt. */
+  outerHtml: string;
+  text: string;
+  quote: CommentQuote;
+}
+
+export interface PinRect {
+  id: string;
+  rect: BridgeRect | null;
+  ppmId: number | null;
+  gen: string | null;
+  /** True when the pin was found by its quote rather than its id; ppmId/gen are the new ones. */
+  reanchored: boolean;
+}
+
+export const MAX_PINS = 500;
+const MAX_OUTER_HTML = 2000;
+const MAX_ELEMENT_TEXT = 500;
+const COORD_LIMIT = 1e6;
+
+type Raw = Record<string, unknown>;
+const isRaw = (v: unknown): v is Raw => !!v && typeof v === "object" && !Array.isArray(v);
+const clampCoord = (v: unknown): number | null =>
+  typeof v === "number" && Number.isFinite(v) ? Math.max(-COORD_LIMIT, Math.min(COORD_LIMIT, v)) : null;
+
+export function parseBridgeRect(v: unknown): BridgeRect | null {
+  if (!isRaw(v)) return null;
+  const x = clampCoord(v.x), y = clampCoord(v.y), w = clampCoord(v.w), h = clampCoord(v.h);
+  if (x === null || y === null || w === null || h === null) return null;
+  return { x, y, w: Math.max(0, w), h: Math.max(0, h) };
+}
+
+const parseGen = (v: unknown): string | null | undefined =>
+  v === null || v === undefined ? null : typeof v === "string" && DESIGN_GEN_RE.test(v) ? v : undefined;
+
+export function parsePickedElement(v: unknown): PickedElement | null {
+  if (!isRaw(v)) return null;
+  const ppmId = parsePpmId(v.ppmId);
+  const gen = parseGen(v.gen);
+  const tag = typeof v.tag === "string" ? v.tag.toLowerCase() : "";
+  const rect = parseBridgeRect(v.rect);
+  const file = typeof v.file === "string" ? v.file.slice(0, COMMENT_LIMITS.file) : "";
+  if (ppmId === undefined || gen === undefined || !ELEMENT_TAG_RE.test(tag) || !rect || !file) return null;
+  const cssPath = typeof v.cssPath === "string" ? v.cssPath.slice(0, COMMENT_LIMITS.cssPath) : "";
+  return {
+    ppmId, gen, file, tag, rect,
+    cssPath: CSS_PATH_RE.test(cssPath) ? cssPath : "",
+    outerHtml: typeof v.outerHtml === "string" ? v.outerHtml.slice(0, MAX_OUTER_HTML) : "",
+    text: typeof v.text === "string" ? v.text.slice(0, MAX_ELEMENT_TEXT) : "",
+    quote: parseCommentQuote(v.quote),
+  };
+}
+
+function parsePinRect(v: unknown): PinRect | null {
+  if (!isRaw(v) || typeof v.id !== "string" || !COMMENT_ID_RE.test(v.id)) return null;
+  const ppmId = parsePpmId(v.ppmId);
+  const gen = parseGen(v.gen);
+  if (ppmId === undefined || gen === undefined) return null;
+  return { id: v.id, rect: v.rect === null ? null : parseBridgeRect(v.rect), ppmId, gen, reanchored: v.reanchored === true };
+}
+
+function parseList<T>(v: unknown, item: (x: unknown) => T | null): T[] | null {
+  if (!Array.isArray(v) || v.length > MAX_PINS) return null;
+  const out: T[] = [];
+  for (const x of v) {
+    const parsed = item(x);
+    if (parsed) out.push(parsed);
+  }
+  return out;
+}
+
+export const PICKER_CHILD_VALIDATORS = {
+  hover: (m: Raw) => {
+    if (m.el === null) return { type: "hover" as const, el: null };
+    if (!isRaw(m.el)) return null;
+    const tag = typeof m.el.tag === "string" ? m.el.tag.toLowerCase() : "";
+    const rect = parseBridgeRect(m.el.rect);
+    return ELEMENT_TAG_RE.test(tag) && rect ? { type: "hover" as const, el: { tag, rect } } : null;
+  },
+  select: (m: Raw) => {
+    const el = parsePickedElement(m.el);
+    return el ? { type: "select" as const, el } : null;
+  },
+  "element-menu": (m: Raw) => {
+    const el = parsePickedElement(m.el);
+    return el ? { type: "element-menu" as const, el } : null;
+  },
+  "picker-exit": () => ({ type: "picker-exit" as const }),
+  "pins-rects": (m: Raw) => {
+    const pins = parseList(m.pins, parsePinRect);
+    return pins ? { type: "pins-rects" as const, pins } : null;
+  },
+};
+
+export const PICKER_PARENT_VALIDATORS = {
+  picker: (m: Raw) => (typeof m.on === "boolean" ? { type: "picker" as const, on: m.on } : null),
+  "pins-set": (m: Raw) => {
+    const pins = parseList(m.pins, (p): { id: string; anchor: CommentAnchor } | null => {
+      if (!isRaw(p) || typeof p.id !== "string" || !COMMENT_ID_RE.test(p.id)) return null;
+      const anchor = parseCommentAnchor(p.anchor);
+      return anchor ? { id: p.id, anchor } : null;
+    });
+    return pins ? { type: "pins-set" as const, pins } : null;
+  },
+  "select-parent": () => ({ type: "select-parent" as const }),
+  "clear-selection": () => ({ type: "clear-selection" as const }),
+};

package/src/shared/design-bridge-messages-slides.ts

@@ -0,0 +1,37 @@
+import { parseSlideDoc } from "./design-slide-doc-parse";
+
+/**
+ * Bridge messages for the PowerPoint export, spread into the protocol's registries.
+ *
+ * Parent → frame: `slides-extract`, asking the bridge to measure every slide of the live
+ * canvas. Frame → parent: `slides-data` (the measured deck) or `slides-error` (why it could
+ * not). Both echo the parent's `requestId`, so an answer to an earlier request (or one a page
+ * script invents) is not taken for the current one. The deck is validated whole by
+ * {@link parseSlideDoc}; it only ever becomes a file the user downloads, never a write.
+ */
+
+/** Shape of a request id: the parent mints it, the frame echoes it. */
+export const SLIDES_REQUEST_ID_RE = /^[A-Za-z0-9_-]{8,64}$/;
+
+type Raw = Record<string, unknown>;
+const requestId = (v: unknown): string | null => (typeof v === "string" && SLIDES_REQUEST_ID_RE.test(v) ? v : null);
+
+export const SLIDES_CHILD_VALIDATORS = {
+  "slides-data": (m: Raw) => {
+    const id = requestId(m.requestId);
+    const doc = id ? parseSlideDoc(m.doc) : null;
+    return id && doc ? { type: "slides-data" as const, requestId: id, doc } : null;
+  },
+  "slides-error": (m: Raw) => {
+    const id = requestId(m.requestId);
+    if (!id || typeof m.message !== "string") return null;
+    return { type: "slides-error" as const, requestId: id, message: m.message.slice(0, 300) };
+  },
+};
+
+export const SLIDES_PARENT_VALIDATORS = {
+  "slides-extract": (m: Raw) => {
+    const id = requestId(m.requestId);
+    return id ? { type: "slides-extract" as const, requestId: id } : null;
+  },
+};

package/src/shared/design-bridge-messages-transform.ts

@@ -0,0 +1,121 @@
+import { DESIGN_GEN_RE } from "./design-types";
+import { ELEMENT_TAG_RE, parsePpmId } from "./design-comment-types";
+import { parseBridgeRect, type BridgeRect } from "./design-bridge-messages-picker";
+
+/**
+ * Bridge messages for moving and resizing an element on the canvas, spread into the
+ * protocol's registries.
+ *
+ * Parent → frame: `transform-mode` (Move on/off, and the canvas scale, so handles stay 44
+ * screen px), `transform-target` (which element gets handles), `transform-nudge` (arrow keys
+ * pressed in the parent's canvas pane) and `transform-cancel` (put the live style back).
+ * Frame → parent: `transform-live` (where the element is while it moves) and
+ * `transform-commit`, which is only a **proposal**: the page's own scripts can post the same
+ * shape, so the parent decides whether anything is written (see
+ * `design-transform-proposal.ts`), and the server validates the props again with
+ * {@link parseTransformProps}.
+ */
+
+export type TransformProp = "translate" | "width" | "height";
+export type TransformProps = Partial<Record<TransformProp, string>>;
+
+export interface TransformBox {
+  /** The `translate` offsets and the `width`/`height` the element has right now, in px. */
+  tx: number;
+  ty: number;
+  w: number;
+  h: number;
+}
+
+/** Largest absolute px value a write may carry. */
+export const MAX_TRANSFORM_PX = 20000;
+/** Largest single nudge, in frame px. */
+export const MAX_NUDGE_PX = 1000;
+
+const PX = "(-?\\d{1,5}(?:\\.\\d{1,2})?)px";
+const TRANSLATE_RE = new RegExp(`^${PX} ${PX}$`);
+const SIZE_RE = /^(\d{1,5}(?:\.\d{1,2})?)px$/;
+
+type Raw = Record<string, unknown>;
+const isRaw = (v: unknown): v is Raw => !!v && typeof v === "object" && !Array.isArray(v);
+const inRange = (s: string): boolean => Math.abs(Number(s)) <= MAX_TRANSFORM_PX;
+const finite = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
+
+/**
+ * The three properties a canvas write may set, each a plain px value: `translate` as
+ * `"<n>px <n>px"`, `width`/`height` as `"<n>px"` (not negative), |n| ≤ 20000 with at most
+ * two decimals. Anything else, any other key, or nothing at all is null. The server trusts
+ * no other check than this one.
+ */
+export function parseTransformProps(v: unknown): TransformProps | null {
+  if (!isRaw(v)) return null;
+  const keys = Object.keys(v);
+  if (keys.length === 0 || keys.length > 3) return null;
+  const out: TransformProps = {};
+  for (const key of keys) {
+    const value = v[key];
+    if (typeof value !== "string") return null;
+    if (key === "translate") {
+      const m = TRANSLATE_RE.exec(value);
+      if (!m || !inRange(m[1]!) || !inRange(m[2]!)) return null;
+      out.translate = value;
+    } else if (key === "width" || key === "height") {
+      const m = SIZE_RE.exec(value);
+      if (!m || !inRange(m[1]!)) return null;
+      out[key] = value;
+    } else {
+      return null;
+    }
+  }
+  return out;
+}
+
+function parseBox(v: unknown): TransformBox | null {
+  if (!isRaw(v)) return null;
+  const tx = finite(v.tx), ty = finite(v.ty), w = finite(v.w), h = finite(v.h);
+  if (tx === null || ty === null || w === null || h === null) return null;
+  const clamp = (n: number) => Math.max(-1e6, Math.min(1e6, n));
+  return { tx: clamp(tx), ty: clamp(ty), w: Math.max(0, clamp(w)), h: Math.max(0, clamp(h)) };
+}
+
+export const TRANSFORM_CHILD_VALIDATORS = {
+  "transform-live": (m: Raw) => {
+    const ppmId = parsePpmId(m.ppmId);
+    if (typeof ppmId !== "number") return null;
+    const rect: BridgeRect | null = m.rect === null ? null : parseBridgeRect(m.rect);
+    if (m.rect !== null && !rect) return null;
+    const box = m.box === null || m.box === undefined ? null : parseBox(m.box);
+    return { type: "transform-live" as const, ppmId, rect, box };
+  },
+  "transform-commit": (m: Raw) => {
+    const ppmId = parsePpmId(m.ppmId);
+    const tag = typeof m.tag === "string" ? m.tag.toLowerCase() : "";
+    const gen = typeof m.gen === "string" && DESIGN_GEN_RE.test(m.gen) ? m.gen : null;
+    const file = typeof m.file === "string" && m.file.length <= 1024 ? m.file : "";
+    const props = parseTransformProps(m.props);
+    if (typeof ppmId !== "number" || !ELEMENT_TAG_RE.test(tag) || !gen || !file || !props) return null;
+    return { type: "transform-commit" as const, ppmId, tag, gen, file, props };
+  },
+};
+
+export const TRANSFORM_PARENT_VALIDATORS = {
+  "transform-mode": (m: Raw) => {
+    const scale = finite(m.scale);
+    if (typeof m.on !== "boolean" || scale === null || scale <= 0 || scale > 10) return null;
+    return { type: "transform-mode" as const, on: m.on, scale };
+  },
+  /** `ppmId: null` drops the handles. */
+  "transform-target": (m: Raw) => {
+    if (m.ppmId === null) return { type: "transform-target" as const, ppmId: null, tag: "" };
+    const ppmId = parsePpmId(m.ppmId);
+    const tag = typeof m.tag === "string" ? m.tag.toLowerCase() : "";
+    return typeof ppmId === "number" && ELEMENT_TAG_RE.test(tag) ? { type: "transform-target" as const, ppmId, tag } : null;
+  },
+  "transform-nudge": (m: Raw) => {
+    const dx = finite(m.dx), dy = finite(m.dy);
+    if (dx === null || dy === null || !Number.isInteger(dx) || !Number.isInteger(dy)) return null;
+    if (Math.abs(dx) > MAX_NUDGE_PX || Math.abs(dy) > MAX_NUDGE_PX || (dx === 0 && dy === 0)) return null;
+    return { type: "transform-nudge" as const, dx, dy };
+  },
+  "transform-cancel": () => ({ type: "transform-cancel" as const }),
+};

package/src/shared/design-bridge-messages-tweaks.ts

@@ -0,0 +1,65 @@
+import { MAX_TWEAKS, TWEAK_VAR_RE, isSafeTweakValueShape } from "./design-tweaks";
+
+/**
+ * Bridge messages for tweak controls, spread into the protocol's registries.
+ *
+ * Parent → frame: `tweak-set` (live values, applied as inline custom properties on the
+ * document element), `tweak-reset` (drop those overrides again) and `tweak-read` (report
+ * the rendered values). Frame → parent: `tweak-values`, the answer to a read.
+ *
+ * `tweak-values` is untrusted like everything the frame sends: it only fills the panel's
+ * controls and the "overridden" hint. What gets written is decided by the parent, from its
+ * own state, and re-validated by the server against the manifest.
+ */
+
+/** Which kind of rule the frame found setting a variable last, among the sheets it can read. */
+export type TweakWinner = "root" | "conditional" | "other" | "unknown";
+const WINNERS: readonly TweakWinner[] = ["root", "conditional", "other", "unknown"];
+/** Longest rendered value reported back; a custom property can hold far more than a tweak needs. */
+export const MAX_READ_VALUE = 200;
+
+type Raw = Record<string, unknown>;
+const isRaw = (v: unknown): v is Raw => !!v && typeof v === "object" && !Array.isArray(v);
+
+function varMap<T>(v: unknown, item: (x: unknown) => T | null): Record<string, T> | null {
+  if (!isRaw(v)) return null;
+  const entries = Object.entries(v);
+  if (entries.length > MAX_TWEAKS) return null;
+  const out: Record<string, T> = {};
+  for (const [name, value] of entries) {
+    const parsed = item(value);
+    if (!TWEAK_VAR_RE.test(name) || parsed === null) return null;
+    out[name] = parsed;
+  }
+  return out;
+}
+
+function varList(v: unknown): string[] | null {
+  if (!Array.isArray(v) || v.length > MAX_TWEAKS) return null;
+  return v.every((x) => typeof x === "string" && TWEAK_VAR_RE.test(x)) ? (v as string[]) : null;
+}
+
+export const TWEAK_CHILD_VALIDATORS = {
+  "tweak-values": (m: Raw) => {
+    const values = varMap(m.values, (x) => (typeof x === "string" ? x.slice(0, MAX_READ_VALUE) : null));
+    const winners = varMap(m.winners, (x) => WINNERS.find((w) => w === x) ?? null);
+    return values && winners ? { type: "tweak-values" as const, values, winners } : null;
+  },
+};
+
+export const TWEAK_PARENT_VALIDATORS = {
+  "tweak-set": (m: Raw) => {
+    const values = varMap(m.values, (x) => (isSafeTweakValueShape(x) ? x : null));
+    return values ? { type: "tweak-set" as const, values } : null;
+  },
+  /** No `vars`: every override the bridge set. */
+  "tweak-reset": (m: Raw) => {
+    if (m.vars === undefined) return { type: "tweak-reset" as const };
+    const vars = varList(m.vars);
+    return vars ? { type: "tweak-reset" as const, vars } : null;
+  },
+  "tweak-read": (m: Raw) => {
+    const vars = varList(m.vars);
+    return vars ? { type: "tweak-read" as const, vars } : null;
+  },
+};

package/src/shared/design-bridge-protocol.ts

@@ -0,0 +1,158 @@
+/**
+ * The postMessage protocol between the design canvas (parent, PPM's origin) and the bridge
+ * script injected into the sandboxed design document (child, an opaque origin).
+ *
+ * Every message is an envelope `{ppm: BRIDGE_CHANNEL, v: BRIDGE_VERSION, nonce, type, ...}`.
+ * The nonce is minted fresh by the parent for every iframe load (`?n=` on the URL) and baked
+ * into the document server-side; the bridge echoes its own copy on every message it posts.
+ * The parent accepts a child message only when its source is the iframe's `contentWindow`
+ * *and* its nonce is the current one: if the frame navigates itself to a foreign page, that
+ * page is the new `contentWindow` and passes the source check, but it never saw the nonce —
+ * unless the parent had told it, which is why parent → frame envelopes never carry one. The
+ * frame authenticates a parent message purely by `event.source`, which only `window.parent`
+ * itself can satisfy; no page running inside the frame can forge that.
+ *
+ * Everything the child sends is untrusted — the page's own scripts can post the same shapes.
+ * The validators cap every field; later features append their own validators to the two
+ * registries below and must never let a child message cause a write on its own.
+ */
+
+import { DESIGN_GEN_RE } from "./design-types";
+import { PICKER_CHILD_VALIDATORS, PICKER_PARENT_VALIDATORS } from "./design-bridge-messages-picker";
+import { TWEAK_CHILD_VALIDATORS, TWEAK_PARENT_VALIDATORS } from "./design-bridge-messages-tweaks";
+import { TRANSFORM_CHILD_VALIDATORS, TRANSFORM_PARENT_VALIDATORS } from "./design-bridge-messages-transform";
+import { SLIDES_CHILD_VALIDATORS, SLIDES_PARENT_VALIDATORS } from "./design-bridge-messages-slides";
+import { CHECK_CHILD_VALIDATORS, CHECK_PARENT_VALIDATORS } from "./design-bridge-messages-check";
+
+export { DESIGN_GEN_RE };
+
+export const BRIDGE_CHANNEL = "design-bridge";
+export const BRIDGE_VERSION = 1;
+/** Shape of the per-load nonce. Anything else is dropped by the server and the parent. */
+export const BRIDGE_NONCE_RE = /^[A-Za-z0-9_-]{16,64}$/;
+/** Most `issue` messages one document load may post. */
+export const MAX_BRIDGE_ISSUES = 20;
+
+export interface BridgeEnvelope {
+  ppm: typeof BRIDGE_CHANNEL;
+  v: typeof BRIDGE_VERSION;
+  nonce: string | null;
+  type: string;
+}
+
+type Raw = Record<string, unknown>;
+type Validator<T> = (raw: Raw) => T | null;
+
+const str = (v: unknown, max: number): string | null => (typeof v === "string" ? v.slice(0, max) : null);
+const num = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
+
+function cssGens(v: unknown): Record<string, string> | null {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return null;
+  const entries = Object.entries(v as Raw);
+  if (entries.length > 64) return null;
+  const out: Record<string, string> = {};
+  for (const [file, gen] of entries) {
+    if (file.length > 512 || typeof gen !== "string" || !DESIGN_GEN_RE.test(gen)) return null;
+    out[file] = gen;
+  }
+  return out;
+}
+
+export type IssueKind = "error" | "rejection" | "resource" | "csp";
+const ISSUE_KINDS: readonly IssueKind[] = ["error", "rejection", "resource", "csp"];
+
+/** Frame → parent. */
+export const CORE_CHILD_VALIDATORS = {
+  ready: (m: Raw) => {
+    const gen = typeof m.gen === "string" && DESIGN_GEN_RE.test(m.gen) ? m.gen : null;
+    const file = str(m.file, 1024);
+    const gens = cssGens(m.cssGens);
+    if (gen === null || file === null || gens === null || typeof m.instrumented !== "boolean") return null;
+    return {
+      type: "ready" as const, gen, cssGens: gens, file, instrumented: m.instrumented,
+      title: str(m.title, 200) ?? "", docHeight: Math.max(0, num(m.docHeight) ?? 0),
+    };
+  },
+  scroll: (m: Raw) => {
+    const x = num(m.x), y = num(m.y);
+    return x === null || y === null ? null : { type: "scroll" as const, x, y };
+  },
+  issue: (m: Raw) => {
+    const kind = ISSUE_KINDS.find((k) => k === m.kind);
+    const message = str(m.message, 500);
+    if (!kind || message === null) return null;
+    return { type: "issue" as const, kind, message, source: str(m.source, 1024) ?? undefined, line: num(m.line) ?? undefined };
+  },
+  "navigate-blocked": (m: Raw) => {
+    const href = str(m.href, 2048);
+    return href === null ? null : { type: "navigate-blocked" as const, href };
+  },
+  /** Posted by the expired-token page, which stands in for the design when its token is dead. */
+  expired: () => ({ type: "expired" as const }),
+} satisfies Record<string, Validator<{ type: string }>>;
+
+/** Parent → frame. */
+export const CORE_PARENT_VALIDATORS = {
+  "restore-scroll": (m: Raw) => {
+    const x = num(m.x), y = num(m.y);
+    return x === null || y === null ? null : { type: "restore-scroll" as const, x, y };
+  },
+} satisfies Record<string, Validator<{ type: string }>>;
+
+// Later features spread their validators into these two objects.
+export const CHILD_VALIDATORS = {
+  ...CORE_CHILD_VALIDATORS,
+  ...PICKER_CHILD_VALIDATORS,
+  ...TWEAK_CHILD_VALIDATORS,
+  ...TRANSFORM_CHILD_VALIDATORS,
+  ...SLIDES_CHILD_VALIDATORS,
+  ...CHECK_CHILD_VALIDATORS,
+};
+export const PARENT_VALIDATORS = {
+  ...CORE_PARENT_VALIDATORS,
+  ...PICKER_PARENT_VALIDATORS,
+  ...TWEAK_PARENT_VALIDATORS,
+  ...TRANSFORM_PARENT_VALIDATORS,
+  ...SLIDES_PARENT_VALIDATORS,
+  ...CHECK_PARENT_VALIDATORS,
+};
+
+type Validated<R> = { [K in keyof R]: R[K] extends Validator<infer T> ? T : never }[keyof R];
+export type ChildMessage = Validated<typeof CHILD_VALIDATORS> & { nonce: string | null };
+export type ParentMessage = Validated<typeof PARENT_VALIDATORS>;
+export type ChildMessageType = ChildMessage["type"];
+export type ParentMessageType = ParentMessage["type"];
+
+function parseEnvelope(data: unknown, registry: Record<string, Validator<{ type: string }>>): { nonce: string | null; body: { type: string } } | null {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+  const m = data as Raw;
+  if (m.ppm !== BRIDGE_CHANNEL || m.v !== BRIDGE_VERSION || typeof m.type !== "string") return null;
+  if (m.nonce !== null && (typeof m.nonce !== "string" || !BRIDGE_NONCE_RE.test(m.nonce))) return null;
+  // Own properties only: a type of "constructor" or "__proto__" must not reach a prototype.
+  if (!Object.prototype.hasOwnProperty.call(registry, m.type)) return null;
+  const body = registry[m.type]!(m);
+  return body ? { nonce: m.nonce as string | null, body } : null;
+}
+
+/** A validated child message (nonce included, for the caller to compare), or null. */
+export function parseChildMessage(data: unknown): ChildMessage | null {
+  const parsed = parseEnvelope(data, CHILD_VALIDATORS);
+  return parsed ? ({ ...parsed.body, nonce: parsed.nonce } as ChildMessage) : null;
+}
+
+/** A validated parent message, or null. The parent runs this before sending too. */
+export function parseParentMessage(data: unknown): ParentMessage | null {
+  const parsed = parseEnvelope(data, PARENT_VALIDATORS);
+  return parsed ? (parsed.body as ParentMessage) : null;
+}
+
+/**
+ * The envelope for a parent → frame message; envelope fields win over the payload's.
+ *
+ * No nonce: the frame never needs one to trust its parent (see the module docstring), and
+ * sending one would hand it to any page the frame navigated itself to, for that page to echo
+ * straight back and forge a `ready`.
+ */
+export function parentEnvelope(message: ParentMessage): BridgeEnvelope & ParentMessage {
+  return { ...message, ppm: BRIDGE_CHANNEL, v: BRIDGE_VERSION, nonce: null };
+}