@jxsuite/studio 0.23.1 → 0.24.0

package/src/canvas/{canvas-render.js → canvas-render.ts}

@@ -1,3 +1,4 @@
+/// <reference lib="dom" />
 /**
  * Canvas render — extracted from studio.js (Phase 4o). Multi-mode canvas rendering orchestrator:
  * dispatches to manage/settings/source/edit/design/preview rendering paths.
@@ -7,12 +8,12 @@ import { html, render as litRender, nothing } from "lit-html";
 import { ref } from "lit-html/directives/ref.js";
 import * as monaco from "monaco-editor/esm/vs/editor/editor.api.js";
 
-import { canvasWrap, canvasPanels, updateCanvas } from "../store.js";
-import { activeTab } from "../workspace/workspace.js";
-import { view } from "../view.js";
-import { loadMarkdown } from "../files/file-ops.js";
-import { renderWelcome } from "../panels/welcome-screen.js";
-import { projectState } from "../state.js";
+import { canvasWrap, canvasPanels, updateCanvas } from "../store";
+import { activeTab } from "../workspace/workspace";
+import { view } from "../view";
+import { loadMarkdown } from "../files/file-ops";
+import { renderWelcome } from "../panels/welcome-screen";
+import { projectState } from "../state";
 import {
   canvasPanelTemplate,
   applyTransform,
@@ -20,61 +21,47 @@ import {
   renderZoomIndicator,
   resetZoomIndicator,
   updateActivePanelHeaders,
-} from "./canvas-utils.js";
-import { effectiveZoom, overlayBoxDescriptor } from "./canvas-helpers.js";
+} from "./canvas-utils";
+import { effectiveZoom, overlayBoxDescriptor } from "./canvas-helpers";
 import {
   parseMediaEntries,
   activeBreakpointsForWidth,
   collectMediaOverrides,
   applyOverridesToCanvas,
-} from "../utils/canvas-media.js";
-import { getEffectiveMedia } from "../site-context.js";
-import { renderCanvasLive } from "./canvas-live-render.js";
-import { renderCanvasNode } from "../panels/preview-render.js";
-import { registerPanelDnD } from "../panels/canvas-dnd.js";
-import { registerPanelEvents } from "../panels/panel-events.js";
-import { computeDocumentDiff } from "./canvas-diff.js";
-import { updateForcedPseudoPreview } from "../panels/pseudo-preview.js";
-import { findCanvasElement } from "./canvas-helpers.js";
-import { enterComponentInlineEdit } from "../editor/component-inline-edit.js";
-import { renderStylebookMode, refreshStylebookStyles } from "../panels/stylebook-panel.js";
-import { dismissLinkPopover, dismissBlockActionBar } from "../panels/block-action-bar.js";
-import { dismissContextMenu } from "../editor/context-menu.js";
-import { dismissSlashMenu } from "../editor/slash-menu.js";
-import { renderFunctionEditor } from "../panels/editors.js";
-import { mediaDisplayName } from "../panels/shared.js";
-import { statusMessage } from "../panels/statusbar.js";
-import * as overlaysPanel from "../panels/overlays.js";
-
-/** @typedef {import("../panels/canvas-dnd.js").CanvasPanel} CanvasPanel */
-
-/**
- * @typedef {{
- *   filePath: string;
- *   originalContent: string;
- *   currentContent: string;
- *   isMarkdown: boolean;
- *   fileStatus: string;
- *   originalDoc?: JxMutableNode | null;
- *   currentDoc?: JxMutableNode | null;
- *   original?: JxMutableNode | null;
- * }} GitDiffState
- */
-
-/**
- * @typedef {{
- *   getCanvasMode: () => string;
- *   setCanvasMode: (mode: string) => void;
- *   openFileFromTree: (path: string) => void;
- *   exportFile: () => void;
- *   closeFunctionEditor: () => void;
- *   gitDiffState: GitDiffState | null;
- *   setGitDiffState: (state: GitDiffState | null) => void;
- * }} CanvasRenderCtx
- */
+} from "../utils/canvas-media";
+import { getEffectiveMedia } from "../site-context";
+import { renderCanvasLive } from "./canvas-live-render";
+import { renderCanvasNode } from "../panels/preview-render";
+import { registerPanelDnD } from "../panels/canvas-dnd";
+import { registerPanelEvents } from "../panels/panel-events";
+import { computeDocumentDiff } from "./canvas-diff";
+import { updateForcedPseudoPreview } from "../panels/pseudo-preview";
+import { findCanvasElement } from "./canvas-helpers";
+import { enterComponentInlineEdit } from "../editor/component-inline-edit";
+import { renderStylebookMode, refreshStylebookStyles } from "../panels/stylebook-panel";
+import { dismissLinkPopover, dismissBlockActionBar } from "../panels/block-action-bar";
+import { dismissContextMenu } from "../editor/context-menu";
+import { dismissSlashMenu } from "../editor/slash-menu";
+import { renderFunctionEditor } from "../panels/editors";
+import { mediaDisplayName } from "../panels/shared";
+import { statusMessage } from "../panels/statusbar";
+import * as overlaysPanel from "../panels/overlays";
+
+import type { CanvasPanel } from "../panels/canvas-dnd";
+import type { GitDiffState, InlineEditDef } from "../types";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
+interface CanvasRenderCtx {
+  getCanvasMode: () => string;
+  setCanvasMode: (mode: string) => void;
+  openFileFromTree: (path: string) => void;
+  exportFile: () => void;
+  closeFunctionEditor: () => void;
+  gitDiffState: GitDiffState | null;
+  setGitDiffState: (state: GitDiffState | null) => void;
+}
 
