@hienlh/ppm 0.22.10 → 0.23.0

package/src/services/design/bridge/bridge-transform-math.ts

@@ -0,0 +1,104 @@
+/**
+ * The arithmetic behind the canvas's move and resize handles.
+ *
+ * Each function is shipped to the frame as its own source through `ppm.lib` (see
+ * bridge-script.ts), so each one must be self-contained: no reference to anything else in
+ * this module, not even to another function in it.
+ *
+ * Moving writes the individual `translate` property: it composes with an existing
+ * `transform`, never reflows siblings, and works whether or not the element is positioned.
+ * Resizing writes `width`/`height`; a drag from the left or top edge also shifts `translate`
+ * by what the size gave up, so the opposite edge stays where it was.
+ */
+
+export type TransformZone = "move" | "n" | "s" | "e" | "w" | "ne" | "nw" | "se" | "sw";
+
+export interface TransformBoxValue {
+  tx: number;
+  ty: number;
+  w: number;
+  h: number;
+}
+
+export interface ZoneRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/**
+ * A `translate` value as px offsets, or null when it holds anything else (a percentage, a
+ * `calc()`, a non-zero z) — a value the handles cannot extend without changing its meaning.
+ * `none` and the empty string are no offset at all.
+ */
+export function parseTranslate(value: string | null | undefined): { x: number; y: number } | null {
+  const v = String(value == null ? "" : value).trim().toLowerCase();
+  if (v === "" || v === "none") return { x: 0, y: 0 };
+  const parts = v.split(/\s+/);
+  if (parts.length > 3) return null;
+  const nums: number[] = [];
+  for (let i = 0; i < parts.length; i++) {
+    const m = /^(-?(?:\d+\.?\d*|\.\d+)(?:e-?\d+)?)(px)?$/.exec(parts[i]!);
+    if (!m) return null;
+    const n = Number(m[1]);
+    // A unitless number is only valid CSS for zero.
+    if (!Number.isFinite(n) || (!m[2] && n !== 0)) return null;
+    nums.push(n);
+  }
+  if (nums.length === 3 && nums[2] !== 0) return null;
+  return { x: nums[0]!, y: nums.length > 1 ? nums[1]! : 0 };
+}
+
+/** `n` as a CSS px value: at most two decimals, within ±20000, never `-0`. */
+export function formatPx(n: number): string {
+  const clamped = Math.max(-20000, Math.min(20000, Number.isFinite(n) ? n : 0));
+  const rounded = Math.round(clamped * 100) / 100;
+  return (rounded === 0 ? 0 : rounded) + "px";
+}
+
+/**
+ * The box after dragging `zone` by (dx, dy) frame px from `start`. Sizes never go below
+ * `min`; when a left or top drag hits that floor, the offset stops with it.
+ */
+export function applyDrag(start: TransformBoxValue, zone: TransformZone, dx: number, dy: number, min?: number): TransformBoxValue {
+  const floor = typeof min === "number" && min > 0 ? min : 1;
+  const out = { tx: start.tx, ty: start.ty, w: start.w, h: start.h };
+  if (zone === "move") {
+    out.tx = start.tx + dx;
+    out.ty = start.ty + dy;
+    return out;
+  }
+  if (zone.indexOf("e") >= 0) out.w = Math.max(floor, start.w + dx);
+  if (zone.indexOf("w") >= 0) {
+    out.w = Math.max(floor, start.w - dx);
+    out.tx = start.tx + (start.w - out.w);
+  }
+  if (zone.indexOf("s") >= 0) out.h = Math.max(floor, start.h + dy);
+  if (zone.indexOf("n") >= 0) {
+    out.h = Math.max(floor, start.h - dy);
+    out.ty = start.ty + (start.h - out.h);
+  }
+  return out;
+}
+
+/**
+ * Which handle a point is on: a square of side `hit` around each handle, and the element
+ * itself for moving. The middle half of the element always moves, so an element smaller
+ * than its handles can still be dragged by its centre.
+ */
+export function zoneAt(rect: ZoneRect, px: number, py: number, hit: number): TransformZone | null {
+  const half = hit / 2;
+  const inside = px >= rect.x && px <= rect.x + rect.w && py >= rect.y && py <= rect.y + rect.h;
+  const cx = rect.x + rect.w / 2, cy = rect.y + rect.h / 2;
+  if (inside && Math.abs(px - cx) <= rect.w / 4 && Math.abs(py - cy) <= rect.h / 4) return "move";
+  const x = rect.x, y = rect.y, r = rect.x + rect.w, b = rect.y + rect.h;
+  const points: Array<[TransformZone, number, number]> = [
+    ["nw", x, y], ["ne", r, y], ["sw", x, b], ["se", r, b], ["n", cx, y], ["s", cx, b], ["w", x, cy], ["e", r, cy],
+  ];
+  for (let i = 0; i < points.length; i++) {
+    const p = points[i]!;
+    if (Math.abs(px - p[1]) <= half && Math.abs(py - p[2]) <= half) return p[0];
+  }
+  return inside ? "move" : null;
+}

