@penpair/web 0.1.3 → 0.3.0

package/examples/reflection-browser/README.md

@@ -0,0 +1,49 @@
+# Real browser comparison starter
+
+Copy `capture.mjs` and `provider.mjs` into the adopting project, or use the shipped copies under `node_modules/@penpair/web/examples/reflection-browser/`. This is a starting provider for the existing `ImplementationProvider.runCase` contract. It does not install a browser, change your application or approve a design.
+
+Use your project's pinned Playwright and matching browser installation. A copied provider resolves `@penpair/core` from its project; declare it at the same version as the other Penpair packages, or pass its three IO helpers explicitly as `io`. Keep all Penpair versions aligned. Do not use the fixture hooks as application evidence.
+
+In your trusted project provider:
+
+```js
+import { chromium } from 'playwright'; // the adopter's pinned version
+import { createBrowserProvider } from './provider.mjs';
+import { hooks } from './project-hooks.mjs';
+export async function runCase(test) {
+  const browser = await chromium.launch();
+  try {
+    return await createBrowserProvider({ browser, baseURL: 'http://127.0.0.1:5173', projectRoot: process.cwd(), hooks }).runCase(test);
+  } finally { await browser.close(); }
+}
+```
+
+Required hooks:
+
+| Hook | Contract |
+| --- | --- |
+| `route(test)` | Return the exact intended route; must match `test.route` on the configured app origin. |
+| `setup(page, test)` | Explicitly establish application fixture, theme and state using your app's controls or test APIs. |
+| `observe(page, test)` | Independently read **actual** `{theme,state,fixture}` from rendered DOM/application evidence. Never return the requested fields directly. |
+| `captureRoot(test)` | Return one unique CSS selector for the design region. |
+| `expectedFonts(test)` | Return explicit webfont `{family,weight,style}` faces; each must be observed loaded in `document.fonts`. System-font fallback cannot stand in for webfont evidence. |
+| `prepareCapture(page, test, root)` | Optional explicit scroll/sticky setup after automatic scroll. Use it when a shell would cover the root. Occlusion checks refuse covered captures; the starter does not hide your shell. |
+
+The provider measures the viewport and device scale (default 1), waits for font faces/weights and three equal root boxes, parks the pointer outside the viewport, checks hover and sampled occlusion, and rounds the document box **outward to whole CSS pixels**. It captures that clip against the full document so viewport trimming cannot silently remove a pixel. Root dimensions must match the design case. It never resizes a screenshot to improve the comparison. Metadata retains root/clip, browser version, actual fonts, scroll, pointer and layout evidence. Occlusion checks sample points; inspect images for unsampled overlays and animation differences.
+
+The comparison uses exact decoded RGBA pixel differences in a browser canvas. The numeric ratio is evidence; inspect image differences and retain `owner-review-required`. Baseline hashes, paths and PNG dimensions are still independently checked by the adapter. Old schema-1 providers remain readable; this starter requires its complete capture metadata.
+
+```sh
+penpair reflection plan --map design/implementation-cases.json
+penpair reflection check --map design/implementation-cases.json --provider design/browser/run.mjs
+```
+
+These commands require registered `@penpair/reflection-check` and current exact approved design cases. See [adapter setup](../../docs/adapters.md). `runCase` must close its browser/context as above. Do not store credentials in hooks or evidence.
+
+## Local plumbing trial
+
+From this repository, run `pnpm smoke:browser` using a locally installed pinned Playwright and browser. Optional `PENPAIR_PLAYWRIGHT_MODULE` selects an absolute module path; `PENPAIR_BROWSER_EXECUTABLE` or `PENPAIR_BROWSER_CHANNEL` selects an existing test browser. No absolute machine paths are committed to the example.
+
+The script starts/stops a loopback fixture, captures desktop/mobile × light/dark × loaded/empty, tests wrong theme, missing face/weight, delayed font loading, scale mismatch, hover and sticky occlusion, and verifies unchanged baseline bytes. Its browser references are deliberately **unapproved synthetic fixtures**. They exercise plumbing; they are not Penpot acceptance or owner-approved design baselines.
+
+The fixture's Abel Regular font is redistributed under [SIL OFL](fixture/OFL.txt), retrieved from [Google Fonts](https://github.com/google/fonts/tree/main/ofl/abel), SHA-256 `8809dcad25318225052f88333e208c5aad4adcb7b2c934c135735ec19aa410b4`. Browser APIs follow [Playwright screenshot documentation](https://playwright.dev/docs/api/class-page#page-screenshot) and [font-loading evidence](https://developer.mozilla.org/en-US/docs/Web/API/FontFaceSet).

