@penpair/web 0.2.0 → 0.3.0

package/examples/reflection-browser/fixture-hooks.mjs

@@ -0,0 +1,24 @@
+export const hooks = {
+  route: (test) => test.route,
+  async setup(page) {
+    await page.locator("#capture").scrollIntoViewIfNeeded();
+  },
+  async prepareCapture(page) {
+    await page.evaluate(() => window.scrollTo(0, 0));
+  },
+  async observe(page) {
+    return page.evaluate(() => ({
+      theme: document.documentElement.dataset.theme,
+      state: document.querySelector("main").dataset.state,
+      fixture: document.querySelector("main").dataset.fixture,
+    }));
+  },
+  captureRoot: () => "#capture",
+  expectedFonts: () => [
+    {
+      family: "Fixture",
+      weight: "400",
+      style: "normal",
+    },
+  ],
+};

package/examples/reflection-browser/provider.mjs

@@ -0,0 +1,90 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { captureCase, comparePng } from "./capture.mjs";
+
+/** Pass a browser from the adopting project's pinned Playwright; this example installs nothing. */
+export function createBrowserProvider({
+  browser,
+  baseURL,
+  projectRoot,
+  hooks,
+  deviceScaleFactor = 1,
+  timeoutMs = 10000,
+  io,
+}) {
+  if (!browser || !projectRoot || !baseURL || typeof hooks?.route !== "function") {
+    throw new Error("Browser, project root, app origin and explicit route hook required");
+  }
+  return {
+    async runCase(test) {
+      const { atomicWriteFile, resolveProjectInput, resolveProjectOutput } =
+        io ?? (await import("@penpair/core"));
+      const target = new URL(await hooks.route(test), baseURL);
+      const expected = new URL(test.route, baseURL);
+      if (target.origin !== new URL(baseURL).origin || target.href !== expected.href) {
+        throw new Error(
+          "Route hook must open the exact intended route on the configured app origin",
+        );
+      }
+      const before = await readFile(await resolveProjectInput(projectRoot, test.baseline.path));
+      const hash = createHash("sha256").update(before).digest("hex");
+      if (hash !== test.baseline.sha256) {
+        throw new Error("Baseline hash changed");
+      }
+      const context = await browser.newContext({
+        viewport: test.intent.viewport,
+        deviceScaleFactor,
+      });
+      try {
+        const page = await context.newPage();
+        await page.goto(target.href, {
+          waitUntil: "domcontentloaded",
+          timeout: timeoutMs,
+        });
+        const capture = await captureCase(page, test, hooks, {
+          timeoutMs,
+        });
+        if (page.url() !== target.href) {
+          throw new Error("Application navigated away from the intended route");
+        }
+        const diffPixelRatio = await comparePng(page, before, capture.screenshot);
+        const screenshot = path.join(
+          ".penpair/reflection",
+          createHash("sha256")
+            .update(test.id + ":" + test.setup)
+            .digest("hex") + ".png",
+        );
+        const output = await resolveProjectOutput(projectRoot, screenshot);
+        if (output === (await resolveProjectInput(projectRoot, test.baseline.path))) {
+          throw new Error("Capture cannot overwrite its baseline");
+        }
+        await mkdir(path.dirname(output), {
+          recursive: true,
+        });
+        await atomicWriteFile(output, capture.screenshot, {
+          replace: true,
+        });
+        return {
+          schemaVersion: 1,
+          id: test.id,
+          route: test.route,
+          setup: test.setup,
+          baselineHash: hash,
+          observed: capture.observed,
+          fonts: capture.fonts,
+          fontsReady: capture.fontsReady,
+          screenshot,
+          diffPixelRatio,
+          capture: capture.capture,
+          provider: {
+            name: "penpair-browser-starter-rgba-exact",
+            version: "1",
+          },
+        };
+      } finally {
+        await context.close();
+      }
+    },
+  };
+}

package/examples/reflection-browser/serve.mjs

