@jxsuite/studio 2.0.1 → 2.1.0

package/src/settings/preferences-keymap.ts

@@ -0,0 +1,270 @@
+/// <reference lib="dom" />
+/**
+ * Preferences-keymap.ts — the user's keyboard layer: where it is kept, and what it refuses.
+ *
+ * `specs/studio.md` §15 rule 2 says the Keyboard sheet is a PROJECTION of the command registry —
+ * the same `shortcutReference()` that generates `docs/studio/interface/shortcuts.md` — so it cannot
+ * drift from the app. Rebinding must not break that, which is why nothing here writes to a command
+ * record. A rebinding is one entry in an override map that `keymap.setOverrides` lays over the
+ * declared chords; `keymap.declaredFor(id)` keeps answering what the app ships with, and a reset is
+ * the removal of an entry rather than the restoration of a value this module remembered.
+ *
+ * Three refusals, in the order they are checked, because each one is a different mistake:
+ *
+ * 1. **Not a chord.** Modifier-only, or a string no keyboard produces.
+ * 2. **A bare printable key.** `s` bound globally fires while you are typing your name into a field:
+ *    the dispatcher is one `document` keydown listener, and only some scopes are narrow enough to
+ *    hold the key back. So a letter, digit or punctuation needs a modifier; ↑, Esc, F5 and their
+ *    kind do not, because nothing types them.
+ * 3. **Already taken.** The chord is claimed by another command in a scope that can be live at the
+ *    same instant as this one — `keymap.overlappingScopes`. In the SAME scope that is exactly the
+ *    condition `keymap.add` throws on at registration (the check that caught ⌘W); across scopes it
+ *    is the quieter version of the same loss, because every dispatch stack is `[engine, "global"]`
+ *    and a narrow binding silently shadows a global one for as long as that engine has focus. Two
+ *    engine scopes (`caret` and `grid`, say) never share a stack and may hold one chord each for
+ *    ever, so that is allowed — refusing it would forbid the shadowing ladder its whole purpose.
+ *    Here it must not throw and must not silently win: the result NAMES the command holding the
+ *    chord AND where that command is live, so the sheet can say who has it and offer to show that
+ *    row.
+ *
+ * Storage is `localStorage`, the same place the chrome theme lives, and it is read defensively at
+ * every layer: unavailable storage, invalid JSON, a non-array value and an unparseable chord all
+ * degrade to "this author has no override for that command" rather than to a keyboard that throws
+ * during boot.
+ */
+
+import { normalizeChord, overlappingScopes, parseChord } from "../commands/keymap";
+import type { KeybindingOverrides } from "../commands/keymap";
+import type { KeyScope } from "../commands/levels";
+import type { AnyCommand, CommandRegistry } from "../commands/registry";
+
+/** Where the user's layer is kept. One key, one JSON object of `id → chords`. */
+export const KEYBINDINGS_STORAGE_KEY = "jx.keybindings";
+
+/** Keys that type nothing, and so may be bound without a modifier. */
+const UNMODIFIED_KEYS = new Set([
+  "escape",
+  "enter",
+  "tab",
+  "backspace",
+  "delete",
+  "arrowup",
+  "arrowdown",
+  "arrowleft",
+  "arrowright",
+  "home",
+  "end",
+  "pageup",
+  "pagedown",
+  "insert",
+]);
+
+const FUNCTION_KEY = /^f([1-9]|1\d|2[0-4])$/;
+
+/**
+ * Where each scope's chords are live, in words a refusal can end with.
+ *
+ * A cross-scope conflict is otherwise unreadable: "⌘S is already Save" is baffling when the sheet
+ * is showing you a canvas command and Save is a global one. The scope is the missing half of the
+ * sentence, and it is also the half that tells the author whether they care.
+ */
+const SCOPE_WHERE: Readonly<Record<KeyScope, string>> = {
+  global: "everywhere",
+  canvas: "on the canvas",
+  caret: "while text is being edited",
+  grid: "in the data grid",
+  code: "in the code editor",
+  dock: "in the panels",
+  palette: "in the command palette",
+};
+
+/** The command that already holds a chord — everything the refusal needs to name it. */
+export interface RebindConflict {
+  /** Canonical chord, as the user just pressed it. */
+  chord: string;
+  scope: KeyScope;
+  /** The holder. */
+  commandId: string;
+  /** The holder's title, so the refusal names an action rather than an id. */
+  title: string;
+}
+
+/**
+ * What a rebind did.
+ *
+ * A refusal always carries a `reason` fit to show a person, and carries `conflict` when the reason
+ * is another command — the case the sheet turns into "show me that one".
+ */
+export type RebindResult = { ok: true } | { ok: false; reason: string; conflict?: RebindConflict };
+
+/** Whether a canonical chord may be bound at all. Modifier-less printable keys may not. */
+export function isBindableChord(chord: string): boolean {
+  let parsed;
+  try {
+    parsed = parseChord(chord);
+  } catch {
+    // Modifier-only, or empty: `parseChord` is the one place that decides what a chord is.
+    return false;
+  }
+  if (parsed.mod || parsed.ctrl || parsed.alt) {
+    return true;
+  }
+  // Shift alone is not enough: ⇧A is how a capital A is typed.
+  return UNMODIFIED_KEYS.has(parsed.key) || FUNCTION_KEY.test(parsed.key);
+}
+
+function readRaw(): string {
+  try {
+    return globalThis.localStorage?.getItem(KEYBINDINGS_STORAGE_KEY) ?? "";
+  } catch {
+    // Storage unavailable (private mode): every command keeps the chord it declared.
+    return "";
+  }
+}
+
+/** Every chord in one stored entry, canonicalised — or `null` if any of them is not a chord. */
+function canonicalise(chords: unknown): string[] | null {
+  if (!Array.isArray(chords)) {
+    return null;
+  }
+  const canonical: string[] = [];
+  for (const chord of chords as unknown[]) {
+    if (typeof chord !== "string") {
+      return null;
+    }
+    try {
+      canonical.push(normalizeChord(chord));
+    } catch {
+      // A stored string that is not a chord: drop the whole entry rather than half of it.
+      return null;
+    }
+  }
+  return canonical;
+}
+
+/**
+ * The stored layer, validated.
+ *
+ * Nothing here trusts the store: it is a JSON blob a user can hand-edit and an older release can
+ * have written. An entry that does not survive validation is dropped, and the command keeps its
+ * declared chord — which is the only failure mode that leaves the app usable.
+ */
+export function loadKeybindingOverrides(): Map<string, string[]> {
+  const layer = new Map<string, string[]>();
+  const raw = readRaw();
+  if (!raw) {
+    return layer;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    // Corrupt store: the defaults are the whole keymap.
+    return layer;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return layer;
+  }
+  for (const [id, chords] of Object.entries(parsed as Record<string, unknown>)) {
+    const canonical = canonicalise(chords);
+    if (canonical) {
+      layer.set(id, canonical);
+    }
+  }
+  return layer;
+}
+
+function store(layer: KeybindingOverrides): void {
+  try {
+    if (layer.size === 0) {
+      globalThis.localStorage?.removeItem(KEYBINDINGS_STORAGE_KEY);
+      return;
+    }
+    globalThis.localStorage?.setItem(
+      KEYBINDINGS_STORAGE_KEY,
+      JSON.stringify(Object.fromEntries(layer)),
+    );
+  } catch {
+    // Storage unavailable — the rebinding is live in this window and is not remembered.
+  }
+}
+
+/**
+ * Lay the stored overrides over a registry's keymap.
+ *
+ * Called from `registerPreferencesCommands`, which is the bootstrap's one contact point with
+ * Preferences. Because the layer lives INSIDE the keymap, applying it before the rest of the
+ * bootstrap has finished registering is safe: a record registered afterwards is indexed against the
+ * layer that is already there.
+ */
+export function applyKeybindingOverrides(registry: CommandRegistry): void {
+  registry.keymap.setOverrides(loadKeybindingOverrides());
+}
+
+/**
+ * Bind `command` to `chord`, or say why not.
+ *
+ * Rebinding a command back to the chord it declared REMOVES the override rather than pinning the
+ * current default: the point of a layer is that a command whose default moves in a later release
+ * moves with it unless the author asked for something else.
+ */
+export function rebindCommand(
+  registry: CommandRegistry,
+  command: AnyCommand,
+  chord: string,
+): RebindResult {
+  let canonical: string;
+  try {
+    canonical = normalizeChord(chord);
+  } catch {
+    return { ok: false, reason: "That is not a shortcut — hold a key as well as the modifiers." };
+  }
+  if (!isBindableChord(canonical)) {
+    return {
+      ok: false,
+      reason:
+        `${registry.keymap.format(canonical)} would fire while you type. ` +
+        "Add ⌘, Ctrl or Alt, or use a key that types nothing.",
+    };
+  }
+  const scope: KeyScope = command.keyScope ?? "global";
+  // Every scope this one can share a dispatch stack with, not just its own: a chord claimed in an
+  // Overlapping scope is one of the two commands going quiet, and which one it is depends only on
+  // Which is narrower. `resolveChord` walks the list in order, so the same scope is named first.
+  const held = registry.keymap.resolveChord(canonical, overlappingScopes(scope));
+  if (held && held.commandId !== command.id) {
+    const holder = registry.get(held.commandId);
+    const title = holder?.title ?? held.commandId;
+    const where = held.scope === scope ? "" : `, which is live ${SCOPE_WHERE[held.scope]}`;
+    return {
+      ok: false,
+      reason: `${registry.keymap.format(canonical)} is already ${title}${where}.`,
+      conflict: { chord: canonical, commandId: held.commandId, scope: held.scope, title },
+    };
+  }
+  const next = new Map(registry.keymap.overrides());
+  const declared = registry.keymap.declaredFor(command.id);
+  if (declared.length === 1 && declared[0] === canonical) {
+    next.delete(command.id);
+  } else {
+    next.set(command.id, [canonical]);
+  }
+  registry.keymap.setOverrides(next);
+  store(next);
+  return { ok: true };
+}
+
+/**
+ * Drop the override on `commandId`, restoring what the registry declares.
+ *
+ * @returns Whether there was one to drop, so a caller does not repaint over nothing.
+ */
+export function resetKeybinding(registry: CommandRegistry, commandId: string): boolean {
+  const next = new Map(registry.keymap.overrides());
+  if (!next.delete(commandId)) {
+    return false;
+  }
+  registry.keymap.setOverrides(next);
+  store(next);
+  return true;
+}

