@penpair/web 0.3.5 → 0.3.7

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/niklas-westman/penpair/main/docs/assets/logo.png" alt="Penpair: a pen nib between blue code brackets" width="120" height="120">
+  <img src="https://raw.githubusercontent.com/niklas-westman/penpair/main/docs/assets/banner.png" alt="Penpair: Design together. Build together. A shared workflow from design and contracts to build, verification and human review." width="100%">
 </p>
 
 # penpair

package/docs/adapters.md

@@ -87,4 +87,4 @@ The design-only workflow can start with one command package. Frontend projects s
 
 The shipped setup/handoff skills should recommend the appropriate companion, preserve existing adapter configuration and report readiness at each stage. They must keep missing references or provider work visible and never invent owner approval.
 
-Use the shipped [real-browser provider starter](../examples/reflection-browser/README.md) to supply capture plumbing while keeping route/theme/state/fixture hooks project-owned. It includes measured font, pointer, scroll and crop evidence; a browser dependency is not added to the core.
+Use the shipped [real-browser provider starter](../examples/reflection-browser/README.md) to supply capture plumbing while keeping route/theme/state/fixture hooks project-owned. It includes measured font, pointer, scroll and crop evidence; a browser dependency is not added to the core. The starter saves static lossless WebP with a project-supplied encoder; the adapter also reads legacy PNG evidence without converting approved references.

package/docs/coverage.md

@@ -20,7 +20,7 @@ A baseline frame may declare an explicit viewport, theme label, UI state, fixtur
 
 `theme`, `state` and `fixture` are declared design intent. A label alone does not prove actual theme activation, application state or data loading. Optional `activeThemeIds` asserts the complete exact active native theme-ID set at capture; omit it for a manually styled frame and retain that uncertainty. Baseline capture remains read-only toward the Penpot document: it never switches themes. Use the separate [mode trial](mode-verification.md) for temporary theme switching.
 
-Frame geometry and PNG dimensions must match the declared CSS viewport and observed export scale. A failed viewport/theme assertion marks `case-mismatch`, exits incomplete and preserves the previous generation. New provenance records exact design dimensions, active native theme IDs where available, API/tool version, renderer description and capture time. Font names are declarations; loaded font versions remain unobserved.
+Frame geometry must match the declared CSS viewport within less than 0.01 CSS px per axis, allowing floating-point noise from Penpot transforms and auto sizing. Baseline capture, case approval and offline coverage use the same tolerance. Exported PNG dimensions must still exactly equal the declared viewport multiplied by the observed export scale and rounded to whole pixels; the geometry tolerance never applies to PNG dimensions. A failed viewport/theme assertion marks `case-mismatch`, exits incomplete and preserves the previous generation. New provenance retains raw, unrounded design dimensions, active native theme IDs where available, API/tool version, renderer description and capture time. Font names are declarations; loaded font versions remain unobserved.
 
 Case metadata is part of approval identity. Changing a fixture/state/theme/viewport declaration requires `--apply --update` even if the PNG bytes happen to match. Moving a matching image to a different file/page/frame identity also requires review. Recapture preserves the original approval until that explicit update. Metadata is pinned before asynchronous capture.
 

package/docs/guide.md

@@ -169,6 +169,6 @@ Use `inspect <shape-id> --page <name> --all` for bounded structured evidence wit
 
 ## State, theme and responsive coverage
 
-Add explicit `frames[].case` metadata and a required matrix under `baselines.coverage`. `baselines coverage --json` validates approved images offline and exposes missing/unsupported slots. Rich cases remain pending browser setup mappings; see [coverage semantics and approval](coverage.md).
+Add explicit `frames[].case` metadata and a required matrix under `baselines.coverage`. Case geometry allows less than 0.01 CSS px of Penpot floating-point noise per axis; exported PNG dimensions remain exact at the capture scale, and raw geometry stays in provenance. `baselines coverage --json` validates approved images offline and exposes missing/unsupported slots. Rich cases remain pending browser setup mappings; see [coverage semantics and approval](coverage.md).
 
 For project-specific agent tools, use the [explicit-root stdio server and client examples](mcp.md). It exposes typed guarded services and defaults to omitting design-write tools.

package/docs/releasing.md

