@jxsuite/studio 6.1.2 → 8.0.0

package/src/panels/style-panel.ts

@@ -91,6 +91,7 @@ import { showPromptDialog } from "../ui/layers";
 import { parseMediaEntries, schemeOfQuery } from "../utils/canvas-media";
 import { getEffectiveMedia, getEffectiveStyle } from "../site-context";
 import { computeInheritedSources } from "../utils/inherited-style";
+import { tagAncestorSources } from "../style/tag-inheritance";
 import { loadUsages, peekUsages, usageFiles } from "../services/references";
 import { mediaDisplayName } from "./shared";
 import {
@@ -125,6 +126,7 @@ import type { CssFontPreset, CssLonghand, CssMetaEntry } from "./style-utils";
 import { UNIT_RE } from "../ui/unit-selector";
 import { colorTokens, resolvedColor } from "../ui/color-selector";
 import { resolveTokenValue, toTokenRef, tokenRefName } from "../style/token-ref";
+import { PROJECT_VARIABLES_VIEW } from "../style/project-styles";
 import { mountStylePanelSurface } from "../surfaces/style-panel";
 import { openMenu } from "../surfaces/menu";
 import type { MenuHandle, MenuRowProjection } from "../surfaces/menu";
@@ -1382,6 +1384,11 @@ function shorthandPlaceholder(
 
 // ─── The whole view ──────────────────────────────────────────────────────────
 
+/** What the Style tab says beside the Variables view, where there is no element to style. */
+export const VARIABLES_INSPECTOR_MESSAGE =
+  "Variables are edited in the view itself. Switch the view to Elements and pick a tag to style " +
+  "its default here.";
+
 /** The three teaching states, and the one that offers a button. */
 function emptyView(message: string, withOpen: boolean): StylePanelView {
   return {
@@ -1401,6 +1408,12 @@ function buildView(canvasMode: () => string): StylePanelView {
   if (!tab) {
     return emptyView("Open a page to style what you click.", true);
   }
+  /* The Styles workspace's Variables view has no canvas to click and edits its custom properties in
+     the pane itself, so the canvas teaching line would ask for something impossible. Say where the
+     Inspector's half of the workspace is instead. */
+  if (canvasMode() === PROJECT_VARIABLES_VIEW) {
+    return emptyView(VARIABLES_INSPECTOR_MESSAGE, false);
+  }
   if (canvasMode() === "stylebook" && shell.stylebook.selection) {
     const node = tab.doc.document;
     /* Checked, not trusted: a tab's document is whatever the file parsed to, asserted rather than
@@ -1442,9 +1455,10 @@ function buildEditor(
   opts: { effectiveStyle?: JxStyle | undefined; stylebookSelector?: string | null },
 ): StylePanelView {
   const { effectiveStyle, stylebookSelector = null } = opts;
-  /* SAFETY: `buildView` calls this with a primary selection it has checked, or in Stylebook, where
-     `selectStylebookTag` parks the selection on the root path `[[]]` rather than emptying it. */
-  const sel = primarySelection(tab.session.selection) as JxPath;
+  /* `buildView` calls this with a primary selection it has checked, or in Stylebook, where the
+     edit targets a TAG and the selection is only parked on the root. A Stylebook tab whose session
+     was never parked (or was cleared since) therefore means the root too, rather than a throw. */
+  const sel: JxPath = primarySelection(tab.session.selection) ?? [];
   /** The document's OWN style — what a commit writes into. */
   const ownRootStyle: JxStyle = node.style || {};
   const style = effectiveStyle ?? ownRootStyle;
@@ -1620,6 +1634,14 @@ function buildEditor(
       };
     }
   }
+  // A Project Styles tag rule also inherits from the rules above it in this same file (`body`,
+  // Then each ancestor tag in its path), which is what its specimen is drawn with. The context walk
+  // Above outranks it: a value the tag itself sets at Base is nearer than anything it inherits.
+  if (stylebookPath) {
+    for (const [p, source] of Object.entries(tagAncestorSources(style, stylebookPath, editMedia))) {
+      inheritedInfo[p] ??= { donor: source.donor, value: source.value };
+    }
+  }
   const inheritedStyle: Record<string, string | number> = {};
   for (const [p, info] of Object.entries(inheritedInfo)) {
     inheritedStyle[p] = info.value;
@@ -2134,6 +2156,11 @@ let _standing: { host: HTMLElement; handle: StylePanelSurface; scope: EffectScop
 export interface StyleHostDeps {
   /** `stylebook` edits a tag catalogue entry; anything else edits the element selection. */
   getCanvasMode: () => string;
+  /**
+   * Whether the tab is the one showing. Read inside the projecting effect, so a hidden tab costs
+   * nothing per selection and re-projects the moment it is opened. Absent means always showing.
+   */
+  isShowing?: () => boolean;
 }
 
 /** The default the tab falls back to when the dock names no mode. */
@@ -2186,9 +2213,16 @@ export function bindStyleHost(el: HTMLElement | null, ctx?: StyleHostDeps): void
   const handle = mountStylePanelSurface(el, first, ACTIONS, {
     target: (element) => attachTargetLine(element ?? undefined),
   });
+  const isShowing = ctx?.isShowing ?? (() => true);
   const scope = effectScope();
   scope.run(() => {
     effect(() => {
+      /* A hidden tab does not project. Its editor is thousands of nodes, and a new selection
+         re-keys every row, so projecting behind the Content tab rebuilt the whole of it on every
+         click — most of what selecting an element cost. */
+      if (!isShowing()) {
+        return;
+      }
       const view = buildView(_canvasMode);
       rememberButtons(view);
       handle.update(view);

package/src/panels/stylebook-doc.ts

@@ -21,8 +21,15 @@ import { isKeyframesAtRule } from "@jxsuite/runtime/css";
 import type { StylebookEntry } from "./stylebook-panel";
 import type { ComponentEntry } from "../files/components";
 import type { JxPath } from "../state";
-import { isNonNullObject } from "@jxsuite/schema/guards";
-import type { JxMutableNode, JxStyle } from "@jxsuite/schema/types";
+import { isNonNullObject, isRef } from "@jxsuite/schema/guards";
+import type { StylebookSpecimens } from "../style/stylebook-specimens";
+import type {
+  JxDocument,
+  JxHeadEntry,
+  JxMutableNode,
+  JxStateDefinition,
+  JxStyle,
+} from "@jxsuite/schema/types";
 
 export interface StylebookDocResult {
   /** The specimen document (plain JSON — safe to post over the bridge). */
@@ -142,6 +149,101 @@ export function hasTagStyle(rootStyle: JxStyle, tagPath: string): boolean {
   return false;
 }
 
+/** One catalogue tag as a list of element defaults draws it: the Styles panel's, and the Outline's. */
+export interface CatalogueRow {
+  /** The catalogue entry the row stands for. */
+  entry: StylebookEntry;
+  tag: string;
+  /** The compound path (`ul li`): the row's key, and what selecting the row selects. */
+  path: string;
+  /** How deep in its specimen the tag sits: 0 for a section's own entries. */
+  depth: number;
+  /** Whether the selection's leaf is this tag ({@link selectionLeaf}). */
+  selected: boolean;
+}
+
+/**
+ * The leaf of a stylebook selection.
+ *
+ * A selection is a compound path (`"ul li"`) and the catalogue draws one row per TAG, so the row
+ * that is marked is the one whose tag is the path's last segment. That is what the tree has always
+ * done; it is written down here because "selected" meaning something other than "equal" is exactly
+ * the kind of thing a reader assumes is a bug.
+ */
+export function selectionLeaf(selection: string | null): string | null {
+  if (!selection) {
+    return null;
+  }
+  return selection.split(" ").pop() ?? null;
+}
+
+/**
+ * Flatten catalogue entries and everything under them into rows, in document order.
+ *
+ * Children are deduplicated by tag: a `<ul>` specimen carries several `<li>`s and they are one row,
+ * because the row selects a TAG and there is one rule per tag path to write. The ONE walk both
+ * lists draw from, so the two cannot drift; what each says about a row (its dot, its label) is the
+ * caller's.
+ *
+ * @param entries A section's entries, or several sections' in order
+ * @param selection The stylebook selection (`shell.stylebook.selection`)
+ */
+export function catalogueRows(
+  entries: readonly StylebookEntry[],
+  selection: string | null,
+): CatalogueRow[] {
+  const leaf = selectionLeaf(selection);
+  const out: CatalogueRow[] = [];
+  const walk = (entry: StylebookEntry, depth: number, parentPath: string): void => {
+    const path = parentPath ? `${parentPath} ${entry.tag}` : entry.tag;
+    out.push({ depth, entry, path, selected: entry.tag === leaf, tag: entry.tag });
+    const children = entry.children
+      ? [...new Map(entry.children.map((child) => [child.tag, child])).values()]
+      : [];
+    for (const child of children) {
+      walk(child, depth + 1, path);
+    }
+  };
+  for (const entry of entries) {
+    walk(entry, 0, "");
+  }
+  return out;
+}
+
+/**
+ * A card's specimen for a component drawn as the first row of a list
+ * (`style/stylebook-specimens.ts`): the list's repeater, reading its row from `rootState[key]` so
+ * two cards' lists cannot collide, and the rest of the page state the row was drawn in, the first
+ * card's value winning a shared name (`$page`, `$site`). Null when the sample is not a repeater
+ * over a state list.
+ */
+export function sampleRowSpecimen(
+  sample: JxDocument,
+  key: string,
+  rootState: Record<string, JxStateDefinition>,
+): JxMutableNode | null {
+  const [list] = Array.isArray(sample.children) ? sample.children : [];
+  if (!isNonNullObject(list) || Array.isArray(list) || !isRef(list.items)) {
+    return null;
+  }
+  const { $ref } = list.items;
+  const listKey = $ref.startsWith("#/state/") ? $ref.slice("#/state/".length) : "";
+  const rows = sample.state?.[listKey];
+  if (!Array.isArray(rows)) {
+    return null;
+  }
+  rootState[key] = rows;
+  for (const [name, value] of Object.entries(sample.state ?? {})) {
+    if (name !== listKey && !(name in rootState)) {
+      rootState[name] = value;
+    }
+  }
+  /* SAFETY: `list` is the repeater object a page's `children` held; only its `items` is replaced,
+     with a ref of the same shape. */
+  const repeater = { ...list, items: { $ref: `#/state/${key}` } } as JxMutableNode;
+  return { children: [repeater], tagName: "div" };
+}
+
 /** Options for {@link buildStylebookDoc}. */
 export interface BuildStylebookDocOpts {
   meta: { $sections: { label: string; elements: StylebookEntry[] }[] };
@@ -150,9 +252,16 @@ export interface BuildStylebookDocOpts {
   effectiveStyle: JxStyle;
   /** Merged $media map (getEffectiveMedia output) — becomes the doc's $media. */
   effectiveMedia: Record<string, string>;
+  /** Merged project+document `$head` (getEffectiveHead output) — becomes the doc's `$head`. */
+  effectiveHead?: JxHeadEntry[];
   filter: string;
   customizedOnly: boolean;
   projectRoot: string | null;
+  /**
+   * How each component card is drawn, by tag (`style/stylebook-specimens.ts`). A component with no
+   * entry is drawn bare, with its declared defaults as attributes.
+   */
+  specimens?: StylebookSpecimens;
 }
 
 /**
@@ -265,6 +374,8 @@ export function buildStylebookDoc(opts: BuildStylebookDocOpts): StylebookDocResu
 
   // Custom components from the registry — live custom elements registered via $elements.
   const $elements: (string | { $ref: string })[] = [];
+  // The data the sample-row cards read: each row's list, and the page context it was drawn in.
+  const rootState: Record<string, JxStateDefinition> = {};
   {
     let comps = opts.components;
     if (filter) {
@@ -288,17 +399,30 @@ export function buildStylebookDoc(opts: BuildStylebookDocOpts): StylebookDocResu
               "/",
             ),
           });
-          const attributes: Record<string, string> = {};
-          for (const p of comp.props ?? []) {
-            if (p.default !== undefined && p.default !== "false" && p.default !== "''") {
-              attributes[p.name] = String(p.default).replaceAll(/^'|'$/g, "");
+          const drawn = opts.specimens?.get(comp.tagName);
+          if (drawn?.kind === "props") {
+            const specimen: JxMutableNode = { $props: drawn.props, tagName: comp.tagName };
+            return cardNode(comp.tagName, `<${comp.tagName}>`, specimen, cardPath, null);
+          }
+          if (drawn?.kind === "row") {
+            const row = sampleRowSpecimen(drawn.sample.doc, `stylebookRow${ci}`, rootState);
+            if (row) {
+              return cardNode(comp.tagName, `<${comp.tagName}>`, row, cardPath, null);
             }
           }
-          const specimen: JxMutableNode = { tagName: comp.tagName };
-          if (Object.keys(attributes).length > 0) {
-            specimen.attributes = attributes;
+          if (drawn?.kind !== "none") {
+            const attributes: Record<string, string> = {};
+            for (const p of comp.props ?? []) {
+              if (p.default !== undefined && p.default !== "false" && p.default !== "''") {
+                attributes[p.name] = String(p.default).replaceAll(/^'|'$/g, "");
+              }
+            }
+            const specimen: JxMutableNode = { tagName: comp.tagName };
+            if (Object.keys(attributes).length > 0) {
+              specimen.attributes = attributes;
+            }
+            return cardNode(comp.tagName, `<${comp.tagName}>`, specimen, cardPath, null);
           }
-          return cardNode(comp.tagName, `<${comp.tagName}>`, specimen, cardPath, null);
         }
         // Npm/format-class components can't be $ref-registered — placeholder box (legacy parity).
         const fallback: JxMutableNode = {
@@ -325,7 +449,15 @@ export function buildStylebookDoc(opts: BuildStylebookDocOpts): StylebookDocResu
   if ($elements.length > 0) {
     doc.$elements = $elements;
   }
+  /* The project's `$head` too: its webfont links are what make `fontFamily: 'Barlow'` render as
+     Barlow, and a specimen sheet drawn in the system fallback shows styles the site never has. */
+  if (opts.effectiveHead && opts.effectiveHead.length > 0) {
+    doc.$head = opts.effectiveHead;
+  }
   doc.$media = opts.effectiveMedia;
+  if (Object.keys(rootState).length > 0) {
+    doc.state = rootState;
+  }
   doc.attributes = { class: "sb-root" };
   doc.children = sections;
   doc.style = transposeStylebookStyle(opts.effectiveStyle);

package/src/panels/stylebook-layers-panel.ts

@@ -1,14 +1,21 @@
 /// <reference lib="dom" />
 /**
- * The Outline panel while the pane is showing Project Styles — the element catalogue and the
- * document's own custom properties.
+ * The Outline panel while the pane is showing a document's Elements view — the element catalogue.
+ *
+ * A page or a component offers **Elements** in its Editor control, which styles that file's element
+ * defaults (`docs/studio/design/stylebook.md`), and the Outline beside it lists the catalogue's
+ * tags instead of the document's tree. `project.json` in the Styles workspace has its own
+ * Navigator, the Styles panel (`panels/styles-panel.ts`), which lists the project's CSS custom
+ * properties too; the variables list this body used to draw beside the Variables view went there
+ * with it.
  *
  * **The body is a Jx document** (`surfaces/panel-stylebook-layers.json`, mounted by
  * `surfaces/panel-stylebook-layers.ts`), so this module renders nothing and projects everything.
- * What stays here is what is a DECISION: how the catalogue's recursive `$sections` flatten into a
- * list, how a child's compound path is spelled, which children are duplicates of each other, which
- * tags the open file has already styled, and which row the current selection marks. The surface
- * reads values.
+ * What stays here is what is a DECISION: which tags the open file has already styled, and what each
+ * row is called. The walk itself (how the catalogue's recursive `$sections` flatten into a list,
+ * how a child's compound path is spelled, which children are duplicates of each other, and which
+ * row the current selection marks) is `stylebook-doc.ts`'s `catalogueRows`, which the Styles
+ * panel's Elements section draws from too. The surface reads values.
  *
  * The panel does not own the panel RECORD — `panels/layers-panel.ts` does, because the Outline is
  * one panel with two bodies and only the record can know which the pane is asking for. That module
@@ -23,13 +30,13 @@ import { activeTab } from "../workspace/workspace";
 import { shell } from "../shell";
 import { componentRegistry } from "../files/components";
 import { mountStylebookLayersSurface } from "../surfaces/panel-stylebook-layers";
+import { catalogueRows } from "./stylebook-doc";
 
 import type { StylebookEntry } from "./stylebook-panel";
 import type {
   StylebookLayersSurfaceHandle,
   StylebookLayersValues,
   StylebookRowView,
-  StylebookVariableView,
 } from "../surfaces/panel-stylebook-layers";
 import { isNonNullObject } from "@jxsuite/schema/guards";
 import type { JxStyle } from "@jxsuite/schema/types";
@@ -55,61 +62,6 @@ function hasTagStyle(rootStyle: JxStyle, tag: string): boolean {
   return isNonNullObject(s) && Object.keys(s).length > 0;
 }
 
-/**
- * The leaf of the current selection.
- *
- * A selection is a compound path (`"ul li"`) and the catalogue draws one row per TAG, so the row
- * that is marked is the one whose tag is the path's last segment. That is what the tree has always
- * done; it is written down here because "selected" meaning something other than "equal" is exactly
- * the kind of thing a reader assumes is a bug.
- */
-function selectedLeaf(selection: string | null): string | null {
-  if (!selection) {
-    return null;
-  }
-  return selection.includes(" ") ? (selection.split(" ").pop() ?? null) : selection;
-}
-
-/**
- * Flatten one catalogue entry and everything under it into rows.
- *
- * Children are deduplicated by tag — a `<ul>` specimen carries two `<li>`s and they are one row,
- * because the row selects a TAG and there is only one `& li` to write.
- */
-function elementRows(
-  entry: StylebookEntry,
-  rootStyle: JxStyle,
-  leaf: string | null,
-  depth: number,
-  parentPath: string,
-  out: StylebookRowView[],
-): void {
-  const { tag } = entry;
-  const fullPath = parentPath ? `${parentPath} ${tag}` : tag;
-  out.push({
-    customized: hasTagStyle(rootStyle, tag),
-    indent: `${INDENT_BASE + depth * INDENT_STEP}px`,
-    key: fullPath,
-    kind: "element",
-    label: entry.text || `<${tag}>`,
-    selected: tag === leaf,
-    tag,
-  });
-  const children = entry.children
-    ? [...new Map(entry.children.map((c: StylebookEntry) => [c.tag, c])).values()]
-    : [];
-  for (const child of children) {
-    elementRows(child, rootStyle, leaf, depth + 1, fullPath, out);
-  }
-}
-
-/** The custom properties the open file declares, in the order it declares them. */
-function variableRows(rootStyle: JxStyle): StylebookVariableView[] {
-  return Object.entries(rootStyle)
-    .filter(([k]) => k.startsWith("--"))
-    .map(([name, value]) => ({ key: name, name, value: String(value) }));
-}
-
 /**
  * What the surface should be showing right now.
  *
@@ -123,14 +75,20 @@ export function stylebookLayersValues(ctx: StylebookLayersCtx): StylebookLayersV
   const tab = activeTab.value;
   const rootStyle: JxStyle = tab?.doc.document?.style || {};
   const { selection } = shell.stylebook;
-  const leaf = selectedLeaf(selection);
 
-  const rows: StylebookRowView[] = [];
-  for (const section of ctx.stylebookMeta.$sections) {
-    for (const entry of section.elements) {
-      elementRows(entry, rootStyle, leaf, 0, "", rows);
-    }
-  }
+  /* The stylebook's own walk (`stylebook-doc.ts` `catalogueRows`), which the Styles panel's
+     Elements section draws from too: the path, the nesting, the deduplication and the leaf mark
+     are one decision, and only the dot and the label are this list's. */
+  const entries = ctx.stylebookMeta.$sections.flatMap((section) => section.elements);
+  const rows: StylebookRowView[] = catalogueRows(entries, selection).map((row) => ({
+    customized: hasTagStyle(rootStyle, row.tag),
+    indent: `${INDENT_BASE + row.depth * INDENT_STEP}px`,
+    key: row.path,
+    kind: "element",
+    label: row.entry.text || `<${row.tag}>`,
+    selected: row.selected,
+    tag: row.tag,
+  }));
   for (const comp of componentRegistry) {
     rows.push({
       customized: false,
@@ -145,13 +103,7 @@ export function stylebookLayersValues(ctx: StylebookLayersCtx): StylebookLayersV
     });
   }
 
-  const variables = variableRows(rootStyle);
-  return {
-    hasVariables: variables.length > 0,
-    rows,
-    tab: shell.stylebook.tab,
-    variables,
-  };
+  return { rows };
 }
 
 /**
@@ -161,7 +113,12 @@ export function stylebookLayersValues(ctx: StylebookLayersCtx): StylebookLayersV
  * one Navigator, so a mount into a DIFFERENT node is the old one being replaced, and holding both
  * would leave the first one's effects running against a scope nobody writes any more.
  */
-let standing: { host: HTMLElement; handle: StylebookLayersSurfaceHandle } | null = null;
+let standing: {
+  /** The latest ctx: the handlers read it, not the one the first mount closed over. */
+  ctx: StylebookLayersCtx;
+  host: HTMLElement;
+  handle: StylebookLayersSurfaceHandle;
+} | null = null;
 
 /**
  * Keep the selected row on screen after a repaint.
@@ -201,12 +158,14 @@ export function mountStylebookLayersPanel(ctx: StylebookLayersCtx, host: HTMLEle
   }
   const values = stylebookLayersValues(ctx);
   if (standing) {
+    standing.ctx = ctx;
     standing.handle.update(values);
   } else {
     standing = {
+      ctx,
       handle: mountStylebookLayersSurface(target, values, {
         selectRow: (path) => {
-          ctx.selectStylebookTag(path, undefined, { panCanvas: true });
+          (standing?.ctx ?? ctx).selectStylebookTag(path, undefined, { panCanvas: true });
         },
       }),
       host: target,
@@ -218,8 +177,8 @@ export function mountStylebookLayersPanel(ctx: StylebookLayersCtx, host: HTMLEle
 /**
  * Take the catalogue down.
  *
- * Called by the Outline's record when the pane is no longer showing Project Styles. Without it the
- * document survives its own irrelevance: lit's branch renders into the range it owns inside
+ * Called by the Outline's record when the pane is no longer showing an Elements view. Without it
+ * the document survives its own irrelevance: lit's branch renders into the range it owns inside
  * `.panel-content` and leaves everything appended after it exactly where it was.
  */
 export function detachStylebookLayers(): void {

package/src/panels/stylebook-panel.ts

@@ -24,15 +24,16 @@ import { projectState, updateSession } from "../store";
 import { createStylebookChromeSurface } from "../surfaces/stylebook-chrome";
 import type { StylebookChromeSurface } from "../surfaces/stylebook-chrome";
 import type { CanvasSurface } from "../canvas/canvas-surface";
-import { tabOfPane } from "../canvas/canvas-surface";
+import { activeMediaOfPane, tabOfPane } from "../canvas/canvas-surface";
 import { activeTab } from "../workspace/workspace";
 import { shell } from "../shell";
 import { componentRegistry } from "../files/components";
-import { getEffectiveMedia, getEffectiveStyle } from "../site-context";
+import { getEffectiveHead, getEffectiveMedia, getEffectiveStyle } from "../site-context";
 import { parseMediaEntries } from "../utils/canvas-media";
 import { mediaDisplayName } from "./shared";
 import { buildStylebookDoc } from "./stylebook-doc";
 import { PROJECT_STYLES_TITLE } from "../style/project-styles";
+import { loadStylebookSpecimens } from "../style/stylebook-specimens";
 import { mountStylebookCanvas, panToStylebookTag } from "../canvas/iframe-host";
 import stylebookMeta from "../../data/stylebook-meta.json";
 import type { CanvasPanelEntry } from "../canvas/canvas-utils";
@@ -124,11 +125,29 @@ function chromeBar(surface: CanvasSurface): HTMLElement {
  * a lit template: the hand-over used to be a `TemplateResult` per artboard, which meant the boards
  * could only be drawn by whoever was already rendering with lit. It is a mount seam instead — the
  * catalogue's bar is a node this module owns, placed in the empty box the stage draws for it, the
- * same way the Compare bar and the Document Header card are.
+ * same way the Compare bar and the writing banner are.
  *
  * @param {StylebookCtx} ctx
  * @returns {Promise<void>} Settles once the artboards are in the page
  */
+/**
+ * The one breakpoint the specimen sheet is drawn at: the one the Context bar's size switcher names
+ * (its `activeMedia`, or the lens a split pane derives), else the base.
+ *
+ * It drew every declared breakpoint side by side, as Design does for a page, and fitting four
+ * artboards into one pane put a 1280px sheet at 24%, where no heading or paragraph can be read; a
+ * sheet of type specimens is read, not compared at a glance. One artboard at the breakpoint being
+ * styled is what the Styles workspace's board shows (Desktop · Tablet · Phone, one at a time), and
+ * it is the breakpoint a style edit lands on, because selecting a specimen writes `activeMedia`.
+ */
+export function stylebookBoards<T extends { name: string }>(
+  boards: readonly T[],
+  active: string | null,
+): T[] {
+  const named = boards.filter((board) => board.name === (active ?? "base"));
+  return named.length > 0 ? named : boards.slice(0, 1);
+}
+
 export async function renderStylebookMode(
   surface: CanvasSurface,
   ctx: StylebookCtx,
@@ -142,6 +161,9 @@ export async function renderStylebookMode(
   const tab = tabOfPane(surface.paneId);
   const filter = shell.stylebook.filter.toLowerCase();
   const { customizedOnly } = shell.stylebook;
+  const generation = surface.renderGeneration;
+  const registry = componentRegistry;
+  const specimensPending = loadStylebookSpecimens(registry);
 
   const effectiveMedia = getEffectiveMedia(tab?.doc.document?.$media);
   const { sizeBreakpoints, baseWidth } = parseMediaEntries(effectiveMedia);
@@ -185,7 +207,7 @@ export async function renderStylebookMode(
       ),
     ];
   } else {
-    panelEntries = allPanelDefs.map((def) =>
+    panelEntries = stylebookBoards(allPanelDefs, activeMediaOfPane(surface.paneId)).map((def) =>
       ctx.canvasPanelEntry(def.name, `${def.displayName} (${def.width}px)`, false, def.width),
     );
   }
@@ -220,11 +242,21 @@ export async function renderStylebookMode(
     chromeHost.replaceChildren(chromeBarNode);
   }
 
+  /* What each component card is drawn with (started before the stage was drawn), asked once per
+     registry, so only the first paint after the project's components are read waits for it. A
+     render that began while it was being asked owns the stage now, and this one stops. */
+  const specimens = await specimensPending;
+  if (surface.renderGeneration !== generation) {
+    return;
+  }
+
   // ONE generated doc shared by every panel — per-panel @media differentiation comes from each
   // Iframe's real viewport width, not from a per-panel style flatten.
   const generated = buildStylebookDoc({
-    components: componentRegistry,
+    components: registry,
+    specimens,
     customizedOnly: Boolean(customizedOnly),
+    effectiveHead: getEffectiveHead(tab?.doc.document?.$head),
     effectiveMedia,
     effectiveStyle: getEffectiveStyle(tab?.doc.document?.style),
     filter,
@@ -255,18 +287,23 @@ export async function renderStylebookMode(
  * @param {string | null} [media]
  */
 export function selectStylebookTag(tag: string, media?: string | null, { panCanvas = false } = {}) {
-  shell.stylebook.selection = tag;
   const ui: Partial<TabUi> = { activeSelector: tag, rightTab: "style" };
   if (media !== undefined) {
     ui.activeMedia = media;
   }
+  // The session is written BEFORE the stylebook selection moves: writing `shell.stylebook.selection`
+  // Re-runs the Style panel's effect synchronously, and it should find `activeSelector` and the
+  // Breakpoint already in place.
   updateSession(activeTab.value, {
-    // The ROOT path, not an empty selection: stylebook mode has always parked the selection on the
-    // Document element while the Style tab edits a TAG, and widening the field to a list changed
-    // Which literal spells that — `[[]]` is one selected path, the root — not what it means.
-    selection: [[]],
+    // EMPTY, not the root. A specimen is not a node of the document, so no document path names
+    // What is selected; `stylebookTarget` is how the chrome learns the tag. Parking on the root
+    // `[[]]` made every reader of the document selection (the command bar, the Inspector header)
+    // Name the catalogue's root `div` while `h1` was being edited, and it is what a canvas hit on
+    // A specimen already left behind, so the Outline and the canvas now agree.
+    selection: [],
     ui,
   });
+  shell.stylebook.selection = tag;
 
   if (tag && panCanvas) {
     panToStylebookTag(tag);