partforge 0.26.1 → 0.28.0

package/README.md

@@ -99,10 +99,11 @@ const runtime = mount(part, {
   createWorker,
   elements: {
     viewer, controls,                       // canvas host + param-panel host
+    rail,                                   // full-height resizable/collapsible controls rail
     status: { status, busy, phase },        // status chrome
     tabs,                                   // view-tab segmented control
     exports: { stl, step, threeMf },        // export buttons
-    chrome: { pause, reframe, theme },      // viewer buttons
+    chrome: { pause, reframe, theme, railToggle }, // viewer buttons + rail collapse/restore
   },
   onBuild: ({ status, ms, error }) => {},   // per accepted build: "success" | "error"
   onPick: ({ selection, label, prompt, token }) => {}, // programmatic click-to-select
@@ -112,9 +113,20 @@ runtime.dispose();     // stops loops, workers, observers, listeners; frees GPU
 ```
 
 Every `elements` entry defaults to the legacy global ID (`#app`, `#controls`,
-`#status`/`#busy`/`#phase`, `#part`, `#download`/`#download-step`/`#download-3mf`,
-`#pause`/`#reframe`/`#theme`), so a classic host page needs no changes. The viewer
-sizes from its container via ResizeObserver — no window coupling.
+`#panel` for `rail`, `#status`/`#busy`/`#phase`, `#part`,
+`#download`/`#download-step`/`#download-3mf`,
+`#pause`/`#reframe`/`#theme`/`#rail-toggle`), so a classic host page needs no
+changes. The viewer sizes from its container via ResizeObserver — no window
+coupling.
+
+`rail` is the full-height controls rail introduced by the resizable-panel
+layout (`docs/superpowers/specs/2026-07-26-controls-rail-layout-design.md`);
+`chrome.railToggle` is its optional collapse/restore button. Both are optional
+— a host that lays out the framework itself (no rail markup) gets a no-op.
+The rail's resize seam is positioned against `rail.parentElement` by default,
+so **the rail must be a direct child of the positioned `.pf-shell`** unless
+the host also supplies `elements.shell` to point at the real containing block
+(e.g. when a wrapper div sits between them, as is common in a React layout).
 
 `onPick` arms click-to-select permanently: `label` is the feature label (falling
 back to the sub-part label/name) for compact UI, `prompt` is the LLM-ready

package/bin/cli.js

@@ -15,9 +15,10 @@ import { verify } from "../src/testing/verify.js";
 import { renderViews } from "../src/testing/render.js";
 import { createPickServer, requestPicks, formatPickResult } from "../src/framework/pick-request/server.js";
 import { matchPattern } from "../src/testing/error-patterns.js";
+import { lintPart } from "../src/lint.js";
 
 const die = (msg) => { console.error(msg); process.exit(1); };
-const USAGE = "usage: partforge <measure|render|pick-serve|pick> …";
+const USAGE = "usage: partforge <lint|measure|render|pick-serve|pick> …";
 
 // Crash contract (issue #27): with --json, a thrown error becomes structured
 // stdout JSON; either way the message is matched against ERROR-PATTERNS.md and
