@jxsuite/studio 4.0.0 → 5.0.0

package/src/shell/tree.ts

@@ -15,29 +15,7 @@
 
 import { html, render as litRender } from "lit-html";
 import type { TemplateResult } from "lit-html";
-
-/**
- * Render a frame template into `host`, surviving a host that was emptied since the last mount.
- *
- * `textContent = ""` (or `innerHTML = ""`) removes the comment nodes lit uses as a ChildPart's
- * markers but leaves lit's private `_$litPart$` reference behind, so the next render reuses a part
- * whose markers are detached from the DOM and throws — or, worse, quietly renders nothing. Test
- * fixtures clear the body between cases constantly, and the app does the same thing to a stage on
- * every mode transition; `canvas/canvas-render.ts`'s hardClearCanvasWrap carries the same ejection
- * for the same reason.
- *
- * Mounting is a one-shot, so ejecting unconditionally costs nothing and makes it idempotent.
- */
-function mountInto(host: ParentNode, tpl: TemplateResult): void {
-  /* Both halves, in this order. Clearing alone leaves lit's private part reference pointing at
-     comment markers that are no longer in the document, so the next render throws or paints
-     nothing. Ejecting alone leaves the OLD nodes in place and lit starts a fresh part beside them,
-     so a second mount produces two frames rather than one. */
-  (host as HTMLElement).textContent = "";
-  // @ts-expect-error -- _$litPart$ is lit's private render-part marker, not in the DOM types
-  delete (host as HTMLElement)["_$litPart$"];
-  litRender(tpl, host as HTMLElement);
-}
+import { mountShellSurface } from "../surfaces/shell";
 
 /**
  * The four overlay layers that `ui/layers.ts` renders into, in stacking order.
@@ -74,82 +52,59 @@ export function overlayLayers(): TemplateResult {
 }
 
 /**
- * The application frame: the Spectrum theme wrapper, the app grid, and the four overlay layers.
+ * Render the frame and the overlay layers into `host`, in that order.
  *
- * The theme's three attributes are BINDINGS rather than literals, and that is not decoration. A
- * literal lives in the template lit clones with `importNode`, and cloning a registered custom
- * element makes the DOM fire `attributeChangedCallback` before its constructor has run — Spectrum's
- * Theme then reaches for `_provideSystemContext` and finds nothing. A binding is applied after the
- * element exists. `shell.ts` overwrites `color` on the first theme effect anyway, so the literal
- * was never the source of truth.
+ * `#app` and its cells are `src/surfaces/shell.json`, mounted through the runtime — the frame is a
+ * Jx document, which is the whole point of the migration. The four overlay LAYERS are still a lit
+ * template, and deliberately: they belong to `ui/layers.ts` rather than to the frame, and they move
+ * when that module does. Both land in the theme wrapper, `#app` first, exactly as before.
  *
- * Region ids are stamped HERE. They used to live in a selector-to-id map in `ui/regions.ts`, whose
- * comment gave the reason plainly — these were "bare `<div id>` in index.html, so it cannot stamp
- * itself". A template can, so the map is gone and the id sits on the element it names.
- */
-export function shellTree(): TemplateResult {
-  return html`
-    <div id="app">
-      <div id="toolbar" data-jx-region="commandbar"></div>
-      <!-- The PANE GRID (studio.md §18.1). One cell per pane, each holding that pane's own strip,
-             jump bar, chrome layer and stage — the four surfaces that used to be flat siblings of
-             THIS grid, which is to say application rows that only ever described one pane. There is
-             nothing to see here in markup: panels/pane-grid.ts reconciles the cells against
-             workspace.panes, because how many there are is a fact about the workspace and a
-             single div can only ever be one of them. -->
-      <div id="pane-grid"></div>
-      <div id="activity-bar" data-jx-region="rail"></div>
-      <div id="left-panel" data-jx-region="navigator"></div>
-      <div id="resize-left" class="resize-handle"></div>
-      <!-- The Bottom dock (⌘J). It sits in the PANE's column, under the stage and above the
-             status bar, so opening it never narrows the Navigator or the Inspector (studio.md §12
-             region ⑪). Its handle resizes on the other axis; panels/bottom-dock.ts stamps
-             dock.bottom on this host while it is open, and nothing while it is closed. -->
-      <div id="resize-bottom" class="resize-handle resize-handle-row"></div>
-      <div id="bottom-dock"></div>
-      <div id="resize-right" class="resize-handle"></div>
-      <!-- The Inspector dock. Four tabs — Content · Style · Logic · Assistant (studio.md §12
-             region ⑨) — all inside this one host. -->
-      <div id="right-panel" data-jx-region="inspector"></div>
-      <!-- The app's only status channel: announce what lands in it (studio.md §12 region ⑫). -->
-      <div id="statusbar" role="status" aria-live="polite" data-jx-region="statusbar"></div>
-    </div>
-    ${overlayLayers()}
-  `;
-}
-
-/**
- * Render {@link shellTree} into `host`.
- *
- * The entry calls this once, before `initShellRefs()`. Tests call it instead of pasting an
- * approximation of the frame — which is the whole reason it is a function.
+ * **This is now asynchronous, and every caller must await it.** `store.ts`'s `initShellRefs` reads
+ * five of these cells out of the document on the line after the mount, and `ui/panel-resize.ts`
+ * reads three more; a mount that has not settled hands each of them a null. The runtime renders one
+ * microtask after insertion and waits for the kit to be defined first, so there is no synchronous
+ * spelling of this to fall back on.
  *
  * @param host Where the frame goes. Defaults to the document body.
  */
