@jxsuite/studio 6.1.1 → 6.1.2

package/src/tabs/project-config.ts

@@ -63,7 +63,7 @@ import { errorMessage } from "@jxsuite/schema/parse";
 import { effect, toRaw } from "../reactivity";
 import { getPlatform } from "../platform";
 import { notify } from "../services/notify";
-import { requireProjectState, setProjectState } from "../state";
+import { projectState, requireProjectState, setProjectState } from "../state";
 import { setWorkspaceProject, workspace } from "../workspace/workspace";
 import { PROJECT_CONFIG_PATH, createTab, disposeTab } from "./tab";
 import { transactDoc } from "./transact";
@@ -71,7 +71,7 @@ import { deriveJsonLayout, parseJsonDocument, serializeJson } from "@jxsuite/sch
 import type { JsonLayout } from "@jxsuite/schema/json-layout";
 
 import type { Tab } from "./tab";
-import type { ProjectConfig } from "@jxsuite/schema/types";
+import type { JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 
 export { PROJECT_CONFIG_PATH } from "./tab";
 
@@ -147,7 +147,7 @@ let _seeding: Promise<void> | null = null;
  */
 function openConfigTab(): Tab | null {
   const tab = workspace.tabs.get(PROJECT_CONFIG_PATH);
-  return tab ? (toRaw(tab as unknown as object) as Tab) : null;
+  return tab ? toRaw(tab) : null;
 }
 
 /** Drop the current binding, disposing the detached document if that is what it was. */
@@ -169,7 +169,8 @@ function seedCommitted(): Promise<void> {
       const text = await getPlatform().readFile(PROJECT_CONFIG_PATH);
       const { document, layout } = parseJsonDocument(text);
       _layout = layout;
-      _committed = serializeProjectConfig(document as unknown as ProjectConfig);
+      // {@link serializeProjectConfig}'s serialisation, over the file's parse rather than a config.
+      _committed = serializeJson(document, configLayout());
     } catch {
       // No file, an unreadable one, or one that does not parse. "Unknown" is the honest answer,
       // And an unknown file is one every commit must write.
@@ -240,8 +241,22 @@ function syncProjectState(config: ProjectConfig): void {
  * @returns {ProjectConfig | null}
  */
 function liveConfig(): ProjectConfig | null {
-  const config = requireProjectState()?.projectConfig;
-  return config ? (toRaw(config as unknown as object) as ProjectConfig) : null;
+  const config = projectState?.projectConfig;
+  return config ? toRaw(config) : null;
+}
+
+/**
+ * The configuration a configuration document holds, unwrapped.
+ *
+ * @param {JxMutableNode} document The bound tab's `doc.document`.
+ * @returns {ProjectConfig}
+ */
+function configOf(document: JxMutableNode): ProjectConfig {
+  /* SAFETY: every document this module reads is the `project.json` tab's root, and that root is
+     only ever installed as a ProjectConfig: `createTab` below seeds it from `projectConfig`, an open
+     tab parsed the file the schema gate wrote, and every transaction here assigns configuration
+     keys. The Tab type calls every root a JxMutableNode; this is the one place that says which. */
+  return toRaw(document) as ProjectConfig;
 }
 
 /**
@@ -261,10 +276,10 @@ function liveConfig(): ProjectConfig | null {
  * settings surfaces render from `projectState` and mutate it in place, and every reader of the
  * document follows the root reference {@link transactDoc} replaces when the transaction ends.
  *
- * @param {Record<string, unknown>} target
+ * @param {JxMutableNode} target
  * @param {ProjectConfig} source
  */
-function replaceContents(target: Record<string, unknown>, source: ProjectConfig): void {
+function replaceContents(target: JxMutableNode, source: ProjectConfig): void {
   for (const key of Object.keys(target)) {
     delete target[key];
   }
@@ -282,10 +297,10 @@ function bind(tab: Tab): Tab {
   tab.scope.run(() => {
     effect(() => {
       const doc = tab.doc.document;
-      if (_bound !== tab || !requireProjectState()) {
+      if (_bound !== tab || !projectState) {
         return;
       }
-      syncProjectState(toRaw(doc) as unknown as ProjectConfig);
+      syncProjectState(configOf(doc));
     });
   });
   return tab;
@@ -316,7 +331,7 @@ export function projectConfigDocument(): Tab {
     return bind(open);
   }
   _detached = createTab({
-    document: (state.projectConfig ?? {}) as unknown as Record<string, unknown>,
+    document: state.projectConfig ?? {},
     documentPath: PROJECT_CONFIG_PATH,
     id: PROJECT_CONFIG_PATH,
   });
@@ -380,7 +395,7 @@ export async function commitProjectConfig(
   // The seed, and the record it read handed to the document — so the tab the Settings door opened
   // Writes the same bytes from ⌘S that this commit is about to.
   await lendProjectConfigLayout(tab);
-  const current = toRaw(tab.doc.document) as unknown as ProjectConfig;
+  const current = configOf(tab.doc.document);
   const currentText = serializeProjectConfig(current);
 
   // Two objects that disagree — whichever one loses, an edit written into it is lost. Null when
@@ -404,7 +419,7 @@ export async function commitProjectConfig(
   }
 
   const base = rival ?? current;
-  const next = patch ? ({ ...base, ...patch } as ProjectConfig) : base;
+  const next: ProjectConfig = patch ? { ...base, ...patch } : base;
   const text = serializeProjectConfig(next);
 
   // Nothing the file does not already say: no transaction, no write, and therefore no diff. The
@@ -417,7 +432,7 @@ export async function commitProjectConfig(
 
   const before = extensionsKey(current);
   transactDoc(tab, (t) => {
-    const doc = t.doc.document as unknown as Record<string, unknown>;
+    const doc = t.doc.document;
     if (rival) {
       replaceContents(doc, rival);
     }
@@ -429,7 +444,7 @@ export async function commitProjectConfig(
   // Serialised from what the transaction actually LANDED, not from the `next` computed above: a
   // Gate on `transactDoc` can refuse a mutation, and writing the value it refused would put the
   // File and the document into the one disagreement this module exists to make impossible.
-  const config = toRaw(tab.doc.document) as unknown as ProjectConfig;
+  const config = configOf(tab.doc.document);
   const output = serializeProjectConfig(config);
   try {
     await getPlatform().writeFile(PROJECT_CONFIG_PATH, output);
@@ -480,18 +495,14 @@ export async function commitProjectConfig(
  * @returns {Promise<void>}
  */
 export async function adoptProjectConfig(config: ProjectConfig, text: string): Promise<void> {
-  if (!requireProjectState()) {
+  if (!projectState) {
     // No project state is no configuration document either ({@link projectConfigDocument} reads
     // One). The workspace copy is then the only thing there is to keep true.
     setWorkspaceProject(workspace.projectRoot, config);
     return;
   }
   const tab = projectConfigDocument();
-  transactDoc(
-    tab,
-    (t) => replaceContents(t.doc.document as unknown as Record<string, unknown>, config),
-    { skipHistory: true },
-  );
+  transactDoc(tab, (t) => replaceContents(t.doc.document, config), { skipHistory: true });
   tab.doc.dirty = false;
   // Settle a read already in flight before saying what the file holds, or it would resolve after
   // These lines with the PREVIOUS bytes and record, and make the next real commit look like a

package/src/tabs/selection.ts

@@ -42,6 +42,8 @@
  * standing between a mixed selection and a half-applied, unrecorded delete.
  */
 
+import { isNumber } from "@jxsuite/schema/guards";
+
 import type { JxPath } from "../state";
 import { isAncestor, pathsEqual } from "../state";
 
@@ -52,7 +54,7 @@ import { isAncestor, pathsEqual } from "../state";
  * @returns {JxPath | null}
  */
 export function primarySelection(selection: readonly JxPath[] | null | undefined): JxPath | null {
-  return selection && selection.length > 0 ? (selection.at(-1) as JxPath) : null;
+  return selection?.at(-1) ?? null;
 }
 
 /**
@@ -62,7 +64,7 @@ export function primarySelection(selection: readonly JxPath[] | null | undefined
  * @returns {JxPath | null}
  */
 export function selectionAnchor(selection: readonly JxPath[] | null | undefined): JxPath | null {
-  return selection && selection.length > 0 ? (selection[0] as JxPath) : null;
+  return selection?.[0] ?? null;
 }
 
 /**
@@ -187,7 +189,7 @@ export function comparePaths(a: JxPath, b: JxPath): number {
     if (x === y) {
       continue;
     }
-    if (typeof x === "number" && typeof y === "number") {
+    if (isNumber(x) && isNumber(y)) {
       return x - y;
     }
     return String(x) < String(y) ? -1 : 1;
@@ -231,7 +233,27 @@ export function topLevelSelection(selection: readonly JxPath[]): JxPath[] {
  * @returns {boolean}
  */
 export function isSpliceablePath(path: JxPath): boolean {
-  return path.at(-2) === "children" && typeof path.at(-1) === "number";
+  return spliceCoordinate(path) !== null;
+}
+
+/** Where a structural verb splices: the parent element's path and the index in its children. */
+export interface SpliceCoordinate {
+  parentPath: JxPath;
+  index: number;
+}
+
+/**
+ * The splice coordinate `path` names, or `null` for no path and for every path
+ * {@link isSpliceablePath} refuses.
+ *
+ * @param {JxPath | null | undefined} path
+ * @returns {SpliceCoordinate | null}
+ */
+export function spliceCoordinate(path: JxPath | null | undefined): SpliceCoordinate | null {
+  const index = path?.at(-1);
+  return path && path.at(-2) === "children" && isNumber(index)
+    ? { index, parentPath: path.slice(0, -2) }
+    : null;
 }
 
 /**
@@ -289,7 +311,13 @@ export function selectionsEqual(
 ): boolean {
   const x = a ?? [];
   const y = b ?? [];
-  return x.length === y.length && x.every((p, i) => pathsEqual(p, y[i] as JxPath));
+  return x.length === y.length && x.every((p, i) => pathsEqual(p, y[i] ?? null));
+}
+
+/** One field's value read across the selection: `mixed` when the selected nodes disagree. */
+export interface UnifiedValue<T> {
+  mixed: boolean;
+  value: T | undefined;
 }
 
 /**
@@ -306,13 +334,13 @@ export function selectionsEqual(
  *
  * @template T
  * @param {readonly T[]} values One per selected node, in selection order.
- * @returns {{ mixed: boolean; value: T | undefined }}
+ * @returns {UnifiedValue<T>}
  */
-export function unifyValues<T>(values: readonly T[]): { mixed: boolean; value: T | undefined } {
+export function unifyValues<T>(values: readonly T[]): UnifiedValue<T> {
   if (values.length === 0) {
     return { mixed: false, value: undefined };
   }
-  const first = values[0] as T;
+  const [first] = values;
   const key = JSON.stringify(first ?? null);
   for (let i = 1; i < values.length; i++) {
     if (JSON.stringify(values[i] ?? null) !== key) {

package/src/tabs/tab.ts

@@ -1,12 +1,13 @@
 /// <reference lib="dom" />
 import { effectScope, reactive } from "../reactivity";
 import { formatByName, formatForPath } from "../format/format-host";
+import type { FormatFrontmatter } from "../format/format-host";
 import { normalizeArrayChildren } from "../state";
 import type { JxPath } from "../state";
 import type { FormulaEditDef, FunctionEditDef, InlineEditDef, JsonValue } from "../types";
 import { editorKindForMode } from "../commands/context";
 import type { EditorKind } from "../commands/context";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JsonObject, JxMutableNode } from "@jxsuite/schema/types";
 import type { JxDocOp, JxFmOp } from "./patch-ops";
 import type { JsonLayout } from "@jxsuite/schema/json-layout";
 
@@ -125,7 +126,7 @@ export interface StoredLivePreview {
 
 interface HistorySnapshot {
   /** Full document at this state (checkpoint), or null when the ops describe the transition. */
-  document: Record<string, unknown> | null;
+  document: JxMutableNode | null;
   /** Selection after this state's transaction — the whole set, so a batch undoes back to it. */
   selection: (string | number)[][];
   /** Selection before this state's transaction (restored on surgical undo). */
@@ -177,11 +178,10 @@ export interface Tab {
   scope: {
     stop: () => void;
     run: <T>(fn: () => T) => T | undefined;
-    [k: string]: unknown;
   };
   doc: {
     document: JxMutableNode;
-    content: { frontmatter: Record<string, unknown> };
+    content: { frontmatter: FormatFrontmatter };
     mode: string;
     sourceFormat: string | null;
     handlersSource: string | null;
@@ -230,7 +230,7 @@ export interface Tab {
       // A serializable snapshot of the iframe's resolved `$defs` (data-source values), posted over
       // The bridge as a `dataScope` message and read by the data-explorer panel. Plain data now —
       // The old live `EffectScope` (with `.stop()`) moved into the iframe realm with buildScope.
-      scope: Record<string, unknown> | null;
+      scope: JsonObject | null;
       // Latest live (iframe-evaluated) expression previews keyed by editing-target id, stored
       // Beside `scope` the same way (services/live-preview.ts owns reads/writes).
       livePreviews: Record<string, StoredLivePreview> | null;
@@ -249,7 +249,7 @@ export interface Tab {
  * @param {boolean} preview — initial preview-toggle state
  * @returns {TabUi}
  */
-function createDefaultUi(canvasMode: string, preview = false) {
+function createDefaultUi(canvasMode: string, preview = false): TabUi {
   return {
     activeMedia: null,
     activeSelector: null,
@@ -264,7 +264,7 @@ function createDefaultUi(canvasMode: string, preview = false) {
     pendingInlineEdit: null,
     preview,
     previewColorScheme: "auto" as const,
-    previewLocale: null as string | null,
+    previewLocale: null,
     previewParams: {},
     previewProps: null,
     rightTab: "properties",
@@ -295,8 +295,8 @@ const ALL_MODES = ["edit", "design", "preview", "source", "stylebook", "git-diff
  *   id: string;
  *   documentPath?: string | null;
  *   fileHandle?: FileSystemFileHandle | null;
- *   document: Record<string, unknown>;
- *   frontmatter?: Record<string, unknown>;
+ *   document: JxMutableNode;
+ *   frontmatter?: FormatFrontmatter;
  *   sourceFormat?: string | null;
  *   capabilities?: { modes?: string[] };
  *   openedFrom?: TabOrigin | null;
@@ -320,8 +320,8 @@ export function createTab({
   id: string;
   documentPath?: string | null;
   fileHandle?: FileSystemFileHandle | null;
-  document: Record<string, unknown>;
-  frontmatter?: Record<string, unknown>;
+  document: JxMutableNode;
+  frontmatter?: FormatFrontmatter;
   sourceFormat?: string | null;
   capabilities?: { modes?: string[] };
   openedFrom?: TabOrigin | null;
@@ -342,45 +342,56 @@ export function createTab({
   const initialCanvasMode = resolvedModes.find((m) => m !== "preview") ?? "edit";
   const initialPreview = resolvedModes[0] === "preview";
 
+  const doc: Tab["doc"] = {
+    content: { frontmatter: frontmatter || {} },
+    dirty: false,
+    document,
+    handlersSource: null,
+    layout,
+    mode: inferDocumentMode(documentPath, sourceFormat),
+    sourceFormat,
+  };
+  const history: Tab["history"] = {
+    index: 0,
+    snapshots: [{ document: structuredClone(document), selection: [] }],
+  };
+  const session: Tab["session"] = {
+    canvas: {
+      refreshing: false,
+      error: null,
+      livePreviews: null,
+      pendingInlineEdit: null,
+      scope: null,
+      status: "idle",
+    },
+    clipboard: null,
+    hover: null,
+    openedFrom,
+    selection: [],
+    ui: createDefaultUi(initialCanvasMode, initialPreview),
+  };
+
+  /* SAFETY: `reactive()` returns a deep proxy carrying its target's own members, and none of these
+     Three trees holds a ref for `UnwrapNestedRefs` to unwrap, so each proxy IS the shape it is cast
+     To. The type argument is pinned to `object` because `UnwrapNestedRefs<JxMutableNode>` recurses
+     Deeply enough for tsc to give up (TS2589); the proxies are deep either way. */
   const tab = scope.run(() => ({
     capabilities: { modes: resolvedModes },
-    doc: reactive({
-      content: { frontmatter: frontmatter || {} },
-      dirty: false,
-      document,
-      handlersSource: null,
-      layout,
-      mode: inferDocumentMode(documentPath, sourceFormat),
-      sourceFormat,
-    }),
+    doc: reactive<object>(doc) as Tab["doc"],
     documentPath,
     fileHandle,
-    history: reactive({
-      index: 0,
-      snapshots: [{ document: structuredClone(document), selection: [] }],
-    }),
+    history: reactive<object>(history) as Tab["history"],
     id,
     pinned: false,
     preview: previewTab,
     scope,
-    session: reactive({
-      canvas: {
-        refreshing: false,
-        error: null,
-        livePreviews: null,
-        pendingInlineEdit: null,
-        scope: null,
-        status: "idle",
-      },
-      clipboard: null,
-      hover: null,
-      openedFrom,
-      selection: [],
-      ui: createDefaultUi(initialCanvasMode, initialPreview),
-    }),
-  })) as unknown as Tab;
+    session: reactive<object>(session) as Tab["session"],
+  }));
 
-  return tab;
+  /* SAFETY: `scope` was created at the top of this function and nothing has stopped it, and an
+     Active scope's `run` always returns its callback's value; `undefined` is only what an inactive
+     Scope answers. */
+  return tab as Tab;
 }
 
 /**