@orbytes/astrolab 0.4.0-next.1 → 0.4.0-next.2

package/src/pin/toolbar.js

@@ -860,6 +860,10 @@ export default defineToolbarApp({
 		}
 
 		let mode = 'idle'; // idle | picking | selected
+		/** Whether Astro has this app toggled on — the lab's Comment button shows it as pressed. */
+		let appActive = false;
+		/** Set by the lab's Comment: the element whose box confines the pick (› the lab channel). */
+		let scope = null;
 		let hoverEl = null;
 		let selectedEl = null;
 		/**
@@ -1633,6 +1637,7 @@ export default defineToolbarApp({
 				syncMarkers();
 				// The count on the toolbar button is read from the same list, so it moves with it.
 				updateTicketsButton();
+				publish();
 			}
 		}
 
@@ -2280,6 +2285,7 @@ export default defineToolbarApp({
 
 			if (next === 'picking') {
 				if (!surface.isConnected) canvas.append(surface);
+				fitSurface();
 				hideChrome(hoverHighlight);
 				// The picker owns clicks while it is armed — a marker must not swallow one that
 				// was meant to pin the element underneath it.
@@ -2300,6 +2306,18 @@ export default defineToolbarApp({
 				clearCrumbs();
 				hideChrome(selectedHighlight);
 			}
+			publish();
+		}
+
+		/** The surface covers the page — or only the scope's box, when the lab's Comment set one. */
+		function fitSurface() {
+			const r = scope && scope.isConnected ? scope.getBoundingClientRect() : null;
+			Object.assign(
+				surface.style,
+				r
+					? { left: `${r.left}px`, top: `${r.top}px`, width: `${r.width}px`, height: `${r.height}px`, right: 'auto', bottom: 'auto' }
+					: { left: '0', top: '0', right: '0', bottom: '0', width: '', height: '' },
+			);
 		}
 
 		function hideChrome(el) {
@@ -2362,6 +2380,7 @@ export default defineToolbarApp({
 		}
 
 		function reposition() {
+			if (mode === 'picking') fitSurface();
 			if (mode === 'picking' && hoverEl) {
 				place(hoverHighlight, hoverEl, hoverFrames);
 				const { source } = resolveSource(hoverEl);
@@ -2424,6 +2443,10 @@ export default defineToolbarApp({
 		 * @returns {{ el: Element|null, frames: Element[], note: string|null }}
 		 */
 		function hitTest(x, y) {
+			if (scope) {
+				const r = scope.getBoundingClientRect();
+				if (x < r.left || x > r.right || y < r.top || y > r.bottom) return { el: null, frames: [], note: null };
+			}
 			let doc = document;
 			let px = x;
 			let py = y;
@@ -2439,7 +2462,8 @@ export default defineToolbarApp({
 				}
 
 				const frame = frameUnder(el, px, py);
-				if (!frame) return { el, frames: frames.slice(), note: null };
+				// A scoped pick (the lab's Comment) pins what is IN the frame, never the lab around it.
+				if (!frame) return scope && !frames.length ? { el: null, frames: [], note: null } : { el, frames: frames.slice(), note: null };
 
 				const inner = frameDocument(frame);
 				if (!inner) {
@@ -2881,6 +2905,19 @@ export default defineToolbarApp({
 		// box constantly — and a dictated paragraph cannot be retyped from memory. So Escape
 		// never discards text: with anything in the box it holds the selection, the words and
 		// the caret, and points at Cancel, which is the one control that discards on purpose.
+		//
+		// Inside the lab, Escape ends Comment mode rather than stopping at idle. Decided
+		// 2026-09-24: the lab's Comment is one mode — pick, write, send — so wherever Escape would
+		// leave this app on and idle ("Nothing selected", with Comment still pressed), it turns the
+		// app off instead, exactly as pressing Comment again does. Only a pick the lab started has a
+		// `scope`; the toolbar's own button keeps the steps above. The branch that holds a comment
+		// still runs first, and turning the app off never empties the box, so a word typed here
+		// survives every Escape.
+		function leaveOrIdle() {
+			if (scope) app.toggleState({ state: false });
+			else setMode('idle');
+		}
+
 		function onKeydown(event) {
 			// The climb. Capture phase and preventDefault, because ⌥↑ in a textarea is
 			// "move the caret to the start of the paragraph" on macOS and would otherwise
@@ -2904,7 +2941,8 @@ export default defineToolbarApp({
 				swallowEscapeKeyup = true;
 				// The badge and the hint line both change on setMode — saying it again in words
 				// was the log talking to itself.
-				setMode(selectedEl ? 'selected' : 'idle');
+				if (selectedEl) setMode('selected');
+				else leaveOrIdle();
 			} else if (mode === 'selected') {
 				event.preventDefault();
 				event.stopPropagation();
@@ -2915,7 +2953,7 @@ export default defineToolbarApp({
 					return;
 				}
 				clearSelection();
-				setMode('idle');
+				leaveOrIdle();
 			} else if (panelOpen) {
 				// Idle, with the panel open. Escape peels one layer at a time — the expanded entry,
 				// then the panel — and only once both are shut does it reach Astro's own
@@ -2936,6 +2974,13 @@ export default defineToolbarApp({
 				} else {
 					closePanel();
 				}
+			} else if (scope && appActive) {
+				// Idle in the lab, with nothing left to peel: close the app here rather than hope
+				// Astro's own Escape handler is armed, which it is only after a real hover.
+				event.preventDefault();
+				event.stopPropagation();
+				swallowEscapeKeyup = true;
+				leaveOrIdle();
 			}
 		}
 
@@ -2951,6 +2996,8 @@ export default defineToolbarApp({
 		/* ---------- lifecycle ---------- */
 
 		app.onToggled(({ state }) => {
+			appActive = Boolean(state);
+			if (!state) scope = null;
 			if (state) {
 				setMode(selectedEl ? 'selected' : 'picking');
 				// Astro hides an app's whole canvas when the app is toggled off, so the markers go
@@ -3129,6 +3176,37 @@ export default defineToolbarApp({
 			}
 		});
 
+		/* ---------- the lab's channel ---------- */
+
+		/**
+		 * The component lab drives this app from its own navbar — the Comment button, and the pins
+		 * it draws over its framed preview — and imports nothing from this file, so the door in and
+		 * the window out are plain window events:
+		 *
+		 *   in   `orbytes-pin:command`  { action: 'pick', within?: Element } | { action: 'stop' }
+		 *   out  `orbytes-pin:state`    { active, mode, tickets } after every mode change, toggle and
+		 *        board read; the same snapshot sits on `window.__orbytesPin` for a late listener.
+		 *
+		 * `within` confines the pick to that element's box, and to what lies inside a frame there,
+		 * so Comment pins the previewed page and never the lab's chrome around it. The toolbar's own
+		 * button still opens the app unscoped, exactly as before.
+		 */
+		function publish() {
+			const detail = { active: appActive, mode, tickets: panelTickets };
+			window.__orbytesPin = detail;
+			window.dispatchEvent(new CustomEvent('orbytes-pin:state', { detail }));
+		}
+		window.addEventListener('orbytes-pin:command', (event) => {
+			const { action, within } = (event && event.detail) || {};
+			if (action === 'pick') {
+				scope = within instanceof Element ? within : null;
+				if (appActive) setMode(selectedEl ? 'selected' : 'picking');
+				else app.toggleState({ state: true });
+			} else if (action === 'stop') {
+				app.toggleState({ state: false });
+			}
+		});
+
 		setMode('idle');
 		restoreAfterReload();
 		// Read the board once at start-up so the markers are on the page the moment the app is

package/src/shell/Browse.astro

@@ -5,7 +5,9 @@
 // sub-folder they sit in, and the panel's search and filter narrow both at once.
 //
 // REDESIGNED 2026-09-24 onto the chrome shell (../chrome/Shell.astro). Cards are per component
-// now, not per story — a component's stories are tabs on its own page.
+// now, not per story — a component's stories are its variants, chosen on its own page. The title
+// bar is the listing one (Figma `Lab / Listing`): title, counts, and filter chips that drive the
+// same filter as level 2's menu. On the sections tier, level 2 is the Sections tree.
 //
 // Pure chrome: this page renders no story. Its thumbnails are iframes of /lab/stories/<id>, which
 // are their own documents and get the consumer's CSS there (decided 2026-09-22 — ../ui/lab.css).
@@ -73,26 +75,49 @@ const filters: FilterOption[] = [
     : []),
 ];
 const live = mods.filter((m) => m.live).length;
+const used = mods.filter((m) => !m.live && m.usedBy.length).length;
+const unused = mods.length - live - used;
 const stories = mods.reduce((n, m) => n + m.stories.length, 0);
+const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+// What one of these is called: "sections" on the sections tier, "components" anywhere else.
+const noun = tier ? tierLabel(tier).toLowerCase() : "components";
+const counts = [
+  segments.length > 1 ? segments.slice(0, -1).map((s, i) => (i === 0 ? tierLabel(s) : s)).join(" / ") : null,
+  plural(mods.length, noun.replace(/s$/, ""), noun),
+  plural(stories, "variant"),
+  live > 0 ? `${live} live` : null,
+  used > 0 ? `${used} used` : null,
+  unused > 0 ? `${unused} unused` : null,
+].filter(Boolean);
+// The title bar's filter chips set the same filter as level 2's menu (./../chrome/shell-client.ts).
+const chips = [
+  { value: "", label: "All", n: mods.length },
+  { value: "live", label: "Live", n: live },
+  { value: "used", label: "Used", n: used },
+  { value: "unused", label: "Unused", n: unused },
+];
 ---
 
 <Shell
   title={title}
   active={tier ? `tier:${tier}` : "home"}
+  navbarClass="lab-navbar--listing"
   panel={folder ? { label: tierLabel(tier), crumbs, filters, filterLabel: "Show components", searchPlaceholder: `Search ${tierLabel(tier).toLowerCase()}` } : undefined}
 >
   {folder && <Tree slot="panel" nodes={tierTree(index, tier)} />}
 
   <Fragment slot="navbar">
-    <div class="lab-navbar__id">
-      <h1 class="lab-navbar__title">
-        {title}
-        {segments.length > 1 && <small>{segments.slice(0, -1).map((s, i) => (i === 0 ? tierLabel(s) : s)).join(" / ")}</small>}
-      </h1>
-      <div class="lab-navbar__meta">
-        <span class="lab-pill">{mods.length} component{mods.length === 1 ? "" : "s"}</span>
-        <span class="lab-pill">{stories} stor{stories === 1 ? "y" : "ies"}</span>
-        {live > 0 && <span class="lab-pill lab-pill--live">{live} live</span>}
+    <div class="lab-listing-bar">
+      <h1 class="lab-listing-bar__title">{title}</h1>
+      <p class="lab-listing-bar__counts">{counts.join(" · ")}</p>
+      <div class="lab-chips" role="radiogroup" aria-label="Show">
+        {
+          chips.map((chip) => (
+            <button class="lab-chip" type="button" role="radio" aria-checked={String(chip.value === "")} data-lab-filter={chip.value}>
+              {chip.label} {chip.n}
+            </button>
+          ))
+        }
       </div>
     </div>
   </Fragment>

package/src/shell/lab-index.ts

@@ -75,13 +75,14 @@ export interface LabItem {
   livePage: string | null;
   /** every page that mounts it — one entry on a normal site, more for shared chrome */
   liveOn: LiveMount[];
-  /** section versions only (tier "sections"); null everywhere the mark does not apply */
+  /** section versions only (the tier holding the responsive role); null everywhere else */
   responsive: { done: boolean; approved: boolean } | null;
   /** the same story on the deployed lab; null when no `stagingUrl` is configured */
   stagingUrl: string | null;
   /** vscode://file/<absolute path> to the component; null in a build — the link is dev-only */
   editorUrl: string | null;
-  /** repo-relative files of LIVE section components that import this item's componentFile */
+  /** repo-relative files that import this item's componentFile and are live themselves (a page
+   *  mounts them, whatever their tier or folder) */
   usedBy: string[];
   tags: string[];
   summary: string | null;
@@ -149,7 +150,7 @@ const summaryOf = (rootDir: string, moduleFile: string): string | null => {
 const classify = (directory: string) => {
   const parts = directory ? directory.split("/") : [];
   const tier = parts[0] ?? "";
-  const sectional = tier === "sections";
+  const sectional = labConfig.sectionsTier !== null && tier === labConfig.sectionsTier;
   return {
     tier,
     section: sectional && parts[1] ? parts[1] : null,
@@ -329,7 +330,7 @@ export const itemsUnder = (index: LabIndex, folderPath: string): LabItem[] =>
 /**
  * The live pill's text. A single-page site reads exactly as it always did — `live · slot 3 of 12`
  * — and only a page that is not the home page names itself: `live · /about, slot 3`.
- * The sidebar script in LabHead.astro carries the same three lines; keep the two in step.
+ * Every live pill in the chrome is built here; nothing else formats one.
  */
 export const livePillText = (item: LabItem): string | null => {
   if (!item.live) return null;

package/src/shell/lab-params.ts

@@ -10,9 +10,9 @@
    at all.
 
    So: a component that has something to tune DECLARES it here and renders nothing. The panel is
-   drawn by the viewport lab's chrome (./Viewport.astro), between the top bar and the
-   stage — and only there. The same story at <subpath>/stories/<id> (the bare render) and on the
-   dashboard shows no panel at all, because nothing in this module touches the DOM.
+   drawn by the lab's chrome (../chrome/params-client.ts) as a drawer on the right edge of the
+   component page's canvas — and only there. The same story at <subpath>/stories/<id> (the bare
+   render) shows no panel at all, because nothing in this module touches the DOM.
 
    HOW IT FITS TOGETHER. This module runs INSIDE the story document (the iframe). It keeps the
    registered groups on `window.__labParams` and announces each one with a `lab:params` event on
@@ -34,7 +34,7 @@
    with the restored values, so `apply` must tolerate being called before the thing it configures
    exists. Then:
 
-       import { registerLabParams } from "@orbytes/astrolab/params";
+       import { LAB_UNITS, parseLabLength, registerLabParams } from "@orbytes/astrolab/params";
 
        const shader = document.querySelector<HTMLCanvasElement>(".hero__shader");
        let uniforms: Uniforms | null = null;          // filled in below; apply() tolerates null
@@ -46,6 +46,7 @@
          note: "Uniforms are read every frame; nothing here is on the live page.",
          controls: [
            { kind: "range",  id: "speed", label: "Speed", min: 0, max: 4, step: 0.05, value: 1, unit: "×" },
+           { kind: "number", id: "warp",  label: "Warp",  value: 24, unit: "px", units: LAB_UNITS.size },
            { kind: "toggle", id: "grain", label: "Grain", value: true },
            { kind: "select", id: "blend", label: "Blend", value: "screen",
              options: [{ value: "screen", label: "screen" }, { value: "add", label: "add" }] },
@@ -54,6 +55,7 @@
          apply(values) {
            if (!uniforms) return;
            uniforms.speed = Number(values.speed);
+           uniforms.warp = parseLabLength(values.warp)?.value ?? 24;   // "24px" → 24
            uniforms.grain = Boolean(values.grain);
            uniforms.blend = String(values.blend);
            uniforms.tint = String(values.tint);
@@ -66,14 +68,55 @@
 
    That is all. Reset, Copy settings, the collapse chevron, the readouts, the units and the
    storage are the panel's job, not the component's.
+
+   ---------------------------------------------------------------------------------------------
+   SLIDER OR NUMBER? Decided 2026-09-24: a parameter that is a SIZE — a font size, a tracking, a
+   line height, a width, an offset, a blur radius — is never a slider. It is `kind: "number"`: a
+   field to type the value into, joined to a select of the units it can be expressed in (72 px,
+   4.5 rem, 12.5 vw). Unless it names its own `units`, it offers px · rem · em · vw · vh · %.
+   Sliders stay for unitless tuning values (speed, grain, scale, opacity).
+
+   A number control hands `apply` ONE CSS-READY STRING — the number and the unit joined, "72px",
+   "12.5rem", or "1.05" when the unit is "" — so it drops straight into a style:
+
+       el.style.setProperty("--headline-size", String(values.headlineSize));   // "72px"
+
+   and `parseLabLength` takes it apart again when the number itself is wanted (a shader uniform,
+   a calculation). 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.
+
+       { kind: "number", id: "headlineSize", label: "Headline size", value: 72, unit: "px",
+         units: LAB_UNITS.size },
+       { kind: "number", id: "tracking", label: "Tracking", value: -0.02, unit: "em",
+         units: LAB_UNITS.tracking, step: 0.01 },
+       { kind: "number", id: "lineHeight", label: "Line height", value: 1.05, unit: "",
+         units: LAB_UNITS.lineHeight, step: 0.01 },
    ============================================================================================= */
 
 export type LabParamValue = number | boolean | string;
 export type LabParamValues = Record<string, LabParamValue>;
 
+/**
+ * The unit sets a number control usually offers — pass one as `units`, or any list of your own.
+ * "" is "no unit" (the drawer shows it as "—"), which is what a line height is at its most
+ * useful. Figma writes tracking as a percentage; that is em × 100, so Figma's −2% is −0.02em.
+ */
+export const LAB_UNITS = {
+  /** Font sizes, widths, offsets, radii — and the set a number control gets when it names none. */
+  size: ["px", "rem", "em", "vw", "vh", "%"],
+  /** Letter spacing. */
+  tracking: ["em", "px"],
+  /** Line height: unitless first, because a unitless line height scales with the font. */
+  lineHeight: ["", "px"],
+} as const satisfies Record<string, readonly string[]>;
+
 /** One row of the panel. `id` is the key in `values`; `note` is shown on hover. */
 export type LabParamControl =
   | {
+      /**
+       * A slider, for a UNITLESS tuning value — speed, grain, scale. The value is a number and
+       * `unit` is only the readout's suffix ("×"). A size is a `number` control instead.
+       */
       kind: "range";
       id: string;
       label: string;
@@ -93,7 +136,59 @@ export type LabParamControl =
       options: { value: string; label: string }[];
       note?: string;
     }
-  | { kind: "color"; id: string; label: string; value: string; note?: string };
+  | { kind: "color"; id: string; label: string; value: string; note?: string }
+  | {
+      /**
+       * A SIZE — a number field joined to a unit select (72 px · 4.5 rem · 12.5 vw).
+       *
+       * The value in `values` is ONE CSS-ready STRING, the number and unit joined: "72px",
+       * "12.5rem", "-0.02em", or "1.05" when the unit is "". Put it straight into a style, or
+       * take it apart with `parseLabLength`. Changing the unit keeps the number; nothing is
+       * converted.
+       */
+      kind: "number";
+      id: string;
+      label: string;
+      /** The default number, bare: 72. */
+      value: number;
+      /** The default unit — "px", "em", or "" for none. Added to `units` if it is missing. */
+      unit: string;
+      /**
+       * What the unit select offers, in order. Defaults to `LAB_UNITS.size` (px · rem · em · vw ·
+       * vh · %); a tracking wants `LAB_UNITS.tracking`, a line height `LAB_UNITS.lineHeight`.
+       * A list of one shows the unit without a choice.
+       */
+      units?: readonly string[];
+      /** What ↑ / ↓ add. Defaults to 1. */
+      step?: number;
+      /** Optional bounds, applied to typed and stored values alike. */
+      min?: number;
+      max?: number;
+      note?: string;
+    };
+
+/** The units a number control offers: its declared `units`, with its default `unit` guaranteed. */
+export const labUnitsOf = (control: Extract<LabParamControl, { kind: "number" }>): string[] => {
+  const units = [...(control.units ?? LAB_UNITS.size)];
+  return units.includes(control.unit) ? units : [control.unit, ...units];
+};
+
+/**
+ * "72px" → { value: 72, unit: "px" }; "1.05" → { value: 1.05, unit: "" }. Null for anything that
+ * is not one number followed by an optional unit — so a value from a number control always
+ * parses, and a stray string never quietly becomes 0.
+ */
+export const parseLabLength = (raw: unknown): { value: number; unit: string } | null => {
+  if (typeof raw === "number") return Number.isFinite(raw) ? { value: raw, unit: "" } : null;
+  if (typeof raw !== "string") return null;
+  const match = /^\s*([-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?)\s*([a-z%]*)\s*$/i.exec(raw);
+  if (!match) return null;
+  const value = Number(match[1]);
+  return Number.isFinite(value) ? { value, unit: match[2]!.toLowerCase() } : null;
+};
+
+/** The inverse: 72 and "px" → "72px". `String()` already turns −0 into "0". */
+export const formatLabLength = (value: number, unit: string): string => `${String(value)}${unit}`;
 
 export interface LabParamGroup {
   /** Stable, and the localStorage key suffix. One group per thing being tuned. */
@@ -180,14 +275,26 @@ const coerce = (control: LabParamControl, raw: unknown): LabParamValue | undefin
       return typeof raw === "string" && control.options.some((o) => o.value === raw) ? raw : undefined;
     case "color":
       return typeof raw === "string" && /^#[0-9a-f]{3,8}$/i.test(raw) ? raw : undefined;
+    case "number": {
+      // A bare number is what a slider saved. Reading it in the default unit is what lets a size
+      // that used to be a `range` become a `number` without losing the tuning saved for it.
+      const parsed = typeof raw === "number" ? parseLabLength(`${raw}${control.unit}`) : parseLabLength(raw);
+      if (!parsed || !labUnitsOf(control).includes(parsed.unit)) return undefined;
+      const value = Math.min(control.max ?? Infinity, Math.max(control.min ?? -Infinity, parsed.value));
+      return formatLabLength(value, parsed.unit);
+    }
   }
 };
 
+/** A control's declared default, as `values` holds it. */
+const defaultOf = (control: LabParamControl): LabParamValue =>
+  control.kind === "number" ? formatLabLength(control.value, control.unit) : control.value;
+
 export function registerLabParams(group: LabParamGroup): LabParamHandle {
   const storageKey = group.storageKey ?? `${STORE_PREFIX}${group.id}`;
 
   const defaults: LabParamValues = {};
-  for (const control of group.controls) defaults[control.id] = control.value;
+  for (const control of group.controls) defaults[control.id] = defaultOf(control);
 
   const values: LabParamValues = { ...defaults };
   const stored = readStore(storageKey);