@jxsuite/studio 0.28.4 → 0.29.0

package/src/canvas/canvas-perf.ts

@@ -0,0 +1,68 @@
+/**
+ * Canvas render instrumentation. Counts full renders vs surgical patches so tests and users can
+ * verify that hot-path edits do not rebuild the canvas.
+ *
+ * Inspect in the browser via `globalThis.__jxCanvasPerf`; enable per-event logging with
+ * `localStorage["jx-canvas-debug"] = "1"`.
+ */
+
+export interface CanvasPerf {
+  /** Full renderCanvas() invocations (whole-canvas orchestration). */
+  fullRenders: number;
+  /** Individual panel renders (one per breakpoint panel per full render). */
+  panelRenders: number;
+  /** Doc-effect triggers skipped because the change was consumed by the patcher. */
+  skippedFullRenders: number;
+  /** Patch ops applied surgically to the live canvas DOM. */
+  patchedOps: number;
+  /** Isolated subtree re-renders (structural patches). */
+  subtreeRenders: number;
+  /** Patch batches that escalated to a full render. */
+  escalations: number;
+  lastEscalationReason: string;
+}
+
+export const canvasPerf: CanvasPerf = {
+  fullRenders: 0,
+  panelRenders: 0,
+  skippedFullRenders: 0,
+  patchedOps: 0,
+  subtreeRenders: 0,
+  escalations: 0,
+  lastEscalationReason: "",
+};
+
+(globalThis as Record<string, unknown>).__jxCanvasPerf = canvasPerf;
+
+function debugEnabled() {
+  try {
+    return typeof localStorage !== "undefined" && Boolean(localStorage.getItem("jx-canvas-debug"));
+  } catch {
+    return false;
+  }
+}
+
+/** Log a canvas perf event when debug mode is on. */
+export function perfLog(event: string, detail?: unknown) {
+  if (debugEnabled()) {
+    console.debug(`[jx-canvas] ${event}`, detail ?? "");
+  }
+}
+
+/** Record an escalation to full render with its reason. */
+export function recordEscalation(reason: string) {
+  canvasPerf.escalations += 1;
+  canvasPerf.lastEscalationReason = reason;
+  perfLog("escalation", reason);
+}
+
+/** Reset all counters (for tests). */
+export function resetCanvasPerf() {
+  canvasPerf.fullRenders = 0;
+  canvasPerf.panelRenders = 0;
+  canvasPerf.skippedFullRenders = 0;
+  canvasPerf.patchedOps = 0;
+  canvasPerf.subtreeRenders = 0;
+  canvasPerf.escalations = 0;
+  canvasPerf.lastEscalationReason = "";
+}

package/src/canvas/canvas-render.ts

@@ -33,6 +33,7 @@ import {
 } from "../utils/canvas-media";
 import { getEffectiveMedia } from "../site-context";
 import { renderCanvasLive } from "./canvas-live-render";
+import { canvasPerf } from "./canvas-perf";
 import { renderCanvasNode } from "../panels/preview-render";
 import { registerPanelDnD } from "../panels/canvas-dnd";
 import { registerPanelEvents } from "../panels/panel-events";
@@ -57,8 +58,6 @@ interface CanvasRenderCtx {
   getCanvasMode: () => string;
   setCanvasMode: (mode: string) => void;
   openFileFromTree: (path: string) => void;
-  exportFile: () => void;
-  closeFunctionEditor: () => void;
   gitDiffState: GitDiffState | null;
   setGitDiffState: (state: GitDiffState | null) => void;
 }
@@ -100,13 +99,99 @@ async function sourceContent(tab: Tab, lang: string) {
   return JSON.stringify(tab.doc.document, null, 2);
 }
 
