@penpair/web 0.3.6 → 0.4.0

package/examples/design-release-maps/journey.json

@@ -0,0 +1,187 @@
+{
+  "schemaVersion": 1,
+  "kind": "journey-map",
+  "id": "reset-password-journey",
+  "title": "Reset password",
+  "goal": "Request password-reset instructions and understand the next step.",
+  "sources": [
+    {
+      "id": "sample-brief",
+      "kind": "other",
+      "path": "examples/design-release-maps/sample-source.md",
+      "sha256": "ab97f0a30f066e9a9f2689d1624608ea91287751cbc6a613542c0e97de187a96"
+    }
+  ],
+  "nodes": [
+    {
+      "id": "address-entry",
+      "label": "Enter email",
+      "kind": "screen",
+      "origin": "observed",
+      "sourceIds": [
+        "sample-brief"
+      ],
+      "requirementIds": [
+        "reset-entry"
+      ],
+      "summary": "Provide an address for reset instructions.",
+      "description": "The synthetic brief includes an address-entry screen. No Penpot frame or application has been inspected. Field validation, submission behavior and the final wording still require project evidence or review.",
+      "icon": "screen"
+    },
+    {
+      "id": "confirmation",
+      "label": "Check your email",
+      "kind": "screen",
+      "origin": "observed",
+      "sourceIds": [
+        "sample-brief"
+      ],
+      "requirementIds": [
+        "reset-confirmation"
+      ],
+      "summary": "Explain the next step after the request.",
+      "description": "The synthetic brief includes a confirmation screen. Its success transition and response messaging are proposed, not observed. Confirm the actual request and account-disclosure policy before implementing this state.",
+      "icon": "screen"
+    },
+    {
+      "id": "recoverable-error",
+      "label": "Retry request",
+      "kind": "state",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-error-retry"
+      ],
+      "summary": "Keep the address and offer a retry.",
+      "description": "Proposed recovery preserves the entered address after a failed request, explains the failure and allows another attempt. No inspected design or implementation establishes this behavior yet. Review it, then verify a real failure and retry.",
+      "icon": "action"
+    },
+    {
+      "id": "expiry-policy",
+      "label": "Request policy",
+      "kind": "decision",
+      "origin": "unknown",
+      "requirementIds": [
+        "reset-expiry"
+      ],
+      "summary": "Decide expiry and repeat-request behavior.",
+      "description": "The source provides no expiry, repeat-request or disclosure policy. Obtain the actual product and service contract before deciding what the interface should say or do. This is an unresolved requirement, not an inferred security rule.",
+      "icon": "decision"
+    },
+    {
+      "id": "focus-recovery",
+      "label": "Accessible recovery",
+      "kind": "behavior",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-focus"
+      ],
+      "summary": "Announce errors and guide keyboard focus.",
+      "description": "Proposed accessible recovery should explain failures to screen-reader users and support keyboard correction and retry. Exact focus destinations, announcement behavior and implementation checks remain to be defined and tested.",
+      "icon": "check"
+    }
+  ],
+  "edges": [
+    {
+      "id": "request-success",
+      "from": "address-entry",
+      "to": "confirmation",
+      "label": "Success",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-confirmation"
+      ]
+    },
+    {
+      "id": "request-failure",
+      "from": "address-entry",
+      "to": "recoverable-error",
+      "label": "Failure",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-error-retry"
+      ]
+    },
+    {
+      "id": "retry",
+      "from": "recoverable-error",
+      "to": "address-entry",
+      "label": "Retry",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-error-retry"
+      ]
+    },
+    {
+      "id": "expiry-decision",
+      "from": "address-entry",
+      "to": "expiry-policy",
+      "label": "Resolve policy",
+      "origin": "unknown",
+      "requirementIds": [
+        "reset-expiry"
+      ]
+    },
+    {
+      "id": "focus-requirement",
+      "from": "recoverable-error",
+      "to": "focus-recovery",
+      "label": "Accessible feedback",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-focus"
+      ]
+    }
+  ],
+  "requirements": [
+    {
+      "id": "reset-entry",
+      "text": "The synthetic source includes an address-entry screen.",
+      "origin": "observed",
+      "sourceIds": [
+        "sample-brief"
+      ]
+    },
+    {
+      "id": "reset-confirmation",
+      "text": "The synthetic source includes a confirmation screen; its actual transition is proposed.",
+      "origin": "observed",
+      "sourceIds": [
+        "sample-brief"
+      ]
+    },
+    {
+      "id": "reset-error-retry",
+      "text": "Proposed: preserve the entered address after a failed request and allow retry.",
+      "origin": "proposed"
+    },
+    {
+      "id": "reset-expiry",
+      "text": "Unknown: expiry policy and treatment of repeated requests require a product/security decision.",
+      "origin": "unknown"
+    },
+    {
+      "id": "reset-focus",
+      "text": "Proposed: focus and announced errors must support keyboard and screen-reader recovery.",
+      "origin": "proposed"
+    }
+  ],
+  "findings": [
+    {
+      "id": "decide-request-contract",
+      "message": "No actual API contract or account-disclosure policy has been supplied.",
+      "severity": "blocking",
+      "status": "open"
+    },
+    {
+      "id": "design-error-state",
+      "message": "Recovery and accessible error presentation are proposals; no inspected frame supports them.",
+      "severity": "warning",
+      "status": "open"
+    }
+  ],
+  "presentation": {
+    "fontFamily": "Inter"
+  },
+  "summary": "Request reset instructions and recover from failure.",
+  "description": "This unapproved planning fixture is grounded only in the synthetic brief. It illustrates the proposed reset flow without claiming inspected Penpot frames, actual application behavior or owner agreement. Request policy, recovery and accessibility behavior remain explicit decisions and verification work."
+}

