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

package/src/chrome/params-client.ts

@@ -0,0 +1,434 @@
+// The parameters drawer — built from the Figma components Parameters drawer (20074:3489), Drawer
+// group (20072:259700) and Param row (20072:259490) in the Astrolab file.
+//
+// Present only for a story that registers parameters through @orbytes/astrolab/params, which puts
+// them on the FRAME's window and announces each with a `lab:params` event there. The frame is
+// same-origin, so the drawer reads that array directly and calls each group's own set() across the
+// boundary — the values object is shared, never copied.
+//
+// It overlays the canvas's right edge and never resizes it: resizing would change the preview's
+// width and trip its breakpoints. Whether it is open, and which groups are collapsed, is
+// remembered in this browser. The navbar's Parameters button, the drawer's ✕ and Esc all close it.
+//
+// Every row is a <label> whose input is named by the label's text (aria-labelledby), so a row's
+// readout or unit never leaks into its accessible name. Typing into any of them is safe from the
+// lab's single-key shortcuts: every input and select here is one of the elements
+// window.__labIgnoreKey stands down for (../LabHead.astro).
+import type { IconName } from "./icons";
+import {
+  formatLabLength,
+  labUnitsOf,
+  parseLabLength,
+  type LabParamControl,
+  type LabParamEntry,
+} from "../shell/lab-params";
+
+const DRAWER_KEY = "lab-params-open";
+const COLLAPSE_KEY = "lab-params-collapsed";
+
+const readJson = <T,>(key: string, fallback: T): T => {
+  try {
+    return JSON.parse(localStorage.getItem(key) || "null") ?? fallback;
+  } catch {
+    return fallback;
+  }
+};
+const writeJson = (key: string, value: unknown) => {
+  try {
+    localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+    /* private mode — the drawer still works, it just forgets */
+  }
+};
+
+const el = <K extends keyof HTMLElementTagNameMap>(tag: K, className?: string, text?: string) => {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+};
+
+// The chrome's icons are <symbol>s in ./Sprite.astro, on every lab page; this points at one.
+const SVG_NS = "http://www.w3.org/2000/svg";
+const icon = (name: IconName, className = "") => {
+  const svg = document.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("class", `lab-icon lab-icon--sm ${className}`.trim());
+  svg.setAttribute("aria-hidden", "true");
+  const use = document.createElementNS(SVG_NS, "use");
+  use.setAttribute("href", `#lab-i-${name}`);
+  svg.append(use);
+  return svg;
+};
+
+const iconButton = (name: IconName, label: string, tooltip: string) => {
+  const button = el("button", "vpp__icon-btn");
+  button.type = "button";
+  button.title = tooltip;
+  button.setAttribute("aria-label", label);
+  button.append(icon(name));
+  return button;
+};
+
+let uid = 0;
+const nextId = (stem: string) => `lab-params-${stem}-${++uid}`;
+
+const decimalsOf = (step: number) => {
+  const text = String(step);
+  const dot = text.indexOf(".");
+  return dot === -1 ? 0 : text.length - dot - 1;
+};
+
+// <input type="color"> only takes #rrggbb; a declared #abc or #rrggbbaa would otherwise read as
+// black in the picker while the hex beside it says something else.
+const toPickerHex = (hex: string) =>
+  /^#[0-9a-f]{3,4}$/i.test(hex)
+    ? `#${[...hex.slice(1, 4)].map((c) => c + c).join("")}`
+    : hex.slice(0, 7);
+
+const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`;
+
+// ---- the footer ---------------------------------------------------------------------------------
+// One line for the drawer as a whole, aria-live: what the last action did (Reset, Copy settings).
+// Hidden until there is something to say. It is also where the drawer would report on saving;
+// that is not built here.
+const makeFooter = () => {
+  const footer = el("footer", "vpp__footer");
+  const line = el("p", "vpp__footer-line");
+  line.setAttribute("aria-live", "polite");
+  footer.append(line);
+  footer.hidden = true;
+  return {
+    node: footer,
+    say(text: string) {
+      line.textContent = text;
+      footer.hidden = !text;
+    },
+  };
+};
+type Footer = ReturnType<typeof makeFooter>;
+
+// ---- one row per control ------------------------------------------------------------------------
+// Each returns its node and a `sync` that pulls the input back from the live values — Reset
+// changes the values behind the inputs' backs.
+const buildRow = (entry: LabParamEntry, control: LabParamControl) => {
+  const row = el("label", `vpp__row vpp__row--${control.kind}`);
+  const labelId = nextId("label");
+  const name = el("span", "vpp__label");
+  const text = el("span", "vpp__label-text", control.label);
+  text.id = labelId;
+  name.append(text);
+  let noteId = "";
+  if (control.note) {
+    row.title = control.note;
+    name.append(icon("help", "vpp__help"));
+    const note = el("span", "lab-visually-hidden", control.note);
+    note.id = noteId = nextId("note");
+    name.append(note);
+  }
+  const slot = el("span", "vpp__control");
+  row.append(name, slot);
+  const named = <T extends HTMLElement>(input: T) => {
+    input.setAttribute("aria-labelledby", labelId);
+    if (noteId) input.setAttribute("aria-describedby", noteId);
+    return input;
+  };
+  const set = (value: string | number | boolean) => entry.set(control.id, value);
+
+  switch (control.kind) {
+    case "toggle": {
+      const input = named(el("input", "vpp__switch"));
+      input.type = "checkbox";
+      input.setAttribute("role", "switch");
+      input.addEventListener("change", () => set(input.checked));
+      slot.append(input);
+      const sync = () => (input.checked = entry.values[control.id] === true);
+      sync();
+      return { node: row, sync };
+    }
+    case "select": {
+      const select = named(el("select", "vpp__select"));
+      for (const option of control.options) {
+        const node = el("option", undefined, option.label);
+        node.value = option.value;
+        select.append(node);
+      }
+      select.addEventListener("change", () => set(select.value));
+      slot.append(select);
+      const sync = () => (select.value = String(entry.values[control.id]));
+      sync();
+      return { node: row, sync };
+    }
+    case "color": {
+      const field = el("span", "vpp__field vpp__field--color");
+      const input = named(el("input", "vpp__swatch"));
+      input.type = "color";
+      const out = el("output", "vpp__hex");
+      out.setAttribute("aria-hidden", "true"); // the picker already announces its own value
+      input.addEventListener("input", () => {
+        out.textContent = input.value;
+        set(input.value);
+      });
+      field.append(input, out);
+      slot.append(field);
+      const sync = () => {
+        const hex = String(entry.values[control.id]);
+        input.value = toPickerHex(hex);
+        out.textContent = hex;
+      };
+      sync();
+      return { node: row, sync };
+    }
+    case "number": {
+      // Decided 2026-09-24: a size is typed, not dragged, and says what unit it is in. The value
+      // handed to the component is the number and unit joined ("72px"); changing the unit keeps
+      // the number and changes what it means, because px → rem depends on a root size the lab
+      // cannot know.
+      const units = labUnitsOf(control);
+      const field = el("span", "vpp__field vpp__field--number");
+      const input = named(el("input", "vpp__number"));
+      input.type = "number";
+      input.inputMode = "decimal";
+      input.step = String(control.step ?? 1);
+      if (control.min !== undefined) input.min = String(control.min);
+      if (control.max !== undefined) input.max = String(control.max);
+      const unit = el("select", "vpp__unit");
+      unit.setAttribute("aria-label", `${control.label} unit`);
+      for (const value of units) {
+        const option = el("option", undefined, value || "—");
+        option.value = value;
+        if (!value) option.title = "No unit";
+        unit.append(option);
+      }
+      unit.disabled = units.length < 2;
+      field.append(input, unit);
+      slot.append(field);
+
+      const current = () =>
+        parseLabLength(entry.values[control.id]) ?? { value: control.value, unit: control.unit };
+      const commit = (value: number) => {
+        const bounded = Math.min(control.max ?? Infinity, Math.max(control.min ?? -Infinity, value));
+        set(formatLabLength(bounded, unit.value));
+      };
+      // Live while typing, so the section follows the field. A half-typed value ("-", "1e") has
+      // no number yet and changes nothing; leaving the field shows what is actually applied.
+      input.addEventListener("input", () => {
+        if (input.value !== "" && Number.isFinite(input.valueAsNumber)) commit(input.valueAsNumber);
+      });
+      unit.addEventListener("change", () => commit(current().value));
+      const sync = () => {
+        const { value, unit: which } = current();
+        input.value = String(value);
+        unit.value = which;
+      };
+      input.addEventListener("change", sync);
+      sync();
+      return { node: row, sync };
+    }
+    case "range": {
+      const step = control.step ?? 1;
+      const places = decimalsOf(step);
+      const input = named(el("input", "vpp__range"));
+      input.type = "range";
+      input.min = String(control.min);
+      input.max = String(control.max);
+      input.step = String(step);
+      const out = el("output", "vpp__readout");
+      out.setAttribute("aria-hidden", "true"); // the slider announces its own value
+      const paint = () => {
+        const value = Number(input.value);
+        out.textContent = `${value.toFixed(places)}${control.unit ?? ""}`;
+        const span = control.max - control.min;
+        const fill = span > 0 ? ((value - control.min) / span) * 100 : 0;
+        input.style.setProperty("--lab-params-fill", `${fill}%`);
+      };
+      input.addEventListener("input", () => {
+        paint();
+        set(Number(input.value));
+      });
+      slot.append(input, out);
+      const sync = () => {
+        input.value = String(entry.values[control.id]);
+        paint();
+      };
+      sync();
+      return { node: row, sync };
+    }
+  }
+};
+
+// ---- one <details> per registered group ---------------------------------------------------------
+// Nothing interactive sits inside <summary>: the source link, Reset and Copy live in the body and
+// are positioned up into the header row, so they show only while the group is open.
+const buildGroup = (entry: LabParamEntry, collapsed: Record<string, boolean>, footer: Footer) => {
+  const group = entry.group;
+  const details = el("details", "vpp__group");
+  details.open = collapsed[group.id] !== true;
+  if (group.source) details.dataset.source = "";
+
+  const summary = el("summary", "vpp__summary");
+  summary.append(
+    icon("chevron-down", "vpp__chev"),
+    el("span", "vpp__title", group.title),
+    el("span", "vpp__summary-count", plural(group.controls.length, "control")),
+  );
+  details.append(summary);
+
+  if (group.source) {
+    const link = el("a", "vpp__source", group.source.label);
+    link.href = group.source.href;
+    link.target = "_blank";
+    link.rel = "noreferrer";
+    const arrow = el("span", "vpp__source-arrow", " ↗");
+    arrow.setAttribute("aria-hidden", "true");
+    link.append(arrow);
+    details.append(link);
+  }
+
+  const reset = iconButton("reset", `Reset ${group.title} to its defaults`, "Reset to defaults");
+  const copy = iconButton("copy", `Copy ${group.title} settings`, "Copy settings");
+  const actions = el("div", "vpp__actions");
+  actions.append(reset, copy);
+  details.append(actions);
+
+  if (group.note) details.append(el("p", "vpp__note", group.note));
+
+  const list = el("div", "vpp__controls");
+  const syncers: (() => void)[] = [];
+  for (const control of group.controls) {
+    const built = buildRow(entry, control);
+    syncers.push(built.sync);
+    list.append(built.node);
+  }
+
+  // The component's own status line (panel.status()) — WebGL state, frame cost, an error. Hidden
+  // until the component says something.
+  const status = el("p", "vpp__status");
+  status.setAttribute("aria-live", "polite");
+  const showStatus = (text: string) => {
+    status.textContent = text;
+    status.hidden = !text;
+  };
+  showStatus(entry.lastStatus);
+  entry.onStatus = showStatus;
+  details.append(list, status);
+
+  reset.addEventListener("click", () => {
+    entry.resetAll();
+    for (const sync of syncers) sync();
+    footer.say(`${group.title} reset to its defaults`);
+  });
+  copy.addEventListener("click", async () => {
+    const json = entry.json();
+    try {
+      await navigator.clipboard.writeText(json);
+      footer.say(`${group.title} settings copied as JSON`);
+    } catch {
+      showStatus(json);
+      footer.say("The clipboard is blocked — the settings are shown in the group");
+    }
+  });
+
+  details.addEventListener("toggle", () => {
+    const map = readJson<Record<string, boolean>>(COLLAPSE_KEY, {});
+    if (details.open) delete map[group.id];
+    else map[group.id] = true;
+    writeJson(COLLAPSE_KEY, map);
+  });
+  return details;
+};
+
+const buildDrawer = (drawer: HTMLElement, groups: LabParamEntry[], close: () => void) => {
+  const header = el("header", "vpp__header");
+  const heading = el("div", "vpp__heading");
+  const title = el("h2", "vpp__heading-title", "Parameters");
+  title.id = nextId("title");
+  const total = groups.reduce((sum, entry) => sum + entry.group.controls.length, 0);
+  const count = el("span", "vpp__count", String(total));
+  count.append(el("span", "lab-visually-hidden", total === 1 ? " control" : " controls"));
+  heading.append(title, count);
+  const closeButton = iconButton("close", "Close parameters", "Close (Esc)");
+  closeButton.addEventListener("click", close);
+  header.append(heading, closeButton);
+
+  const footer = makeFooter();
+  const body = el("div", "vpp__scroll");
+  const collapsed = readJson<Record<string, boolean>>(COLLAPSE_KEY, {});
+  for (const entry of groups) body.append(buildGroup(entry, collapsed, footer));
+
+  drawer.setAttribute("aria-labelledby", title.id);
+  drawer.replaceChildren(header, body, footer.node);
+};
+
+export function mountParamsDrawer(drawer: HTMLElement | null, frame: HTMLIFrameElement) {
+  if (!drawer) return;
+  const button = document.querySelector<HTMLElement>("[data-lab-params-toggle]");
+  drawer.id ||= "lab-params";
+  button?.setAttribute("aria-controls", drawer.id);
+
+  let groups: LabParamEntry[] = [];
+  const wantsOpen = () => readJson(DRAWER_KEY, true) !== false;
+  const paint = () => {
+    const present = groups.length > 0;
+    const open = present && wantsOpen();
+    drawer.hidden = !open;
+    if (!button) return;
+    button.hidden = !present;
+    button.setAttribute("aria-pressed", String(open));
+  };
+  const setOpen = (open: boolean) => {
+    writeJson(DRAWER_KEY, open);
+    paint();
+  };
+  const close = () => {
+    const hadFocus = drawer.contains(document.activeElement);
+    setOpen(false);
+    if (hadFocus) button?.focus();
+  };
+  button?.addEventListener("click", () => setOpen(!wantsOpen()));
+
+  // Esc closes it — from inside the drawer always, from elsewhere only when nothing is being typed
+  // and no menu is open (an open popover takes the Esc itself).
+  document.addEventListener("keydown", (event) => {
+    if (event.key !== "Escape" || drawer.hidden || event.defaultPrevented) return;
+    const inside = drawer.contains(document.activeElement);
+    if (!inside && window.__labIgnoreKey?.(event)) return;
+    try {
+      if (document.querySelector(":popover-open")) return;
+    } catch {
+      /* no popover support — so no popover to defer to */
+    }
+    close();
+  });
+
+  const build = () => {
+    try {
+      groups = frame.contentWindow?.__labParams ?? [];
+    } catch {
+      groups = []; // a lab preview is always same-origin, but the drawer must never throw
+    }
+    if (groups.length) buildDrawer(drawer, groups, close);
+    else drawer.replaceChildren();
+    paint();
+  };
+  let queued = false;
+  const queueBuild = () => {
+    if (queued) return;
+    queued = true;
+    queueMicrotask(() => {
+      queued = false;
+      build();
+    });
+  };
+  const readParams = () => {
+    queueBuild();
+    try {
+      // Groups registered after load (an async setup) announce themselves; ones registered during
+      // module evaluation are already in the array queueBuild just read.
+      frame.contentWindow?.addEventListener("lab:params", queueBuild);
+    } catch {
+      /* cross-origin — the drawer stays as built */
+    }
+  };
+  frame.addEventListener("load", readParams);
+  if (frame.contentDocument?.readyState === "complete") readParams();
+}

package/src/chrome/pins-data.ts

@@ -1,26 +1,59 @@
-// Open pin-board tickets per source file, for the "N open pins" pill. Dev only: `labConfig.tasks`
-// is null in every build, and then this returns an empty map without touching the disk.
+// Pin-board tickets counted per source file and per page, for the Properties panel behind the
+// navbar's eye. Dev only: `labConfig.tasks` is null in every build, and then this returns empty
+// counts without touching the disk.
+//
+// The markers drawn on the framed preview do not come from here. They come from the dev toolbar's
+// pin app, which re-reads the board after every write (../pin/toolbar.js › `orbytes-pin:state`),
+// so a pin appears on the frame the moment it is created rather than on the next page load.
 import { labConfig } from "./model";
 
+/** Open and resolved tickets. Cancelled ones are an archive and are counted nowhere. */
+export interface PinTally {
+  open: number;
+  resolved: number;
+}
+
 export interface PinCounts {
   /** open tickets whose source file ends with the given site-relative path */
   openFor: (file: string | null | undefined) => number;
+  /** open and resolved tickets whose source file ends with the given site-relative path */
+  forFile: (file: string | null | undefined) => PinTally;
+  /** open and resolved tickets left on the given page address (`/`, `/about`) */
+  forUrl: (url: string | null | undefined) => PinTally;
   total: number;
   review: number;
 }
 
-const none: PinCounts = { openFor: () => 0, total: 0, review: 0 };
+const zero: PinTally = { open: 0, resolved: 0 };
+const none: PinCounts = { openFor: () => 0, forFile: () => zero, forUrl: () => zero, total: 0, review: 0 };
+
+/** `/a/` and `/a` are the same page; a query string is part of the address. */
+const samePath = (a: string, b: string) => {
+  const norm = (value: string) => {
+    const cut = value.indexOf("?");
+    const path = cut === -1 ? value : value.slice(0, cut);
+    return (path.length > 1 ? path.replace(/\/+$/, "") : path) + (cut === -1 ? "" : value.slice(cut));
+  };
+  return norm(a) === norm(b);
+};
 
 export const pinCounts = async (): Promise<PinCounts> => {
   if (!labConfig.tasks) return none;
   try {
-    const { collectTickets, OPEN_STATUSES, READY_FOR_REVIEW } = await import("../pin/board.mjs");
-    const { tickets } = collectTickets(labConfig.tasks.repoRoot, { backlogDir: labConfig.tasks.backlogDir });
-    const open = (tickets as { status: string; source?: string }[]).filter((t) => OPEN_STATUSES.includes(t.status));
+    const { collectTickets, OPEN_STATUSES, READY_FOR_REVIEW, RESOLVED } = await import("../pin/board.mjs");
+    const { tickets } = collectTickets(labConfig.tasks.repoRoot, { backlogDir: labConfig.tasks.backlogDir }) as {
+      tickets: { status: string; source?: string | null; url?: string | null }[];
+    };
+    const open = tickets.filter((t) => OPEN_STATUSES.includes(t.status));
+    const resolved = tickets.filter((t) => t.status === RESOLVED);
+    // A ticket's source is repo-relative and a lab path is site-relative; in a monorepo the site
+    // sits below the repo root, so the comparison is on the tail.
+    const bySource = (file: string) => (t: { source?: string | null }) => t.source === file || Boolean(t.source?.endsWith(`/${file}`));
+    const byUrl = (url: string) => (t: { url?: string | null }) => Boolean(t.url) && samePath(t.url!, url);
     return {
-      // A ticket's source is repo-relative and a lab path is site-relative; in a monorepo the site
-      // sits below the repo root, so the comparison is on the tail.
-      openFor: (file) => (file ? open.filter((t) => t.source === file || t.source?.endsWith(`/${file}`)).length : 0),
+      openFor: (file) => (file ? open.filter(bySource(file)).length : 0),
+      forFile: (file) => (file ? { open: open.filter(bySource(file)).length, resolved: resolved.filter(bySource(file)).length } : zero),
+      forUrl: (url) => (url ? { open: open.filter(byUrl(url)).length, resolved: resolved.filter(byUrl(url)).length } : zero),
       total: open.length,
       review: open.filter((t) => t.status === READY_FOR_REVIEW).length,
     };

package/src/chrome/shell-client.ts

@@ -4,14 +4,17 @@
 //   · the two collapses: level 1 ⇄ icon rail (⌘⇧B), level 2 open ⇄ closed (⌘B), both (⌘.), each
 //     remembered in localStorage and applied before paint by the inline script in Shell.astro
 //   · the peek: level 2 closed, pointer at the stage's left edge → the panel slides out OVER the
-//     stage for as long as the pointer stays on it. Over, not beside: pushing the stage would
-//     resize the preview frame and trip its breakpoints
+//     stage, below the navbar, for as long as the pointer stays on it. Over, not beside: pushing
+//     the stage would resize the preview frame and trip its breakpoints
 //   · level 1 groups (Site, Tasks) folding, remembered
-//   · the tree: closed groups remembered, scroll restored, the current row kept in view
+//   · the lab's own light/dark (the moon in level 1)
+//   · the tree: closed groups remembered, scroll restored, the current row kept in view, and the
+//     Sections tree's sort (slot or name), remembered
 //   · search (⌘K) and the filter menu, applied to the tree AND to any cards in the content that
 //     carry the same data-lab-search / data-lab-facets attributes
 //   · j / k: the navbar's own previous/next links when the page has them, the tree's rows when not
 //   · popover menus placed under the button that opened them
+//   · Astro's dev toolbar hidden in every frame, so the lab page's own is the only one
 //
 // Every shortcut asks window.__labIgnoreKey first (../LabHead.astro › THE KEYBOARD GUARD).
 
@@ -44,20 +47,34 @@ const write = (key: string, value: string | null, store: Storage = localStorage)
 const ignoreKey = (event: KeyboardEvent) => window.__labIgnoreKey?.(event) ?? false;
 
 // ---- the two collapses ---------------------------------------------------------------------------
+// The collapse button's name follows what it will do; the tooltip's title switches in CSS.
+const l1Button = document.querySelector<HTMLElement>(".lab-l1 [data-lab-l1-btn]");
+const nameL1Button = () => l1Button?.setAttribute("aria-label", l1Rail() ? "Expand menu" : "Collapse menu");
 const setL1 = (rail: boolean) => {
   if (rail) root.dataset.labL1 = "rail";
   else delete root.dataset.labL1;
   write("lab-l1", rail ? "rail" : "open");
+  nameL1Button();
+};
+// Level 2's own header button hides the panel when it is docked and keeps it open while it only
+// peeks, so its name says which (decided 2026-09-24: a label must match its action).
+const l2Button = panel?.querySelector<HTMLElement>("[data-lab-l2-btn]");
+const nameL2Button = () => {
+  const label = "labPeek" in root.dataset ? "Keep panel open" : "Hide panel";
+  l2Button?.setAttribute("aria-label", label);
+  l2Button?.setAttribute("title", `${label} · ⌘B`);
 };
 const setL2 = (closed: boolean) => {
   if (!panel) return;
   if (closed) root.dataset.labL2 = "closed";
   else delete root.dataset.labL2;
   delete root.dataset.labPeek;
+  nameL2Button();
   write("lab-l2", closed ? "closed" : null);
 };
 const l1Rail = () => root.dataset.labL1 === "rail";
 const l2Closed = () => root.dataset.labL2 === "closed";
+nameL1Button();
 const toggleL1 = () => setL1(!l1Rail());
 const toggleL2 = () => setL2(!l2Closed());
 // Focus mode: both away if either is showing, both back if both are away.
@@ -84,6 +101,15 @@ if (panel) {
 }
 
 // ---- the peek -----------------------------------------------------------------------------------
+// The peek and its trigger strip start where the navbar ends, so the panel covers the stage and
+// never the navbar (decided 2026-09-24). The navbar is one row or two depending on the width it
+// gets, so its height is measured, not assumed.
+const navbar = document.querySelector<HTMLElement>("[data-lab-navbar]");
+if (panel && navbar) {
+  const measure = () => root.style.setProperty("--lab-peek-top", `${navbar.offsetHeight}px`);
+  measure();
+  new ResizeObserver(measure).observe(navbar);
+}
 if (panel) {
   const zone = document.querySelector<HTMLElement>("[data-lab-peek-zone]");
   let openTimer = 0;
@@ -91,6 +117,7 @@ if (panel) {
   const peek = (on: boolean) => {
     if (on && l2Closed()) root.dataset.labPeek = "";
     else delete root.dataset.labPeek;
+    nameL2Button();
   };
   zone?.addEventListener("mouseenter", () => {
     clearTimeout(closeTimer);
@@ -135,10 +162,15 @@ for (const group of document.querySelectorAll<HTMLElement>("[data-lab-group]"))
 }
 
 // ---- theme --------------------------------------------------------------------------------------
+// The moon beside the logo: the LAB's light/dark, never the preview's. It is a toggle for dark, so
+// it reports its state as pressed rather than swapping its icon.
 for (const button of document.querySelectorAll<HTMLElement>("[data-lab-theme-toggle]")) {
+  const mark = () => button.setAttribute("aria-pressed", String(window.labTheme?.getTheme() === "dark"));
+  mark();
   button.addEventListener("click", () => {
     const next = window.labTheme?.getTheme() === "dark" ? "light" : "dark";
     window.labTheme?.setTheme(next);
+    mark();
   });
 }
 
@@ -181,6 +213,36 @@ if (body) {
   current?.scrollIntoView({ block: "nearest" });
 }
 
+// ---- the Sections tree's sort -------------------------------------------------------------------
+// Slot number or Name (A–Z), remembered per viewer. The inline script in Shell.astro already put
+// the stored choice on <html> and CSS `order` drew it; this moves the rows themselves to match, so
+// screen readers, Tab and j / k meet them in the order they are shown. Either way the unslotted
+// group stays under its heading, below the slotted one — the ranks from ./trees.ts guarantee it.
+const SORT_KEY = "lab-tree-sort";
+const stree = document.querySelector<HTMLElement>("[data-lab-stree]");
+if (stree) {
+  const sortItems = [...document.querySelectorAll<HTMLElement>("[data-lab-sort-by]")];
+  const rank = (el: HTMLElement, by: string) =>
+    Number(el.style.getPropertyValue(by === "name" ? "--lab-o-name" : "--lab-o-slot")) || 0;
+  const applySort = (by: string) => {
+    if (by === "name") root.dataset.labSort = "name";
+    else delete root.dataset.labSort;
+    const rows = [...stree.querySelectorAll<HTMLElement>(":scope > li")];
+    rows.sort((a, b) => rank(a, by) - rank(b, by));
+    stree.append(...rows);
+    for (const item of sortItems) item.setAttribute("aria-checked", String(item.dataset.labSortBy === by));
+  };
+  applySort(read(SORT_KEY) === "name" ? "name" : "slot");
+  for (const item of sortItems) {
+    item.addEventListener("click", () => {
+      const by = item.dataset.labSortBy === "name" ? "name" : "slot";
+      write(SORT_KEY, by === "name" ? "name" : null);
+      applySort(by);
+      item.closest<HTMLElement>("[popover]")?.hidePopover?.();
+    });
+  }
+}
+
 // ---- search and filter --------------------------------------------------------------------------
 const search = document.querySelector<HTMLInputElement>("[data-lab-tree-search]");
 const filterButton = document.querySelector<HTMLElement>("[data-lab-filter-btn]");
@@ -223,6 +285,10 @@ const applyFilter = () => {
   if (tree) {
     if (!searching) applyStoredOpen();
     for (const li of tree.querySelectorAll<HTMLElement>(":scope > .lab-tree__node")) filterNode(li, terms);
+    // The Sections tree's "Unslotted" heading goes when nothing under it is left to show.
+    for (const heading of tree.querySelectorAll<HTMLElement>(":scope > [data-lab-tree-heading]")) {
+      heading.hidden = !tree.querySelector(':scope > [data-lab-slot-group="unslotted"]:not([data-lab-hidden])');
+    }
     let empty = tree.parentElement?.querySelector<HTMLElement>("[data-lab-tree-none]");
     const anyShown = tree.querySelector(":scope > .lab-tree__node:not([data-lab-hidden])");
     if (!anyShown && tree.children.length) {
@@ -369,4 +435,34 @@ if (thumbs.length) {
   }
 }
 
+// ---- the dev toolbar inside frames --------------------------------------------------------------
+// The dev server puts Astro's toolbar in every page it serves, framed ones included, so without
+// this a lab page shows a second, scaled toolbar over whatever it frames. Decided 2026-09-24: the
+// lab page's own toolbar is the only one — its pin picker already descends into same-origin
+// frames. The bare story hides its own before first paint (../ui/components/preview-layout.astro);
+// this covers the frames the lab does not render itself — the site's pages in the Pages view and
+// its cards, and any page a framed link navigates to. `load` does not bubble, so it is caught on
+// the way down, once per navigation of every frame, present or added later; a frame that finished
+// loading before this module ran is swept once here.
+const hideFramedToolbar = (frame: HTMLIFrameElement) => {
+  try {
+    const doc = frame.contentDocument;
+    if (!doc?.head || doc.getElementById("lab-hide-dev-toolbar")) return;
+    const style = doc.createElement("style");
+    style.id = "lab-hide-dev-toolbar";
+    style.textContent = "astro-dev-toolbar { display: none !important; }";
+    doc.head.append(style);
+  } catch {
+    /* cross-origin — not a lab frame */
+  }
+};
+document.addEventListener(
+  "load",
+  (event) => {
+    if (event.target instanceof HTMLIFrameElement) hideFramedToolbar(event.target);
+  },
+  true,
+);
+for (const frame of document.querySelectorAll("iframe")) hideFramedToolbar(frame);
+
 export {};