@penpair/web 0.2.0 → 0.3.0

package/docs/fixtures/browser-capture-2026-10-22.json

@@ -0,0 +1,217 @@
+{
+  "schemaVersion": 1,
+  "date": "2026-10-22",
+  "browser": "148.0.7778.96",
+  "kind": "local-browser-plumbing-trial",
+  "approvedDesignTrial": false,
+  "cases": [
+    {
+      "id": "1280-light-loaded",
+      "complete": true,
+      "diffPixelRatio": 0,
+      "clip": {
+        "x": 0,
+        "y": 64,
+        "width": 1280,
+        "height": 720
+      },
+      "fonts": [
+        {
+          "family": "Fixture",
+          "weight": "400",
+          "style": "normal",
+          "status": "loaded"
+        }
+      ],
+      "hoveredControls": 0,
+      "occlusion": {
+        "samples": 5,
+        "blocked": 0
+      }
+    },
+    {
+      "id": "1280-light-empty",
+      "complete": true,
+      "diffPixelRatio": 0,
+      "clip": {
+        "x": 0,
+        "y": 64,
+        "width": 1280,
+        "height": 720
+      },
+      "fonts": [
+        {
+          "family": "Fixture",
+          "weight": "400",
+          "style": "normal",
+          "status": "loaded"
+        }
+      ],
+      "hoveredControls": 0,
+      "occlusion": {
+        "samples": 5,
+        "blocked": 0
+      }
+    },
+    {
+      "id": "1280-dark-loaded",
+      "complete": true,
+      "diffPixelRatio": 0,
+      "clip": {
+        "x": 0,
+        "y": 64,
+        "width": 1280,
+        "height": 720
+      },
+      "fonts": [
+        {
+          "family": "Fixture",
+          "weight": "400",
+          "style": "normal",
+          "status": "loaded"
+        }
+      ],
+      "hoveredControls": 0,
+      "occlusion": {
+        "samples": 5,
+        "blocked": 0
+      }
+    },
+    {
+      "id": "1280-dark-empty",
+      "complete": true,
+      "diffPixelRatio": 0,
+      "clip": {
+        "x": 0,
+        "y": 64,
+        "width": 1280,
+        "height": 720
+      },
+      "fonts": [
+        {
+          "family": "Fixture",
+          "weight": "400",
+          "style": "normal",
+          "status": "loaded"
+        }
+      ],
+      "hoveredControls": 0,
+      "occlusion": {
+        "samples": 5,
+        "blocked": 0
+      }
+    },
+    {
+      "id": "390-light-loaded",
+      "complete": true,
+      "diffPixelRatio": 0,
+      "clip": {
+        "x": 0,
+        "y": 64,
+        "width": 390,
+        "height": 844
+      },
+      "fonts": [
+        {
+          "family": "Fixture",
+          "weight": "400",
+          "style": "normal",
+          "status": "loaded"
+        }
+      ],
+      "hoveredControls": 0,
+      "occlusion": {
+        "samples": 5,
+        "blocked": 0
+      }
+    },
+    {
+      "id": "390-light-empty",
+      "complete": true,
+      "diffPixelRatio": 0,
+      "clip": {
+        "x": 0,
+        "y": 64,
+        "width": 390,
+        "height": 844
+      },
+      "fonts": [
+        {
+          "family": "Fixture",
+          "weight": "400",
+          "style": "normal",
+          "status": "loaded"
+        }
+      ],
+      "hoveredControls": 0,
+      "occlusion": {
+        "samples": 5,
+        "blocked": 0
+      }
+    },
+    {
+      "id": "390-dark-loaded",
+      "complete": true,
+      "diffPixelRatio": 0,
+      "clip": {
+        "x": 0,
+        "y": 64,
+        "width": 390,
+        "height": 844
+      },
+      "fonts": [
+        {
+          "family": "Fixture",
+          "weight": "400",
+          "style": "normal",
+          "status": "loaded"
+        }
+      ],
+      "hoveredControls": 0,
+      "occlusion": {
+        "samples": 5,
+        "blocked": 0
+      }
+    },
+    {
+      "id": "390-dark-empty",
+      "complete": true,
+      "diffPixelRatio": 0,
+      "clip": {
+        "x": 0,
+        "y": 64,
+        "width": 390,
+        "height": 844
+      },
+      "fonts": [
+        {
+          "family": "Fixture",
+          "weight": "400",
+          "style": "normal",
+          "status": "loaded"
+        }
+      ],
+      "hoveredControls": 0,
+      "occlusion": {
+        "samples": 5,
+        "blocked": 0
+      }
+    }
+  ],
+  "negativeCases": [
+    "wrong theme",
+    "missing face",
+    "missing weight",
+    "scale mismatch",
+    "hover contamination",
+    "sticky shell occlusion"
+  ],
+  "delayedFontCase": "passed",
+  "baselineBytesPreserved": true,
+  "verdict": "owner-review-required",
+  "limitations": [
+    "Synthetic unapproved browser references; no Penpot target authorized",
+    "Occlusion is sampled; visual inspection remains necessary",
+    "MCP could not import local modules; tested provider using bundled Playwright and cached Chromium"
+  ]
+}

