@jxsuite/studio 5.3.0 → 5.4.0

package/src/content/entry-commands.ts

@@ -28,7 +28,7 @@ import {
 } from "../format/format-host";
 import { notify } from "../services/notify";
 import { activeTab } from "../workspace/workspace";
-import { serializeJson } from "../files/json-layout";
+import { serializeJson } from "@jxsuite/schema/json-layout";
 import { invalidateReferenceEntries } from "../ui/form-controls";
 import { reloadDraftAwareGrids } from "../grid/sources/content-source";
 import { setIncludeDrafts } from "./draft-state";
@@ -64,7 +64,7 @@ async function seedText(collection: EntryCollection): Promise<string> {
     formatForPath(`untitled${collection.ext}`)?.name ??
     defaultContentFormat()?.name;
   if (collection.ext === ".json" || formatName === undefined) {
-    // The save serializer with no layout (`files/json-layout.ts`): a seed has no source text, and
+    // The save serializer with no layout (`@jxsuite/schema/json-layout`): a seed has no source text, and
     // This is what the formatter makes of one, newline included.
     return serializeJson(seed, null);
   }
@@ -190,9 +190,10 @@ export function contentCommands(): AnyCommand[] {
       when: (ctx) => ctx.project.open,
       enablement: () => creatableCollections().length > 0,
       undo: "project",
-      /* No `aiTool`, by §12.4's second deletion rule: `createEntry` awaits `createFileIn`, which
-         awaits the New File prompt for the name; a cancel resolves with nothing thrown. An optional
-         `name` argument that skips the prompt is the way back in, and is a UX call (issue 273). */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's second deletion rule: `createEntry` awaits
+         `createFileIn`, which awaits the New File prompt for the name; a cancel resolves with
+         nothing thrown. An optional `name` argument that skips the prompt is the way back in, and
+         is a UX call (issue 273). */
       run: async (_ctx, args) => {
         const names = creatableCollections();
         await createEntry(enumArg("content.newEntry", args, "collection", names));
@@ -210,8 +211,8 @@ export function contentCommands(): AnyCommand[] {
       group: "1_file",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      /* No `aiTool`, by §12.4's first deletion rule: this opens a surface; the model has
-         `open_document`. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's first deletion rule: this opens a surface;
+         the model has `open_document`. */
       run: async (_ctx, args) => {
         await openEntryEditor(stringArg("content.openEntry", args, "path"));
       },
@@ -233,12 +234,12 @@ export function contentCommands(): AnyCommand[] {
       when: (ctx) => ctx.document.open,
       enablement: () => activeEntryTab() !== null,
       undo: "document",
-      /* No `aiTool`, by §12.4's fourth deletion rule: the draft flag is ONE FIELD on the entry,
-         and the model already writes fields — `set_property` at the root path for a JSON entry
-         (`mutateDocumentField` is the same `set-key` at `[]`), `write_file` for a frontmatter one.
-         The state is reachable — `open_document` opens a collection file as readily as
-         `content.openEntry` does — so the reason is redundancy, not reach. Six lines to re-enter
-         should a task want the flag by name rather than by key. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's fourth deletion rule: the draft flag is ONE
+         FIELD on the entry, and the model already writes fields — `set_property` at the root path
+         for a JSON entry (`mutateDocumentField` is the same `set-key` at `[]`), `write_file` for a
+         frontmatter one. The state is reachable — `open_document` opens a collection file as
+         readily as `content.openEntry` does — so the reason is redundancy, not reach. Six lines to
+         re-enter should a task want the flag by name rather than by key. */
       run: (_ctx, args) => {
         const tab = activeEntryTab();
         if (!tab) {
@@ -259,7 +260,8 @@ export function contentCommands(): AnyCommand[] {
       group: "2_view",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      /* No `aiTool`, by §12.4's first deletion rule: a listing filter for a person. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's first deletion rule: a listing filter for a
+         person. */
       /*
        * Set the flag, then repaint what reads it.
        *

package/src/content/entry-editor.ts

@@ -1,6 +1,6 @@
 /// <reference lib="dom" />
 /**
- * The **Entry editor** — a content entry's fields, as a form, in a pane (§7.4, plan §9.2).
+ * The **Entry editor** (site-architecture.md §7.4): a content entry's fields, as a form, in a pane.
  *
  * Until now a markdown entry could be edited two ways and neither was its schema: the canvas edited
  * its BODY, and the Document Header card drew a field list from `panels/frontmatter-fields.ts`'s
@@ -179,7 +179,7 @@ function formContext(tab: Tab): SchemaFormContext {
  * Required fields this entry does not have.
  *
  * Deliberately keyed on ABSENCE, not emptiness. A seeded entry's `title: ""` is present and the
- * author has not done anything wrong yet, so §7.1 says not to paint it red; a required key that is
+ * author has not done anything wrong yet, so §16.5 says not to paint it red; a required key that is
  * missing from the file is a fact about the document, and saying so is the whole reason the form
  * knows the schema.
  */

package/src/content/entry-fields.ts

@@ -28,7 +28,7 @@
  * editing. That is the point.
  */
 
-import { cloneValue } from "@jxsuite/collab/ops";
+import { cloneValue } from "@jxsuite/schema/doc-ops";
 import { notePreviewOverlayEdit } from "../preview/preview-overlay";
 import { recordDocOp } from "../tabs/patch-ops";
 import { mutateUpdateFrontmatter, transactDoc } from "../tabs/transact";

package/src/editor/context-menu.ts

@@ -1,7 +1,7 @@
 /// <reference lib="dom" />
 // ─── Clipboard & Context Menu ─────────────────────────────────────────────────
 /**
- * The element context menu is a RENDERING of the command registry (UX-REDESIGN-PLAN §5.5).
+ * The element context menu is a RENDERING of the command registry (studio-ui-guidelines.md §12).
  *
  * This file used to hold an 18-item literal of `{ label, action, danger }` records — a fourth
  * hand-maintained copy of verbs that also exist in the toolbar, the block action bar and the
@@ -283,7 +283,7 @@ export function pasteStyles() {
     return;
   }
   const style = jsonClone(workspace.styleClipboard);
-  // Pasting one style onto six cards is the §6.5 example, and it is one undo step: `transactDoc`
+  // Pasting one style onto six cards is one decision and one undo step (§6.7): `transactDoc`
   // Records everything its callback mutates as a single history entry.
   transactDoc(tab, (t) => {
     for (const sel of targets) {
@@ -754,8 +754,8 @@ let _registry: CommandRegistry | null = null;
  */
 export function contextMenuRegistry(): CommandRegistry {
   /*
-   * THE APP'S REGISTRY, when there is one — §5.5's "the file keeps positioning and popover
-   * rendering only".
+   * THE APP'S REGISTRY, when there is one — a menu is a rendering of the records (§13), so this
+   * file keeps positioning and popover rendering only.
    *
    * The private registry below existed because the menu's context had to describe the RIGHT-CLICKED
    * node while the app's described the ambient selection. Those are the same node now:

package/src/editor/convert-to-component.ts

@@ -6,9 +6,10 @@
  * The naming question is `showPromptDialog` — one headline, one sentence, one field, one refusal —
  * which is exactly the shape this used to hand-render as an `sp-dialog-wrapper` of its own, down to
  * the Enter binding, the focus move and the select-all. That helper is already a document over the
- * kit (`src/surfaces/dialog.json`, studio-ui-guidelines §8.7), so the conversion here is a DELETION
- * rather than a second surface: a prompt authored beside the prompt would be a second answer to a
- * question Studio has settled once, and the two would drift the first time one of them was fixed.
+ * kit (`src/surfaces/dialog.json`, studio-ui-guidelines.md §8.7), so the conversion here is a
+ * DELETION rather than a second surface: a prompt authored beside the prompt would be a second
+ * answer to a question Studio has settled once, and the two would drift the first time one of them
+ * was fixed.
  *
  * What is left is the flow, which is all this module ever owned that mattered: what the default
  * name is, what makes a name usable, whether the document actually took the reference, and what is
@@ -25,7 +26,7 @@ import { transact } from "../tabs/transact";
 import { componentRegistry, computeRelativePath, loadComponentRegistry } from "../files/components";
 import { getPlatform } from "../platform";
 import { jsonClone } from "../utils/studio-utils";
-import { serializeJson } from "../files/json-layout";
+import { serializeJson } from "@jxsuite/schema/json-layout";
 import { notify } from "../services/notify";
 import { showPromptDialog } from "../ui/layers";
 import { validateComponentSlots } from "../services/cem-export";
@@ -106,7 +107,7 @@ export async function convertToComponent() {
   // Write component file and refresh registry
   try {
     const platform = getPlatform();
-    /* Through the save serializer (`files/json-layout.ts`) rather than `JSON.stringify`, so the new
+    /* Through the save serializer (`@jxsuite/schema/json-layout`) rather than `JSON.stringify`, so the new
        file lands in the formatter's layout with its trailing newline and the first save from its
        tab is a clean diff. No layout to carry: the subtree was lifted out of another document, and
        its record there is keyed by that document's pointers. */

package/src/editor/inline-edit.ts

@@ -67,9 +67,9 @@ export interface InlineAction {
    * REMOVED from the data, and the field stays only so an older `elements-meta.json` still parses.
    *
    * It held `"Cmd+B"` — a mac spelling, printed verbatim into every tooltip on every platform,
-   * which is the hardcoded-chord defect plan §5.3 exists to kill. The chord now lives on the
-   * `format.*` record (`panels/block-action-bar.ts`) and is formatted by the keymap's one
-   * formatter. Nothing reads this.
+   * which is the hardcoded-chord defect §13.3 exists to kill. The chord now lives on the `format.*`
+   * record (`panels/block-action-bar.ts`) and is formatted by the keymap's one formatter. Nothing
+   * reads this.
    */
   shortcut?: string;
 }

package/src/editor/shortcuts.ts

@@ -218,11 +218,11 @@ function selectFirstChild(): void {
 /**
  * Walk out of the selection by one rung.
  *
- * This is the Escape ladder (plan §5.3), and it is one rung short of complete: the block action bar
- * is not on the registry yet, so "Escape returns to the bar's selection" has nowhere to read focus
- * from. What ships is the rest of it — a nested selection selects its parent, the document element
- * clears — which replaces an Escape that always cleared regardless of depth and so threw away the
- * whole path to get out of one node.
+ * This is the Escape ladder (leave the block action bar, select the parent, clear), and it is one
+ * rung short of complete: the block action bar is not on the registry yet, so "Escape returns to
+ * the bar's selection" has nowhere to read focus from. What ships is the rest of it — a nested
+ * selection selects its parent, the document element clears — which replaces an Escape that always
+ * cleared regardless of depth and so threw away the whole path to get out of one node.
  */
 function selectParent(): void {
   const tab = activeTab.value;
@@ -255,7 +255,7 @@ function insertSiblingParagraph(): void {
 }
 
 /**
- * Duplicate the whole selection in ONE transaction, so a batch is one undo step (§6.5).
+ * Duplicate the whole selection in ONE transaction, so a batch is one undo step (§6.7).
  *
  * With one path selected this is `mutateDuplicateNode` on that path and nothing else — the batch
  * form calls the single form, it does not reimplement it.
@@ -354,12 +354,12 @@ function zoomBy(ctx: CommandContext, factor: number, redraw: () => void): void {
 // ─── Shell verbs ──────────────────────────────────────────────────────────────
 
 /**
- * The Command Bar's dock toggles, mapped onto the two docks that exist.
+ * The Command Bar's dock toggles, mapped onto the two side docks.
  *
- * `"bottom"` is the plan's Problems/Terminal dock (§3.1) and has no shell row yet, so it is absent
- * here and {@link toggleShellDock} routes ⌘J to the Assistant instead — which is no longer a dock at
- * all but the Inspector's fourth tab, and is still the third thing that chord could mean. When the
- * bottom dock lands it gets a row here and that branch goes away.
+ * `"bottom"` is absent: the Bottom dock (§16.3) is toggled by `shell.ts`'s own
+ * `view.toggleBottomDock` (⌘J), and no default record passes `"bottom"` to `toggleDock`. The
+ * `bottom` branch of {@link toggleShellDock}, which selects the Assistant (the Inspector's fourth
+ * tab), predates that dock.
  */
 const DOCK_FOR_COMMAND: Readonly<Record<Exclude<CommandDockId, "bottom">, DockId>> = {
   inspector: "right",
@@ -403,9 +403,9 @@ let zenRestore: Partial<Record<DockId, boolean>> | null = null;
 /**
  * Collapse every dock; the same chord puts them back exactly as they were.
  *
- * "Reversible by the same key" (plan §5.3) is the whole requirement, and it is why the previous
- * state is snapshotted rather than assumed: an author who had the assistant closed does not want
- * leaving Zen to open it.
+ * Being reversible by the same key is the whole requirement, and it is why the previous state is
+ * snapshotted rather than assumed: an author who had the assistant closed does not want leaving Zen
+ * to open it.
  */
 function toggleZen(): void {
   if (zenRestore) {
@@ -427,7 +427,7 @@ function toggleZen(): void {
 // ─── Region focus (F6) ────────────────────────────────────────────────────────
 
 /**
- * The F6 ring, in reading order: rail → navigator → pane → inspector → dock → status (plan §5.3).
+ * The F6 ring, in reading order: rail → navigator → pane → inspector → dock → status.
  *
  * `shell.focusRegion` has enumerated these six values since the shell record landed and nothing
  * could act on it, because there was no map from the enum to the DOM. `ui/regions.ts` is that map;
@@ -445,9 +445,9 @@ export const REGION_CYCLE: readonly FocusRegion[] = [
 /**
  * The next region in the ring that is actually on screen, or `null` when none is.
  *
- * Absent regions are SKIPPED rather than focused-and-lost: the bottom dock does not exist until P4
- * and a collapsed Navigator has no host, so a ring that did not skip would strand the caret every
- * second press. Pure, and injectable, so the walk is testable without a shell.
+ * Absent regions are SKIPPED rather than focused-and-lost: a closed Bottom dock has no region
+ * (§16.3) and a collapsed Navigator has no host, so a ring that did not skip would strand the caret
+ * every second press. Pure, and injectable, so the walk is testable without a shell.
  */
 export function nextRegion(
   current: FocusRegion,
@@ -518,7 +518,7 @@ function cycleRegion(direction: 1 | -1): void {
 // ─── Panel and inspector focus (⌘1–8, ⌘⇧1–4) ─────────────────────────────────
 
 /**
- * Toggle-FOCUS, not toggle-visible (plan §5.3).
+ * Toggle-FOCUS, not toggle-visible.
  *
  * ⌘1 from the canvas reveals Files and puts the caret in it; ⌘1 again — with Files already focused
  * — collapses the dock and hands the caret back to the pane. The distinction matters because the
@@ -992,6 +992,72 @@ const SELF_SCROLLING_MODES: ReadonlySet<string> = new Set([
   "settings",
 ]);
 
+/**
+ * Can a box between `target` and the stage still answer this wheel itself?
+ *
+ * Edit forwards every wheel to the page's scroller (see the branch below), which was the whole
+ * story while the stage cell held nothing but the page. It also holds the Document Header band now,
+ * a capped scroll container standing beside the scroller — and a `preventDefault` from an ANCESTOR
+ * listener cancels the native scroll of whatever the pointer is over, so a form taller than the cap
+ * could not be wheeled at all while the page scrolled underneath it instead. So the stage takes the
+ * wheel only when nothing inside it wants one: the walk stops at the stage cell, and it steps over
+ * the page's scroller because that box is what the forwarding is FOR — a wheel forwarded out of the
+ * cross-origin frame is dispatched on the cell itself and reaches no scrollable element on the way,
+ * and letting the browser scroll the page natively would chain out of it into the shell.
+ *
+ * @param {WheelEvent} e
+ * @param {HTMLElement} stage The cell the listener is on — the walk's upper bound, exclusive.
+ * @param {HTMLElement | null} pageScroller The box the Edit branch scrolls itself.
+ */
+function wheelBelongsInside(
+  e: WheelEvent,
+  stage: HTMLElement,
+  pageScroller: HTMLElement | null,
+): boolean {
+  const { target } = e;
+  let el: Element | null =
+    target instanceof Element ? target : ((target as Node | null)?.parentElement ?? null);
+  while (el && el !== stage) {
+    if (el instanceof HTMLElement && el !== pageScroller && canScrollBy(el, e.deltaX, e.deltaY)) {
+      return true;
+    }
+    el = el.parentElement;
+  }
+  return false;
+}
+
+/**
+ * Is `el` a scroll container with room left in the direction this wheel asks for?
+ *
+ * Both halves are load-bearing: a box already at the end of its range answers nothing, and left the
+ * wheel it would chain the scroll out to its ancestors — which is the shell, and exactly what the
+ * Edit branch's `preventDefault` is there to stop. The 1px slack is the subpixel one a fractional
+ * layout leaves at the end of a range. Overflow is read the way `ui/virtual-window.ts`'s scroller
+ * walk reads it, cheap test first: happy-dom performs no layout, so the sizes are 0 for every
+ * element and no test pays for a `getComputedStyle` it could not answer anyway.
+ *
+ * @param {HTMLElement} el
+ * @param {number} dx
+ * @param {number} dy
+ */
+function canScrollBy(el: HTMLElement, dx: number, dy: number): boolean {
+  const downRoom = dy > 0 && el.scrollTop < el.scrollHeight - el.clientHeight - 1;
+  const upRoom = dy < 0 && el.scrollTop > 0;
+  const acrossRoom =
+    (dx > 0 && el.scrollLeft < el.scrollWidth - el.clientWidth - 1) ||
+    (dx < 0 && el.scrollLeft > 0);
+  if (!downRoom && !upRoom && !acrossRoom) {
+    return false;
+  }
+  const style = getComputedStyle(el);
+  const scrolls = (overflow: string) =>
+    overflow === "auto" || overflow === "scroll" || overflow === "overlay";
+  return (
+    (downRoom || upRoom ? scrolls(style.overflowY) : false) ||
+    (acrossRoom ? scrolls(style.overflowX) : false)
+  );
+}
+
 /** The stage-context reader, published by {@link initShortcuts} for {@link installStageGestures}. */
 let _stageContext: StageContext | null = null;
 
@@ -1033,7 +1099,9 @@ export function installStageGestures(surface: CanvasSurface): () => void {
         /* The stage's own scroller, by the `part` the stage document draws it with — the same
            attribute every other consumer of the canvas's chrome now addresses it by. */
         const sc = canvasWrap.querySelector<HTMLElement>('[part="edit-canvas"]');
-        if (sc) {
+        /* …unless the pointer is over a box in this cell that scrolls itself — the Document Header
+           band, which Edit docks beside the scroller. See {@link wheelBelongsInside}. */
+        if (sc && !wheelBelongsInside(e, canvasWrap, sc)) {
           e.preventDefault();
           sc.scrollTop += e.deltaY;
           sc.scrollLeft += e.deltaX;

package/src/editor/slash-menu.ts

@@ -7,16 +7,17 @@
  * its markup, its ARIA and every value in its style — and this module is the decisions: what is on
  * offer, what the filter matches, which row is active, and what a pick does.
  *
- * **Why this is not `surfaces/menu.json`.** Every other Studio menu is that surface, and §12.5 says
- * a second list of actions is a defect — but a `jx-menu` owns DOM focus by contract: showing one
- * moves the caret onto its first row. This panel exists to filter a caret that is somewhere else,
- * inside the canvas's `contenteditable` and usually inside the canvas IFRAME, and every character
- * typed after the `/` has to keep landing there. A panel that takes the keyboard ends the
- * interaction it exists to serve. So the panel is a listbox that marks its active row and never
- * takes focus, and the keys are taken where they actually land — a document-level capturing
- * listener for this realm, and {@link handleSlashMenuKey} called straight across the bridge for the
- * other one. That listener is not a focus trap and cannot become one: it forwards four keys to the
- * same driver the bridge uses, and everything else keeps going to the caret.
+ * **Why this is not `surfaces/menu.json`.** Every other Studio menu is that surface, and
+ * studio-ui-guidelines.md §12.5 says a second list of actions is a defect — but a `jx-menu` owns
+ * DOM focus by contract: showing one moves the caret onto its first row. This panel exists to
+ * filter a caret that is somewhere else, inside the canvas's `contenteditable` and usually inside
+ * the canvas IFRAME, and every character typed after the `/` has to keep landing there. A panel
+ * that takes the keyboard ends the interaction it exists to serve. So the panel is a listbox that
+ * marks its active row and never takes focus, and the keys are taken where they actually land — a
+ * document-level capturing listener for this realm, and {@link handleSlashMenuKey} called straight
+ * across the bridge for the other one. That listener is not a focus trap and cannot become one: it
+ * forwards four keys to the same driver the bridge uses, and everything else keeps going to the
+ * caret.
  *
  * Light dismissal, the top layer and Escape-on-the-topmost-popover are the platform's, through the
  * `jx-popover` the document is rooted in; the `mousedown` capture listener that used to hand-roll

package/src/files/elements.ts

@@ -2,11 +2,10 @@
  * Elements.ts — what belongs in a document's (or a project's) `$elements`, decided once.
  *
  * `$elements` is the list of component modules a document may use. Three surfaces wrote it, each
- * with its own idea of what "already imported" means, and plan §11.2 names all three: the Packages
- * panel's cherry-pick checkboxes, its "Add component…" picker, and the automatic push when a
- * component is dropped on the canvas. "One `enableElement()` / `disableElement()` service behind
- * all three. Today the same array is written three ways with no shared UI and no shared
- * validation."
+ * with its own idea of what "already imported" means: the Packages panel's cherry-pick checkboxes,
+ * its "Add component…" picker, and the automatic push when a component is dropped on the canvas.
+ * §9.1.3 puts one `enableElement()` / `disableElement()` service behind all three, because the same
+ * array was written three ways with no shared UI and no shared validation.
  *
  * They really did disagree. The canvas drop matched a local component by `ref.endsWith(basename)`,
  * so `./components/card.json` counted `./vendor/card.json` as already imported and the drop

package/src/files/file-ops.ts

@@ -39,7 +39,7 @@ import type { CollabParser } from "../collab/collab-session";
 import { flushCanvasEdits } from "../canvas/iframe-host";
 import { flushPreviewOverlay } from "../preview/preview-overlay";
 import { serializeDocument } from "./serialize-document";
-import { parseJsonDocument } from "./json-layout";
+import { parseJsonDocument } from "@jxsuite/schema/json-layout";
 import {
   defaultContentFormat,
   formatByName,

package/src/files/files.ts

@@ -77,8 +77,8 @@ import { activeRegistry } from "../commands/active-registry";
 import { runActiveReported, runReported } from "../commands/run-reported";
 import { collectionOfPath } from "../content/entry-model";
 import { confirmFileDelete, parseSourceForPath, renamePromptMessage } from "./file-ops";
-import { parseJsonDocument } from "./json-layout";
-import type { JsonLayout } from "./json-layout";
+import { parseJsonDocument } from "@jxsuite/schema/json-layout";
+import type { JsonLayout } from "@jxsuite/schema/json-layout";
 import { invalidateUsages } from "../services/references";
 import {
   documentExtensions,
@@ -379,10 +379,10 @@ export async function openHomePage() {
 /**
  * Reopen the documents this project was last left with, or its home page if there are none.
  *
- * Plan §4.4, and P3's "Newly possible": **the session survives a relaunch.** Every one of the three
- * ways into a project — the `?project=` bootstrap, the PAL picker and a recent-project open — ended
- * at `openHomePage()`, so nine open documents, a split and the mode you were in were lost each
- * time. The per-project record's own interface said "session state grows into this shape".
+ * §14.8: **the session survives a relaunch.** Every one of the three ways into a project — the
+ * `?project=` bootstrap, the PAL picker and a recent-project open — ended at `openHomePage()`, so
+ * nine open documents, a split and the mode you were in were lost each time. The per-project
+ * record's own interface said "session state grows into this shape".
  *
  * ONE function for all three, because the three used to be three calls to `openHomePage` and this
  * is exactly the kind of behaviour that lands on two of them.
@@ -538,10 +538,10 @@ let _fileList: HTMLElement | null = null;
 /**
  * Every DRAWN row's element, by path.
  *
- * Held rather than queried, which is the §9.4 rule and, for a windowed list, the only correct
- * answer: the nodes are re-used for different files as the window slides, so a selector run a frame
- * later resolves to whichever file is standing there now. Entries whose element has left the
- * document are swept on the next projection.
+ * Held rather than queried, which is the studio-ui-guidelines.md §9.4 rule and, for a windowed
+ * list, the only correct answer: the nodes are re-used for different files as the window slides, so
+ * a selector run a frame later resolves to whichever file is standing there now. Entries whose
+ * element has left the document are swept on the next projection.
  */
 const _fileRowEls = new Map<string, HTMLElement>();
 /** The scroll watch that repaints the tree as its scroller moves. */
@@ -1668,9 +1668,9 @@ function fileMenuRows(entry: { name: string; path: string; type: string }): Menu
  *
  * The KIT menu, not a popover of this module's own: `openMenu()` owns the panel, the roving focus,
  * the typeahead, the light dismissal and Escape, and it is the answer this shell already settled on
- * (§8.4). What went with the `sp-popover` it replaces is the hand-written clamp — a `ref` that
- * measured the panel a frame after it opened and moved it back inside the viewport — because the
- * kit does that for every menu instead of this one doing it for itself.
+ * (studio-ui-guidelines.md §8.4). What went with the `sp-popover` it replaces is the hand-written
+ * clamp — a `ref` that measured the panel a frame after it opened and moved it back inside the
+ * viewport — because the kit does that for every menu instead of this one doing it for itself.
  */
 function showFileContextMenu(path: string, x: number, y: number): void {
   const row = fileRowAt(path);
@@ -2235,7 +2235,10 @@ async function deleteFile(
 export interface OpenFileOpts {
   /** Which pane. Defaults to the focused one. */
   paneId?: string;
-  /** Open as a disposable preview tab (§4.3) — browsing rather than committing. */
+  /**
+   * Open as a disposable preview tab — browsing rather than committing
+   * (`docs/studio/interface/tabs.md#preview-and-pinned-documents`).
+   */
   preview?: boolean;
   /** False leaves the keyboard where it is. Defaults to true. */
   focus?: boolean;
@@ -2489,7 +2492,7 @@ export async function reloadFileInTab(path: string) {
  * Contribute the Files panel.
  *
  * `level: "project"` because it WRITES project files — create, rename, delete, move. It reads the
- * focused document only to highlight a row, and principle 3 files a surface by what it writes.
+ * focused document only to highlight a row, and §13.2 files a surface by what it writes.
  */
 export function registerFilesPanel(): void {
   registerPanel({
@@ -2520,8 +2523,9 @@ const FILE_ACTIONS: FilesPanelActions = {
   },
   openProject: () => {
     /* The DECLARED command, run through the registry — never a second opener of this surface's own
-       (§12.5). It is the one the ⌘O chord, the palette and the status bar's PROJECT field already
-       run, and it is the only one that knows about the picker modal and the "new window" target. */
+       (studio-ui-guidelines.md §12.5). It is the one the ⌘O chord, the palette and the status
+       bar's PROJECT field already run, and it is the only one that knows about the picker modal
+       and the "new window" target. */
     void runActiveReported("project.open", undefined, "Files");
   },
   refresh: () => {

package/src/files/serialize-document.ts

@@ -19,7 +19,7 @@ import {
   formatSerialize,
   loadFormats,
 } from "../format/format-host";
-import { serializeJson } from "./json-layout";
+import { serializeJson } from "@jxsuite/schema/json-layout";
 import type { Tab } from "../tabs/tab";
 
 /**

package/src/format/convert-file.ts

@@ -27,8 +27,8 @@ import {
   stringProperty,
 } from "../commands/command-args";
 import { convertTargetExtensions, convertTargets } from "./format-choices";
-import { parseJsonDocument, serializeJson } from "../files/json-layout";
-import type { JsonLayout } from "../files/json-layout";
+import { parseJsonDocument, serializeJson } from "@jxsuite/schema/json-layout";
+import type { JsonLayout } from "@jxsuite/schema/json-layout";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 
 /** What a conversion will do, resolved in full before the reader is asked to confirm it. */
@@ -99,7 +99,7 @@ async function writeDocument(
 ): Promise<string> {
   const merged = { ...frontmatter, ...document };
   if (targetExt === ".json") {
-    /* The same serializer a save uses (`files/json-layout.ts`), with NO layout: the source was
+    /* The same serializer a save uses (`@jxsuite/schema/json-layout`), with NO layout: the source was
        markdown or CSV, so there is no JSON text whose line breaks could be kept. Every object
        expands and every short array stays on one line — which is exactly what the repository's
        formatter would make of `JSON.stringify` output, so the converted file needs no reformat and
@@ -497,8 +497,8 @@ export function fileFormatCommands(): AnyCommand[] {
       // Nothing restores it: the file has moved and its references have been rewritten with it.
       // The confirmation carrying the count is what stands in for an undo.
       undo: "none",
-      /* No `aiTool`, by §12.4's second deletion rule: `run` awaits a confirm dialog the person
-         answers. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's second deletion rule: `run` awaits a
+         confirm dialog the person answers. */
       run: async (_ctx, args: Record<string, unknown>) => {
         const target = typeof args.format === "string" ? args.format : undefined;
         await convertFile(

package/src/github/github-auth-status.ts

@@ -0,0 +1,107 @@
+/**
+ * The GitHub credential's state — whether one exists, where it lives, and how to forget it.
+ *
+ * Split out of `github-auth.ts` because a launcher's PAL-init bundle needs exactly one thing from
+ * that module before Studio itself has loaded: {@link hydrateGithubToken}, so the accounts pane can
+ * say "signed in" on the first frame (`desktop/src/boot.ts`). `github-auth.ts` also pulls in
+ * `notify`, `../ui/layers` and the device-flow dialog surface for the actual sign-in UI — none of
+ * which a bundler drops just because only this module's exports are imported, so a launcher that
+ * imported the combined file got a second, independent copy of Lit's runtime alongside the one the
+ * studio bundle it shares a window with already loads (`packages/desktop/src/init.ts`, the
+ * "Multiple versions of Lit loaded" warning). This file has no UI dependency at all, so a launcher
+ * that imports only this gets none of that.
+ *
+ * `github-auth.ts` re-exports everything here, so every other caller in Studio is unaffected.
+ */
+
+/// <reference lib="dom" />
+
+const STORAGE_KEY = "jx_github_token";
+
+/**
+ * The desktop launcher's RFC 8252 sign-in, when this build is running inside one.
+ *
+ * Launcher-only, like `updater` and `windowControls`, and reached the same way — a loopback
+ * redirect needs a loopback server, which a page in a browser does not have.
+ */
+export interface NativeGithubAuth {
+  signIn: (force?: boolean) => Promise<{ token: string }>;
+  signOut: () => Promise<{ ok: boolean }>;
+  status: () => Promise<{ stored: boolean }>;
+}
+
+export function nativeAuth(): NativeGithubAuth | null {
+  return (
+    (globalThis as unknown as { __jxPlatform?: { githubAuth?: NativeGithubAuth } }).__jxPlatform
+      ?.githubAuth ?? null
+  );
+}
+
+/**
+ * The token the desktop store handed us this session.
+ *
+ * On the desktop the token at rest is a `0600` file in the user's config directory, **not**
+ * `localStorage` — so it is not readable by script in the webview between sessions, and it does not
+ * survive in a place a stray extension or a copied profile can reach. Holding it in a module
+ * variable is what keeps {@link getGithubToken} synchronous for its callers.
+ */
+let nativeToken: string | null = null;
+
+/** Whether the desktop store holds a token, as of the last time it was asked. */
+let nativeStored = false;
+
+/** Record the token a native sign-in just returned — {@link authenticateGithub}'s own setter. */
+export function setNativeToken(token: string | null): void {
+  nativeToken = token;
+}
+
+/**
+ * Record that the desktop's credential store does (or does not) hold a token.
+ *
+ * The launcher calls this once at startup. It carries a **boolean, not the token**: the accounts
+ * pane only needs to know whether one exists, and handing the webview a credential it has not been
+ * asked to use is the exposure the 0600 store exists to remove. When a sign-in does happen the
+ * token arrives through {@link setNativeToken} and lives in memory for that session.
+ *
+ * @param {boolean} stored
+ */
+export function hydrateGithubToken(stored: boolean): void {
+  nativeStored = stored;
+}
+
+/**
+ * Whether a GitHub credential exists, wherever it lives.
+ *
+ * Separate from {@link getGithubToken} because the two questions genuinely differ on the desktop: a
+ * token can be stored on disk and not yet in this session's memory, and the accounts pane asks
+ * "signed in?" while rendering — synchronously — where an API caller asks for the credential itself
+ * and can await it.
+ *
+ * @returns {boolean}
+ */
+export function githubTokenStored(): boolean {
+  return nativeToken !== null || nativeStored || localStorage.getItem(STORAGE_KEY) !== null;
+}
+
+/** Where the credential this build would use actually lives, for text that says so. */
+export function githubTokenLocation(): "desktop" | "browser" {
+  return nativeAuth() ? "desktop" : "browser";
+}
+
+export function getGithubToken(): string | null {
+  return nativeToken ?? localStorage.getItem(STORAGE_KEY);
+}
+
+export function clearGithubToken(): void {
+  nativeToken = null;
+  nativeStored = false;
+  localStorage.removeItem(STORAGE_KEY);
+  // Fire-and-forget: the accounts pane's revoke is synchronous, and a store that failed to forget
+  // The token is not something the user can act on from there.
+  void nativeAuth()
+    ?.signOut()
+    .catch(() => {});
+}
+
+/** The key {@link authenticateGithub}'s device flow writes the browser-stored token under. */
+export { STORAGE_KEY };