@penpair/web 0.3.1 → 0.3.4

package/docs/pr-improvements.md

@@ -1,57 +0,0 @@
-# PR draft
-
-Target: `main` ← `codex/penpair-improvements`
-
-Title: **Add guarded design workflows and reviewed whole-family releases**
-
-## Description
-
-Penpot operations now pin the target file, stop ambiguous write retries, require
-positive readback evidence and record recovery progress. Structured inspection,
-token ownership/reconciliation, explicit design cases, approvals, snapshots and
-implementation handoffs make design-to-code work reproducible and reviewable.
-
-The branch also adds project MCP tools, reusable build recipes, focused agent
-skills, private credential references, advisory audits and clearer documentation.
-The neutral core and one-way package dependency rules remain enforced.
-
-Releases now use Changesets to collect notes into one **Release Penpair** PR. All
-six packages receive the same bump, including unchanged packages. Merging that
-reviewed version PR can trigger the existing guarded whole-family publisher using
-npm OIDC. Feature merges only collect notes. The owner-approved temporary
-`PENPAIR_RELEASE_EXCLUDE_PENPAIR=true` repository variable can omit only the
-blocked short-name wrapper from publishing, with explicit logs/summary and all
-other packages still required. All six repository versions continue together. A separate GitHub PR token is needed
-for automatic version-PR checks. Both automation paths remain disabled until
-owner activation; no package version is changed by this PR. The pending note
-proposes 0.2.0 in the separate generated version PR.
-
-## Validation
-
-- `pnpm check`: build, typecheck, 583 tests and lockstep/config checks.
-- `pnpm smoke:package`: all six tarballs install and run in clean consumers.
-- Real Changesets CLI tests verify unchanged-package bumps, highest-level
-  selection, changelogs, note consumption and exact workspace dependencies.
-- A disposable full version-wrapper rehearsal moves every package, changelog and
-  the source constant to 0.2.0; this branch remains at 0.1.3.
-- All three workflows pass actionlint 1.7.12 and parsed permission/gate checks.
-- Gate tests cover ordinary pushes, exact merged version PRs, manual confirmation,
-  pending notes, malformed auth evidence and workflow permission separation.
-- Detached-checkout regression runs the exact CI Changesets command against the
-  base SHA and verifies consumed-note version PRs through their dedicated path.
-  Version-PR creation also supports a main-only manual trigger.
-
-## Open acceptance and activation
-
-- Hosted export/import restore proof (G3), two-person live trials (I12), and
-  real component measurement/override proof (C1) remain unchecked by request.
-  Native component generation remains gated.
-- Configure GitHub main/environment protection, the PR token and trusted
-  publishers for every npm package before enabling release automation. Verify
-  the previously refused short name and any unpublished package bootstrap.
-- npm publication is sequential; partial failures require explicit recovery.
-- No remote policy, live Penpot mutation, consumer edit, upstream message,
-  release, tag or deployment was performed.
-
-Review details: [branch review](branch-review.md), [living checklist and
-reports](improvements.md), [release activation](releasing.md#one-time-owner-activation).

package/docs/tradient-followups.md

@@ -1,77 +0,0 @@
-# Tradient adoption proposal — owner review required
-
-This is a scoped handoff, not an applied consumer change. Read-only inspection on 2026-10-21 found local `main` at `3aa7a1c` in `/Users/niklaswestman/Documents/tradient/CODE/tradient`. The pre-existing untracked `penpot-poc/` folder remains untouched. No consumer files, commits, configuration, Penpot data or deployment state were changed.
-
-## Evidence and corrections
-
-- Root dev dependencies pin `@penpair/web` and `@penpair/marwes-ui` to `0.1.3`; the primary UI uses `@marwes-ui/react` `^1.11.0`.
-- Root package scripts contain no `design:*` entries. `.env.example` has no `PENPAIR_MCP_URL` entry; no personal key file was read.
-- `penpair.config.json` names `Tradient`, the `packages/frontend-evolved` app, `tradientLight`/`tradientDark` from its `src/theme.ts`, and `design/marwes-tokens.snapshot.json`. It has neither a file pin nor baselines.
-- The committed snapshot is schema 1 with the generated Core/Dark and Tradient Light/Dark sets. It declares no project extra set or ownership map.
-- `packages/frontend-evolved/src/components/organisms/sidebar-nav.tsx` already exports `SidebarNav`. Reuse and assess that component before proposing another sidebar. A missing upstream-library primitive does not mean the consumer lacks one.
-- The existing API workflow uses Node 20, pnpm 10.12.1 and a frozen lockfile install. Its legacy-frontend typecheck is a separate migration concern; this design-token proposal does not change that job's unrelated behavior.
-
-The new commands in this improvement branch are unreleased. A `0.1.3` version string alone does not prove the installed tarball contains these changes. First use an owner-reviewed release or an isolated packed-branch trial; do not edit the consumer to depend on unreviewed branch behavior.
-
-## Proposed small adoption change
-
-- [ ] Owner authorizes a separate consumer branch and confirms the target checkout/worktree. Preserve `penpot-poc/` and every unrelated change.
-- [ ] Add these entries to the existing root `scripts` object:
-
-```json
-{
-  "design:doctor": "penpair doctor",
-  "design:tokens:check": "penpair marwes tokens check"
-}
-```
-
-- [ ] After the existing frozen install in the PR validation workflow, add this offline step:
-
-```yaml
-- name: Check design token snapshot
-  run: pnpm run design:tokens:check
-```
-
-No Penpot key, browser or design-server connection belongs in this CI check. The initial adoption must regenerate the snapshot with the reviewed tool version before enabling a gate that would fail on the old expectation.
-
-- [ ] Add only this empty documentation entry to `.env.example`, with a comment that each person creates their own key and stores it locally:
-
-```dotenv
-# Personal MCP endpoint; keep its value in ignored local configuration.
-PENPAIR_MCP_URL=
-```
-
-- [ ] After installing the reviewed file-guard build, run `penpair connect --pin-file` while the owner independently confirms the intended open file. Commit the public file ID in `penpair.config.json`; keep personal keys out of the proposal, chat, diff and logs. Check `doctor --json` and exercise a wrong-file refusal on scratch files.
-- [ ] Reconcile the installed skill path and project-facts reference with the chosen agent client. Use the owned instruction integration rather than replacing unrelated `AGENTS.md` text. Keep file identity in the typed config; facts may point to it.
-- [ ] Declare the project-owned page/radius tokens under `marwes.extras` after reviewing their formulas or C1 measurements. Do not silently promote the field-note constants to authoritative component measurements.
-- [ ] Regenerate the schema-2 token snapshot, review ownership and value changes, then run `design:tokens:check`. Inspect `tokens push` before any separately authorized Penpot mutation. Differing designer values require an explicit adopt/overwrite decision; prune is not a cleanup shortcut.
-
-## Baseline and implementation follow-up
-
-- [ ] Owner approves the intended `Dashboard / Desktop` frame and confirms its exact page, route and identity. No approval was inferred from the original brief.
-- [ ] Add a baseline block only after that decision. The shape below is a merge template; replace the route with the application's actual route key:
-
-```json
-{
-  "baselines": {
-    "page": "Dashboard",
-    "root": "design/baselines",
-    "frames": [
-      { "frame": "Dashboard / Desktop", "id": "dashboard-desktop", "route": "OWNER_CONFIRMED_ROUTE" }
-    ]
-  }
-}
-```
-
-- [ ] Inspect `baselines`, explicitly authorize the first `--apply`, export/look twice, and commit only the reviewed reference generation. Add rich case metadata and required coverage once state/theme/fixture setup is specified. Rich cases remain pending implementation-provider mappings until those hooks exist.
-- [ ] Establish one working implementation comparison through the existing baseline route before expanding the consumer handoff. Capture stable fonts/data and show desktop/mobile plus one non-happy state. Browser interaction and accessibility checks remain separate.
-- [ ] Review the primary/border-brand/link/focus theme family with C4 lint and actual light/dark screenshots. Confirm supported theme-input fields before editing `src/theme.ts`; keep intentional blue accents when the owner chooses them. Regenerate/review the snapshot after any change.
-- [ ] Compare the app's Marwes 1.11.0 appearance against an isolated 1.4.1 reference when an owner-approved old fixture is available. Do not downgrade or alter the current consumer just to obtain that comparison.
-- [ ] Implement new UI only in `packages/frontend-evolved`, reusing its existing SidebarNav and library primitives. Follow its structure/styling/data patterns and preserve its product semantics. D1 supplies explicit behavior/component metadata; a visual frame alone cannot make this implementation mechanical.
-- [ ] Migrate useful build bodies into reviewed files or registered operations. Split pure helpers, inspection, idempotent mutation and independent readback. Use `@kit` and explicit adapter recipes, stable owned identities and full source hashes; do not copy the throwaway runner's path or name-based deletion shortcuts.
-
-## Validation for that future consumer branch
-
-Run the new offline design check, the primary app's matching tests/typecheck/build, whitespace checks and a browser review for UI changes. Follow the consumer's own pre-push review instruction before a later authorized push or PR. No deployment, AWS write, publishing or external message is part of this handoff.
-
-Owner decisions still needed: which reviewed Penpair build to adopt, the confirmed Penpot file, initial frame approval/route, project-extra constants, intentional theme accents and scope of Dashboard implementation. This proposal keeps those decisions reviewable without applying them.

package/docs/trials/report-template.json

@@ -1,76 +0,0 @@
-{
-  "schemaVersion": 1,
-  "kind": "human-trial",
-  "status": "not-run",
-  "commit": null,
-  "artifacts": [],
-  "participants": [],
-  "environment": {
-    "os": null,
-    "node": null,
-    "packageManager": null,
-    "agentClient": null,
-    "skillPath": null,
-    "penpotDeployment": null,
-    "apiVersion": null
-  },
-  "target": {
-    "ownerAuthorized": false,
-    "fileIds": [],
-    "pageIds": []
-  },
-  "metrics": {
-    "timeToDoctorGreenMs": null,
-    "interventions": null,
-    "understandableFailures": null,
-    "eligibleTokens": null,
-    "boundTokens": null,
-    "inspectionComplete": null,
-    "verifiedOutcomes": null
-  },
-  "exercises": {
-    "onboarding": {
-      "status": "not-run",
-      "evidence": [],
-      "findings": null
-    },
-    "skillDiscovery": {
-      "status": "not-run",
-      "evidence": [],
-      "findings": null
-    },
-    "smallBuild": {
-      "status": "not-run",
-      "evidence": [],
-      "findings": null
-    },
-    "wrongFile": {
-      "status": "not-run",
-      "evidence": [],
-      "findings": null
-    },
-    "writerConflict": {
-      "status": "not-run",
-      "evidence": [],
-      "findings": null
-    },
-    "recovery": {
-      "status": "not-run",
-      "evidence": [],
-      "findings": null
-    },
-    "implementationRoute": {
-      "status": "not-run",
-      "evidence": [],
-      "findings": null
-    },
-    "cleanup": {
-      "status": "not-run",
-      "evidence": [],
-      "findings": null
-    }
-  },
-  "blockers": [],
-  "backlogChanges": [],
-  "ownerReviewed": false
-}

package/docs/trials.md

@@ -1,41 +0,0 @@
-# Human trial runbook (I12)
-
-Status: prepared, **not run**. Niklas asked to finish branch code and leave live trials pending (2026-10-21). Offline fixtures exercise control flow, not people, real servers, visual parity or adoption. Keep I12 unchecked until two actual people complete the exercises and review one real design-to-code route.
-
-## Preparation
-
-Use two consenting people with separate fresh project folders, personal connections and independently owned credentials. The owner must explicitly authorize two disposable Penpot files and identify their public file/page IDs. Never infer authorization from a file name. Keep the editor visible. No telemetry runs in the background.
-
-Record commit, tarball SHA-256 hashes, package versions, OS, Node/package manager, actual agent client, Penpot deployment and observed API version in [report-template.json](trials/report-template.json). This branch still reports 0.1.3: the version alone cannot distinguish it from the registry release. Use a reviewed release or pack the complete branch package set. When installing command/adapter tarballs, override `@penpair/core` to the matching local core tarball, as `scripts/smoke-package.mjs` does. Installing only the web tarball may silently resolve an older registry core.
-
-Start the clock before setup. Each person enters their own secret through the documented hidden connection flow; never collect the key in a report, shell transcript or screenshot. Run onboarding and `doctor --json`, then configure the owner-confirmed file pin. Record interventions and exact understandable or confusing failures, with credentials redacted.
-
-Preview `penpair skills install --dry-run` before installation. Test discovery separately in each actual agent client. Codex scans repository `.agents/skills` from the current folder to the repository root and supports symlinked skill folders; check the skill selector and invoke the skill explicitly before assessing automatic discovery. See [official skill documentation](https://learn.chatgpt.com/docs/build-skills). Record the actual installed path, client version and observed discovery; do not generalize one client's result to another.
-
-## Exercises
-
-1. Build a small card using the [reviewed Hello-card example](../examples/hello-card/README.md), or use `probe --deep --kit --write` on an authorized scratch file with active typed tokens and an available font. Inspect the private preview. Record eligible/bound token counts with the inspected population and whether traversal was complete. The probe removes its temporary root; any persistent example needs an explicit owner-reviewed cleanup.
-2. Pin file A, open disposable file B, and run `examples/trials/wrong-file-read.js` through `run-file` without a page argument. Expect a file-guard refusal before the body. Basic `pages` inspection only warns by design, so it is not the hard-block exercise. Restore A afterward.
-3. Use a dedicated empty page in A. Copy `examples/trials` into each scratch project. Person A runs the holder below with a fresh marker. Person B attempts the same operation from their own project/key with a different fresh marker while A is writing. Record refusal during the lease, server serialization, overlap, unsupported API or unknown, and timings. Same-checkout tests only prove a local lock; they do not prove cross-client atomic exclusion. A busy attempt can have an uncertain journal even before applying: inspect the recorded steps and retain the actual diagnostic.
-4. Run the recovery example below with `failAfterWrite=true`. It deliberately throws after creating a small owned frame. Record the uncertain run ID and frame ID. Use **the same files and parameters** with explicit `--resume RUN_ID`; independent readback must reconcile the existing frame without a duplicate. Export twice, look at the image, and record the result. A fresh run is not recovery. A renamed/duplicated marker or changed source requires inspection rather than an automatic retry.
-5. Exercise one real implementation route through existing baselines and the Reflection handoff. Obtain explicit frame approval; hold fonts and fixture data stable. Record actual browser comparison and adoption findings. Rich coverage cases require the D4 hooks and cannot be represented as successful default-state checks. Human adoption remains a gate before declaring the C1/D1/E1 expansion accepted.
-
-```sh
-penpair run-file examples/trials/hold-writer.js \
-  --inspect examples/trials/hold-inspect.js --readback examples/trials/hold-readback.js \
-  --param fileId=OWNER_CONFIRMED_FILE --param pageId=OWNER_CONFIRMED_EMPTY_PAGE \
-  --param marker=FRESH_PERSON_A_MARKER --param holdMs=30000 \
-  --apply --timeout-ms 45000
-
-penpair run-file examples/trials/recovery-build.js \
-  --inspect examples/trials/recovery-inspect.js --readback examples/trials/recovery-readback.js \
-  --param fileId=OWNER_CONFIRMED_FILE --param pageId=OWNER_CONFIRMED_PAGE \
-  --param name=RecoveryTrial --param marker=FRESH_RECOVERY_MARKER \
-  --param failAfterWrite=true --apply
-```
-
-The holder intentionally waits to create a contention window; it is not layout settling. It creates no design nodes but records a `penpair/trial-hold-MARKER` file metadata record with holding/complete state. A partial marker is evidence requiring inspection. A completed marker makes the same operation a verified no-op; use a fresh marker for each new contention exercise. The recovery example leaves an owned frame intentionally. Remove only explicitly confirmed owned IDs/markers with a reviewed operation, or let the owner discard the dedicated scratch files.
-
-## Evidence and completion
-
-Copy the template under ignored `.penpair/trials/`. Unobserved metrics remain null, not zero. Record time to doctor-green, human interventions, failure comprehension, binding coverage, independent verified outcomes, visual review, blockers and resulting backlog changes. Capture screenshots only after closing secret-entry panels. Commit only owner-reviewed redacted summaries, never keys, raw connection transcripts or private journals. There is no completed human report yet.

package/docs/upstream/marwes-1.11.0-evidence.json

@@ -1,15 +0,0 @@
-{
-  "schemaVersion": 1,
-  "kind": "upstream-request-evidence",
-  "observedAt": "2026-10-21",
-  "method": "read-only installed package declarations and source maps",
-  "liveMeasurements": false,
-  "artifacts": [
-    {"package":"@marwes-ui/react","version":"1.11.0","artifact":"dist/index.js.map","sha256":"5e8dfda3f704a98c07dbb0dba288fd4df8fd0adb8fda07a2507bfa09b9e73791","sources":["../src/components/stat-tile/stat-tile.tsx","../src/components/card/card.tsx"]},
-    {"package":"@marwes-ui/core","version":"1.11.0","artifact":"dist/index.js.map","sha256":"29fd794b744da873b63222bc3827870e7031753d3137cc28415aa14acf3e581d","sources":["../src/components/atoms/stat-tile/stat-tile-recipe.ts","../src/components/atoms/stat-tile/stat-tile-a11y.ts","../src/components/atoms/card/card-recipe.ts","../src/theme/theme-vars.ts"]}
-  ],
-  "facts": ["StatTile trendValue and trendDirection are optional", "StatTile omits arbitrary children", "StatCardProps aliases CardProps", "CardProps accepts children", "No Sidebar or SidebarNav in the inspected React export list"],
-  "candidateEdgeCases": ["Numeric zero trend is subject to a truthiness condition", "Only string trendValue is passed to the core accessible-label recipe"],
-  "notEstablished": ["Latest upstream feature state", "Rendered numerical component values", "Browser/accessibility behavior", "Native Penpot override preservation"],
-  "sent": false
-}

package/docs/upstream/marwes-requests.md

@@ -1,35 +0,0 @@
-# Marwes requests for owner review — 2026-10-21
-
-Status: **draft, unsent**. This document does not authorize an email, issue, package change or consumer edit. Review against the maintainer's current version before sending. Evidence is the installed 1.11.0 React/core package source and Claude's dated original trial notes; no new live component measurements were taken.
-
-## Correct the starting assumptions
-
-- `StatTileProps.trendValue` and `trendDirection` are already optional in React 1.11.0. The source conditionally omits the trend region. Drop the request to add optional trend support. A missing trend in a Penpot helper is an adapter/composition issue until proven otherwise.
-- `StatTile` omits arbitrary `children`, but `StatCardProps` already aliases `CardProps`, which accepts children. Ask whether composing a sparkline in StatCard is the intended route before requesting another slot/API.
-- The installed React export list has no Sidebar/SidebarNav symbol. The consumer already implements its own `SidebarNav`; a new consumer sidebar is unnecessary. An upstream navigation primitive is an optional library discussion, not a blocker for that implementation.
-- Card/StatTile radii and typography values in the original brief are historical observations in one project theme/viewport/state. They are not newly verified universal library constants. The C1 measurement pilot still needs a real fixture and native instance-override proof.
-
-## Prioritized requests
-
-| Priority | Draft request | Evidence and acceptance |
-| --- | --- | --- |
-| P1 | Expose stable component anatomy/measurement metadata and fixture selectors. | Core 1.11.0 recipes expose data-component/slot class names, but those are not a complete versioned measurement contract. Start with Button/Card/StatTile across explicit light/dark/state/viewport fixtures. Ask for documented stable selectors and supported measurements; preserve actual semantic token names instead of inverse-matching equal colors/radii. |
-| P1 | Document or expose component-derived radius and typography roles. | The source theme variable inventory includes general radius/radiusButton and typography scales. Claude reported Card radius 8, StatTile radius 24 and StatTile value 28/600/-0.84 in its trial context. Ask for the relationship to theme inputs and supported semantic roles; let new measurements establish values before proposing named tokens or formulas. Acceptance includes theme changes and explicit fallback constants. |
-| P2 | Clarify the supported StatTile/StatCard composition route for charts. | StatTile has a fixed typed body; StatCard accepts normal Card children. Ask for a documented chart composition recipe first. Add a new slot only if the existing composition cannot preserve intended layout, keyboard behavior and semantics. |
-| P2 | Discuss an upstream sidebar/navigation primitive if several consumers need the same contract. | No export in the inspected 1.11.0 React declarations; the consumer's existing SidebarNav already supplies its local implementation. Acceptance should cover active state, keyboard/focus semantics, responsive collapse and theme roles. Collect a reusable requirement before proposing upstream code. |
-| P3 | Check numeric-zero trend rendering and trend accessible-label input. | React source accepts ReactNode, renders trend with a truthiness check, and passes only string values to the core trend-label recipe. Ask for a focused test of `trendValue={0}` and numeric content. This is a source-based candidate edge case, not an observed browser/accessibility failure. |
-
-## Review/send checklist
-
-- [ ] Owner selects which requests are useful and approves exact wording.
-- [ ] Maintainer/current-version check confirms the requested capability is still absent or undocumented.
-- [ ] C1 fixture captures exact theme, viewport, state, fonts and source version for numerical claims.
-- [ ] Attach only owner-reviewed, non-private evidence and a minimal reproduction.
-- [ ] Owner decides whether to send; no message or issue has been created here.
-- [ ] Record maintainer response and resulting backlog changes after an authorized exchange.
-
-## Reproduction evidence
-
-Read [the source inventory](marwes-1.11.0-evidence.json). It records package versions and source-map hashes, with source paths within those maps. It contains no consumer designs, credentials or private project source. Reproduce with the same package artifacts and inspect the named source entries; rendered behavior still needs a real fixture.
-
-These corrections strengthen Claude's brief: the useful requests are about reproducible anatomy and explicit semantic contracts. Existing optional props and consumer components should be reused before asking for duplicate capabilities. Equal measured values alone cannot establish token semantics or make design-to-code behavior mechanical.