@@ -8,7 +8,7 @@ All packages in this repository are released **together, at one version, even a
 | `pnpm version-packages` | One Changesets fixed group versions every package, synchronizes `version.ts` and refreshes the lockfile |
 | `pnpm check:versions` | Missing, duplicate, ignored or separately grouped release packages, including packages added later |
 | `prepublishOnly` in every package | `pnpm publish` inside one package: it refuses unless `pnpm release` started it, and checks the versions again |
-| `pnpm release` | A half release: it checks, publishes the whole set in dependency order, looks each one up on npm, and reports anything missing |
+| `pnpm release` | A half release: it checks, uploads the whole set with at most three workers, verifies registry visibility concurrently, and reports anything missing |
 
 Publishing cannot be undone: a version, once published, cannot be replaced. Check first, publish once.
 
@@ -34,10 +34,11 @@ Publishing cannot be undone: a version, once published, cannot be replaced. Chec
    publishing. The protected `npm-release` environment may require an additional
    owner approval, depending on its configured protection.
 5. The existing `pnpm release` entrypoint reruns checks and all package smoke
-   installs, publishes packed tarballs in dependency order with npm OIDC and
-   provenance, and verifies every required registry version (all six by default). A moved main branch stops
-   the job instead of publishing a different commit. Do not merge another main
-   change until a release finishes; use manual recovery if it has moved.
+   installs, uploads packed tarballs with at most three workers using npm OIDC and
+   provenance, then verifies every required registry version concurrently (all six by default).
+   It checks out the exact reviewed release SHA and verifies that it belongs to main's
+   history. Feature PRs may merge while that immutable snapshot publishes; newer
+   feature commits and their pending Changesets cannot alter the release artifacts.
 
 Automation is opt-in through the activation switches below. Merging a feature PR
 creates or updates the version PR; publishing starts only after that reviewed
