@penpair/web 0.3.6 → 0.4.0

package/docs/journey-maps.md

@@ -0,0 +1,139 @@
+# Journey maps
+
+A journey map records what a person is trying to accomplish, which states they
+encounter, and the decisions still needed before implementation. It is a
+project-owned contract that later agents can read without recovering earlier
+chats. Use an [integration map](integration-maps.md) to connect the journey to
+application structure, and a [design release](design-releases.md) to freeze a
+reviewed design handoff.
+
+## Local commands
+
+```sh
+penpair journey-map check --from design/journeys/reset-password/map.json
+penpair journey-map render --from design/journeys/reset-password/map.json --out design/journeys/reset-password/rendered
+penpair journey-map context --from design/journeys/reset-password/map.json --out design/journeys/reset-password/context.json
+```
+
+Use your project's local command, such as `pnpm exec penpair`, when installed as
+an application dependency. Rendering with `--out` writes local derived artifacts;
+it does not publish into Penpot. Context is intended for reviewed inputs; drafts
+must be explicit and cannot imply readiness.
+
+## Start from observed intent
+
+Inspect the actual frames and existing application before drafting. Record the
+user goal, entry points, successful outcome, alternate paths and recovery. Use
+stable requirement and node IDs so a finding can refer to the same requirement
+through review and implementation. A frame establishes visible design facts;
+it does not establish what a button does, how an API behaves or how keyboard
+focus moves.
+
+Every node, edge and requirement declares its origin:
+
+| Origin | Meaning |
+| --- | --- |
+| `observed` | Directly supported by the referenced design, code or evidence |
+| `proposed` | An AI or designer recommendation awaiting a decision |
+| `owner-decision` | A decision actually supplied by the owner |
+| `unknown` | Missing information; retain it as a question |
+
+An origin is provenance, not approval. In particular, an `owner-decision` label
+cannot replace a review record binding the owner's actual words to the exact
+contract hash. Do not turn guesses into observations or invent approval notes.
+
+## Keep the flow readable
+
+Use short, specific node titles (`label`), optional one-line `summary` and longer
+`description` text for evidence, decisions and unknowns. The map itself also
+accepts optional `summary` and `description`. Origin badges distinguish observed
+facts from proposals without repeating that status in every title. Optional
+semantic `icon` values use fixed native vectors. Full notes remain available
+below the flow and in Markdown/context; legacy contracts need no new fields.
+See [titles and descriptions](integration-maps.md#readable-titles-and-descriptions).
+These optional fields are part of reviewed canonical intent, so changing them
+needs renewed approval.
+
+## Contract and review
+
+The schema-1 JSON contract contains `kind: "journey-map"`, `id`, `title`, `goal`,
+`sources`, `nodes`, `edges`, `requirements` and `findings`. Sources retain their
+SHA-256 and available path/file/page/frame/revision identity. Nodes and edges
+carry readable labels and stable IDs; requirement links connect them to the
+intended outcomes. Open blocking findings keep readiness pending. Resolving a
+finding requires an explicit resolution, rather than deleting its history.
+
+The `journey-map` command family supports checking, rendering, publishing,
+importing managed edits as proposals, accepting proposals, recording supplied
+approval, and producing bounded context. Consult the installed command's help
+for arguments. Checking and rendering locally do not approve or publish a map.
+Native publication is a Penpot write and needs the normal inspection, pinned
+snapshot, one idempotent write, independent readback and inspected stable export.
+Check the exported typeface against the canvas: a font available to the editor
+can still be unavailable to its exporter. Correct font metadata and identical
+consecutive exports do not prove font fidelity. Visible font substitution needs
+correction before visual approval.
+
+The contract is authoritative; Mermaid and native Penpot objects are derived
+views. Managed native edits become a proposal against the exact prior contract
+hash. Review the diff and accept it explicitly before regenerating dependent
+views. A changed label or connector must not silently rewrite accepted intent.
+An old proposal cannot overwrite a newer contract.
+
+Owner review is a separate `artifact-review` record containing the artifact
+identity, exact hash, supplied words, identity, date and record hash. Review is
+not authenticated identity. Changed contracts or source hashes need fresh review;
+matching saved inputs do not prove the live file is unchanged.
+
+## Review gates
+
+1. **Intent ready:** the goal, success/recovery paths, evidence and unknowns are
+   explicit. Blocking questions are answered or remain visibly blocking.
+2. **Contract reviewed:** the owner reviewed the exact map and supporting
+   decisions. Technical checks and a neat diagram do not supply acceptance.
+3. **Handoff ready:** the integration map references this exact journey hash,
+   required design cases exist, and outstanding implementation work is explicit.
+
+## Reset-password example
+
+The [worked example](../examples/design-release-maps/README.md) describes an
+illustrative reset flow. An observed confirmation frame is distinct from a
+proposed submission transition and an unknown expiry policy. The example is
+unapproved and contains no fabricated inspection or owner evidence.
+
+Keep loading, empty, error and success states proportionate to the feature.
+Capture keyboard entry, focus movement, error announcements and responsive
+behavior as explicit requirements or unknowns. The map does not establish that
+any of these behaviors has been implemented or tested.
+
+Contracts are bounded to 16 MiB, 1,000 nodes and 2,000 edges. Context has a
+128 KiB limit and reports omissions explicitly. Source paths remain inside the
+project. Labels and descriptions are escaped literal data in generated views.
+
+Every local requirement must be connected through node/edge `requirementIds`.
+A readable graph with unmapped requirements remains incomplete for readiness.
+Drawing plans also refuse complete native publication above a 16,384 px axis or
+64 KiB serialized plan size; split large maps into reviewable parts. Semantic
+native imports retain a bound adjacent `.native.json` observation and require
+fresh live readback during acceptance. Pure geometry changes instead produce a
+presentation proposal, preserve canonical intent and require fresh visual review.
+
+For explicit decomposition, use [linked detail maps](integration-maps.md#linked-detail-maps).
+Journey details remain journey contracts, with independent publication and review;
+parent approval does not cover a child map automatically.
+
+## Publication recovery
+
+After an uncertain write, inspect the actual target and retained run first. Resume
+the original journal explicitly, keeping the original contract, sources and
+target flags (including whether `--board-id` was omitted):
+
+```sh
+penpair journey-map publish --from design/journeys/reset-password/map.json \
+  --page-id PAGE_ID --apply --resume RUN_ID
+```
+
+Use the original `--board-id` and `--projection` options if they were supplied.
+Resume independently reconciles readback and exports; it does not blindly repeat
+the write. Changed input or code signatures must refuse reuse. Inspect again and
+start a new explicitly authorized run when needed; do not bypass those guards.

package/docs/releasing.md

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

package/examples/design-release-maps/README.md

@@ -0,0 +1,72 @@
+# Reviewed-map workflow example
+
+These contracts describe a **synthetic, unapproved** reset-password feature.
+They are valid draft inputs, not a real Penpot inspection, code audit, owner
+review or finalized design release. `sample-source.md` is their only observed
+source. Proposed application architecture and unknown policy stay labeled.
+
+From the repository root:
+
+```sh
+pnpm build
+node packages/web/dist/cli.js journey-map render --from examples/design-release-maps/journey.json
+node packages/web/dist/cli.js integration-map render --from examples/design-release-maps/integration.json
+```
+
+Use the installed CLI entrypoint when working from a packaged installation.
+Rendering is offline and establishes neither owner approval nor live fidelity.
+Checks/context should retain the open blockers and missing reviews; this fixture
+is intentionally not ready for implementation or release finalization.
+
+## Read the map
+
+```mermaid
+flowchart LR
+    Entry["Enter email"]
+    Confirm["Check your email"]
+    Error["Retry request"]
+    Entry -->|"Success"| Confirm
+    Entry -->|"Failure"| Error
+    Error -->|"Retry"| Entry
+```
+
+Each JSON node uses a concise `label` as its title, a one-line `summary`, a
+longer `description` for evidence and decisions, and a fixed semantic `icon`.
+Native cards show the compact title/summary with origin badges; detailed notes
+retain the full explanation below the flow. The short labels above do not
+change provenance: entry/confirmation are observations of the synthetic text,
+while success, failure and retry behavior remain proposals. Policy and actual
+code/browser evidence remain unknown.
+
+This short illustration explains the intended flow; the JSON contract remains
+authoritative. Generate full Mermaid/native drawing plans from it rather than
+editing this illustration as if it updated the contract. A native drawing is
+editable, but managed semantic changes must be imported as proposals, reviewed,
+accepted against their base hash and approved again.
+
+| Requirement | Intended result | Hypothetical mismatch | Next action |
+| --- | --- | --- | --- |
+| `reset-error-retry` | Keep the address after a failed request and allow retry | An implementation clears it and makes the person retype it | Confirm the proposed behavior, then test a real failed request and retry. This row is not observed project evidence. |
+
+## Three review gates
+
+1. **Intent ready:** inspect real source frames; decide request, disclosure,
+   expiry, recovery, loading and focus behavior. Do not convert unknown policy
+   into an inferred security rule.
+2. **Design package reviewed:** replace synthetic sources with actual inspection
+   paths/hashes, review the exact journey/integration maps, assemble target
+   native frames in `release/<product-version>`, verify fidelity, then obtain
+   the actual owner words for the exact release candidate. Source image
+   approval does not approve new target frame identities.
+3. **Implementation accepted:** implement against that stable context, observe
+   actual route/state/fixture behavior, compare browser images, test recovery
+   and accessibility, and review the results. Finalized design alone cannot
+   satisfy this gate.
+
+No release plan with invented file IDs, frame IDs, transfer receipts or owner
+words is included. Create a plan only after inspecting the actual pinned file
+and selecting sources. The [release guide](../../docs/design-releases.md)
+describes the native copy, immutable evidence and later drift checks.
+
+New baselines default to static lossless WebP. Preserve existing approved PNG
+bytes; format migration is explicit and requires normal exact-byte review.

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

@@ -0,0 +1,181 @@
+{
+  "schemaVersion": 1,
+  "kind": "integration-map",
+  "id": "reset-password-integration",
+  "title": "Reset implementation",
+  "goal": "Connect the proposed reset flow to implementation responsibilities without inventing existing code.",
+  "sources": [
+    {
+      "id": "sample-brief",
+      "kind": "other",
+      "path": "examples/design-release-maps/sample-source.md",
+      "sha256": "ab97f0a30f066e9a9f2689d1624608ea91287751cbc6a613542c0e97de187a96"
+    }
+  ],
+  "journey": {
+    "path": "examples/design-release-maps/journey.json",
+    "sha256": "956fbe3e9d4eb3519d714912ec89bfaedd2a8c2b8882d06dc5ee9c4c279439a9"
+  },
+  "nodes": [
+    {
+      "id": "reset-route",
+      "label": "Reset route",
+      "kind": "route",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-entry"
+      ],
+      "summary": "Open /reset-password to begin the flow.",
+      "description": "Proposed route responsibility: enter the reset flow using the existing application router. The route and surrounding navigation have not been inspected. Reuse the actual project structure rather than treating this illustrative path as an approved architecture decision.",
+      "icon": "code"
+    },
+    {
+      "id": "reset-form",
+      "label": "Reset form",
+      "kind": "component",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-entry",
+        "reset-error-retry"
+      ],
+      "summary": "Collect an address and retain it on retry.",
+      "description": "Proposed form responsibility: collect the address, follow agreed validation and preserve input during recoverable failure. Inspect existing components before choosing an implementation. Form semantics and behavior need explicit review and real browser evidence.",
+      "icon": "screen"
+    },
+    {
+      "id": "reset-mutation",
+      "label": "Reset service",
+      "kind": "data",
+      "origin": "unknown",
+      "requirementIds": [
+        "reset-request",
+        "reset-expiry"
+      ],
+      "summary": "Agree the request and response contract.",
+      "description": "The endpoint, request payload, validation, response policy and expiry behavior are unknown. Obtain the actual project API and product decisions before implementation. This node does not claim that a service exists or prescribe a new backend.",
+      "icon": "service"
+    },
+    {
+      "id": "reset-feedback",
+      "label": "Request feedback",
+      "kind": "state",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-error-retry",
+        "reset-confirmation",
+        "reset-focus"
+      ],
+      "summary": "Show confirmation or a recoverable error.",
+      "description": "Proposed feedback responsibility: present the agreed confirmation state after an accepted request and useful recovery after failure. Define focus and announcements with the actual application. The synthetic source does not establish these transitions or their accessibility.",
+      "icon": "decision"
+    },
+    {
+      "id": "browser-case",
+      "label": "Verify recovery",
+      "kind": "verification",
+      "origin": "unknown",
+      "requirementIds": [
+        "reset-error-retry",
+        "reset-confirmation",
+        "reset-focus",
+        "reset-expiry"
+      ],
+      "summary": "Check retry, focus, and announcements.",
+      "description": "Verification is pending. Map approved design cases to actual route/state/fixture setup, then observe failed submission, retained input, retry and confirmation in the real browser. Assess keyboard and screen-reader behavior separately from visual comparison. No provider or result is supplied here.",
+      "icon": "check"
+    }
+  ],
+  "edges": [
+    {
+      "id": "route-form",
+      "from": "reset-route",
+      "to": "reset-form",
+      "label": "Compose",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-entry"
+      ]
+    },
+    {
+      "id": "form-request",
+      "from": "reset-form",
+      "to": "reset-mutation",
+      "label": "Submit",
+      "origin": "unknown",
+      "requirementIds": [
+        "reset-request"
+      ]
+    },
+    {
+      "id": "request-feedback",
+      "from": "reset-mutation",
+      "to": "reset-feedback",
+      "label": "Handle result",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-error-retry"
+      ]
+    },
+    {
+      "id": "feedback-evidence",
+      "from": "reset-feedback",
+      "to": "browser-case",
+      "label": "Verify behavior",
+      "origin": "proposed",
+      "requirementIds": [
+        "reset-error-retry"
+      ]
+    }
+  ],
+  "requirements": [
+    {
+      "id": "reset-entry",
+      "text": "Proposed: map the entry screen to the project route and existing form conventions after inspecting code.",
+      "origin": "proposed"
+    },
+    {
+      "id": "reset-request",
+      "text": "Unknown: endpoint, validation and response policy require the actual project contract.",
+      "origin": "unknown"
+    },
+    {
+      "id": "reset-error-retry",
+      "text": "Proposed: retain the entered address on failure; verify retry and accessible feedback in the real browser.",
+      "origin": "proposed"
+    },
+    {
+      "id": "reset-confirmation",
+      "text": "Proposed: render confirmation only after the agreed response; final request policy remains unknown.",
+      "origin": "proposed"
+    },
+    {
+      "id": "reset-expiry",
+      "text": "Unknown: expiry/repeated request behavior must follow the agreed product/security contract.",
+      "origin": "unknown"
+    },
+    {
+      "id": "reset-focus",
+      "text": "Proposed: implement and verify keyboard focus and announced error recovery.",
+      "origin": "proposed"
+    }
+  ],
+  "findings": [
+    {
+      "id": "code-not-inspected",
+      "message": "No application code, route or component identity has been inspected for this synthetic example.",
+      "severity": "blocking",
+      "status": "open"
+    },
+    {
+      "id": "provider-pending",
+      "message": "No approved design cases, actual provider or browser evidence are supplied.",
+      "severity": "blocking",
+      "status": "open"
+    }
+  ],
+  "presentation": {
+    "fontFamily": "Inter"
+  },
+  "summary": "Connect the reset flow to application responsibilities.",
+  "description": "This unapproved integration proposal links the synthetic journey to a route, form, service contract, feedback states and verification work. No application code, API or browser behavior has been inspected. Every proposed responsibility needs project evidence and review before implementation."
+}