-/** @type {CanvasRenderCtx | null} */
-let _ctx = null;
+let _ctx: CanvasRenderCtx | null = null;
 
 let _prevStylebookFilter = "";
 let _prevStylebookCustomizedOnly = false;
@@ -84,7 +71,7 @@ let _prevStylebookCustomizedOnly = false;
  *
  * @param {CanvasRenderCtx} ctx
  */
-export function initCanvasRender(ctx) {
+export function initCanvasRender(ctx: CanvasRenderCtx) {
   _ctx = ctx;
 }
 
@@ -98,7 +85,7 @@ export function renderCanvas() {
     }
     return;
   }
-  const ctx = /** @type {CanvasRenderCtx} */ (_ctx);
+  const ctx = _ctx as CanvasRenderCtx;
   const S = { document: tab.doc.document, ui: tab.session.ui, mode: tab.doc.mode };
   const canvasMode = ctx.getCanvasMode();
 
@@ -227,8 +214,7 @@ export function renderCanvas() {
   if (canvasMode === "source") {
     canvasWrap.style.padding = "0";
     canvasWrap.style.display = "block";
-    /** @type {HTMLDivElement | null} */
-    let editorContainer = null;
+    let editorContainer: HTMLDivElement | null = null;
     litRender(
       html`<div class="source-wrap">
         <div class="source-toolbar">
@@ -240,7 +226,7 @@ export function renderCanvas() {
         <div
           class="source-editor"
           ${ref((el) => {
-            if (el) editorContainer = /** @type {HTMLDivElement} */ (el);
+            if (el) editorContainer = el as HTMLDivElement;
           })}
         ></div>
       </div>`,
@@ -253,25 +239,21 @@ export function renderCanvas() {
       lang === "json" ? JSON.stringify(S.document, null, 2) : S.document?.toString?.() || "";
     const modelUri = monaco.Uri.parse("file:///" + filePath);
     const model = monaco.editor.createModel(content, lang, modelUri);
-    view.monacoEditor = monaco.editor.create(
-      /** @type {HTMLElement} */ (/** @type {unknown} */ (editorContainer)),
-      {
-        model,
-        theme: "vs-dark",
-        automaticLayout: true,
-        minimap: { enabled: false },
-        fontSize: 12,
-        fontFamily: "'SF Mono', 'Fira Code', 'Consolas', monospace",
-        lineNumbers: "on",
-        scrollBeyondLastLine: false,
-        wordWrap: "on",
-        tabSize: 2,
-      },
-    );
+    view.monacoEditor = monaco.editor.create(editorContainer as unknown as HTMLElement, {
+      model,
+      theme: "vs-dark",
+      automaticLayout: true,
+      minimap: { enabled: false },
+      fontSize: 12,
+      fontFamily: "'SF Mono', 'Fira Code', 'Consolas', monospace",
+      lineNumbers: "on",
+      scrollBeyondLastLine: false,
+      wordWrap: "on",
+      tabSize: 2,
+    });
 
     // Debounced sync back to state
-    /** @type {ReturnType<typeof setTimeout> | undefined} */
-    let debounce;
+    let debounce: ReturnType<typeof setTimeout> | undefined;
     view.monacoEditor.onDidChangeModelContent(() => {
       const editor = view.monacoEditor;
       if (!editor) return;
@@ -282,6 +264,7 @@ export function renderCanvas() {
       clearTimeout(debounce);
       debounce = setTimeout(() => {
         const tab = activeTab.value;
+        if (!tab) return;
         if (lang === "json") {
           try {
             tab.doc.document = JSON.parse(editor.getValue());
@@ -332,7 +315,7 @@ export function renderCanvas() {
           class="panzoom-wrap"
           style="transform-origin:0 0"
           ${ref((el) => {
-            if (el) view.panzoomWrap = /** @type {HTMLDivElement} */ (el);
+            if (el) view.panzoomWrap = el as HTMLDivElement;
           })}
         >
           ${origTpl} ${currTpl}
@@ -341,11 +324,11 @@ export function renderCanvas() {
       canvasWrap,
     );
 
-    canvasPanels.push(/** @type {CanvasPanel} */ (origPanel));
-    canvasPanels.push(/** @type {CanvasPanel} */ (currPanel));
+    canvasPanels.push(origPanel as unknown as CanvasPanel);
+    canvasPanels.push(currPanel as unknown as CanvasPanel);
 
     /** @param {string} content */
-    const parseContent = (content) => {
+    const parseContent = (content: string) => {
       if (gitDiffState.isMarkdown) {
         return loadMarkdown(content).then((r) => r.document);
       }
@@ -364,15 +347,15 @@ export function renderCanvas() {
       parseContent(gitDiffState.currentContent || ""),
     ]).then(([originalDoc, currentDoc]) => {
       renderCanvasIntoPanel(
-        /** @type {CanvasPanel} */ (origPanel),
-        new Set(),
+        origPanel as unknown as CanvasPanel,
+        new Set<string>(),
         featureToggles,
         originalDoc,
         gitDiffState,
       );
       renderCanvasIntoPanel(
-        /** @type {CanvasPanel} */ (currPanel),
-        new Set(),
+        currPanel as unknown as CanvasPanel,
+        new Set<string>(),
         featureToggles,
         currentDoc,
         gitDiffState,
@@ -400,16 +383,16 @@ export function renderCanvas() {
     const editTpl = html`
       <div
         class="content-edit-canvas"
-        ${ref((el) => {
-          panel.scrollContainer = /** @type {HTMLElement | null} */ (el || null);
+        ${ref((el: Element | undefined) => {
+          panel.scrollContainer = (el as HTMLElement) || null;
         })}
       >
         <div class="content-edit-column" style="max-width:${baseWidth}px">${panelTpl}</div>
       </div>
     `;
     litRender(editTpl, canvasWrap);
-    canvasPanels.push(/** @type {CanvasPanel} */ (panel));
-    renderCanvasIntoPanel(/** @type {CanvasPanel} */ (panel), new Set(), S.ui.featureToggles);
+    canvasPanels.push(panel as unknown as CanvasPanel);
+    renderCanvasIntoPanel(panel as unknown as CanvasPanel, new Set<string>(), S.ui.featureToggles);
     return;
   }
 
@@ -445,7 +428,7 @@ export function renderCanvas() {
           class="panzoom-wrap"
           style="transform-origin:0 0"
           ${ref((el) => {
-            if (el) view.panzoomWrap = /** @type {HTMLDivElement} */ (el);
+            if (el) view.panzoomWrap = el as HTMLDivElement;
           })}
         >
           ${panelTpl}
@@ -453,8 +436,8 @@ export function renderCanvas() {
       `,
       canvasWrap,
     );
-    canvasPanels.push(/** @type {CanvasPanel} */ (panel));
-    renderCanvasIntoPanel(/** @type {CanvasPanel} */ (panel), new Set(), featureToggles);
+    canvasPanels.push(panel as unknown as CanvasPanel);
+    renderCanvasIntoPanel(panel as unknown as CanvasPanel, new Set<string>(), featureToggles);
     applyTransform();
     if (modeChanged) {
       observeCenterUntilStable();
@@ -494,7 +477,7 @@ export function renderCanvas() {
         class="panzoom-wrap"
         style="transform-origin:0 0"
         ${ref((el) => {
-          if (el) view.panzoomWrap = /** @type {HTMLDivElement} */ (el);
+          if (el) view.panzoomWrap = el as HTMLDivElement;
         })}
       >
         ${panelEntries.map((e) => e.tpl)}
@@ -503,10 +486,15 @@ export function renderCanvas() {
     canvasWrap,
   );
 
-  for (const { panel, activeSet } of panelEntries) {
-    const p = /** @type {CanvasPanel} */ (panel);
+  for (let i = 0; i < panelEntries.length; i++) {
+    const { panel, activeSet } = panelEntries[i];
+    const p = panel as CanvasPanel;
     canvasPanels.push(p);
-    renderCanvasIntoPanel(p, activeSet, featureToggles);
+    if (i === 0) {
+      renderCanvasIntoPanel(p, activeSet, featureToggles);
+    } else {
+      setTimeout(() => renderCanvasIntoPanel(p, activeSet, featureToggles), 0);
+    }
   }
 
   // Highlight active panel header
@@ -535,19 +523,19 @@ export function renderCanvas() {
  *   applies diff highlighting.
  */
 function renderCanvasIntoPanel(
-  panel,
-  activeBreakpoints,
-  featureToggles,
-  docOverride = null,
-  gitDiffState = null,
+  panel: CanvasPanel,
+  activeBreakpoints: Set<string>,
+  featureToggles: Record<string, boolean>,
+  docOverride: JxMutableNode | null = null,
+  gitDiffState: GitDiffState | null = null,
 ) {
   const gen = view.renderGeneration;
   const tab = activeTab.value;
-  const docToRender = /** @type {JxMutableNode} */ (docOverride || tab?.doc.document);
-  const canvas = /** @type {HTMLElement} */ (panel.canvas);
+  const docToRender = docOverride || (tab?.doc.document as JxMutableNode);
+  const canvas = panel.canvas as HTMLElement;
 
   renderCanvasLive(gen, docToRender, canvas)
-    .then((/** @type {Record<string, unknown> | null} */ scope) => {
+    .then((scope: Record<string, unknown> | null) => {
       // Skip post-render setup if a newer render has started
       if (gen !== view.renderGeneration) return;
       if (scope) {
@@ -578,20 +566,18 @@ function renderCanvasIntoPanel(
         renderCanvasNode(docToRender, [], canvas, activeBreakpoints, featureToggles);
       }
       try {
-        registerPanelDnD(/** @type {CanvasPanel} */ (panel));
-      } catch (/** @type {unknown} */ e) {
-        console.warn("registerPanelDnD failed:", /** @type {Error} */ (e).message);
+        registerPanelDnD(panel as unknown as CanvasPanel);
+      } catch (e) {
+        console.warn("registerPanelDnD failed:", (e as Error).message);
       }
-      registerPanelEvents(/** @type {CanvasPanel} */ (panel));
+      registerPanelEvents(panel as unknown as CanvasPanel);
       renderOverlays();
       updateForcedPseudoPreview();
 
       // Process pending inline edit when canvas becomes ready
       const currentTab = activeTab.value;
       if (currentTab?.session.ui?.pendingInlineEdit) {
-        const { path, mediaName: mn } = /** @type {InlineEditDef} */ (
-          currentTab.session.ui.pendingInlineEdit
-        );
+        const { path, mediaName: mn } = currentTab.session.ui.pendingInlineEdit as InlineEditDef;
         currentTab.session.ui.pendingInlineEdit = null;
         const targetPanel = canvasPanels.find((p) => p.mediaName === mn) || canvasPanels[0];
         if (targetPanel) {
@@ -600,18 +586,18 @@ function renderCanvasIntoPanel(
         }
       }
     })
-    .catch((/** @type {unknown} */ err) => {
+    .catch((err: unknown) => {
       if (gen !== view.renderGeneration) return;
       console.warn("renderCanvasLive rejected:", err instanceof Error ? err.message : err);
       updateCanvas({ status: "ready", scope: null, error: null });
       canvas.innerHTML = "";
       renderCanvasNode(docToRender, [], canvas, activeBreakpoints, featureToggles);
       try {
-        registerPanelDnD(/** @type {CanvasPanel} */ (panel));
-      } catch (/** @type {unknown} */ e) {
-        console.warn("registerPanelDnD failed:", /** @type {Error} */ (e).message);
+        registerPanelDnD(panel as unknown as CanvasPanel);
+      } catch (e) {
+        console.warn("registerPanelDnD failed:", (e as Error).message);
       }
-      registerPanelEvents(/** @type {CanvasPanel} */ (panel));
+      registerPanelEvents(panel as unknown as CanvasPanel);
       renderOverlays();
       updateForcedPseudoPreview();
     });
@@ -624,11 +610,14 @@ function renderCanvasIntoPanel(
  * @param {HTMLElement} canvas
  * @param {Map<string, "added" | "removed" | "modified">} diffMap
  */
-function applyDiffHighlightToCanvas(canvas, diffMap) {
+function applyDiffHighlightToCanvas(
+  canvas: HTMLElement,
+  diffMap: Map<string, "added" | "removed" | "modified">,
+) {
   if (!diffMap || diffMap.size === 0) return;
 
   // Walk all elements in canvas and check their data attributes or other markers
-  const walkCanvas = (/** @type {HTMLElement} */ el, /** @type {string} */ path = "") => {
+  const walkCanvas = (el: HTMLElement, /** @type {string} */ path = "") => {
     const pathKey = path || "/";
 
     if (diffMap.has(pathKey)) {
@@ -643,7 +632,7 @@ function applyDiffHighlightToCanvas(canvas, diffMap) {
     for (const child of el.children) {
       const childPath =
         pathKey === "/" ? `children/${childIdx}` : `${pathKey}/children/${childIdx}`;
-      walkCanvas(/** @type {HTMLElement} */ (child), childPath);
+      walkCanvas(child as HTMLElement, childPath);
       childIdx++;
     }
   };
@@ -659,13 +648,13 @@ function applyDiffHighlightToCanvas(canvas, diffMap) {
  * @param {Element} canvasEl
  * @param {Set<string>} activeBreakpoints
  */
-function applyCanvasMediaOverrides(canvasEl, activeBreakpoints) {
+function applyCanvasMediaOverrides(canvasEl: Element, activeBreakpoints: Set<string>) {
   if (!activeBreakpoints.size) return;
   const tab = activeTab.value;
   if (!tab) return;
   const docMedia = getEffectiveMedia(tab.doc.document.$media || {});
   // Build a set of CSS condition texts that match active breakpoints
-  const activeConditions = new Set();
+  const activeConditions = new Set<string>();
   for (const name of activeBreakpoints) {
     if (docMedia[name]) activeConditions.add(docMedia[name]);
   }

package/src/canvas/{canvas-utils.js → canvas-utils.ts}

@@ -1,3 +1,4 @@
+/// <reference lib="dom" />
 /**
  * Canvas panel utilities — extracted from studio.js (Phase 4l). Panzoom infrastructure: panel DOM
  * template creation, centering, transform application, zoom indicator, and fit-to-screen.
@@ -9,24 +10,20 @@ import { classMap } from "lit-html/directives/class-map.js";
 import { styleMap } from "lit-html/directives/style-map.js";
 import { ifDefined } from "lit-html/directives/if-defined.js";
 
-import { renderOnly, updateUi, canvasWrap, canvasPanels } from "../store.js";
-import { activeTab } from "../workspace/workspace.js";
-import { view } from "../view.js";
-import { getLayerSlot } from "../ui/layers.js";
-import { getActivePanel, findCanvasElement } from "./canvas-helpers.js";
+import { renderOnly, updateUi, canvasWrap, canvasPanels } from "../store";
+import { activeTab } from "../workspace/workspace";
+import { view } from "../view";
+import { getLayerSlot } from "../ui/layers";
+import { getActivePanel, findCanvasElement } from "./canvas-helpers";
 
-/**
- * @type {{
- *   getCanvasMode: () => string;
- *   getZoom: () => number;
- *   setZoomDirect: (zoom: number) => void;
- *   renderStylebookOverlays: () => void;
- * }}
- */
-let _ctx;
+let _ctx: {
+  getCanvasMode: () => string;
+  getZoom: () => number;
+  setZoomDirect: (zoom: number) => void;
+  renderStylebookOverlays: () => void;
+};
 
-/** @type {HTMLElement | null} */
-let _zoomIndicatorEl = null;
+let _zoomIndicatorEl: HTMLElement | null = null;
 
 /**
  * Initialize the canvas utils module.
@@ -38,7 +35,12 @@ let _zoomIndicatorEl = null;
  *   renderStylebookOverlays: () => void;
  * }} ctx
  */
-export function initCanvasUtils(ctx) {
+export function initCanvasUtils(ctx: {
+  getCanvasMode: () => string;
+  getZoom: () => number;
+  setZoomDirect: (zoom: number) => void;
+  renderStylebookOverlays: () => void;
+}) {
   _ctx = ctx;
 }
 
@@ -50,21 +52,23 @@ export function initCanvasUtils(ctx) {
  * @param {boolean} fullWidth
  * @param {number | null} width
  */
-export function canvasPanelTemplate(mediaName, label, fullWidth, width = null) {
-  /**
-   * @type {{
-   *   mediaName: string;
-   *   element: HTMLElement | null;
-   *   canvas: HTMLElement | null;
-   *   overlay: HTMLElement | null;
-   *   overlayClk: HTMLElement | null;
-   *   viewport: HTMLElement | null;
-   *   scrollContainer: HTMLElement | null;
-   *   dropLine: HTMLElement | null;
-   *   _width: number | null;
-   * }}
-   */
-  const panel = {
+export function canvasPanelTemplate(
+  mediaName: string | null,
+  label: string | null,
+  fullWidth: boolean,
+  width: number | null = null,
+) {
+  const panel: {
+    mediaName: string;
+    element: HTMLElement | null;
+    canvas: HTMLElement | null;
+    overlay: HTMLElement | null;
+    overlayClk: HTMLElement | null;
+    viewport: HTMLElement | null;
+    scrollContainer: HTMLElement | null;
+    dropLine: HTMLElement | null;
+    _width: number | null;
+  } = {
     mediaName: mediaName || "",
     element: null,
     canvas: null,
@@ -80,7 +84,7 @@ export function canvasPanelTemplate(mediaName, label, fullWidth, width = null) {
       class=${classMap({ "canvas-panel": true, "full-width": fullWidth })}
       data-media=${ifDefined(mediaName !== null ? mediaName : undefined)}
       ${ref((el) => {
-        if (el) panel.element = /** @type {HTMLElement} */ (el);
+        if (el) panel.element = el as HTMLElement;
       })}
     >
       ${label
@@ -99,34 +103,34 @@ export function canvasPanelTemplate(mediaName, label, fullWidth, width = null) {
         class="canvas-panel-viewport"
         style=${styleMap({ width: width && !fullWidth ? `${width}px` : "" })}
         ${ref((el) => {
-          if (el) panel.viewport = /** @type {HTMLElement} */ (el);
+          if (el) panel.viewport = el as HTMLElement;
         })}
       >
         <div
           class="canvas-panel-canvas"
           style=${styleMap({ width: width ? `${width}px` : "" })}
           ${ref((el) => {
-            if (el) panel.canvas = /** @type {HTMLElement} */ (el);
+            if (el) panel.canvas = el as HTMLElement;
           })}
         ></div>
         <div
           class="canvas-panel-overlay"
           ${ref((el) => {
-            if (el) panel.overlay = /** @type {HTMLElement} */ (el);
+            if (el) panel.overlay = el as HTMLElement;
           })}
         >
           <div
             class="canvas-drop-indicator"
             style="display:none"
             ${ref((el) => {
-              if (el) panel.dropLine = /** @type {HTMLElement} */ (el);
+              if (el) panel.dropLine = el as HTMLElement;
             })}
           ></div>
         </div>
         <div
           class="canvas-panel-click"
           ${ref((el) => {
-            if (el) panel.overlayClk = /** @type {HTMLElement} */ (el);
+            if (el) panel.overlayClk = el as HTMLElement;
           })}
         ></div>
       </div>
@@ -231,7 +235,7 @@ export function resetZoomIndicator() {
  * @param {HTMLElement} el
  * @param {{ scrollContainer?: HTMLElement | null }} [panel]
  */
-function _panToEl(el, panel) {
+function _panToEl(el: HTMLElement, panel?: { scrollContainer?: HTMLElement | null }) {
   const wrapRect = canvasWrap.getBoundingClientRect();
   const elRect = el.getBoundingClientRect();
   const elCenterY = elRect.top + elRect.height / 2 - wrapRect.top;
@@ -248,7 +252,7 @@ function _panToEl(el, panel) {
     const targetY = startY + offsetY;
     const start = performance.now();
     const duration = 250;
-    function step(/** @type {number} */ now) {
+    function step(now: number) {
       const t = Math.min((now - start) / duration, 1);
       const ease = t * (2 - t);
       view.panY = startY + (targetY - startY) * ease;
@@ -264,7 +268,7 @@ function _panToEl(el, panel) {
  *
  * @param {(string | number)[]} path
  */
-export function panToElement(path) {
+export function panToElement(path: (string | number)[]) {
   const panel = getActivePanel();
   if (!panel?.canvas) return;
   const el = findCanvasElement(path, panel.canvas);
@@ -277,7 +281,7 @@ export function panToElement(path) {
  *
  * @param {HTMLElement} el
  */
-export function panToCanvasEl(el) {
+export function panToCanvasEl(el: HTMLElement) {
   const panel = getActivePanel();
   _panToEl(el, panel ?? undefined);
 }
@@ -293,8 +297,8 @@ export function renderZoomIndicator() {
     html`
       <div
         class="zoom-indicator"
-        ${ref((el) => {
-          _zoomIndicatorEl = /** @type {HTMLElement | null} */ (el || null);
+        ${ref((el: Element | undefined) => {
+          _zoomIndicatorEl = (el as HTMLElement) || null;
         })}
       >
         <span class="zoom-indicator-action" title="Reset to 100%" @click=${resetZoom}>

package/src/canvas/{nested-site-style.js → nested-site-style.ts}

@@ -6,10 +6,10 @@
  * @param {string} scope - The scoping selector (e.g. `[data-jx-site]`)
  * @returns {string} Generated CSS text
  */
-export function buildNestedSiteCSS(styleObj, scope) {
+export function buildNestedSiteCSS(styleObj: Record<string, any>, scope: string) {
   let css = "";
 
-  function emit(/** @type {string} */ parentSel, /** @type {Record<string, any>} */ rules) {
+  function emit(parentSel: string, rules: Record<string, any>) {
     const props = Object.entries(rules)
       .filter(([, val]) => val === null || typeof val !== "object" || Array.isArray(val))
       .map(([p, val]) => `${camelToKebab(p)}: ${val}`)
@@ -45,6 +45,6 @@ export function buildNestedSiteCSS(styleObj, scope) {
  * @param {string} s
  * @returns {string}
  */
-function camelToKebab(s) {
+function camelToKebab(s: string) {
   return s.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
 }