@jxsuite/studio 6.1.1 → 8.0.0

package/src/site-context.ts

@@ -8,11 +8,12 @@
  * @docs framework/site/i18n
  */
 
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { projectState } from "./store";
 import { getPlatform } from "./platform";
 import { commitProjectConfig } from "./tabs/project-config";
 
-import { resolveI18n } from "@jxsuite/schema/locale";
+import { canonicalizeLocale, localeOfPath, resolveI18n } from "@jxsuite/schema/locale";
 import type { ResolvedI18n } from "@jxsuite/schema/locale";
 import type {
   JxElement,
@@ -21,6 +22,7 @@ import type {
   JxStyle,
   ProjectConfig,
 } from "@jxsuite/schema/types";
+import type { ExtensionsInfo } from "./types";
 
 /**
  * Merge site $media with document $media. Document keys win on conflict.
@@ -57,10 +59,8 @@ export function getEffectiveStyle(docStyle?: JxStyle) {
   }
   const merged = { ...siteStyle };
   for (const [k, v] of Object.entries(docStyle)) {
-    merged[k] =
-      typeof v === "object" && v !== null && typeof merged[k] === "object" && merged[k] !== null
-        ? { ...(merged[k] as JxStyle), ...(v as JxStyle) }
-        : v;
+    const base = merged[k];
+    merged[k] = isNonNullObject(v) && isNonNullObject(base) ? { ...base, ...v } : v;
   }
   return merged;
 }
@@ -72,15 +72,35 @@ export function getEffectiveStyle(docStyle?: JxStyle) {
  *   undefined)
  * @returns {Record<string, string>}
  */
-export function getEffectiveImports(docImports?: Record<string, string>) {
-  const siteImports = projectState?.projectConfig?.imports;
-  if (!siteImports) {
-    return docImports || {};
-  }
-  if (!docImports) {
-    return { ...siteImports };
-  }
-  return { ...siteImports, ...docImports };
+export function getEffectiveImports(
+  docImports?: Record<string, string>,
+  extensions: readonly ExtensionsInfo[] = [],
+) {
+  /* The enabled extensions' manifest classes come last in the order the build resolves a bare
+     `$prototype` in (spec.md §12.5: the document's `imports`, then the project's, then the
+     extension registry), so they are the base the other two are spread over. Without them a
+     layout's `{ "$prototype": "ContentEntry" }` named a class the build knows and the canvas did
+     not, and the canvas warned of an unknown prototype and drew the layout with no data. The
+     first extension to declare a name keeps it, as the registry's `byName` answers. */
+  return {
+    ...extensionClassPaths(extensions),
+    ...projectState?.projectConfig?.imports,
+    ...docImports,
+  };
+}
+
+/**
+ * The enabled extensions' manifest classes, by name, as descriptor paths: the last step of the
+ * build's bare-`$prototype` resolution (spec.md §12.5). The first extension to declare a name keeps
+ * it, as the registry's `byName` answers.
+ */
+export function extensionClassPaths(extensions: readonly ExtensionsInfo[]) {
+  const classes = extensions.flatMap((extension) =>
+    (extension.classes ?? [])
+      .filter((cls) => cls.path.endsWith(".class.json"))
+      .map((cls): [string, string] => [cls.name, cls.path]),
+  );
+  return Object.fromEntries(classes.toReversed());
 }
 
 /**
@@ -101,7 +121,8 @@ export function getEffectiveElements(docElements?: (JxElement | string)[]) {
   const seen = new Set<string>();
   const merged: (JxElement | string)[] = [];
   for (const entry of [...siteElements, ...docElements]) {
-    const key = typeof entry === "string" ? entry : entry?.$ref;
+    // A null entry in hand-edited JSON has no key, and is skipped rather than thrown on.
+    const key = isString(entry) ? entry : isNonNullObject(entry) ? entry.$ref : undefined;
     if (key && !seen.has(key)) {
       seen.add(key);
       merged.push(entry);
@@ -127,8 +148,9 @@ export function getEffectiveHead(docHead?: JxHeadEntry[]) {
   const seen = new Set<string>();
   const merged: JxHeadEntry[] = [];
   for (const entry of [...siteHead, ...docHead]) {
-    const key =
-      String(entry?.attributes?.href || entry?.attributes?.src || "") || JSON.stringify(entry);
+    // A null entry in hand-edited JSON is keyed by its serialisation, like any entry without a URL.
+    const attributes = isNonNullObject(entry) ? entry.attributes : undefined;
+    const key = String(attributes?.href || attributes?.src || "") || JSON.stringify(entry);
     if (!seen.has(key)) {
       seen.add(key);
       merged.push(entry);
@@ -158,6 +180,39 @@ export function getEffectiveLocales(): ResolvedI18n | null {
   return config ? resolveI18n(config).i18n : null;
 }
 
+/**
+ * The language a pane renders in (studio.md §20.2), the one answer the context bar's Language
+ * segment, every artboard's `render` and the live push all read.
+ *
+ * The author's choice while the project declares it, else the document's own: the locale its path
+ * sits under (`site-architecture.md` §13.3 puts a translation in its own directory, so
+ * `pages/ar/about.json` and `content/exhibitions/ar/x.md` are Arabic), else the default locale,
+ * which is what an unprefixed page renders as. Null for a project that declares no locales.
+ *
+ * A stored choice the project no longer declares answers as if none were made, the counterpart of
+ * `i18n.switchLocale` refusing one on the way in; the stored value is left alone, so a locale that
+ * is declared again comes back. Answering with the document's own language when nothing is chosen
+ * is what makes an Arabic translation mirror as soon as it is opened: before, the artboard drew it
+ * left to right until the author picked Arabic from a control already showing Arabic.
+ *
+ * @param previewLocale - The pane's choice (`session.ui.previewLocale`), or null.
+ * @param documentPath - The project-relative path of the document being drawn.
+ */
+export function getEffectiveRenderLocale(
+  previewLocale: string | null | undefined,
+  documentPath: string | null | undefined,
+): string | null {
+  const i18n = getEffectiveLocales();
+  if (i18n === null) {
+    return null;
+  }
+  const chosen = canonicalizeLocale(previewLocale);
+  if (chosen !== null && i18n.locales.includes(chosen)) {
+    return chosen;
+  }
+  return localeOfPath(documentPath ?? "", i18n) ?? i18n.defaultLocale;
+}
+
 // ─── Layout resolution ──────────────────────────────────────────────────────
 
 const layoutCache = new Map<string, JxMutableNode>();
@@ -189,13 +244,16 @@ export function getEffectiveLayoutPath(docLayout: string | false | undefined) {
  */
 export async function resolveLayoutDoc(layoutPath: string) {
   const normalized = layoutPath.replace(/^\.\//, "");
-  if (layoutCache.has(normalized)) {
-    return structuredClone(layoutCache.get(normalized) as JxMutableNode);
+  const cached = layoutCache.get(normalized);
+  if (cached !== undefined) {
+    return structuredClone(cached);
   }
 
   try {
     const platform = getPlatform();
     const content = await platform.readFile(normalized);
+    /* SAFETY: a `$layout` target is a Jx document file, which is a JSON element object; the slot
+       walk that consumes it checks `children` is an array before reading any of it. */
     const doc = JSON.parse(content) as JxMutableNode;
     layoutCache.set(normalized, doc);
     return structuredClone(doc);
@@ -220,8 +278,8 @@ export function distributePageIntoLayout(layoutDoc: JxMutableNode, pageDoc: JxMu
   const defaults: (JxMutableNode | string)[] = [];
 
   for (const child of children) {
-    const slotName = typeof child === "object" ? child.attributes?.slot : undefined;
-    if (typeof child === "object" && typeof slotName === "string" && slotName) {
+    const slotName = isString(child) ? undefined : child.attributes?.slot;
+    if (!isString(child) && isString(slotName) && slotName) {
       if (!named.has(slotName)) {
         named.set(slotName, []);
       }
@@ -254,18 +312,15 @@ function fillSlots(
   named: Map<string, JxMutableNode[]>,
   defaults: (JxMutableNode | string)[],
 ) {
-  if (!node || typeof node !== "object") {
-    return;
-  }
   if (!Array.isArray(node.children)) {
     return;
   }
 
   const newChildren: (JxMutableNode | string)[] = [];
   for (const child of node.children) {
-    if (child && typeof child === "object" && child.tagName === "slot") {
+    if (isNonNullObject(child) && child.tagName === "slot") {
       const slotName = child.attributes?.name;
-      if (typeof slotName === "string" && slotName && named.has(slotName)) {
+      if (isString(slotName) && slotName && named.has(slotName)) {
         newChildren.push(...named.get(slotName)!);
         named.delete(slotName);
       } else if (!slotName && defaults.length > 0) {
@@ -274,15 +329,26 @@ function fillSlots(
         newChildren.push(...child.children);
       }
     } else {
-      if (typeof child !== "string") {
+      /* Only an element has slots to fill. A null child (hand-edited JSON) used to reach the
+         `!node` guard this function opened with; it now stops here, with the same outcome. */
+      if (isNonNullObject(child)) {
         fillSlots(child, named, defaults);
       }
       newChildren.push(child);
     }
   }
-  node.children = newChildren as JxMutableNode[];
+  node.children = newChildren;
 }
 
+/**
+ * A `project.json` patch: each key's new value, or `undefined` to remove the key.
+ *
+ * `Partial<ProjectConfig>` cannot say the second half under `exactOptionalPropertyTypes` — its
+ * `url` is `string` when present, never `undefined` — so clearing a setting had to be spelled as a
+ * double cast at every call site that wanted to.
+ */
+export type ProjectConfigPatch = { [K in keyof ProjectConfig]?: ProjectConfig[K] | undefined };
+
 /**
  * Merge a partial patch into the project's configuration and persist it.
  *
@@ -297,12 +363,15 @@ function fillSlots(
  * 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; a value
- *   of `undefined` clears the key.
+ * @param {ProjectConfigPatch} 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 result = await commitProjectConfig(patch);
+export async function updateSiteConfig(patch: ProjectConfigPatch) {
+  /* SAFETY: `commitProjectConfig` spreads the patch over the current config and serialises the
+     result with JSON.stringify, so an `undefined` member reaches disk as an absent key and the
+     written file is a ProjectConfig; every other member already has its ProjectConfig type. */
+  const result = await commitProjectConfig(patch as Partial<ProjectConfig>);
   if (!result.ok) {
     throw result.error;
   }

package/src/state.ts

@@ -12,7 +12,15 @@
  */
 
 import type { ProjectState } from "./types";
-import { displayTagName, isRef } from "@jxsuite/schema/guards";
+import {
+  displayTagName,
+  isBoolean,
+  isMappedArray,
+  isNonNullObject,
+  isNumber,
+  isRef,
+  isString,
+} from "@jxsuite/schema/guards";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
 export type JxPath = (string | number)[];
@@ -20,23 +28,10 @@ export type JxPath = (string | number)[];
 // ─── Path utilities ───────────────────────────────────────────────────────────
 
 /**
- * Walk the document tree and return the node at the given path.
- *
- * @param {JxMutableNode} doc
- * @param {JxPath} path
- * @returns {JxMutableNode}
+ * Walk the document tree and return the node at the given path, or `undefined` when a step falls
+ * off the tree (a path gone stale since it was taken). One walk, shared with the document ops.
  */
-export function getNodeAtPath(doc: JxMutableNode, path: JxPath) {
-  let node = doc;
-  for (const key of path) {
-    if (node == null) {
-      return undefined as unknown as JxMutableNode;
-    }
-    // Paths address nodes by construction; non-node leaves surface as undefined above.
-    node = node[key] as JxMutableNode;
-  }
-  return node;
-}
+export { getNodeAtPath } from "@jxsuite/schema/doc-ops";
 
 /**
  * The node's children when they are a static array (the edit-mode invariant); an empty array for
@@ -56,45 +51,62 @@ export function childList(node: JxMutableNode | null | undefined): (JxMutableNod
  * `$switch` cases. Runs once when a document is loaded into a tab so every in-studio doc — and its
  * history checkpoints — uses the member form before any mutation.
  *
- * @param {unknown} node
- * @returns {unknown} The same node (mutated)
+ * The rewrite is the editor's invariant, not the file's: `onBare` hears every repeater it moved,
+ * with the JSON Pointer of the node holding it (in the NORMALIZED document's coordinates), so a
+ * save can put the authored form back (`tabs/bare-repeaters.ts`).
+ *
+ * @param {T} node
+ * @param {BareRepeaterVisitor} [onBare]
+ * @param {string} [pointer] - The node's JSON Pointer, `""` for the root.
+ * @returns {T} The same node (mutated)
  */
-export function normalizeArrayChildren(node: unknown): unknown {
-  if (!node || typeof node !== "object") {
+export function normalizeArrayChildren<T>(node: T, onBare?: BareRepeaterVisitor, pointer = ""): T {
+  if (!isNonNullObject(node)) {
     return node;
   }
   if (Array.isArray(node)) {
-    for (const child of node) {
-      normalizeArrayChildren(child);
+    for (const [i, child] of node.entries()) {
+      normalizeArrayChildren(child, onBare, `${pointer}/${i}`);
     }
     return node;
   }
+  /* SAFETY: A non-array object reached from a document root, a children array, a repeater `map` or
+     a `$switch` case is a node definition, and JxMutableNode is the editor's open node shape. */
   const n = node as JxMutableNode;
   const { children } = n;
-  if (
-    children &&
-    typeof children === "object" &&
-    !Array.isArray(children) &&
-    (children as JxMutableNode).$prototype === "Array"
-  ) {
-    n.children = [children as JxMutableNode];
+  if (isMappedArray(children)) {
+    // SAFETY: A legacy whole-children repeater is the same repeater node that becomes the member.
+    const repeater = children as JxMutableNode;
+    onBare?.(pointer, repeater);
+    n.children = [repeater];
   }
   if (Array.isArray(n.children)) {
-    for (const child of n.children) {
-      normalizeArrayChildren(child);
+    for (const [i, child] of n.children.entries()) {
+      normalizeArrayChildren(child, onBare, `${pointer}/children/${i}`);
     }
   }
-  if (n.$prototype === "Array" && n.map && typeof n.map === "object") {
-    normalizeArrayChildren(n.map);
+  if (n.$prototype === "Array" && isNonNullObject(n.map)) {
+    normalizeArrayChildren(n.map, onBare, `${pointer}/map`);
   }
-  if (n.cases && typeof n.cases === "object") {
-    for (const caseDef of Object.values(n.cases)) {
-      normalizeArrayChildren(caseDef);
+  if (isNonNullObject(n.cases)) {
+    for (const [key, caseDef] of Object.entries(n.cases)) {
+      normalizeArrayChildren(caseDef, onBare, `${pointer}/cases/${pointerToken(key)}`);
     }
   }
   return node;
 }
 
+/**
+ * Hears each legacy whole-children repeater {@link normalizeArrayChildren} rewrites: the JSON
+ * Pointer of the node holding it, and the repeater.
+ */
+export type BareRepeaterVisitor = (pointer: string, repeater: JxMutableNode) => void;
+
+/** One JSON Pointer reference token (RFC 6901 §4). */
+export function pointerToken(segment: string | number): string {
+  return String(segment).replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
 /**
  * Return the path to the parent element (strips trailing 'children' + index).
  *
@@ -209,7 +221,7 @@ function collectRows(
   skipSelf: boolean,
 ): void {
   // Text node children: bare primitives get a "text" row
-  if (typeof doc === "string" || typeof doc === "number" || typeof doc === "boolean") {
+  if (isString(doc) || isNumber(doc) || isBoolean(doc)) {
     if (!skipSelf) {
       out.push({ depth, node: doc, nodeType: "text", path });
     }
@@ -220,13 +232,13 @@ function collectRows(
   // Recurse into its single template at `[...path, "map"]`. This is reached both when the array is
   // A member of a children array (path `[…, "children", i]`) and the legacy whole-children form
   // (path `[…, "children"]`).
-  if ((doc as JxMutableNode).$prototype === "Array") {
+  if (doc.$prototype === "Array") {
     if (!skipSelf) {
       out.push({ depth, node: doc, nodeType: "map", path });
     }
-    const mapDef = (doc as JxMutableNode).map;
-    if (mapDef && typeof mapDef === "object") {
-      collectRows(mapDef as JxMutableNode, [...path, "map"], depth + 1, out, false);
+    const mapDef = doc.map;
+    if (isNonNullObject(mapDef)) {
+      collectRows(mapDef, [...path, "map"], depth + 1, out, false);
     }
     return;
   }
@@ -247,36 +259,33 @@ function collectRows(
       const childPath = [...path, "children", i];
       collectRows(children[i]!, childPath, depth + 1, out, false);
     }
-  } else if (
-    children &&
-    typeof children === "object" &&
-    (children as JxMutableNode).$prototype === "Array"
-  ) {
+  } else if (isMappedArray(children)) {
     // Legacy whole-children repeater: the array occupies the children slot itself.
+    // SAFETY: The repeater in the children slot is the same repeater node a children member is.
     collectRows(children as JxMutableNode, [...path, "children"], depth + 1, out, false);
   }
 
   // $switch — emit each case as a virtual child
-  if (doc.$switch && doc.cases && typeof doc.cases === "object") {
+  if (doc.$switch && isNonNullObject(doc.cases)) {
     for (const [caseName, caseDef] of Object.entries(doc.cases)) {
       const casePath = [...path, "cases", caseName];
-      if (caseDef && typeof caseDef === "object" && (caseDef as JxMutableNode).$ref) {
+      if (isNonNullObject(caseDef) && caseDef.$ref) {
         out.push({
           depth: depth + 1,
-          node: caseDef as JxMutableNode,
+          node: caseDef,
           nodeType: "case-ref",
           path: casePath,
         });
-      } else if (caseDef && typeof caseDef === "object") {
+      } else if (isNonNullObject(caseDef)) {
         out.push({
           depth: depth + 1,
-          node: caseDef as JxMutableNode,
+          node: caseDef,
           nodeType: "case",
           path: casePath,
         });
         // Recurse into case children — skipSelf, because the "case" row above already stands in for
         // The case node itself (with its own nodeType).
-        collectRows(caseDef as JxMutableNode, casePath, depth + 2, out, true);
+        collectRows(caseDef, casePath, depth + 2, out, true);
       }
     }
   }
@@ -285,10 +294,10 @@ function collectRows(
 /**
  * Get a display label for a node (for layers + overlays).
  *
- * @param {JxMutableNode | null} node
+ * @param {JxMutableNode | null | undefined} node
  * @returns {string}
  */
-export function nodeLabel(node: JxMutableNode | null) {
+export function nodeLabel(node: JxMutableNode | null | undefined) {
   if (!node) {
     return "?";
   }
@@ -306,14 +315,14 @@ export function nodeLabel(node: JxMutableNode | null) {
   }
   if (node.tagName === "slot") {
     const name = node.attributes?.name;
-    return typeof name === "string" && name.trim() ? `slot: ${name.trim()}` : "slot";
+    return isString(name) && name.trim() ? `slot: ${name.trim()}` : "slot";
   }
   /* `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) {
+  if (isString(node.textContent) && node.textContent.length > 0) {
     return `${tag} — ${node.textContent.slice(0, 24)}${suffix}`;
   }
   return tag + suffix;
@@ -340,5 +349,7 @@ export function setProjectState(ps: ProjectState | null) {
  * @returns {ProjectState}
  */
 export function requireProjectState() {
+  /* SAFETY: The contract above restricts callers to paths reached after `setProjectState` installed
+     a project (a project command, a panel that only mounts with one open); nothing here checks it. */
   return projectState as ProjectState;
 }

package/src/store.ts

@@ -9,9 +9,10 @@
 
 // ─── Re-exports from state.js ────────────────────────────────────────────────
 
+import { isFunction, isNonNullObject } from "@jxsuite/schema/guards";
 import { INPUT_DEBOUNCE } from "./ui/timing";
 import type { JxPath } from "./state";
-import type { Tab } from "./tabs/tab";
+import type { Tab, TabUi } from "./tabs/tab";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
 export {
@@ -36,18 +37,38 @@ export {
    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 toolbarEl = null as unknown as HTMLElement;
-export let statusbarEl = null as unknown as HTMLElement;
+
+/* Null until `initShellRefs()`, which `studio.ts` calls at boot right after mounting the shell
+   document; a render asked for before that (a test, or a command run ahead of the shell) reads null. */
+export let activityBar: HTMLElement | null = null;
+export let leftPanel: HTMLElement | null = null;
+export let rightPanel: HTMLElement | null = null;
+export let toolbarEl: HTMLElement | null = null;
+export let statusbarEl: HTMLElement | null = null;
+
+/** The shell region whose `id` is given, or null when the mounted shell has none. */
+function shellRef(id: string): HTMLElement | null {
+  const element = document.querySelector(`#${id}`);
+  return element instanceof HTMLElement ? element : null;
+}
 
 export function initShellRefs() {
-  activityBar = document.querySelector("#activity-bar") as HTMLElement;
-  leftPanel = document.querySelector("#left-panel") as HTMLElement;
-  rightPanel = document.querySelector("#right-panel") as HTMLElement;
-  toolbarEl = document.querySelector("#toolbar") as HTMLElement;
-  statusbarEl = document.querySelector("#statusbar") as HTMLElement;
+  activityBar = shellRef("activity-bar");
+  leftPanel = shellRef("left-panel");
+  rightPanel = shellRef("right-panel");
+  toolbarEl = shellRef("toolbar");
+  statusbarEl = shellRef("statusbar");
+}
+
+/**
+ * A shell region for a caller that cannot work without it. Reading one before `initShellRefs()` has
+ * found it is a boot-order bug, so it throws a TypeError that names the region.
+ */
+export function requireShellRef(ref: HTMLElement | null, id: string): HTMLElement {
+  if (!ref) {
+    throw new TypeError(`#${id} is not in the shell yet; initShellRefs() has not found it`);
+  }
+  return ref;
 }
 
 // ─── Shared constants ────────────────────────────────────────────────────────
@@ -130,6 +151,11 @@ export { stripEventHandlers } from "./utils/strip-events";
 
 const _renderers = new Map<string, () => void>();
 
+/** Whether a renderer's return value is a thenable — an `async` renderer that is still painting. */
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (isNonNullObject(value) || isFunction(value)) && "then" in value && isFunction(value.then);
+}
+
 /**
  * How many registered renderers are mid-paint right now.
  *
@@ -154,9 +180,9 @@ function runRenderer(name: string, fn: () => void) {
   };
   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>;
+    const result = fn();
+    if (isThenable(result)) {
+      pending = result;
     }
   } catch (error) {
     console.error(`Renderer "${name}" failed:`, error);
@@ -165,7 +191,7 @@ function runRenderer(name: string, fn: () => void) {
     done();
     return;
   }
-  pending.then(done, (error: unknown) => {
+  pending.then(done, (error) => {
     console.error(`Renderer "${name}" failed:`, error);
     done();
   });
@@ -232,8 +258,8 @@ export function updateSession(
     selection?: JxPath[];
     hover?: JxPath | null;
     clipboard?: JxMutableNode | null;
-    ui?: Record<string, unknown>;
-    canvas?: Record<string, unknown>;
+    ui?: Partial<TabUi>;
+    canvas?: Partial<Tab["session"]["canvas"]>;
   },
 ) {
   if (tab) {
@@ -241,20 +267,16 @@ export function updateSession(
       tab.session.selection = patch.selection;
     }
     if (patch.hover !== undefined) {
-      tab.session.hover = patch.hover as JxPath | null;
+      tab.session.hover = patch.hover;
     }
     if (patch.clipboard !== undefined) {
-      tab.session.clipboard = patch.clipboard!;
+      tab.session.clipboard = patch.clipboard;
     }
     if (patch.ui) {
-      for (const [k, v] of Object.entries(patch.ui)) {
-        (tab.session.ui as unknown as Record<string, unknown>)[k] = v;
-      }
+      Object.assign(tab.session.ui, patch.ui);
     }
     if (patch.canvas) {
-      for (const [k, v] of Object.entries(patch.canvas)) {
-        (tab.session.canvas as unknown as Record<string, unknown>)[k] = v;
-      }
+      Object.assign(tab.session.canvas, patch.canvas);
     }
   }
 }
@@ -263,12 +285,12 @@ export function updateSession(
  * 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
+ * @param {K} field
+ * @param {TabUi[K]} value
  */
-export function updateUi(tab: Tab | null, field: string, value: unknown) {
+export function updateUi<K extends keyof TabUi>(tab: Tab | null, field: K, value: TabUi[K]) {
   if (tab) {
-    (tab.session.ui as unknown as Record<string, unknown>)[field] = value;
+    tab.session.ui[field] = value;
   }
 }
 
@@ -276,12 +298,10 @@ export function updateUi(tab: Tab | null, field: string, value: unknown) {
  * 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
+ * @param {Partial<Tab["session"]["canvas"]>} patch
  */
-export function updateCanvas(tab: Tab | null, patch: Record<string, unknown>) {
+export function updateCanvas(tab: Tab | null, patch: Partial<Tab["session"]["canvas"]>) {
   if (tab) {
-    for (const [k, v] of Object.entries(patch)) {
-      (tab.session.canvas as Record<string, unknown>)[k] = v;
-    }
+    Object.assign(tab.session.canvas, patch);
   }
 }