@@ -134,20 +135,36 @@ pnpm release                          # dry run; publishes nothing
 pnpm release --publish --confirm-version X.Y.Z
 ```
 
+Local OTP publication uploads one package at a time to keep interactive prompts
+separate, then uses the same concurrent family visibility barrier.
+
 The manual GitHub **Publish reviewed Penpair release** dispatch also remains:
-enter the exact version already on main. It rejects mismatches or pending notes;
-set `continue_release` only after inspecting an interrupted release. The dispatch
-still passes through the protected environment and all unchanged release guards.
+enter the exact reviewed version. Optionally enter its full 40-character `release_sha`
+when main has advanced; omitting it selects the dispatch commit. Both automatic
+and manual releases require the selected SHA to match a merged, same-repository
+release PR, contain the increased shared version, and have no pending Changesets
+in that snapshot. Set `continue_release` only after inspecting an interrupted
+release. The dispatch still passes through the protected environment and release guards.
+Historical recovery requires the selected commit's `scripts/release-protocol.json`
+to declare the controller's supported protocol (currently version 1). Missing or
+unsupported protocols are rejected before checkout or publication approval; releases
+predating this tooling must use their original recovery process. Incompatible future
+publisher safeguards must increment both the marker and the supported protocol so
+older publisher scripts cannot bypass them.
 
 ## If a release stops half way
 
 After a successful upload, npm may still be processing the version. The release
-checks registry visibility immediately and then once per minute within a
-ten-minute deadline **for each uploaded package**, printing progress while it
-waits. Each metadata query has a 30-second maximum (or the remaining deadline,
+does not block the remaining uploads on that package's registry visibility.
+Up to three uploads run together. After all started uploads settle, every accepted
+upload and already published required package is checked concurrently under one
+shared ten-minute visibility deadline, with immediate checks followed by minute
+polls. Each metadata query has a 30-second maximum (or the remaining deadline,
 whichever is smaller), with npm's internal retries disabled. Query time counts
-toward the deadline. A registry error still stops the release; only an actual
-not-found result waits for propagation. The visibility wait never republishes.
+toward the deadline. Registry errors remain unknown failures rather than evidence
+of absence. Visibility checks never republish. A failed upload stops new scheduling;
+already started uploads finish and their results are retained before the command exits.
+A partial release still requires explicit recovery.
 
 A publish can fail after some packages are out (a network error, a wrong one-time code, a name npm refuses). The version is then on npm for some packages and not for others, which must not stay that way. Fix the cause and run:
 
@@ -158,18 +175,26 @@ pnpm release --publish --continue    # publishes only what is missing at this ve
 Without `--continue`, `pnpm release` refuses to run while only some packages are at the version, so a partial release cannot be forgotten.
 
 For GitHub recovery, run **Publish reviewed Penpair release** on `main`, enter
-the exact interrupted version and set `continue_release=true`. Approve
-`npm-release` when requested. This checks the registry again, skips versions
-already present and publishes only missing required packages. Inspect the final
-package/provenance verification before counting the release complete.
-
-Finish an interrupted release before merging unrelated changes or a tooling fix
-with new pending Changesets. The manual release gate requires a reviewed version
-with no pending notes; merging another feature can prevent continuation until
-that release state is reconciled. Do not discard pending package-release notes
-or weaken guards to force recovery through.
-
-An empty, tooling-only Changeset contains no package release entries. Changesets
+the exact interrupted version, its full `release_sha` when main has advanced, and
+set `continue_release=true`. Approve `npm-release` when requested. This checks
+the registry again, skips versions already present and publishes only missing
+required packages from that reviewed snapshot. If an accepted upload is still
+propagating, wait and independently inspect the registry before requesting recovery.
+A newer published `latest` version on any required package refuses the older
+release rather than moving that tag backward. Tags are checked both during
+preflight and immediately before uploads. Inspect final package/provenance
+verification before counting the release complete.
+
+Feature merges may continue during publication or recovery: pending Changesets
+on newer main commits do not change the reviewed release snapshot. Keep release
+versions in sequence and inspect a failed family before approving a newer release.
+Only actual publish jobs enter the `penpair-package-release` concurrency group;
+`queue: max` retains up to 100 pending jobs rather than replacing the previous one.
+Queue arrival order can differ from version order, so the latest-version rollback
+check remains required. See [GitHub concurrency documentation](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency).
+Do not discard pending package-release notes or weaken guards to force recovery through.
+
+For legacy releases predating snapshot-aware recovery, an empty, tooling-only Changeset contains no package release entries. Changesets
 can consume that metadata without changing versions. If such a note blocks an
 interrupted release, handle it in a reviewed metadata-only cleanup, preserve its
 summary in the completion report and verify unchanged package/source versions
@@ -185,7 +210,7 @@ the release's own evidence; never relax the existing release guards.
 pnpm release --publish --except penpair
 ```
 
-The release is then reported as `INCOMPLETE` (exit code 3) on purpose, and `pnpm release --publish --continue` finishes it the day npm allows the name. Nothing else can be left out, and only by naming it.
+The release is then reported as `INCOMPLETE` (exit code 3) on purpose. Recovery at that version requires explicit continuation and refuses if a newer required package version has already taken `latest`. Nothing else can be left out, and only by naming it.
 
 ## Verify
 
@@ -217,10 +242,15 @@ See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) and
 [provenance requirements](https://docs.npmjs.com/generating-provenance-statements/).
 Publishing validates the workflow context and rejects long-lived npm token
 fallback, packs with pnpm to rewrite `workspace:*` to exact versions, and publishes
-single tarballs with npm and provenance. These local checks are operational guards;
+single tarballs with npm and provenance. For SHA-selected recovery, only the npm
+publish subprocess receives `GITHUB_SHA` set to the verified source SHA, so npm's
+provenance source digest identifies the artifact checkout. Workflow identity/ref,
+OIDC issuance and run invocation retain the actual dispatch context. These local checks are operational guards;
 npm authenticates the actual identity against owner-managed publisher settings.
 
-npm cannot atomically publish multiple packages. A network/permission failure can
+npm cannot atomically publish multiple packages. With concurrent uploads a dependent
+package may briefly appear before its exact dependency has propagated. Consumers
+should use a version after final family verification succeeds. A network/permission failure can
 leave some published and others missing; the release reports failure and requires
 explicit continuation at the same version. A rerun never silently resumes.
 

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.5",
+  "version": "0.3.7",
   "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.5"
+    "@penpair/core": "0.3.7"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",