@jxsuite/studio 0.19.0 → 0.20.0

package/src/settings/schema-field-ui.js

@@ -14,7 +14,7 @@ export const FORMAT_OPTIONS = ["", "image", "date", "color"];
  *   type?: string;
  *   properties?: Record<string, SchemaProperty>;
  *   required?: string[];
- *   items?: any;
+ *   items?: SchemaProperty;
  *   format?: string;
  *   $ref?: string;
  * }} SchemaProperty
@@ -70,7 +70,7 @@ export function detectFieldFormat(schema) {
  * @param {boolean} isRequired
  * @param {FieldHandlers} handlers
  * @param {string[]} [contentTypeNames] - Available content type names for reference target picker
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 export function fieldCardTpl(fieldName, fieldSchema, isRequired, handlers, contentTypeNames = []) {
   const type = detectFieldType(fieldSchema);
@@ -89,16 +89,18 @@ export function fieldCardTpl(fieldName, fieldSchema, isRequired, handlers, conte
           quiet
           value=${fieldName}
           class="schema-field-name-input"
-          @change=${(/** @type {any} */ e) => {
-            const newName = e.target.value.trim();
+          @change=${(/** @type {Event} */ e) => {
+            const target = /** @type {HTMLInputElement} */ (e.target);
+            const newName = target.value.trim();
             if (newName && newName !== fieldName) handlers.onRename(fieldName, newName);
-            else e.target.value = fieldName;
+            else target.value = fieldName;
           }}
-          @keydown=${(/** @type {any} */ e) => {
-            if (e.key === "Enter") e.target.blur();
+          @keydown=${(/** @type {KeyboardEvent} */ e) => {
+            const target = /** @type {HTMLInputElement} */ (e.target);
+            if (e.key === "Enter") target.blur();
             if (e.key === "Escape") {
-              e.target.value = fieldName;
-              e.target.blur();
+              target.value = fieldName;
+              target.blur();
             }
           }}
         ></sp-textfield>
@@ -131,9 +133,12 @@ export function fieldCardTpl(fieldName, fieldSchema, isRequired, handlers, conte
                 size="s"
                 label="Target"
                 value=${refTarget}
-                @change=${(/** @type {any} */ e) => {
+                @change=${(/** @type {Event} */ e) => {
                   if (handlers.onChangeRefTarget)
-                    handlers.onChangeRefTarget(fieldName, e.target.value);
+                    handlers.onChangeRefTarget(
+                      fieldName,
+                      /** @type {HTMLInputElement} */ (e.target).value,
+                    );
                 }}
               >
                 ${contentTypeNames.map((n) => html`<sp-menu-item value=${n}>${n}</sp-menu-item>`)}
@@ -170,7 +175,7 @@ export function fieldCardTpl(fieldName, fieldSchema, isRequired, handlers, conte
  * @param {SchemaProperty} childSchema
  * @param {boolean} isRequired
  * @param {FieldHandlers} handlers
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 function nestedFieldCardTpl(parentName, childName, childSchema, isRequired, handlers) {
   const type = detectFieldType(childSchema);
@@ -184,19 +189,21 @@ function nestedFieldCardTpl(parentName, childName, childSchema, isRequired, hand
           quiet
           value=${childName}
           class="schema-field-name-input"
-          @change=${(/** @type {any} */ e) => {
-            const newName = e.target.value.trim();
+          @change=${(/** @type {Event} */ e) => {
+            const target = /** @type {HTMLInputElement} */ (e.target);
+            const newName = target.value.trim();
             if (newName && newName !== childName && handlers.onRenameNested) {
               handlers.onRenameNested(parentName, childName, newName);
             } else {
-              e.target.value = childName;
+              target.value = childName;
             }
           }}
-          @keydown=${(/** @type {any} */ e) => {
-            if (e.key === "Enter") e.target.blur();
+          @keydown=${(/** @type {KeyboardEvent} */ e) => {
+            const target = /** @type {HTMLInputElement} */ (e.target);
+            if (e.key === "Enter") target.blur();
             if (e.key === "Escape") {
-              e.target.value = childName;
-              e.target.blur();
+              target.value = childName;
+              target.blur();
             }
           }}
         ></sp-textfield>
@@ -240,7 +247,7 @@ function nestedFieldCardTpl(parentName, childName, childSchema, isRequired, hand
  *
  * @param {string} parentName
  * @param {FieldHandlers} handlers
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 function nestedAddFieldTpl(parentName, handlers) {
   return html`
@@ -249,15 +256,18 @@ function nestedAddFieldTpl(parentName, handlers) {
         size="s"
         placeholder="field name"
         class="schema-nested-add-name"
-        @keydown=${(/** @type {any} */ e) => {
+        @keydown=${(/** @type {KeyboardEvent} */ e) => {
           if (e.key === "Enter") {
-            const row = e.target.closest(".schema-nested-add");
-            const name = e.target.value.trim();
-            const typePicker = row?.querySelector("sp-picker");
+            const target = /** @type {HTMLInputElement} */ (e.target);
+            const row = target.closest(".schema-nested-add");
+            const name = target.value.trim();
+            const typePicker = /** @type {HTMLInputElement | null} */ (
+              row?.querySelector("sp-picker")
+            );
             const type = typePicker?.value || "string";
             if (name && handlers.onAddNestedField) {
               handlers.onAddNestedField(parentName, { name, type, required: false });
-              e.target.value = "";
+              target.value = "";
             }
           }
         }}
@@ -267,15 +277,20 @@ function nestedAddFieldTpl(parentName, handlers) {
         size="xs"
         quiet
         title="Add nested field"
-        @click=${(/** @type {any} */ e) => {
-          const row = e.target.closest(".schema-nested-add");
-          const nameInput = /** @type {any} */ (row?.querySelector(".schema-nested-add-name"));
-          const typePicker = /** @type {any} */ (row?.querySelector("sp-picker"));
+        @click=${(/** @type {Event} */ e) => {
+          const target = /** @type {HTMLElement} */ (e.target);
+          const row = target.closest(".schema-nested-add");
+          const nameInput = /** @type {HTMLInputElement | null} */ (
+            row?.querySelector(".schema-nested-add-name")
+          );
+          const typePicker = /** @type {HTMLInputElement | null} */ (
+            row?.querySelector("sp-picker")
+          );
           const name = nameInput?.value?.trim();
           const type = typePicker?.value || "string";
           if (name && handlers.onAddNestedField) {
             handlers.onAddNestedField(parentName, { name, type, required: false });
-            nameInput.value = "";
+            if (nameInput) nameInput.value = "";
           }
         }}
       >
@@ -290,7 +305,7 @@ function nestedAddFieldTpl(parentName, handlers) {
  *
  * @param {string} value
  * @param {(type: string) => void} onChange
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 export function typePickerTpl(value, onChange) {
   return html`
@@ -298,7 +313,8 @@ export function typePickerTpl(value, onChange) {
       size="s"
       label="Type"
       value=${value}
-      @change=${(/** @type {any} */ e) => onChange(e.target.value)}
+      @change=${(/** @type {Event} */ e) =>
+        onChange(/** @type {HTMLInputElement} */ (e.target).value)}
     >
       ${FIELD_TYPES.map((t) => html`<sp-menu-item value=${t}>${t}</sp-menu-item>`)}
     </sp-picker>
@@ -310,7 +326,7 @@ export function typePickerTpl(value, onChange) {
  *
  * @param {string} value
  * @param {(format: string) => void} onChange
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 export function formatPickerTpl(value, onChange) {
   return html`
@@ -318,7 +334,8 @@ export function formatPickerTpl(value, onChange) {
       size="s"
       label="Format"
       value=${value}
-      @change=${(/** @type {any} */ e) => onChange(e.target.value)}
+      @change=${(/** @type {Event} */ e) =>
+        onChange(/** @type {HTMLInputElement} */ (e.target).value)}
     >
       ${FORMAT_OPTIONS.map((f) => html`<sp-menu-item value=${f}>${f || "(none)"}</sp-menu-item>`)}
     </sp-picker>
@@ -330,11 +347,11 @@ export function formatPickerTpl(value, onChange) {
  *
  * @param {{ name: string; type: string; format: string; required: boolean }} state
  * @param {{
- *   onInput: (field: string, value: any) => void;
+ *   onInput: (field: string, value: string | boolean) => void;
  *   onConfirm: () => void;
  *   onCancel: () => void;
  * }} handlers
- * @returns {any}
+ * @returns {import("lit-html").TemplateResult}
  */
 export function addFieldFormTpl(state, handlers) {
   return html`
@@ -343,8 +360,9 @@ export function addFieldFormTpl(state, handlers) {
         size="s"
         placeholder="Field name"
         .value=${state.name}
-        @input=${(/** @type {any} */ e) => handlers.onInput("name", e.target.value)}
-        @keydown=${(/** @type {any} */ e) => {
+        @input=${(/** @type {Event} */ e) =>
+          handlers.onInput("name", /** @type {HTMLInputElement} */ (e.target).value)}
+        @keydown=${(/** @type {KeyboardEvent} */ e) => {
           if (e.key === "Enter") handlers.onConfirm();
           if (e.key === "Escape") handlers.onCancel();
         }}
@@ -356,7 +374,8 @@ export function addFieldFormTpl(state, handlers) {
       <sp-switch
         size="s"
         ?checked=${state.required}
-        @change=${(/** @type {any} */ e) => handlers.onInput("required", e.target.checked)}
+        @change=${(/** @type {Event} */ e) =>
+          handlers.onInput("required", /** @type {HTMLInputElement} */ (e.target).checked)}
       >
         Required
       </sp-switch>

package/src/site-context.js

@@ -5,14 +5,15 @@
  * definitions merge on top (file wins on conflict).
  */
 
-import { projectState, setProjectState } from "./store.js";
+import { projectState, setProjectState, requireProjectState } from "./store.js";
 import { getPlatform } from "./platform.js";
 
 /**
  * Merge site $media with document $media. Document keys win on conflict.
  *
- * @param {any} docMedia - The current document's $media (may be undefined)
- * @returns {any}
+ * @param {Record<string, string> | undefined} docMedia - The current document's $media (may be
+ *   undefined)
+ * @returns {Record<string, string>}
  */
 export function getEffectiveMedia(docMedia) {
   const siteMedia = projectState?.projectConfig?.$media;
@@ -25,8 +26,8 @@ export function getEffectiveMedia(docMedia) {
  * Merge site style with document style. Document keys win on conflict. Nested selector objects
  * (e.g. `& li`) are shallow-merged individually.
  *
- * @param {any} docStyle - The current document's style (may be undefined)
- * @returns {any}
+ * @param {JxStyle | undefined} docStyle - The current document's style (may be undefined)
+ * @returns {JxStyle}
  */
 export function getEffectiveStyle(docStyle) {
   const siteStyle = projectState?.projectConfig?.style;
@@ -40,7 +41,7 @@ export function getEffectiveStyle(docStyle) {
       typeof merged[k] === "object" &&
       merged[k] !== null
     ) {
-      merged[k] = { ...merged[k], ...v };
+      merged[k] = { .../** @type {JxStyle} */ (merged[k]), .../** @type {JxStyle} */ (v) };
     } else {
       merged[k] = v;
     }
@@ -51,8 +52,9 @@ export function getEffectiveStyle(docStyle) {
 /**
  * Merge site imports with document imports. Document keys win on conflict.
  *
- * @param {any} docImports - The current document's imports (may be undefined)
- * @returns {any}
+ * @param {Record<string, string> | undefined} docImports - The current document's imports (may be
+ *   undefined)
+ * @returns {Record<string, string>}
  */
 export function getEffectiveImports(docImports) {
   const siteImports = projectState?.projectConfig?.imports;
@@ -64,8 +66,9 @@ export function getEffectiveImports(docImports) {
 /**
  * Merge site $elements with document $elements. Union with dedup by $ref or string value.
  *
- * @param {any[]} [docElements] - The current document's $elements (may be undefined)
- * @returns {any[]}
+ * @param {(JxElement | string)[]} [docElements] - The current document's $elements (may be
+ *   undefined)
+ * @returns {(JxElement | string)[]}
  */
 export function getEffectiveElements(docElements) {
   const siteElements = projectState?.projectConfig?.$elements;
@@ -73,7 +76,7 @@ export function getEffectiveElements(docElements) {
   if (!docElements?.length) return [...siteElements];
   /** @type {Set<string>} */
   const seen = new Set();
-  /** @type {any[]} */
+  /** @type {(JxElement | string)[]} */
   const merged = [];
   for (const entry of [...siteElements, ...docElements]) {
     const key = typeof entry === "string" ? entry : entry?.$ref;
@@ -88,8 +91,8 @@ export function getEffectiveElements(docElements) {
 /**
  * Merge site $head with document $head. Union with dedup by href/src.
  *
- * @param {any[]} [docHead] - The current document's $head (may be undefined)
- * @returns {any[]}
+ * @param {JxHeadEntry[]} [docHead] - The current document's $head (may be undefined)
+ * @returns {JxHeadEntry[]}
  */
 export function getEffectiveHead(docHead) {
   const siteHead = projectState?.projectConfig?.$head;
@@ -97,10 +100,11 @@ export function getEffectiveHead(docHead) {
   if (!docHead?.length) return [...siteHead];
   /** @type {Set<string>} */
   const seen = new Set();
-  /** @type {any[]} */
+  /** @type {JxHeadEntry[]} */
   const merged = [];
   for (const entry of [...siteHead, ...docHead]) {
-    const key = entry?.attributes?.href || entry?.attributes?.src || JSON.stringify(entry);
+    const key =
+      String(entry?.attributes?.href || entry?.attributes?.src || "") || JSON.stringify(entry);
     if (!seen.has(key)) {
       seen.add(key);
       merged.push(entry);
@@ -111,7 +115,7 @@ export function getEffectiveHead(docHead) {
 
 // ─── Layout resolution ──────────────────────────────────────────────────────
 
-/** @type {Map<string, any>} */
+/** @type {Map<string, JxMutableNode>} */
 const layoutCache = new Map();
 
 export function invalidateLayoutCache() {
@@ -121,7 +125,8 @@ export function invalidateLayoutCache() {
 /**
  * Determine the effective layout path for a document.
  *
- * @param {any} docLayout - The document's $layout value (string path, false, or undefined)
+ * @param {string | false | undefined} docLayout - The document's $layout value (string path, false,
+ *   or undefined)
  * @returns {string | null} The layout path, or null if no layout applies
  */
 export function getEffectiveLayoutPath(docLayout) {
@@ -134,11 +139,12 @@ export function getEffectiveLayoutPath(docLayout) {
  * Resolve a layout document by path. Fetches and caches the parsed JSON.
  *
  * @param {string} layoutPath - Relative path to the layout file (e.g., "./layouts/base.json")
- * @returns {Promise<any | null>} The parsed layout document, or null on failure
+ * @returns {Promise<JxMutableNode | null>} The parsed layout document, or null on failure
  */
 export async function resolveLayoutDoc(layoutPath) {
   const normalized = layoutPath.replace(/^\.\//, "");
-  if (layoutCache.has(normalized)) return structuredClone(layoutCache.get(normalized));
+  if (layoutCache.has(normalized))
+    return structuredClone(/** @type {JxMutableNode} */ (layoutCache.get(normalized)));
 
   try {
     const platform = getPlatform();
@@ -155,9 +161,9 @@ export async function resolveLayoutDoc(layoutPath) {
  * Distribute page children into a layout document's <slot> elements. Returns the merged document
  * with page content injected into slots.
  *
- * @param {any} layoutDoc - Deep-cloned layout document
- * @param {any} pageDoc - The page document
- * @returns {any} The merged document
+ * @param {JxMutableNode} layoutDoc - Deep-cloned layout document
+ * @param {JxMutableNode} pageDoc - The page document
+ * @returns {JxMutableNode} The merged document
  */
 export function distributePageIntoLayout(layoutDoc, pageDoc) {
   const pageChildren = pageDoc.children ?? [];
@@ -187,19 +193,20 @@ export function distributePageIntoLayout(layoutDoc, pageDoc) {
 }
 
 function fillSlots(
-  /** @type {any} */ node,
-  /** @type {Map<string, any[]>} */ named,
-  /** @type {any[]} */ defaults,
+  /** @type {JxMutableNode} */ node,
+  /** @type {Map<string, JxMutableNode[]>} */ named,
+  /** @type {(JxMutableNode | string)[]} */ defaults,
 ) {
   if (!node || typeof node !== "object") return;
   if (!Array.isArray(node.children)) return;
 
+  /** @type {(JxMutableNode | string)[]} */
   const newChildren = [];
   for (const child of node.children) {
     if (child && typeof child === "object" && child.tagName === "slot") {
       const slotName = child.attributes?.name;
       if (slotName && named.has(slotName)) {
-        newChildren.push(.../** @type {any[]} */ (named.get(slotName)));
+        newChildren.push(.../** @type {JxMutableNode[]} */ (named.get(slotName)));
         named.delete(slotName);
       } else if (!slotName && defaults.length > 0) {
         newChildren.push(...defaults);
@@ -207,21 +214,24 @@ function fillSlots(
         newChildren.push(...child.children);
       }
     } else {
-      fillSlots(child, named, defaults);
+      if (typeof child !== "string") fillSlots(child, named, defaults);
       newChildren.push(child);
     }
   }
-  node.children = newChildren;
+  node.children = /** @type {JxMutableNode[]} */ (newChildren);
 }
 
 /**
  * Update the project's project.json with a partial patch and persist to disk.
  *
- * @param {Record<string, any>} patch - Fields to merge into the current projectConfig
+ * @param {Partial<ProjectConfig>} patch - Fields to merge into the current projectConfig
  */
 export async function updateSiteConfig(patch) {
   const platform = getPlatform();
-  const config = { ...projectState.projectConfig, ...patch };
+  const config = /** @type {ProjectConfig} */ ({
+    ...requireProjectState().projectConfig,
+    ...patch,
+  });
   await platform.writeFile("project.json", JSON.stringify(config, null, 2));
-  setProjectState({ ...projectState, projectConfig: config });
+  setProjectState({ ...requireProjectState(), projectConfig: config });
 }

package/src/state.js

@@ -9,28 +9,37 @@
  */
 
 /**
- * @typedef {Record<string, any>} JxNode
- *
  * @typedef {(string | number)[]} JxPath
  *
- * @typedef {{ document: JxNode; selection: JxPath | null }} HistorySnapshot
+ * @typedef {{ document: JxMutableNode; selection: JxPath | null }} HistorySnapshot
  *
  * @typedef {{
- *   document: JxNode;
+ *   document: JxMutableNode;
  *   selection: JxPath | null;
  *   hover: JxPath | null;
  *   history: HistorySnapshot[];
  *   historyIndex: number;
  *   dirty: boolean;
- *   fileHandle: any;
+ *   fileHandle: FileSystemFileHandle | null;
  *   documentPath: string | null;
- *   documentStack: any[];
+ *   documentStack: StudioStackFrame[];
  *   handlersSource: string | null;
  *   mode: string;
- *   content: { frontmatter: Record<string, any> };
- *   ui: Record<string, any>;
- *   canvas: { status: string; scope: any; error: string | null };
+ *   content: { frontmatter: Record<string, unknown> };
+ *   ui: Record<string, unknown>;
+ *   canvas: { status: string; scope: Record<string, unknown> | null; error: string | null };
  * }} StudioState
+ *
+ * @typedef {{
+ *   document: JxMutableNode;
+ *   selection: JxPath | null;
+ *   fileHandle: FileSystemFileHandle | null;
+ *   documentPath: string | null;
+ *   dirty: boolean;
+ *   history: HistorySnapshot[];
+ *   historyIndex: number;
+ *   mode: string;
+ * }} StudioStackFrame
  */
 
 // ─── Path utilities ───────────────────────────────────────────────────────────
@@ -38,14 +47,14 @@
 /**
  * Walk the document tree and return the node at the given path.
  *
- * @param {any} doc
+ * @param {JxMutableNode} doc
  * @param {JxPath} path
- * @returns {any}
+ * @returns {JxMutableNode}
  */
 export function getNodeAtPath(doc, path) {
   let node = doc;
   for (const key of path) {
-    if (node == null) return undefined;
+    if (node == null) return /** @type {JxMutableNode} */ (/** @type {unknown} */ (undefined));
     node = node[key];
   }
   return node;
@@ -114,10 +123,15 @@ export function isAncestor(path, descendant) {
  *
  * NodeType: 'element' (default) | 'map' | 'case' | 'case-ref'
  *
- * @param {any} doc
+ * @param {JxMutableNode | string | number | boolean} doc
  * @param {JxPath} [path]
  * @param {number} [depth]
- * @returns {{ node: any; path: JxPath; depth: number; nodeType: string }[]}
+ * @returns {{
+ *   node: JxMutableNode | string | number | boolean;
+ *   path: JxPath;
+ *   depth: number;
+ *   nodeType: string;
+ * }[]}
  */
 export function flattenTree(doc, path = [], depth = 0) {
   // Text node children: bare primitives get a "text" row
@@ -125,7 +139,14 @@ export function flattenTree(doc, path = [], depth = 0) {
     return [{ node: doc, path, depth, nodeType: "text" }];
   }
 
-  /** @type {{ node: any; path: JxPath; depth: number; nodeType: string }[]} */
+  /**
+   * @type {{
+   *   node: JxMutableNode | string | number | boolean;
+   *   path: JxPath;
+   *   depth: number;
+   *   nodeType: string;
+   * }[]}
+   */
   const rows = [{ node: doc, path, depth, nodeType: "element" }];
 
   // Custom component instances without user-authored children are atomic in the layer tree
@@ -140,12 +161,22 @@ export function flattenTree(doc, path = [], depth = 0) {
       const childPath = [...path, "children", i];
       rows.push(...flattenTree(children[i], childPath, depth + 1));
     }
-  } else if (children && typeof children === "object" && children.$prototype === "Array") {
+  } else if (
+    children &&
+    typeof children === "object" &&
+    /** @type {JxMutableNode} */ (children).$prototype === "Array"
+  ) {
     // $map — emit the map container, then recurse into the template
     rows.push({ node: children, path: [...path, "children"], depth: depth + 1, nodeType: "map" });
-    const mapDef = children.map;
+    const mapDef = /** @type {JxMutableNode} */ (children).map;
     if (mapDef && typeof mapDef === "object") {
-      rows.push(...flattenTree(mapDef, [...path, "children", "map"], depth + 2));
+      rows.push(
+        ...flattenTree(
+          /** @type {JxMutableNode} */ (mapDef),
+          [...path, "children", "map"],
+          depth + 2,
+        ),
+      );
     }
   }
 
@@ -153,7 +184,7 @@ export function flattenTree(doc, path = [], depth = 0) {
   if (doc.$switch && doc.cases && typeof doc.cases === "object") {
     for (const [caseName, caseDef] of Object.entries(doc.cases)) {
       const casePath = [...path, "cases", caseName];
-      if (caseDef && typeof caseDef === "object" && /** @type {any} */ (caseDef).$ref) {
+      if (caseDef && typeof caseDef === "object" && /** @type {JxMutableNode} */ (caseDef).$ref) {
         rows.push({ node: caseDef, path: casePath, depth: depth + 1, nodeType: "case-ref" });
       } else if (caseDef && typeof caseDef === "object") {
         rows.push({ node: caseDef, path: casePath, depth: depth + 1, nodeType: "case" });
@@ -170,7 +201,7 @@ export function flattenTree(doc, path = [], depth = 0) {
 /**
  * Get a display label for a node (for layers + overlays).
  *
- * @param {any} node
+ * @param {JxMutableNode | null} node
  * @returns {string}
  */
 export function nodeLabel(node) {
@@ -193,7 +224,7 @@ export function nodeLabel(node) {
 // ─── State factory ────────────────────────────────────────────────────────────
 
 /**
- * @param {any} doc
+ * @param {JxMutableNode} doc
  * @returns {StudioState}
  */
 export function createState(doc) {
@@ -248,19 +279,19 @@ export function createState(doc) {
 /**
  * Compose a flat StudioState from separate doc and session slices.
  *
- * @param {any} doc
- * @param {any} session
+ * @param {Partial<StudioState>} doc
+ * @param {Partial<StudioState>} session
  * @returns {StudioState}
  */
 export function toFlat(doc, session) {
-  return { ...doc, ...session };
+  return /** @type {StudioState} */ ({ ...doc, ...session });
 }
 
 /**
  * Decompose a flat StudioState into doc and session slices.
  *
  * @param {StudioState} S
- * @returns {{ doc: any; session: any }}
+ * @returns {{ doc: Partial<StudioState>; session: Partial<StudioState> }}
  */
 export function fromFlat(S) {
   const {
@@ -303,14 +334,24 @@ export function fromFlat(S) {
 //          selectedPath: string|null, searchQuery: string }
 // DirEntry: { name, path, type: "file"|"directory", size, modified }
 
-/** @type {any} */
+/** @type {ProjectState | null} */
 export let projectState = null;
 
-/** @param {any} ps */
+/** @param {ProjectState | null} ps */
 export function setProjectState(ps) {
   projectState = ps;
 }
 
+/**
+ * Return the current project state, asserting it is non-null. Only call when a project is known to
+ * be loaded.
+ *
+ * @returns {ProjectState}
+ */
+export function requireProjectState() {
+  return /** @type {ProjectState} */ (projectState);
+}
+
 // ─── Frontmatter mutation ───────────────────────────────────────────────────
 
 /**
@@ -319,7 +360,7 @@ export function setProjectState(ps) {
  *
  * @param {StudioState} state
  * @param {string} field
- * @param {any} value
+ * @param {unknown} value
  * @returns {StudioState}
  */
 export function updateFrontmatter(state, field, value) {
@@ -359,7 +400,7 @@ export function hoverNode(state, path) {
  * Push current document onto the stack and switch to editing a new document.
  *
  * @param {StudioState} state
- * @param {any} doc
+ * @param {JxMutableNode} doc
  * @param {string | null} documentPath
  * @returns {StudioState}
  */