+// Double-RAF scheduling so the canvas render yields to higher-priority panel paints first.
+// Concurrent schedule requests within the same frame are deduped.
+let _canvasRafId = 0;
+export function scheduleCanvasRender() {
+  if (_canvasRafId) {
+    return;
+  }
+  _canvasRafId = requestAnimationFrame(() => {
+    _canvasRafId = requestAnimationFrame(() => {
+      _canvasRafId = 0;
+      try {
+        renderCanvas();
+      } catch (error) {
+        console.error("renderCanvas error:", error);
+      }
+    });
+  });
+}
+
+/**
+ * Eject canvasWrap's DOM and Lit render part together. Setting textContent/innerHTML removes the
+ * comment nodes Lit uses as a ChildPart's markers; if the private `_$litPart$` reference is left
+ * behind, the next litRender() reuses a part whose markers are detached from the DOM and throws
+ * "This `ChildPart` has no `parentNode`…". Always eject the markers through this helper so the two
+ * operations can never drift apart.
+ */
+function hardClearCanvasWrap() {
+  canvasWrap.textContent = "";
+  // @ts-expect-error -- _$litPart$ is Lit's private render-part marker, not in the DOM types
+  delete canvasWrap["_$litPart$"];
+}
+
+/**
+ * Tear the canvas all the way back down to a pristine state. Invoked whenever there is no active
+ * tab (e.g. every tab was closed) so the canvas can never get wedged in a half-initialized state:
+ * open editors and observers are disposed, outgoing panel scopes stopped, pending cleanups run, the
+ * Lit render part is ejected cleanly, inline style overrides reset, and `prevCanvasMode` cleared so
+ * the very next render is treated as a fresh mode transition and rebuilds the surface from
+ * scratch.
+ */
+function resetCanvasView() {
+  if (view.functionEditor) {
+    view.functionEditor.dispose();
+    view.functionEditor = null;
+  }
+  if (view.monacoEditor) {
+    view.monacoEditor.getModel()?.dispose();
+    view.monacoEditor.dispose();
+    view.monacoEditor = null;
+  }
+  if (view.centerObserver) {
+    view.centerObserver.disconnect();
+    view.centerObserver = null;
+  }
+  for (const fn of view.canvasDndCleanups) {
+    fn();
+  }
+  view.canvasDndCleanups = [];
+  for (const fn of view.canvasEventCleanups) {
+    fn();
+  }
+  view.canvasEventCleanups = [];
+  for (const p of canvasPanels) {
+    p.renderScope?.stop();
+    p.renderScope = null;
+  }
+  canvasPanels.length = 0;
+
+  hardClearCanvasWrap();
+
+  view.panzoomWrap = null;
+  canvasWrap.style.padding = "";
+  canvasWrap.style.alignItems = "";
+  canvasWrap.style.flexDirection = "";
+  canvasWrap.style.display = "";
+  canvasWrap.style.overflow = "";
+  resetZoomIndicator();
+  dismissBlockActionBar();
+  dismissLinkPopover();
+  dismissContextMenu();
+  dismissSlashMenu();
+  view.prevCanvasMode = null;
+}
+
 export function renderCanvas() {
   const tab = activeTab.value;
   if (!tab) {
+    // No active tab — reset every piece of canvas view state so reopening a file can never inherit
+    // A stale Lit part, a dead Monaco editor, or a mismatched prevCanvasMode (the toxic states that
+    // Previously left the canvas unrenderable until a full reload).
+    resetCanvasView();
     if (!projectState) {
       renderWelcome(canvasWrap);
-    } else {
-      canvasWrap.textContent = "";
     }
     return;
   }
@@ -120,6 +205,7 @@ export function renderCanvas() {
 
   // Advance render generation so stale async renders from the previous cycle bail out
   view.renderGeneration += 1;
+  canvasPerf.fullRenders += 1;
 
   // Detect whether this is a mode transition or a content-only re-render
   const modeChanged = canvasMode !== view.prevCanvasMode;
@@ -130,14 +216,12 @@ export function renderCanvas() {
   // RenderCanvasLive uses atomic clear (innerHTML = "" right before appendChild).
   // @ts-expect-error -- _$litPart$ is Lit's private render-part marker, not in the DOM types
   if (modeChanged && canvasWrap["_$litPart$"]) {
-    canvasWrap.textContent = "";
-    // @ts-expect-error -- _$litPart$ is Lit's private render-part marker, not in the DOM types
-    delete canvasWrap["_$litPart$"];
+    hardClearCanvasWrap();
   }
 
   // Function editor mode: editing a function body in Monaco (JS)
   if (S.ui.editingFunction) {
-    renderFunctionEditor(ctx.closeFunctionEditor);
+    renderFunctionEditor();
     return;
   }
 
@@ -199,6 +283,12 @@ export function renderCanvas() {
 
   // Panel JS objects are cheap — always clear and repopulate from templates.
   // The actual DOM elements are preserved by Lit's diffing on content-only re-renders.
+  // Stop each outgoing panel's render effect scope (and its surgical-subtree child scopes)
+  // So render-time reactive effects don't accumulate across renders.
+  for (const p of canvasPanels) {
+    p.renderScope?.stop();
+    p.renderScope = null;
+  }
   canvasPanels.length = 0;
 
   if (modeChanged) {
@@ -258,12 +348,6 @@ export function renderCanvas() {
     let editorContainer: HTMLDivElement | null = null;
     litRender(
       html`<div class="source-wrap">
-        <div class="source-toolbar">
-          <sp-action-button size="s" @click=${ctx.exportFile}>
-            <sp-icon-export slot="icon"></sp-icon-export>
-            Export
-          </sp-action-button>
-        </div>
         <div
           class="source-editor"
           ${ref((el) => {
@@ -336,7 +420,7 @@ export function renderCanvas() {
           }
         } else if (lang === "json") {
           try {
-            tabNow.doc.document = JSON.parse(editor.getValue());
+            tabNow.doc.document = JSON.parse(editor.getValue()) as JxMutableNode;
             tabNow.doc.dirty = true;
           } catch {
             // Invalid JSON — don't update state
@@ -395,18 +479,17 @@ export function renderCanvas() {
       canvasWrap,
     );
 
-    canvasPanels.push(origPanel as unknown as CanvasPanel);
-    canvasPanels.push(currPanel as unknown as CanvasPanel);
+    canvasPanels.push(origPanel as unknown as CanvasPanel, currPanel as unknown as CanvasPanel);
 
     /** @param {string} content */
-    const parseContent = (content: string) => {
+    const parseContent = (content: string): Promise<JxMutableNode> => {
       const fmtPath = gitDiffState.filePath ?? "";
       if (formatForPath(fmtPath)) {
         return parseSourceForPath(fmtPath, content).then((r) => r.document);
       }
       return Promise.resolve().then(() => {
         try {
-          return JSON.parse(content);
+          return JSON.parse(content) as JxMutableNode;
         } catch {
           return {
             children: [{ tagName: "p", textContent: "Failed to parse" }],
@@ -417,7 +500,7 @@ export function renderCanvas() {
     };
 
     const { featureToggles } = S.ui;
-    Promise.all([
+    void Promise.all([
       parseContent(gitDiffState.originalContent || ""),
       parseContent(gitDiffState.currentContent || ""),
     ]).then(([originalDoc, currentDoc]) => {
@@ -568,7 +651,7 @@ export function renderCanvas() {
   );
 
   for (let i = 0; i < panelEntries.length; i++) {
-    const { panel, activeSet } = panelEntries[i];
+    const { panel, activeSet } = panelEntries[i]!;
     const p = panel as CanvasPanel;
     canvasPanels.push(p);
     if (i === 0) {
@@ -615,7 +698,12 @@ function renderCanvasIntoPanel(
   const docToRender = docOverride || (tab?.doc.document as JxMutableNode);
   const canvas = panel.canvas as HTMLElement;
 
-  renderCanvasLive(gen, docToRender, canvas)
+  canvasPerf.panelRenders += 1;
+  panel.ready = false;
+  panel.liveCtx = null;
+  panel.activeBreakpoints = activeBreakpoints;
+
+  renderCanvasLive(gen, docToRender, canvas, panel)
     .then((scope: Record<string, unknown> | null) => {
       // Skip post-render setup if a newer render has started
       if (gen !== view.renderGeneration) {
@@ -625,6 +713,9 @@ function renderCanvasIntoPanel(
         updateCanvas({ error: null, scope, status: "ready" });
         applyCanvasMediaOverrides(canvas, activeBreakpoints);
         statusMessage("Runtime render OK", 1500);
+        // Panel is patchable only when the live runtime path rendered the real document
+        panel.ready = !docOverride;
+        scheduleStyleTagSweep();
 
         // Apply diff highlighting if in git-diff mode
         if (gitDiffState && docOverride) {
@@ -741,7 +832,7 @@ function applyDiffHighlightToCanvas(
  * @param {Element} canvasEl
  * @param {Set<string>} activeBreakpoints
  */
-function applyCanvasMediaOverrides(canvasEl: Element, activeBreakpoints: Set<string>) {
+export function applyCanvasMediaOverrides(canvasEl: Element, activeBreakpoints: Set<string>) {
   if (activeBreakpoints.size === 0) {
     return;
   }
@@ -764,3 +855,24 @@ function applyCanvasMediaOverrides(canvasEl: Element, activeBreakpoints: Set<str
 export function renderOverlays() {
   overlaysPanel.render();
 }
+
+// ─── Style-tag hygiene ────────────────────────────────────────────────────────
+
+let _sweepTimer: ReturnType<typeof setTimeout> | undefined;
+
+/**
+ * Remove scoped <style> tags whose owner elements are no longer in the document. The runtime emits
+ * one tag per styled element (nested selectors / media rules) and full re-renders orphan the
+ * previous tree's tags. Debounced so in-flight panel renders finish attaching first.
+ */
+function scheduleStyleTagSweep() {
+  clearTimeout(_sweepTimer);
+  _sweepTimer = setTimeout(() => {
+    for (const tag of document.head.querySelectorAll("style[data-jx-owner]")) {
+      const uid = (tag as HTMLElement).dataset.jxOwner;
+      if (uid && !document.querySelector(`[data-jx="${uid}"]`)) {
+        tag.remove();
+      }
+    }
+  }, 250);
+}

package/src/canvas/canvas-subtree-render.ts

@@ -0,0 +1,113 @@
+/// <reference lib="dom" />
+/// <reference lib="dom.iterable" />
+/**
+ * Isolated subtree rendering for surgical canvas patches. Re-renders a single document node into
+ * fresh DOM using the same edit-mode transform, runtime renderer, scope, and path mapper as the
+ * panel's last full render — so the patched DOM is indistinguishable from a full re-render.
+ */
+
+import { elToRenderScope, elToScope, getNodeAtPath, stripEventHandlers } from "../store";
+import { prepareForEditMode } from "../utils/edit-display";
+import { renderNode as runtimeRenderNode } from "@jxsuite/runtime";
+import { effectScope } from "../reactivity";
+import { canvasPerf } from "./canvas-perf";
+
+import type { JxPath } from "../state";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { CanvasPanel, PanelLiveCtx } from "../types";
+
+/**
+ * Render the document node at docPath into a detached DOM subtree for the given panel.
+ *
+ * The scope comes from the parent element's recorded render scope (elToScope), falling back to the
+ * panel's root scope — so $-bindings, $media, and state references resolve exactly as they did in
+ * the full render. Throws when the panel has no live render context.
+ *
+ * @param {CanvasPanel} panel
+ * @param {JxMutableNode} doc Raw (non-reactive) document root
+ * @param {JxPath} docPath
+ * @param {Element} parentEl The rendered parent element (scope source)
+ */
+export function renderSubtree(
+  panel: CanvasPanel,
+  doc: JxMutableNode,
+  docPath: JxPath,
+  parentEl: Element,
+): HTMLElement | Text {
+  const { liveCtx } = panel;
+  if (!liveCtx) {
+    throw new Error("panel-missing-live-ctx");
+  }
+  const node = getNodeAtPath(doc, docPath) as JxMutableNode | string | undefined;
+  if (node === undefined) {
+    throw new Error(`node-not-found:${docPath.join("/")}`);
+  }
+  const def = typeof node === "string" ? node : prepareForEditMode(stripEventHandlers(node));
+  const scope = elToScope.get(parentEl) ?? liveCtx.scope;
+
+  // Render inside an effect scope parented to the panel's render scope: disposable on its own
+  // When the subtree is later replaced/removed, and disposed with the panel on full renders.
+  const render = () => {
+    const subScope = effectScope();
+    const rendered = subScope.run(() =>
+      runtimeRenderNode(def, scope, {
+        _path: docPathToRenderPath(docPath, liveCtx),
+        onNodeCreated: liveCtx.pathMapper,
+      }),
+    )!;
+    if (rendered instanceof HTMLElement) {
+      elToRenderScope.set(rendered, subScope);
+    }
+    return rendered;
+  };
+  const el = panel.renderScope ? panel.renderScope.run(render)! : render();
+  canvasPerf.subtreeRenders += 1;
+
+  // Match full-render edit display: canvas content never receives pointer events directly.
+  if (el instanceof HTMLElement) {
+    el.style.pointerEvents = "none";
+    for (const child of el.querySelectorAll("*")) {
+      (child as HTMLElement).style.pointerEvents = "none";
+    }
+  }
+  return el;
+}
+
+/**
+ * Inverse of makePathMapper's layout-prefix strip: document paths are relative to the page doc,
+ * render paths to the layout-merged doc. ($map/$switch paths never reach here — the patcher
+ * escalates them.)
+ *
+ * @param {JxPath} docPath
+ * @param {PanelLiveCtx} liveCtx
+ */
+function docPathToRenderPath(docPath: JxPath, liveCtx: PanelLiveCtx): (string | number)[] {
+  if (liveCtx.layoutWrapped && liveCtx.pageContentPrefix && docPath[0] === "children") {
+    // Re-apply the slot-container offset stripped by makePathMapper: page child index N renders at
+    // Container index N + offset (offset = leading layout siblings before the <slot>).
+    const [, idx] = docPath;
+    return typeof idx === "number"
+      ? [...liveCtx.pageContentPrefix, idx + (liveCtx.pageContentOffset ?? 0), ...docPath.slice(2)]
+      : [...liveCtx.pageContentPrefix, ...docPath.slice(1)];
+  }
+  return docPath;
+}
+
+/**
+ * The DOM node currently occupying children[index] of the rendered parent, or null when appending
+ * at the end. The runtime renders an optional leading text node (from textContent) followed by one
+ * DOM node per children entry, in order.
+ *
+ * @param {Element} parentEl
+ * @param {JxMutableNode} parentNode
+ * @param {number} index
+ */
+export function domChildReference(
+  parentEl: Element,
+  parentNode: JxMutableNode,
+  index: number,
+): ChildNode | null {
+  const text = parentNode.textContent;
+  const textOffset = text != null && String(text) !== "" ? 1 : 0;
+  return parentEl.childNodes[textOffset + index] ?? null;
+}

package/src/canvas/canvas-utils.ts

@@ -64,12 +64,16 @@ export function canvasPanelTemplate(
   // Which lit runs synchronously during render — before any consumer reads them.
   const panel = {
     _width: width || null,
+    activeBreakpoints: null,
     canvas: null,
     dropLine: null,
     element: null,
+    liveCtx: null,
     mediaName: mediaName || "",
     overlay: null,
     overlayClk: null,
+    ready: false,
+    renderScope: null,
     scrollContainer: null,
     viewport: null,
   } as unknown as CanvasPanel;

package/src/editor/component-inline-edit.ts

@@ -27,16 +27,6 @@ import { dismissSlashMenu, isSlashMenuOpen, showSlashMenu } from "./slash-menu";
 import { renderBlockActionBar } from "../panels/block-action-bar";
 import { defaultDef } from "../panels/shared";
 
-/**
- * @type {{
- *   findCanvasElement: (
- *     path: import("../state").JxPath,
- *     canvasEl: HTMLElement,
- *   ) => HTMLElement | null;
- * } | null}
- */
-let _ctx = null;
-
 /**
  * Initialize the component inline edit module.
  *
@@ -45,12 +35,13 @@ let _ctx = null;
  *     path: import("../state").JxPath,
  *     canvasEl: HTMLElement,
  *   ) => HTMLElement | null;
- * }} ctx
+ * }} _ctx
  */
-export function initComponentInlineEdit(ctx: {
+export function initComponentInlineEdit(_ctx: {
   findCanvasElement: (path: JxPath, canvasEl: HTMLElement) => HTMLElement | null;
 }) {
-  _ctx = ctx;
+  // Public init hook retained for API symmetry; the ctx it once stored is no longer read here.
+  void _ctx;
 }
 
 /**
@@ -278,28 +269,6 @@ function splitParagraph() {
   updateUi("pendingInlineEdit", { mediaName, path: newPath });
 }
 
-function _commitComponentInlineEdit() {
-  if (!view.componentInlineEdit) {
-    return;
-  }
-  const { el, path, originalText } = view.componentInlineEdit;
-  const newText = (el.textContent ?? "").trim();
-
-  cleanupComponentInlineEdit(el);
-
-  const pPath = parentElementPath(path);
-  if (!newText && pPath) {
-    transactDoc(activeTab.value, (t) => mutateRemoveNode(t, path));
-  } else if (newText !== originalText) {
-    transactDoc(activeTab.value, (t) =>
-      mutateUpdateProperty(t, path, "textContent", newText || undefined),
-    );
-  } else {
-    renderOnly("canvas");
-    renderOnly("overlays");
-  }
-}
-
 function cancelComponentInlineEdit() {
   if (!view.componentInlineEdit) {
     return;