package/src/services/design/bridge/bridge-transform-overlay.ts

@@ -0,0 +1,94 @@
+import type { TransformZone, ZoneRect } from "./bridge-transform-math.ts";
+
+/**
+ * The move and resize handles, drawn inside the design frame.
+ *
+ * Like the picker's outline, they live in a closed shadow root on a host appended to
+ * `<html>`, out of reach of page CSS and never part of described markup. Unlike the
+ * outline, the handles are hit targets: each is a square of the given `hit` size (44 screen
+ * px, converted to frame px by the parent's scale) with `touch-action: none`, so a finger on
+ * one drags the element instead of scrolling the page, and the element's own box is the
+ * move area. The host itself stays `pointer-events: none`, so everything outside the
+ * handles still reaches the page. Seen from the window, every event on a handle targets the
+ * host; `bridge-transform.ts` works out which handle from the coordinates.
+ *
+ * Shipped as source (`ppm.lib.createTransformOverlay`), so it may only use what it is handed.
+ */
+
+export interface TransformOverlay {
+  host: HTMLElement;
+  /** Place the outline and handles over `rect` (frame viewport px), or hide them. */
+  place(rect: ZoneRect | null, hit: number, scale: number, zones: readonly TransformZone[]): void;
+}
+
+export function createTransformOverlay(doc: Document): TransformOverlay {
+  const host = doc.createElement("ppm-design-handles");
+  host.setAttribute("aria-hidden", "true");
+  const props: Array<[string, string]> = [
+    ["position", "fixed"], ["top", "0"], ["left", "0"], ["width", "0"], ["height", "0"], ["display", "block"],
+    ["overflow", "visible"], ["pointer-events", "none"], ["z-index", "2147483647"], ["margin", "0"], ["padding", "0"],
+  ];
+  for (const [name, value] of props) host.style.setProperty(name, value, "important");
+  const root = host.attachShadow({ mode: "closed" });
+  const make = (css: string): HTMLElement => {
+    const el = doc.createElement("div");
+    el.style.cssText = "position:fixed;display:none;box-sizing:border-box;" + css;
+    root.appendChild(el);
+    return el;
+  };
+  const outline = make("pointer-events:none;border:1.5px solid #2563eb;");
+  const move = make("pointer-events:auto;touch-action:none;cursor:move;background:transparent;");
+  const cursors: Record<string, string> = {
+    nw: "nwse-resize", se: "nwse-resize", ne: "nesw-resize", sw: "nesw-resize", n: "ns-resize", s: "ns-resize", w: "ew-resize", e: "ew-resize",
+  };
+  const order: TransformZone[] = ["nw", "ne", "sw", "se", "n", "s", "w", "e"];
+  const handles: Record<string, { area: HTMLElement; dot: HTMLElement }> = {};
+  for (const zone of order) {
+    const area = make("pointer-events:auto;touch-action:none;cursor:" + cursors[zone] + ";");
+    const dot = doc.createElement("div");
+    dot.style.cssText = "position:absolute;left:50%;top:50%;box-sizing:border-box;background:#fff;border:1.5px solid #2563eb;border-radius:2px;transform:translate(-50%,-50%);";
+    area.appendChild(dot);
+    handles[zone] = { area, dot };
+  }
+
+  const box = (el: HTMLElement, x: number, y: number, w: number, h: number): void => {
+    el.style.left = x + "px";
+    el.style.top = y + "px";
+    el.style.width = Math.max(0, w) + "px";
+    el.style.height = Math.max(0, h) + "px";
+    el.style.display = "block";
+  };
+
+  return {
+    host,
+    place(rect, hit, scale, zones) {
+      if (!host.isConnected && doc.documentElement) doc.documentElement.appendChild(host);
+      const all = [outline, move].concat(order.map((z) => handles[z]!.area));
+      if (!rect) {
+        for (const el of all) el.style.display = "none";
+        return;
+      }
+      const s = scale > 0 ? scale : 1;
+      box(outline, rect.x, rect.y, rect.w, rect.h);
+      outline.style.borderWidth = 1.5 / s + "px";
+      if (zones.indexOf("move") >= 0) box(move, rect.x, rect.y, rect.w, rect.h);
+      else move.style.display = "none";
+      const cx = rect.x + rect.w / 2, cy = rect.y + rect.h / 2, r = rect.x + rect.w, b = rect.y + rect.h;
+      const at: Record<string, [number, number]> = {
+        nw: [rect.x, rect.y], ne: [r, rect.y], sw: [rect.x, b], se: [r, b], n: [cx, rect.y], s: [cx, b], w: [rect.x, cy], e: [r, cy],
+      };
+      const dot = 10 / s;
+      for (const zone of order) {
+        const h = handles[zone]!;
+        if (zones.indexOf(zone) < 0) {
+          h.area.style.display = "none";
+          continue;
+        }
+        box(h.area, at[zone]![0] - hit / 2, at[zone]![1] - hit / 2, hit, hit);
+        h.dot.style.width = dot + "px";
+        h.dot.style.height = dot + "px";
+        h.dot.style.borderWidth = 1.5 / s + "px";
+      }
+    },
+  };
+}