package/src/settings/project-sections.ts

@@ -0,0 +1,260 @@
+/// <reference lib="dom" />
+/**
+ * The three Project Settings sections the document adds — Extensions, Deploy and Raw JSON.
+ *
+ * They live together because each is a small, direct view of ONE `project.json` key and none of
+ * them owns a dialog, a picker or a schema form: `extensions` (an array of package names),
+ * `build.adapter` (one enum), and the file itself.
+ *
+ * **Extensions had no UI at all** — plan §9.2's last row — despite `site-context.ts` carrying a
+ * dedicated branch to react to the array changing. Adding or removing a package here is therefore
+ * the first way to turn an extension on from inside Studio, and the chokepoint's own
+ * `refreshExtensionSurfaces()` re-reads the formats and the contributed sections afterwards, so the
+ * section list beside this one updates without a reload.
+ *
+ * **Raw JSON does not open a second editor.** It shows what is on disk and hands the author to the
+ * Code editor over the SAME tab — one document, three editors (§9.3), so switching to the text and
+ * back keeps one undo stack instead of forking two.
+ *
+ * @docs studio/projects/settings
+ */
+
+import { html, render as litRender, nothing } from "lit-html";
+import { errorMessage } from "@jxsuite/schema/parse";
+import { projectState, updateUi } from "../store";
+import { serializeProjectConfig } from "../tabs/project-config";
+import { tabOfContainer } from "../canvas/canvas-surface";
+import { updateSiteConfig } from "../site-context";
+
+import type { ProjectConfig } from "@jxsuite/schema/types";
+
+/** The mode the Code editor draws under — `tabs/tab.ts`'s `EDITOR_KIND_BY_MODE` maps it to `code`. */
+const CODE_MODE = "source";
+
+/**
+ * The last failed write per rendered section container.
+ *
+ * Keyed by container so two mounted copies (and two tests) never share a message — the same shape
+ * `general-settings.ts` uses, and for the same reason: these sections save on change, so a silent
+ * rejection would read as "my edit just vanished".
+ */
+const errors = new WeakMap<HTMLElement, string>();
+
+/** Drop a parked error and re-render. */
+function clearError(container: HTMLElement): void {
+  errors.delete(container);
+}
+
+/** The error line for a section, if its last write failed. */
+function errorLine(container: HTMLElement) {
+  const message = errors.get(container);
+  return message === undefined
+    ? nothing
+    : html`<p class="settings-field-error" role="alert">${message}</p>`;
+}
+
+/**
+ * Persist a patch, surfacing the rejection instead of swallowing it.
+ *
+ * `updateSiteConfig` rejects on a failed write and the chokepoint has already filed the Problem, so
+ * all that is left here is to keep the form honest about what is on disk.
+ *
+ * @param {HTMLElement} container
+ * @param {Partial<ProjectConfig>} patch
+ * @param {() => void} rerender
+ */
+async function persist(
+  container: HTMLElement,
+  patch: Partial<ProjectConfig>,
+  rerender: () => void,
+): Promise<void> {
+  try {
+    await updateSiteConfig(patch);
+    clearError(container);
+  } catch (error) {
+    errors.set(container, `Could not save project.json — ${errorMessage(error)}`);
+  }
+  rerender();
+}
+
+/** The live project configuration, or an empty one before a project is open. */
+function config(): ProjectConfig {
+  return (projectState?.projectConfig ?? {}) as ProjectConfig;
+}
+
+// ─── Extensions ───────────────────────────────────────────────────────────────
+
+/** Pending package name per container, so typing survives the section re-rendering. */
+const pendingExtension = new WeakMap<HTMLElement, string>();
+
+/**
+ * The `extensions` array, as a list you can add to and remove from.
+ *
+ * @param {HTMLElement} container
+ */
+export function renderExtensionsSection(container: HTMLElement): void {
+  const rerender = () => renderExtensionsSection(container);
+  const extensions = config().extensions ?? [];
+  const pending = pendingExtension.get(container) ?? "";
+
+  /* Both handlers re-read rather than closing over the render's values. Typing updates the pending
+     name WITHOUT a re-render (re-rendering per keystroke would fight the field's own value), so a
+     closed-over `pending` would always be whatever it was when the section was last drawn — which
+     is "" on the first add. */
+  const add = () => {
+    const name = (pendingExtension.get(container) ?? "").trim();
+    const current = config().extensions ?? [];
+    if (!name || current.includes(name)) {
+      return;
+    }
+    pendingExtension.delete(container);
+    void persist(container, { extensions: [...current, name] }, rerender);
+  };
+
+  const remove = (name: string) => {
+    const current = config().extensions ?? [];
+    void persist(container, { extensions: current.filter((e) => e !== name) }, rerender);
+  };
+
+  const tpl = html`
+    <div class="settings-section">
+      <h3 class="settings-section-title">Extensions</h3>
+      <p class="settings-field-desc">
+        Packages this project loads. An extension can contribute formats, elements, data connectors
+        — and settings sections of its own, which appear in the list beside this one.
+      </p>
+      ${errorLine(container)}
+      <div class="settings-list-panel">
+        ${
+          extensions.length === 0
+            ? html`<div class="settings-empty-state">No extensions.</div>`
+            : extensions.map(
+                (name) => html`
+                  <div class="settings-row">
+                    <span class="settings-row-name">${name}</span>
+                    <sp-action-button
+                      size="xs"
+                      quiet
+                      title=${`Remove ${name}`}
+                      @click=${() => remove(name)}
+                    >
+                      <sp-icon-delete slot="icon"></sp-icon-delete>
+                    </sp-action-button>
+                  </div>
+                `,
+              )
+        }
+        <div class="settings-inline-form">
+          <sp-textfield
+            size="s"
+            class="settings-extension-name"
+            placeholder="@scope/package"
+            .value=${pending}
+            @input=${(e: Event) => {
+              pendingExtension.set(container, (e.target as HTMLInputElement).value);
+            }}
+            @keydown=${(e: KeyboardEvent) => {
+              if (e.key === "Enter") {
+                add();
+              }
+            }}
+          ></sp-textfield>
+          <sp-action-button size="s" @click=${add}>Add</sp-action-button>
+        </div>
+      </div>
+    </div>
+  `;
+
+  litRender(tpl, container);
+}
+
+// ─── Deploy ───────────────────────────────────────────────────────────────────
+
+/** The build adapters `@jxsuite/compiler` ships. One enumeration, shared with New Project. */
+export const BUILD_ADAPTERS: readonly { value: string; label: string }[] = [
+  { label: "Static", value: "static" },
+  { label: "Bun", value: "bun" },
+  { label: "Node", value: "node" },
+  { label: "Cloudflare Workers", value: "cloudflare-workers" },
+  { label: "Cloudflare Pages", value: "cloudflare-pages" },
+];
+
+/**
+ * Where the project is built for, and what it is built with.
+ *
+ * The adapter moved off Overview: Overview says what the site IS, and the adapter is a fact about
+ * where it SHIPS — the same split §2 principle 5 applies to Contexts.
+ *
+ * @param {HTMLElement} container
+ */
+export function renderDeploySection(container: HTMLElement): void {
+  const rerender = () => renderDeploySection(container);
+  const current = config().build?.adapter || "static";
+
+  const onAdapterChange = (e: Event) => {
+    void persist(
+      container,
+      { build: { ...config().build, adapter: (e.target as HTMLInputElement).value } },
+      rerender,
+    );
+  };
+
+  const tpl = html`
+    <div class="settings-section">
+      <h3 class="settings-section-title">Deploy</h3>
+      ${errorLine(container)}
+      <div class="settings-field">
+        <label class="settings-field-label">Platform Adapter</label>
+        <p class="settings-field-desc">
+          What the site is built for. Static writes plain files; the others emit a server entry for
+          that runtime.
+        </p>
+        <sp-picker
+          size="s"
+          label="Platform Adapter"
+          class="settings-build-adapter"
+          .value=${current}
+          @change=${onAdapterChange}
+        >
+          ${BUILD_ADAPTERS.map(
+            (adapter) => html`<sp-menu-item value=${adapter.value}>${adapter.label}</sp-menu-item>`,
+          )}
+        </sp-picker>
+      </div>
+    </div>
+  `;
+
+  litRender(tpl, container);
+}
+
+// ─── Raw JSON ─────────────────────────────────────────────────────────────────
+
+/**
+ * `project.json` as it is written, and the way into editing it as text.
+ *
+ * The serialisation is the chokepoint's own (`serializeProjectConfig`), so what this shows is what
+ * a save writes — not a second pretty-printer that would disagree with the file by an indent.
+ *
+ * @param {HTMLElement} container
+ */
+export function renderRawJsonSection(container: HTMLElement): void {
+  const tpl = html`
+    <div class="settings-section">
+      <h3 class="settings-section-title">Raw JSON</h3>
+      <p class="settings-field-desc">
+        The whole of <code>project.json</code>, as it is saved. Editing it as code opens the same
+        document in the Code editor — one undo stack, one dirty flag.
+      </p>
+      <pre class="settings-raw-json">${serializeProjectConfig(config())}</pre>
+      <sp-action-button
+        size="s"
+        class="settings-edit-as-code"
+        @click=${() => updateUi(tabOfContainer(container), "canvasMode", CODE_MODE)}
+      >
+        Edit as code
+      </sp-action-button>
+    </div>
+  `;
+
+  litRender(tpl, container);
+}