package/examples/design-release-maps/sample-source.md

@@ -0,0 +1,8 @@
+# Synthetic reset-password source
+
+This is illustrative fixture text, not a Penpot inspection or approved product
+requirement. It supplies reproducible local source bytes for the map examples.
+
+The sample includes an address-entry screen and a confirmation screen.
+The intended user goal is to request password-reset instructions.
+No API, expiry policy, error recovery or focus behavior is established here.

package/examples/reflection-browser/README.md

@@ -8,12 +8,13 @@ In your trusted project provider:
 
 ```js
 import { chromium } from 'playwright'; // the adopter's pinned version
+import sharp from 'sharp'; // declare the adopter's reviewed, pinned codec
 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);
+    return await createBrowserProvider({ browser, baseURL: 'http://127.0.0.1:5173', projectRoot: process.cwd(), hooks, encodeLosslessWebp: (bytes) => sharp(bytes).webp({ lossless: true, exact: true, effort: 6 }).toBuffer() }).runCase(test);
   } finally { await browser.close(); }
 }
 ```
@@ -47,3 +48,19 @@ From this repository, run `pnpm smoke:browser` using a locally installed pinned
 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).
+
+The starter captures a temporary PNG through Playwright and writes static lossless
+WebP evidence by default. `encodeLosslessWebp` is an explicit project-owned codec
+hook; declare Sharp directly in the adopting project when using the example above.
+`lossless: true, exact: true` preserves image pixels, including RGB under transparent
+pixels; `quality: 100` alone does not select lossless WebP. The provider compares
+the encoded image with the capture before saving and refuses changed decoded pixels.
+See [Sharp WebP output options](https://sharp.pixelplumbing.com/api-output#webp).
+
+Comparison reads both PNG and WebP references by content. Existing approved PNG
+references keep their original hashes. `imageFormat: "png"` explicitly selects the
+legacy output path without requiring an encoder. Browser capture metadata, exact
+scale/viewport checks, independent evidence paths and owner review remain unchanged.
+The adapter rejects lossy/animated WebP and validates container metadata without
+adding a native decoder dependency. The repository's pinned Sharp dev dependency
+exists only for smoke validation; it is not shipped as an adapter runtime dependency.

package/examples/reflection-browser/capture.mjs

@@ -264,12 +264,12 @@ export async function captureCase(page, test, hooks, { timeoutMs = 10000 } = {})
 }
 
 /** Exact decoded RGBA pixel difference, without resizing or threshold-based approval. */