package/src/services/design/bridge/bridge-transform-style.ts

@@ -0,0 +1,78 @@
+import type { TransformBoxValue } from "./bridge-transform-math.ts";
+
+/**
+ * Reading and writing the three inline properties the canvas handles change, on the live
+ * element inside the design frame.
+ *
+ * The box is what the element has *now*: the computed `translate` (so a stylesheet's offset
+ * is extended, not replaced by zero) and the computed `width`/`height`, falling back to the
+ * rendered size where those are not px (`auto` on an inline element). `apply` always starts
+ * from the inline values saved when the gesture began and sets only what changed, so an
+ * untouched `width: auto` stays auto and a revert is exact.
+ *
+ * Shipped as source (`ppm.lib.createTransformStyle`); the two helpers it needs are handed
+ * in, since it may not reference anything in this module.
+ */
+
+export type SavedInlineStyle = Record<string, [string, string]>;
+
+export interface TransformPending {
+  start: TransformBoxValue;
+  box: TransformBoxValue;
+  base: SavedInlineStyle;
+}
+
+export interface TransformStyle {
+  /** `movable` is false when the element's `translate` is not a plain px offset. */
+  measure(el: HTMLElement): { box: TransformBoxValue; movable: boolean };
+  save(el: HTMLElement): SavedInlineStyle;
+  restore(el: HTMLElement, saved: SavedInlineStyle): void;
+  /** The props a gesture from `start` to `box` would write. */
+  props(start: TransformBoxValue, box: TransformBoxValue): Record<string, string>;
+  apply(el: HTMLElement, pending: TransformPending): void;
+}
+
+export function createTransformStyle(
+  win: Window,
+  formatPx: (n: number) => string,
+  parseTranslate: (value: string | null | undefined) => { x: number; y: number } | null,
+): TransformStyle {
+  const PROPS = ["translate", "width", "height"];
+  const px = (v: string, fallback: number): number => (/px$/.test(v) && isFinite(parseFloat(v)) ? parseFloat(v) : fallback);
+
+  function save(el: HTMLElement): SavedInlineStyle {
+    const out: SavedInlineStyle = {};
+    for (const p of PROPS) out[p] = [el.style.getPropertyValue(p), el.style.getPropertyPriority(p)];
+    return out;
+  }
+  function restore(el: HTMLElement, saved: SavedInlineStyle): void {
+    for (const p of PROPS) {
+      const entry = saved[p];
+      if (entry && entry[0]) el.style.setProperty(p, entry[0], entry[1]);
+      else el.style.removeProperty(p);
+    }
+  }
+  function props(start: TransformBoxValue, box: TransformBoxValue): Record<string, string> {
+    const out: Record<string, string> = {};
+    if (box.tx !== start.tx || box.ty !== start.ty) out.translate = formatPx(box.tx) + " " + formatPx(box.ty);
+    if (box.w !== start.w) out.width = formatPx(box.w);
+    if (box.h !== start.h) out.height = formatPx(box.h);
+    return out;
+  }
+  return {
+    measure(el) {
+      const cs = win.getComputedStyle(el);
+      const t = parseTranslate(cs.getPropertyValue("translate") || el.style.getPropertyValue("translate"));
+      const r = el.getBoundingClientRect();
+      return { box: { tx: t ? t.x : 0, ty: t ? t.y : 0, w: px(cs.width, r.width), h: px(cs.height, r.height) }, movable: t !== null };
+    },
+    save,
+    restore,
+    props,
+    apply(el, pending) {
+      restore(el, pending.base);
+      const next = props(pending.start, pending.box);
+      for (const name of Object.keys(next)) el.style.setProperty(name, next[name]!);
+    },
+  };
+}

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

