@orbytes/astrolab 0.3.0 → 0.4.0-next.2

package/README.md

@@ -1,21 +1,24 @@
 # @orbytes/astrolab
 
-Two dev surfaces for an Astro site, in one package and one integration call.
-
-**The component lab** at `/lab` — an [Astrobook](https://github.com/ocavue/astrobook) shell. Every
-section, component and experiment in a build, rendered live, with the one thing a component
-playground normally cannot tell you — **which of these is actually on the site right now**, derived
-from the pages rather than declared.
-
-**The pin board** at `/pin` — click a rendered element on `astro dev`, leave a comment, and a
-markdown ticket plus a screenshot land on local disk for an agent to pick up
-([docs/PIN.md](./docs/PIN.md), contract at [docs/PIN-CONTRACT.md](./docs/PIN-CONTRACT.md)). It moved
-in from its own package on 2026-09-22, so the two install, configure and version as one thing. Dev
-only, switchable off with `pin: false`.
-
-It ships mostly **source**. The `.astro` files, and everything under `src/shell/`, `src/ui/` and
-`src/types/`, are compiled by the consumer's own Vite, the way Starlight ships its components —
-which is why the lab picks up the consumer's tokens, fonts and breakpoints in a story preview: it
+A local dev tool for an Astro site, in one package and one integration call. Everything runs on
+the site's own dev server at `/lab`; nothing leaves the machine.
+
+**The lab** — every page, section and component in the build, rendered live on a canvas you size,
+with the one thing a component playground normally cannot tell you: **which of these is actually on
+the site right now**, derived from the pages rather than declared. Its engine began as
+[Astrobook](https://github.com/ocavue/astrobook), vendored; its chrome is this package's own.
+
+**Tasks — the pin board** at `/lab/tasks` — click a rendered element on `astro dev`, leave a
+comment, and a markdown ticket plus a screenshot land on local disk for an agent to pick up
+([docs/PIN.md](./docs/PIN.md), contract at [docs/PIN-CONTRACT.md](./docs/PIN-CONTRACT.md)). Kanban and
+table views in the lab, and a **Comment** button in its navbar that pins an element of the page it
+is previewing. Dev only, and only in a site that is inside a git repository (see
+[Tasks](#tasks--the-pin-board-at-labtasks)); switchable off with `pin: false`. `/pin`, its old
+address, redirects there.
+
+It ships mostly **source**. The `.astro` files, and everything under `src/chrome/`, `src/shell/`,
+`src/ui/` and `src/types/`, are compiled by the consumer's own Vite, the way Starlight ships its components —
+which is why the lab picks up the consumer's tokens, fonts and breakpoints in a variant's preview: it
 renders inside the consumer's pipeline. The one exception is `src/core/`, transpiled to `dist/` by
 `scripts/build-core.mjs` at `prepack` and `prepare`, because `astro.config.mjs` is loaded by Node's
 own ESM loader and Node refuses to strip TypeScript under `node_modules`. Without that step an
@@ -24,9 +27,12 @@ installed copy cannot be loaded at all. The script's header comment is the full
 ## Install
 
 ```sh
-npm i -D @orbytes/astrolab
+npm i -D -E @orbytes/astrolab
 ```
 
+`-E` (`--save-exact`) pins the version: a lab upgrade is a deliberate change to a site, never a
+side effect of `npm install`.
+
 Then add the integration:
 
 ```js
@@ -37,18 +43,26 @@ import orbytesLab from "@orbytes/astrolab";
 export default defineConfig({
   integrations: [
     orbytesLab({
-      css: ["./src/styles/global.css"], // your token and base stylesheets
+      css: ["./src/styles/global.css"], // optional: your site's own stylesheet(s), for the previews
     }),
   ],
 });
 ```
 
+`css` is optional, and `./src/styles/global.css` is only an example: name whatever stylesheet your
+site's layout imports. A new Astro project has no such file, so either point `css` at the one you
+have or leave the option out. Left out, it is `[]` and the variant previews get no site stylesheet
+at all, only each component's own scoped styles; the lab's chrome never gets it either way. Each
+entry becomes a plain `import` in the preview's layout (a path starting with `.` resolves against
+the project root, anything else as a package), so name only files that exist.
+
 That is the whole configuration. In particular, **do not add an `ssr.noExternal` entry for this
 package** — the integration adds its own, because the package ships `.astro` files that Vite would
 otherwise externalise and hand to Node, which cannot read them. A consumer needs nothing. (Two
 older orbytes repos set it by hand; it is redundant, and copying it from them is copying noise.)
 
-Now write a story. Stories live under `src/lab/`, in one directory per tier:
+Each named export in a stories file is a story; the lab lists them as **Variants**. Now write a
+story. Stories live under `src/lab/`, in one directory per tier:
 
 ```
 src/lab/
@@ -56,12 +70,11 @@ src/lab/
   components/Button.astro + Button.stories.ts
   explorations/KeycapButton.astro + KeycapButton.stories.ts
   decorators/            ← yours, built against YOUR page shell (see below)
-  cull.json              ← written by the lab, commit it
   responsive.json        ← written by the lab, commit it
 ```
 
 A stories file has a default export naming the component, and one named export per story. The
-export's name is what the sidebar shows; its `args` are the component's props.
+export's name is the variant's label in the lab; its `args` are the component's props.
 
 ```ts
 // src/lab/components/Button.stories.ts
@@ -76,8 +89,17 @@ export const Subtle = { args: { label: "See pricing", variant: "subtle" } };
 export const Strong = { args: { label: "Book a call", variant: "strong" } };
 ```
 
-Then `npm run dev` and open **`http://localhost:4321/lab`** — the home page lists every tier and
-renders every story live. `subpath` moves it; `directory` moves the stories.
+Then `npm run dev` and open **`http://localhost:4321/lab`**. `subpath` moves it; `directory` moves
+the stories.
+
+**Test versions** are published under the `next` tag while the redesign settles:
+`npm i -D -E @orbytes/astrolab@next`. `latest` stays on the last stable release until 1.0.
+
+**Upgrading from 0.3.** The mark-for-deletion feature (the cull) is removed, decided 2026-09-24.
+The `orbytes-lab-cull` command is gone, so delete any `lab:cull` script that calls it, and the
+`src/lab/cull.json` it kept. The `cullTier`, `cullDir` and `cullFile` options and a tier's
+`cullable` flag are no longer read: a config that still sets them builds, but they do nothing, and
+a typed config will flag them. Nothing else a 0.3 site configured changes meaning.
 
 **Peers.** Astro **7 or newer**, narrowed from `>=5.2.0` on 2026-09-22 when the pin board moved in:
 the board's dev-toolbar app imports `astro/client/dev-toolbar/apps/utils/highlight.js` and
@@ -167,10 +189,15 @@ than silent.
 
 ### What is vendored
 
-**Astrobook is not a dependency**, and neither is anything it used to pull in. All three of its
-packages are vendored at version `0.13.3` — the core into [`src/core/`](./src/core/), the UI into
-[`src/ui/`](./src/ui/), the types into [`src/types/`](./src/types/) — and `astro-theme-toggle` with
-them. Nothing outside Astro is installed, and there is nothing to keep in step but this folder.
+**Astrobook is not a dependency**, and neither is anything it used to pull in. Its core is vendored
+at version `0.13.3` into [`src/core/`](./src/core/), its types into [`src/types/`](./src/types/), and
+what the preview still needs of its UI into [`src/ui/`](./src/ui/) — the rest of that UI was retired
+by the redesign (2026-09-24), whose chrome is this package's own, in [`src/chrome/`](./src/chrome/).
+Nothing outside Astro is installed, and there is nothing to keep in step but this folder.
+
+The chrome bundles two third-party assets, each with its licence beside it: **Inter** (SIL OFL,
+[`src/chrome/fonts/`](./src/chrome/fonts/)) and **Lucide** icons (ISC,
+[`src/chrome/LICENSE-icons`](./src/chrome/LICENSE-icons)).
 
 Attribution, the upstream commit, and every deliberate divergence from it are recorded in
 [`src/core/LICENSE-astrobook`](./src/core/LICENSE-astrobook) (MIT, Copyright (c) 2024 ocavue; the
@@ -183,19 +210,19 @@ This package is MIT too; see [LICENSE](./LICENSE).
 ### The chrome is not styled by the website
 
 **Decided 2026-09-22.** The lab's own furniture looks the same in every site it is installed in,
-and only the rendered story takes the site's styling. A site that wants a different-looking lab
+and only the rendered variant takes the site's styling. A site that wants a different-looking lab
 edits this package's source: there is no theme API and no token override, on purpose.
 
-So the chrome — layout, sidebar, search, the home and folder pages, the viewport configurator — is
-drawn by one stylesheet that ships with this package, [`src/ui/lab.css`](./src/ui/lab.css), in
-`--lab-*` tokens that cannot collide with a site's own, on a system font stack, with light and dark
-themes of its own. It never receives the `css` list or the `head` component.
+So the chrome — both sidebar levels, the navbar, every view — is drawn by one stylesheet that ships
+with this package, [`src/ui/lab.css`](./src/ui/lab.css), in `--lab-*` tokens that cannot collide with
+a site's own, in Inter, with light and dark themes of its own. It never receives the `css` list or
+the `head` component.
 
-The **preview** — the story at `/lab/stories/<id>`, and the story rendered inside
-`/lab/dashboard/<id>` — still gets both, because seeing a component as the real site renders it is
-the whole point. Isolation runs both ways: the chrome's stylesheet is not loaded on a bare story
-page, and a component styled by lab CSS the real site has never heard of would be a lab that lies.
-The mechanism, and what it costs, is documented at the top of `lab.css`.
+The **preview** — the bare variant at `/lab/stories/<id>`, and the site's own pages — gets both,
+because seeing a component as the real site renders it is the whole point. Since the redesign the
+chrome only ever shows a preview **inside an `<iframe>`**, so the two never share a document: no
+chrome page carries a byte of the site's CSS, and the chrome's stylesheet never reaches a variant.
+The preview also keeps its **own** light/dark, separate from the chrome's.
 
 ## Options
 
@@ -205,13 +232,14 @@ Every option is optional.
 | --- | --- | --- |
 | `directory` | `"src/lab"` | Where the stories live, relative to the project root. |
 | `subpath` | `"/lab"` | Where the lab is served. `""` serves it at the site root. |
-| `css` | `[]` | The site's token and base stylesheets. Astrobook injects them into its own pages; the lab's own pages (folder pages, viewport) pull the same list. |
-| `head` | — | A path to the site's own head component, rendered **inside** the lab's head. This is how fonts arrive: lab stories never render through the site's layout, so whatever that layout registers has to be repeated here. |
-| `title` | `"Component lab"` | The lab's name, on the home page and in the dashboard. |
-| `stagingUrl` | — | The deployed lab's base URL — the real minified build, which a dev server is not. Every card and the story header link to the same story there. Omit it and those links do not appear. |
+| `css` | `[]` | The site's own token and base stylesheets, if you want the previews styled like the site (see [Install](#install)). They reach the variant **previews** only, never the lab's own chrome. |
+| `head` | — | A path to the site's own head component, rendered inside every variant preview's head. This is how fonts arrive: variants never render through the site's layout, so whatever that layout registers has to be repeated here. |
+| `title` | `"Component lab"` | The site's name as the lab shows it — the tab title and the home page. |
+| `stagingUrl` | — | The deployed lab's base URL — the real minified build, which a dev server is not. Every card and every component page link to the same variant there. Omit it and those links do not appear. |
 | `previewUrlTemplate` | — | A branch-preview URL with a `{branch}` placeholder, e.g. `"https://{branch}-my-site.workers.dev"`. The home page then lists the local git branches with a link each. Omit it and there is no branch list. It is a string, not a function, because the config crosses a virtual module and has to stay JSON-serialisable. |
 | `feedbucketKey` | — | Set it and every lab page carries the [Feedbucket](https://feedbucket.app) tag. The package takes a key or nothing: the consumer keeps its own staging gate, so pass the key only where the widget belongs. |
-| `tiers` | `["sections", "components", "explorations"]` | The tiers, in reading order. A tier is the first path segment under `directory`. |
+| `tiers` | `["sections", "components", "explorations"]` | The tiers, in reading order. A tier is the first path segment under `directory`. A tier with no stories files is left out of the menu. |
+| `viewports` | the orbytes scale | The viewport's screen sizes: `design` widths (the device switch), `breakpoints` (the band the Viewport field names, and the presets) and named `devices`. See [Viewports](#viewports). |
 | `pin` | `true` | The pin board. `false` omits it entirely; an object is the board's own options — see below. |
 
 ### Tiers
@@ -223,39 +251,120 @@ what each one *is*:
 tiers: [
   { id: "pages", label: "Page sections", responsive: true },
   "atoms",
-  { id: "sketches", label: "Sketches", cullable: true },
+  { id: "sketches", label: "Sketches" },
 ]
 ```
 
-- **`responsive`** — this tier holds page sections. Its stories carry the responsive mark, and they
-  render at page width (1440×900) in thumbnails and as the viewport's default frame; everything
-  else renders on a component stage (960×540). Defaults to true for a tier named `sections`.
-- **`cullable`** — this tier's stories may be marked for deletion in the sidebar and removed by
-  `orbytes-lab-cull`. Nothing else can be: version history and shared chrome are never deleted from
-  a browser. Defaults to true for a tier named `explorations`.
+- **`responsive`** — this tier holds page sections, laid out `<tier>/<Section>/<Version>/`; the lab
+  reads the section and version from those folders whatever the tier is called. Its variants carry
+  the responsive mark, and they render at page width (1440×900) in thumbnails and as the viewport's
+  default frame; everything else renders on a component stage (960×540). Defaults to true for a
+  tier named `sections`.
 
-At most one tier holds each role.
+At most one tier holds the role.
 
-## What you get
+### Viewports
 
-**`<subpath>/`** — the home page: a card per tier, then every story as a scaled-down live render.
+```js
+viewports: {
+  design: [
+    { label: "Desktop", width: 1440, icon: "monitor" },
+    { label: "Phone", width: 390, icon: "phone" },   // icons: monitor, tablet, phone-landscape, phone
+  ],
+  breakpoints: [{ name: "desktop", min: 1024 }, { name: "mobile", min: 0 }],
+  devices: [{ label: "Pixel 8", width: 412, height: 915 }],
+}
+```
 
-**`<subpath>/browse/<path>`** — a folder page per folder in the tree, with a filter box.
+Each key is optional and replaces its default whole. `breakpoints` are lower edges, widest first,
+the last one `0`; the presets offer both sides of every edge (1024 and 1023).
 
-**`<subpath>/viewport/<story>`** — the viewport configurator. Drag, type or pick the frame's width
-and height, zoom independently of it, and read the breakpoint band. The viewport is in the URL
-(`?w=390&h=844&z=0.6`), so a link — or a screenshot tool — names the exact frame. `[` `]` step the
-width presets, `r` rotates, `f` fits, `0` is 1:1.
+## What you get
+
+Two sidebar levels — the menu (Home; Site: Pages, one entry per tier, Assets; Tasks; Support and
+Settings), with the lab's own light/dark switch (a moon) beside the logo, and a panel with a
+breadcrumb, a search box and a tree — and a main area with a navbar over the content. The menu
+shrinks to a 64px icon rail, where the moon sits under the logomark and each group opens as a
+flyout under its own name. Kanban Board and All Tasks have no panel. The panel's tree has no icons
+and reads at 12px.
+
+**`<subpath>/`** — Home: counts for pages, each tier, assets and open tasks, and every page's
+mounted components in slot order — what is on the site right now.
+
+**`<subpath>/pages/<route>`** — the site's own pages, in a tree nested the way the routes nest, each
+shown on the viewport canvas at its real URL. The navbar is the component page's, less the
+variants: the page's name and route, the eye (below), a menu of the components the page mounts, in
+slot order, and **Reload** and **Open page** beside the viewport controls. `<subpath>/pages` lists
+them all.
+
+**`<subpath>/browse/<tier>`** — a tier (Sections, Components, …): its components as cards with a live
+thumbnail, under a title bar with filter chips (All · Live · Used · Unused). A live component's card
+carries a green badge with its slot number; the others carry a *used by N* pill when something live
+uses them, and a section carries its responsive state. On the sections tier the panel's filter
+menu adds responsive state.
+
+On the sections tier the panel is the **Sections tree**: one row per section with a slot badge —
+green with its slot number, a grey dash when no page mounts it, violet on the row you are on. The
+mounted sections come first; the rest sit under *Unslotted · on no page*. **Sort by** switches
+between slot number and name (A–Z) and is remembered in this browser.
+
+**`<subpath>/dashboard/<story>`** — a component's page. The tree stops at the component, and the
+navbar carries the rest:
+
+- **The name, the version and an eye.** Hovering the eye opens the **Properties** panel: where the
+  component is live and in which slot (or what uses it, or *Not on any page*), its open and resolved
+  pins, the two responsive marks as checkboxes (sections only, see [Marks](#marks)) and its source
+  file. Clicking the eye keeps the panel open; Escape or a click elsewhere closes it.
+- **Variants** — always a dropdown ("Default 1 of 3"), whatever the count — and previous / next
+  buttons, with `j`/`k` stepping through every variant of the tier.
+- **The device switch and the Viewport field.** The switch picks a design width. The field is the
+  frame's width × height, typed in place, and a button naming the band and the zoom ("tablet Fit")
+  that opens the presets: Rotate, both sides of every breakpoint edge, the named devices and a zoom
+  row (Fit, 25–200%). Drag the frame's right edge, bottom edge or corner to resize it. Fit is the
+  default: it scales the frame to fit the stage in both directions, and never past 100%.
+- **Comment**, where the pin board runs — see [Pinning from the lab](#pinning-from-the-lab).
+- **Parameters**, only for a variant that registers some — see [Parameters panel](#parameters-panel).
+- **⋯** — everything that leaves the lab (Open in VS Code, open the bare variant full screen, view
+  on staging, copy a link to this exact size), then two sets of switches: **Pins** (Show pins, on;
+  Show resolved, off) and **Preview › Dark mode**, which appears only when the framed site has a
+  dark mode of its own and switches the preview, not the lab.
+
+The navbar is one row when it is 1040px wide or more, and two rows below that, the viewport row
+last. The viewport is in the URL (`?w=390&h=844&z=fit`), so a link names the exact frame, and it
+rides along when you step between variants. `[` `]` step the widths, `r` rotates, `f` fits, `0` is
+100%.
+
+**`<subpath>/assets`** — every image under `src/` and `public/`, its size and dimensions, and which
+files reference it, so "what does nothing use?" is a filter.
+
+**`<subpath>/tasks`**, **`<subpath>/tasks/all`** — the pin board, dev only. See below.
 
 **`<subpath>/index.json`** — the whole index as a static file: every story with its id, URLs,
 files, tier/section/version, live slot, used-by list, tags and summary. Scripts and agent briefs
 read this instead of globbing.
 
-**The sidebar**, decorated: a **live** pill on every story a page actually mounts (`live · slot 3
-of 12`, or `live · /about, slot 3` when the page is not the home page), a **used by** pill on
-shared chrome, a **responsive** pill and two checkboxes on section versions, a cull switch in the
-header, and the search widened so `live`, `v1`, `responsive` or a tag all match. `⌘B` collapses the
-sidebar, `⌘K` focuses search, `j`/`k` walk the stories.
+**`<subpath>/viewport/<story>`** — the old viewport configurator's address, now a redirect to the
+component page, kept so old links still land.
+
+**Keys.** `⌘B` closes and opens the panel, `⌘⇧B` shrinks the menu to icons, `⌘.` does both,
+`⌘K` searches. With the panel closed, point at the canvas's left edge and the panel slides out
+under the navbar, over the canvas, without resizing the preview.
+
+**Astro's dev toolbar is hidden inside the lab's frames**, so a lab page shows one toolbar: its
+own. The site's pages, and a bare variant opened in its own tab, keep theirs.
+
+### Pinning from the lab
+
+Where the pin board runs, **Comment** pins an element of the framed preview: click it, click the
+element, and the pin app on Astro's dev toolbar opens its composer. The pick is confined to the
+canvas, so it can never land on the lab's own chrome; Escape stops it. The button stays disabled
+until that toolbar app has started, because it is the one picker and composer the lab uses.
+
+Pins already left on the framed page are drawn over the frame at their elements, blue while open and
+grey once resolved; a pin whose selector finds nothing on the page, or more than one thing, is not
+drawn. Clicking a pin, or the pin row in the Properties panel, opens All Tasks. ⋯ › Pins decides
+what is drawn — Show pins (on) and Show resolved (off) — and the choice is remembered in this
+browser. On the site's own pages, outside the lab, pinning goes through the dev toolbar as before.
 
 **An unconditional `noindex`** on every lab page. Lab pages do not render through the site's
 layout, so they never inherit its staging `noindex` — this one is not gated on the environment, on
@@ -265,47 +374,26 @@ purpose. Keep your own build gate as well: two mechanisms, because the rule is a
 
 A component is live when a page under `src/pages/` imports it **and** mounts it as a tag. Every
 page is walked, the layout is excluded, and the slot is the component's position in that page's
-document order. Nothing is configured, so the pill cannot go stale.
+document order. Nothing is configured, so the slot badge cannot go stale.
 
 ## Marks
 
-Two JSON files under `directory`, both written by a **dev-only** API (`PUT /__lab/cull`,
-`PUT /__lab/responsive`) and both meant to be committed:
-
-- **`responsive.json`** — `{ done, approved }` per section version. Responsive work is
-  approval-gated and neither fact is readable from the code, so both are ticked by hand in the
-  sidebar.
-- **`cull.json`** — `{ marked }`: stories in the cullable tier, marked for deletion.
-
-The API refuses anything outside the right tier, anything that is not a stories file on disk, and
-anything live or used by a live section — with the offender and the reason. In a build there is no
-dev server, so there is no write path at all and the switches hide themselves.
+One JSON file under `directory`, **`responsive.json`**, written by a **dev-only** API
+(`PUT /__lab/responsive`) and meant to be committed. It holds `{ done, approved }` per section
+version, ticked in the component's **Properties** panel (the eye beside its name). Responsive work
+is approval-gated and neither fact is readable from the code, so both are ticked by hand.
 
-### `orbytes-lab-cull`
-
-The marks delete nothing. This binary does, and only when told to:
-
-```sh
-orbytes-lab-cull            # dry run — print the plan, remove nothing
-orbytes-lab-cull --json     # the same plan as JSON
-orbytes-lab-cull --yes      # perform it: `git rm` (staged, not committed)
-orbytes-lab-cull --dir=…    # when the lab is not at src/lab
-```
-
-It runs in the current working directory, so wire it as a script in the consumer:
-
-```json
-"scripts": { "lab:cull": "orbytes-lab-cull" }
-```
-
-It removes each marked stories file, the component it renders, and anything under the lab
-directory that only the removal set imports — then refuses the whole run if any entry is blocked.
+The API refuses anything outside the responsive tier and anything that is not a stories file on
+disk — with the offender and the reason. In a build there is no dev server, so there is no write
+path at all: the boxes stay disabled and show the state the page was built with.
 
 ## Parameters panel
 
-A component with something to tune declares it and renders no UI of its own. The panel is drawn by
-the viewport configurator, under the top bar, and only there — the dashboard and the bare story
-page show nothing.
+A component with something to tune declares it and renders no UI of its own. The panel is a drawer
+over the right edge of the component page's canvas, opened from the navbar's **Parameters** button,
+which exists only for a variant that registered something — the bare variant page shows nothing.
+The drawer never resizes the canvas, because that would change the preview's width and trip its
+breakpoints; whether it is open, and which groups are collapsed, is remembered in this browser.
 
 ```ts
 import { registerLabParams } from "@orbytes/astrolab/params";
@@ -315,6 +403,7 @@ const panel = registerLabParams({
   title: "hero shader",
   controls: [
     { kind: "range", id: "speed", label: "Speed", min: 0, max: 4, step: 0.05, value: 1, unit: "×" },
+    { kind: "number", id: "headlineSize", label: "Headline size", value: 72, unit: "px" },
     { kind: "toggle", id: "grain", label: "Grain", value: true },
   ],
   apply(values) { /* push them into whatever they configure */ },
@@ -324,47 +413,102 @@ const values = panel.values;          // LIVE — mutated in place, safe to hold
 panel.status("WebGL2 · 0.8 ms/frame");
 ```
 
+The control kinds are `range` (a slider), `number` (below), `toggle`, `select` and `color`.
+
 `apply` is called once at registration with the restored values, so it must tolerate running before
 the thing it configures exists. Values persist per group in `localStorage`. Reset, Copy settings,
 the readouts and the collapse are the panel's job, not the component's.
 
-Exported types: `LabParamControl`, `LabParamGroup`, `LabParamHandle`, `LabParamValue`,
-`LabParamValues`, `LabParamEntry`.
+### Sizes are never sliders
 
-## The pin board at `/pin`
+**Decided 2026-09-24.** A parameter that is a size — a font size, a tracking, a line height, a width,
+an offset, a radius — is `kind: "number"`: a field to type the value into, joined to a select of the
+units it can be expressed in. Sliders stay for unitless tuning values (speed, grain, scale,
+opacity).
 
-Dev only, on by default, and it needs no configuration: `orbytesLab()` already gives it the lab's
-resolved `subpath` so the board's own "Lab" link points wherever the lab actually is. Everything it
-does is in [docs/PIN.md](./docs/PIN.md); what matters at the integration boundary is here.
+```ts
+{ kind: "number", id, label, value, unit, units?, step?, min?, max?, note? }
+```
+
+- `value` is the bare default number (`72`) and `unit` its default unit (`"px"`, or `""` for none).
+- `units` is what the select offers. It defaults to `LAB_UNITS.size` — px · rem · em · vw · vh · %.
+  `LAB_UNITS.tracking` (em · px) and `LAB_UNITS.lineHeight` (none · px) are there too, or pass a
+  list of your own; the default `unit` is added if the list lacks it.
+- `step` is what ↑ / ↓ add (1 by default); `min` and `max` bound typed and restored values alike.
+
+`apply` receives **one CSS-ready string** per number control, the number and the unit joined —
+`"72px"`, `"12.5rem"`, or `"1.05"` when the unit is `""` — so it drops straight into a style:
+
+```ts
+el.style.setProperty("--headline-size", String(values.headlineSize)); // "72px"
+```
+
+`parseLabLength("72px")` gives `{ value: 72, unit: "px" }` back when the number itself is wanted,
+and `null` for anything that is not one number and an optional unit. Changing the unit keeps the
+number and changes what it means: the panel never converts between units, because px → rem
+depends on a root size it cannot know. A size that used to be a `range` can become a `number`
+without losing its saved tuning — a stored bare number is read in the default unit.
+
+Exported from `@orbytes/astrolab/params`: `registerLabParams`, `LAB_UNITS`, `parseLabLength`,
+`formatLabLength` (its inverse), `labUnitsOf`, and the types `LabParamControl`, `LabParamGroup`,
+`LabParamHandle`, `LabParamValue`, `LabParamValues`, `LabParamEntry`.
+
+## Tasks — the pin board at `/lab/tasks`
+
+Dev only and on by default. Inside the lab it is two views in the lab's own chrome — **Kanban
+Board** at `<subpath>/tasks` and **All Tasks**, a sortable table, at `<subpath>/tasks/all` — with no
+panel beside them: the board's own chips filter by status. `/pin`, its old address, redirects there.
+Pinning from inside the lab is the navbar's Comment button ([Pinning from the
+lab](#pinning-from-the-lab)). Everything the board does is in [docs/PIN.md](./docs/PIN.md); what
+matters at the integration boundary is here.
+
+**It needs the site to be inside a git repository.** Every ticket path is stored relative to the
+repository root: the Astro project's folder, or the nearest one above it, that holds `.git`.
+With none, the board switches itself off for that run and says so only as a warning in the dev
+server's log; the lab is unaffected. Nothing on screen says why: `<subpath>/tasks`,
+`<subpath>/tasks/all` and `/pin` answer 404, the Tasks group and the Comment button are absent,
+there is no pin app on the dev toolbar and no source stamp. Run `git init` (then restart the dev
+server) to turn it on, or pass `pin: false` to silence the warning.
 
 ```js
 orbytesLab({
   css: ["./src/styles/global.css"],
   pin: {
-    stamp: ["src/lab/sections", "src/components"],  // site-relative
+    // site-relative; this adds the lab's components tier to the default
+    stamp: ["src/lab/sections", "src/lab/components", "src/components"],
     project: "acme-website",                        // the screenshot archive folder
   },
 })
 ```
 
+**Which files a pin can name.** A pin names the source file of the nearest element that carries a
+`data-orbytes-src` attribute, and `stamp` decides which `.astro` files get one. The default is
+`src/lab/sections` and `src/components` — **not** `src/lab/components` or `src/lab/explorations`,
+where the layout above puts components — so a pin on one of those, in its own variant, records
+its source as `unresolved` (its selector, screenshot and HTML are still in the ticket). Rendered
+inside a stamped section, the same component's pin names the section's file. Add the directories you
+want, as in the example: `stamp` replaces the default rather than adding to it, and it does not
+follow `directory` if you moved the stories. Before widening it, read the last bullet below: a
+template in a stamped folder with no element to stamp (its first top-level tag a component, say)
+throws, and needs a `stampSkip` entry.
+
 | Option | Default | What it does |
 | --- | --- | --- |
-| `stamp` | `["src/lab/sections", "src/components"]` | **Site-relative** directories whose `.astro` files get `data-orbytes-src`, so a pin can name the file it came from. |
+| `stamp` | `["src/lab/sections", "src/components"]` | **Site-relative** directories whose `.astro` files get `data-orbytes-src`, so a pin can name the file it came from. Replaces the default whole; see above for `src/lab/components`. |
 | `stampSkip` | `[]` | **Site-relative** `.astro` paths exempt from the stamp's hard failure. A repo-relative path is accepted too, for configs written before 2026-09-22. |
 | `backlogDir` | `"backlog"` | Repo-relative board directory: tickets in `tasks/`, PNGs in `assets/`. |
 | `archiveDir` | `~/.orbytes/feedback-archive` | Canonical screenshot home; the repo copy is a hardlink into it. |
 | `project` | the checkout's folder name | The folder under `archiveDir` this project's screenshots live in. |
 | `shots` | `true` | `false` writes tickets and never loads playwright. |
-| `route` | `"/pin"` | Where the board is served. |
-| `links` | the lab's resolved subpath | The board's corner links. `[]` draws none. |
+| `route` | `"<subpath>/tasks"` | Where the board is served. On its own, without the lab, `"/pin"`. |
+| `links` | the lab's resolved subpath | The standalone board's corner links. `[]` draws none. |
 | `appId` / `appName` / `icon` | `"orbytes-pin"` / `"Pin"` / `"bug"` | The dev-toolbar app's identity. |
 
 Three things about it are worth knowing before they surprise you:
 
-- **`route` shadows a host page at the same path.** The board is middleware installed ahead of
-  Astro's own request handler, so a site with its own `src/pages/pin.astro` serves the board
-  instead — in dev, with nothing on screen to say why. The default stays `/pin` because it is the
-  address every document here names; a site that owns that path sets `pin: { route: "/__pin" }`.
+- **`/pin` still answers, in dev, with a redirect.** It is middleware installed ahead of Astro's own
+  request handler, so a site with its own `src/pages/pin.astro` gets the redirect instead of its
+  page — in dev only. Build output is unaffected.
 - **`project` defaults to the checkout's directory name**, which two clones of *different* repos
   under the same folder name silently share. One's `pin-007.png` overwrites the other's and both
   boards keep rendering. Set it explicitly where that is possible.
@@ -375,8 +519,8 @@ Three things about it are worth knowing before they surprise you:
 
 ### `orbytes-pin-gallery`
 
-The board is live at `/pin` and read fresh on every request, so this binary is only for the file: a
-snapshot that opens with no dev server running.
+The board is live at `/lab/tasks` and read fresh on every request, so this binary is only for the
+file: a snapshot that opens with no dev server running.
 
 ```sh
 orbytes-pin-gallery                        # → backlog/gallery.html
@@ -385,8 +529,8 @@ orbytes-pin-gallery --backlog-dir feedback # when the site moved its board
 ```
 
 It renders from the same module the live board does and is read-only — a `file://` page has nothing
-listening behind it. It runs in the current working directory, like `orbytes-lab-cull`, so wire it
-as a script in the consumer:
+listening behind it. It runs in the current working directory, so wire it as a script in the
+consumer:
 
 ```json
 "scripts": { "pin:gallery": "orbytes-pin-gallery" }
@@ -397,7 +541,7 @@ as a script in the consumer:
 - **`decorators/`** — a decorator wraps a story in the page shell it will really live in. That
   shell is different in every build, so the package ships none: write your own against your own
   layout.
-- **`cull.json` / `responsive.json`** — data about your components, committed with them.
+- **`responsive.json`** — data about your components, committed with them.
 - **The build gate** — whether the lab is in this build is the consumer's decision, in the
   consumer's `astro.config.mjs`, and worth asserting with a check of your own.
 - **The head component** — fonts and anything else the site's layout registers.
@@ -405,6 +549,7 @@ as a script in the consumer:
 ## Notes
 
 - The `tags` a story declares (`export default { component, meta: { tags: [...] } }`) are read
-  through `import.meta.glob("/src/**/*.stories.ts")`, so a `directory` outside `src/` gets no tags.
+  from the stories file's text, not imported, so write them as string literals: a tag built at
+  runtime is not seen.
 - Editing the integration or its `.mjs` helpers is not picked up by the dev server's config-change
   restart — they stay in Node's ESM cache. Stop and start the server.