@@ -0,0 +1,37 @@
+import { createServer } from "node:http";
+import { readFile } from "node:fs/promises";
+const files = new Map([
+  [
+    "/",
+    [
+      "index.html",
+      "text/html",
+    ],
+  ],
+  [
+    "/Abel-Regular.ttf",
+    [
+      "Abel-Regular.ttf",
+      "font/ttf",
+    ],
+  ],
+]);
+const server = createServer(async (request, response) => {
+  const entry = files.get(new URL(request.url, "http://localhost").pathname);
+  if (!entry) {
+    response.writeHead(404).end();
+    return;
+  }
+  try {
+    response.writeHead(200, {
+      "Content-Type": entry[1],
+      "Cache-Control": "no-store",
+    });
+    response.end(await readFile(new URL(`fixture/${entry[0]}`, import.meta.url)));
+  } catch {
+    response.writeHead(500).end();
+  }
+});
+server.listen(Number(process.env.PENPAIR_EXAMPLE_PORT ?? 4174), "127.0.0.1", () =>
+  console.log(`Browser fixture: http://127.0.0.1:${server.address().port}`),
+);

package/examples/theme-preview/README.md

@@ -0,0 +1,21 @@
+# Projected theme scratch example
+
+Generate independent light/dark artifacts with `penpair marwes tokens preview --from SNAPSHOT --theme NAME --out NEW_FILE`. The selected theme is resolved offline; no active flags are changed. Inspect each artifact's `complete`, `unknowns`, source hash, theme and ordered sets first.
+
+These reviewed example bodies accept literal `CFG.preview` JSON, `CFG.color` token name, `CFG.rootId` and `CFG.marker`. Each target must already be a confirmed disposable, owned scratch root with `getSharedPluginData("penpair","owner") === marker`. Do not adopt an existing design root implicitly. Prepare separate light and dark roots and inspect/pin the source before any apply.
+
+Use the normal `prepareFileScript`/`runFileScript` API with:
+
+```js
+const prepared = await prepareFileScript(projectRoot, 'preview/apply.js', {
+ page: 'Scratch', include: ['preview/helpers.js'],
+ inspect: 'preview/inspect.js', readback: 'preview/readback.js',
+ params: { preview: JSON.stringify(previewArtifact), color: 'surface', rootId, marker },
+});
+await runFileScript(client, prepared); // review inspection first
+// Within the authorized scratch scope, apply once with a private journal and independently verify.
+```
+
+The example sets one opaque projected fill directly and records `kind`, source hash, theme/sets and projected property provenance under a separate `projection` metadata key. This **removes any fill binding** and must not be reported as native per-frame theme binding. Typography/spacing/radius bindings remain real, independently inspected bindings. The example refuses unsupported colors and partial projections; it does not guess gradients, opacity or token semantics.
+
+After applying, compare catalog definitions/order, global theme/set selections and unrelated objects against the pinned pre-write inspection. Look at two stable exports. Repeating must preserve IDs, bindings outside fill and the same provenance. Live acceptance of this example remains pending; it is covered by sandbox-body tests only.

package/examples/theme-preview/apply.js

@@ -0,0 +1,8 @@
+// penpair: write
+// penpair: idempotent
+const input = previewInput();
+if (!CFG.inspection || CFG.inspection.rootId !== input.root.id || CFG.inspection.provenance !== input.provenance || CFG.inspection.preserved !== input.preserved) throw new Error("Projection inputs or preserved bindings changed since inspection");
+const fills = [{ fillColor: input.value, fillOpacity: 1 }];
+if (JSON.stringify(input.root.fills) !== JSON.stringify(fills)) input.root.fills = fills;
+if (input.root.getSharedPluginData("penpair", "projection") !== input.provenance) input.root.setSharedPluginData("penpair", "projection", input.provenance);
+return {ok:true,rootId:input.root.id};

package/examples/theme-preview/helpers.js

