@jxsuite/studio 0.23.1 → 0.24.0

package/src/{site-context.js → site-context.ts}

@@ -1,3 +1,4 @@
+/// <reference lib="dom" />
 /**
  * Site context helpers - merge site-level definitions with file-level.
  *
@@ -5,8 +6,16 @@
  * definitions merge on top (file wins on conflict).
  */
 
-import { projectState, setProjectState, requireProjectState } from "./store.js";
-import { getPlatform } from "./platform.js";
+import { projectState, setProjectState, requireProjectState } from "./store";
+import { getPlatform } from "./platform";
+
+import type {
+  JxElement,
+  JxMutableNode,
+  JxStyle,
+  JxHeadEntry,
+  ProjectConfig,
+} from "@jxsuite/schema/types";
 
 /**
  * Merge site $media with document $media. Document keys win on conflict.
@@ -15,7 +24,7 @@ import { getPlatform } from "./platform.js";
  *   undefined)
  * @returns {Record<string, string>}
  */
-export function getEffectiveMedia(docMedia) {
+export function getEffectiveMedia(docMedia: Record<string, string> | undefined) {
   const siteMedia = projectState?.projectConfig?.$media;
   if (!siteMedia) return docMedia || {};
   if (!docMedia) return { ...siteMedia };
@@ -29,7 +38,7 @@ export function getEffectiveMedia(docMedia) {
  * @param {JxStyle | undefined} docStyle - The current document's style (may be undefined)
  * @returns {JxStyle}
  */
-export function getEffectiveStyle(docStyle) {
+export function getEffectiveStyle(docStyle: JxStyle | undefined) {
   const siteStyle = projectState?.projectConfig?.style;
   if (!siteStyle) return docStyle || {};
   if (!docStyle) return { ...siteStyle };
@@ -41,7 +50,7 @@ export function getEffectiveStyle(docStyle) {
       typeof merged[k] === "object" &&
       merged[k] !== null
     ) {
-      merged[k] = { .../** @type {JxStyle} */ (merged[k]), .../** @type {JxStyle} */ (v) };
+      merged[k] = { ...(merged[k] as JxStyle), ...(v as JxStyle) };
     } else {
       merged[k] = v;
     }
@@ -56,7 +65,7 @@ export function getEffectiveStyle(docStyle) {
  *   undefined)
  * @returns {Record<string, string>}
  */
-export function getEffectiveImports(docImports) {
+export function getEffectiveImports(docImports: Record<string, string> | undefined) {
   const siteImports = projectState?.projectConfig?.imports;
   if (!siteImports) return docImports || {};
   if (!docImports) return { ...siteImports };
@@ -70,14 +79,12 @@ export function getEffectiveImports(docImports) {
  *   undefined)
  * @returns {(JxElement | string)[]}
  */
-export function getEffectiveElements(docElements) {
+export function getEffectiveElements(docElements?: (JxElement | string)[]) {
   const siteElements = projectState?.projectConfig?.$elements;
   if (!siteElements?.length) return docElements || [];
   if (!docElements?.length) return [...siteElements];
-  /** @type {Set<string>} */
-  const seen = new Set();
-  /** @type {(JxElement | string)[]} */
-  const merged = [];
+  const seen: Set<string> = new Set();
+  const merged: (JxElement | string)[] = [];
   for (const entry of [...siteElements, ...docElements]) {
     const key = typeof entry === "string" ? entry : entry?.$ref;
     if (key && !seen.has(key)) {
@@ -94,14 +101,12 @@ export function getEffectiveElements(docElements) {
  * @param {JxHeadEntry[]} [docHead] - The current document's $head (may be undefined)
  * @returns {JxHeadEntry[]}
  */
-export function getEffectiveHead(docHead) {
+export function getEffectiveHead(docHead?: JxHeadEntry[]) {
   const siteHead = projectState?.projectConfig?.$head;
   if (!siteHead?.length) return docHead || [];
   if (!docHead?.length) return [...siteHead];
-  /** @type {Set<string>} */
-  const seen = new Set();
-  /** @type {JxHeadEntry[]} */
-  const merged = [];
+  const seen: Set<string> = new Set();
+  const merged: JxHeadEntry[] = [];
   for (const entry of [...siteHead, ...docHead]) {
     const key =
       String(entry?.attributes?.href || entry?.attributes?.src || "") || JSON.stringify(entry);
@@ -115,8 +120,7 @@ export function getEffectiveHead(docHead) {
 
 // ─── Layout resolution ──────────────────────────────────────────────────────
 
-/** @type {Map<string, JxMutableNode>} */
-const layoutCache = new Map();
+const layoutCache: Map<string, JxMutableNode> = new Map();
 
 export function invalidateLayoutCache() {
   layoutCache.clear();
@@ -129,7 +133,7 @@ export function invalidateLayoutCache() {
  *   or undefined)
  * @returns {string | null} The layout path, or null if no layout applies
  */
-export function getEffectiveLayoutPath(docLayout) {
+export function getEffectiveLayoutPath(docLayout: string | false | undefined) {
   if (docLayout === false) return null;
   const defaultLayout = projectState?.projectConfig?.defaults?.layout;
   return docLayout || defaultLayout || null;
@@ -141,10 +145,10 @@ export function getEffectiveLayoutPath(docLayout) {
  * @param {string} layoutPath - Relative path to the layout file (e.g., "./layouts/base.json")
  * @returns {Promise<JxMutableNode | null>} The parsed layout document, or null on failure
  */
-export async function resolveLayoutDoc(layoutPath) {
+export async function resolveLayoutDoc(layoutPath: string) {
   const normalized = layoutPath.replace(/^\.\//, "");
   if (layoutCache.has(normalized))
-    return structuredClone(/** @type {JxMutableNode} */ (layoutCache.get(normalized)));
+    return structuredClone(layoutCache.get(normalized) as JxMutableNode);
 
   try {
     const platform = getPlatform();
@@ -165,7 +169,7 @@ export async function resolveLayoutDoc(layoutPath) {
  * @param {JxMutableNode} pageDoc - The page document
  * @returns {JxMutableNode} The merged document
  */
-export function distributePageIntoLayout(layoutDoc, pageDoc) {
+export function distributePageIntoLayout(layoutDoc: JxMutableNode, pageDoc: JxMutableNode) {
   const pageChildren = pageDoc.children ?? [];
   const children = typeof pageChildren === "string" ? [pageChildren] : pageChildren;
 
@@ -193,20 +197,19 @@ export function distributePageIntoLayout(layoutDoc, pageDoc) {
 }
 
 function fillSlots(
-  /** @type {JxMutableNode} */ node,
-  /** @type {Map<string, JxMutableNode[]>} */ named,
-  /** @type {(JxMutableNode | string)[]} */ defaults,
+  node: JxMutableNode,
+  named: Map<string, JxMutableNode[]>,
+  defaults: (JxMutableNode | string)[],
 ) {
   if (!node || typeof node !== "object") return;
   if (!Array.isArray(node.children)) return;
 
-  /** @type {(JxMutableNode | string)[]} */
-  const newChildren = [];
+  const newChildren: (JxMutableNode | string)[] = [];
   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 {JxMutableNode[]} */ (named.get(slotName)));
+        newChildren.push(...(named.get(slotName) as JxMutableNode[]));
         named.delete(slotName);
       } else if (!slotName && defaults.length > 0) {
         newChildren.push(...defaults);
@@ -218,7 +221,7 @@ function fillSlots(
       newChildren.push(child);
     }
   }
-  node.children = /** @type {JxMutableNode[]} */ (newChildren);
+  node.children = newChildren as JxMutableNode[];
 }
 
 /**
@@ -226,12 +229,12 @@ function fillSlots(
  *
  * @param {Partial<ProjectConfig>} patch - Fields to merge into the current projectConfig
  */
-export async function updateSiteConfig(patch) {
+export async function updateSiteConfig(patch: Partial<ProjectConfig>) {
   const platform = getPlatform();
-  const config = /** @type {ProjectConfig} */ ({
+  const config = {
     ...requireProjectState().projectConfig,
     ...patch,
-  });
+  } as ProjectConfig;
   await platform.writeFile("project.json", JSON.stringify(config, null, 2));
   setProjectState({ ...requireProjectState(), projectConfig: config });
 }

package/src/{state.js → state.ts}

@@ -1,3 +1,4 @@
+/// <reference lib="dom" />
 /**
  * State.js — Builder state model and mutation API
  *
@@ -8,39 +9,43 @@
  * = third child of first child
  */
 
-/**
- * @typedef {(string | number)[]} JxPath
- *
- * @typedef {{ document: JxMutableNode; selection: JxPath | null }} HistorySnapshot
- *
- * @typedef {{
- *   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 };
- * }} StudioState
- *
- * @typedef {{
- *   document: JxMutableNode;
- *   selection: JxPath | null;
- *   fileHandle: FileSystemFileHandle | null;
- *   documentPath: string | null;
- *   dirty: boolean;
- *   history: HistorySnapshot[];
- *   historyIndex: number;
- *   mode: string;
- * }} StudioStackFrame
- */
+import type { ProjectState } from "./types";
+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 ───────────────────────────────────────────────────────────
 
@@ -51,10 +56,10 @@
  * @param {JxPath} path
  * @returns {JxMutableNode}
  */
-export function getNodeAtPath(doc, path) {
+export function getNodeAtPath(doc: JxMutableNode, path: JxPath) {
   let node = doc;
   for (const key of path) {
-    if (node == null) return /** @type {JxMutableNode} */ (/** @type {unknown} */ (undefined));
+    if (node == null) return undefined as unknown as JxMutableNode;
     node = node[key];
   }
   return node;
@@ -66,7 +71,7 @@ export function getNodeAtPath(doc, path) {
  * @param {JxPath} path
  * @returns {JxPath | null}
  */
-export function parentElementPath(path) {
+export function parentElementPath(path: JxPath) {
   return path.length >= 2 ? path.slice(0, -2) : null;
 }
 
@@ -76,7 +81,7 @@ export function parentElementPath(path) {
  * @param {JxPath} path
  * @returns {string | number}
  */
-export function childIndex(path) {
+export function childIndex(path: JxPath) {
   return path[path.length - 1];
 }
 
@@ -86,7 +91,7 @@ export function childIndex(path) {
  * @param {JxPath} path
  * @returns {string}
  */
-export function pathKey(path) {
+export function pathKey(path: JxPath) {
   return path.join("/");
 }
 
@@ -97,7 +102,7 @@ export function pathKey(path) {
  * @param {JxPath | null} b
  * @returns {boolean}
  */
-export function pathsEqual(a, b) {
+export function pathsEqual(a: JxPath | null, b: JxPath | null) {
   if (a === b) return true;
   if (!a || !b || a.length !== b.length) return false;
   return a.every((v, i) => v === b[i]);
@@ -110,7 +115,7 @@ export function pathsEqual(a, b) {
  * @param {JxPath} descendant
  * @returns {boolean}
  */
-export function isAncestor(path, descendant) {
+export function isAncestor(path: JxPath, descendant: JxPath) {
   if (path.length > descendant.length) return false;
   return path.every((v, i) => v === descendant[i]);
 }
@@ -133,21 +138,24 @@ export function isAncestor(path, descendant) {
  *   nodeType: string;
  * }[]}
  */
-export function flattenTree(doc, path = [], depth = 0) {
+export type FlatRow = {
+  node: JxMutableNode | string | number | boolean;
+  path: JxPath;
+  depth: number;
+  nodeType: string;
+};
+
+export function flattenTree(
+  doc: JxMutableNode | string | number | boolean,
+  path: JxPath = [],
+  depth: number = 0,
+): FlatRow[] {
   // Text node children: bare primitives get a "text" row
   if (typeof doc === "string" || typeof doc === "number" || typeof doc === "boolean") {
     return [{ node: doc, path, depth, nodeType: "text" }];
   }
 
-  /**
-   * @type {{
-   *   node: JxMutableNode | string | number | boolean;
-   *   path: JxPath;
-   *   depth: number;
-   *   nodeType: string;
-   * }[]}
-   */
-  const rows = [{ node: doc, path, depth, nodeType: "element" }];
+  const rows: FlatRow[] = [{ node: doc, path, depth, nodeType: "element" }];
 
   // Custom component instances without user-authored children are atomic in the layer tree
   if (doc.$props && (doc.tagName || "").includes("-") && !Array.isArray(doc.children)) {
@@ -164,19 +172,18 @@ export function flattenTree(doc, path = [], depth = 0) {
   } else if (
     children &&
     typeof children === "object" &&
-    /** @type {JxMutableNode} */ (children).$prototype === "Array"
+    (children as JxMutableNode).$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 = /** @type {JxMutableNode} */ (children).map;
+    rows.push({
+      node: children as JxMutableNode,
+      path: [...path, "children"],
+      depth: depth + 1,
+      nodeType: "map",
+    });
+    const mapDef = (children as JxMutableNode).map;
     if (mapDef && typeof mapDef === "object") {
-      rows.push(
-        ...flattenTree(
-          /** @type {JxMutableNode} */ (mapDef),
-          [...path, "children", "map"],
-          depth + 2,
-        ),
-      );
+      rows.push(...flattenTree(mapDef as JxMutableNode, [...path, "children", "map"], depth + 2));
     }
   }
 
@@ -184,12 +191,22 @@ 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 {JxMutableNode} */ (caseDef).$ref) {
-        rows.push({ node: caseDef, path: casePath, depth: depth + 1, nodeType: "case-ref" });
+      if (caseDef && typeof caseDef === "object" && (caseDef as JxMutableNode).$ref) {
+        rows.push({
+          node: caseDef as JxMutableNode,
+          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" });
+        rows.push({
+          node: caseDef as JxMutableNode,
+          path: casePath,
+          depth: depth + 1,
+          nodeType: "case",
+        });
         // Recurse into case children (skip the case node itself — already emitted)
-        const caseChildren = flattenTree(caseDef, casePath, depth + 2);
+        const caseChildren = flattenTree(caseDef as JxMutableNode, casePath, depth + 2);
         rows.push(...caseChildren.slice(1));
       }
     }
@@ -204,7 +221,7 @@ export function flattenTree(doc, path = [], depth = 0) {
  * @param {JxMutableNode | null} node
  * @returns {string}
  */
-export function nodeLabel(node) {
+export function nodeLabel(node: JxMutableNode | null) {
   if (!node) return "?";
   // $map container (Repeater)
   if (node.$prototype === "Array") {
@@ -227,7 +244,7 @@ export function nodeLabel(node) {
  * @param {JxMutableNode} doc
  * @returns {StudioState}
  */
-export function createState(doc) {
+export function createState(doc: JxMutableNode): StudioState {
   const initial = { document: doc, selection: null };
   return {
     document: doc,
@@ -264,6 +281,7 @@ export function createState(doc) {
       gitCommitMessage: "", // commit message input
       gitLoading: false, // loading indicator during async ops
       gitError: null, // error message string
+      gitDiffState: null,
       pendingInlineEdit: null, // null | { path, mediaName } — deferred inline edit awaiting canvas readiness
     },
     canvas: {
@@ -283,8 +301,8 @@ export function createState(doc) {
  * @param {Partial<StudioState>} session
  * @returns {StudioState}
  */
-export function toFlat(doc, session) {
-  return /** @type {StudioState} */ ({ ...doc, ...session });
+export function toFlat(doc: Partial<StudioState>, session: Partial<StudioState>) {
+  return { ...doc, ...session } as StudioState;
 }
 
 /**
@@ -293,7 +311,7 @@ export function toFlat(doc, session) {
  * @param {StudioState} S
  * @returns {{ doc: Partial<StudioState>; session: Partial<StudioState> }}
  */
-export function fromFlat(S) {
+export function fromFlat(S: StudioState) {
   const {
     document,
     dirty,
@@ -334,11 +352,10 @@ export function fromFlat(S) {
 //          selectedPath: string|null, searchQuery: string }
 // DirEntry: { name, path, type: "file"|"directory", size, modified }
 
-/** @type {ProjectState | null} */
-export let projectState = null;
+export let projectState: ProjectState | null = null;
 
 /** @param {ProjectState | null} ps */
-export function setProjectState(ps) {
+export function setProjectState(ps: ProjectState | null) {
   projectState = ps;
 }
 
@@ -349,7 +366,7 @@ export function setProjectState(ps) {
  * @returns {ProjectState}
  */
 export function requireProjectState() {
-  return /** @type {ProjectState} */ (projectState);
+  return projectState as ProjectState;
 }
 
 // ─── Frontmatter mutation ───────────────────────────────────────────────────
@@ -363,7 +380,7 @@ export function requireProjectState() {
  * @param {unknown} value
  * @returns {StudioState}
  */
-export function updateFrontmatter(state, field, value) {
+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;
@@ -381,7 +398,7 @@ export function updateFrontmatter(state, field, value) {
  * @param {JxPath | null} path
  * @returns {StudioState}
  */
-export function selectNode(state, path) {
+export function selectNode(state: StudioState, path: JxPath | null) {
   return { ...state, selection: path };
 }
 
@@ -390,7 +407,7 @@ export function selectNode(state, path) {
  * @param {JxPath | null} path
  * @returns {StudioState}
  */
-export function hoverNode(state, path) {
+export function hoverNode(state: StudioState, path: JxPath | null) {
   return { ...state, hover: path };
 }
 
@@ -404,7 +421,7 @@ export function hoverNode(state, path) {
  * @param {string | null} documentPath
  * @returns {StudioState}
  */
-export function pushDocument(state, doc, documentPath) {
+export function pushDocument(state: StudioState, doc: JxMutableNode, documentPath: string | null) {
   const frame = {
     document: state.document,
     selection: state.selection,
@@ -428,7 +445,7 @@ export function pushDocument(state, doc, documentPath) {
  * @param {StudioState} state
  * @returns {StudioState}
  */
-export function popDocument(state) {
+export function popDocument(state: StudioState) {
   if (!state.documentStack || state.documentStack.length === 0) return state;
   const stack = [...state.documentStack];
   const frame = stack.pop();