package/src/settings/section-registry.ts

@@ -0,0 +1,169 @@
+/**
+ * The Project Settings section registry, and which of its sections the document is showing.
+ *
+ * `registerSettingsSection` is a **preserved public contract** (specs/extensions.md §9.1): an
+ * extension's `project` class declares a `$studio.settings` block and `settings/extension-sections`
+ * turns it into one of these records. P6 moved Project Settings out of a modal and into a document
+ * in the pane; the registry did not move with it, because a section is a contribution to
+ * CONFIGURATION, not to a dialog. Splitting it out is what lets the host be replaced without the
+ * contribution point being touched.
+ *
+ * **This module holds no renderer and imports nothing.** That is load-bearing rather than tidy:
+ * `panels/settings-pane.ts` is reached from `canvas/canvas-render.ts`, so anything this module
+ * imports becomes part of the canvas's import graph. The section RENDERERS are registered by
+ * `settings/settings-document.ts`, which the app loads when it registers its commands.
+ *
+ * **What is requested and what is displayed are two variables, and unregistering touches neither.**
+ * The modal had one, and its `unregisterSettingsSection` reset it to `"general"` — which is half of
+ * the deep-link race P6 exists to close. The contribution sync unregisters stale keys before it
+ * registers fresh ones, so a section merely being REFRESHED took the caller's requested section
+ * down with it, silently, after the awaited readiness promise had already resolved. Here a request
+ * outlives its section going away and is satisfied the moment the key comes back.
+ */
+
+/** A Project Settings section: an inner-nav entry plus a renderer for the content area. */
+export interface SettingsSection {
+  key: string;
+  label: string;
+  /** Nav icon name (reserved for future nav treatments). */
+  icon?: string | undefined;
+  /** Sort position — lower orders render higher in the inner nav. */
+  order: number;
+  render: (container: HTMLElement) => void;
+}
+
+/** Where a settings document lands when nobody named a section. */
+export const DEFAULT_SETTINGS_SECTION = "overview";
+
+const sections = new Map<string, SettingsSection>();
+
+const listeners = new Set<() => void>();
+
+/**
+ * Tell every subscriber something changed.
+ *
+ * A `Set` tolerates deletion during its own iteration, so a listener that unsubscribes itself (the
+ * pane host, on unmount) is safe without copying.
+ */
+function announce(): void {
+  for (const listener of listeners) {
+    listener();
+  }
+}
+
+/**
+ * Redraw the settings document — for a change this module cannot see, such as a command selecting
+ * an entry inside the section that is already on screen.
+ */
+export function notifySettingsDocument(): void {
+  announce();
+}
+
+/**
+ * Subscribe to everything that changes what the settings document draws: the section set (an
+ * extension registering or going away) and the chosen section. Returns the unsubscribe.
+ *
+ * @param {() => void} listener
+ * @returns {() => void}
+ */
+export function onSettingsDocumentChanged(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+// ─── Registration ─────────────────────────────────────────────────────────────
+
+/**
+ * Register (or replace) a settings section.
+ *
+ * @param {SettingsSection} section
+ */
+export function registerSettingsSection(section: SettingsSection): void {
+  sections.set(section.key, section);
+  announce();
+}
+
+/**
+ * Remove a registered section — used when a descriptor-contributed section's extension is disabled
+ * (see ./extension-sections). Built-ins are never unregistered.
+ *
+ * @param {string} key
+ */
+export function unregisterSettingsSection(key: string): void {
+  if (sections.delete(key)) {
+    announce();
+  }
+}
+
+/** Registered sections sorted by order (registration order breaks ties). */
+export function sortedSettingsSections(): SettingsSection[] {
+  return [...sections.values()].toSorted((a, b) => a.order - b.order);
+}
+
+/** Every registered section key, built-ins and contributions alike, in display order. */
+export function settingsSectionKeys(): string[] {
+  return sortedSettingsSections().map((section) => section.key);
+}
+
+/**
+ * One section by key, or `undefined`.
+ *
+ * @param {string} key
+ * @returns {SettingsSection | undefined}
+ */
+export function settingsSection(key: string): SettingsSection | undefined {
+  return sections.get(key);
+}
+
+// ─── Which section is on screen ───────────────────────────────────────────────
+
+/** The section the last caller ASKED for, kept until it is satisfied. */
+let _requested: string | null = null;
+
+/** The section the document is drawing. Only a nav click and a satisfied request move it. */
+let _displayed = DEFAULT_SETTINGS_SECTION;
+
+/**
+ * The section key the document should render right now.
+ *
+ * A pending request wins as soon as its section exists. Otherwise the displayed one, and — when
+ * that has been unregistered too — the first section there is, so the content area is never blank
+ * because of bookkeeping.
+ *
+ * @returns {string}
+ */
+export function settingsDocumentSection(): string {
+  if (_requested !== null && sections.has(_requested)) {
+    _displayed = _requested;
+    _requested = null;
+    return _displayed;
+  }
+  if (sections.has(_displayed)) {
+    return _displayed;
+  }
+  return settingsSectionKeys()[0] ?? _displayed;
+}
+
+/**
+ * Show a section. A nav click satisfies itself immediately; a deep link to a section that has not
+ * registered yet is remembered until it does.
+ *
+ * @param {string} key
+ */
+export function setSettingsSection(key: string): void {
+  if (sections.has(key)) {
+    _displayed = key;
+    _requested = null;
+  } else {
+    _requested = key;
+  }
+  announce();
+}
+
+/** Forget the chosen section — the project-close and test hook. */
+export function resetSettingsDocumentState(): void {
+  _requested = null;
+  _displayed = DEFAULT_SETTINGS_SECTION;
+}