package/docs/fixtures/feedback-reproductions.md

@@ -0,0 +1,12 @@
+# Adoption feedback baseline
+
+Source: owner-supplied `feedback-0.2.0-2026-10-22.md`, consumer trial dated 2026-10-22. Installed Penpair 0.1.3 → 0.2.0; hosted plugin API 2.18.4. Repository baseline: `57f9782`, pnpm 10.12.1, TypeScript 5.6.3, Vitest 3.2.4. The consumer used Codex; its exact model/build and browser version were not recorded here and remain unknown.
+
+Portable reproductions execute real plugin bodies against minimal objects, with no copied consumer runners, logs, endpoints or private journals:
+
+- `packages/core/test/feedback-repro.test.ts`: idle native wait failure despite stable geometry; deferred revision during inspection (lease save and external edit both refuse); delayed page navigation. Initially expected failures identify the fixes still required.
+- `packages/marwes-ui/test/migration.test.ts`: identical values with legacy metadata/hash still produce an unexplained stale snapshot.
+
+Confirmed: native failure blocks fallback, metadata staleness lacks an explanation, a single page-switch delay is insufficient in the synthetic delayed editor. Unproven: the hosted lease/save race and the root cause of the consumer's multi-page failure. Synthetic reproduction is not live causal evidence.
+
+Copy `feedback-scratch.template.json` only after an owner confirms a disposable file. Fill public IDs from inspection; `null` values are deliberately not executable. Keep the personal MCP key outside this manifest. Before any write, inspect, pin a snapshot, apply once, independently read back and look at two exports. Repeat and change one heading; compare IDs, bindings and preservation fields.

package/docs/fixtures/feedback-scratch.template.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "authorized": false,
+  "fileId": null,
+  "pages": [{ "role": "build", "id": null }, { "role": "preservation", "id": null }],
+  "build": { "ownedPrefix": "penpair-feedback/", "flex": true, "text": true, "tokenBindings": ["typography", "fill", "rowGap"] },
+  "preserve": ["unrelated shape IDs and values", "token definitions and order", "global theme selections", "original visible page"],
+  "cases": ["desktop/light/loaded", "desktop/light/empty", "desktop/dark/loaded", "desktop/dark/empty", "mobile/light/loaded", "mobile/light/empty", "mobile/dark/loaded", "mobile/dark/empty"]
+}

package/docs/formats.md

