@orbytes/astrolab 0.3.0

package/LICENSE

@@ -0,0 +1,37 @@
+MIT License
+
+Copyright (c) 2026 William Teig (orbytes.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+PARTS OF THIS PACKAGE ARE VENDORED FROM ASTROBOOK, ALSO UNDER MIT.
+
+`src/core/`, `src/ui/` and `src/types/` are vendored from Astrobook
+(https://github.com/ocavue/astrobook), version 0.13.3, commit
+a79f03cdfd32eb08330b33fa7d5830ac506f9272 — Copyright (c) 2024, 2025 ocavue.
+
+Their upstream copyright and permission notices are reproduced in full in
+`src/core/LICENSE-astrobook`, which also records exactly which files diverge
+from upstream and how. That file ships inside the published package, which is
+what MIT redistribution requires; do not remove it from the `files` list in
+package.json, and do not move it without checking that it still ships.
+
+Everything outside those three directories is original to this package.

package/README.md

@@ -0,0 +1,410 @@
+# @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
+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
+installed copy cannot be loaded at all. The script's header comment is the full account.
+
+## Install
+
+```sh
+npm i -D @orbytes/astrolab
+```
+
+Then add the integration:
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import orbytesLab from "@orbytes/astrolab";
+
+export default defineConfig({
+  integrations: [
+    orbytesLab({
+      css: ["./src/styles/global.css"], // your token and base stylesheets
+    }),
+  ],
+});
+```
+
+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:
+
+```
+src/lab/
+  sections/Section01Hero/V1/Section01Hero.astro + Section01Hero.stories.ts
+  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.
+
+```ts
+// src/lab/components/Button.stories.ts
+import Button from "./Button.astro";
+
+export default {
+  component: Button,
+  meta: { tags: ["cta", "v2"] }, // optional — the sidebar search matches tags
+};
+
+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.
+
+**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
+`.../window.js`, which are Astro 7 internals and part of no published API, so the old range was a
+promise this package cannot keep. `playwright` is a second peer and an **optional** one — it is
+loaded by dynamic import, only when a screenshot is actually taken, so a site without it runs the
+lab and writes pin tickets without pictures rather than failing to load its config. Add it with
+`npm i -D playwright && npx playwright install chromium` if you want the screenshots.
+
+### Keeping the lab out of production
+
+The integration does not decide this; you do. Wrap it in whatever condition your deployment gives
+you, and the lab is simply absent from any build where the condition is false:
+
+```js
+// The lab is a staging surface. Ship it to dev and staging, never to production.
+const includeLab = process.argv.includes("dev") || process.env.MY_DEPLOY_ENV === "staging";
+
+export default defineConfig({
+  integrations: [includeLab ? orbytesLab({ css: ["./src/styles/global.css"] }) : null],
+});
+```
+
+The environment variable is **yours**. orbytes' own sites use `PUBLIC_DEPLOY_ENV=staging`; that is
+a deployment convention and no part of this package, which never reads any environment variable to
+decide whether it loads. Every lab page also carries an unconditional `noindex`, so the two
+mechanisms are independent — see *What you get*.
+
+### One integration, not three
+
+`orbytesLab()` returns the vendored Astrobook integration, the lab shell *and* the pin board as an
+array; Astro flattens integration arrays, so that single entry configures all of them. Do not
+install and add the `astrobook` package yourself — a second copy would fight this one over the same
+routes and the same `virtual:astrobook/*` module ids.
+
+The lab alone, for a site that does not want the board:
+
+```js
+orbytesLab({ css: ["./src/styles/global.css"], pin: false })
+```
+
+### Editing this package from a git worktree
+
+Only relevant if you are developing **the lab itself** from a git worktree of a consuming repo. A
+worktree has no `node_modules` of its own, so node walks up and resolves a bare `@orbytes/astrolab`
+to the *main* clone's copy — you edit the package and the running site shows no change at all. The
+whole shell follows that first resolution, because the integration anchors its route entrypoints
+with `new URL(…, import.meta.url)`.
+
+The fix has two halves. Import the package by **relative path** rather than by the bare specifier,
+and add a `vite.resolve.alias` entry per **subpath** (`@orbytes/astrolab/head`, `/home`, `/params`
+and friends), because those are resolved by Vite rather than by that import.
+`testbeds/orbytes-v2/astro.config.mjs` builds the alias map from this package's own `name` and
+`exports` so neither half can drift from it — copy that file.
+
+**An installed copy needs none of this.** Measured 2026-09-22 against a packed tarball in a clean
+Astro project: the bare specifier resolved, and `/head`, `/home` and `/params` resolved through
+`node_modules` with no alias map at all.
+
+### Installing from a folder copy — the legacy path
+
+Before this package was published, a site got it by **copying the folder in** and linking it as a
+workspace. That path still works and at least one orbytes site is still on it, so it is documented
+rather than removed; a new install should use npm.
+
+```sh
+rsync -a --delete --exclude='.git' --exclude='.DS_Store' --exclude='ops/' --exclude='node_modules' \
+  --exclude='testbeds/' --exclude='.claude/' --exclude='package-lock.json' \
+  <this repo>/ <site>/packages/astro-lab/
+```
+
+The excludes matter: `testbeds/` is this package's own consuming site, not part of what a site
+installs, and a plain `cp -R` would carry it in along with this repo's `workspaces` and `scripts`
+keys. Then, in the site's `package.json`:
+
+```json
+{
+  "workspaces": ["packages/*"],
+  "devDependencies": { "@orbytes/astrolab": "*" }
+}
+```
+
+`npm install` links it from the site's own repo, so a CI build needs no token and no registry. On
+this path **this repo is canonical**: fix it here first, bump the `version`, then refresh each
+site's copy — that version is the stamp saying which copy a site is on, so drift is visible rather
+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.
+
+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
+theme toggle's own notice is at the end of the same file). Read it before touching anything under
+`src/core/`, `src/ui/` or `src/types/` — each mirrors its upstream layout on purpose, so a future
+version can still be diffed in.
+
+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
+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.
+
+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`.
+
+## Options
+
+Every option is optional.
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `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. |
+| `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`. |
+| `pin` | `true` | The pin board. `false` omits it entirely; an object is the board's own options — see below. |
+
+### Tiers
+
+Tier names are a convention, not a law. Pass strings to rename or reorder them, or objects to say
+what each one *is*:
+
+```js
+tiers: [
+  { id: "pages", label: "Page sections", responsive: true },
+  "atoms",
+  { id: "sketches", label: "Sketches", cullable: true },
+]
+```
+
+- **`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`.
+
+At most one tier holds each role.
+
+## What you get
+
+**`<subpath>/`** — the home page: a card per tier, then every story as a scaled-down live render.
+
+**`<subpath>/browse/<path>`** — a folder page per folder in the tree, with a filter box.
+
+**`<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.
+
+**`<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.
+
+**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
+purpose. Keep your own build gate as well: two mechanisms, because the rule is absolute.
+
+### "Live" is derived, never declared
+
+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.
+
+## 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.
+
+### `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.
+
+## 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.
+
+```ts
+import { registerLabParams } from "@orbytes/astrolab/params";
+
+const panel = registerLabParams({
+  id: "hero-shader",                 // stable — it is the storage key
+  title: "hero shader",
+  controls: [
+    { kind: "range", id: "speed", label: "Speed", min: 0, max: 4, step: 0.05, value: 1, unit: "×" },
+    { kind: "toggle", id: "grain", label: "Grain", value: true },
+  ],
+  apply(values) { /* push them into whatever they configure */ },
+});
+
+const values = panel.values;          // LIVE — mutated in place, safe to hold in a render loop
+panel.status("WebGL2 · 0.8 ms/frame");
+```
+
+`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`.
+
+## The pin board at `/pin`
+
+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.
+
+```js
+orbytesLab({
+  css: ["./src/styles/global.css"],
+  pin: {
+    stamp: ["src/lab/sections", "src/components"],  // site-relative
+    project: "acme-website",                        // the screenshot archive folder
+  },
+})
+```
+
+| 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. |
+| `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. |
+| `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" }`.
+- **`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.
+- **`stamp` throws on a matched `.astro` file with no element to stamp** — a template whose first
+  top-level tag is a component, say. That is deliberate (a warned-past file produces tickets with no
+  source), and `stampSkip` is the way past it. Point `stamp` at directories you know, not at
+  `src/`.
+
+### `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.
+
+```sh
+orbytes-pin-gallery                        # → backlog/gallery.html
+orbytes-pin-gallery --out somewhere.html
+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:
+
+```json
+"scripts": { "pin:gallery": "orbytes-pin-gallery" }
+```
+
+## What stays yours
+
+- **`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.
+- **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.
+
+## 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.
+- 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.