@jxsuite/studio 2.0.1 → 2.1.0

package/src/site-context.ts

@@ -4,12 +4,16 @@
  *
  * When a project has a project.json, its $media and style cascade into every file. File-level
  * definitions merge on top (file wins on conflict).
+ *
+ * @docs framework/site/i18n
  */
 
-import { projectState, requireProjectState, setProjectState } from "./store";
+import { projectState } from "./store";
 import { getPlatform } from "./platform";
-import { setWorkspaceProject, workspace } from "./workspace/workspace";
+import { commitProjectConfig } from "./tabs/project-config";
 
+import { resolveI18n } from "@jxsuite/schema/locale";
+import type { ResolvedI18n } from "@jxsuite/schema/locale";
 import type {
   JxElement,
   JxHeadEntry,
@@ -133,6 +137,27 @@ export function getEffectiveHead(docHead?: JxHeadEntry[]) {
   return merged;
 }
 
+/**
+ * The project's resolved locales, or null when it declares none.
+ *
+ * The resolution is `@jxsuite/schema/locale`'s own — literally the function the compiler runs — so
+ * a tag Studio offers is a tag the build accepts, and the two cannot drift into disagreeing about
+ * what `EN-us` means or which locales exist.
+ *
+ * Errors are dropped here on purpose. Every helper in this file answers a render, and a render has
+ * nowhere to put a sentence; `settings/locales-section.ts` is where a malformed tag is refused with
+ * words, before it can reach the file.
+ *
+ * Called at render time rather than cached: `projectState` is a plain module-level binding replaced
+ * wholesale on a project switch, so a cached answer would outlive the project it described.
+ *
+ * @returns {ResolvedI18n | null}
+ */
+export function getEffectiveLocales(): ResolvedI18n | null {
+  const config = projectState?.projectConfig;
+  return config ? resolveI18n(config).i18n : null;
+}
+
 // ─── Layout resolution ──────────────────────────────────────────────────────
 
 const layoutCache = new Map<string, JxMutableNode>();
@@ -259,26 +284,26 @@ function fillSlots(
 }
 
 /**
- * Update the project's project.json with a partial patch and persist to disk. A patch touching
- * `extensions` invalidates the format/extensions caches and refreshes the editor's per-project
- * schemas plus the contributed settings sections — the enabled-extension surface just changed.
+ * Merge a partial patch into the project's configuration and persist it.
+ *
+ * The patch-shaped door onto `tabs/project-config.ts` — the single chokepoint every configuration
+ * write goes through. It used to serialize and write `project.json` itself, which is how this file
+ * came to hold one of the two serializations in play, and how ten call sites came to change the
+ * file that defines the project with no history behind them.
+ *
+ * **It still rejects.** `settings/general-settings.ts` and `settings/contexts-section.ts` catch the
+ * rejection and park it on the control that caused it (§7.1's inline tier), and that is the right
+ * treatment for a field the author is looking at. The chokepoint ALSO files the failure as a
+ * Problem, because the eight other sites reach this through `void updateSiteConfig(...)` and used
+ * to drop it on the floor.
  *
- * @param {Partial<ProjectConfig>} patch - Fields to merge into the current projectConfig
+ * @param {Partial<ProjectConfig>} patch - Fields to merge into the current projectConfig; a value
+ *   of `undefined` clears the key.
+ * @throws {unknown} The platform's rejection, when the write fails.
  */
 export async function updateSiteConfig(patch: Partial<ProjectConfig>) {
-  const platform = getPlatform();
-  const config = {
-    ...requireProjectState().projectConfig,
-    ...patch,
-  } as ProjectConfig;
-  await platform.writeFile("project.json", JSON.stringify(config, null, 2));
-  setProjectState({ ...requireProjectState(), projectConfig: config });
-  setWorkspaceProject(workspace.projectRoot, config);
-  if ("extensions" in patch) {
-    const { loadFormats, refreshExtensionUi, refreshFormats } =
-      await import("./format/format-host");
-    refreshFormats();
-    void loadFormats();
-    refreshExtensionUi(platform);
+  const result = await commitProjectConfig(patch);
+  if (!result.ok) {
+    throw result.error;
   }
 }

package/src/state.ts

@@ -1,57 +1,22 @@
-/// <reference lib="dom" />
 /**
- * State.js — Builder state model and mutation API
+ * Document paths, the tree walk over them, and the project record.
  *
- * All state changes go through named mutation functions. State is immutable — every mutation
- * produces a new state object. History is a linear stack of { document, selection } snapshots.
+ * A `JxPath` addresses one node from the document root: `[]` is the root itself, `["children", 0]`
+ * its first child, `["children", 0, "children", 2]` that child's third. Every module that points at
+ * a node — selection, hover, the layers tree, a patch — spells it this way, which is why the
+ * comparison and ancestry predicates live here rather than beside any one of them.
  *
- * Path convention: [] = root document ['children', 0] = first child ['children', 0, 'children', 2]
- * = third child of first child
+ * The editable document and its history belong to a TAB (`tabs/tab.ts`) and its session lives on
+ * the workspace; nothing here holds mutable document state. The one exception is `projectState`,
+ * which outlives every document because it describes the folder they all come from.
  */
 
 import type { ProjectState } from "./types";
-import { isRef } from "@jxsuite/schema/guards";
+import { displayTagName, isRef } from "@jxsuite/schema/guards";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
 export type JxPath = (string | number)[];
 
-interface HistorySnapshot {
-  document: JxMutableNode;
-  selection: JxPath | null;
-}
-
-export interface StudioState {
-  document: JxMutableNode;
-  selection: JxPath | null;
-  hover: JxPath | null;
-  history: HistorySnapshot[];
-  historyIndex: number;
-  dirty: boolean;
-  fileHandle: FileSystemFileHandle | null;
-  documentPath: string | null;
-  documentStack: StudioStackFrame[];
-  handlersSource: string | null;
-  mode: string;
-  content: { frontmatter: Record<string, unknown> };
-  ui: Record<string, unknown>;
-  canvas: {
-    status: string;
-    scope: Record<string, unknown> | null;
-    error: string | null;
-  };
-}
-
-interface StudioStackFrame {
-  document: JxMutableNode;
-  selection: JxPath | null;
-  fileHandle: FileSystemFileHandle | null;
-  documentPath: string | null;
-  dirty: boolean;
-  history: HistorySnapshot[];
-  historyIndex: number;
-  mode: string;
-}
-
 // ─── Path utilities ───────────────────────────────────────────────────────────
 
 /**
@@ -73,35 +38,6 @@ export function getNodeAtPath(doc: JxMutableNode, path: JxPath) {
   return node;
 }
 
-/**
- * Shallow-clone every node along `path` from root to target, leaving non-path subtrees as shared
- * references. Returns the new root and the mutable target node at the end of the path.
- *
- * Used by mutation functions for structural-sharing history: the old root becomes an immutable
- * snapshot (shared subtrees are never mutated), and the new root is the live document.
- */
-export function cloneAlongPath(
-  doc: JxMutableNode,
-  path: JxPath,
-): { root: JxMutableNode; target: JxMutableNode } {
-  const root = Array.isArray(doc) ? [...doc] : { ...doc };
-  let node: Record<string | number, unknown> = root as Record<string | number, unknown>;
-
-  for (const key of path) {
-    const child = node[key];
-    if (child == null) {
-      return { root: root as JxMutableNode, target: node as JxMutableNode };
-    }
-    const cloned = Array.isArray(child)
-      ? [...(child as unknown[])]
-      : { ...(child as Record<string, unknown>) };
-    node[key] = cloned;
-    node = cloned as Record<string | number, unknown>;
-  }
-
-  return { root: root as JxMutableNode, target: node as JxMutableNode };
-}
-
 /**
  * The node's children when they are a static array (the edit-mode invariant); an empty array for
  * mapped-array or absent children.
@@ -300,7 +236,7 @@ function collectRows(
   }
 
   // Custom component instances without user-authored children are atomic in the layer tree
-  if (doc.$props && (doc.tagName || "").includes("-") && !Array.isArray(doc.children)) {
+  if (doc.$props && displayTagName(doc.tagName).includes("-") && !Array.isArray(doc.children)) {
     return;
   }
 
@@ -372,7 +308,10 @@ export function nodeLabel(node: JxMutableNode | null) {
     const name = node.attributes?.name;
     return typeof name === "string" && name.trim() ? `slot: ${name.trim()}` : "slot";
   }
-  const tag = node.tagName ?? "div";
+  /* `displayTagName`, because a tag may be CHOSEN rather than written: this label reached the
+     Outline row, the Inspector's header and the jump bar, and a raw read rendered `[object Object]`
+     in all three. `a|div` is the honest answer — one element, tag decided at creation. */
+  const tag = displayTagName(node.tagName) || "div";
   const suffix = node.$switch ? " ⇆" : "";
   if (typeof node.textContent === "string" && node.textContent.length > 0) {
     return `${tag} — ${node.textContent.slice(0, 24)}${suffix}`;
@@ -380,113 +319,6 @@ export function nodeLabel(node: JxMutableNode | null) {
   return tag + suffix;
 }
 
-// ─── State factory ────────────────────────────────────────────────────────────
-
-/**
- * @param {JxMutableNode} doc
- * @returns {StudioState}
- */
-export function createState(doc: JxMutableNode): StudioState {
-  const initial = { document: doc, selection: null };
-  return {
-    canvas: {
-      error: null, // Error message on failure
-      scope: null, // $defs scope from runtime buildScope
-      status: "idle", // "idle" | "loading" | "ready" | "error"
-    },
-    content: { frontmatter: {} }, // Frontmatter metadata for .md files
-    dirty: false,
-    document: doc,
-    documentPath: null, // Root-relative path, e.g. "examples/markdown/blog.json"
-    documentStack: [], // Frames for component navigation
-    fileHandle: null,
-    handlersSource: null,
-    history: [initial],
-    historyIndex: 0,
-    hover: null,
-    mode: "component", // 'component' | 'content'
-    selection: null,
-    ui: {
-      activeMedia: null, // '--md' | null (base) — focused canvas/breakpoint
-      activeSelector: null, // ':hover' | '.child' | null (base) — nested selector context
-      editingFunction: null, // Null | { type: 'def', defName } | { type: 'event', path, eventKey }
-      featureToggles: {}, // { '--dark': true } — non-size media toggles
-      gitBranches: null, // { current, branches: [] }
-      gitCommitMessage: "", // Commit message input
-      gitDiffState: null,
-      gitError: null, // Error message string
-      gitLoading: false, // Loading indicator during async ops
-      gitStatus: null, // { branch, ahead, behind, files: [] }
-      inspectorSections: {}, // { identity: true, ... } — properties panel section open/closed state
-      pendingInlineEdit: null, // Null | { path, mediaName } — deferred inline edit awaiting canvas readiness
-      rightTab: "properties", // 'properties' | 'events' | 'style'
-      settingsTab: "stylebook", // "stylebook" | "definitions" | "contentTypes"
-      styleFilter: "", // Free-text filter for CSS property names
-      styleFilterActive: false, // True = show only props with values set
-      styleSections: {}, // { layout: true, ... } — section open/closed state
-      styleShorthands: {}, // { padding: true, ... } — shorthand expand/collapse state
-      stylebookCustomizedOnly: false, // Show only customized elements
-      stylebookFilter: "", // Search filter text
-      stylebookSelection: null, // Tag name string, e.g. "h1"
-      stylebookTab: "elements", // "elements" | "variables"
-      zoom: 1,
-    },
-  };
-}
-
-// ─── Doc/Session slice helpers ───────────────────────────────────────────────
-
-/**
- * Compose a flat StudioState from separate doc and session slices.
- *
- * @param {Partial<StudioState>} doc
- * @param {Partial<StudioState>} session
- * @returns {StudioState}
- */
-export function toFlat(doc: Partial<StudioState>, session: Partial<StudioState>) {
-  return { ...doc, ...session } as StudioState;
-}
-
-/**
- * Decompose a flat StudioState into doc and session slices.
- *
- * @param {StudioState} S
- * @returns {{ doc: Partial<StudioState>; session: Partial<StudioState> }}
- */
-export function fromFlat(S: StudioState) {
-  const {
-    document,
-    dirty,
-    fileHandle,
-    documentPath,
-    documentStack,
-    handlersSource,
-    mode,
-    content,
-    history,
-    historyIndex,
-    selection,
-    hover,
-    ui,
-    canvas,
-  } = S;
-  return {
-    doc: {
-      content,
-      dirty,
-      document,
-      documentPath,
-      documentStack,
-      fileHandle,
-      handlersSource,
-      history,
-      historyIndex,
-      mode,
-    },
-    session: { canvas, hover, selection, ui },
-  };
-}
-
 // ─── Project state (persists across document switches) ────────────────────────
 //
 // Shape: { root, name, projectRoot, isSiteProject, projectConfig,
@@ -510,96 +342,3 @@ export function setProjectState(ps: ProjectState | null) {
 export function requireProjectState() {
   return projectState as ProjectState;
 }
-
-// ─── Frontmatter mutation ───────────────────────────────────────────────────
-
-/**
- * Update a frontmatter field. Does not use applyMutation because frontmatter lives in S.content,
- * not S.document.
- *
- * @param {StudioState} state
- * @param {string} field
- * @param {unknown} value
- * @returns {StudioState}
- */
-export function updateFrontmatter(state: StudioState, field: string, value: unknown) {
-  const fm = { ...state.content?.frontmatter };
-  if (value === undefined || value === null || value === "") {
-    delete fm[field];
-  } else {
-    fm[field] = value;
-  }
-  return {
-    ...state,
-    content: { ...state.content, frontmatter: fm },
-    dirty: true,
-  };
-}
-
-// ─── Selection / hover ────────────────────────────────────────────────────────
-
-/**
- * @param {StudioState} state
- * @param {JxPath | null} path
- * @returns {StudioState}
- */
-export function selectNode(state: StudioState, path: JxPath | null) {
-  return { ...state, selection: path };
-}
-
-/**
- * @param {StudioState} state
- * @param {JxPath | null} path
- * @returns {StudioState}
- */
-export function hoverNode(state: StudioState, path: JxPath | null) {
-  return { ...state, hover: path };
-}
-
-// ─── Document stack (component navigation) ──────────────────────────────────
-
-/**
- * Push current document onto the stack and switch to editing a new document.
- *
- * @param {StudioState} state
- * @param {JxMutableNode} doc
- * @param {string | null} documentPath
- * @returns {StudioState}
- */
-export function pushDocument(state: StudioState, doc: JxMutableNode, documentPath: string | null) {
-  const frame = {
-    dirty: state.dirty,
-    document: state.document,
-    documentPath: state.documentPath,
-    fileHandle: state.fileHandle,
-    history: state.history,
-    historyIndex: state.historyIndex,
-    mode: state.mode,
-    selection: state.selection,
-  };
-  const newState = createState(doc);
-  newState.documentStack = [...(state.documentStack || []), frame];
-  newState.documentPath = documentPath;
-  newState.ui = { ...state.ui, activeMedia: null, activeSelector: null };
-  return newState;
-}
-
-/**
- * Pop the document stack and return to the previous document.
- *
- * @param {StudioState} state
- * @returns {StudioState}
- */
-export function popDocument(state: StudioState) {
-  if (!state.documentStack || state.documentStack.length === 0) {
-    return state;
-  }
-  const stack = [...state.documentStack];
-  const frame = stack.pop();
-  return {
-    ...state,
-    ...frame,
-    documentStack: stack,
-    ui: { ...state.ui },
-  };
-}

package/src/store.ts

@@ -9,13 +9,12 @@
 
 // ─── Re-exports from state.js ────────────────────────────────────────────────
 
-import { activeTab } from "./workspace/workspace";
+import { INPUT_DEBOUNCE } from "./ui/timing";
 import type { JxPath } from "./state";
+import type { Tab } from "./tabs/tab";
 import type { JxMutableNode } from "@jxsuite/schema/types";
-import type { CanvasPanel } from "./types";
 
 export {
-  createState,
   getNodeAtPath,
   childList,
   flattenTree,
@@ -28,35 +27,29 @@ export {
   projectState,
   setProjectState,
   requireProjectState,
-  updateFrontmatter,
 } from "./state";
 
 // ─── Shell element refs (populated by initShellRefs) ─────────────────────────
 
-export let canvasWrap = null as unknown as HTMLElement;
+/* There is no `canvasWrap` here, and there cannot be one.
+   It was `#canvas-wrap`, the shell's single stage, imported by six modules and read at ~30 sites —
+   each of which meant "the pane I am acting on" and got "the pane that happens to be focused". A
+   stage belongs to a pane (`canvas/canvas-surface.ts`), a pane's cell is built by
+   `panels/pane-grid.ts`, and every one of those readers now takes its surface. */
 export let activityBar = null as unknown as HTMLElement;
 export let leftPanel = null as unknown as HTMLElement;
 export let rightPanel = null as unknown as HTMLElement;
-export let chatPanelEl = null as unknown as HTMLElement;
 export let toolbarEl = null as unknown as HTMLElement;
 export let statusbarEl = null as unknown as HTMLElement;
-export let frontmatterPanelEl = null as unknown as HTMLElement;
 
 export function initShellRefs() {
-  canvasWrap = document.querySelector("#canvas-wrap") as HTMLElement;
   activityBar = document.querySelector("#activity-bar") as HTMLElement;
   leftPanel = document.querySelector("#left-panel") as HTMLElement;
   rightPanel = document.querySelector("#right-panel") as HTMLElement;
-  chatPanelEl = document.querySelector("#chat-panel") as HTMLElement;
   toolbarEl = document.querySelector("#toolbar") as HTMLElement;
   statusbarEl = document.querySelector("#statusbar") as HTMLElement;
-  frontmatterPanelEl = document.querySelector("#frontmatter-panel") as HTMLElement;
 }
 
-// ─── Shared containers (mutated in place by owner modules) ───────────────────
-
-export const canvasPanels: CanvasPanel[] = [];
-
 // ─── Shared constants ────────────────────────────────────────────────────────
 
 /** Void elements that cannot accept children */
@@ -102,14 +95,15 @@ const _styleDebounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
 
 /**
  * @param {string} prop
- * @param {number} ms
+ * @param {number | undefined} ms Debounce delay; `undefined` takes the standard input debounce.
  * @param {(...args: unknown[]) => void} fn
  */
 export function debouncedStyleCommit<A extends unknown[]>(
   prop: string,
-  ms: number,
+  ms: number | undefined,
   fn: (...args: A) => void,
 ) {
+  const delay = ms ?? INPUT_DEBOUNCE;
   return (...args: A) => {
     clearTimeout(_styleDebounceTimers.get(prop));
     _styleDebounceTimers.set(
@@ -117,7 +111,7 @@ export function debouncedStyleCommit<A extends unknown[]>(
       setTimeout(() => {
         _styleDebounceTimers.delete(prop);
         fn(...args);
-      }, ms),
+      }, delay),
     );
   };
 }
@@ -136,6 +130,47 @@ export { stripEventHandlers } from "./utils/strip-events";
 
 const _renderers = new Map<string, () => void>();
 
+/**
+ * How many registered renderers are mid-paint right now.
+ *
+ * Condition 1 of the `probe.idle()` predicate (`services/idle.ts`, spec §13.5). A renderer is
+ * declared `() => void`, but TypeScript happily assigns an `async` function to that type, so a
+ * renderer that awaits keeps repainting long after `render()` returned. Counting the returned
+ * thenable is what makes "no queued lit render" an answerable question instead of an assumption —
+ * the alternative is a sleep, and a sleep cannot name what it is waiting for.
+ */
+let _rendersInFlight = 0;
+
+/** Renderers currently mid-paint — zero when the shell's DOM has caught up with its state. */
+export function rendersInFlight(): number {
+  return _rendersInFlight;
+}
+
+/** Run one renderer, counting it as in-flight until it returns (or its promise settles). */
+function runRenderer(name: string, fn: () => void) {
+  _rendersInFlight += 1;
+  const done = () => {
+    _rendersInFlight -= 1;
+  };
+  let pending: PromiseLike<unknown> | null = null;
+  try {
+    const result = fn() as unknown;
+    if (typeof (result as PromiseLike<unknown> | null)?.then === "function") {
+      pending = result as PromiseLike<unknown>;
+    }
+  } catch (error) {
+    console.error(`Renderer "${name}" failed:`, error);
+  }
+  if (!pending) {
+    done();
+    return;
+  }
+  pending.then(done, (error: unknown) => {
+    console.error(`Renderer "${name}" failed:`, error);
+    done();
+  });
+}
+
 /**
  * Register a named renderer. Called at module import time by each module.
  *
@@ -149,11 +184,7 @@ export function registerRenderer(name: string, fn: () => void) {
 /** Call all registered renderers (full repaint). */
 export function render() {
   for (const [name, fn] of _renderers.entries()) {
-    try {
-      fn();
-    } catch (error) {
-      console.error(`Renderer "${name}" failed:`, error);
-    }
+    runRenderer(name, fn);
   }
 }
 
@@ -168,32 +199,46 @@ export function renderOnly(...names: string[]) {
     if (!fn) {
       continue;
     }
-    try {
-      fn();
-    } catch (error) {
-      console.error(`Renderer "${name}" failed:`, error);
-    }
+    runRenderer(name, fn);
   }
 }
 
 // ─── Session dispatch ──────────────────────────────────────────────────────
 
+/* **Every dispatcher below takes the tab it writes, and none of them can find one on its own.**
+   All three used to open with `const tab = activeTab.value`, which made "the document this
+   control is about" and "the document the keyboard happens to be in" the same expression — the
+   defect that produced the Document Header card writing through focus, the zoom axis writing
+   through focus, the debounced Monaco commit writing through focus, and the whole pane context
+   bar writing through focus. Four instances, four audits, no gate: while the shell had one stage
+   the two readings could not disagree, so nothing could observe the difference.
+
+   `store.ts` is where they could not disagree, so `store.ts` is where the shape is fixed. There is
+   no `activeTab` import in this file and no zero-argument variant of any of these: a caller that
+   means the focused pane spells `activeTab.value` at its own call site, where a reviewer and
+   `scripts/check-pane-singletons.ts` can both see it, and a caller drawn FOR a pane passes the tab
+   it was drawn for. */
+
 /**
- * Dispatch a session-only state update (selection, hover, ui). Writes directly to reactive tab.
+ * Dispatch a session-only state update (selection, hover, ui) into `tab`.
  *
+ * @param {Tab | null} tab — the tab this update is about. `null` is a no-op.
  * @param {object} patch — partial session object, e.g. { ui: { zoom: 2 } }
  */
-export function updateSession(patch: {
-  selection?: JxPath | null;
-  hover?: JxPath | null;
-  clipboard?: JxMutableNode | null;
-  ui?: Record<string, unknown>;
-  canvas?: Record<string, unknown>;
-}) {
-  const tab = activeTab.value;
+export function updateSession(
+  tab: Tab | null,
+  patch: {
+    /** The whole selection SET — `[]` clears it. Widened with `session.selection` itself (§6.5). */
+    selection?: JxPath[];
+    hover?: JxPath | null;
+    clipboard?: JxMutableNode | null;
+    ui?: Record<string, unknown>;
+    canvas?: Record<string, unknown>;
+  },
+) {
   if (tab) {
     if (patch.selection !== undefined) {
-      tab.session.selection = patch.selection as JxPath | null;
+      tab.session.selection = patch.selection;
     }
     if (patch.hover !== undefined) {
       tab.session.hover = patch.hover as JxPath | null;
@@ -215,25 +260,25 @@ export function updateSession(patch: {
 }
 
 /**
- * Update a single UI field.
+ * Update a single UI field on `tab`.
  *
+ * @param {Tab | null} tab — the tab this field belongs to. `null` is a no-op.
  * @param {string} field
  * @param {unknown} value
  */
-export function updateUi(field: string, value: unknown) {
-  const tab = activeTab.value;
+export function updateUi(tab: Tab | null, field: string, value: unknown) {
   if (tab) {
     (tab.session.ui as unknown as Record<string, unknown>)[field] = value;
   }
 }
 
 /**
- * Update the canvas async state (status, scope, error).
+ * Update `tab`'s canvas async state (status, scope, error).
  *
+ * @param {Tab | null} tab — the tab whose stage produced this state. `null` is a no-op.
  * @param {object} patch
  */
-export function updateCanvas(patch: Record<string, unknown>) {
-  const tab = activeTab.value;
+export function updateCanvas(tab: Tab | null, patch: Record<string, unknown>) {
   if (tab) {
     for (const [k, v] of Object.entries(patch)) {
       (tab.session.canvas as Record<string, unknown>)[k] = v;