@@ -18,3 +18,5 @@ This is a deliberately limited, validated subset of [DTCG Format 2025.10](https:
 The version-1 portable artifact retains typed values, paths, group metadata and explicit losses. Supported conversions are lossless and report an empty losses list. Unsupported input is rejected before output; it is never silently omitted. Bounds are 8 MiB input, 10,000 tokens, 32 group levels and 64 alias levels. This is offline exchange, not a Penpot token-set importer or an implementation of the complete DTCG resolver specification.
 
 Outside this subset: JSON Pointer/property references, group extensions/inheritance, deprecated metadata, root tokens, other composite types, named weights, nonnumeric color components, additional color spaces and native Penpot arithmetic expressions. Formula evaluation and px/rem conversion are intentionally absent: the tool preserves units rather than choosing a root font size. Native token snapshots retain their own richer values and formulas; using this exchange subset does not claim full standards conformance.
+
+`projected-theme-preview` v1 records deterministic offline values, source/theme/set identity and explicit unknowns; `nativeBindings:false` distinguishes it from live binding evidence. See [theme previews](theme-previews.md).

package/docs/getting-started.md

@@ -69,6 +69,8 @@ npx @penpair/web skills install
 This copies the rules the assistant follows (how to work safely in Penpot, and how to judge a screen) into `.skills/` and makes them visible to Codex and Claude Code. It prints a line for each to add to your `AGENTS.md`. Then fill in `.skills/penpair-design/references/project-facts.md` (your file, never replaced): the Penpot file, the token sets, the names you use, who approves.
 
 ### Every day
+Before moving into frontend implementation, choose the [companion adapters](adapters.md): use the library adapter for library-aware tokens/recipes and the recommended Reflection Check adapter for comparing the running frontend with approved designs. Installation and registration are the first steps; browser setup/provider evidence is a separate readiness stage.
+
 Open the file in Penpot, choose **File, MCP Server, Connect**, keep the tab visible, and start working with the assistant.
 
 ### Your safety net

package/docs/guide.md

@@ -1,6 +1,6 @@
 # Guide
 
-For this unreleased improvement branch, start with the [review guide](branch-review.md). Choose a tested workflow below, then use the extension and command references for the selected work. Live checks are identified separately.
+Choose a workflow below, starting with [companion adapters](adapters.md) when connecting a component library or verifying frontend code. Use the [review guide](branch-review.md) for the original improvement delivery; live checks are identified separately.
 
 ## Documentation map
 
@@ -9,7 +9,7 @@ For this unreleased improvement branch, start with the [review guide](branch-rev
 | First run / shared file | [Getting started](getting-started.md), [team](team.md), [trial runbook](trials.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 | [MCP](mcp.md), [formats](formats.md), [extension trust](extensions-trust.md), [credentials](credentials.md), [token adapter](marwes.md), [upstream draft](upstream/marwes-requests.md) |
+| Integration | [Companion adapters](adapters.md), [MCP](mcp.md), [formats](formats.md), [extension trust](extensions-trust.md), [credentials](credentials.md), [token adapter](marwes.md), [upstream draft](upstream/marwes-requests.md) |
 | Repair / operations | [Status/open](status.md), [troubleshooting](troubleshooting.md), [recovery](recovery.md), [backup](backup.md), [compatibility](compatibility.md), [releasing](releasing.md) |
 
 ## Extension points

package/docs/handoff.md

@@ -1,5 +1,7 @@
 # Derived design handoff
 
+For frontend implementation, pair this handoff with the recommended [Reflection Check companion](adapters.md#check-the-frontend-against-the-design). The handoff carries observed design facts; the companion connects approved cases to actual browser comparison evidence. Install/register the adapter and configure the project's real provider before claiming that comparison is ready.
+
 ```sh
 penpair spec --page Dashboard --frame FRAME_ID --out design/specs/dashboard.md
 penpair spec --from design/inspections/dashboard.json --map design/component-map.json --out design/specs/dashboard.md

package/docs/marwes-tokens.md

@@ -161,3 +161,16 @@ Each apply still checks file/source identity, original journal inputs and struct
 After `--include @kit`, opt into `--include @marwes-kit` for card, segmented, progress, icon-tile and stat-tile recipes. Project radius constants and progress sizing height remain explicit inputs; these recipes do not claim measured native-component parity. See [the build kit](build-kit.md).
 
 Component anatomy is a separate [measured three-component pilot](marwes-components.md); token sync does not establish component parity.
+
+## Metadata-only upgrades
+
+`tokens check --json` includes `reasons` with stable codes: `missing-snapshot`, `schema-migration`, `missing-ownership`, `content-drift`, `metadata-mismatch` and `package-mismatch`. `current:false` always explains why, even if `diff.identical:true`. Exit 2 is stale data; invalid/unreadable input is still an error.
+
+For a legacy snapshot, explicitly map **every** set name to `"adapter"` or `"project"` in `ownership.json`. Preview without connecting to Penpot:
+
+```sh
+penpair marwes tokens migrate --from design/legacy-tokens.json --ownership ownership.json
+penpair marwes tokens migrate --from design/legacy-tokens.json --ownership ownership.json --out design/migrated-tokens.json
+```
+
+Review values, themes and original provenance before adopting the migrated file. Do not infer ownership from name prefixes or regenerate away the source evidence.

package/docs/marwes.md

@@ -5,3 +5,5 @@
 The adapter consumes the adopting project's installed library/theme, and keeps project knowledge outside the neutral core. Project extras remain declared inputs. Computed component values are measurements in a theme/state/viewport; token matches are candidates, not inferred semantic bindings. Native library generation and human adoption acceptance remain pending until observed proof exists.
 
 `penpair marwes theme lint` compares declared project colors with installed defaults in light/dark mode. When primary changes, unchanged brand-family siblings with a distant hue become advisory warnings. Configure `marwes.themeLint.hueThresholdDegrees` (default 30) and exact `suppressions: [{theme:"light",token:"mw-color-border-brand",reason:"Intentional blue navigation"}]`. Suppressions remain visible. Transparent, non-literal and achromatic colors remain unknown; hue is neither a brand rule nor an accessibility score. Warnings return success and never rewrite themes or Penpot.
+
+[Projected theme previews](theme-previews.md) resolve declared light/dark values offline without changing active selections or claiming native per-frame theme bindings.

package/docs/plans/registry-polling-fix.md

@@ -0,0 +1,101 @@
+# Registry visibility polling — 2026-10-22
+
+Branch: `codex/release-registry-polling`. Base: reviewed 0.3.0 release on main,
+`4ea9975`. Repository package versions remain 0.3.0.
+
+## Failure and evidence
+
+The [publish job](https://github.com/niklas-westman/penpair/actions/runs/39801876697/job/119904592523)
+accepted `@penpair/core@0.3.0` at 15:17:02 UTC with signed provenance. npm explicitly
+reported that processing could take a few minutes. The script exhausted twelve
+five-second visibility checks and stopped at 15:18:05 UTC. No subsequent package
+was published by that run.
+
+An independent registry check then found core 0.3.0 visible, with Docker, the token
+adapter, the comparison adapter and web still absent. This establishes a
+processing-delay failure after an accepted upload; increasing a publish timeout
+or retrying the upload is unnecessary.
+
+## Completed checklist
+
+- [x] Extract a focused post-publish visibility helper. It checks immediately and
+  then at minute intervals within a ten-minute deadline for each uploaded package.
+- [x] Count registry query time toward the deadline and report elapsed time and
+  the next check/deadline in workflow logs.
+- [x] Bound each npm metadata process and HTTP request to 30 seconds or the
+  remaining deadline, with hidden npm retries disabled.
+- [x] Retain errors for failed lookups, explicit interrupted-release continuation,
+  dependency-order publishing and the configured short-name exception. The
+  visibility helper never uploads a package.
+- [x] Add virtual-clock tests for immediate/delayed visibility, exact minute
+  cadence, query duration, ten-minute expiry, remaining query budget, late
+  observations and registry errors. Query-boundary tests cover 404, authentication,
+  network errors and killed processes without touching npm.
+- [x] Document recovery and the order of operations before merging a tooling fix.
+
+## Validation
+
+- `pnpm check`: **658 tests** pass, including 15 new polling/query tests, along
+  with builds, typechecks, style/path checks and the six-package version guard.
+- `pnpm smoke:package`: all six tarballs install and run.
+- Final polling/logging tests pass independently using virtual time. No real
+  ten-minute sleeps or npm publication were used for testing.
+- `git diff --check` passes. The empty Changeset records repository tooling work
+  and does not propose a package version bump.
+
+## Current release recovery and remaining risk
+
+- [ ] On current `main`, dispatch **Publish reviewed Penpair release** with
+  `version=0.3.0` and `continue_release=true`, then approve `npm-release`.
+- [ ] Verify all five required scoped versions and provenance. The `penpair`
+  wrapper remains explicitly excluded.
+- [x] Polling fix merged as PR #5 before recovery completed; the early-merge recovery below supersedes the original merge order.
+
+The current main workflow still has its original one-minute visibility wait. If
+another accepted upload exceeds it, inspect the registry and explicitly continue
+the same version again. Rerunning the failed push workflow does not select
+continuation automatically.
+
+Finish recovery before merging this branch: its pending Changeset would block the
+manual release gate on main. This preserves the existing guard rather than
+changing it to accommodate an interrupted release. Ten minutes is a bounded
+window, not a guarantee that npm finishes processing; a failed lookup or an
+expired deadline still stops for inspection.
+
+## Early merge recovery
+
+PR #5 was merged on 2026-10-22 as `d339a19` while the 0.3.0 release remained
+interrupted. The new minute polling is now on main. The remaining pending note
+`bounded-registry-polling` has an empty release list and requests no version bump.
+The version-PR workflow therefore created no release PR. Manual continuation is
+blocked until that metadata has been consumed.
+
+The post-merge push workflow separately hit a GitHub API HTTP 500 while reading
+associated PRs; its publish job was skipped. That API error is distinct from the
+pending-note check. Manual dispatch uses the explicit-version path.
+
+- [x] Reproduce Changesets' consumption in an isolated workspace: only the empty
+  note is removed and every package stays at 0.3.0.
+- [x] Use the same Changesets CLI operation on the cleanup branch. Confirm no
+  package manifest, source version, lockfile, script or workflow changes.
+- [x] Run the unchanged `checkReleaseCommit` and manual workflow gate against the
+  resulting tree: both accept 0.3.0 with no pending notes. No publish command runs.
+- [x] Pass style/path checks and 47 existing Changesets, release-guard, polling,
+  registry-query and documentation tests. The cleanup changes only metadata/docs;
+  the previous 658-test run and six-package smoke cover the retained polling code.
+- [ ] Review/merge the metadata-only cleanup PR and pass its CI.
+- [ ] On the resulting main, dispatch **Publish reviewed Penpair release** with
+  `version=0.3.0`, `continue_release=true`, and approve `npm-release`.
+- [ ] Verify all five scoped packages and their provenance before marking the
+  release complete; the short-name exception remains enabled.
+
+The consumed tooling note is preserved here:
+
+> Allow npm processing time after successful uploads: check visibility immediately
+> and then once per minute within a ten-minute deadline per package. Bound metadata
+> queries and retain explicit recovery for interrupted releases. This changes
+> repository release tooling only.
+
+This cleanup completes an empty metadata item through Changesets. Package release
+notes and release guards remain intact; the interrupted version remains 0.3.0,
+with core skipped by explicit continuation once independently observed on npm.