@@ -0,0 +1,201 @@
+import type { BridgeApi } from "./bridge-core.ts";
+import type { TransformZone } from "./bridge-transform-math.ts";
+import type { SavedInlineStyle, TransformPending } from "./bridge-transform-style.ts";
+
+/**
+ * Move and resize inside the design frame.
+ *
+ * With Move on (`transform-mode`) and a target (`transform-target`, the element the parent
+ * selected), the element gets a move area and eight resize handles. A drag restyles it live
+ * (inline `translate`/`width`/`height`, normal priority, so what shows is what a write would
+ * do) and on release posts `transform-commit` — only a proposal: the parent decides, and
+ * answers a refusal with `transform-cancel`, which puts the style back. Arrow keys (Shift for
+ * 10 px), here or forwarded as `transform-nudge`, are coalesced into one proposal 500 ms after
+ * the last key. `pointercancel` and Esc revert.
+ *
+ * Installed before the picker, so these capture listeners on `window` run first and every
+ * event on the handles stops here, before the picker (which would select the handle host) or
+ * the page sees it. Shipped as source, so it may only use `ppm`.
+ */
+export function installTransform(ppm: BridgeApi): void {
+  const win = ppm.win;
+  const doc = ppm.doc;
+  const lib = ppm.lib;
+  const NUDGE_COMMIT_MS = 500;
+  const ALL: TransformZone[] = ["move", "nw", "ne", "sw", "se", "n", "s", "w", "e"];
+  // Without a px translate to extend, only the handles that leave the offset alone work.
+  const SIZE_ONLY: TransformZone[] = ["se", "s", "e"];
+  const { measure, save, restore, props, apply } = lib.createTransformStyle(win, lib.formatPx, lib.parseTranslate);
+
+  let on = false;
+  let scale = 1;
+  let target: { ppmId: number; tag: string } | null = null;
+  let overlay: ReturnType<typeof lib.createTransformOverlay> | null = null;
+  let drag: (TransformPending & { pointerId: number; zone: TransformZone; x: number; y: number; moved: boolean }) | null = null;
+  let nudge: (TransformPending & { timer: number }) | null = null;
+  let lastProposal: { ppmId: number; base: SavedInlineStyle } | null = null;
+  let tick: number | null = null;
+
+  function element(): HTMLElement | null {
+    if (!target) return null;
+    const el = ppm.byId(target.ppmId);
+    return el && el.localName.toLowerCase() === target.tag ? (el as HTMLElement) : null;
+  }
+  const rectOf = (el: Element) => { const r = el.getBoundingClientRect(); return { x: r.left, y: r.top, w: r.width, h: r.height }; };
+
+  let liveQueued = false;
+  let lastLive = "";
+  /** Where the element is now, at most once a frame and only when it changed. */
+  function postLive(): void {
+    liveQueued = false;
+    const el = element();
+    if (!on || !target) return;
+    const p = drag || nudge;
+    const payload = { ppmId: target.ppmId, rect: el ? rectOf(el) : null, box: p ? p.box : el ? measure(el).box : null };
+    const key = JSON.stringify(payload);
+    if (key === lastLive) return;
+    lastLive = key;
+    ppm.post("transform-live", payload);
+  }
+  function draw(): void {
+    const el = on ? element() : null;
+    if (el && !overlay) overlay = lib.createTransformOverlay(doc);
+    if (overlay) overlay.place(el ? rectOf(el) : null, 44 / scale, scale, el && !measure(el).movable ? SIZE_ONLY : ALL);
+    if (liveQueued || !target || !on) return;
+    liveQueued = true;
+    if (typeof win.requestAnimationFrame === "function") win.requestAnimationFrame(postLive);
+    else win.setTimeout(postLive, 16);
+  }
+
+  function propose(p: TransformPending): void {
+    const changed = props(p.start, p.box);
+    if (!target || Object.keys(changed).length === 0) return;
+    lastProposal = { ppmId: target.ppmId, base: p.base };
+    ppm.post("transform-commit", { file: ppm.boot.file, gen: ppm.boot.gen, ppmId: target.ppmId, tag: target.tag, props: changed });
+  }
+  function flushNudge(): void {
+    const done = nudge;
+    nudge = null;
+    if (done) { win.clearTimeout(done.timer); propose(done); }
+  }
+  function revert(): boolean {
+    const el = element();
+    const p = drag || nudge;
+    if (nudge) win.clearTimeout(nudge.timer);
+    drag = null;
+    nudge = null;
+    if (!p) return false;
+    if (el) restore(el, p.base);
+    draw();
+    return true;
+  }
+  function nudgeBy(dx: number, dy: number): void {
+    const el = on && !drag ? element() : null;
+    if (!el) return;
+    if (!nudge) {
+      const m = measure(el);
+      if (!m.movable) return;
+      nudge = { start: m.box, box: { tx: m.box.tx, ty: m.box.ty, w: m.box.w, h: m.box.h }, base: save(el), timer: 0 };
+    }
+    nudge.box.tx += dx;
+    nudge.box.ty += dy;
+    apply(el, nudge);
+    win.clearTimeout(nudge.timer);
+    nudge.timer = win.setTimeout(flushNudge, NUDGE_COMMIT_MS);
+    draw();
+  }
+
+  const onHandles = (event: Event): boolean => on && !!overlay && event.target === overlay.host;
+  const consume = (event: Event): void => {
+    if (event.cancelable) event.preventDefault();
+    event.stopImmediatePropagation();
+  };
+  const listen = (type: string, fn: (event: Event) => void): void => win.addEventListener(type, fn, { capture: true, passive: false });
+
+  listen("pointerdown", (event) => {
+    if (!onHandles(event)) return;
+    consume(event);
+    const e = event as PointerEvent;
+    const el = element();
+    if (!el || drag || (e.pointerType === "mouse" && e.button !== 0)) return;
+    const m = measure(el);
+    const zone = lib.zoneAt(rectOf(el), e.clientX, e.clientY, 44 / scale);
+    if (!zone || (m.movable ? ALL : SIZE_ONLY).indexOf(zone) < 0) return;
+    flushNudge();
+    // Consuming mousedown also cancels the focus it would give this frame; arrow keys need it.
+    win.focus();
+    drag = { start: m.box, box: m.box, base: save(el), pointerId: e.pointerId, zone, x: e.clientX, y: e.clientY, moved: false };
+    try { overlay!.host.setPointerCapture(e.pointerId); } catch (err) { /* capture is a nicety; window listeners still see the drag */ }
+  });
+  /** The drag's own pointer event, consumed; any other event on the handles is consumed too. */
+  const ours = (event: Event): PointerEvent | null => {
+    const mine = !!drag && (event as PointerEvent).pointerId === drag.pointerId;
+    if (mine || onHandles(event)) consume(event);
+    return mine ? (event as PointerEvent) : null;
+  };
+  listen("pointermove", (event) => {
+    const e = ours(event);
+    const el = element();
+    if (!e || !drag || !el) return;
+    drag.box = lib.applyDrag(drag.start, drag.zone, e.clientX - drag.x, e.clientY - drag.y);
+    drag.moved = true;
+    apply(el, drag);
+    draw();
+  });
+  listen("pointerup", (event) => {
+    if (!ours(event) || !drag) return;
+    const done = drag;
+    drag = null;
+    if (done.moved) propose(done);
+    draw();
+  });
+  listen("pointercancel", (event) => { if (ours(event)) revert(); });
+  // Whatever else lands on the handles is theirs too, so neither the picker nor the page acts on it.
+  const swallowed = ["mousedown", "mouseup", "mousemove", "click", "dblclick", "auxclick", "contextmenu",
+    "touchstart", "touchmove", "touchend", "touchcancel", "dragstart", "selectstart"];
+  for (const type of swallowed) listen(type, (event) => { if (onHandles(event)) consume(event); });
+
+  listen("keydown", (event) => {
+    const e = event as KeyboardEvent;
+    if (!on || !target) return;
+    if (e.key === "Escape") {
+      if (revert()) consume(e);
+      return;
+    }
+    const steps: Record<string, [number, number]> = { ArrowLeft: [-1, 0], ArrowRight: [1, 0], ArrowUp: [0, -1], ArrowDown: [0, 1] };
+    const step = steps[e.key];
+    const t = e.target as HTMLElement | null;
+    const editing = !!t && (/^(input|textarea|select)$/i.test(t.tagName || "") || t.isContentEditable === true);
+    if (!step || editing || !element()) return;
+    consume(e);
+    nudgeBy(step[0] * (e.shiftKey ? 10 : 1), step[1] * (e.shiftKey ? 10 : 1));
+  });
+
+  const redraw = (): void => { if (on && target) draw(); };
+  win.addEventListener("scroll", redraw, { capture: true, passive: true });
+  win.addEventListener("resize", redraw, { passive: true });
+
+  ppm.on("transform-mode", (m) => {
+    const next = m.on === true;
+    if (typeof m.scale === "number" && isFinite(m.scale) && m.scale > 0) scale = m.scale;
+    if (!next) revert();
+    on = next;
+    if (tick !== null) win.clearInterval(tick);
+    // Layout can shift under the handles without a scroll or resize (fonts, images, scripts).
+    tick = on ? win.setInterval(redraw, 400) : null;
+    draw();
+  });
+  ppm.on("transform-target", (m) => {
+    const next = typeof m.ppmId === "number" && typeof m.tag === "string" ? { ppmId: m.ppmId, tag: m.tag } : null;
+    if (!next || !target || next.ppmId !== target.ppmId) revert();
+    target = next;
+    draw();
+  });
+  ppm.on("transform-nudge", (m) => { if (typeof m.dx === "number" && typeof m.dy === "number" && isFinite(m.dx + m.dy)) nudgeBy(m.dx, m.dy); });
+  ppm.on("transform-cancel", () => {
+    const el = lastProposal ? ppm.byId(lastProposal.ppmId) : null;
+    if (lastProposal && el) restore(el as HTMLElement, lastProposal.base);
+    lastProposal = null;
+    draw();
+  });
+}

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

