@penpair/web 0.1.3 → 0.3.0

package/docs/build-kit.md

@@ -0,0 +1,59 @@
+# Build kit and recipes
+
+`penpair run-file ... --include @kit` defines the neutral plugin namespace `pp`. The library exports the same plain JavaScript text as `kit()`; concatenate it into a guarded snippet rather than importing Node code into the plugin. Inclusion defines functions and recipes without touching the document.
+
+```sh
+penpair kit check
+penpair recipes
+penpair kit check --include @kit --include @marwes-kit
+penpair recipes --include @kit --include @marwes-kit
+```
+
+The last two examples require the token adapter configured in the adopting project. A normal core check/list or `@kit` include does not import unrelated adapters. Explicit extension aliases load configured trusted adapter code to discover their source. Dependencies must appear earlier in include order; ambiguous aliases or recipe names refuse. Each kit is at most 32 KiB and combined kit source at most 48 KiB, leaving room within the final wrapped 90 KB snippet guard. Reports retain bytes and source hashes.
+
+## Neutral helpers
+
+| Helper | Contract |
+| --- | --- |
+| `tok(name)` | Reads current active sets in catalog order; later active sets win. Missing names and duplicates inside a set refuse. No inactive-set fallback or persistent cache. |
+| `bind(shape, name, properties)` | Queues explicit token-property bindings for `flush`; properties are token binding keys, not arbitrary JavaScript shape fields. |
+| `box(parent, options)` | Makes a flex board; `gap` and four-sided `pad` accept spacing token names or unbound zero. `w`/`h` are explicit geometry. `bg`/`stroke` are color tokens and `radius` is a radius token. |
+| `text(parent, value, options)` | Requires nonempty characters, `typo` and `color` tokens; preflights an exact font family/weight/style and applies the face before bindings. Use `wrap`, `fill`, `grow`, `align` and explicit `font` where needed. |
+| `icon(parent, kind, color, size)` | Square wrapper around a uniformly scaled path on a 24-unit drawing grid. Built-ins: chevron, check, alert, calendar. A custom glyph supplies `path` and `[x,y,width,height]` bounds. |
+| `dot`, `rule` | Small geometric helpers with explicit color tokens. Intrinsic one-pixel rules/strokes are geometry, not inferred library measurements. |
+| `inst(parent, path, name, textOverrides, library?)` | Exact unique component match; validates named text overrides and never removes/reorders instance children. Defaults to the local library. |
+| `style(shape, options)` | Queues requested styling only; an isolated color update preserves existing spacing and bindings. |
+| `fill`, `fillV` | Sets layout-child horizontal/vertical fill sizing. |
+| `settle(root, options)` | `strategy: auto | native | geometry`, default auto. Auto caps native at min(500 ms, remaining/4), then requires three complete equal geometry/hierarchy samples. Time/node/malformed evidence cannot report stable. |
+| `flush({root, timeoutMs, strategy})` | Waits for layout, applies queued values/styles, then awaits queued bindings, then settles again. Active token-context changes refuse. |
+
+Always `await pp.flush()` before independent readback/export. There are no fixed 1.2/2.5-second styling sleeps. Layout completion does not prove font download, token persistence or pixels; keep positive readback and stable exports. Queues are local to one execution, not a recovery log. Partial errors are not transactions; the enclosing reviewed operation must own and reconcile its roots. Bindings remain subject to the runtime's supported token properties; A4 owns the broader compatibility whitelist.
+
+Example body (inside a reviewed `run-file` operation):
+
+```js
+const card = pp.recipe("hello-card", ownedRoot, {
+  box: { name: "Hello card", w: 240, gap: CFG.space, pad: [CFG.space, CFG.space, CFG.space, CFG.space], stroke: CFG.color, radius: CFG.radius },
+  text: { typo: CFG.typo, color: CFG.color },
+  label: "Hello, card",
+});
+await pp.flush({ root: ownedRoot });
+```
+
+A recipe is registered with `pp.defineRecipe(name, (parent, props) => shape, description)` and invoked through `pp.recipe`. Recipe source must remain synchronous at construction time; asynchronous binding/layout work finishes in `flush`. See the [complete repeatable example](../examples/hello-card/README.md).
+
+## Adapter recipes
+
+`@marwes-kit`, included after `@kit`, defines `mw.card`, `mw.segmented`, `mw.progress`, `mw.iconTile` and `mw.statTile`, and registers corresponding recipe names. Library token defaults live entirely in the adapter; every token can be retargeted through props. Card/progress/tile radius tokens are explicit project declarations or measured inputs. Progress additionally requires an explicit **sizing** height token, since spacing tokens do not bind height. Tile dimensions and content are explicit.
+
+These are compositional starting points. They are not generated native component variants or measured parity claims; C1 owns that calibration. Missing library defaults fail visibly rather than producing silently unbound styling.
+
+## Opt-in scratch probe
+
+`penpair probe --deep --kit --write` adds a journaled kit trial to the ordinary deep probe. Use an owner-authorized scratch file with active color, typography, spacing and radius tokens and the typography's font available. The trial builds a small “Hello, card” under a directly owned temporary root, observes text/bindings/geometry, exports matching renders, removes only that root, and independently compares the original page/token state. Unsupported context refuses; failed export still attempts owned cleanup. Explicit resume is allowed only against the original source and clean/reconciled state.
+
+A verified trial saves a private PNG preview under `.penpair/probes/`, with byte hash and capture identity. Look at the preview as the write protocol requires. `visualApproval: false` remains explicit. Redacted/incomplete evidence cannot publish a preview; an existing differing preview is preserved. No new live pinned-version trial has been performed in this branch.
+
+Current references: [flex layout](https://doc.plugins.penpot.app/interfaces/FlexLayout), [font application](https://doc.plugins.penpot.app/interfaces/Font), [component instantiation](https://doc.plugins.penpot.app/interfaces/LibraryComponent), [spacing properties](https://doc.plugins.penpot.app/types/TokenSpacingProps) and [sizing properties](https://doc.plugins.penpot.app/types/TokenSizingProps). Runtime capability and independent evidence remain required.
+
+Host operations retain a 30 s total layout deadline; kit settle/flush default to 10 s. `native` reports failure without fallback; `geometry` skips native waiting. Diagnostics include the chosen strategy, native outcome, fallback reason and elapsed time. Neither transport loss, cancellation, changed target nor malformed/truncated data becomes a successful fallback. `run-file`, `export` and `shots` accept `--layout auto|native|geometry`. The default is suitable for ordinary builds; there is no CLI off mode.

package/docs/command-contract.md

@@ -0,0 +1,27 @@
+# Command results for scripts and tools
+
+`--json` emits one schema-versioned stdout document for core commands and the bundled adapter. Human output remains available without it. This replaces earlier command-specific JSON roots: read `data.ok` and `data.checks` for doctor, and `data.valid` for config check. CLI progress and diagnostics go to stderr; diagnostics are also included in the result.
+
+The outer schema is exported as `commandResultSchema`, with the TypeScript `CommandResult` type. It contains `schemaVersion: 1`, command name, outcome, phase, exit code, observed target IDs when available, run ID when available, command-owned `data`, human messages, warnings, structured errors with remedies, completeness and timings. An absent target is `null`, never inferred from a file name. Do not decide success from empty errors alone: check outcome, exitCode, completeness and the command's verification fields.
+
+| Exit | Outcome | Meaning |
+| --- | --- | --- |
+| 0 | success | Command completed; an inspect/preview still does not mean it applied or visually approved a change. |
+| 1 | failed | Validation, connection, verification or command failure. Error codes distinguish configuration and transport problems. |
+| 2 | drift | A valid comparison found differences or a stale snapshot. |
+| 3 | incomplete | Required output is missing, truncated or unstable. |
+| 4 | uncertain | A possible write lacks a confirmed outcome. Inspect the run before resuming. |
+| 124 | deadline | The deadline interrupted work without a delivered write being classified uncertain. |
+| 130 | cancelled | Cancellation interrupted work without a delivered write being classified uncertain. |
+
+Tree JSON retains its truncation flag, and truncated tree output exits 3 in both formats. Baselines cannot pass with missing/unstable captures. A standalone unstable PNG export preserves its previous output and exits 3. Adapter status marks unavailable Penpot inspection incomplete instead of reporting a complete successful status.
+
+Use `--timeout-ms <1..1800000>` for an overall CLI deadline. Each MCP request also retains a 120-second SDK timeout. SIGINT/SIGTERM abort requests and waits; SDK cancellation does not prove that plugin execution stopped. An interruption after a write was delivered therefore remains uncertain (4), with journal evidence retained. There is no forced rollback or detached background continuation. Synchronous extension code must cooperate; a JavaScript deadline cannot preempt a blocking synchronous module. Interactive setup/connect require a terminal, refuse JSON mode, and do not accept this deadline flag. Run doctor in JSON mode afterwards.
+
+Library callers can use `runCommand(args, { signal })` to receive the same result without printing it; it enables command JSON data internally. The stdio MCP server uses this service boundary. Supply `runCommand(args, {root, signal})` for request-scoped projects; the process working directory remains unchanged. CLI calls default to the current project. Connection-specific redactors sanitize data, errors and diagnostic boundaries, including known bare key values. Never provide keys in arguments.
+
+Adapters should write through `context.output.log/error/result` and reserve `context.log` for progress. `result(value)` sets their authoritative structured data. Existing third-party adapters that write directly to global console/process streams must migrate to this output contract; arbitrary imported code is not sandboxed or intercepted. Unsupported or ignored command flags are refused before execution, including write flags on read commands and invalid numeric budgets.
+
+MCP transport accepts an executor envelope `{ result, log? }` in `structuredContent`, or the equivalent JSON text envelope for older servers. Structured content takes precedence and must validate; malformed structured data cannot fall back to a reassuring legacy text response. The SDK continues to handle its advertised schema checks. This is executor-envelope validation, not proof that an arbitrary snippet measured the state correctly. See the [MCP tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).
+
+Explicit mode trials may use a separate cooperative ten-second restoration deadline after main-command cancellation. The command remains cancelled/uncertain where applicable; cleanup does not establish a successful measurement. See [mode verification](mode-verification.md).

package/docs/compatibility.md

@@ -27,3 +27,49 @@ What has been checked, where, and what differs. Update it whenever a Penpot is p
 - Paid plans, and whether the free plan keeps the remote MCP.
 - Two people in the same hosted file while an agent writes.
 - Penpot's own version history as a backup for an external project.
+
+## Automated checks and manual scratch smoke
+
+The local suite includes a real HTTP fake MCP server: protocol negotiation, tool discovery, authentication rejection/redaction, read-only suspension retry, write acknowledgment loss and malformed replies. Generated normalization invariants exercise color case, font-list storage and typography normalization. These are transport/storage tests, not evidence of new live Penpot compatibility.
+
+After `pnpm build`, an owner can run `pnpm smoke:live --scratch-file <disposable-file-id> --origin <expected-origin> --expected-version <x.y.z> --confirm-scratch`. Set `PENPAIR_MCP_URL` in the environment (never as a command argument or committed value). The harness refuses missing confirmation, wrong instance/file and version drift before the mutating probe. It uses the existing tagged deep check and independently verifies cleanup. Every required step must be observed; empty reports cannot pass. An uncertain write is never replayed automatically; use the tag/run ID to inspect leftovers.
+
+The `Scratch Penpot compatibility smoke` workflow is manual-dispatch only. Configure a protected `penpot-smoke` environment and its `PENPAIR_SMOKE_MCP_URL` secret, then open the disposable file and keep its authenticated editor/plugin connected. CI cannot create that browser session from a key alone. The workflow stores a redacted text report; update the live compatibility table only after reviewing an actual run. A scheduled nightly hosted job remains deferred until editor-session lifecycle is solved. The first live run of this harness is still outstanding; no hosted/local version gained a new verified check from the unit tests.
+
+## Capability-driven native APIs
+
+`probe` now emits report `schemaVersion: 1`, the observed Penpot API version, target IDs, observation time, and presence of layout wait, integrity validation, version-history and markup/style/font helpers. Presence is not a behavior test. `probe --integrity` invokes `File.validate()` only when supported; unsupported is explicit, issues return `valid: false` and a failing CLI status, and thrown/malformed API results do not count as valid. The ordinary probe and doctor do not create versions or run write-capability tests.
+
+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.
+- `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.
+
+## Hosted archive candidate
+
+`backup file` requests the documented `currentFile.export("penpot", "all")` signature, bounds the returned payload and refuses to accept an archive if file identity/revision changed. Simulated tests do not resolve the observed live export failure or establish import fidelity. Follow the [scratch round-trip checklist](backup.md#prove-the-restore-on-scratch) before marking this path proven; the live table remains unchanged.
+
+## Build-brief observations reviewed 2026-10-21
+
+Scope: hosted Penpot 2.18.4, as reported in the design-build brief. These reports were incorporated into the shipped [plugin gotchas reference](../packages/core/skills/penpair-design/references/penpot-plugin-gotchas.md#build-report-hosted-penpot-2184-reviewed-2026-10-21); they were not independently rerun on this branch and do not add passes to the live matrix.
+
+| Reported area | Workaround or verification requirement |
+| --- | --- |
+| Stretch row nested in a hugging parent | Try start alignment plus intentional explicit child height; inspect actual geometry. |
+| Fill child changes parent hug sizing | Reassert auto only when hug is the intended parent contract; read back sizing. |
+| Fixed sizing leaves the 100 px default | Resize to explicit intended dimensions. |
+| Empty characters rejected | Omit the node or deliberately use a non-breaking space. |
+| `fillOpacity` cannot be assigned | Use whole-shape opacity or the fill array; verify after token binding. |
+| Token formulas and adding a set to an existing theme | Inspect resolved values under the intended active theme; portability is a separate question. |
+| Instance children cannot be freely removed/reordered | Match structural variants; verify supported overrides. |
+| Layout padding setters differ from token binding keys | Keep setter and binding names distinct. |
+| Component creation splits path/name and can race saved bindings | Use the local library API and observe bindings before creation. |
+| A font token alone did not guarantee the exported face | Find/apply the actual font variant and review the export. |
+| Square resizing distorts a non-square path | Preserve aspect ratio inside a fixed-size wrapper. |
+| Layout/export takes roughly 10–30 seconds to settle | Bounded layout evidence plus independent stable exports; no fixed-delay proof. |
+| Hidden editor loses heartbeat, observed after 6–8 minutes | Keep a separate visible editor window; retry only declared reads and inspect uncertain writes. |
+
+The existing doctor remedy already says to keep the tab visible. Its text now also suggests a separate window; it does not predict the browser's suspension deadline. Recipe enforcement will be delivered with the kit. Native/fallback layout behavior on live pinned versions remains to be checked. The documentation does not imply those later items are implemented.

package/docs/conventions/README.md

@@ -0,0 +1,63 @@
+# Code conventions
+
+Start with the row matching the change. Copy the relevant pattern, then use the
+nearest production module's domain vocabulary. The examples compile and run in
+`pnpm conventions:check`; production code never imports them.
+
+The [completion report](completion-2026-10-22.md) records the initial rollout,
+resolved problems, verification and limits.
+
+| Work | Read | Checked example |
+| --- | --- | --- |
+| Choose a package, folder or module boundary | [Structure](structure.md) | [Comparison adapter](../../packages/reflection-check/src/index.ts) |
+| Write a helper, contract or test | [TypeScript](typescript.md) | [Frame label](templates/frame-label.ts), [tests](templates/conventions.test.ts) |
+| Add an adapter command | [TypeScript](typescript.md), [structure](structure.md) | [Offline command](templates/adapter-command.ts) |
+| Generate code for the Penpot sandbox | [Plugin code](plugin-code.md) | [Read-only snippet](templates/frame-inspection.ts) |
+| Change release or workspace scripts | [Structure](structure.md), [releasing](../releasing.md) | Existing sibling in `scripts/` |
+
+```sh
+pnpm format             # Format supported source/configuration files
+pnpm lint:fix           # Apply safe lint fixes
+pnpm check:style        # Check formatting, focused lint rules and code directory names
+pnpm conventions:check # Typecheck and execute these examples
+pnpm check              # Style, build, typecheck, examples, tests and version consistency
+pnpm smoke:package      # Verify the packaged installation shapes
+```
+
+`biome.json` is the formatting authority: two spaces, LF, a 100-column target,
+double quotes, semicolons, expanded object/array layouts and parenthesized arrow
+parameters. Braces and one variable per declaration keep control flow readable.
+Use the editor's Biome extension with the repository's pinned version if desired;
+`.editorconfig` supplies the basic whitespace settings in other editors.
+
+Biome checks filenames; `check-code-paths.mjs` checks directories containing code
+under `packages/`, `scripts/`, `examples/` and this folder, including new untracked
+files. Both run in CI through `pnpm check`. Human/agent review still checks whether
+names describe intent and whether responsibilities should be split. A formatter
+cannot judge those decisions.
+
+Vertical spacing is also an author/review responsibility: Biome keeps intentional
+blank lines, but does not add separation between declarations or logical steps.
+Follow [TypeScript spacing guidance](typescript.md) even when `check:style` passes.
+
+The [repository skill](../../.agents/skills/penpair-code-conventions/SKILL.md)
+applies this workflow to implementation and refactoring work. It develops Penpair
+itself; the separately shipped `packages/core/skills/` teach consumers how to use
+Penpair with their designs.
+
+## Coverage and exceptions
+
+- Generated `dist/`, dependencies, ignored local artifacts and data fixtures are
+  outside formatting. Keep captured evidence unchanged.
+- `docs/trials/` and `docs/upstream/` preserve external evidence.
+- Raw plugin bodies in `examples/hello-card/`, `examples/theme-preview/` and
+  `examples/trials/` may contain a top-level `return`, which Biome's module parser
+  rejects. Their existing sandbox tests compile them as async function bodies.
+  Follow [plugin code](plugin-code.md) when editing them.
+- JavaScript inside template strings is string data to Biome. Format that source
+  deliberately and test the generated snippet. Do not run blind whitespace
+  rewriting over strings, serialized snapshots or embedded protocols.
+
+Add new file-type examples when an actual feature needs a pattern. Keep them
+minimal and executable; do not introduce a framework or dependency just for a
+template.

package/docs/conventions/completion-2026-10-22.md

@@ -0,0 +1,73 @@
+# Readability conventions completion — 2026-10-22
+
+Branch: `codex/tradient-feedback`. All repository package versions remain 0.2.0.
+
+## Completed checklist and what each update resolves
+
+- [x] **Readable formatting baseline.** Pin Biome 2.6.2, use two-space indentation
+  and expanded layouts, add braces and separate variable declarations. This
+  removes compressed source layouts and makes subsequent diffs consistent. The
+  mechanical baseline is its own commit, `b1a9445`, for review.
+- [x] **Maintained conventions.** Add task-based guidance for naming, package
+  ownership, module extraction, TypeScript, tests and sandbox code. This gives new
+  work a concrete placement and implementation pattern instead of relying on
+  memory or copying unrelated frontend conventions.
+- [x] **Checked examples.** Typecheck actual core contracts and run helper,
+  sandbox-generation and path-rule tests. This catches stale examples and proves
+  that the generated plugin body compiles and behaves as documented.
+- [x] **Agent discovery.** Link the conventions and repository-local
+  `penpair-code-conventions` skill from `AGENTS.md`, with contributor routing from
+  `CONTRIBUTING.md`. This makes readable names and early responsibility extraction
+  part of the implementation workflow.
+- [x] **Continuous enforcement.** Include Biome, directory naming and example
+  validation in `pnpm check`, which existing CI already runs. The CI job name stays
+  stable for branch protection. These checks prevent automatic style/path drift;
+  review still judges the meaning of names and module boundaries.
+- [x] **Comparison adapter extraction.** Replace the dense entrypoint with focused
+  public contracts, planning, capture validation, provider validation, PNG I/O,
+  orchestration and command modules. Public imports, report fields, approval gates
+  and command behavior remain compatible. Shared test fixtures and capture tests
+  also have focused files.
+- [x] **Installed contract verification.** Extend package smoke testing to import
+  the packed adapter's public functions/default export and typecheck its public
+  contracts. This catches missing extracted files or broken declaration exports.
+
+## Validation
+
+- `pnpm check` passes: **640 package tests plus 3 convention tests**, style/path
+  checks, builds, typechecks and the six-package version guard.
+- `pnpm smoke:package` passes for all **six tarballs**, including the new runtime
+  export and declaration checks.
+- The comparison package's tests/helpers also pass a separate strict TypeScript
+  check. Skill YAML metadata, UI metadata and local convention/skill links resolve.
+- Before the manual extraction, an AST comparison across 199 changed
+  JavaScript/TypeScript files found no differences beyond formatting, equivalent
+  control-flow blocks and separate declarations. The initial formatted baseline
+  passed all 630 pre-existing tests.
+- `git diff --check` passes. A patch Changeset records the delivered refactor and
+  documentation. No version bump, push, publication or live Penpot write occurred.
+
+## Limits
+
+Biome cannot determine whether a name expresses the right domain meaning or when
+responsibilities deserve separate modules; the skill and review cover those
+decisions. Raw async plugin bodies, JavaScript inside strings, generated artifacts
+and captured fixtures retain the handling described in the [conventions index](README.md).
+This update does not constitute new live Penpot or browser acceptance. The
+[existing pending acceptance](../plans/tradient-feedback-review.md#remaining-acceptance)
+stays open.
+
+## Vertical spacing correction
+
+- [x] Separate declarations and individual steps in the component pilot module.
+- [x] Clarify that Biome retains author-supplied blank lines but does not insert
+  the separation required by the conventions.
+
+Resolved: `packages/marwes-ui/src/components.ts` passed Biome while remaining
+visually dense. The file now has blank lines between its contracts, functions,
+guards and work steps. The diff contains only added blank lines, and Biome keeps
+them. `pnpm check:style` and all three existing component tests pass. No behavior
+changed; the full suite was not rerun for this whitespace-only follow-up.
+
+Automatic vertical-spacing enforcement remains outside the current Biome checks;
+the conventions and code review require it explicitly.

package/docs/conventions/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -0,0 +1 @@
+{"version":"3.2.4","results":[[":templates/conventions.test.ts",{"duration":5.28132800000003,"failed":false}]]}

package/docs/conventions/plugin-code.md

@@ -0,0 +1,23 @@
+# Penpot plugin source
+
+Node-side TypeScript and the Penpot editor sandbox are different environments.
+The sandbox has `penpot` and explicit injected values such as `CFG`; it cannot
+import Node filesystem modules or reach local project paths. Keep Node I/O outside
+the generated source. Use the neutral kit/snippet APIs and actual upstream names.
+
+Raw plugin files are async function bodies and may return at the top level.
+`*.ts` generators are ordinary Node modules and are formatted by Biome; their
+template string contents need deliberate formatting. Prefer readable multiline
+source with descriptive names and braces. Preserve string values and parameter
+serialization when editing whitespace.
+
+The [frame inspection example](templates/frame-inspection.ts) shows a small
+read-only generator. Its tests compile the generated body and execute it against
+a sandbox stub. This catches syntax and behavior errors that formatting the
+outer TypeScript module cannot catch.
+
+For writes, follow [the write protocol](../../packages/core/skills/penpair-design/references/write-protocol.md):
+inspect, pin a snapshot, perform one idempotent write, independently read back,
+then export and look. Preserve file/page guards, bounded layout settling and the
+under-90-KB transport limit. A syntax test does not prove live Penpot behavior.
+Tests may stub read-only sandbox objects; live acceptance remains separate.

package/docs/conventions/structure.md

@@ -0,0 +1,48 @@
+# Folder and module structure
+
+Place code with the responsibility that owns it. The dependency direction is
+command packages/adapters → core; the core never imports an adapter or names a
+consumer project or component library.
+
+| Location | Owns |
+| --- | --- |
+| `packages/core/src/` | Neutral engine, validation, transport and public extension contracts |
+| `packages/web/`, `packages/docker/`, `packages/penpair/` | Command distribution and profile-specific lifecycle |
+| `packages/<adapter>/src/` | Library/tool knowledge and its adapter commands |
+| `packages/<package>/test/` | That package's behavior and integration contracts |
+| `scripts/` and `scripts/lib/` | Workspace/release tooling and reusable script helpers |
+| `examples/<feature>/` | Consumer-facing workflows and explicit sample project knowledge |
+| `packages/core/skills/` | Shipped consumer workflows |
+| `.agents/skills/` | Skills for developing this repository |
+| `docs/conventions/templates/` | Checked examples, never runtime dependencies |
+
+Use kebab-case for new code directories and filenames. Prefer a domain name such
+as `capture-validation.ts` over `helpers.ts`, `utils.ts` or `manager.ts`. Add a
+feature folder when several related files form one cohesive area; keep small
+features as siblings rather than adding a directory around every file. Preserve
+tool-required names such as `AGENTS.md`, `SKILL.md` and `README.md`.
+
+## Split as soon as a responsibility stands on its own
+
+Extract a responsibility when it has its own inputs/outputs, invariants or useful
+tests. Do this in the change that introduces it. Typical splits are public types,
+argument parsing/provider loading, pure planning, evidence validation and image
+I/O. Keep a package's public `index.ts` focused on exports and adapter wiring.
+Preserve public imports when moving implementations.
+
+The comparison adapter demonstrates this shape: `case-plan.ts` plans approved
+cases, `evidence-validation.ts` validates observed state, `capture-validation.ts`
+checks browser geometry, `png-evidence.ts` reads bounded images, `run-cases.ts`
+orchestrates evidence collection, and `command.ts` handles CLI/provider loading.
+
+Do not split tightly coupled steps solely to make files short. Avoid one-line
+forwarders and a forest of generic folders. Repeated domain code, mixed I/O and
+validation, a long boolean condition, or unrelated reasons for a file to change
+are stronger signals than a line count. Around 200 lines in a module or 40 lines
+in a function is a review prompt, not an automatic failure or a reason to hide
+complexity in another large helper.
+
+Before extracting, identify the public contract and the tests that protect it.
+After extracting, read the orchestration from top to bottom: names should explain
+the workflow without opening every helper. Keep shared types below implementations
+in the dependency direction and avoid circular imports or unnecessary barrels.

package/docs/conventions/templates/adapter-command.ts

@@ -0,0 +1,28 @@
+import type { AdapterCommand, AdapterContext } from "../../../packages/core/src/adapters.js";
+
+async function runExampleStatus(
+  context: AdapterContext,
+  commandArguments: string[],
+): Promise<number> {
+  if (commandArguments.length > 0) {
+    throw new Error("Usage: example-status");
+  }
+
+  const report = {
+    configured: Boolean(context.config.file),
+  };
+  context.output?.result(report);
+  context.log(JSON.stringify(report));
+
+  return report.configured ? 0 : 3;
+}
+
+// Register in an adapter's defineAdapter({ commands: [...] }) when adopting this pattern.
+export const exampleStatusCommand: AdapterCommand = {
+  name: "example-status",
+  summary: "Report offline file-pin readiness",
+  usage: [
+    "penpair example-status",
+  ],
+  run: runExampleStatus,
+};

package/docs/conventions/templates/conventions.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { compiles } from "../../../packages/core/src/snippet.js";
+import { findInvalidCodeDirectories } from "../../../scripts/check-code-paths.mjs";
+import { formatFrameLabel } from "./frame-label.js";
+import { createFrameInspection } from "./frame-inspection.js";
+
+describe("convention examples", () => {
+  it("normalizes names and refuses incomplete labels", () => {
+    expect(
+      formatFrameLabel({
+        pageName: " Dashboard ",
+        frameName: " Empty ",
+      }),
+    ).toBe("Dashboard / Empty");
+    expect(() =>
+      formatFrameLabel({
+        pageName: " ",
+        frameName: "Empty",
+      }),
+    ).toThrow("requires");
+  });
+
+  it("compiles and executes the generated read-only sandbox body", async () => {
+    const inspection = createFrameInspection("Empty");
+    expect(compiles(inspection.code)).toBeUndefined();
+    const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+    const executeInspection = new AsyncFunction("penpot", inspection.code);
+    const frame = {
+      id: "frame-1",
+      type: "board",
+      name: "Empty",
+    };
+
+    expect(
+      await executeInspection({
+        currentPage: {
+          children: [
+            frame,
+          ],
+        },
+      }),
+    ).toEqual({
+      ok: true,
+      frameId: "frame-1",
+      frameName: "Empty",
+    });
+    expect(
+      await executeInspection({
+        currentPage: {
+          children: [
+            frame,
+            frame,
+          ],
+        },
+      }),
+    ).toMatchObject({
+      ok: false,
+    });
+  });
+
+  it("checks new code folders while leaving data paths outside the code rule", () => {
+    expect(
+      findInvalidCodeDirectories([
+        "packages/core/src/capture-validation.ts",
+        "examples/browser-capture/provider.mjs",
+        "docs/conventions/templates/frame-label.ts",
+        "docs/trials/ImportedEvidence/report.json",
+      ]),
+    ).toEqual([]);
+    expect(
+      findInvalidCodeDirectories([
+        "packages/core/src/captureHelpers/geometry.ts",
+        "packages/core/src/captureHelpers/fonts.ts",
+        "examples/BrowserCapture/provider.mjs",
+      ]),
+    ).toEqual([
+      "examples/BrowserCapture",
+      "packages/core/src/captureHelpers",
+    ]);
+  });
+});

package/docs/conventions/templates/frame-inspection.ts

@@ -0,0 +1,27 @@
+import { snippet, type Snippet } from "../../../packages/core/src/snippet.js";
+
+export function createFrameInspection(frameName: string): Snippet {
+  if (!frameName.trim()) {
+    throw new Error("Frame name is required");
+  }
+
+  return snippet(
+    "example-frame-inspection",
+    `
+const matchingFrames = penpot.currentPage.children.filter((shape) => {
+  return shape.type === "board" && shape.name === CFG.frameName;
+});
+
+if (matchingFrames.length !== 1) {
+  return { ok: false, message: "Expected one uniquely named frame" };
+}
+
+const frame = matchingFrames[0];
+return { ok: true, frameId: frame.id, frameName: frame.name };
+`,
+    {
+      frameName,
+    },
+    "read",
+  );
+}

package/docs/conventions/templates/frame-label.ts

@@ -0,0 +1,15 @@
+export interface FrameLabel {
+  pageName: string;
+  frameName: string;
+}
+
+export function formatFrameLabel(label: FrameLabel): string {
+  const pageName = label.pageName.trim();
+  const frameName = label.frameName.trim();
+
+  if (!pageName || !frameName) {
+    throw new Error("A frame label requires a page name and a frame name");
+  }
+
+  return `${pageName} / ${frameName}`;
+}

package/docs/conventions/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "declaration": false,
+    "allowJs": true,
+    "checkJs": true
+  },
+  "include": [
+    "templates/**/*.ts",
+    "vitest.config.ts"
+  ]
+}

package/docs/conventions/typescript.md

@@ -0,0 +1,59 @@
+# TypeScript and naming
+
+Use `pnpm format` and `pnpm check:style`; do not hand-align code against Biome.
+Separate top-level declarations and distinct steps inside a function with blank
+lines. Use braces for every branch and loop, and declare one variable at a time.
+Prefer early exits that leave the main path easy to follow.
+
+Biome preserves these blank lines but does not insert them between declarations
+or logical steps. Add them while writing/reviewing code, before running the
+formatter. A passing style check alone does not prove that vertical spacing follows
+this convention. Separate each top-level declaration (including interfaces and
+type aliases), and separate input preparation, guard clauses, work and returns
+inside a function. Keep a documentation comment attached to its declaration.
+
+## Names carry intent
+
+- Files and folders: `capture-validation.ts`, `page-session/`. Keep conventional
+  `index.ts`, `*.test.ts`, `*.config.ts` and tool-required filenames.
+- Values and functions: `captureMetadata`, `baselineImage`, `implementationCase`,
+  `validateCaptureMetadata`. Use a verb for an action and a noun for a value.
+- Types: `ImplementationCase`, `BrowserCaptureMetadata`. Prefer interfaces for
+  object contracts and unions for finite alternatives.
+- Booleans: `fontsReady`, `hasCurrentApproval`, `isComplete`.
+- Units and encodings: `timeoutMs`, `maxSnippetBytes`, `screenshotHash`,
+  `imageWidth`. Make conversions visible where they happen.
+- Avoid one-letter domain names (`c`, `m`, `r`, `b`) and unexplained abbreviations
+  (`cfg`, `sub`, `rest`) when the full name makes the next line understandable.
+  Familiar small mathematical coordinates (`x`, `y`) remain appropriate.
+- Preserve public field names, CLI flags and external API spelling. Improve a
+  local binding without renaming a persisted schema or an upstream property.
+
+Use `const` unless reassignment is needed. Export named functions and types;
+adapter definitions retain the default export required by their loader. Give
+exported functions explicit return types. Use `unknown` with validation at input
+boundaries rather than `any` or a cast that pretends an external value was checked.
+
+## Functions and errors
+
+A function should name one operation at one level of detail. Extract a named
+predicate when a condition combines independently meaningful rules; retain the
+short-circuit checks that protect access to malformed input. Extract filesystem
+work from pure validation when each can be tested independently.
+
+Throw errors with actionable domain context. Catch them where a caller can choose
+recovery, report a failed case or return a command exit code. Preserve existing
+error classifications, redaction and cancellation behavior during a refactor.
+Comment on non-obvious reasons; use names to explain routine steps.
+
+## Tests
+
+Use the package's Vitest runner and its existing `test/` layout. Test observable
+contracts: accepted evidence, rejected malformed/stale evidence, partial progress,
+and filesystem boundaries. Keep fixtures local and deterministic. For a refactor,
+keep a public-entrypoint integration test and add regression cases for the rules
+being extracted. Avoid tests that only search for an implementation's wording.
+
+Production TypeScript uses ESM imports with `.js` for local modules. Match the
+existing NodeNext configuration. Documentation templates import actual core types
+so API changes invalidate stale examples during `pnpm check`.

package/docs/conventions/vitest.config.ts

@@ -0,0 +1,11 @@
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  root: fileURLToPath(new URL("./", import.meta.url)),
+  test: {
+    include: [
+      "templates/**/*.test.ts",
+    ],
+  },
+});

package/docs/cookbook.md

@@ -0,0 +1,25 @@
+# Cookbook
+
+## Add a page
+
+Confirm the target and active token vocabulary. Start with the [Hello-card example](../examples/hello-card/README.md), then compose reviewed project recipes through [the build kit](build-kit.md). Inspect/apply/read back, export twice and obtain owner review. Adapt the project naming convention for page/state/device; retain IDs and ownership markers for recovery.
+
+## Update library tokens
+
+Run the configured adapter's snapshot/check commands, review the declaration diff, then inspect live reconciliation before applying. The [token adapter guide](marwes.md) covers ownership/adoption conflicts and measured component limits. A stale snapshot or intentional designer edit requires a declaration/ownership decision rather than a blind overwrite.
+
+## Onboard a colleague
+
+Share config and the owner-authorized file pin through Git. Follow [team onboarding](team.md) with separate accounts/keys and write coordination. Doctor must observe the intended file. Localhost Docker instances are not automatically shared deployments.
+
+## Rotate a key
+
+Use the provider's own key-management UI and the private `connect --replace` flow. Reconnect the intended editor, run doctor and retain the same public file pin. Keep key values out of chat, command arguments, commits and reports. File/OS credential references are documented with their implemented provider support; avoid inventing external command helpers.
+
+## Move to another Penpot
+
+Obtain owner authorization, create an independent archive and prove a scratch import before changing the project target. Confirm all new public file/page/component IDs and update explicit mappings. Start a new evidence lineage; hashes/approvals from another file do not transfer just because frame names match.
+
+## Recover interrupted work
+
+Inspect the recorded run and the actual pinned objects; follow [recovery](recovery.md) with unchanged source/parameters and explicit resume. Preserve third-party edits. For disaster recovery use [backup/restore](backup.md), not a structural snapshot: the [review snapshot](snapshots.md) intentionally lacks full native fidelity.