@penpair/web 0.3.7 → 0.4.1

package/docs/adapters.md

@@ -27,7 +27,7 @@ Use it when your application uses Marwes UI. Follow the [adapter overview](marwe
 5. Run a project provider to open that state, read it back, capture the browser and compare the image.
 6. Review the screenshots and differences; record human approval separately.
 
-The adapter checks that the returned evidence identifies the requested case and expected state, references the correct unchanged baseline, and has matching PNG dimensions/scale and font evidence. A complete result within the configured difference threshold is technical evidence, not visual approval or an accessibility assessment.
+The adapter checks that the returned evidence identifies the requested case and expected state, references the correct unchanged baseline, and has matching image dimensions/scale (PNG or static lossless WebP) and font evidence. A complete result within the configured difference threshold is technical evidence, not visual approval or an accessibility assessment.
 
 The provider is project code with an `async runCase(test)` export. It supplies actual route/theme/state/fixture setup, browser readback, screenshot capture and image comparison through the project's pinned tools. It can integrate the project's existing Reflection/browser checker. The adapter itself does not install a browser or execute a particular Reflection engine automatically.
 

package/docs/approvals.md

@@ -8,7 +8,7 @@ penpair approve --page Dashboard --frame FRAME_ID --write \
 # Include --case CONFIGURED_BASELINE_ID for a rich theme/state/fixture case.
 ```
 
-Preview captures stable evidence and records nothing. Recording captures again and appends a schema-1 owner-words record to `design/approvals.json`, with file/page/frame IDs, revision, scale, actual theme/render context, optional declared case, PNG SHA-256, date, identity, exact note and record hash. The immutable PNG lives under `design/approvals/SHA256.png`. A local exclusive append lock prevents lost records; a stale lock requires inspection. The file is atomically replaced after image bytes exist. Prior records are retained.
+Preview captures stable evidence and records nothing. Recording captures again and appends a schema-1 owner-words record to `design/approvals.json`, with file/page/frame IDs, revision, scale, actual theme/render context, optional declared case, encoded-image SHA-256, date, identity, exact note and record hash. The immutable image lives under `design/approvals/SHA256.webp` or the preserved PNG form `design/approvals/SHA256.png`. A local exclusive append lock prevents lost records; a stale lock requires inspection. The file is atomically replaced after image bytes exist. Prior records are retained.
 
 The command records supplied words; it cannot authenticate a person or establish consent. An agent needs the owner's actual approval for the exact reviewed artifact and must never invent words or run this as a routine automatic success step. No approvals were recorded by this implementation task. Content hashes detect changes, not identity. An empty note/identity, unstable capture, mismatched case, altered approved bytes or credential redaction refuses publication.
 
@@ -16,4 +16,35 @@ The command records supplied words; it cannot authenticate a person or establish
 
 An exceptional `--apply --update --force-reason 'EXPLICIT_REASON'` may save a reference without a matching owner record. Its provenance says `forced-reference`; the reason persists. Rich case coverage and the implementation-case adapter refuse to count that waiver as owner-approved evidence. A waived reference is useful for an experiment, but cannot silently satisfy the design acceptance gate. Empty reasons and reasons without apply/update refuse.
 
-The latest revision is a conservative invalidation boundary: an unrelated design edit may require fresh approval even if pixels stay equal. A PNG alone does not approve structure, behavior or accessibility. Approval records remain local/project artifacts until reviewed; no publish, client configuration or consumer-repository edit occurs automatically.
+The latest revision is a conservative invalidation boundary: an unrelated design edit may require fresh approval even if pixels stay equal. An image alone does not approve structure, behavior or accessibility. Approval records remain local/project artifacts until reviewed; no publish, client configuration or consumer-repository edit occurs automatically.
+
+## Image format and migration
+
+New image approvals default to static lossless WebP. `approve --format png` or
+`approve --format webp` selects an exact encoding. For `approve --case CASE_ID`
+without explicit `--format`, the baseline resolver preserves an existing
+reference's actual format; otherwise it uses `baselines.format`, then WebP.
+An approval without `--case` uses explicit `--format` or WebP. Review the actual
+encoded candidate before supplying owner words; equal decoded pixels do not make
+PNG and WebP byte approvals interchangeable.
+
+Changing `baselines.format` or supplying `baselines --format webp` alone does not
+convert an existing PNG reference. Preview migration explicitly:
+
+```sh
+penpair baselines --format webp --migrate-format
+penpair approve --page Dashboard --frame FRAME_ID --case CASE_ID --format webp
+```
+
+After inspecting the new-format artifact and obtaining the owner's actual words,
+record it using the same approval command with `--write --by OWNER --note
+EXACT_OWNER_WORDS`. Then apply the migration:
+
+```sh
+penpair baselines --format webp --migrate-format --apply --update
+```
+
+The CLI requires `--format` with `--migrate-format`; applying requires `--update`.
+Normal exact-image/case approval rules still apply. Prior PNG approval records
+and generations stay intact; migration publishes a new immutable generation.
+Public `export` and `shots` output remain PNG and are independent of this choice.

package/docs/artifacts.md

@@ -1,13 +1,33 @@
 # Capture and approval provenance
 
-Baseline manifests use schema 2. `capturedRevision` identifies the coherent capture run, while each frame has separate `captured` and `approved` records. Those records identify the file, page and frame by immutable ID, revision, PNG hash, scale, active theme names, capture time, penpair version, reported Penpot API version and browser user agent when available. A missing environment value is recorded as unknown; the record does not establish that fonts loaded correctly or identify every rendering dependency.
+Baseline manifests use schema 2. `capturedRevision` identifies the coherent capture run, while each frame has separate `captured` and `approved` records. Those records identify the file, page and frame by immutable ID, revision, encoded-image hash, scale, active theme names, capture time, penpair version, reported Penpot API version and browser user agent when available. A missing environment value is recorded as unknown; the record does not establish that fonts loaded correctly or identify every rendering dependency.
 
-An unchanged reference retains its original approval record. A changed image recaptured without `--update` retains its approved bytes, path, revision and hash, while `captured` describes the new candidate. Legacy images without trustworthy provenance are marked `legacy`; a current revision is never invented for them. Changing a baseline still requires the owner's `--apply --update`. Schema 2 does not claim a separate human review record; that is tracked in D2.
+An unchanged reference retains its original approval record. A changed image recaptured without `--update` retains its approved bytes, path, revision and hash, while `captured` describes the new candidate. Legacy images without trustworthy provenance are marked `legacy`; a current revision is never invented for them. Changing a baseline still requires the owner's `--apply --update`. Exact owner words are retained separately in [approval records](approvals.md); manifest provenance alone cannot manufacture consent.
 
 All configured frames must be present and stable. File/page/revision evidence is checked inside exports and across consecutive exports; the complete frame listing is checked again after capture. Intervening changes, failures or cancellation do not publish a new complete manifest. There is no partial-publication mode.
 
-PNG captures live in immutable `captures/<capture-id>/<baseline-id>.png` generations instead of replacing `<baseline-id>.png`. Read approved image paths from manifest frame `file` fields. Generated Reflection cases already use those paths. `penpair-baselines.json` is the authoritative commit point and is published last with a same-directory atomic rename. Its `casesFile` points to the exact immutable case file for that generation. The root `reflection-cases.json` remains a convenience for existing config imports; when reading it together with a manifest, require matching `captureId`, or follow `casesFile` from the manifest. Independent root files cannot be replaced as one filesystem transaction.
+Baseline captures live in immutable `captures/<capture-id>/<baseline-id>.webp` or `.png` generations. New references default to static lossless WebP; existing PNG references keep PNG during ordinary captures and updates. Historical `<baseline-id>.png` files are not renamed or converted implicitly. Read approved image paths from manifest frame `file` fields. Generated Reflection cases already use those paths. `penpair-baselines.json` is the authoritative commit point and is published last with a same-directory atomic rename. Its `casesFile` points to the exact immutable case file for that generation. The root `reflection-cases.json` remains a convenience for existing config imports; when reading it together with a manifest, require matching `captureId`, or follow `casesFile` from the manifest. Independent root files cannot be replaced as one filesystem transaction.
 
 A process interrupted during output may leave an unreferenced capture generation. Previous manifest references remain usable; inspect before cleaning generations. Staging directories are removed on handled errors. This is filesystem publication safety, not a power-loss-proof multi-file transaction or a remote backup.
 
 Standalone PNG export and full-file archive candidates also stage complete bytes before publication. Archives use exclusive creation and never replace an existing file. PNG exports atomically replace the requested output only after a stable result. The export report includes target provenance. Archive restore verification remains a separate scratch import/readback task.
+
+## Baseline encoding and explicit migration
+
+Always follow the manifest's exact `file` path and encoded-byte hash; do not
+construct a `.png` or `.webp` path from the baseline ID. PNG and WebP with identical
+pixels have different approval identities. An existing reference keeps its
+actual encoding even when `baselines.format` or `--format` selects another
+format. New references choose explicit `--format`, then config, then WebP.
+
+An explicit `--format webp --migrate-format` previews migration. Publishing it
+also requires `--apply --update` and the normal matching exact new-format approval
+(or explicit waiver rules). Earlier immutable generations and owner records
+remain unchanged. See [approval migration](approvals.md#image-format-and-migration).
+
+WebP conversion is lossless and independently verifies decoded RGBA bytes,
+dimensions and ICC preservation. Animation, unsupported bit depth, excessive
+size or pixel/metadata mismatch refuses conversion and preserves the previous
+manifest. Public PNG exports, shot generations and pinned release-source PNG
+renders retain their existing format; baseline defaults do not redefine those
+artifacts.

package/docs/browser-sessions.md

@@ -0,0 +1,147 @@
+# Recovering a suspended Penpot tab
+
+Penpair executes live design operations through the Penpot browser plugin. A
+reachable Penpot server does not establish that its editor tab is responsive.
+Browser timer throttling, freezing and discarding are separate from computer
+sleep; keeping the computer awake does not prevent them.
+
+## Wake an existing tab
+
+From the configured project, with an owner-confirmed file pin and an existing
+MCP connection:
+
+```sh
+penpair wake --debug-port 9222
+penpair wake --debug-port 9222 --timeout-ms 10000 --json
+```
+
+The browser must already expose a debugging endpoint on `127.0.0.1` at the
+specified port. Penpair does not start a browser or enable debugging in an
+existing browser. `--timeout-ms` accepts 1000–30000; the default 5000 ms budget
+covers activation and verification together.
+
+Penpair lists the browser's targets, requires exactly one editor page matching
+both the project's Penpot origin and pinned `file-id`, then requests activation
+through `/json/activate/<target-id>`. It refuses duplicate matching tabs rather
+than choosing one. Hosted deployments require an exact origin. For a local
+instance, both `http://127.0.0.1:<frontend-port>` and
+`http://localhost:<frontend-port>` are accepted, matching Penpair's existing
+opening commands. Other hosts and ports are refused; duplicate matching tabs
+across the two aliases still fail.
+
+After activation, Penpair performs a fresh read with a challenge and checks the
+actual file ID. Exit 0 means activation was acknowledged and that read verified
+the intended editor. Activation can succeed while readiness fails: JSON then
+reports `activated: true, ready: false`. A browser may also leave a minimized
+window minimized; check the actual window when activation alone is insufficient.
+
+This command does not reload, navigate, restart the plugin, inject page code or
+resume a write. Its `keepAlive: "none"` result means activation is momentary
+recovery, with no sustained keep-alive mechanism. Browser focus can affect legacy
+MCP routing, which is why a fresh identity check follows activation. A target can
+navigate between discovery and activation; the acknowledgment is not an atomic
+guarantee of tab identity or exclusive ownership.
+
+If a write became uncertain, retain its journal, inspect the intended target
+independently and reconcile it before explicitly resuming. Waking a tab does not
+establish whether the previous write completed. See [recovery](recovery.md).
+
+## Understand doctor evidence
+
+```sh
+penpair doctor --json
+```
+
+Doctor stays read-only: it does not activate tabs or install a keep-alive.
+The execution check exposes `evidence.pluginHealth`:
+
+```json
+{
+  "state": "suspended",
+  "heartbeatAgeMs": 36000,
+  "heartbeatSource": "upstream-error",
+  "keepAlive": { "method": "unknown", "verified": false }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `state` | `responsive` after a verified fresh read; `suspended` when the upstream failure explicitly reports suspension; otherwise `unknown`. |
+| `heartbeatAgeMs` | Age reported in an upstream error such as `no heartbeat for 36s`; `null` when unavailable. |
+| `heartbeatSource` | `upstream-error` when an age was parsed, otherwise `unavailable`. |
+| `keepAlive` | The current connection does not expose independently verified browser keep-alive telemetry, so its method remains `unknown` and `verified` remains `false`. |
+
+The check's `observedAt` records when Penpair observed this evidence. A successful
+read does not imply a zero-second heartbeat age or prove that the next background
+request will succeed. A generic timeout does not establish suspension.
+
+## Browser settings and a dedicated window
+
+Chrome's **Settings → Performance → Always keep these sites active** exclusion
+can prevent Memory Saver from deactivating the configured Penpot site. It does
+not establish that background timers or Penpot layout will run without delay.
+See [Chrome's performance settings](https://support.google.com/chrome/answer/12929150?hl=en).
+
+For an explicit experiment, start a separate Chrome instance with its own profile
+outside the repository. This macOS example uses an installed Google Chrome:
+
+```sh
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  --user-data-dir="$HOME/Library/Application Support/Penpair/browser-profile" \
+  --remote-debugging-address=127.0.0.1 \
+  --remote-debugging-port=9222 \
+  --disable-background-timer-throttling \
+  --disable-renderer-backgrounding \
+  --disable-backgrounding-occluded-windows \
+  --new-window https://design.penpot.app
+```
+
+Use the project's configured origin for a different deployment. These launch
+switches do not retrofit an already running ordinary browser instance. Since
+Chrome 136, remote debugging requires a non-default user-data directory. Keep
+that profile private: it can retain account cookies and cached designs. Keep the
+debugging port on loopback and do not expose it on a network. See
+[Chrome's debugging changes](https://developer.chrome.com/blog/remote-debugging-port/).
+
+Login and plugin connection in that dedicated profile remain human setup steps;
+Penpair does not copy credentials or complete them automatically. The flags above
+are an experimental configuration, not a verified guarantee of background
+Penpot operation. No managed-browser lifecycle, browser dependency or browser
+download is added by the wake command.
+
+A silent audio track does **not** count for Chrome's audio timer-throttling
+exemption. Web Workers, SharedWorkers and Web Locks have different lifecycle
+behavior, but are not verified here as a complete solution for the Penpot plugin.
+Penpair does not inject these workarounds. See
+[Chrome timer throttling](https://developer.chrome.com/blog/timer-throttling-in-chrome-88)
+and [the Page Lifecycle API](https://developer.chrome.com/docs/web-platform/page-lifecycle-api).
+
+## Verification status and the remaining acceptance trial
+
+The initial manual trial raised an existing Penpot window through native browser
+controls without reloading it. Port 9222 was unavailable, and the chat's MCP
+connection reported no connected Penpot instance. That trial therefore did not
+prove restored plugin heartbeats. A separate real CDP trial used the installed
+Brave browser with a temporary unauthenticated profile and the three background
+flags above. The wake implementation changed a disposable local fixture page
+from hidden to visible. No Penpot account or design was loaded, so this proves
+browser activation only. Automated tests also cover target selection, activation
+requests, deadlines and refusal paths using fake and local HTTP endpoints.
+
+The required sustained-background acceptance trial remains **unverified**. Use an
+owner-authorized disposable file and the intended installed browser build:
+
+1. Record the browser version, launch flags, profile, settings and initial doctor
+   evidence. Verify the file pin and establish a normal responsive connection.
+2. Run 30 frames, one journaled write per frame, each lasting 20–60 seconds, with
+   the Penpot window behind another window. Do not manually focus or reload it.
+3. Independently read back the results, export and visually inspect them. Record
+   heartbeat failures, layout timeouts and any required intervention.
+4. Test minimized, occluded and screen-locked states separately; success in one
+   state does not establish the others. Computer sleep is a separate boundary.
+5. If any write becomes uncertain, stop and reconcile before replay. Do not
+   increase retries or weaken journal, identity or layout checks to pass.
+
+One successful activation is not a passing 30-frame run. The dedicated-browser
+configuration and any future plugin keep-alive require that real acceptance
+trial before they can be advertised as reliable background execution.

package/docs/compatibility.md

@@ -12,9 +12,11 @@ What has been checked, where, and what differs. Update it whenever a Penpot is p
 | Deep check (`probe --deep --write`): flex layout, text, token set and binding, components and swap, clone, PNG export, clean-up | all steps pass, nothing left behind (run on a fresh instance's empty file) | all steps pass, nothing left behind (run twice) |
 | `pages`, `tree`, `audit`, `tokens dump`, `export` (waits for a stable render), `archive` with `--apply`, a project snippet that writes (`run seed-demo`) | all in use | all verified on seeded sample content |
 | `doctor` (external profile) | ok | ok |
+| Cross-page clone followed by `appendChild` / `insertChild` | refused with either page active; scratch cleanup verified ([details](copy-between-pages.md)) | not tried |
 | `init`, `up`, `doctor` for a Penpot penpair starts (a fresh instance on its own port, then the owner's account, key and plugin connection) | ok: 16 seconds to answer with the images cached; `doctor` all ok | not applicable |
 
 ## Differences found
+- **Cross-page reparenting is refused on local 2.18.3.** Clones stay on the source page. Use native editor copy/paste; see [copying between pages](copy-between-pages.md).
 - **A new token set starts inactive, with no themes in the file.** Seen on both the hosted Penpot and a fresh local instance. (An earlier note that local sets start active was wrong or applied to a file with themes.)
 - **A token binding is recorded after the call, not during it.** On the hosted Penpot it appeared after about half a second to a few seconds; reading it straight away shows nothing. Code that checks a binding has to wait for it.
 - **Applying the same token again removes the binding** (seen on the hosted Penpot, as in the local notes).
@@ -42,11 +44,11 @@ The `Scratch Penpot compatibility smoke` workflow is manual-dispatch only. Confi
 
 Library helpers accept the project's guarded client:
 
-- `waitForStableLayout(client, { shapeId, timeoutMs })`: prefers supported native completion; otherwise polls geometry. Native failure, target changes, incomplete samples and timeout cannot pass. Geometry stability does not establish token/font/pixel correctness; independent readback and stable exports remain necessary. Default operation/export and token verification paths now use this helper; see [layout settling](layout-settling.md). Live behavior on pinned versions remains unverified.
+- `waitForStableLayout(client, { shapeId, timeoutMs })`: prefers supported native completion; otherwise polls geometry. In `auto` mode a failed native wait can fall back to geometry. Budget overflow reports explicitly partial evidence; target changes, malformed samples and timeout cannot pass. Geometry stability does not establish token/font/pixel correctness; independent readback and stable exports remain necessary. Default operation/export and token verification paths use this helper; see [layout settling](layout-settling.md).
 - `validateFileIntegrity(client)`: distinguishes unsupported from a valid empty issue list or actual referential-integrity problems.
 - `createCheckpoint(client, { label, runId }, { apply })`: optional native version history. Without apply it inspects; with apply it saves a run-keyed named version once and independently finds it again. Reusing that run ID reuses an existing checkpoint; it does not provide atomic cross-client locking. No automatic restore/rollback is performed.
 
-Current upstream references: [Penpot API](https://doc.plugins.penpot.app/interfaces/Penpot), [File API](https://doc.plugins.penpot.app/interfaces/File), [FileVersion API](https://doc.plugins.penpot.app/interfaces/FileVersion). Unit fixtures cover missing, present and throwing APIs. These helpers have not yet been exercised against the pinned 2.18.3/2.18.4 instances; the live compatibility table above is intentionally unchanged.
+Current upstream references: [Penpot API](https://doc.plugins.penpot.app/interfaces/Penpot), [File API](https://doc.plugins.penpot.app/interfaces/File), [FileVersion API](https://doc.plugins.penpot.app/interfaces/FileVersion). Unit fixtures cover missing, present and throwing APIs. A read-only layout check on local 2.18.3 on 2026-10-25 observed two existing boards: three equal geometry samples covered 192 nodes; a five-node budget returned `method: "partial"`, `nodeCount: 5`, `truncated: true` and both requested root IDs. This does not prove a live write on a page over 10,000 nodes, native wait timing, integrity validation or version-history behavior. Those remain unverified.
 
 ## Hosted archive candidate
 

package/docs/copy-between-pages.md

@@ -0,0 +1,54 @@
+# Copy boards between pages
+
+Penpair currently cannot copy or move an existing board between pages through
+the Penpot plugin API. There is no `copy-boards` command. Use native copy/paste
+in the Penpot editor, leaving the originals in place, then independently inspect
+the destination and compare stable exports. Keep component references, token
+bindings, sizes and child counts intact. See [design release assembly](design-releases.md)
+for its additional fidelity requirements.
+
+## Tested API boundary
+
+A disposable two-page probe on local Penpot 2.18.3 on 2026-10-25 tested a board
+with one rectangle child. Each `clone()` stayed on the source page. Appending or
+inserting the clone into a board on the other page failed with:
+
+```text
+Cannot modify a page that is not currently active
+```
+
+Both `appendChild(clone)` and `insertChild(0, clone)` failed with either the
+source page or the destination page active. Independent readback found both
+clones on the source page, no destination children, and the original board and
+child unchanged. Two destination exports were inspected and showed the empty
+board. Both disposable pages were removed; a separate read confirmed their
+absence and the original pages' names and top-level shape IDs were preserved.
+This establishes a local API limitation, not hosted-version or component/token
+copy fidelity.
+
+The [upstream shape implementation](https://github.com/penpot/penpot/blob/develop/frontend/src/app/plugins/shape.cljs)
+checks that both parent and child pages are active before either structural
+operation. The [Board API](https://doc.plugins.penpot.app/interfaces/Board)
+provides cloning and reparenting, but no cross-page transfer operation. The
+[File API](https://doc.plugins.penpot.app/interfaces/File) exposes export,
+validation and history, without a file-change submission method.
+
+## File-change route
+
+Penpair's connection calls the editor's MCP tools; it has no authenticated
+Penpot backend file-change client or supported plugin method for submitting raw
+file changes. Internal `$page` metadata does not provide that capability.
+Changing a proxy's internals, reconstructing a board from its visible properties,
+or patching backend file objects would not establish preserved component
+overrides, token bindings, references, undo behavior or revision coordination.
+
+There is therefore no safe file-change route in the current implementation.
+Automatic cross-page copying stops at this boundary. A future supported transfer
+API or separately validated native editor integration would need exact source
+selection, a dry run, journaled recovery, independent fidelity readback and stable
+exports before shipping a copy command. Moving must remain explicit.
+
+For large pages, scope a writer's layout observation with repeatable
+`--layout-root <shape-id>` and, when needed, `--layout-max-nodes <n>`; see
+[layout settling](layout-settling.md). Reducing the observation scope does not
+add a cross-page copy capability.

package/docs/coverage.md

@@ -20,9 +20,9 @@ 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 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.
+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. Encoded image dimensions (PNG or static lossless WebP) must still exactly equal the declared viewport multiplied by the observed export scale and rounded to whole pixels; the geometry tolerance never applies to image 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.
+Case metadata is part of approval identity. Changing a fixture/state/theme/viewport declaration requires `--apply --update` even if the image 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.
 
 ## Required matrix
 
@@ -30,7 +30,7 @@ Add `baselines.coverage.required` as an explicit list of route/viewport/theme/st
 
 See [an example matrix](../examples/coverage-matrix.json) spanning desktop/mobile, light/dark and an empty state. Only request combinations the product intends to support; no matrix is inferred from frame sizes or names.
 
-`penpair baselines coverage --json` runs offline. It loads the version-2 manifest, checks the configured file pin, validates project-bound artifact paths, independently hashes approved PNG bytes and reports:
+`penpair baselines coverage --json` runs offline. It loads the version-2 manifest, checks the configured file pin, validates project-bound artifact paths, independently hashes approved PNG or static lossless WebP bytes and reports:
 
 - `missing-case`: no configured frame for the required tuple.
 - `missing-capture`: a frame is configured but has no approved capture.
@@ -41,7 +41,7 @@ See [an example matrix](../examples/coverage-matrix.json) spanning desktop/mobil
 
 `designCasesComplete` means all requested design slots have matching approved intent. `browserVerification: not-run` and `accessibility: not-assessed` remain separate, even when every design slot is complete. Unknown font loading, absent activation assertions and missing renderer metadata are listed. The offline report exits 3 for gaps; it never connects to Penpot or loads project extensions.
 
-Ordinary `baselines` can publish a coherent capture of its configured frames while the broader required matrix still has gaps; that command returns incomplete when configured requirements remain uncovered. The manifest distinguishes capture completeness from matrix coverage. An incomplete capture itself still publishes nothing. Manifest reads are bounded to 16 MiB and each approved PNG check to 64 MiB; exceeding those bounds cannot produce covered evidence.
+Ordinary `baselines` can publish a coherent capture of its configured frames while the broader required matrix still has gaps; that command returns incomplete when configured requirements remain uncovered. The manifest distinguishes capture completeness from matrix coverage. An incomplete capture itself still publishes nothing. Manifest reads are bounded to 16 MiB and each approved image check to 64 MiB; exceeding those bounds cannot produce covered evidence.
 
 ## Browser integration
 
@@ -62,3 +62,19 @@ Baseline entries require `frame` or `frameId`, or both. `frameId` is a unique bo
 When both are supplied, a different current board name reports `renamed` and the entry is never captured under its stale name. Review the rename and update the expected name before retrying. ID-only entries follow the ID and report its current name. Page searches stop with an explicit error if the 10,000-shape budget truncates the listing.
 
 `approve --case CASE_ID --page PAGE --frame ID` compares `--frame` directly with a configured `frameId`; name-only cases retain the unique-name check. Nested frames use the same exact frame-ID capture identity for approval matching. The baseline manifest continues to record `frameId`; Reflection case format is unchanged.
+
+## Image encoding
+
+New baseline references default to static lossless WebP. Existing PNG references
+and approvals retain their exact original bytes, paths and hashes during normal
+capture/update. Neither `baselines.format` nor `--format` alone migrates an
+existing reference. Use explicit `--format webp --migrate-format` for a preview;
+application also requires `--apply --update` and matching exact new-format image
+approval. A PNG approval does not cover equivalent WebP pixels. See
+[approval and migration](approvals.md#image-format-and-migration).
+
+WebP conversion preserves exact dimensions, decoded RGBA pixels including RGB
+under transparency, and the source ICC profile. Unsupported animated/16-bit
+input or failed conversion verification leaves the prior generation intact.
+The conversion budget is 64 megapixels; geometry tolerance never relaxes image
+pixel-size or pixel-identity checks.

package/docs/design-releases.md

@@ -0,0 +1,164 @@
+# Design releases
+
+A design release freezes a reviewed design handoff for an explicit product SemVer,
+independent of the Penpair package version. It joins
+[journey maps](journey-maps.md), [integration maps](integration-maps.md), exact
+design cases and immutable evidence so a later implementation agent can identify
+what was reviewed. This is a design release, separate from publishing Penpair's
+npm packages or accepting a frontend implementation.
+
+## Local commands
+
+Create the plan from actual source inspection, using your own product SemVer.
+These paths illustrate project-owned inputs. A release accepts at most 100
+selected source screens. Use the local project command, such as
+`pnpm exec penpair`, when installed as a dependency.
+
+```sh
+# Save a planned release, then inspect the remote assembly preview.
+penpair design-release plan --from design/releases/1.0.0/plan.json \
+  --out design/releases/1.0.0/release.json
+penpair design-release assemble --from design/releases/1.0.0/release.json
+
+# After reviewing the preview and authorizing the assembly write:
+penpair design-release assemble --from design/releases/1.0.0/release.json --apply
+```
+
+Next, perform the guided native copy and record actual source/target identities
+in `receipts.json`. Verification reads the live frames and saves evidence;
+finalization below is a preview and records no owner approval.
+
+```sh
+penpair design-release verify --from design/releases/1.0.0/release.json \
+  --receipts design/releases/1.0.0/receipts.json
+penpair design-release finalize --from design/releases/1.0.0/release.json
+penpair design-release check --from design/releases/1.0.0/release.json --live
+penpair design-release context --from design/releases/1.0.0/release.json --draft
+```
+
+Only apply finalization after the owner supplies actual words for the exact
+verified candidate, as described below. After finalization, omit `--draft` to
+request approved context. Missing required proof keeps verification/finalization
+incomplete; these commands do not bypass the native support limits.
+
+## Prepare and assemble
+
+Use the `design-release` command family to plan, assemble, verify, finalize,
+check and produce context. Use the installed command's help for current argument
+names. Planning exposes required inputs and unresolved work. Assembly records
+identities and hashes; it does not invent source observations or owner approval.
+Each selected source needs its complete `inspection` reference (project-relative
+`path` and exact `sha256`). Pin a stable source PNG through its `render` reference
+before verification; a draft without this reference cannot pass fidelity. A
+source using tokens also needs a complete pinned token-inspection `dependencies`
+reference. Required dependency changes invalidate the pinned source evidence.
+
+Include the parent and every linked detail-map contract in the release's
+`contracts` list, each with its independent exact review. A reviewed parent link
+is not approval of the child graph. See [linked detail maps](integration-maps.md#linked-detail-maps).
+
+Keep the release page in the same pinned Penpot file, named `release/<version>`.
+Assembly creates the owned overview/map sections and reports `awaiting-copy`.
+Copy source design frames natively using a reviewed, guided copy/paste operation
+by a person or an authorized AI using existing browser tools. Assembly does not
+perform an unsupported cross-page clone.
+The [cross-page API assessment](copy-between-pages.md) records the tested
+boundary and why there is no automatic file-change fallback.
+Preserve visual fidelity, native components, token bindings, text and layout;
+do not recreate frames from screenshots or normalize their dimensions. A source
+using auto height must retain it. Floating-point geometry noise is not a reason
+to change source sizing.
+
+The live sequence is read-only inspection, pinned snapshot, one idempotent write,
+independent readback and stable exports that are looked at. Snippets stay under
+90 KB. If a write response is uncertain, inspect what exists before retrying.
+Keep unmanaged content intact; a page name alone cannot authorize replacement.
+Do not copy via a lossy or structurally incomplete fallback when native fidelity
+cannot be established: report the missing proof.
+
+## Supported native verification limits
+
+Native verification is deliberately narrower than native copy/paste. Selecting a
+screen for this workflow does not establish that its content can be verified.
+The current verifier blocks these cases:
+
+- **All component instances, copies, main instances and component roots.** The
+  inspection cannot establish complete override state. Retaining links during a
+  copy is required, but it does not prove override fidelity.
+- **Groups without an explicit `maskedGroup` observation.** An absent mask flag
+  is unknown, not proof that the group is unmasked.
+- **Unknown text range/style observations**, including unobserved mixed-range
+  state, and any other unknown or missing required inspection field.
+- **Paths/vector shapes whose actual path content was not observed.** A path
+  type or matching raster export cannot establish the native path data.
+- Unsupported shape content, incomplete hierarchy, unobservable interactions or
+  missing pinned source render/dependency evidence.
+
+A selected screen containing one of these cases remains blocked with a reason;
+it cannot be finalized by waiving the finding or accepting equal pixels. Retain
+its native structure and source evidence, then obtain the missing observation or
+extend and validate inspection support before retrying. Do not detach components,
+flatten groups, remove styles or substitute raster images to bypass the gate.
+Simple screens whose required fields are fully observed can be assessed, but
+that is not a claim of complete support for every native Penpot feature.
+
+## Verify the package
+
+Supply a project-owned receipt list with explicit `sourceId` and
+`targetFrameId` values to `verify --receipts FILE`. Check release frame identities
+against the selected sources and retain immutable inspection/export evidence
+with exact paths and hashes. Compare source and release frames independently,
+including component/token identity and sizing
+behavior, and inspect stable exports. A current rendering cannot rewrite the
+bytes of an already recorded artifact. Native release objects remain mutable,
+including changes inherited through shared components and tokens. A later change
+is drift and needs a new reviewed generation, not a silent refresh of finalized
+evidence.
+
+New baseline evidence uses lossless WebP. Existing PNG baselines and image
+approvals remain valid in their original format. Conversion must be a deliberate
+migration with new evidence and review; never change approved bytes in place.
+Penpot can supply PNG during export, so conversion must retain exact dimensions
+and pixels. Quality 100 alone does not establish lossless encoding.
+
+The release needs matching exact-artifact review records and no unresolved
+blocking findings. Preserve the distinction between:
+
+- Map review: the owner's supplied words bind an exact contract hash.
+- Design image approval: the existing exact case/image approval protocol.
+- Technical verification: independently observed structure and image evidence.
+- Implementation acceptance: actual application behavior, browser evidence and
+  owner review, assessed separately after implementation.
+
+## Finalize and continue
+
+The release record progresses from `planned` through `awaiting-copy` and
+`verified` to `final`. Finalization records the reviewed release identity and
+immutable evidence. It must not promote missing evidence, waivers or inferred owner approval into a
+successful design gate. Finalized means the design package is ready to guide
+implementation; it does not mean the application has been built or checked.
+
+Finalization previews by default. Only use `finalize --apply --by OWNER --note
+EXACT_WORDS` after the owner has supplied those words for the exact candidate.
+Keep journal/run identity when reconciling interrupted remote work.
+
+Run checks again before using the package later. Missing or modified artifacts,
+changed map/source hashes and changed release evidence must remain visible as
+drift or incomplete evidence. A saved-source check does not contact Penpot;
+live freshness requires an explicit fresh observation. Context must identify
+its verification scope and any truncation. Release context includes actual frozen
+`mapContexts`, exact release-page `mapTargets`, independently pending implementation
+status and next actions. Linked detail navigation targets the release's own child
+boards; each child contract retains its separate review requirement.
+Its `proposedBaselines` is a configuration fragment with the release page, WebP
+format, baseline root and explicit target `frameId` entries. Review and merge it
+into the existing `baselines` block; context does not rewrite project config or
+approve the new target image identities.
+
+Use `penpair-handoff` with the approved integration context, then `penpair-verify`
+for the actual frontend. Keep those later implementation results separately;
+never rewrite the finalized design to match an implementation failure.
+
+The [reset-password example](../examples/design-release-maps/README.md) is an
+unapproved fixture showing decisions and gaps. It is not a finalized release or
+proof of a live Penpot copy.

package/docs/guide.md

@@ -10,6 +10,7 @@ consumer evidence.
 | Path | Documents |
 | --- | --- |
 | First run / shared file | [Choose an installation route](installation.md), [manual installation](getting-started.md), [team](team.md), [validation](validation.md) |
+| Intent / release | [Journey maps](journey-maps.md), [integration maps](integration-maps.md), [design releases](design-releases.md) |
 | Build / handoff | [Cookbook](cookbook.md), [workflow](design-workflow.md), [kit](build-kit.md), [file scripts](run-file.md), [handoff](handoff.md) |
 | Evidence | [Inspection](inspection.md), [advisory audits](audits.md), [snapshots](snapshots.md), [approvals](approvals.md), [coverage](coverage.md), [artifacts](artifacts.md) |
 | Integration | [Companion adapters](adapters.md), [MCP](mcp.md), [formats](formats.md), [extension trust](extensions-trust.md), [credentials](credentials.md), [token adapter](marwes.md) |
@@ -95,6 +96,7 @@ For registered writes, supply an explicit `verify({ inspect, apply, readback })`
 "baselines": {
   "page": "Candidate",
   "root": "tests/baselines",
+  "format": "webp",
   "threshold": 0.05,
   "frames": [
     { "frame": "F / candidates", "id": "candidates-desktop", "route": "candidates" },
@@ -107,8 +109,23 @@ For registered writes, supply an explicit `verify({ inspect, apply, readback })`
 - Each entry requires `frame` or `frameId` (or both). `frameId` is a board UUID, unique across entries, resolved anywhere on the configured page. Frames inside boards, such as release frames inside section boards, need `frameId`. Name-only entries still match top-level frames only.
 - With both fields, `frame` is an expected name: a changed name reports `renamed` and captures nothing for that entry. Review and update the expected name before retrying. ID-only entries use the board's current name in reports. A truncated page search (10,000 shapes) stops the capture instead of using a partial listing.
 - For example: `{ "frameId": "10216397-acdf-805e-8008-d69b71f841d4", "frame": "Login / Empty", "id": "login-empty", "route": "login" }`.
-- `id` names the image (`<id>.png`) and the check. `route` is the route in your app this frame is the design of; a frame without a route is exported but gets no check.
-- Without `--apply` the command only looks and reports each frame as `new`, `same`, `changed`, `unstable` (the export never settled) or `missing`/`renamed`. `--apply` writes new images, `penpair-baselines.json` (file, revision, sizes, hashes) and `reflection-cases.json`. A `changed` image is replaced only with `--apply --update`: that is the act of approving the new design, and the owner's call. The exit code is 2 when a design differs from its image, 3 when a frame is missing, renamed or unstable.
+- `id` names the image (`<id>.webp` for a new default reference; existing PNG references retain `.png`) and the check. `route` is the route in your app this frame is the design of; a frame without a route is exported but gets no check.
+- Without `--apply` the command only looks and reports each frame as `new`, `same`, `changed`, `unstable` (the export never settled) or `missing`/`renamed`. `--apply` writes new images, `penpair-baselines.json` (file, revision, sizes, hashes) and `reflection-cases.json`. A `changed` image is replaced only with `--apply --update` and matching exact-artifact owner approval (or an explicitly recorded waiver); see [approval records](approvals.md). The exit code is 2 when a design differs from its image, 3 when a frame is missing, renamed or unstable.
+
+New references default to static lossless WebP. `baselines.format` accepts
+`"webp"` or `"png"`; a command's `--format` overrides that choice for new
+references. Existing approved images keep their original encoding during ordinary
+captures and updates, even when config or `--format` selects another format.
+Approved byte hashes are never silently converted.
+
+To preview an explicit migration, run `penpair baselines --format webp
+--migrate-format`. After reviewing and recording matching new-format approval,
+apply it with `penpair baselines --format webp --migrate-format --apply --update`.
+`--migrate-format` requires explicit `--format`, and applying it requires
+`--update`. Use `approve --format webp` (plus the intended `--case`, when present)
+to review/record the same encoding; PNG approval cannot approve WebP bytes.
+See [approval and migration details](approvals.md#image-format-and-migration).
+Public `export` and `shots` remain PNG.
 
 The generated `reflection-cases.json` holds, per route, the viewports (the image's exact size) and the `visualSmoke` cases (review-only, `strict: false`). A Reflection config uses it like this; only the route's own expectations are written by hand:
 
@@ -169,6 +186,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`. 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).
+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; encoded image dimensions (PNG or lossless WebP) 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/handoff.md