@@ -59,16 +60,57 @@ async function loadPart(partPath, usage) {
 const bootKernel = (part) => (detectBackend(part) === "occt" ? bootOcctKernel() : bootManifoldKernel());
 
 const commands = {
+  async lint(args) {
+    const usage = "usage: partforge lint <part-module> [--params <json>] [--json] [--out <file>] [--strict]";
+    const { values: flags, positionals: [partPath] } = parse(args, {
+      params: { type: "string" },
+      json: { type: "boolean" },
+      out: { type: "string" },
+      strict: { type: "boolean" },
+    }, usage);
+    try {
+      const part = await loadPart(partPath, usage);
+      const params = flags.params ? JSON.parse(flags.params) : undefined;
+      const report = lintPart(part, { params });
+      if (!flags.json) printLint(report);
+      if (flags.out) {
+        mkdirSync(dirname(resolve(flags.out)), { recursive: true });
+        writeFileSync(flags.out, JSON.stringify(report, null, 2));
+        console.log(`\nwrote ${flags.out}`);
+      }
+      if (flags.json) console.log(JSON.stringify(report, null, 2));
+      process.exit(report.ok && (!flags.strict || report.warnings.length === 0) ? 0 : 1);
+    } catch (e) {
+      crash("lint", e, !!flags.json);
+    }
+  },
+
   async measure(args) {
-    const usage = "usage: partforge measure <part-module> [view] [--process <profile>] [--no-verify] [--json] [--out <file>]";
+    const usage = "usage: partforge measure <part-module> [view] [--process <profile>] [--no-verify] [--no-lint] [--json] [--out <file>]";
     const { values: flags, positionals: [partPath, view] } = parse(args, {
       process: { type: "string" },
       "no-verify": { type: "boolean" },
+      "no-lint": { type: "boolean" },
       json: { type: "boolean" },
       out: { type: "string" },
     }, usage);
     try {
       const part = await loadPart(partPath, usage);
+      // Error-tier lint before the kernel boots: a statically broken part fails in
+      // milliseconds with a precise message rather than after a WASM boot and a
+      // downstream error that doesn't name the cause. Warnings never gate measure.
+      if (!flags["no-lint"]) {
+        const lint = lintPart(part);
+        if (!lint.ok) {
+          if (flags.json) console.log(JSON.stringify({ ok: false, lint }, null, 2));
+          else printLint(lint);
+          if (flags.out) {
+            mkdirSync(dirname(resolve(flags.out)), { recursive: true });
+            writeFileSync(flags.out, JSON.stringify({ ok: false, lint }, null, 2));
+          }
+          process.exit(1);
+        }
+      }
       const kernel = await bootKernel(part);
       const report = measure(kernel, part, view);
       printMeasure(report);
@@ -172,6 +214,19 @@ function printVerify(v) {
   console.log(`  result: ${f ? `${f} gate failure(s)` : "all gates passed"}${w ? `, ${w} warning(s)` : ""}`);
 }
 
+function printLint(r) {
+  const all = [...r.errors, ...r.warnings];
+  if (all.length === 0) { console.log("lint: clean"); return; }
+  console.log("lint:");
+  for (const f of all) {
+    console.log(`  ${f.severity === "error" ? "✗" : "⚠"} ${f.rule}${f.path ? `  ${f.path}` : ""}`);
+    console.log(`      ${f.message}`);
+    console.log(`      hint: ${f.hint}${f.pattern ? ` (ERROR-PATTERNS.md#${f.pattern})` : ""}`);
+  }
+  const e = r.errors.length, w = r.warnings.length;
+  console.log(`  result: ${e ? `${e} error(s)` : "no errors"}${w ? `, ${w} warning(s)` : ""}`);
+}
+
 const [, , cmd, ...args] = process.argv;
 if (!commands[cmd]) die(USAGE);
 await commands[cmd](args);

package/docs/AUTHORING-PARTS.md

@@ -30,8 +30,9 @@ OCCT-only fillet/chamfer/shell ops.
    `http://localhost:5173/<your-part>.html`.
 
 That's the whole loop. The chrome (panel, tabs, viewer, export buttons) is shared —
-your HTML is ~30 lines of structural markup and carries no CSS (the framework
-supplies it via `framework/app.css`, imported by `mount`).
+your HTML is structural markup only and carries no CSS (the framework supplies it via
+`framework/app.css`, imported by `mount`). See "Wiring a part into a runnable app"
+below for what that markup must contain.
 
 ---
 
@@ -390,6 +391,28 @@ choosing a preset updates both numeric and text fields.
 Every `key` used must exist in `defaults`. `src/parts/demo.js` is the worked example for
 everything below.
 
+**Standalone toggles** (a plain on/off checkbox, no accompanying sliders): add a
+`toggles` array to a preset section — shown below the preset picker, outside the
+Advanced fold, so it stays visible:
+
+```js
+{
+  id: "shape",
+  title: "Shape ops",
+  toggles: [
+    { key: "clip", label: "Clip arms to a disc (intersect)", on: 1,
+      description: "**Intersect** the cross with a circle so the four arm tips are rounded off to a common radius." },
+  ],
+}
+```
+
+Each entry is `{ key, label, on?, hidden?, description? }`: checked sets `key` to `on`
+(default `1`); unchecked sets it to `0`. This is the correct home for a bare boolean —
+a `features` entry *requires* a `sliders` array (the panel reads `feat.sliders.filter(...)`
+unguarded and throws if it's missing), so a feature with nothing to reveal belongs in
+`toggles` instead. `src/parts/bracket.js`'s `clip` toggle (shown above) is the worked
+example.
+
 **Control metadata (optional — on any control def, feature, or section):**
 
 - `description` — a CommonMark string shown in a click-open **ⓘ** popover beside the
@@ -666,37 +689,121 @@ stylesheet). `mount` looks up these element IDs:
 | `#download-step` / `#download` / `#download-3mf` | STEP / STL / 3MF export buttons |
 | `#status`, `#busy`, `#phase` | status line + busy overlay |
 | `#viewbar` with `#pause` / `#reframe` / `#cutaway` / `#theme` | optional viewer controls (omit any you don't want) |
-
-Copy `demo.html` and change the title, the panel heading, and the `<script src>`. Two workers are spawned from your one worker entry
-(`name` = `"manifold"` for preview/STL/3MF, `"occt"` for STEP — handled for you).
+| `#panel` | the full-height controls rail (`class="pf-rail"`); programmatic hosts pass `elements.rail` instead |
+| `#rail-toggle` | optional — collapses/restores the rail; resolved the same way as `#pause`/`#theme` |
+
+Copy `demo.html` and change the title, the panel heading, and the `<script src>`. Two
+workers are spawned from your one worker entry (`name` = `"manifold"` for preview/STL/3MF,
+`"occt"` for STEP — handled for you).
+
+**The markup convention (`demo.html` is the canonical copy-me page):** `<body>` carries
+`class="pf-shell"`, the flex row that lays the viewer column next to the rail. `#app`
+(`class="pf-stage"`) *is* that viewer column, and now contains the floating chrome
+(`#topbar`, `#viewbar`, `#busy`) as absolutely-positioned siblings of the canvas, not
+page-level overlays. `#panel` (`class="pf-rail"`) is a full-height rail docked to the
+right edge, split into three children — `.pf-rail-head` / `.pf-rail-body` /
+`.pf-rail-foot` — of which head and foot are flex-fixed and only the body scrolls: put
+your heading in the head and the download row in the foot so the export buttons never
+scroll out of reach. The rail's drag/collapse seam is created by `rail.js` itself; don't
+add markup for it. This isn't decorative — get the head/body/foot split wrong and either
+the export buttons scroll away or a tall parameter list pushes them off-screen. See
+`docs/superpowers/specs/2026-07-26-controls-rail-layout-design.md` for why the rail is
+shaped this way (resize/collapse behavior, breakpoints, the design rationale).
+
+**Keyboard (the seam is `role="separator"`, focusable, `tabIndex=0`):**
+
+| Key | Action |
+|---|---|
+| ← | widen the rail 16px (64px with Shift). No-op while collapsed. |
+| → | narrow the rail 16px (64px with Shift), clamped at the 240px minimum — never collapses. No-op while collapsed. |
+| Home | jump to the 240px minimum, animated. Reopens even while collapsed. |
+| End | jump to the clamped maximum (half the shell, capped at 560px), animated. Reopens even while collapsed. |
+| Enter / Space | toggle collapse — collapses if open; reopens at the remembered width if collapsed. |
+| double-click (on the seam) | reset to the 288px default, animated, and opens if collapsed. |
+
+Arrow keys move the **separator**, not the pane — standard `role="separator"`
+semantics, and why ← *widens* a right-hand rail. `Cmd`/`Ctrl`/`Alt` held with an
+arrow key passes through untouched (those are OS/browser-reserved combos, e.g.
+back navigation or window-switching); `Shift` alone still applies the larger
+step. Collapsed, the two arrow keys are deliberate no-ops rather than a reopen
+gesture — reopening would otherwise silently discard the remembered width and
+clamp to the minimum, and "press an arrow, get narrower" reads backwards for a
+rail that's already shut. Home/End and Enter/Space/double-click are exempt from
+that rule and always reopen, since jumping to an explicit width or toggling is
+an unambiguous, deliberate gesture either way. A held arrow-key repeat
+suppresses the 150ms width transition for the whole repeat window (not just one
+keydown), matching what happens during a drag.
+
+Legacy id-only markup (predating this class scheme) still renders: `app.css` keeps
+`:not(.pf-*)` fallbacks (`#app:not(.pf-stage)`, `#panel:not(.pf-rail)`, and
+placement-only ones for `#topbar`/`#viewbar`) that reproduce the old floating-card
+look — `:not()` rather than a plain id rule because an id selector outranks a class. New
+apps should still use the classed markup above; the fallback exists for pages that
+predate it, not as a second supported style.
+
+A host that builds its own DOM instead of using `mount`'s markup (e.g. an editor
+embedding the viewer/rail inside a larger UI) can adopt the same layout by importing
+**`partforge/chrome.css`** directly — it's deliberately class-based and id-free for that
+reason. It expects `partforge/tokens.css` to already be loaded for its `--pf-*` custom
+properties, and expects the host to size `.pf-shell` itself (`mount`'s own `app.css`,
+which `@import`s both, does both of these for you already).
 
 `#cutaway` is optional viewer chrome. When present, it toggles an interactive
 section plane whose exposed faces are hatched; changing views resets it. Cutaway
 is viewer-only and never changes STL, STEP, or 3MF exports. Hosts that omit the
 button get no cutaway UI.
 
-Programmatic hosts can provide the same optional control without relying on an
-ID by passing it beside the other chrome references:
+Programmatic hosts can provide the same optional controls, including the rail toggle,
+without relying on an ID by passing them beside the other chrome references — and can
+pass the rail itself as `elements.rail` instead of relying on `#panel`:
 
 ```js
 mount(part, {
   createWorker,
   elements: {
+    rail,
     chrome: {
       pause,
       reframe,
       cutaway,
       theme,
+      railToggle,
     },
   },
 });
 ```
 
+`rail`/`chrome.railToggle` are both optional; a host with no rail markup gets a
+no-op (the resize/collapse behavior below simply doesn't attach). **Constraint:**
+the rail element must be a direct child of the positioned `.pf-shell` — the
+resize seam is created and positioned against `rail.parentElement` by default,
+so an extra wrapper div between them (common in a React layout) puts the seam
+against the wrong ancestor and silently breaks `[data-pf-dragging] .pf-stage`.
+A host that can't make the rail a direct child of `.pf-shell` must also pass
+`elements.shell` pointing at the real positioned ancestor:
+
+```js
+mount(part, {
+  createWorker,
+  elements: { rail, shell, chrome: { railToggle } },
+});
+```
+
 > Production deploy compiles only the pages listed in `build.rollupOptions.input`
 > (currently the landing gallery + the demo part pages). Other root `*.html` files are
 > **dev-only** (Vite serves any root HTML in `npm run dev`) unless added there. To also
 > ship one, add it to `build.rollupOptions.input` in `vite.config.js`.
 
+**Styling hooks:** the rail/stage layout and palette are both plain `--pf-*` custom
+properties from `partforge/tokens.css`, overridable on `:root` (or
+`:root[data-theme="light"]`) without touching `chrome.css`. Layout/shape tokens added
+alongside the rail: `--pf-sans`, `--pf-rail-w`, `--pf-rail-pad`, `--pf-radius-control`,
+`--pf-radius-pill`, `--pf-shadow-float`, `--pf-shadow-rail`. The dev demos self-host
+Geist and Geist Mono (`@fontsource-variable/geist(-mono)`, a `devDependency`, imported
+from each `app-<part>.js` — see `src/app-demo.js`) so a standalone forge looks like the
+finished product; the published library ships no font files, and a consumer that loads
+none falls through `--pf-sans`/`--pf-mono` to system stacks by design.
+
 ### Developing against a local (linked) partforge
 
 A normal `npm install partforge` needs no extra config. But if you `npm link` a local
@@ -785,6 +892,83 @@ The `measure` function is also exported for vitest (boot a Manifold kernel as in
       expect(r.subparts[0].holes).toBe(1);   // e.g. expects one bore
     });
 
+## Linting
+
+`partforge lint` statically validates a PartDefinition without booting a geometry
+kernel. It runs in milliseconds and catches the authoring mistakes that otherwise
+surface only at runtime — or, worse, not at all.
+
+```bash
+npx partforge lint src/parts/<part>.js [--params '{"h":40}'] [--json] [--out f] [--strict]
+```
+
+Exit 0 when clean, 1 when any **error** finding is present; `--strict` also fails on
+warnings. `partforge measure` runs the error tier automatically before booting a
+kernel — pass `--no-lint` to skip it.
+
+The same check is available programmatically and in the browser:
+
+```js
+import { lintPart } from "partforge/lint";
+const { ok, errors, warnings } = lintPart(part, { params });
+```
+
+`partforge/lint` has **zero runtime dependencies** and never imports a geometry
+kernel or the DOM viewer, so it runs unchanged in Node, a Web Worker, a sandboxed
+iframe, and Deno. A worker also answers `{ type: "lint", params }` with
+`{ type: "lint-report", report }` without booting its kernel.
+
+**Findings** carry the same guarantees as verify's checks — a self-contained `hint`
+on every one, and a stable `pattern` id where an ERROR-PATTERNS.md entry applies:
+
+```js
+{ rule: "features-requires-sliders", severity: "error",
+  message: "section \"flange\" feature 0 has no `sliders` array",
+  hint: "A `features` entry must carry a `sliders` array …",
+  path: "parameters[1].features[0]", pattern: "features-missing-sliders" }
+```
+
+`path` is a JS accessor path rooted at the PartDefinition — `parameters[1].features[0]`,
+`defaults.bore`, `parts.spacer.views[0]`, `parameters[0].presets["M3"].od`. Findings
+about the definition as a whole use `""`.
+
+**Severity.** A finding is an `error` when the part is *provably broken* — it cannot
+behave as authored — whether or not that shows up as a thrown exception. Some error
+findings do correspond to a runtime throw (`build-throws`, `verify-expect-throws`),
+but others catch **silent** wrongness: `missing-meta-title`, `part-view-unknown`,
+`control-key-not-in-defaults`, `preset-key-not-in-defaults`, and
+`verify-unknown-subpart` all fire on parts that build, measure, and verify cleanly —
+a dead control that's silently unreachable, a view that renders nothing, or a
+`verify` expectation that's silently dropped so its gate never runs. That's still an
+error: the part doesn't do what its author wrote, the failure is just quiet instead
+of loud. Everything speculative or stylistic — lossy but not broken — is a `warning`
+and never blocks anything. Because `measure` runs the error tier as a gate (see
+below), a part with one of these silent defects now exits non-zero where it
+previously didn't; that's the fix working as intended, not a regression.
+
+### Rule catalog
+
+**Definition shape** — `missing-meta-title`, `missing-defaults`, `no-buildable-parts`,
+`missing-views`, `part-view-unknown` (all errors); `view-unused` (warning).
+
+**Parameter schema** — `features-requires-sliders`, `control-key-not-in-defaults`,
+`preset-key-not-in-defaults` (errors); `slider-range-excludes-default`,
+`unknown-control-field`, `duplicate-control-key`, `default-not-exposed` (warnings).
+
+**Kernel API**, found by executing `build()` against a geometry-free probe —
+`unknown-kernel-op`, `unknown-solid-op`, `invalid-op-options`, `build-throws`,
+`derive-throws`, `manifold-backend-uses-occt-op`, `build-runaway` (errors);
+`nondeterministic-build` (warning, from diffing two probe runs).
+
+**Verify block** — `verify-unknown-metric`, `verify-unknown-subpart`,
+`verify-bad-expr`, `verify-bad-pair-check`, `verify-unknown-process`,
+`verify-expect-throws` (all errors). Note `_view` also accepts the pair-wise
+`contacts` / `clearance` keys, which are not scalar view metrics; they are
+validated by `verify-bad-pair-check`, matching `verify.js`'s own handling.
+
+A rule that itself throws yields an `internal-rule-error` **warning** and the run
+continues: `lintPart` never throws and never blocks a part because of a linter bug.
+
 ### The diagnostics contract (for agents)
 
 `partforge measure <part> --json` / `--out <file>` emits the machine-readable
@@ -817,13 +1001,20 @@ JSON to stdout and exits 1:
 ```
 
 `pattern`/`hint` appear when the message matches an ERROR-PATTERNS.md symptom
-string. Exit codes: 0 pass, 1 gate failure or crash — unchanged. Caveat: a throw
-*after* measure output has printed (e.g. an unknown metric in `verify.expect`, or
-a per-case build crash) appends this JSON after the human lines, so stdout is no
-longer pure JSON; prefer `--out` (or parse the trailing JSON object — the crash
-JSON is pretty-printed across multiple lines) for robust machine parsing. With
-`--out` the measure report is written to the file as soon as `measure` succeeds,
-so even if a later `verify` throw crashes the run the file is there — it just
+string. Exit codes: 0 pass, 1 gate failure or crash — unchanged. `measure`'s
+automatic lint pass (see "Linting" above) now catches most of the defects that
+used to surface this way statically, before the kernel boots, so they fail with
+pure JSON up front instead. The caveat narrows but doesn't disappear: lint
+resolves `verify.expect` once against the part's *defaults*, while `verify()`
+itself expands every `verify.cases` entry and re-resolves `expect(p, d)` per
+case — so an expectation that only names a bad metric/subpart for a non-default
+case (see `test/fixtures/unknown-metric-in-case-part.js`) still passes lint
+clean and then throws at runtime, after measure output has printed. That throw
+appends crash JSON after the human lines, so stdout is no longer pure JSON;
+prefer `--out` (or parse the trailing JSON object — the crash JSON is
+pretty-printed across multiple lines) for robust machine parsing. With `--out`
+the measure report is written to the file as soon as `measure` succeeds, so
+even if a later `verify` throw crashes the run the file is there — it just
 lacks the `verify` key.
 
 **Fresh-evidence rule.** A passing report is evidence only for the source, parameters,

package/docs/ERROR-PATTERNS.md

@@ -115,6 +115,12 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 - **Cause:** A `key` used in the `parameters` schema (slider, feature, or preset override) doesn't exist in `defaults` — every key must, including `hidden` ones.
 - **Fix:** Add the key to `defaults` with a sensible starting value. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Parameters: the control-panel schema".
 
+## features-missing-sliders
+
+- **Symptom:** `Cannot read properties of undefined (reading 'filter')` thrown from the control panel while the app boots, with no geometry ever rendering.
+- **Cause:** A `features` entry in the parameter schema has no `sliders` array — `controls.js` reads `feat.sliders.filter(...)` unguarded. A bare on/off control was put in `features` instead of `toggles`.
+- **Fix:** Move a bare boolean to the section's `toggles` array (`{ key, label, on }`), or give the `features` entry the `sliders` array it requires. `npx partforge lint <part>` catches this statically as `features-requires-sliders`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Parameters: the control-panel schema".
+
 ## dimmed-control-vestigial-param
 
 - **Symptom:** A control renders dimmed (but still editable) and changing it does nothing on screen.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.26.1",
+  "version": "0.28.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",
@@ -25,9 +25,11 @@
     ".": "./src/index.js",
     "./worker": "./src/framework/worker.js",
     "./geometry": "./src/framework/geometry/polygon.js",
+    "./lint": "./src/lint.js",
     "./derive": "./src/framework/derive.js",
     "./testing": "./src/testing.js",
-    "./tokens.css": "./src/framework/tokens.css"
+    "./tokens.css": "./src/framework/tokens.css",
+    "./chrome.css": "./src/framework/chrome.css"
   },
   "bin": {
     "partforge": "./bin/cli.js"
@@ -53,6 +55,8 @@
     "three": "^0.184.0"
   },
   "devDependencies": {
+    "@fontsource-variable/geist": "^5.3.0",
+    "@fontsource-variable/geist-mono": "^5.3.0",
     "happy-dom": "^20.10.6",
     "playwright": "^1.49.0",
     "vite": "^8.0.16",

package/skills/partforge/SKILL.md

@@ -60,4 +60,10 @@ Picks come back **in request order**, each echoing its prompt, so you can map th
 ## Related: debugging failures
 
 If anything fails while you're editing a part, grep `docs/ERROR-PATTERNS.md` for the
-symptom first — its preamble states the full grep-first rule.
+symptom first — its preamble states the full grep-first rule. Before assuming a user's
+click is needed at all, run the static linter — it's instant, needs no live app, and
+catches schema/build mistakes no pick session would explain:
+
+```bash
+partforge lint src/parts/<part>.js
+```

package/src/app-bracket.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import part from "./parts/bracket.js";
 import { mount } from "./framework/index.js";
 

package/src/app-demo.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import demoPart from "./parts/demo.js";
 import { mount } from "./framework/index.js";
 

package/src/app-faceted-vase.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import vasePart from "./parts/faceted-vase.js";
 import { mount } from "./framework/index.js";
 

package/src/app-filleted-box.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import part from "./parts/filleted-box.js";
 import { mount } from "./framework/index.js";
 

package/src/app-hull-sweep.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import part from "./parts/hull-sweep.js";
 import { mount } from "./framework/index.js";
 

package/src/app-nameplate.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import part from "./parts/nameplate.js";
 import { mount } from "./framework/index.js";
 

package/src/app-planter.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import planterPart from "./parts/planter.js";
 import { mount } from "./framework/index.js";
 

package/src/app-text-smoke.js

@@ -1,3 +1,8 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
 import part from "./parts/text-smoke.js";
 import { mount } from "./framework/index.js";