@@ -0,0 +1,118 @@
+import type { BridgeApi } from "./bridge-core.ts";
+
+/**
+ * Live tweak values inside the design document.
+ *
+ * `tweak-set` writes each value as an inline custom property on the document element, with
+ * `important` priority so it shows even where the page's own `:root` rule is `!important`;
+ * `tweak-reset` removes them again, which reveals the stylesheet's own value. `tweak-read`
+ * answers `tweak-values` with each variable's computed value plus which kind of readable rule
+ * sets it last (`root`, `conditional` inside an at-rule or a media-limited sheet, `other`
+ * selector, or `unknown` when nothing readable does or a linked sheet the opaque origin
+ * cannot read comes after it). That report is a hint for the panel, never a write decision.
+ *
+ * The parent validates what it sends, and the protocol validates it again, but the frame
+ * re-checks the variable name and the value's shape here too: this code runs next to the
+ * page's scripts, and a malformed value must never reach `setProperty`. The checks mirror
+ * `isSafeTweakValueShape` in `shared/design-tweaks.ts`; shipped as source, this function
+ * cannot import it.
+ */
+export function installTweaks(ppm: BridgeApi): void {
+  const doc = ppm.doc;
+  const win = ppm.win as Window & typeof globalThis;
+  const VAR = /^--[a-zA-Z0-9_-]{1,48}$/;
+  const CHARS = /^[A-Za-z0-9 #.,%()-]{1,64}$/;
+  const FUNCS = /^(rgba?|hsla?|hwb|lab|lch|oklab|oklch|calc|min|max|clamp|var)$/i;
+  const applied: Record<string, true> = {};
+
+  function safeValue(v: unknown): v is string {
+    if (typeof v !== "string" || !CHARS.test(v) || v.trim() !== v || v.indexOf("/*") >= 0 || v.indexOf("*/") >= 0) return false;
+    let depth = 0;
+    for (let i = 0; i < v.length; i++) {
+      if (v[i] === "(") depth++;
+      else if (v[i] === ")" && --depth < 0) return false;
+    }
+    if (depth !== 0) return false;
+    const calls = /([A-Za-z-]*)\(/g;
+    let m: RegExpExecArray | null;
+    while ((m = calls.exec(v))) if (!FUNCS.test(m[1]!)) return false;
+    return true;
+  }
+
+  function vars(list: unknown): string[] {
+    if (!Array.isArray(list)) return [];
+    const out: string[] = [];
+    for (let i = 0; i < list.length && out.length < 24; i++) if (typeof list[i] === "string" && VAR.test(list[i])) out.push(list[i]);
+    return out;
+  }
+
+  const root = (): HTMLElement | null => doc.documentElement as HTMLElement | null;
+
+  /** Last readable declaration of `name`, in sheet order, and what kind of rule holds it. */
+  function winnerOf(name: string): "root" | "conditional" | "other" | "unknown" {
+    let winner: "root" | "conditional" | "other" | "unknown" = "unknown";
+    const sheets = doc.styleSheets;
+    const walk = (rules: CSSRuleList, conditional: boolean): void => {
+      for (let i = 0; i < rules.length; i++) {
+        const rule = rules[i] as CSSRule & { selectorText?: string; style?: CSSStyleDeclaration; cssRules?: CSSRuleList };
+        if (rule.style && typeof rule.selectorText === "string" && rule.style.getPropertyValue(name) !== "") {
+          const sel = rule.selectorText.trim().toLowerCase();
+          winner = conditional ? "conditional" : sel === ":root" || sel === "html" ? "root" : "other";
+        }
+        // Grouping rules (@media, @supports, @layer) and nested style rules.
+        if (rule.cssRules && !rule.style) walk(rule.cssRules, true);
+      }
+    };
+    for (let i = 0; i < sheets.length; i++) {
+      const sheet = sheets[i]!;
+      let rules: CSSRuleList | null = null;
+      try {
+        rules = sheet.cssRules;
+      } catch (e) {
+        // A linked sheet: unreadable from the opaque origin, so whatever came before it may lose.
+        winner = "unknown";
+        continue;
+      }
+      const media = sheet.media && sheet.media.mediaText ? sheet.media.mediaText.trim().toLowerCase() : "";
+      if (rules) walk(rules, media !== "" && media !== "all");
+    }
+    return winner;
+  }
+
+  ppm.on("tweak-set", (m) => {
+    const el = root();
+    const values = m.values;
+    if (!el || !values || typeof values !== "object") return;
+    for (const name of Object.keys(values)) {
+      const value = (values as Record<string, unknown>)[name];
+      if (!VAR.test(name) || !safeValue(value)) continue;
+      el.style.setProperty(name, value, "important");
+      applied[name] = true;
+    }
+  });
+
+  ppm.on("tweak-reset", (m) => {
+    const el = root();
+    if (!el) return;
+    const names = m.vars === undefined ? Object.keys(applied) : vars(m.vars);
+    for (const name of names) {
+      if (!applied[name]) continue;
+      el.style.removeProperty(name);
+      delete applied[name];
+    }
+  });
+
+  ppm.on("tweak-read", (m) => {
+    const el = root();
+    const values: Record<string, string> = {};
+    const winners: Record<string, string> = {};
+    if (el) {
+      const computed = win.getComputedStyle(el);
+      for (const name of vars(m.vars)) {
+        values[name] = String(computed.getPropertyValue(name) || "").trim().slice(0, 200);
+        winners[name] = winnerOf(name);
+      }
+    }
+    ppm.post("tweak-values", { values, winners });
+  });
+}

package/src/services/design/check/design-canvas-check-broker.ts

@@ -0,0 +1,77 @@
+import { randomBytes } from "node:crypto";
+import { resolve } from "node:path";
+import { emitDesignEvent } from "../design-events.ts";
+import type { CanvasCheckReport } from "../../../shared/design-canvas-check.ts";
+
+/**
+ * The server half of the canvas self-check. The design is only ever laid out in a browser
+ * tab, so a check is a round trip: announce `design:check_request` to the clients showing
+ * that design (`/ws/global`), and wait for the first of them to POST its report back.
+ *
+ * A pending request is bound to its project and design; an answer naming any other one is
+ * refused, so a client cannot settle a check it was never asked about. The map is bounded
+ * and every entry leaves it on its own timer, answered or not.
+ */
+
+export const CHECK_TIMEOUT_MS = 20_000;
+export const MAX_PENDING_CHECKS = 32;
+export const NO_CANVAS_MESSAGE =
+  "No open design canvas answered. Open this design's tab in PPM to check the canvas, then call design_check again.";
+
+export type CanvasCheckOutcome = { ok: true; report: CanvasCheckReport } | { ok: false; error: string };
+
+interface Pending {
+  key: string;
+  settle: (outcome: CanvasCheckOutcome) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const fold = (p: string): string => (process.platform === "win32" ? resolve(p).toLowerCase() : resolve(p));
+const keyOf = (projectPath: string, slug: string): string => `${fold(projectPath)}\u0000${slug}`;
+
+export function createCanvasCheckBroker(opts: {
+  timeoutMs?: number;
+  maxPending?: number;
+  announce?: (projectPath: string, slug: string, requestId: string, screenshot: boolean) => void;
+} = {}) {
+  const timeoutMs = opts.timeoutMs ?? CHECK_TIMEOUT_MS;
+  const maxPending = opts.maxPending ?? MAX_PENDING_CHECKS;
+  const announce = opts.announce ?? ((projectPath, slug, requestId, screenshot) =>
+    emitDesignEvent("check_request", { projectPath, slug, requestId, screenshot }));
+  const pending = new Map<string, Pending>();
+
+  function request(projectPath: string, slug: string, options: { screenshot: boolean }): Promise<CanvasCheckOutcome> {
+    if (pending.size >= maxPending) {
+      return Promise.resolve({ ok: false, error: "Too many canvas checks are waiting; try again in a few seconds." });
+    }
+    const requestId = randomBytes(12).toString("base64url");
+    return new Promise<CanvasCheckOutcome>((done) => {
+      const settle = (outcome: CanvasCheckOutcome): void => {
+        const entry = pending.get(requestId);
+        if (!entry) return;
+        clearTimeout(entry.timer);
+        pending.delete(requestId);
+        done(outcome);
+      };
+      const timer = setTimeout(() => settle({ ok: false, error: NO_CANVAS_MESSAGE }), timeoutMs);
+      pending.set(requestId, { key: keyOf(projectPath, slug), settle, timer });
+      try {
+        announce(projectPath, slug, requestId, options.screenshot);
+      } catch (e) {
+        settle({ ok: false, error: `Could not reach the canvas: ${(e as Error).message}` });
+      }
+    });
+  }
+
+  /** Settles a pending check with a client's report; false when none matches this design. */
+  function resolveCheck(projectPath: string, slug: string, requestId: string, report: CanvasCheckReport): boolean {
+    const entry = pending.get(requestId);
+    if (!entry || entry.key !== keyOf(projectPath, slug)) return false;
+    entry.settle({ ok: true, report });
+    return true;
+  }
+
+  return { request, resolveCheck, pendingCount: () => pending.size };
+}
+
+export const canvasCheckBroker = createCanvasCheckBroker();