@@ -29,6 +29,6 @@ An optional schema-1 component map names exact source identities:
 
 Names and equal pixels do not establish a mapping. There are no guessed library IDs in shipped maps: the adapter's native component catalogue awaits C1 proof. Static scalar props are owner-declared hints; text props resolve only explicit descendants of that instance. Missing text IDs stay unknown. No inferred click handlers, state transitions, keyboard behavior, accessibility roles, focus order or responsive layout claims are emitted. The current recorded state does not describe every breakpoint or theme.
 
-`spec check` regenerates from the supplied structured capture and map, detecting manual edits, source/revision changes and mapping changes (exit 2). It does not contact Penpot or establish current live freshness. A PNG export manifest alone cannot prove structural/text freshness; use a new structured inspection rather than treating an unchanged image as proof. Live human handoff/adoption acceptance remains pending under I12; native mapping generation remains gated under C1. JSON output uses the shared command envelope.
+`spec check` regenerates from the supplied structured capture and map, detecting manual edits, source/revision changes and mapping changes (exit 2). It does not contact Penpot or establish current live freshness. An image export manifest alone cannot prove structural/text freshness; use a new structured inspection rather than treating an unchanged image as proof. Live human handoff/adoption acceptance remains pending under I12; native mapping generation remains gated under C1. JSON output uses the shared command envelope.
 
 Owner review can be retained as an [exact-artifact approval record](approvals.md). Changed baseline references require matching supplied owner words or an explicitly labeled waiver; a comparison metric does not supply approval.