@@ -0,0 +1,12 @@
+// penpair: read
+const previewInput = () => {
+ const preview = JSON.parse(CFG.preview);
+ if (preview.schemaVersion !== 1 || preview.kind !== "projected-theme-preview" || preview.nativeBindings !== false || !/^[a-f0-9]{64}$/.test(preview.sourceHash) || !preview.complete || !Array.isArray(preview.resolved) || !Array.isArray(preview.unknowns) || preview.unknowns.length) throw new Error("Complete explicit projected preview required");
+ const matches = preview.resolved.filter(token => token.name === CFG.color && token.type === "color");
+ if (matches.length !== 1 || typeof matches[0].value !== "string" || !/^#[a-f0-9]{6}$/i.test(matches[0].value)) throw new Error("Example requires one literal opaque hex color");
+ const root = penpot.currentPage.getShapeById(CFG.rootId);
+ if (!root || !CFG.marker || root.getSharedPluginData("penpair", "owner") !== CFG.marker) throw new Error("Authorized owned scratch root required");
+ const preserved = JSON.stringify(Object.fromEntries(Object.entries(root.tokens || {}).filter(([property]) => property !== "fill")));
+ const provenance = JSON.stringify({ kind: preview.kind, sourceHash: preview.sourceHash, theme: preview.theme, sets: preview.sets, projectedProperties: { fill: CFG.color }, preservedBindings: preserved, nativeBindings: false });
+ return { root, value: matches[0].value, provenance, preserved };
+};

package/examples/theme-preview/inspect.js

@@ -0,0 +1,3 @@
+// penpair: read
+const input = previewInput();
+return {ok:true,rootId:input.root.id,desiredColor:input.value,provenance:input.provenance,preserved:input.preserved};

package/examples/theme-preview/readback.js

@@ -0,0 +1,7 @@
+// penpair: read
+const input = previewInput();
+const fill = input.root.fills && input.root.fills[0];
+return {ok:true,rootId:input.root.id,verification:{
+ expected:{color:input.value,opacity:1,fillBinding:null,provenance:input.provenance},
+ actual:{color:fill && fill.fillColor,opacity:fill && fill.fillOpacity,fillBinding:input.root.tokens.fill || null,provenance:input.root.getSharedPluginData("penpair","projection")}
+}};

package/examples/trials/hold-inspect.js

@@ -0,0 +1,5 @@
+// penpair: read
+if (penpot.currentFile.id !== CFG.fileId || penpot.currentPage.id !== CFG.pageId) throw new Error("Confirm the owner-authorized scratch file/page IDs");
+if (penpot.currentPage.root.children.length !== 0) throw new Error("Use the dedicated empty scratch page for the writer exercise");
+if (typeof CFG.marker !== "string" || !CFG.marker) throw new Error("A fresh trial marker is required");
+return { ok: true, fileId: penpot.currentFile.id, pageId: penpot.currentPage.id, children: 0 };

package/examples/trials/hold-readback.js

@@ -0,0 +1,8 @@
+// penpair: read
+const raw = penpot.currentFile.getSharedPluginData("penpair", "trial-hold-" + CFG.marker);
+let record = null;
+try { record = raw ? JSON.parse(raw) : null; } catch {}
+return { ok: true, verification: {
+  expected: { fileId: CFG.fileId, pageId: CFG.pageId, children: 0, marker: CFG.marker, holdMs: Number(CFG.holdMs), state: "complete" },
+  actual: { fileId: penpot.currentFile.id, pageId: penpot.currentPage.id, children: penpot.currentPage.root.children.length, marker: record?.marker ?? null, holdMs: record?.holdMs ?? null, state: record?.state ?? null }
+} };

package/examples/trials/hold-writer.js

@@ -0,0 +1,16 @@
+// penpair: write
+// penpair: idempotent
+const milliseconds = Number(CFG.holdMs);
+if (!Number.isInteger(milliseconds) || milliseconds < 1 || milliseconds > 30000) throw new Error("holdMs must be 1–30000");
+if (!CFG.inspection || penpot.currentFile.id !== CFG.inspection.fileId || penpot.currentPage.id !== CFG.inspection.pageId || penpot.currentPage.root.children.length !== 0) throw new Error("Scratch source changed before the hold");
+if (!CFG.marker) throw new Error("A fresh trial marker is required");
+const key = "trial-hold-" + CFG.marker;
+const prior = penpot.currentFile.getSharedPluginData("penpair", key);
+if (prior) throw new Error("Trial marker already exists; inspect it before recovery");
+const record = { schemaVersion: 1, state: "holding", marker: CFG.marker, fileId: CFG.fileId, pageId: CFG.pageId, holdMs: milliseconds };
+penpot.currentFile.setSharedPluginData("penpair", key, JSON.stringify(record));
+// This deliberate delay opens a controlled contention window. It is not layout settling.
+// The operation runner owns the advisory writer lease; this body changes no design objects.
+await new Promise(resolve => setTimeout(resolve, milliseconds));
+penpot.currentFile.setSharedPluginData("penpair", key, JSON.stringify({ ...record, state: "complete" }));
+return { ok: true, heldMilliseconds: milliseconds };

package/examples/trials/recovery-build.js

@@ -0,0 +1,23 @@
+// penpair: write
+// penpair: idempotent
+if (!CFG.inspection || penpot.currentFile.id !== CFG.fileId || penpot.currentPage.id !== CFG.pageId) throw new Error("Scratch identity changed");
+if (JSON.stringify(penpot.currentPage.root.children.map(shape => shape.id).sort()) !== JSON.stringify(CFG.inspection.rootIds)) throw new Error("Scratch source changed before the recovery exercise");
+if (CFG.inspection.existingId) {
+  const frame = penpot.currentPage.getShapeById(CFG.inspection.existingId);
+  if (!frame || frame.name !== CFG.name || frame.width !== 160 || frame.height !== 80 || frame.getSharedPluginData("penpair", "trial") !== CFG.marker) throw new Error("Owned frame has an unexplained third state");
+  return { ok: true, alreadyBuilt: true, frameId: frame.id };
+}
+let frame = null, configured = false;
+try {
+  frame = penpot.createBoard();
+  frame.name = CFG.name;
+  frame.setSharedPluginData("penpair", "trial", CFG.marker);
+  frame.fills = [];
+  frame.resize(160, 80);
+  configured = true;
+} finally {
+  if (!configured && frame) frame.remove();
+}
+// Deliberate fault: the owned write exists, but the normal acknowledgment is not returned.
+if (CFG.failAfterWrite === "true") throw new Error("Controlled trial failure after the owned write; inspect before explicit resume");
+return { ok: true, frameId: frame.id };

package/examples/trials/recovery-inspect.js

@@ -0,0 +1,10 @@
+// penpair: read
+if (penpot.currentFile.id !== CFG.fileId || penpot.currentPage.id !== CFG.pageId) throw new Error("Confirm the authorized scratch file/page IDs");
+if (typeof CFG.name !== "string" || !CFG.name || typeof CFG.marker !== "string" || !CFG.marker) throw new Error("A unique trial name and ownership marker are required");
+const matches = penpot.currentPage.root.children.filter(shape => shape.name === CFG.name);
+if (matches.length > 1) throw new Error("Recovery trial name is ambiguous");
+const frame = matches[0];
+const marked = penpot.currentPage.root.children.filter(shape => typeof shape.getSharedPluginData === "function" && shape.getSharedPluginData("penpair", "trial") === CFG.marker);
+if (marked.length > 1 || (marked.length === 1 && marked[0] !== frame)) throw new Error("Trial ownership marker moved or duplicated; inspect before recovery");
+if (frame && (typeof frame.getSharedPluginData !== "function" || frame.getSharedPluginData("penpair", "trial") !== CFG.marker)) throw new Error("Existing frame is not this trial's owned object");
+return { ok: true, existingId: frame?.id ?? null, width: frame?.width ?? null, height: frame?.height ?? null, rootIds: penpot.currentPage.root.children.map(shape => shape.id).sort() };

package/examples/trials/recovery-readback.js

@@ -0,0 +1,7 @@
+// penpair: read
+const matches = penpot.currentPage.root.children.filter(shape => shape.name === CFG.name);
+const frame = matches.length === 1 ? matches[0] : null;
+return { ok: true, frameId: frame?.id ?? null, verification: {
+  expected: { fileId: CFG.fileId, pageId: CFG.pageId, name: CFG.name, marker: CFG.marker, width: 160, height: 80 },
+  actual: frame ? { fileId: penpot.currentFile.id, pageId: penpot.currentPage.id, name: frame.name, marker: typeof frame.getSharedPluginData === "function" ? frame.getSharedPluginData("penpair", "trial") : null, width: frame.width, height: frame.height } : { missingOrAmbiguous: true }
+} };

package/examples/trials/wrong-file-read.js

@@ -0,0 +1,3 @@
+// penpair: read
+// A benign read: the configured same-execution file guard must block this body on the other file.
+return { ok: true, actualFileId: penpot.currentFile.id, actualPageId: penpot.currentPage.id };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/web",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The penpair command for Penpot on the web (design.penpot.app or your team's own): guided setup, a safe write protocol, skills for AI agents. Includes everything in @penpair/core.",
   "license": "MIT",
   "repository": {
@@ -32,6 +32,7 @@
   "files": [
     "dist",
     "docs",
+    "examples",
     "LICENSE",
     "README.md"
   ],
@@ -47,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@penpair/core": "0.2.0"
+    "@penpair/core": "0.3.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",