@penpair/web 0.4.0 → 0.5.0

package/README.md

@@ -56,6 +56,36 @@ Then choose a scratch page and agree on a small design task. The workflow is: in
 
 The installed skills cover **setup → design → recipes → handoff → verification**, with `design-judgment` for visual hierarchy. Ask the assistant to name the skill it uses. For frontend work, `penpair-handoff` carries design evidence into implementation; `penpair-verify` guides browser comparison, image review, fixes and recapture. [Check skill discovery and behavior](https://github.com/niklas-westman/penpair/blob/main/docs/skill-validation.md).
 
+## Where the command and tools live
+
+Install one command package in your application project. Both expose the same
+`penpair` command; the core library is installed as a dependency.
+
+| Surface | Where it comes from | How you discover it |
+| --- | --- | --- |
+| Hosted/team Penpot CLI | `@penpair/web` | `pnpm exec penpair --help` |
+| CLI with local Penpot containers | `@penpair/docker` | The same command, plus instance lifecycle commands |
+| Engine and shipped agent skills | `@penpair/core` | Library exports and `penpair skills`; core has no executable |
+| Penpair MCP tools | Your installed command, started as a stdio server | Register the executable with `mcp --root /absolute/path/to/project` in your assistant |
+| Your assistant's browser/computer controls | The assistant host, separately from Penpair | Host configuration; installing Penpair does not add these controls |
+
+For example, register `/absolute/path/to/project/node_modules/.bin/penpair` with
+arguments `["mcp", "--root", "/absolute/path/to/project"]`. That exposes typed
+inspection, status, doctor, spec and export tools for the pinned project. It does
+not expose every CLI command or arbitrary browser control. See the
+[tool inventory and client configuration](https://github.com/niklas-westman/penpair/blob/main/docs/mcp.md).
+
+Explicit `--allow-writes` additionally exposes registered operations and the
+experimental `design_release_copy` tool. Both preview by default; applying a
+native copy also requires a loopback browser debugging port and existing browser
+clipboard read/write capability. Penpair does not grant those permissions. The equivalent CLI
+starts with `penpair design-release copy --source-page PAGE --frame BOARD_ID
+--release 1.2.0`. Copying creates native boards and transfer evidence; it does not
+approve a full design release. Read the
+[native copy guide](https://github.com/niklas-westman/penpair/blob/main/docs/copy-between-pages.md)
+before applying it. `penpair wake` remains CLI-only.
+For Claude and other hosts, read the [CLI/MCP prerequisites and current qualification](https://github.com/niklas-westman/penpair/blob/main/docs/copy-between-pages.md#using-from-claude-or-other-hosts); the native-UI test driver is not shipped as a fallback.
+
 ## Add your companions
 
 | Package | Add it when | What it contributes |

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,204 @@
+# Copy native boards between pages
+
+`penpair design-release copy` is an experimental native-editor transfer within
+the project's pinned Penpot file. It copies selected boards to
+`release/<version>`, leaves their originals in place and independently captures
+source and destination evidence. It uses the browser's native clipboard rather
+than trying to move a plugin shape proxy between pages.
+
+This is a page-copy operation, not a complete design-release assembly or owner
+approval. It produces a private transfer receipt, not a fabricated
+`release.json`. The stricter [design release verification](design-releases.md)
+requirements still apply before a full release can be finalized.
+
+## Prerequisites and preview
+
+Use the reviewed project installation, with a valid configuration, an
+owner-confirmed file pin and a connected responsive Penpot plugin. Choose one
+source page and 1–100 distinct board IDs from that page. IDs must identify boards,
+not arbitrary shapes; selecting a board together with its descendant board is
+refused. Boards nested in sections can be selected by their IDs.
+The PoC bounds each observed page to 20,000 nodes and the native clipboard
+payload to 16 MiB; exceeding either limit stops the transfer.
+
+```sh
+# Replace these board IDs and page name with observed source identities.
+penpair design-release copy --source-page "Screens" \
+  --frame SOURCE_BOARD_ID --frame ANOTHER_BOARD_ID --release 1.2.0
+```
+
+Preview resolves the source and destination, inventories existing content and
+reports the planned selection. It does not create a page, alter selection or
+use the clipboard. The destination is always `release/1.2.0` in the same pinned
+file; this command does not copy between files or deployments.
+
+A unique existing destination can be reused without replacing its content.
+Missing destinations are created on apply. Ambiguous page names, finalized
+release ownership and conflicting ownership markers are refused. New copies
+are arranged separately from existing destination content; existing frames are
+not moved or normalized.
+
+## Apply through the native editor
+
+Review the preview and authorize the actual transfer before applying:
+
+```sh
+penpair design-release copy --source-page "Screens" \
+  --frame SOURCE_BOARD_ID --frame ANOTHER_BOARD_ID --release 1.2.0 \
+  --debug-port 9222 --apply
+```
+
+The browser must already expose a loopback debugging port. See
+[browser setup and recovery](browser-sessions.md) for an isolated-profile example.
+Clipboard APIs also require a secure browser context, normally HTTPS or local
+loopback HTTP. See the browser vendor's [clipboard access guidance](https://web.dev/articles/async-clipboard).
+Penpair adds no browser dependency or browser download and does not start a
+managed session. It verifies the browser origin and pinned file; configured local
+instances may use the equivalent `localhost`/`127.0.0.1` HTTP origin on the same
+port. Hosted deployments require the exact configured origin.
+
+The bundled transport also requires the browser's existing clipboard read/write
+capability for that editor. Penpair does not grant clipboard permissions. If the
+capability is unavailable, denied or waiting for a browser prompt, the operation
+fails closed before paste. Complete any intended browser permission decision
+separately; a debugging connection alone does not establish clipboard access.
+
+Applying changes page and board selection, foregrounds the editor and dispatches
+native Copy/Paste. The Penpot canvas must have focus, with no text field,
+content-editable region, plugin iframe or dialog focused. Penpair refuses unsafe
+focus instead of sending shortcuts into another control. This replaces the
+system clipboard contents; previous clipboard contents are not automatically
+restored. Avoid using the clipboard or changing editor focus during the transfer.
+A local clipboard lease excludes cooperating Penpair sessions, not unrelated
+applications or manual actions.
+
+Before dispatching Copy, the transport clears the clipboard to a unique sentinel.
+It then waits for an actual native Penpot JSON/verbose-Transit payload matching
+the pinned file and selected board UUIDs. Validation and SHA-256 calculation run
+inside the browser; the bundled transport does not return, log or persist raw
+clipboard contents. Immediately before Paste it revalidates the payload digest.
+Missing, stale, unrelated or changed clipboard data prevents paste rather than
+reusing whatever was previously on the clipboard. Clearing the clipboard can
+therefore replace its contents even when the transfer subsequently stops.
+
+The command captures source inspections and stable exports, prepares the
+same-file destination, fences one native paste attempt, identifies the new
+boards and arranges only those copies. Independent readback checks the copied
+boards and the unchanged originals. It records structural findings and decoded
+pixel comparisons. Review the saved source/target exports visually as part of
+acceptance; a technical result does not supply human approval.
+
+## Results and recovery
+
+The result includes a `runId`, source/target board pairs, `nativeVerified`,
+`pixelsMatch`, problems and a receipt path:
+
+```text
+.penpair/native-copy/<run-id>/receipt.json
+```
+
+The receipt and its referenced inspections/exports are private operation evidence.
+A successful fully verified transfer reports `status: "copied"`; missing native
+proof or a pixel mismatch can leave `status: "incomplete"` and exit 3 even when
+boards already exist in the destination. Read the findings before doing anything
+else. Existing verification limits remain strict: component overrides, masks,
+paths, mixed text styles and other unobserved native fields cannot be accepted
+merely because exported pixels match.
+
+Do not rerun a fresh apply to recover a lost response. Inspect the journal and
+destination independently, then use the original inputs and run ID:
+
+```sh
+penpair runs RUN_ID
+penpair design-release copy --source-page "Screens" \
+  --frame SOURCE_BOARD_ID --frame ANOTHER_BOARD_ID --release 1.2.0 \
+  --debug-port 9222 --resume RUN_ID --apply
+```
+
+Resume reconciles the observed destination against the original transfer. A
+paste-attempt fence prevents blind replay after an uncertain paste. Changed
+inputs, changed originals or an ambiguous destination require explicit
+reconciliation; neither resume nor browser activation promises rollback.
+
+The transfer receipt is not the receipt-list schema consumed by
+`design-release verify --receipts`. Do not rename it to `release.json` or pass it
+as an approved release. Full release plans, maps, source evidence, native-copy
+mapping and exact owner reviews remain separate requirements. Compatibility
+between copy-created page ownership and the full assembly workflow must be
+validated before treating a copied page as an assembled release.
+
+## MCP discovery
+
+The typed `design_release_copy` tool appears only when the project's Penpair
+stdio server starts with `--allow-writes`. Its inputs are `sourcePage`,
+`frameIds`, `releaseVersion`, optional `debugPort`, `apply` and `resume`. Preview
+is the default; apply requires `debugPort`, and resume requires apply. The tool
+returns the same operation result and keeps the same target/recovery safeguards.
+It does not expose raw page code. See [MCP tools](mcp.md).
+
+## Using from Claude or other hosts
+
+The standard copy route is host-neutral: an assistant can invoke the installed
+CLI or call the typed Penpair MCP tool. It requires the configured project,
+owner-confirmed file pin and responsive plugin connection described above. Apply
+also requires a debugging-enabled browser on the same computer as the Penpair
+process, the explicit debugging port and existing clipboard read/write access.
+These are the same prerequisites in Claude, Codex and other CLI/MCP-capable hosts.
+
+Claude does not need an additional computer-control integration for the standard
+CDP route. Register the reviewed Penpair executable with `--allow-writes` to expose
+`design_release_copy`, or use the CLI directly. Preview first; tool visibility
+alone neither applies the copy nor grants browser permissions. See the
+[Claude registration example](mcp.md#client-registration).
+
+The native-UI keyboard driver used in the trial below was an injected test
+driver, not a public CLI/MCP fallback supplied to Claude or other hosts. That
+trial establishes the core-service proof described below; qualification of the
+bundled CDP clipboard path against Penpot remains pending. Installing Penpair or
+adding host computer controls does not turn that pending qualification into a
+passing result.
+
+## Evidence and API boundary
+
+The hardened bundled CDP transport has not passed end-to-end browser
+qualification. In a disposable unauthenticated Brave fixture, it stopped while
+awaiting clipboard read access and dispatched no paste. Earlier shortcut-only
+fixture results do not establish that the current payload-validation path works
+end to end. A separate native-UI experiment also does not qualify the bundled
+CDP transport or provide a public CLI fallback.
+
+An owner-authorized hosted Penpot trial on 25 October 2026 copied two synthetic
+240 × 160 boards with simple rectangle/ellipse children into a disposable release
+page. It used an injected native-UI keyboard driver through the same core copy
+service because that existing browser profile had no debugging port. The actual
+JSON/verbose-Transit clipboard payload was checked locally against the pinned
+file, selected board identities and digest before one paste; arranging the new
+copies was a separate idempotent step. Independent inspection/native-fidelity
+comparison and decoded RGBA pixel hashes passed for both boards, with four mapped
+nodes. Source and copied stable PNG exports were visually inspected.
+
+The original trial run then completed explicit resume with `status: "copied"`,
+`nativeVerified: true`, `pixelsMatch: true` and no problems. The copies were
+arranged, the original source hashes remained unchanged, the receipt was saved
+and the journal reached `verified`. Revision drift had safely interrupted the
+first final capture; bounded read-only recapture and reconciliation completed
+verification without another Copy or Paste dispatch.
+
+This establishes the limited native-UI/core-service proof of concept. End-to-end
+Penpot qualification of the bundled CDP clipboard transport remains pending;
+the native-UI result does not establish that qualification or record owner
+approval. Unsupported content remains incomplete. Full release assembly adoption
+is not implemented by this transfer proof of concept.
+
+The direct plugin API limitation remains: a disposable two-page trial on local
+Penpot 2.18.3 tested a board with one rectangle child. `clone()` remained on the
+source page, and cross-page `appendChild`/`insertChild` attempts failed with
+`Cannot modify a page that is not currently active`. Independent readback found
+the originals unchanged and no destination children. The native clipboard route
+avoids that unsupported operation; it does not make cross-page reparenting safe.
+
+The [upstream shape implementation](https://github.com/penpot/penpot/blob/develop/frontend/src/app/plugins/shape.cljs)
+checks active-page ownership. The [Board API](https://doc.plugins.penpot.app/interfaces/Board)
+provides cloning and reparenting, but no cross-page transfer operation. Penpair
+does not patch proxy internals, reconstruct the design from screenshots or
+submit unauthenticated raw backend file changes as a fallback.

package/docs/design-releases.md

@@ -7,6 +7,27 @@ 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.
 
+## Copy boards to a release page
+
+For an experimental same-file page transfer, preview the observed source boards:
+
+```sh
+penpair design-release copy --source-page "Screens" \
+  --frame SOURCE_BOARD_ID --release 1.2.0
+# After reviewing and authorizing the transfer:
+penpair design-release copy --source-page "Screens" \
+  --frame SOURCE_BOARD_ID --release 1.2.0 --debug-port 9222 --apply
+```
+
+This uses native editor copy/paste into `release/1.2.0`, preserving originals and
+existing destination content, and writes private evidence under
+`.penpair/native-copy/<run-id>/`. It can report incomplete native fidelity after
+copying; read the findings and inspect the exports. The transfer receipt is not
+a release manifest, the `verify --receipts` input schema or owner approval.
+Copy-created page ownership does not by itself establish compatibility with the
+full assembly flow below. See [native copy and recovery](copy-between-pages.md)
+for prerequisites, clipboard effects, explicit resume and current proof limits.
+
 ## Local commands
 
 Create the plan from actual source inspection, using your own product SemVer.
@@ -60,8 +81,12 @@ is not approval of the child graph. See [linked detail maps](integration-maps.md
 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.
+by a person or an authorized AI using existing browser tools. The experimental
+`design-release copy` path separately automates native clipboard transfer; its
+receipt is not automatically a full release's mapping or approval. Assembly
+does not perform an unsupported cross-page clone. The
+[native copy guide](copy-between-pages.md) records both that API boundary and the
+new transport's verification limits.
 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

package/docs/layout-settling.md

@@ -1,6 +1,6 @@
 # Bounded layout settling
 
-Normal operation writes, PNG exports, baselines, shots and token push verification now use `waitForStableLayout`. A supported shape/global native wait is preferred. Older APIs fall back to geometry samples, requiring two consecutive equal observations of the target subtree. Missing targets, changed file/page identity, malformed geometry, more than 10,000 sampled nodes, native failure and expired budgets cannot establish stability.
+Normal operation writes, PNG exports, baselines, shots and token push verification now use `waitForStableLayout`. A supported shape/global native wait is preferred. Older APIs fall back to geometry samples, requiring three consecutive equal observations of the target subtree. Missing targets, changed file/page identity, malformed sampled geometry and expired budgets cannot establish stability. Native failure falls back to geometry in `auto` mode; `native` mode still requires a successful native wait.
 
 The default layout budget is 30 seconds, with 200 ms fallback intervals. A run is also limited to 1,000 samples. Each layout observation forwards its remaining request budget through guards to the MCP SDK and disables suspension retries; a read timeout does not silently restart the budget. Custom clients must honor the optional `ToolCallOptions.timeoutMs` contract. A late native response is rejected even if it claims completion. The overall CLI `--timeout-ms` remains a separate bound on the complete command.
 
@@ -11,3 +11,19 @@ Exports retain the first capture as an initial observation, wait for layout, and
 The previous unconditional ten-second operation sleep is replaced by bounded evidence. Library callers can retain an explicitly measured `settleMs` minimum from 0 to 30 seconds for an additional asynchronous contract such as binding persistence. It is a delay, not verification. A missing binding still fails independent readback and may be reconciled through the journal once it arrives. Page switching retains its existing short navigation delay. No new live timing or compatibility claim is made.
 
 Library options may select a target and budget through `layout`, or explicitly set `layout: false` when the caller supplies its own settlement evidence. CLI design commands do not expose that opt-out. Multi-step mutations remain nontransactional: a post-write layout failure can leave completed work applied; inspect the run and explicitly resume after resolving it. The later build kit should reuse these primitives rather than introduce another fixed-sleep convention.
+
+## Scope and node budgets
+
+`run-file`, `run`, `archive`, token edit writers, `export` and `shots` accept:
+
+```sh
+penpair run-file design/build.js --inspect design/inspect.js --readback design/readback.js \
+  --page Candidate --layout-root BOARD_ID --layout-root OTHER_BOARD_ID \
+  --layout-max-nodes 20000 --apply
+```
+
+Each repeatable `--layout-root` identifies an existing shape on the operation's page. Roots must be distinct, nonoverlapping subtrees. Missing roots refuse rather than falling back to the page. The same roots are observed before planning, after writing and during recovery. New shape IDs cannot be selected before creation; select their existing parent or use the page default. Without explicit roots the current page is sampled; exports retain their existing shape scope. Library callers use `layout.shapeIds` (or the existing singular `shapeId`) and `layout.maxNodes`.
+
+`--layout-max-nodes` is an integer from 1 to 100,000, shared across the selected subtrees; the default remains 10,000. When the traversal exceeds it, the observer retains a bounded depth-first prefix. A successful native wait or three equal bounded samples can continue the operation with `method: "partial"` and `truncated: true`. This establishes stability only for the sample, not for unsampled shapes. Invalid geometry, cycles or duplicate IDs encountered in the sample still refuse. Use explicit roots for complete evidence on a large page. Partial evidence never replaces positive independent write readback or visual export inspection.
+
+Reports and journal observations, visible through `penpair runs RUN_ID`, record `rootIds`, `nodeCount` (the sampled count), `maxNodes` and `truncated`. The sample count is a lower bound on subtree size when truncated. Journal input hashes retain the chosen scope and budget, so changing either requires a new run. The build kit's `pp.settle(root, {maxNodes})` shares this policy and evidence; it also accepts an array of root shapes.

package/docs/mcp.md

@@ -6,9 +6,48 @@ penpair mcp --root /absolute/path/to/project
 
 Use the project's reviewed local executable. Startup requires an absolute root, valid project config and owner-confirmed file pin. The server keeps that target for its lifetime and refuses a changed target until restart/review. Each call gets request-scoped root state; it never calls `process.chdir`. Even basic reads use strict same-execution file guards. Environment/project `.env.local` endpoint resolution remains available; unrelated global Codex/Claude endpoint fallback is disabled. Keep credentials in the private connection flow, outside client configuration examples.
 
-Default tools: pages, bounded tree/audit/inspection, bounded token dump, offline baseline coverage, doctor, derived spec, and stable export to a path inside the project. Export creates/replaces a local file and has a write annotation. There is no raw-code tool or unrestricted command forwarding. Each typed input is validated independently of the client schema. No Penpot write tool is advertised by default.
+Default tool names are `pages`, `tree`, `audit`, `inspect`, `tokens_dump`, `run_status`, `baselines_status`, `project_status`, `doctor`, `design_spec` and `export`. These cover bounded live inspection, offline run/baseline evidence, diagnostics, derived specs and stable export to a path inside the project. Export creates/replaces a local file and has a write annotation. There is no raw-code tool or unrestricted command forwarding. Each typed input is validated independently of the client schema. No Penpot write tool is advertised by default.
 
-Explicit `--allow-writes` additionally advertises `run_registered`. It accepts a registered operation name and scalar parameters, defaults to inspection, and requires explicit `apply:true` for design writes. Explicit `resume` requires apply and the original journal; file/instance guards, local/shared advisory lease, same-execution preconditions, checkpoints supported by the underlying command, and independent readback remain in the same services. Registered modules execute trusted project code, including imports; they must keep stdout for MCP and log through the command context. This is not an execution sandbox. Adapter-specific commands remain available through the CLI; the neutral server does not guess library-specific tool schemas.
+Explicit `--allow-writes` additionally advertises `run_registered` and `design_release_copy`. The first runs registered operations; the second provides the typed native-copy workflow described below. `run_registered` accepts a registered operation name and scalar parameters, defaults to inspection, and requires explicit `apply:true` for design writes. Explicit `resume` requires apply and the original journal; file/instance guards, local/shared advisory lease, same-execution preconditions, checkpoints supported by the underlying command, and independent readback remain in the same services. Registered modules execute trusted project code, including imports; they must keep stdout for MCP and log through the command context. This is not an execution sandbox. Adapter-specific commands remain available through the CLI; the neutral server does not guess library-specific tool schemas.
+
+## Native release-page copy
+
+Start the reviewed project executable with write tools enabled only when those
+operations are authorized:
+
+```sh
+penpair mcp --root /absolute/path/to/project --allow-writes
+```
+
+The `design_release_copy` tool previews by default. Example input, with observed
+source board IDs substituted:
+
+```json
+{
+  "sourcePage": "Screens",
+  "frameIds": ["SOURCE_BOARD_ID", "ANOTHER_BOARD_ID"],
+  "releaseVersion": "1.2.0",
+  "apply": false
+}
+```
+
+Explicit `apply: true` also requires `debugPort` (1–65535) for an already enabled
+loopback browser debugging endpoint and existing clipboard read/write capability.
+Penpair does not grant browser permissions; denied or unavailable access stops
+before paste. `resume` requires apply and the original run ID/inputs. Copy uses the pinned file, preserves originals, and creates or appends
+to `release/1.2.0`; it changes browser focus and selection and replaces the system
+clipboard. The bundled transport clears stale data before Copy, validates the
+native payload against the pinned file and selected boards inside the browser,
+and rechecks its digest before Paste. Raw clipboard data is not returned, logged
+or persisted by that transport. An uncertain paste is reconciled rather than
+automatically replayed.
+An incomplete native/pixel result is not a completed transfer or release
+approval. See [native copy, evidence and recovery](copy-between-pages.md).
+
+This tool is absent from the default server. There is no MCP `wake` tool: explicit
+browser activation remains the CLI `penpair wake` command. Native browser/computer
+controls supplied by an assistant host are separate tools and are not installed
+or exposed by Penpair's server.
 
 Requests return the version-1 CLI envelope as text plus structured content. Default cooperative deadline: 60 seconds; SDK cancellation propagates into the service. Arbitrary trusted code can ignore cancellation. A 256 KiB response cap returns an explicit incomplete envelope rather than apparently successful truncated data; uncertain writes retain their uncertain outcome/run ID. Use narrower inspection or CLI artifact output for larger evidence. Stdio has no HTTP listener or background polling.
 
@@ -22,8 +61,9 @@ Every advertised tool explicitly declares boolean `readOnlyHint`, `destructiveHi
 | `pages`, `tree`, `audit`, `inspect`, `tokens_dump`, `project_status`, `doctor`, `design_spec` (may contact Penpot or its deployment) | true | false | true | true |
 | `export` (creates or replaces a local image from live Penpot) | false | true | false | true |
 | `run_registered` (opt-in trusted code, potentially mutating) | false | true | false | true |
+| `design_release_copy` (opt-in native clipboard transfer) | false | false | false | true |
 
-`export` can overwrite an existing artifact, so its destructive hint is true. It captures the current design, so callers must not assume repeated calls preserve the earlier image. `run_registered` retains conservative hints even when a particular invocation only previews: its metadata must cover the registered code's possible effects. `archive` is an internal registered operation invoked through `run_registered`, not a separately advertised MCP tool.
+`export` can overwrite an existing artifact, so its destructive hint is true. It captures the current design, so callers must not assume repeated calls preserve the earlier image. `run_registered` retains conservative hints even when a particular invocation only previews: its metadata must cover the registered code's possible effects. `design_release_copy` preserves source boards and existing destination content, but is still mutating and non-idempotent: it can create native copies, change selection/focus and replace the clipboard. Its preview does not change that tool-wide annotation. `archive` is an internal registered operation invoked through `run_registered`, not a separately advertised MCP tool.
 
 ## Code execution boundaries
 
@@ -46,6 +86,24 @@ Claude Code supports project `.mcp.json` entries under `mcpServers`; see [offici
 }
 ```
 
+For authorized native-copy work, change that Claude entry's `args` to:
+
+```json
+["mcp", "--root", "/absolute/path/to/project", "--allow-writes"]
+```
+
+Restart or reconnect the server to discover `design_release_copy`. This enables
+tool visibility; it does not apply a copy or grant browser permissions. The tool
+must be present in the installed Penpair version's tool list. Registering only
+Penpot's upstream MCP server does not expose Penpair's project tools.
+The tool
+still previews by default. Apply requires `apply: true`, `debugPort`, the pinned
+project/plugin connection and existing clipboard read/write access in the
+browser on the Penpair process's computer. The standard CDP route needs no
+additional Claude computer-control integration. The injected native-UI driver
+used in the core-service trial is not a public fallback; bundled CDP/Penpot
+qualification remains pending. See [host prerequisites and qualification](copy-between-pages.md#using-from-claude-or-other-hosts).
+
 Codex uses project `.codex/config.toml` for trusted projects, with a server table; see [official Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).
 
 ```toml
@@ -55,3 +113,5 @@ args = ["mcp", "--root", "/absolute/path/to/project"]
 ```
 
 Restart/reconnect after reviewed target or tool-capability changes. Keep the actual Penpot editor visible. SDK in-memory tests establish discovery, typed input refusal, explicit write opt-in, root isolation and target-change refusal; actual agent/editor compatibility remains a pending I12 trial.
+
+For explicit tab activation, heartbeat diagnostics and the limits of background operation, see [recovering a suspended Penpot tab](browser-sessions.md). The CLI `wake` action is separate from the read-only doctor tool.

package/docs/run-file.md

@@ -69,3 +69,5 @@ The common verifier requires matching nonempty expected/actual objects. Empty `p
 Final wrapped UTF-8 snippets obey the existing 90 KB guard, including helpers, guards, parameters and the captured inspection passed to apply. Every phase compiles offline before connecting; an oversized runtime inspection can still make apply refuse before delivery. Each input file is bounded independently, and at most 20 distinct include paths and 100 parameters are accepted. Reports identify the ordered source text hashes actually prepared. No implicit imports, glob expansion or transpilation occurs.
 
 Writes reuse pinned file guards, revisions, writer coordination, positive independent verification and redacted journals. Optional `--checkpoint`, `--force-lock` and explicit `--apply --resume RUN_ID` follow normal recovery rules. Source/parameter changes refuse resume; a final state already independently verified is not written again. Partial unexplained state requires inspection; there is no rollback or enforced idempotency sandbox. A redacted journal cannot be presented as complete verification or automatically resumed.
+
+On a large page, scope layout settling to the existing boards touched by the write with repeatable `--layout-root SHAPE_ID`. `--layout-max-nodes N` sets the shared sample budget (1–100,000; default 10,000). The roots must exist before the write and remain present through readback. Reports and `penpair runs RUN_ID` retain the roots and sampled node count. Budget overflow continues with explicitly partial layout evidence; independent readback is still required. See [layout settling](layout-settling.md) for scope and partial-sample limits.

package/docs/troubleshooting.md

@@ -11,7 +11,7 @@ Generated from the core error remedy inventory. Regenerate with `pnpm docs:gener
 | `incomplete-output` | Required output is missing, truncated or unstable. Narrow the scope or resolve the capture problem before accepting it as complete. |
 | `mcp-unavailable` | Start the Penpot instance and check the MCP URL. Run `penpair probe` to see what answers. |
 | `plugin-disconnected` | In the open Penpot file choose File, MCP Server, Connect, and keep that tab visible, then run the command again. |
-| `plugin-suspended` | The browser put the Penpot tab to sleep. Bring it to the foreground and keep it visible while a command runs. A suspended-tab error does not mean nothing was written: read the page before running a write again. |
+| `plugin-suspended` | The browser put the Penpot tab to sleep. Bring it to the foreground, or use penpair wake --debug-port PORT with a dedicated debugging browser, then run penpair doctor. Waking is temporary recovery. A suspended-tab error does not mean nothing was written: read the page and reconcile the run before explicitly replaying a write. |
 | `snippet-too-large` | Split the snippet. Penpot's proxy refuses request bodies of about 110 KB, so snippets stay under 90 KB. |
 | `stale-inspection` | The file, revision, query or inspected content changed. Discard the old cursor/chunks and start a fresh capture. |
 | `tool-failed` | Penpot's tool reported a failure; the message above says what. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/web",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The penpair command for Penpot on the web (design.penpot.app or your team's own): guided setup, a safe write protocol, skills for AI agents. Includes everything in @penpair/core.",
   "license": "MIT",
   "repository": {
@@ -48,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@penpair/core": "0.4.0"
+    "@penpair/core": "0.5.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",