-export async function comparePng(page, baseline, screenshot) {
+export async function compareImages(page, baseline, screenshot) {
   return page.evaluate(
     async (images) => {
-      const decode = async (base64) => {
+      const decode = async ({ mime, base64 }) => {
         const image = new Image();
-        image.src = "data:image/png;base64," + base64;
+        image.src = "data:" + mime + ";base64," + base64;
         await image.decode();
         return image;
       };
@@ -304,8 +304,26 @@ export async function comparePng(page, baseline, screenshot) {
       return changed / (canvas.width * canvas.height);
     },
     [
-      baseline.toString("base64"),
-      screenshot.toString("base64"),
+      imageData(baseline),
+      imageData(screenshot),
     ],
   );
 }
+
+function imageData(bytes) {
+  const png = bytes.length >= 8 && bytes.subarray(0, 8).toString("hex") === "89504e470d0a1a0a";
+  const webp =
+    bytes.length >= 12 &&
+    bytes.toString("ascii", 0, 4) === "RIFF" &&
+    bytes.toString("ascii", 8, 12) === "WEBP";
+  if (!png && !webp) {
+    throw new Error("Comparison requires PNG or WebP bytes");
+  }
+  return {
+    mime: png ? "image/png" : "image/webp",
+    base64: bytes.toString("base64"),
+  };
+}
+
+/** Existing PNG callers retain the same decoded-pixel comparison. */
+export const comparePng = compareImages;

package/examples/reflection-browser/provider.mjs

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { captureCase, comparePng } from "./capture.mjs";
+import { captureCase, compareImages } from "./capture.mjs";
 
 /** Pass a browser from the adopting project's pinned Playwright; this example installs nothing. */
 export function createBrowserProvider({
@@ -12,10 +12,25 @@ export function createBrowserProvider({
   deviceScaleFactor = 1,
   timeoutMs = 10000,
   io,
+  imageFormat = "webp",
+  encodeLosslessWebp,
 }) {
   if (!browser || !projectRoot || !baseURL || typeof hooks?.route !== "function") {
     throw new Error("Browser, project root, app origin and explicit route hook required");
   }
+  if (
+    ![
+      "webp",
+      "png",
+    ].includes(imageFormat)
+  ) {
+    throw new Error("Evidence imageFormat must be webp or png");
+  }
+  if (imageFormat === "webp" && typeof encodeLosslessWebp !== "function") {
+    throw new Error(
+      "Lossless WebP evidence requires encodeLosslessWebp from the project's pinned image codec",
+    );
+  }
   return {
     async runCase(test) {
       const { atomicWriteFile, resolveProjectInput, resolveProjectOutput } =
@@ -48,12 +63,27 @@ export function createBrowserProvider({
         if (page.url() !== target.href) {
           throw new Error("Application navigated away from the intended route");
         }
-        const diffPixelRatio = await comparePng(page, before, capture.screenshot);
+        const diffPixelRatio = await compareImages(page, before, capture.screenshot);
+        const imageBytes =
+          imageFormat === "webp"
+            ? Buffer.from(await encodeLosslessWebp(capture.screenshot))
+            : capture.screenshot;
+        if (imageFormat === "webp") {
+          if (
+            imageBytes.toString("ascii", 0, 4) !== "RIFF" ||
+            imageBytes.toString("ascii", 8, 12) !== "WEBP"
+          ) {
+            throw new Error("Lossless WebP encoder returned a different image format");
+          }
+          if ((await compareImages(page, capture.screenshot, imageBytes)) !== 0) {
+            throw new Error("Lossless WebP encoding changed captured pixels");
+          }
+        }
         const screenshot = path.join(
           ".penpair/reflection",
           createHash("sha256")
             .update(test.id + ":" + test.setup)
-            .digest("hex") + ".png",
+            .digest("hex") + `.${imageFormat}`,
         );
         const output = await resolveProjectOutput(projectRoot, screenshot);
         if (output === (await resolveProjectInput(projectRoot, test.baseline.path))) {
@@ -62,7 +92,7 @@ export function createBrowserProvider({
         await mkdir(path.dirname(output), {
           recursive: true,
         });
-        await atomicWriteFile(output, capture.screenshot, {
+        await atomicWriteFile(output, imageBytes, {
           replace: true,
         });
         return {
@@ -79,7 +109,7 @@ export function createBrowserProvider({
           capture: capture.capture,
           provider: {
             name: "penpair-browser-starter-rgba-exact",
-            version: "1",
+            version: "2",
           },
         };
       } finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/web",
-  "version": "0.3.6",
+  "version": "0.4.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": {
@@ -48,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@penpair/core": "0.3.6"
+    "@penpair/core": "0.4.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",