@penpair/web 0.1.1 → 0.1.2

package/README.md

@@ -128,14 +128,22 @@ Everyone who works with the assistant does their own `npx @penpair/web connect`:
 | [`@penpair/docker`](https://www.npmjs.com/package/@penpair/docker) | The same command, plus Penpot in Docker on your computer: `up`, `down`, `backup`, `restore`. Includes everything in the core | 0.1.1 |
 | [`@penpair/core`](https://www.npmjs.com/package/@penpair/core) | The library and engine, with the skills. No command of its own; the two above are built on it | 0.1.1 |
 | `penpair` | The short name for `@penpair/web`, so that `npx penpair setup` works | Waiting for npm to allow the name (it is blocked as too close to an unrelated package). Until then use `npx @penpair/web`. |
-| `@penpair/marwes-ui` | The adapter for the Marwes UI component library | Planned, see below |
+| [`@penpair/marwes-ui`](https://www.npmjs.com/package/@penpair/marwes-ui) | The adapter for the Marwes UI component library: Marwes tokens (and your theme) in Penpot, with drift checks | Tokens now; components planned. See below |
 | `@penpair/reflection-check` | The link to Reflection's `reflection-check`, as its own package (today `penpair baselines` does it) | Planned |
 
 You install **one** command package, `@penpair/web` or `@penpair/docker`; the core comes with it.
 
 ## Use it with Marwes
 
-Using [Marwes UI](https://marwes.io), the themeable component library for React, Vue and Svelte? Connecting Marwes is the recommended setup: your Penpot file then speaks the same tokens and components as your code, so what is designed is what gets built. The adapter, `@penpair/marwes-ui`, is the next package on the plan: it will import the Marwes tokens into your Penpot file and check that frames use them. Until it ships, set up penpair as above and name Marwes as your library in the project facts the setup skill asks you to fill in; the assistant then works against Marwes's tokens and components.
+Using [Marwes UI](https://marwes.io), the themeable component library for React, Vue and Svelte? Connecting Marwes is the recommended setup: your Penpot file then speaks the same tokens as your code, so what is designed is what gets built.
+
+```bash
+npm i -D @penpair/marwes-ui
+npx penpair marwes tokens snapshot --write     # the expected tokens, from the installed Marwes and your own theme
+npx penpair marwes tokens push --apply         # Penpot gets them: Marwes sets, plus a small overlay of what your theme changes
+```
+
+The part that keeps it solid is drift: a Marwes upgrade, a theme edit or a hand edit in Penpot is found, not discovered later. `penpair marwes tokens check` runs offline in CI and fails when the committed snapshot no longer matches the installed Marwes; `diff` shows what Penpot lacks and how many shapes each changed token reaches. How it works and how to put it in CI: [Marwes tokens in Penpot, and keeping them true](https://github.com/niklas-westman/penpair/blob/main/docs/marwes-tokens.md). Marwes components in Penpot are not covered yet; they are built as your pages need them.
 
 ## Check each page with Reflection
 
@@ -184,7 +192,7 @@ If you were told to set penpair up, read [the setup skill](https://github.com/ni
 - Run `npx @penpair/web doctor --json` to see where things stand; every failing check carries a `remedy`.
 - Web is the default; use Docker only when the person asks for offline or local data.
 - **The personal MCP key never goes through you.** The person pastes it themselves into `npx @penpair/web connect` (a hidden prompt), or pipes it from their clipboard.
-- Done means `doctor` reports `ok: true` and "editor and plugin" connected. Then `npx @penpair/web skills install` gives you the rules for working in Penpot (`penpot-design`) and for judging a screen (`design-judgment`).
+- Done means `doctor` reports `ok: true` and "editor and plugin" connected. Then `npx @penpair/web skills install` gives you the rules for working in Penpot (`penpair-design`) and for judging a screen (`design-judgment`).
 
 ## Commands
 
@@ -211,6 +219,7 @@ If you were told to set penpair up, read [the setup skill](https://github.com/ni
 
 - [Getting started](https://github.com/niklas-westman/penpair/blob/main/docs/getting-started.md): step by step, for designers and for whoever sets it up
 - [Guide](https://github.com/niklas-westman/penpair/blob/main/docs/guide.md): extension points, instances, commands
+- [Marwes tokens](https://github.com/niklas-westman/penpair/blob/main/docs/marwes-tokens.md): Marwes tokens in Penpot and drift checks
 - [Compatibility](https://github.com/niklas-westman/penpair/blob/main/docs/compatibility.md): what was checked on which Penpot
 - [Releasing](https://github.com/niklas-westman/penpair/blob/main/docs/releasing.md), [Changelog](https://github.com/niklas-westman/penpair/blob/main/CHANGELOG.md)
 

package/docs/getting-started.md

@@ -62,7 +62,7 @@ If you want to know what your Penpot offers before you start, `npx @penpair/web
 ```
 npx @penpair/web skills install
 ```
-This copies the rules the assistant follows (how to work safely in Penpot, and how to judge a screen) into `.skills/` and makes them visible to Codex and Claude Code. It prints a line for each to add to your `AGENTS.md`. Then fill in `.skills/penpot-design/references/project-facts.md` (your file, never replaced): the Penpot file, the token sets, the names you use, who approves.
+This copies the rules the assistant follows (how to work safely in Penpot, and how to judge a screen) into `.skills/` and makes them visible to Codex and Claude Code. It prints a line for each to add to your `AGENTS.md`. Then fill in `.skills/penpair-design/references/project-facts.md` (your file, never replaced): the Penpot file, the token sets, the names you use, who approves.
 
 ### Every day
 Open the file in Penpot, choose **File, MCP Server, Connect**, keep the tab visible, and start working with the assistant.

package/docs/guide.md

@@ -6,7 +6,7 @@ The contract an adopting project works through. It grows with the code; each sec
 | Point | A project supplies | First implementations |
 | --- | --- | --- |
 | Connection profile | endpoint, Penpot version, where the token comes from | local Docker, shared self-hosted, hosted |
-| Library adapter | where tokens and components come from | Marwes |
+| Library adapter | where tokens and components come from; commands the adapter adds, listed under `adapters` in `penpair.config.json` (`defineAdapter` in `@penpair/core`) | `@penpair/marwes-ui` (tokens) |
 | Snippet registry | named plugin snippets with inputs and a size check | tree, audit, tokens, archive |
 | Verification provider | what "matches the design" means | `penpair baselines` (images and Reflection cases, below), a page-verify gate |
 | Skill pack | rules the agent follows | the Penpot skill, design judgment |

package/docs/marwes-tokens.md

@@ -0,0 +1,119 @@
+# Marwes tokens in Penpot, and keeping them true
+
+`@penpair/marwes-ui` puts the design tokens of [Marwes UI](https://marwes.io) (and your own theme on top of them) into your Penpot file, and keeps them from drifting away from the Marwes your app actually uses. The idea in one line: **the installed Marwes and your theme file are the truth; Penpot is made to match, and anything that stops matching is found.**
+
+## How it fits together
+
+```
+  installed Marwes  ─┐
+  (@marwes-ui/core)  ├──▶  expected tokens  ──▶  committed snapshot  ──▶  Penpot file
+  your theme file   ─┘     (generated)           design/…snapshot.json     (sets and themes)
+  (acmeLight …)                              reviewed in git
+```
+
+- **Nothing is typed in twice.** The tokens are generated from the Marwes the app resolves and from the theme file the app imports (the same file and export), so what you design with is what the app renders.
+- **Your choices stay visible.** Marwes's own values go in `Marwes · Core` and `Marwes · Dark`. What your theme changes goes in a small overlay set on top (`Acme · Light`, `Acme · Dark`), holding only the differences. A Marwes update moves the Marwes sets and never silently loses your choices, and the colours Marwes derives from yours (hover, pressed, disabled) follow automatically.
+- **The snapshot is the record.** `design/marwes-tokens.snapshot.json` is generated, committed and reviewed like code. A Marwes bump shows up as a readable git diff of exactly which tokens changed.
+
+## Setup
+
+```bash
+npm i -D @penpair/marwes-ui        # next to @penpair/web (or @penpair/docker)
+```
+
+In `penpair.config.json`:
+
+```json
+{
+  "adapters": ["@penpair/marwes-ui"],
+  "marwes": {
+    "name": "Acme",
+    "project": "packages/app",
+    "themes": {
+      "light": { "module": "packages/app/src/theme.ts", "export": "acmeLight" },
+      "dark":  { "module": "packages/app/src/theme.ts", "export": "acmeDark" }
+    },
+    "snapshot": "design/marwes-tokens.snapshot.json"
+  }
+}
+```
+
+| Setting | Meaning |
+| --- | --- |
+| `name` | Prefix for your overlay sets. Defaults to the instance name, capitalised. |
+| `project` | The folder of the package that depends on Marwes (a workspace package in a monorepo). Default: the project root. |
+| `themes` | Your own light and dark themes: a file and the name of its export (a Marwes `ThemeInput`; TypeScript is fine). Leave them out and only the Marwes sets are made. |
+| `snapshot` | Where the committed snapshot lives. Default: `design/marwes-tokens.snapshot.json`. |
+
+Then:
+
+```bash
+penpair marwes tokens snapshot --write     # generate the expectation and save it; commit the file
+penpair marwes tokens push --apply         # make Penpot match (look first without --apply)
+```
+
+## The commands
+
+| Command | Needs Penpot | What it does |
+| --- | --- | --- |
+| `penpair marwes tokens snapshot [--write]` | no | Builds the expected tokens from the installed Marwes and your theme, and shows how they differ from the committed snapshot. `--write` saves it. |
+| `penpair marwes tokens check [--json]` | no | Is the committed snapshot current? Exit 0 yes, 2 stale or missing, 1 broken (for example a half-finished Marwes upgrade). Made for CI. |
+| `penpair marwes tokens diff [--json]` | yes | Penpot against the snapshot: what is missing, what differs, what was added by hand, and **how many shapes use each changed token**. |
+| `penpair marwes tokens push [--apply] [--prune]` | yes | Brings Penpot to the snapshot. Looks first and prints the plan; `--apply` writes. |
+| `penpair marwes tokens status` | optional | One screen: the installed Marwes packages, the snapshot, and Penpot. |
+
+## What can drift, and what catches it
+
+| What drifted | Caught by | Resolved by |
+| --- | --- | --- |
+| Marwes was upgraded (any token changed, added or removed) | `check` (offline, in CI): the snapshot is stale | `snapshot --write`, review the git diff, commit, then `push --apply` |
+| Your theme file changed | `check`: the snapshot is stale | the same |
+| Marwes packages are at different versions (a half-finished upgrade) | `check` fails with exit 1 | finish the upgrade; Marwes releases its packages together |
+| **Marwes grew a kind of variable the adapter does not turn into a token** | `check`: the snapshot lists every variable it does not cover, so a new one changes it | review it, then extend the adapter or accept it by writing the snapshot |
+| Someone edited a token in Penpot by hand | `diff`: shown as a difference, with what it reaches | `push --apply` puts it back (Marwes is authoritative) |
+| Someone added a token to a Marwes set by hand | `diff`: "not in the expectation" | kept unless you push with `--prune` |
+| A set was deleted or a theme changed in Penpot | `diff` | `push --apply` |
+| The recorded Marwes version (in every token's description) is old | `diff` | `push --apply` updates it, so the file says which Marwes it came from |
+
+## After a Marwes bump
+
+```bash
+pnpm up @marwes-ui/react                          # the app moves to the new Marwes
+penpair marwes tokens check                       # fails: the snapshot is stale, and says what changed
+penpair marwes tokens snapshot --write            # regenerate; review `git diff design/` (the tokens that moved)
+penpair marwes tokens diff                        # what Penpot lacks, and how many shapes each change reaches
+penpair marwes tokens push --apply                # bring Penpot along; it reads everything back to verify
+```
+
+`push` refuses to run while the snapshot is stale: the repository's record must lead, so a token never reaches Penpot that has not been through a commit. After the push, export your pages and let [Reflection](https://github.com/niklas-westman/reflection) show you what the new tokens changed visually.
+
+## Keeping it from drifting in the first place
+
+- **CI.** Add the check to the same pipeline that runs your tests: `penpair marwes tokens check`. It needs no Penpot and no key, so it runs anywhere. A pull request that bumps Marwes (by hand or by a dependency bot) or edits the theme without a new snapshot cannot merge.
+- **A test, if you prefer.** The adapter exports the same check for your test runner:
+
+  ```ts
+  import { checkTokenSnapshot } from "@penpair/marwes-ui";
+
+  it("the Penpot token snapshot is current", async () => {
+    const check = await checkTokenSnapshot(process.cwd());
+    expect(check.problems).toEqual([]);
+    expect(check.current).toBe(true);
+  });
+  ```
+
+- **Before designing.** `penpair marwes tokens status` takes a second and says whether the design file is on the Marwes the app uses.
+
+## What `push` does and does not touch
+
+- It manages only the sets the snapshot names (`Marwes · …` and your `Acme · Light/Dark`). Any other set in the file is yours and is never touched.
+- It creates new sets inactive and builds the Light and Dark themes. If the file has **no active theme**, it activates Light so the tokens take part; a file that already has an active theme keeps its choice.
+- Plain values are updated in place. Typography tokens are removed and added again, because Penpot stores a typography value assigned in place un-normalised.
+- Tokens go in batches that stay under Penpot's request limit, and it stops at the first token Penpot rejects and says which.
+- Afterwards it reads everything back: the file must match the snapshot, and **no shape may have moved or been rebound** (a fingerprint of every page's structure is compared before and after). Otherwise it says so and exits 1.
+
+## What is covered, and what is not
+
+Everything Marwes resolves for a theme becomes a token: colours, density sizes, the two radii, the three font families and the typography styles, plus the spacing scale. A variable that is not (today: `--mw-density-spacing-multiplier`, a multiplier) is listed in the snapshot's `unmapped` field and in `snapshot` output, so the gap is visible and a change to it is noticed.
+
+Not covered yet: Marwes **components** in Penpot. Tokens come first; components are built as pages need them.

package/docs/releasing.md

@@ -1,6 +1,6 @@
 # Releasing
 
-All packages in this repository are released **together, at one version, even a package that did not change**: `@penpair/core`, `@penpair/web`, `@penpair/docker`, `penpair`, and anything added under `packages/` later. The root of the repository is a private workspace and is never published. The rule is enforced, not remembered:
+All packages in this repository are released **together, at one version, even a package that did not change**: `@penpair/core`, `@penpair/web`, `@penpair/docker`, `@penpair/marwes-ui`, `penpair`, and anything added under `packages/` later. The root of the repository is a private workspace and is never published. The rule is enforced, not remembered:
 
 | Guard | What it stops |
 | --- | --- |
@@ -63,13 +63,14 @@ The release is then reported as `INCOMPLETE` (exit code 3) on purpose, and `pnpm
 npm view @penpair/core version
 npm view @penpair/web version
 npm view @penpair/docker version
+npm view @penpair/marwes-ui version
 ```
 
 Then, in an empty folder, run `npx @penpair/web --version`, `npx @penpair/web setup --help` and `npx @penpair/docker --version` (and, once the short name is published, the same with `npx penpair`). Tag the release if you want one: `git tag v<version> && git push origin v<version>`.
 
 ## What each package ships
 
-The core ships `dist`, `skills`, `LICENSE` and a short `README.md`. The web package ships `dist`, `docs`, `LICENSE` and the repository's `README.md` (copied in by `prepack`, git-ignored there). The Docker package ships `dist`, `LICENSE` and `README.md`. The short name ships `bin`, `LICENSE` and `README.md`. Check with `npm pack --dry-run --ignore-scripts` in a package.
+The core ships `dist`, `skills`, `LICENSE` and a short `README.md`. The web package ships `dist`, `docs`, `LICENSE` and the repository's `README.md` (copied in by `prepack`, git-ignored there). The Docker package and the Marwes adapter ship `dist`, `LICENSE` and `README.md`. The short name ships `bin`, `LICENSE` and `README.md`. Check with `npm pack --dry-run --ignore-scripts` in a package.
 
 ## After publishing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/web",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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": {
@@ -20,8 +20,8 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
     "./cli": "./dist/cli.js",
     "./package.json": "./package.json"
@@ -47,7 +47,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@penpair/core": "0.1.1"
+    "@penpair/core": "0.1.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",