@jxsuite/studio 6.1.2 → 8.0.1

package/src/surfaces/rail.ts

@@ -11,38 +11,27 @@
  * whose only name is a hover tooltip is the accessibility failure studio-ui-guidelines.md §12.3
  * names — and `aria-pressed` states the toggle-focus semantics honestly: re-picking the open panel
  * collapses its dock, which is a two-state control, not a one-way selection. The label is the
- * record's `railLabel` when it declares one (Source Control's is "Source", because the full title
- * ellipsed in the 48px label box), and the full `title` stays the accessible name and the tooltip.
+ * record's `railLabel` when it declares one (none does today: Source Control's "Source" left the
+ * rail with it), and the full `title` stays the accessible name and the tooltip.
  *
- * The foot holds the two buttons that open no Navigator panel. **Library** runs `library.open`: the
- * Library is a canvas tab, not a panel, and its button is pressed while that tab is the focused
- * one. Below it is the ⚙ **Settings** menu, a menu button rendered from the `settings/menu`
- * placement: a record joins the gear by declaring the placement and there is nothing here to update
- * in step. With no registry, or one that declares nothing for either, the foot is empty.
+ * **The rail has no foot.** It is drawn only in the Design workspace (the frame hides its column
+ * everywhere else, `shell.ts`'s `applyDockLayout`), so a control every workspace needs cannot live
+ * here: the ⚙ Settings menu moved to the top bar, and the Library button left with the Library,
+ * which the Content workspace replaces.
  *
- * What this adapter owns is the projection and the two decisions: which panel a button toggles, and
- * where the gear's menu opens. The scope is reactive, so the surface follows `shell` through one
- * effect that recomputes the projection; nothing repaints.
+ * What this adapter owns is the projection and the one decision: which panel a button toggles. The
+ * scope is reactive, so the surface follows `shell` through one effect that recomputes the
+ * projection; nothing repaints.
  *
  * @docs studio/interface
  */
 import { activityBar } from "../store";
 import { effect, effectScope, reactive } from "../reactivity";
 import { requireNavigatorPanelId, shell, toggleActivityTab } from "../shell";
-import { refreshGitStatus } from "../panels/git-panel";
+import { refreshGitStatus } from "../publish/source-control";
 import { panelContext, railGroups } from "../panels/panel-registry";
 import { registerNavigatorPanels } from "../panels/navigator-panels";
-import { activeRegistry } from "../commands/active-registry";
-import { runActiveReported } from "../commands/run-reported";
-import {
-  dismissSettingsMenu,
-  isSettingsMenuOpen,
-  openSettingsMenu,
-  SETTINGS_MENU_PLACEMENT,
-} from "../panels/settings-menu";
 import { mountSurface, registerSurface } from "../ui/surface";
-import { libraryTabId } from "../browse/library-source";
-import { activeTab } from "../workspace/workspace";
 import railDoc from "./rail.json";
 
 import type { EffectScope } from "@vue/reactivity";
@@ -71,21 +60,9 @@ interface RailGroupProjection {
   panels: RailButton[];
 }
 
-/** The parts of the rail's scope recomputed from the registry and the shell on every render. */
-type RailProjection = Pick<
-  RailScope,
-  "groups" | "libraryOpen" | "libraryVisible" | "settingsVisible"
->;
-
 interface RailScope {
   groups: RailGroupProjection[];
-  settingsVisible: boolean;
-  settingsOpen: boolean;
-  libraryVisible: boolean;
-  libraryOpen: boolean;
-  openLibrary: () => void;
   toggle: (id: string) => void;
-  openSettings: (anchor: EventTarget | null) => void;
 }
 
 let _scope: EffectScope | null = null;
@@ -117,9 +94,9 @@ export function toggleRailPanel(panel: PanelRecord): void {
 }
 
 /** The rail, as the surface reads it, from the registry and the shell as they stand now. */
-function project(): RailProjection {
+function project(): RailGroupProjection[] {
   const ctx = panelContext();
-  const groups = railGroups(ctx).map((group, index) => ({
+  return railGroups(ctx).map((group, index) => ({
     dividerAbove: index > 0,
     label: group.label,
     level: group.level,
@@ -132,41 +109,12 @@ function project(): RailProjection {
       title: panel.title,
     })),
   }));
-  const registry = activeRegistry();
-  const settingsVisible =
-    registry !== null && registry.forPlacement(SETTINGS_MENU_PLACEMENT).length > 0;
-  const libraryVisible =
-    registry?.get(LIBRARY_COMMAND) !== undefined && registry.isVisible(LIBRARY_COMMAND);
-  const libraryOpen = activeTab.value?.id === libraryTabId();
-  return { groups, libraryOpen, libraryVisible, settingsVisible };
 }
 
-/** The command the Library button runs: the record decides when it can, and what opening means. */
-const LIBRARY_COMMAND = "library.open";
-
 /** The reactive scope the surface reads, made once. */
 function state(): RailScope {
   _state ??= reactive<RailScope>({
     groups: [],
-    libraryOpen: false,
-    libraryVisible: false,
-    openLibrary: () => {
-      void runActiveReported(LIBRARY_COMMAND, undefined, "Navigator rail");
-    },
-    openSettings: (anchor: EventTarget | null) => {
-      if (!(anchor instanceof HTMLElement)) {
-        return;
-      }
-      openSettingsMenu(anchor, {
-        rerender: () => {
-          if (_state) {
-            _state.settingsOpen = isSettingsMenuOpen();
-          }
-        },
-      });
-    },
-    settingsOpen: false,
-    settingsVisible: false,
     toggle: (id: string) => {
       const panel = railGroups(panelContext())
         .flatMap((group) => group.panels)
@@ -181,13 +129,7 @@ function state(): RailScope {
 
 /** Recompute the projection from the registry and the shell; the surface follows. */
 export function renderActivityBar(): void {
-  const scope = state();
-  const next = project();
-  scope.groups = next.groups;
-  scope.settingsVisible = next.settingsVisible;
-  scope.libraryVisible = next.libraryVisible;
-  scope.libraryOpen = next.libraryOpen;
-  scope.settingsOpen = isSettingsMenuOpen();
+  state().groups = project();
   ensureMounted();
 }
 
@@ -209,9 +151,11 @@ export function mount(): void {
   _scope = effectScope();
   _scope.run(() => {
     effect(() => {
-      // Source control is PROJECT state, so the badge is fetched and drawn without reference to
-      // Any tab. The badge needs a status once. A refresh that already failed must not re-arm this:
-      // The effect re-runs on the very state the failure writes, so retrying here spins.
+      // Source control is PROJECT state, so its status is fetched without reference to any tab.
+      // No rail button draws it now; the Command Bar's Publish count does, and this is the fetch
+      // That count reads (`ctx.git.dirtyCount`). It needs a status once. A refresh that already
+      // Failed must not re-arm this: the effect re-runs on the very state the failure writes, so
+      // Retrying here spins.
       const { error, loading, status } = shell.git;
       if (!status && !loading && !error) {
         void refreshGitStatus();
@@ -222,7 +166,6 @@ export function mount(): void {
 }
 
 export function unmount(): void {
-  dismissSettingsMenu();
   _scope?.stop();
   _scope = null;
   const pending = _mount;

package/src/surfaces/schema-form.json

@@ -80,6 +80,11 @@
       "gap": "var(--jx-space-1)",
       "minWidth": "0"
     },
+    "& [part=\"row\"] > [part=\"cell\"]:only-of-type > *": {
+      "$description": "A row of one cell (an item of a list of single values: a category, a picture) gives that cell the row's width, so a list reads as the fields around it do rather than as a column of stubs.",
+      "flex": "1",
+      "minWidth": "0"
+    },
     "& [part=\"row-add\"]": {
       "alignSelf": "flex-start"
     },
@@ -236,6 +241,9 @@
                       },
                       "multiline": {
                         "$ref": "$map/item/multiline"
+                      },
+                      "type": {
+                        "$ref": "$map/item/inputType"
                       }
                     },
                     "oninput": {
@@ -621,7 +629,7 @@
                     ]
                   },
                   "rows": {
-                    "$description": "An array whose items are objects with a declared shape: one row per item, one cell per declared property, a remove beside each and one add below. The alternative was the raw-JSON editor, which is what an array of anything else still gets — a shape the schema states is a shape the form can draw.",
+                    "$description": "An array whose items have a declared shape: one row per item, one cell per declared property of an object item, or one cell for a single-value item (a list of categories, a gallery of pictures), with a remove beside each and one add below. The alternative was the raw-JSON editor, which is what an array of anything else still gets: a shape the schema states is a shape the form can draw.",
                     "tagName": "span",
                     "attributes": {
                       "part": "rows",
@@ -858,7 +866,7 @@
                                     }
                                   },
                                   "control": {
-                                    "$description": "A cell a registered control owns — a relationship to another collection is the one that reaches here. The document draws the empty host and nothing inside it; `ui/schema-form.ts` mounts the control into it, by the same dispatch a FIELD host gets. An extension's control is its own surface rather than part of this one, and the seam between them is this empty node.",
+                                    "$description": "A cell a registered control owns: a relationship to another collection, or a picture (the media field). The document draws the empty host and nothing inside it; `ui/schema-form.ts` mounts the control into it, by the same dispatch a FIELD host gets. An extension's control is its own surface rather than part of this one, and the seam between them is this empty node.",
                                     "tagName": "span",
                                     "attributes": {
                                       "part": "cell-control-host",

package/src/surfaces/schema-form.ts

@@ -106,6 +106,8 @@ export interface SchemaFormFieldView {
   mono: boolean;
   /** Draw the text control as a text area. */
   multiline: boolean;
+  /** The native input type of the text control: `date` for a `format: "date"` field, else `text`. */
+  inputType: string;
   /** Why this value is refused (§16.1's inline tier). Empty draws nothing. */
   error: string;
   /** Whether there is a refusal to announce. A document branches on a flag, never on a length. */

package/src/surfaces/seo.json

@@ -244,7 +244,7 @@
       "color": "var(--warning)"
     },
     "& [part=\"empty\"]": {
-      "$description": "A fully-described page says so rather than printing an empty list. It borrowed `.doc-header-empty` from the card this block used to live in; the card still writes that class, so the rule stays where it is and this surface stops reaching across for it.",
+      "$description": "A fully-described page says so rather than printing an empty list.",
       "margin": "0",
       "padding": "0 0 var(--jx-space-3)",
       "fontSize": "var(--jx-text-md)",

package/src/surfaces/settings-contributed.json

@@ -214,7 +214,7 @@
                         "part": "new-open"
                       },
                       "$props": {
-                        "label": "New Entry",
+                        "label": "${state.newLabel}",
                         "icon": "plus",
                         "quiet": true,
                         "size": "sm"
@@ -234,7 +234,7 @@
                       "children": [
                         {
                           "tagName": "span",
-                          "textContent": "New Entry"
+                          "textContent": "${state.newLabel}"
                         }
                       ]
                     },
@@ -250,8 +250,8 @@
                             "part": "new-field"
                           },
                           "$props": {
-                            "label": "New entry name",
-                            "placeholder": "entry-name",
+                            "label": "${state.newFieldLabel}",
+                            "placeholder": "${state.newPlaceholder}",
                             "size": "sm",
                             "value": {
                               "$ref": "#/state/newName"
@@ -361,7 +361,7 @@
                   "attributes": {
                     "part": "empty"
                   },
-                  "textContent": "Select or create an entry"
+                  "textContent": "${state.emptyText}"
                 },
                 "editing": {
                   "tagName": "div",

package/src/surfaces/settings-contributed.ts

@@ -41,7 +41,7 @@ export interface ContributedEntryView {
   /** The key in the section's map on disk — the row's identity and its `data-entry`. */
   key: string;
   selected: boolean;
-  /** `pane.primary/entry:<key>`, so a shot can name the row without a selector. */
+  /** `overlay.dialog:settings/entry:<key>`, so a shot can name the row without a selector. */
   region: string;
 }
 
@@ -61,8 +61,16 @@ export interface ContributedView {
   editorState: "empty" | "editing";
   /** What the rename field holds — the key on disk, or what the reader has just typed. */
   entryName: string;
-  /** `pane.primary/editor`. */
+  /** `overlay.dialog:settings/editor`. */
   editorRegion: string;
+  /** The new-entry button: "New content type", or "New entry" when the section names none. */
+  newLabel: string;
+  /** The new-entry field's accessible label. */
+  newFieldLabel: string;
+  /** The new-entry field's placeholder, a slug of the noun. */
+  newPlaceholder: string;
+  /** What the right column says while nothing is selected. */
+  emptyText: string;
 }
 
 /** What the reader may do here. Each one is a decision the section makes. */
@@ -116,6 +124,10 @@ function emptyView(): ContributedView {
     newName: "",
     newState: "closed",
     title: "",
+    emptyText: "",
+    newFieldLabel: "",
+    newLabel: "",
+    newPlaceholder: "",
   };
 }
 
@@ -199,6 +211,10 @@ export function mountContributedSurface(
       scope.newName = view.newName;
       scope.newState = view.newState;
       scope.title = view.title;
+      scope.emptyText = view.emptyText;
+      scope.newFieldLabel = view.newFieldLabel;
+      scope.newLabel = view.newLabel;
+      scope.newPlaceholder = view.newPlaceholder;
     },
   };
 }

package/src/surfaces/settings-css-vars.json

@@ -1,29 +1,30 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioSettingsCssVars",
-  "$description": "Project Settings › CSS Variables: the project's design tokens, grouped by what they name, each editable in place and each able to carry a different value in any rendering context the project declares. The adapter (`surfaces/settings-css-vars.ts`) hands in the groups already grouped, each token already resolved — its swatch colour, the chip it wears when its value follows another token, the override rows it has and the contexts it could still be given one in — and the document draws them. Nothing here reads `project.json` and nothing here decides what a token IS: `style/project-styles.ts` owns the vocabulary and `settings/css-vars-editor.ts` owns the writes. A context is DEFINED in Contexts and only overridden here, which is why the one thing the colour group says when no scheme exists is where to go and say it.",
+  "$description": "The Styles workspace's Variables view, its editor (studio.md §7.1): the project's design tokens, grouped by what they name, each editable in place and each able to carry a different value in any rendering context the project declares. The view's own frame (`surfaces/styles-variables.json`) draws the heading and mounts this document into its `editor` island. The adapter (`surfaces/settings-css-vars.ts`) hands in the groups already grouped, each token already resolved — its swatch colour, the chip it wears when its value follows another token, the override rows it has, the contexts it could still be given one in and whether it is the token the Outline pointed at — and the document draws them. Nothing here reads `project.json` and nothing here decides what a token IS: `style/project-styles.ts` owns the vocabulary and `settings/css-vars-editor.ts` owns the writes. A context is DEFINED in Project Settings › Contexts and only overridden here, which is why the one thing the colour group says when no scheme exists is where to go and say it.",
   "tagName": "section",
   "attributes": {
     "part": "cssvars"
   },
   "style": {
-    "$description": "This section's whole look, keyed on `part`. Six of the rules it used to borrow are gone rather than moved: `.settings-section` never had a rule anywhere (it was on the orphan ledger), and `.css-var-swatch input[type=\"color\"]` plus the two chip spans are drawn here now because the lit helper that emitted them is drawn here now. Every `--spectrum-font-size-*` reference is re-pointed at the kit's scale: a document is mounted in the pane rather than inside `<sp-theme>`, so each of those would have silently taken its hard-coded fallback.",
+    "$description": "This section's whole look, keyed on `part`. Six of the rules it used to borrow are gone rather than moved: `.settings-section` never had a rule anywhere (it was on the orphan ledger), and `.css-var-swatch input[type=\"color\"]` plus the two chip spans are drawn here now because the lit helper that emitted them is drawn here now. Every `--spectrum-font-size-*` reference is re-pointed at the kit's scale: a document is mounted in the pane rather than inside `<sp-theme>`, so each of those would have silently taken its hard-coded fallback. Two part names are this document's own on purpose: the colour well is `well` and a font token's specimen is `font-preview`, because `swatch` and `preview` are parts INSIDE `jx-select` (its options' colour chip and its closed-state value), and this section draws a `jx-select` per token. The kit is light DOM, so `& [part=\"preview\"]` reached the Add override picker's own value and gave it this sheet's 108px indent, bottom padding and 13px type: a 36px control under a 20px field. The name column is a fixed width (`--name-col`) so every value field in a group starts at the same x, and the override list indents to that same column rather than to a literal that guessed it.",
+    "--name-col": "12rem",
     "display": "block",
-    "& [part=\"title\"]": {
-      "margin": "0 0 16px",
-      "fontSize": "16px",
-      "fontWeight": "600",
-      "color": "var(--fg)"
-    },
     "& [part=\"section-error\"]": {
       "$description": "A write that failed, said under the section title rather than pinned to a control. This section saves on change and the predecessor dropped every rejection on the floor, so a read-only file made each edit look as though it had been taken and then quietly forgotten. It is `section-error` rather than `error` because every text field and select in the section draws a permanent `[part=\"error\"]` of its own in this same light-DOM tree, and a rule on that name would give their refusal sentences this margin and size too.",
       "margin": "0 0 12px",
       "fontSize": "var(--jx-text-md)",
       "color": "var(--danger)"
     },
-    "& [part=\"group\"]": {
+    "& [part=\"token-group\"]": {
       "marginBottom": "24px"
     },
+    "& [part=\"token\"][aria-current=\"true\"]": {
+      "$description": "The token the Outline pointed the view at: a tinted band with the accent edge the Outline's own selected row wears, so the two say the same thing about one property.",
+      "borderRadius": "var(--radius)",
+      "background": "var(--accent-20)",
+      "boxShadow": "inset 2px 0 0 var(--accent)"
+    },
     "& [part=\"group-title\"]": {
       "margin": "0 0 8px",
       "fontSize": "13px",
@@ -39,14 +40,18 @@
       "padding": "4px 0"
     },
     "& [part=\"name\"]": {
+      "$description": "A fixed column, not a minimum: with `minWidth` the value field started wherever its name ended, so a long name pushed its field out of line with every field above it. A name longer than the column is cut with an ellipsis and carries its whole self in `title`.",
+      "flex": "0 0 var(--name-col)",
+      "overflow": "hidden",
+      "textOverflow": "ellipsis",
+      "whiteSpace": "nowrap",
       "fontSize": "var(--jx-text-md)",
-      "color": "var(--fg-dim)",
-      "minWidth": "100px"
+      "color": "var(--fg-dim)"
     },
     "& [part=\"swatch-slot\"], & [part=\"chip-slot\"]": {
       "display": "contents"
     },
-    "& [part=\"swatch\"]": {
+    "& [part=\"well\"]": {
       "$description": "The colour well. Its background is the value the token RESOLVES to, so an alias token is a colour rather than a blank square, and the native input over it is transparent — the well is what the reader sees and the input is only what they operate.",
       "position": "relative",
       "width": "24px",
@@ -66,15 +71,14 @@
       "cursor": "pointer"
     },
     "& [part=\"value\"]": {
-      "flex": "1",
+      "flex": "0 1 16rem",
       "minWidth": "0"
     },
     "& [data-group=\"color\"] [part=\"value\"]": {
-      "maxWidth": "160px"
+      "flexBasis": "10rem"
     },
     "& [data-group=\"size\"] [part=\"value\"]": {
-      "flex": "none",
-      "maxWidth": "120px"
+      "flexBasis": "8rem"
     },
     "& [part=\"chip\"]": {
       "$description": "A value that is exactly `var(--token)` is a reference, and raw text is the one rendering that hides both which token and what it currently is. The chip says both. It is a span, not a button: it states, it does not navigate. Same border, same size and same radius as the provenance chips in the Inspector, because \"this value comes from somewhere else\" is the same sentence in both places.",
@@ -103,16 +107,20 @@
       "overflow": "hidden",
       "textOverflow": "ellipsis"
     },
-    "& [part=\"preview\"]": {
-      "$description": "A font token is the one kind whose value cannot be read: `'Georgia', serif` is a name for a shape, so the shape is drawn. Indented to the value column, because it belongs to the field above it rather than to the section.",
-      "padding": "4px 0 12px 108px",
+    "& [part=\"font-preview\"]": {
+      "$description": "A font token is the one kind whose value cannot be read: `'Georgia', serif` is a name for a shape, so the shape is drawn. Indented to the value column (the name column and the gap after it), because it belongs to the field above it rather than to the section.",
+      "padding": "4px 0 12px calc(var(--name-col) + 8px)",
       "fontSize": "13px",
       "color": "var(--fg-dim)"
     },
     "& [part=\"overrides\"]": {
-      "paddingLeft": "108px",
+      "$description": "Indented to the value column: past the name column and its gap, and in the colour group past the well too, so an override value sits under the base value it overrides.",
+      "paddingLeft": "calc(var(--name-col) + 8px)",
       "marginBottom": "8px"
     },
+    "& [data-group=\"color\"] [part=\"overrides\"]": {
+      "paddingLeft": "calc(var(--name-col) + 40px)"
+    },
     "& [part=\"override\"]": {
       "display": "flex",
       "alignItems": "center",
@@ -138,6 +146,11 @@
       "alignItems": "center",
       "padding": "2px 0"
     },
+    "& [part=\"add-picker\"]": {
+      "$description": "As compact as the fields beside it: sized to its own label rather than stretched, since it is a verb on the list above it and not a value of its own.",
+      "flex": "none",
+      "width": "auto"
+    },
     "& [part=\"add\"]": {
       "display": "flex",
       "alignItems": "center",
@@ -162,13 +175,6 @@
     }
   },
   "children": [
-    {
-      "tagName": "h3",
-      "attributes": {
-        "part": "title"
-      },
-      "textContent": "CSS Variables"
-    },
     {
       "tagName": "div",
       "attributes": {
@@ -200,12 +206,12 @@
       "map": {
         "tagName": "div",
         "attributes": {
-          "part": "group",
+          "part": "token-group",
           "data-group": "${$map.item.id}"
         },
         "children": [
           {
-            "tagName": "h4",
+            "tagName": "h3",
             "attributes": {
               "part": "group-title"
             },
@@ -223,7 +229,8 @@
               "tagName": "div",
               "attributes": {
                 "part": "token",
-                "data-token": "${$map.item.name}"
+                "data-token": "${$map.item.name}",
+                "aria-current": "${$map.item.current ? 'true' : null}"
               },
               "children": [
                 {
@@ -245,7 +252,7 @@
                         "swatch": {
                           "tagName": "div",
                           "attributes": {
-                            "part": "swatch"
+                            "part": "well"
                           },
                           "style": {
                             "background": {
@@ -290,7 +297,8 @@
                     {
                       "tagName": "span",
                       "attributes": {
-                        "part": "name"
+                        "part": "name",
+                        "title": "${$map.item.label}"
                       },
                       "textContent": "${$map.item.label}"
                     },
@@ -433,7 +441,7 @@
                     "font": {
                       "tagName": "div",
                       "attributes": {
-                        "part": "preview"
+                        "part": "font-preview"
                       },
                       "style": {
                         "fontFamily": {
@@ -498,7 +506,7 @@
                                   "swatch": {
                                     "tagName": "div",
                                     "attributes": {
-                                      "part": "swatch"
+                                      "part": "well"
                                     },
                                     "style": {
                                       "background": {
@@ -788,7 +796,7 @@
                 "children": [
                   {
                     "tagName": "span",
-                    "textContent": "No colour scheme is defined yet, so these tokens have one value each."
+                    "textContent": "No color scheme is defined yet, so these tokens have one value each."
                   },
                   {
                     "tagName": "jx-action-button",
@@ -797,7 +805,7 @@
                     },
                     "$props": {
                       "size": "sm",
-                      "hint": "Define a colour scheme in Project Settings › Contexts"
+                      "hint": "Define a color scheme in Project Settings › Contexts"
                     },
                     "onclick": {
                       "$ref": "#/state/manageContexts"

package/src/surfaces/settings-css-vars.ts

@@ -1,6 +1,8 @@
 /// <reference lib="dom" />
 /**
- * The CSS Variables settings section, as a mounted document.
+ * The CSS Variables editor, as a mounted document: the body of the Styles workspace's Variables
+ * view (`surfaces/styles-variables.json` is its frame). The file keeps the `settings-` name it had
+ * while the editor was a Project Settings section.
  *
  * `settings/css-vars-editor.ts` is the flow — it reads the project's root style block, decides what
  * an edit writes and pushes the result at every live canvas — and this is the surface it draws
@@ -19,11 +21,11 @@
  * inventing one to be photographed is what the screenshot policy forbids. It is the one place a
  * document reaches past the kit, and it reaches for a platform element rather than a Spectrum one.
  *
- * **Keyed by host, not by module.** Project Settings is a pane document and a pane can be split, so
- * two containers may be showing this section at once; a single module-level mount would take the
+ * **Keyed by host, not by module.** The Variables view is a pane document and a pane can be split,
+ * so two containers may be showing this section at once; a single module-level mount would take the
  * first one's surface away from it the moment the second drew.
  *
- * @docs studio/projects/settings
+ * @docs studio/design/tokens
  */
 
 import { reactive } from "../reactivity";
@@ -60,6 +62,8 @@ export interface OverrideRowView {
 export interface TokenRowView {
   /** The custom property. The row's key, and every handler's first argument. */
   name: string;
+  /** Whether this is the token the Outline pointed the view at. Drawn as `aria-current`. */
+  current: boolean;
   label: string;
   value: string;
   removeLabel: string;
@@ -190,3 +194,72 @@ export function renderCssVarsSurface(
     record.handle = handle;
   });
 }
+
+/**
+ * Bring one token's row on screen and put the keyboard on its value.
+ *
+ * The adapter's half of pointing the editor at a token: the flow marks the row through the scope
+ * (`current`), and only the surface knows where the row it draws is. It waits a turn, because the
+ * mark is a scope write and the row it marks is drawn by the binding that write schedules, and it
+ * searches the mounted root as it stands then, so a section redrawn since the call is the one
+ * searched. A host with no surface, or a name with no row, moves nothing.
+ *
+ * @param {HTMLElement} host The section container the editor was rendered into.
+ * @param {string} name A custom property, `--accent`.
+ */
+export function revealCssVarsToken(host: HTMLElement, name: string): void {
+  const record = mounts.get(host);
+  if (!record) {
+    return;
+  }
+  setTimeout(() => {
+    const root = record.handle?.root;
+    if (!(root instanceof HTMLElement) || !root.isConnected) {
+      return;
+    }
+    const row = [...root.querySelectorAll<HTMLElement>('[part="token"]')].find(
+      (candidate) => candidate.dataset["token"] === name,
+    );
+    if (!row) {
+      return;
+    }
+    row.scrollIntoView({ behavior: "smooth", block: "nearest" });
+    // The NATIVE input: the kit's text field does not delegate focus from its host.
+    row.querySelector<HTMLElement>('[part="value"] input')?.focus();
+  }, 0);
+}
+
+/**
+ * Bring one group's heading on screen, and with `add` put the keyboard on its Add row's name field.
+ *
+ * The Styles panel's group headings and its "Add variable" land here. It waits a turn for the
+ * reason {@link revealCssVarsToken} does. A host with no surface, or a group the section does not
+ * draw (an empty Other), moves nothing.
+ *
+ * @param {HTMLElement} host The section container the editor was rendered into.
+ * @param {string} group A token group id: `color`, `font`, `size` or `other`.
+ * @param {boolean} add Whether to focus the group's Add row.
+ */
+export function revealCssVarsGroup(host: HTMLElement, group: string, add: boolean): void {
+  const record = mounts.get(host);
+  if (!record) {
+    return;
+  }
+  setTimeout(() => {
+    const root = record.handle?.root;
+    if (!(root instanceof HTMLElement) || !root.isConnected) {
+      return;
+    }
+    const section = [...root.querySelectorAll<HTMLElement>("[data-group]")].find(
+      (candidate) => candidate.dataset["group"] === group,
+    );
+    if (!section) {
+      return;
+    }
+    section.scrollIntoView({ behavior: "smooth", block: "start" });
+    if (add) {
+      // The NATIVE input, for the reason `revealCssVarsToken` gives.
+      section.querySelector<HTMLElement>('[part="add-name"] input')?.focus();
+    }
+  }, 0);
+}