@jxsuite/studio 6.1.2 → 8.0.1

package/src/services/automation.ts

@@ -92,13 +92,14 @@ export function isScriptable(command: AnyCommand): boolean {
 // ─── The registry-gap declaration ─────────────────────────────────────────────
 
 /**
- * How a manifest id the registry does not declare is going to stop existing.
+ * Why a manifest id the registry does not declare will never be one.
  *
- * - `command` — a thing a user does, so it becomes a registry record. The value names who lands it.
- * - `seed` — a remote's state, addressed through {@link AutomationApi.seed}.
- * - `refused` — §13.5 says the app will never provide it; the manifest step is deleted.
+ * There were three fates. `command` (a thing a user does, so it becomes a registry record) emptied
+ * when `media.browse` landed in `media/media-commands.ts`, the last of them; `seed` (a remote's
+ * state) is answered from {@link seedIds}. What is left is `refused`: §13.5 says the app will never
+ * provide it, and the manifest step is deleted.
  */
-export type GapDisposition = "command" | "seed" | "refused";
+export type GapDisposition = "refused";
 
 export interface ManifestId {
   disposition: GapDisposition;
@@ -117,17 +118,16 @@ export interface ManifestId {
  * — only to explain, when the registry refuses an id, which of the three fates that id has.
  *
  * This is a countdown, in the idiom of the checker's own `TOGGLE_DEBT`: it may only shrink. It went
- * 39 → 8 when the manifest converted, and 8 → 7 when `element.insertData` became `insert.data`
- * (`canvas/canvas-render.ts`). What left: every `seed` entry, now read off {@link seedIds} and
+ * 39 → 8 when the manifest converted, 8 → 7 when `element.insertData` became `insert.data`
+ * (`canvas/canvas-render.ts`), and down to five when `media.browse` became a record of its own
+ * (`media/media-commands.ts`). What left: every `seed` entry, now read off {@link seedIds} and
  * answered from the live registry rather than from a hand-kept list; every `toggle*` entry, which
- * {@link TOGGLE_ID} refuses before this map is ever consulted; and every `command` entry whose
- * record has since landed.
+ * {@link TOGGLE_ID} refuses before this map is ever consulted; and every `command` entry, each of
+ * whose records has landed.
  *
- * What is left is two kinds. Two `command` entries are the manifest's real registry gaps — each
- * reached today by an `input` step clicking a hand-stamped region, and each of those steps carries
- * an `unstable` hatch naming the phase that lands the record, so this map and that hatch count are
- * the same debt. Five `refused` entries are NOT a countdown: they are §13.5's normative refusals,
- * and they stay so that a caller reaching for one gets the reason instead of "unknown command".
+ * What is left is one kind, and it is NOT a countdown: five `refused` entries, §13.5's normative
+ * refusals, which stay so that a caller reaching for one gets the reason instead of "unknown
+ * command".
  */
 export const AUTOMATION_COMMANDS = {
   "file.contextMenu": {
@@ -138,14 +138,13 @@ export const AUTOMATION_COMMANDS = {
     disposition: "refused",
     note: "matched RENDERED TEXT, which R1 of scripts/screenshots/README.md forbids; a row is addressed by its data-jx-path",
   },
-  "media.browse": { disposition: "command", note: "media.browse, site-architecture.md §9.4" },
   "project.showWelcome": {
     disposition: "refused",
     note: "cold start is a startup profile (?profile=fresh), not an action",
   },
   "settings.setSection": {
     disposition: "refused",
-    note: 'mirrored the section registry\'s LABELS; say settings.open { section: "cssVars" }',
+    note: 'mirrored the section registry\'s LABELS; say settings.open { section: "contexts" }',
   },
   "view.setStatus": {
     disposition: "refused",
@@ -414,11 +413,8 @@ function unknownCommandMessage(
     return `"${id}" is a seed, not a command — call seed("${id}", …)`;
   }
   const gap = COMMAND_GAPS.get(id);
-  if (gap?.disposition === "refused") {
-    return `"${id}" is refused by spec §13.5: ${gap.note}`;
-  }
   if (gap) {
-    return `"${id}" has no command record yet (${gap.note}) — __jxAutomation.run projects the registry and nothing else`;
+    return `"${id}" is refused by spec §13.5: ${gap.note}`;
   }
   const known = registry
     .list()

package/src/services/cf-settings.ts

@@ -1,12 +1,12 @@
 /// <reference lib="dom" />
 /**
  * Cf-settings — the Cloudflare publish connection on platforms without a hosted OAuth broker (dev
- * server, desktop). The API token is stored like the AI key, over `settings/kernel.ts`. It only ever
- * leaves the machine to the same-origin `/__studio/cf/proxy`, which forwards it as a bearer to
+ * server, desktop). The API token is stored like the AI key, over `settings/kernel.ts`. It only
+ * ever leaves the machine to the same-origin `/__studio/cf/proxy`, which forwards it as a bearer to
  * api.cloudflare.com (not CORS-enabled, hence the proxy).
  *
- * As with the AI provider, a blank value is a VALUE: {@link clearCfConnection} is the deletion path,
- * so nothing can revoke a connection by rendering an empty field into a setter.
+ * As with the AI provider, a blank value is a VALUE: {@link clearCfConnection} is the deletion
+ * path, so nothing can revoke a connection by rendering an empty field into a setter.
  *
  * @license MIT
  */

package/src/services/connection.ts

@@ -14,8 +14,8 @@
  * does not stay on the Problems list (§16.1's second and third rules: a record is retired when what
  * it names is fixed, and a repeat is not a new row).
  *
- * A platform without `subscribeConnection` — the dev server, electrobun — installs nothing. There
- * is no connection to lose there, and a notice about one would be a lie.
+ * A platform without `subscribeConnection` — the dev server — installs nothing. There is no
+ * connection to lose there, and a notice about one would be a lie.
  *
  * @docs studio/interface/problems-and-progress
  */

package/src/services/directory-picker.ts

@@ -25,8 +25,8 @@
  * cancel, and Browse… a button that silently did nothing.
  *
  * Only the plain dev-server browser session needs this. Every packaged build has a real native
- * dialog that returns a path directly and keeps it — electrobun's `Utils.openFileDialog`, and the
- * NixOS chromium build's XDG desktop portal.
+ * dialog that returns a path directly and keeps it — the Electron app's native folder dialog, and
+ * the NixOS chromium build's XDG desktop portal.
  *
  * @docs studio/projects/create
  */

package/src/services/render-critic.ts

@@ -13,8 +13,16 @@
  * @license MIT
  */
 
-import { buildScope, renderNode, runScoped, setSkipServerFunctions } from "@jxsuite/runtime";
+import {
+  buildScope,
+  renderNode,
+  runScoped,
+  setResolveToken,
+  setSkipServerFunctions,
+  setTemplateErrorHandler,
+} from "@jxsuite/runtime";
 import type { JxDocument } from "@jxsuite/schema/types";
+import { hostResolveToken } from "../canvas/canvas-origin";
 
 /**
  * Translate a render-time error into an actionable message the model can fix.
@@ -52,8 +60,17 @@ export async function renderCheck(
   doc: JxDocument,
 ): Promise<{ ok: true } | { ok: false; error: string }> {
   let stopRender: (() => void) | null = null;
+  /* A binding that throws no longer unwinds the render (spec.md §6.1) — it renders empty and waits
+     for its data — so the throw is collected here instead. The first one is the verdict: a page
+     whose template can never evaluate is exactly what this check exists to refuse. */
+  const bindingErrors: Error[] = [];
+  setTemplateErrorHandler((error) => {
+    bindingErrors.push(error);
+  });
   try {
     setSkipServerFunctions(true);
+    // The desktop dev proxy refuses a class resolve without the token the canvas carries.
+    setResolveToken(hostResolveToken());
 
     const state = await buildScope(doc, {});
 
@@ -63,10 +80,12 @@ export async function renderCheck(
     });
     stopRender = stop;
 
-    return { ok: true };
+    const [first] = bindingErrors;
+    return first ? { ok: false, error: translateRenderError(first) } : { ok: true };
   } catch (error) {
     return { ok: false, error: translateRenderError(error) };
   } finally {
+    setTemplateErrorHandler(null);
     // Dispose all effects created synchronously by renderNode via the RUNTIME's runScoped — scope
     // Collection is per @vue/reactivity module instance, so a studio effectScope here would collect
     // Nothing. Effects from the async buildScope (prototype/computed setup) still escape the scope;

package/src/services/settings/definitions.ts

@@ -2,23 +2,23 @@
  * The settings registry — every application setting Studio holds, declared once.
  *
  * Before this table the answer to "which settings roam, and what is each one's default" lived in
- * four places: a `PERSISTED_SETTINGS_KEYS` array, a private `const` per key in each `*-settings.ts`,
- * a bespoke getter/setter pair beside it, and whatever the getter's `||` happened to fall back to.
- * Adding a roaming setting meant editing all four and hoping; the key strings themselves were
- * duplicated between the array and the module that owned them.
+ * four places: a `PERSISTED_SETTINGS_KEYS` array, a private `const` per key in each
+ * `*-settings.ts`, a bespoke getter/setter pair beside it, and whatever the getter's `||` happened
+ * to fall back to. Adding a roaming setting meant editing all four and hoping; the key strings
+ * themselves were duplicated between the array and the module that owned them.
  *
  * Two properties of this table are load-bearing rather than tidy:
  *
- * 1.  **Scope is declared, not inferred.** {@link USER_SETTINGS} is DERIVED from it, so a setting
- *     roams because it says `scope: "user"` — not because someone remembered to add its key to a
- *     second list. `device` is the honest name for the rest: panel geometry and a palette's MRU
- *     describe *this window*, and a user with two windows open wants them to differ.
- * 2.  **A default is not a value.** The default is what a *reader* sees when nothing is stored; it
- *     is never itself stored. `getModel()` used to mask unset as `"gpt-4o"` with `||`, a form
- *     prefilled from it, and Save wrote the mask back — which is how an install whose owner had
- *     configured an entirely different provider was left holding `jx.ai.model: "gpt-4o"` and
- *     nothing else. {@link readSetting} and {@link readStoredSetting} in `kernel.ts` are two
- *     functions for exactly this reason.
+ * 1. **Scope is declared, not inferred.** {@link USER_SETTINGS} is DERIVED from it, so a setting roams
+ *    because it says `scope: "user"` — not because someone remembered to add its key to a second
+ *    list. `device` is the honest name for the rest: panel geometry and a palette's MRU describe
+ *    _this window_, and a user with two windows open wants them to differ.
+ * 2. **A default is not a value.** The default is what a _reader_ sees when nothing is stored; it is
+ *    never itself stored. `getModel()` used to mask unset as `"gpt-4o"` with `||`, a form prefilled
+ *    from it, and Save wrote the mask back — which is how an install whose owner had configured an
+ *    entirely different provider was left holding `jx.ai.model: "gpt-4o"` and nothing else.
+ *    {@link readSetting} and {@link readStoredSetting} in `kernel.ts` are two functions for exactly
+ *    this reason.
  *
  * @license MIT
  */
@@ -144,6 +144,17 @@ export const SETTINGS = {
     normalize: trimmed,
     scope: "user",
   },
+  /**
+   * Whether the Design rail draws the developer panels — Files and Packages (`specs/studio.md`
+   * §5.1). Unset, the default, keeps them off the rail; `settings/developer-panels.ts` reads it.
+   * Roams, for the reason `showIgnoredFiles` does: it is a way of working, not a window's.
+   */
+  developerPanels: {
+    default: "",
+    key: "jx.panels.developer",
+    normalize: trimmed,
+    scope: "user",
+  },
   cfAccountId: {
     default: "",
     key: "jx.cf.accountId",

package/src/settings/contributed-section.ts

@@ -49,8 +49,7 @@ import { resolveContextPointer } from "../services/context-resolver";
 import { deriveSecretEnvName } from "../services/data-service";
 import { validateProjectConfig } from "../services/jx-validate";
 import { notify } from "../services/notify";
-import { paneRegion } from "../ui/regions";
-import { paneOfContainer } from "../canvas/canvas-surface";
+import { SETTINGS_DIALOG_REGION } from "../surfaces/settings-dialog";
 import { mountContributedSurface } from "../surfaces/settings-contributed";
 
 import type { JsonSchema, SchemaFormContext } from "../ui/schema-form";
@@ -77,6 +76,12 @@ export interface SettingsContribution {
       | {
           ui?: Record<string, { control?: string; enum?: unknown }> | undefined;
           newEntry?: JsonObject | undefined;
+          /**
+           * What ONE entry of a map section is called, singular and lowercase ("content type",
+           * "table"), so the column offers "New content type" rather than "New Entry", a word that
+           * means a collection's item everywhere else in Studio. Defaults to "entry".
+           */
+          noun?: string | undefined;
         }
       | undefined;
   };
@@ -365,10 +370,17 @@ function sectionValue(key: string): JsonObject | null {
 
 // ─── Per-container mount ──────────────────────────────────────────────────────
 
-/* There is no `paneOfContainer` here. It moved to `canvas/canvas-surface.ts`, beside the other
-   "which pane is this about" answers, because it is not a settings idea: any stage content handed
-   only a host needs it, and `settings/general-settings.ts` and `settings/project-sections.ts` are
-   two more that do — both write a canvas mode, and both used to write the FOCUSED pane's. */
+/**
+ * A region under the settings dialog, which is where a contributed section is drawn (§17.1): its
+ * entry rows and its entry editor are named under `overlay.dialog:settings`, so a shot can crop one
+ * without a selector.
+ *
+ * @param {string} part
+ * @returns {string}
+ */
+function sectionRegion(part: string): string {
+  return `${SETTINGS_DIALOG_REGION}/${part}`;
+}
 
 /** One mounted section: its document, its two island hosts, and what it was last asked to draw. */
 interface SectionMount {
@@ -412,14 +424,39 @@ function say(record: SectionMount, value: string): void {
 
 // ─── Projection ───────────────────────────────────────────────────────────────
 
+/** The default name for one entry of a map section, when the contribution names none. */
+const DEFAULT_ENTRY_NOUN = "entry";
+
+/** The map column's words for one entry: the four places a map section names it. */
+export interface EntryWords {
+  newLabel: string;
+  newFieldLabel: string;
+  newPlaceholder: string;
+  emptyText: string;
+}
+
+/** The map column's words, from what the contribution calls one entry. */
+export function entryWords(noun?: string): EntryWords {
+  const word = noun?.trim().toLowerCase() || DEFAULT_ENTRY_NOUN;
+  const capitalised = `${word.charAt(0).toUpperCase()}${word.slice(1)}`;
+  // "an entry", "a table": the article English reads before the word's first sound, by its letter.
+  const article = /^[aeiou]/u.test(word) ? "an" : "a";
+  return {
+    emptyText: `Select ${article} ${word} or create one`,
+    newFieldLabel: `${capitalised} name`,
+    newLabel: `New ${word}`,
+    newPlaceholder: `${slugify(word)}-name`,
+  };
+}
+
 /** What the document draws right now, read from the store and this module's own state. */
 function project(record: SectionMount): ContributedView {
-  const { container, contribution, opts } = record;
+  const { contribution, opts } = record;
   const sectionKey = contribution.key;
   const title = contribution.title ?? sectionKey;
   const actionsState = opts.actions ? "slot" : "none";
-  const paneId = paneOfContainer(container);
-  const editorRegion = paneRegion(paneId, "editor");
+  const editorRegion = sectionRegion("editor");
+  const words = entryWords(contribution.settings.entry?.noun);
 
   if ((contribution.settings.layout ?? "form") !== "map") {
     return {
@@ -432,6 +469,7 @@ function project(record: SectionMount): ContributedView {
       newName: "",
       newState: "closed",
       title,
+      ...words,
     };
   }
 
@@ -445,7 +483,7 @@ function project(record: SectionMount): ContributedView {
     editorState: editing ? "editing" : "empty",
     entries: Object.keys(entries).map((name) => ({
       key: name,
-      region: paneRegion(paneId, `entry:${name}`),
+      region: sectionRegion(`entry:${name}`),
       selected: name === selected,
     })),
     entryName: record.echo ?? (editing ? selected : ""),
@@ -453,6 +491,7 @@ function project(record: SectionMount): ContributedView {
     newName: newEntryNames.get(sectionKey) ?? "",
     newState: newEntryOpen.has(sectionKey) ? "open" : "closed",
     title,
+    ...words,
   };
 }
 

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

@@ -11,8 +11,16 @@
  * **The markup left.** The section is the `settings-css-vars` surface
  * (`surfaces/settings-css-vars.json`), mounted by `surfaces/settings-css-vars.ts`; what is here is
  * the part that was always this module's — what a row shows, what an edit writes, and what a failed
- * write says. `renderCssVarsEditor` is unchanged as a contract: the registry hands a container to a
- * `render`, and this one mounts a document into it instead of rendering lit.
+ * write says. `renderCssVarsEditor` is unchanged as a contract: it is handed a container and mounts
+ * a document into it instead of rendering lit.
+ *
+ * **Its host is the Styles workspace's Variables view** (`style/variables-view.ts`, §7.1), the
+ * `tokens` editor of the `project.json` tab. It was Project Settings › CSS Variables, and its
+ * persistence did not change with the move: an edit is committed through the configuration
+ * chokepoint (`updateSiteConfig` → `commitProjectConfig`) as it is made, which writes the whole
+ * document, so an element style edit the Elements view left unsaved on the same tab is written too
+ * and the tab comes back clean. The view says so in as many words, rather than letting the Save
+ * button's state be the first the author hears of it.
  *
  * Three things it does NOT do, each on purpose:
  *
@@ -28,7 +36,7 @@
 
 import { isNumber, isString } from "@jxsuite/schema/guards";
 import { errorMessage } from "@jxsuite/schema/parse";
-import { notify } from "../services/notify";
+import { runActiveReported } from "../commands/run-reported";
 import { projectState } from "../store";
 import { getEffectiveMedia, updateSiteConfig } from "../site-context";
 import {
@@ -37,12 +45,15 @@ import {
   groupTokens,
   listTokenContexts,
   readTokenOverride,
-  tokenLabel,
   writeTokenOverride,
 } from "../style/project-styles";
 import { resolveTokenValue, toTokenRef, tokenRefName } from "../style/token-ref";
 import { pushProjectStylesToCanvas } from "../style/live-preview";
-import { renderCssVarsSurface } from "../surfaces/settings-css-vars";
+import {
+  renderCssVarsSurface,
+  revealCssVarsGroup,
+  revealCssVarsToken,
+} from "../surfaces/settings-css-vars";
 import { friendlyNameToVar } from "../utils/studio-utils";
 
 import type { JxStyle, ProjectConfig } from "@jxsuite/schema/types";
@@ -89,6 +100,8 @@ const ADD_OVERRIDE_ROW = { label: "Add override…", value: "" };
 interface Form {
   add: Partial<Record<TokenGroupId, { name: string; value: string }>>;
   error: string;
+  /** The token the Outline pointed this editor at ({@link focusCssVar}), or `null`. */
+  current: string | null;
 }
 
 const forms = new WeakMap<HTMLElement, Form>();
@@ -97,7 +110,7 @@ const forms = new WeakMap<HTMLElement, Form>();
 function form(container: HTMLElement): Form {
   let state = forms.get(container);
   if (!state) {
-    state = { add: {}, error: "" };
+    state = { add: {}, current: null, error: "" };
     forms.set(container, state);
   }
   return state;
@@ -197,11 +210,11 @@ function overrideRow(
   const current = readTokenOverride(rootStyle, context, token.name);
   return {
     ctx: context.name,
-    fieldLabel: `${token.label} in ${context.label}`,
+    fieldLabel: `${token.name} in ${context.label}`,
     id: `${token.name} ${context.name}`,
     kind: context.kind,
     label: context.label,
-    swatchLabel: `${token.label} in ${context.label}`,
+    swatchLabel: `${token.name} in ${context.label}`,
     swatchState: isColor ? "swatch" : "none",
     token: token.name,
     value: current === undefined ? "" : String(current),
@@ -217,6 +230,10 @@ function overrideRow(
  * in dark mode" is a question a palette is always answering. A token with no value is offered no
  * picker: writing an empty override is how one is CLEARED, so the affordance would be inert.
  *
+ * A row is NAMED by its custom property, `--color-accent`, never by a friendly rewording of it: the
+ * Outline beside the view lists the same `--name`, a `var()` reference spells it, and it is what
+ * CSS reads. The same goes for a reference chip, which names the property the value follows.
+ *
  * @param {ProjectToken} token
  * @param {TokenGroup} group
  * @param {JxStyle} rootStyle
@@ -228,6 +245,7 @@ function tokenRow(
   group: TokenGroup,
   rootStyle: JxStyle,
   declared: TokenContext[],
+  current: string | null,
 ): TokenRowView {
   const isColor = group.id === "color";
   const value = String(token.value);
@@ -240,25 +258,26 @@ function tokenRow(
   );
   const addable = value === "" ? [] : addableContexts(rootStyle, declared, token.name, shown);
   return {
-    addLabel: `Add an override for ${token.label}`,
+    addLabel: `Add an override for ${token.name}`,
     addOptions: [ADD_OVERRIDE_ROW, ...addable.map((c) => ({ label: c.label, value: c.name }))],
     addPick: "",
     addState: addable.length === 0 ? "none" : "shown",
-    chipLabel: refName === null ? "" : tokenLabel(refName),
+    chipLabel: refName ?? "",
     chipState: refName === null ? "none" : isColor && resolved !== undefined ? "swatch" : "plain",
     chipSwatch: resolved === undefined ? "" : String(resolved),
     chipTitle:
       refName === null
         ? ""
         : `${toTokenRef(refName)} → ${resolved === undefined ? "unresolved" : String(resolved)}`,
-    label: token.label,
+    current: token.name === current,
+    label: token.name,
     name: token.name,
     overrides: shown.map((context) => overrideRow(token, context, isColor, rootStyle)),
     overrideState: shown.length === 0 && addable.length === 0 ? "none" : "shown",
     previewFont: group.id === "font" ? value : "",
     previewState: group.id === "font" ? "font" : "none",
-    removeLabel: `Delete ${token.label}`,
-    swatchLabel: `${token.label} colour`,
+    removeLabel: `Delete ${token.name}`,
+    swatchLabel: `${token.name} color`,
     swatchState: isColor ? "swatch" : "none",
     value,
     ...well(isColor ? resolved : undefined, COLOR_INPUT_FALLBACK),
@@ -297,7 +316,9 @@ function view(container: HTMLElement): CssVarsView {
       nameLabel: `New ${group.title} name`,
       noticeState: group.id === "color" && !hasScheme ? "shown" : "none",
       title: group.title,
-      tokens: tokens.map((token) => tokenRow(token, group, rootStyle, declared)),
+      tokens: tokens.map((token) =>
+        tokenRow(token, group, rootStyle, declared, form(container).current),
+      ),
       valueHint: ADD_ROW_HINTS[group.id].value,
       valueLabel: `New ${group.title} value`,
     });
@@ -360,16 +381,17 @@ function addOverride(container: HTMLElement, token: string, ctx: string): void {
   commit(container);
 }
 
-/** Switch Settings to the Contexts section, saying so when the section registry will not load. */
-async function openContextsSection(): Promise<void> {
-  try {
-    const { setSettingsSection } = await import("./section-registry");
-    setSettingsSection("contexts");
-  } catch (error) {
-    notify.error(`Could not open Settings › Contexts — ${errorMessage(error)}`, {
-      source: "Settings",
-    });
-  }
+/**
+ * Open Project Settings on Contexts, where the color schemes and breakpoints this editor overrides
+ * per token are defined.
+ *
+ * Through the command rather than by writing the registry's section: the editor is hosted outside
+ * Settings (the Styles workspace's Variables view), so selecting a section of a dialog that is not
+ * open would change nothing the reader can see. A refusal is filed under "Styles", the workspace
+ * the editor lives in, as the Variables view's own button files it.
+ */
+function openContextsSection(): void {
+  void runActiveReported("settings.open", { section: "contexts" }, "Styles");
 }
 
 /**
@@ -395,11 +417,11 @@ function actions(container: HTMLElement): CssVarsActions {
        * point at the place a scheme is DEFINED. It used to define one itself — a button here
        * appended `'--dark': '(prefers-color-scheme: dark)'` to `$media` without ever using the word
        * breakpoint, which made this form the fourth and least discoverable definition site for a
-       * map whose other three lived in the wizard, Overview and Properties › Media. The lazy import
-       * breaks the css-vars-editor ↔ section-registry cycle.
+       * map whose other three lived in the wizard, Overview and Properties › Media. It goes there
+       * through `settings.open`, so the dialog opens on Contexts however this editor is hosted.
        */
       manageContexts: () => {
-        void openContextsSection();
+        openContextsSection();
       },
       removeToken: (name: string) => {
         delete style()[name];
@@ -453,3 +475,47 @@ function actions(container: HTMLElement): CssVarsActions {
 export function renderCssVarsEditor(container: HTMLElement): void {
   refresh(container);
 }
+
+/**
+ * Point the editor at one token: mark its row, scroll it into view and put the keyboard on its
+ * value. What a variable row in the Styles workspace's Outline asks for.
+ *
+ * A name this project does not declare is still recorded (it may be about to be added, or the
+ * Outline may be ahead of a write), and simply marks nothing. The flow only marks the row; bringing
+ * it on screen is the surface's (`revealCssVarsToken`), because only the adapter knows where the
+ * row it draws is.
+ *
+ * @param {HTMLElement} container
+ * @param {string | null} name A custom property, `--accent`, or `null` to mark none
+ * @param {{ reveal?: boolean }} [options] `reveal: false` marks the row without moving the keyboard
+ *   or the scroll position
+ */
+export function focusCssVar(
+  container: HTMLElement,
+  name: string | null,
+  options: { reveal?: boolean } = {},
+): void {
+  form(container).current = name;
+  refresh(container);
+  if (name === null || options.reveal === false) {
+    return;
+  }
+  revealCssVarsToken(container, name);
+}
+
+/**
+ * Point the editor at one group: bring its heading on screen, and with `add` put the keyboard on
+ * its Add row, the editor's own way of adding a variable. What a group heading and "Add variable"
+ * in the Styles workspace's Styles panel ask for.
+ *
+ * @param {HTMLElement} container
+ * @param {TokenGroupId} group
+ * @param {{ add?: boolean }} [options] `add: true` focuses the Add row's name field
+ */
+export function focusCssVarGroup(
+  container: HTMLElement,
+  group: TokenGroupId,
+  options: { add?: boolean } = {},
+): void {
+  revealCssVarsGroup(container, group, options.add === true);
+}

package/src/settings/developer-panels.ts

@@ -0,0 +1,43 @@
+/**
+ * The **Show developer panels** preference (`specs/studio.md` §5.1, §15).
+ *
+ * Off by default. A site author works in pages, templates, components and media, and the Site panel
+ * lists those by what they are; the Files tree and the Packages list are where a developer looks,
+ * so they are off the Design rail until the author asks for them. With the switch off both panels
+ * are still reachable by `view.setActivity` and the palette: the switch hides two rail buttons, not
+ * two capabilities.
+ *
+ * The value roams like the theme does (`SETTINGS.developerPanels`, scope `user`), and it is read
+ * through a REACTIVE mirror rather than straight from the kernel: the rail derives its groups
+ * inside an effect, and a kernel read is not tracked, so a flip in Preferences (or in another
+ * window) would otherwise leave the rail drawing the old answer until something unrelated repainted
+ * it.
+ *
+ * @docs studio/interface
+ */
+
+import { reactive } from "../reactivity";
+import { SETTINGS } from "../services/settings/definitions";
+import { onSettingsChanged, readStoredSetting, setSetting } from "../services/settings/kernel";
+
+/** The stored spelling of "on". Anything else, including unset, is off. */
+const ON = "true";
+
+const _state = reactive({ on: readStoredSetting(SETTINGS.developerPanels) === ON });
+
+onSettingsChanged((keys) => {
+  if (keys.includes(SETTINGS.developerPanels.key)) {
+    _state.on = readStoredSetting(SETTINGS.developerPanels) === ON;
+  }
+});
+
+/** Whether the developer panels (Files, Packages) are on the rail. Tracked when read in an effect. */
+export function developerPanelsShown(): boolean {
+  return _state.on;
+}
+
+/** Put the developer panels on the rail, or take them off. Persisted and roaming. */
+export function setDeveloperPanelsShown(show: boolean): void {
+  _state.on = show;
+  setSetting(SETTINGS.developerPanels, show ? ON : "");
+}