-export function mountShellTree(host: ParentNode = document.body): void {
-  mountInto(themeHost(host), shellTree());
+export async function mountShellTree(host: ParentNode = document.body): Promise<void> {
+  const root = shellRoot(host);
+  /* The same clear-and-eject the lit mount did, for the same two reasons — a fixture that empties
+     the host leaves lit's part marker pointing at comment nodes that are gone, and ejecting without
+     clearing makes a second mount paint a second frame beside the first — and now for a third: the
+     document mount APPENDS, so without this a remount leaves two `#app`s and every `querySelector`
+     silently picks the stale one. */
+  root.textContent = "";
+  // @ts-expect-error -- _$litPart$ is lit's private render-part marker, not in the DOM types
+  delete root["_$litPart$"];
+  await mountShellSurface(root);
+  /* After the frame, so the layers are its siblings in the order they always were. lit's `render`
+     manages only the range between its own markers, so appending here leaves `#app` alone. */
+  litRender(overlayLayers(), root);
 }
 
 /**
- * The Spectrum theme wrapper, created once and reused.
+ * The element the frame and its layers are mounted into, created once and reused.
  *
- * It is NOT part of {@link shellTree}, and the reason is a real constraint rather than taste. lit
- * instantiates a template by cloning it with `importNode`, and cloning a registered custom element
- * enqueues its `attributeChangedCallback` before the constructor body has run — Spectrum's Theme
- * then reaches for a field it assigns in that body and throws. `createElement` runs the constructor
- * first, so the attributes are safe to set afterwards.
+ * This was `<sp-theme>`, and the wrapper is all that survives it. Spectrum's tokens were declared
+ * ON that element and reached only its descendants, so the frame had to be inside one or every
+ * `var(--spectrum-*)` in the chrome fell to a hex fallback. The kit declares every token at `:root`
+ * and `applyChromeTheme()` stamps the scheme on `<html>`, so nothing here themes anything
+ * (studio-ui-guidelines.md §1.1).
  *
- * `shell.ts` rewrites `color` on the first theme effect, so the value here is only the first frame.
+ * It stays because the mount needs a container it OWNS. `src/studio.ts` calls `mountResizeEdges()`
+ * one line before this, which appends its own container to `document.body` — so the clear-and-eject
+ * above cannot be aimed at the host without taking the four resize edges with it. A plain div is
+ * also what makes the layers' `position: fixed` mean the viewport: an element that established a
+ * containing block here would move all four of them, silently.
  */
-function themeHost(host: ParentNode): HTMLElement {
-  const existing = host.querySelector?.("sp-theme");
+function shellRoot(host: ParentNode): HTMLElement {
+  const existing = host.querySelector?.("#shell-root");
   if (existing) {
     return existing as HTMLElement;
   }
-  const theme = document.createElement("sp-theme");
-  theme.setAttribute("color", "dark");
-  theme.setAttribute("scale", "medium");
-  theme.setAttribute("system", "spectrum");
-  (host as HTMLElement).append(theme);
-  return theme;
+  const root = document.createElement("div");
+  root.id = "shell-root";
+  (host as HTMLElement).append(root);
+  return root;
 }

package/src/shell.ts

@@ -227,7 +227,7 @@ export function isBottomTabId(value: unknown): value is BottomTabId {
   return typeof value === "string" && (BOTTOM_TAB_IDS as readonly string[]).includes(value);
 }
 
-/** The Studio chrome's Spectrum theme — the `color` attribute on `<sp-theme>`. */
+/** The Studio chrome's themes — the `data-theme` stamp on `<html>` (studio-ui-guidelines.md §1.1). */
 export const CHROME_THEMES = ["light", "dark"] as const;
 
 export type ChromeTheme = (typeof CHROME_THEMES)[number];
@@ -264,6 +264,16 @@ export interface ShellGit {
   loading: boolean;
   error: string | null;
   diffState: GitDiffState | null;
+  /**
+   * Bumped whenever the working tree may have moved under an open comparison.
+   *
+   * A comparison is two texts read once, so nothing about it notices a save. That was invisible
+   * while the artboards merely drew two documents; with change marks on them, the tint and the
+   * count go stale the moment the author edits the file they are reviewing — and a review loop
+   * whose marks lie is worse than one with no marks. This is the one input both holders of a
+   * comparison watch: the panel's `diffState` re-reads, and a Diff lens's memo re-issues.
+   */
+  rev: number;
   logEntries: GitLogEntry[] | null;
   /** "changes" | "history" — the panel's sub-tab. */
   subTab: string;
@@ -325,7 +335,7 @@ export interface ShellState {
    * COMMAND (`view.setBottomTab`) is what refuses an undeclared id, at the one door callers use.
    */
   bottomTab: string;
-  /** The Studio chrome's Spectrum theme. One of {@link CHROME_THEMES}. */
+  /** The Studio chrome's theme. One of {@link CHROME_THEMES}. */
   theme: ChromeTheme;
   docks: Record<DockId, DockState>;
   /**
@@ -368,8 +378,9 @@ const PROJECT_STORAGE_PREFIX = "jx-studio-project::";
 /**
  * The chrome theme Studio wakes up in.
  *
- * `index.html` hard-codes `color="dark"` on `<sp-theme>` so the first paint has a theme before this
- * module evaluates; the default here has to agree with it or the shell flashes.
+ * `styles/tokens.css` carries the kit's DARK values as its hex fallbacks, so the first paint has a
+ * theme before this module evaluates; the default here has to agree with them or the shell
+ * flashes.
  */
 const DEFAULT_THEME: ChromeTheme = "dark";
 
@@ -454,6 +465,17 @@ interface PersistedDocks {
 /** An even split — what the grid opens on, and what a double-click on the splitter restores. */
 export const DEFAULT_PANE_SPLIT = 0.5;
 
+/**
+ * The supported range for {@link ShellState.paneSplit}, and the ONE place it is written down.
+ *
+ * It was written three times — the read clamp, the write clamp, and the drag's own bounds — which
+ * is three chances to disagree about one number. The surface now hands the same two values to
+ * `jx-split` as its `min` and `max`, so the element, the writer and the reader all bound the split
+ * alike, and a splitter can no longer report a position the store would refuse to keep.
+ */
+export const PANE_SPLIT_MIN = 0.2;
+export const PANE_SPLIT_MAX = 0.8;
+
 /**
  * Coerce a stored split into the supported range.
  *
@@ -462,12 +484,14 @@ export const DEFAULT_PANE_SPLIT = 0.5;
  * one caller that has to be defended.
  */
 function clampPaneSplit(value: unknown): number {
-  return typeof value === "number" && value >= 0.2 && value <= 0.8 ? value : DEFAULT_PANE_SPLIT;
+  return typeof value === "number" && value >= PANE_SPLIT_MIN && value <= PANE_SPLIT_MAX
+    ? value
+    : DEFAULT_PANE_SPLIT;
 }
 
 /** Move the splitter. Clamped, and the one writer every control routes through. */
 export function setPaneSplit(value: number): void {
-  shell.paneSplit = Math.min(0.8, Math.max(0.2, value));
+  shell.paneSplit = Math.min(PANE_SPLIT_MAX, Math.max(PANE_SPLIT_MIN, value));
 }
 
 /** Read the persisted dock record, tolerating absent/corrupt storage. */
@@ -488,6 +512,7 @@ function freshGit(): ShellGit {
     lastUpdated: null,
     loading: false,
     logEntries: null,
+    rev: 0,
     status: null,
     subTab: "changes",
   };
@@ -942,7 +967,7 @@ export function resetLayout(deps: LayoutDeps): void {
  * The Monaco theme that goes with a chrome theme.
  *
  * Monaco paints its own chrome from its own registry and cannot read a CSS custom property, so it
- * is the one surface in the app the Spectrum theme does not reach. Both editors used to be created
+ * is the one surface in the app the chrome theme does not reach. Both editors used to be created
  * with a literal `"vs-dark"`, which is how a light Studio kept a black code view in the middle of
  * it. `"vs"` is Monaco's stock light theme — the counterpart of the `"vs-dark"` already in use, not
  * a new palette to maintain.
@@ -952,11 +977,11 @@ export function monacoTheme(theme: ChromeTheme = shell.theme): string {
 }
 
 /**
- * Project the theme record onto `<sp-theme>` and onto Monaco.
+ * Project the theme record onto the document and onto Monaco.
  *
- * The predecessor was a raw `document.querySelector("sp-theme")?.setAttribute(...)` inside the
- * automation hook — a presentation poke no user could make and no surface could read back. It is a
- * shell input like the docks, so it lives on the record and is applied by the same effect.
+ * The predecessor was a raw `document.querySelector(...)?.setAttribute(...)` inside the automation
+ * hook — a presentation poke no user could make and no surface could read back. It is a shell input
+ * like the docks, so it lives on the record and is applied by the same effect.
  *
  * `setTheme` is global to Monaco and repaints every live editor, so an open code view follows the
  * switch rather than waiting to be remounted. It goes through {@link loadedMonaco} — never
@@ -964,13 +989,16 @@ export function monacoTheme(theme: ChromeTheme = shell.theme): string {
  * session that has not opened one. With no editor loaded there is nothing to repaint, and the
  * `theme:` option each mount passes reads the record when it eventually happens.
  *
- * The `data-theme` stamp on `<html>` exists for ONE rule, and only because `<html>` is an ancestor
- * of `<sp-theme>`: the backdrop in `styles/tokens.css` cannot read a `--spectrum-*` token from up
- * there (see that file's note on why the semantic layer is not on `:root`), so it painted a fixed
- * near-black behind every theme. An attribute is the only channel that reaches it.
+ * **The `data-theme` stamp is now the ONLY channel, and that is the removal rather than a
+ * simplification of it.** There were two: this stamp, and a `color` attribute on the `sp-theme`
+ * element the frame was wrapped in. Two writers meant a theme could half-apply — `color="light"`
+ * over a colour fragment Spectrum had never been given adopted no palette at all, so the setting
+ * moved the backdrop and nothing else, which is how Light once shipped as a switch that did
+ * nothing. The kit declares every colour as a `light-dark()` pair on `:root` and reads the scheme
+ * off this attribute, so the stamp now paints the whole chrome and there is no second thing to
+ * forget.
  */
 export function applyChromeTheme(): void {
-  document.querySelector("sp-theme")?.setAttribute("color", shell.theme);
   document.documentElement.dataset.theme = shell.theme;
   loadedMonaco()?.editor.setTheme(monacoTheme());
 }
@@ -1281,14 +1309,8 @@ export function shellViewCommands(deps: ShellCommandDeps): AnyCommand[] {
       group: "4_docks",
       requires: "an open project",
       when: projectOpen,
-      aiTool: {
-        description:
-          "Show one of the Navigator panels (Files, Search, Source Control, Languages, Outline, " +
-          "Page, Data, Packages, Insert) and open the Navigator dock if it is closed. Languages is " +
-          "the translation-parity grid, and it exists only in a project that declares two or more " +
-          "locales. Problems is a Bottom dock tab — use show_bottom_tab for it.",
-        name: "show_navigator_panel",
-      },
+      /* No `aiTool`: application-level, which `register()` refuses to project — an application verb
+         acts on the editor, which the model cannot see (§12.4, chrome). */
       run: (_ctx, args) => {
         const tab = enumArg("view.setActivity", args, "tab", NAVIGATOR_PANEL_IDS);
         // The record's own `when`, asked here because `enablement` cannot see an argument — the
@@ -1392,12 +1414,7 @@ export function shellViewCommands(deps: ShellCommandDeps): AnyCommand[] {
       level: "application",
       menus: ["palette"],
       group: "4_docks",
-      aiTool: {
-        description:
-          "Show one of the Bottom dock's tabs (Problems, Diff, Logic, Activity) and open the " +
-          "Bottom dock if it is closed.",
-        name: "show_bottom_tab",
-      },
+      /* No `aiTool`: application-level chrome, refused at registration (§12.4). */
       run: (_ctx, args) => {
         const tab = enumArg("view.setBottomTab", args, "tab", BOTTOM_TAB_IDS);
         // The record's own `when`, asked here because `enablement` cannot see an argument — the
@@ -1460,12 +1477,7 @@ export function shellViewCommands(deps: ShellCommandDeps): AnyCommand[] {
       group: "4_layouts",
       requires: "an open project",
       when: projectOpen,
-      aiTool: {
-        description:
-          "Adopt one of the project's named layouts (Write, Design, Build, Ship, or one the user " +
-          "saved): its Navigator panel, its dock widths and visibility, and its Inspector tab.",
-        name: "set_layout",
-      },
+      /* No `aiTool`: application-level chrome, refused at registration (§12.4). */
       run: (_ctx, args) => {
         applyLayout(stringArg("view.setLayout", args, "layout"), deps);
       },