package/examples/reflection-browser/capture.mjs

@@ -0,0 +1,311 @@
+/** Browser plumbing only. Project hooks supply real setup and independent DOM readback. */
+export function outwardClip(box) {
+  if (
+    !box ||
+    ![
+      box.x,
+      box.y,
+      box.width,
+      box.height,
+    ].every(Number.isFinite) ||
+    box.x < 0 ||
+    box.y < 0 ||
+    box.width <= 0 ||
+    box.height <= 0
+  ) {
+    throw new Error("Capture root needs a finite, positive document box");
+  }
+  const x = Math.floor(box.x);
+  const y = Math.floor(box.y);
+  return {
+    x,
+    y,
+    width: Math.ceil(box.x + box.width) - x,
+    height: Math.ceil(box.y + box.height) - y,
+  };
+}
+export async function captureCase(page, test, hooks, { timeoutMs = 10000 } = {}) {
+  for (const name of [
+    "setup",
+    "observe",
+    "captureRoot",
+    "expectedFonts",
+  ]) {
+    if (typeof hooks[name] !== "function") {
+      throw new Error(`Required project hook: ${name}`);
+    }
+  }
+  page.setDefaultTimeout(timeoutMs);
+  await hooks.setup(page, test);
+  const selector = await hooks.captureRoot(test);
+  const root = page.locator(selector);
+  if ((await root.count()) !== 1) {
+    throw new Error("Capture root must resolve uniquely");
+  }
+  const expectedFonts = await hooks.expectedFonts(test);
+  if (
+    !Array.isArray(expectedFonts) ||
+    !expectedFonts.length ||
+    expectedFonts.some((font) => !font.family || !font.weight || !font.style)
+  ) {
+    throw new Error("Explicit font family/weight/style evidence is required");
+  }
+  await page.waitForFunction(
+    (fonts) => {
+      const clean = (value) => value.replace(/["']/g, "");
+      return (
+        document.fonts.status === "loaded" &&
+        fonts.every((wanted) =>
+          [
+            ...document.fonts,
+          ].some(
+            (face) =>
+              clean(face.family) === wanted.family &&
+              face.weight === wanted.weight &&
+              face.style === wanted.style &&
+              face.status === "loaded",
+          ),
+        )
+      );
+    },
+    expectedFonts,
+    {
+      timeout: timeoutMs,
+    },
+  );
+  await root.scrollIntoViewIfNeeded();
+  if (hooks.prepareCapture) {
+    await hooks.prepareCapture(page, test, root);
+  }
+  // Observe three complete stable boxes across animation frames, after scroll/sticky layout.
+  const rootBox = await root.evaluate(async (element, timeout) => {
+    let previous;
+    let equal = 0;
+    const deadline = performance.now() + timeout;
+    for (let count = 0; count < 120; count++) {
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(
+          () => reject(new Error("Capture layout deadline exceeded")),
+          Math.max(1, deadline - performance.now()),
+        );
+        requestAnimationFrame(() => {
+          clearTimeout(timer);
+          resolve();
+        });
+      });
+      const rect = element.getBoundingClientRect();
+      const box = {
+        x: rect.x + scrollX,
+        y: rect.y + scrollY,
+        width: rect.width,
+        height: rect.height,
+      };
+      const current = JSON.stringify(box);
+      equal = current === previous ? equal + 1 : 1;
+      if (equal === 3) {
+        return box;
+      }
+      previous = current;
+    }
+    throw new Error("Capture root did not settle");
+  }, timeoutMs);
+  const clip = outwardClip(rootBox);
+  const occlusion = await root.evaluate((element) => {
+    const r = element.getBoundingClientRect();
+    const left = Math.max(0, r.left);
+    const top = Math.max(0, r.top);
+    const right = Math.min(innerWidth, r.right);
+    const bottom = Math.min(innerHeight, r.bottom);
+    if (right - left < 2 || bottom - top < 2) {
+      throw new Error("Capture root has no observable viewport area");
+    }
+    const points = [
+      [
+        left + 1,
+        top + 1,
+      ],
+      [
+        right - 1,
+        top + 1,
+      ],
+      [
+        (left + right) / 2,
+        (top + bottom) / 2,
+      ],
+      [
+        left + 1,
+        bottom - 1,
+      ],
+      [
+        right - 1,
+        bottom - 1,
+      ],
+    ];
+    return {
+      samples: points.length,
+      blocked: points.filter(([x, y]) => {
+        const hit = document.elementFromPoint(x, y);
+        return !hit || !element.contains(hit);
+      }).length,
+    };
+  });
+  if (occlusion.blocked) {
+    throw new Error(
+      "Capture root is occluded by sticky shell or external content; use prepareCapture to establish the intended scroll state",
+    );
+  }
+  // Move outside the viewport; a corner inside a full-screen root is not a safe parking place.
+  await page.mouse.move(-10, -10);
+  const pointer = await root.evaluate((element) => ({
+    x: -10,
+    y: -10,
+    outsideRoot: !element.matches(":hover"),
+    hoveredControls: element.querySelectorAll(
+      "button:hover,a:hover,input:hover,select:hover,textarea:hover,[role=button]:hover",
+    ).length,
+  }));
+  if (!pointer.outsideRoot || pointer.hoveredControls !== 0) {
+    throw new Error("Hover contamination in capture root");
+  }
+  const observed = await hooks.observe(page, test);
+  const measured = await page.evaluate(() => ({
+    viewport: {
+      width: innerWidth,
+      height: innerHeight,
+    },
+    deviceScaleFactor: devicePixelRatio,
+    scroll: {
+      x: scrollX,
+      y: scrollY,
+    },
+    fonts: [
+      ...document.fonts,
+    ]
+      .filter((face) => face.status === "loaded")
+      .map((face) => ({
+        family: face.family.replace(/["']/g, ""),
+        weight: face.weight,
+        style: face.style,
+        status: face.status,
+      })),
+  }));
+  const actual = {
+    viewport: measured.viewport,
+    theme: observed.theme,
+    state: observed.state,
+    fixture: observed.fixture,
+  };
+  const desired = {
+    viewport: test.intent.viewport,
+    theme: test.intent.theme,
+    state: test.intent.state,
+    fixture: test.intent.fixture,
+  };
+  if (JSON.stringify(actual) !== JSON.stringify(desired)) {
+    throw new Error("Observed browser state/theme/fixture/viewport differs from requested case");
+  }
+  if (
+    clip.width !== desired.viewport.width ||
+    clip.height !== desired.viewport.height ||
+    measured.deviceScaleFactor !== test.baseline.scale
+  ) {
+    throw new Error(
+      "Rounded root dimensions or device scale differ from design case; do not resize the image",
+    );
+  }
+  const screenshot = await page.screenshot({
+    type: "png",
+    fullPage: true,
+    clip,
+    scale: "device",
+    animations: "disabled",
+    caret: "hide",
+  });
+  const after = await hooks.observe(page, test);
+  const afterBox = await root.boundingBox();
+  if (
+    JSON.stringify(after) !== JSON.stringify(observed) ||
+    !afterBox ||
+    JSON.stringify(
+      outwardClip({
+        ...afterBox,
+        x: afterBox.x + measured.scroll.x,
+        y: afterBox.y + measured.scroll.y,
+      }),
+    ) !== JSON.stringify(clip)
+  ) {
+    throw new Error("Browser source changed during capture");
+  }
+  return {
+    screenshot,
+    observed: actual,
+    fonts: [
+      ...new Set(measured.fonts.map((font) => font.family)),
+    ],
+    fontsReady: true,
+    capture: {
+      schemaVersion: 1,
+      root: selector,
+      rootBox,
+      clip,
+      rounding: "outward-css-pixels",
+      deviceScaleFactor: measured.deviceScaleFactor,
+      browser: {
+        name: page.context().browser().browserType().name(),
+        version: page.context().browser().version(),
+      },
+      fonts: measured.fonts,
+      pointer,
+      occlusion,
+      scroll: measured.scroll,
+      layoutSamples: 3,
+    },
+  };
+}
+
+/** Exact decoded RGBA pixel difference, without resizing or threshold-based approval. */
+export async function comparePng(page, baseline, screenshot) {
+  return page.evaluate(
+    async (images) => {
+      const decode = async (base64) => {
+        const image = new Image();
+        image.src = "data:image/png;base64," + base64;
+        await image.decode();
+        return image;
+      };
+      const [before, after] = await Promise.all(images.map(decode));
+      if (before.width !== after.width || before.height !== after.height) {
+        throw new Error("Comparison dimensions differ");
+      }
+      const canvas = document.createElement("canvas");
+      canvas.width = before.width;
+      canvas.height = before.height;
+      const context = canvas.getContext("2d", {
+        willReadFrequently: true,
+      });
+      context.drawImage(before, 0, 0);
+      const a = context.getImageData(0, 0, canvas.width, canvas.height).data;
+      context.clearRect(0, 0, canvas.width, canvas.height);
+      context.drawImage(after, 0, 0);
+      const b = context.getImageData(0, 0, canvas.width, canvas.height).data;
+      let changed = 0;
+      for (let index = 0; index < a.length; index += 4) {
+        if (
+          [
+            0,
+            1,
+            2,
+            3,
+          ].some((channel) => a[index + channel] !== b[index + channel])
+        ) {
+          changed++;
+        }
+      }
+      return changed / (canvas.width * canvas.height);
+    },
+    [
+      baseline.toString("base64"),
+      screenshot.toString("base64"),
+    ],
+  );
+}

package/examples/reflection-browser/fixture/OFL.txt

@@ -0,0 +1,93 @@
+Copyright (c) 2011, Matthew Desmond (http://www.madtype.com | mattdesmond@gmail.com),with Reserved Font Name Abel.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/examples/reflection-browser/fixture/index.html

@@ -0,0 +1,11 @@
+<!doctype html><html lang="en"><meta charset="utf-8"><title>Comparison capture fixture</title>
+<style>
+@font-face{font-family:Fixture;src:url('./Abel-Regular.ttf');font-style:normal;font-weight:400;font-display:swap}
+*{box-sizing:border-box}html,body{margin:0;font-family:Fixture,sans-serif}header{height:64px;position:sticky;top:0;background:#163e3c;color:white;padding:20px;z-index:2}main{position:relative;margin-left:.25px;width:calc(100vw - .5px);height:calc(100vh - .5px);padding:30px;background:#f2f5f3;color:#152c2a}html[data-theme=dark] main{background:#152c2a;color:#f2f5f3}button{font:inherit;padding:12px;border:1px solid #71928a;background:transparent;color:inherit}button:hover{background:magenta}h1{font-size:32px;font-weight:400;margin:0 0 16px}section{padding:20px 0}p{margin:12px 0}
+</style>
+<header>Application shell — excluded from capture</header><main id="capture"><h1>Workspace</h1><p id="state"></p><section><button>New item</button><p id="items"></p></section></main>
+<script>
+const query=new URLSearchParams(location.search),theme=query.get('theme')||'light',state=query.get('state')||'loaded';
+document.documentElement.dataset.theme=theme;document.querySelector('main').dataset.state=state;document.querySelector('main').dataset.fixture=state==='empty'?'no-items':'sample-items';
+document.querySelector('#state').textContent=state==='empty'?'Your workspace is ready for its first item.':'Recent activity';document.querySelector('#items').textContent=state==='empty'?'No items yet.':'First item · Second item · Third item';
+</script></html>

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};