@jxsuite/studio 4.1.0 → 5.0.0

package/src/panels/data-grid.ts

@@ -9,13 +9,23 @@
  * confirmation before apply), and Open Data Grid — which opens the grid-tab source picker; table
  * editing itself lives in the spreadsheet grid tabs (src/grid/), which replaced the old modal grid
  * at feature parity (paging, cell edit, add/delete row) and added batch save with undo.
+ *
+ * **The markup left.** The row is `surfaces/data-actions.json` and the push plan is
+ * `surfaces/push-plan.json`, mounted into the confirm dialog `ui/layers.ts` already owns — a push
+ * is a confirm, and a second answer to that question is a defect (studio-ui-guidelines.md §12.5).
+ * The actions slot became a MOUNT rather than a template: the section redraws on every keystroke
+ * its form takes, and re-rendering the row each time replaced the button the reader was pressing.
  */
 
-import { html, nothing } from "lit-html";
-import { openModal } from "../ui/layers";
+import { layerHost } from "../ui/layers";
+import { openDialogSurface } from "../surfaces/dialog";
+import { mountDataActionsSurface } from "../surfaces/data-actions";
+import { mountPushPlanSurface } from "../surfaces/push-plan";
 import { dataSurfaceAvailable, pushSchema, testConnection } from "../services/data-service";
 import { openGridSourcePicker } from "../grid/grid-open";
-import type { TemplateResult } from "lit-html";
+import type { DataActionsSurfaceHandle, DataActionsView } from "../surfaces/data-actions";
+import type { DialogSurfaceHandle } from "../surfaces/dialog";
+import type { PushPlanSurfaceHandle, PushPlanView } from "../surfaces/push-plan";
 import type { DataConnectionTestResult, DataPushResult } from "../types";
 import type { SectionActionsContext } from "../settings/contributed-section";
 
@@ -25,6 +35,10 @@ import type { SectionActionsContext } from "../settings/contributed-section";
 export function resetDataGridState(): void {
   actionsState = { pushing: false, testResult: null, testing: null };
   closePushDialog();
+  for (const mount of mounted.values()) {
+    mount.dispose();
+  }
+  mounted.clear();
 }
 
 /** True when the platform serves the data grid. */
@@ -35,10 +49,12 @@ export function isDataGridAvailable(): boolean {
 // ─── Push dialog (dry-run plan confirmation before apply) ─────────────────────
 
 interface PushDialogState {
-  handle: ReturnType<typeof openModal>;
+  handle: DialogSurfaceHandle;
+  /** The plan body, once the dialog's island exists. */
+  plan: PushPlanSurfaceHandle | null;
   connection: string | undefined;
   phase: "loading" | "confirm" | "applying" | "done";
-  plan: DataPushResult | null;
+  dryRun: DataPushResult | null;
   result: DataPushResult | null;
   onDone: () => void;
 }
@@ -47,8 +63,65 @@ let pushDialog: PushDialogState | null = null;
 
 /** Close the push dialog (also part of resetDataGridState). */
 function closePushDialog(): void {
-  pushDialog?.handle.close();
+  const open = pushDialog;
   pushDialog = null;
+  open?.plan?.dispose();
+  open?.handle.close();
+}
+
+/** Give every row of the plan an identity, so a re-projection reconciles rather than rebuilds. */
+function noteRows(texts: readonly string[], prefix: string) {
+  return texts.map((text, index) => ({ key: `${prefix}:${index}`, text }));
+}
+
+/** What the body lists: the dry run until it has been applied, then what actually happened. */
+function planView(state: PushDialogState): PushPlanView {
+  const shown = state.phase === "done" ? state.result : state.dryRun;
+  return {
+    errors: noteRows(shown?.errors ?? [], "error"),
+    steps: (shown?.plan ?? []).map((step, index) => ({
+      key: `${step.kind}:${index}`,
+      kind: step.kind,
+      summary: step.summary,
+    })),
+    warnings: noteRows(shown?.warnings ?? [], "warning"),
+  };
+}
+
+/**
+ * The sentence under the headline.
+ *
+ * The empty plan gets one of its own: "nothing to push" is the answer an author most needs and the
+ * one an empty list says worst.
+ */
+function planMessage(state: PushDialogState): string {
+  if (state.phase === "loading") {
+    return "Compiling plan…";
+  }
+  if (state.phase === "applying") {
+    return "Applying…";
+  }
+  if (state.phase === "done") {
+    return state.result?.applied ? "Schema applied." : "Push failed.";
+  }
+  const steps = state.dryRun?.plan.length ?? 0;
+  const errors = state.dryRun?.errors?.length ?? 0;
+  return steps === 0 && errors === 0 ? "Nothing to push — the schema is up to date." : "";
+}
+
+/** Put the dialog's three moving parts — its buttons, its sentence and its list — in step. */
+function paintPushDialog(): void {
+  const state = pushDialog;
+  if (!state) {
+    return;
+  }
+  const confirmable = state.phase === "confirm" && (state.dryRun?.plan.length ?? 0) > 0;
+  state.handle.update({
+    cancelLabel: state.phase === "done" ? "Close" : "Cancel",
+    confirmLabel: confirmable ? "Apply" : "",
+    message: planMessage(state),
+  });
+  state.plan?.update(planView(state));
 }
 
 /** Start a push: dry-run first, then a confirmation dialog gates the apply. */
@@ -56,109 +129,66 @@ export async function startPush(connection: string | undefined, onDone: () => vo
   if (pushDialog) {
     return;
   }
-  const handle = openModal(html``, { label: "Push Schema", onDismiss: closePushDialog });
-  pushDialog = { connection, handle, onDone, phase: "loading", plan: null, result: null };
-  renderPushDialog();
+  const state: PushDialogState = {
+    connection,
+    dryRun: null,
+    handle: null as unknown as DialogSurfaceHandle,
+    onDone,
+    phase: "loading",
+    plan: null,
+    result: null,
+  };
+  state.handle = openDialogSurface({
+    cancelLabel: "Cancel",
+    confirmLabel: "",
+    headline: connection ? `Push Schema — ${connection}` : "Push Schema",
+    island: (host) => {
+      state.plan = mountPushPlanSurface(host, planView(state));
+    },
+    layer: layerHost("dialog"),
+    message: "Compiling plan…",
+    onCancel: closePushDialog,
+    onClosed: () => {
+      if (pushDialog === state) {
+        closePushDialog();
+      }
+    },
+    onConfirm: () => {
+      void applyPush();
+    },
+    region: "data/push",
+  });
+  pushDialog = state;
+
   const plan = await pushSchema({
     dryRun: true,
     ...(connection === undefined ? {} : { connection }),
   });
-  if (!pushDialog) {
+  if (pushDialog !== state) {
     return;
   }
-  pushDialog.plan = plan;
-  pushDialog.phase = "confirm";
-  renderPushDialog();
+  state.dryRun = plan;
+  state.phase = "confirm";
+  paintPushDialog();
 }
 
 async function applyPush(): Promise<void> {
-  if (!pushDialog) {
+  const state = pushDialog;
+  if (!state) {
     return;
   }
-  pushDialog.phase = "applying";
-  renderPushDialog();
+  state.phase = "applying";
+  paintPushDialog();
   const result = await pushSchema(
-    pushDialog.connection === undefined ? {} : { connection: pushDialog.connection },
+    state.connection === undefined ? {} : { connection: state.connection },
   );
-  if (!pushDialog) {
-    return;
-  }
-  pushDialog.result = result;
-  pushDialog.phase = "done";
-  renderPushDialog();
-  pushDialog.onDone();
-}
-
-function pushDialogBody(state: PushDialogState): TemplateResult {
-  if (state.phase === "loading" || state.phase === "applying") {
-    return html`<div class="push-dialog-status">
-      ${state.phase === "loading" ? "Compiling plan…" : "Applying…"}
-    </div>`;
-  }
-  const shown = state.phase === "done" ? state.result : state.plan;
-  const steps = shown?.plan ?? [];
-  const warnings = shown?.warnings ?? [];
-  const errors = shown?.errors ?? [];
-  return html`
-    <div class="push-dialog-plan">
-      ${
-        state.phase === "done"
-          ? html`<div class="push-dialog-status">
-              ${shown?.applied ? "Schema applied." : "Push failed."}
-            </div>`
-          : steps.length === 0 && errors.length === 0
-            ? html`<div class="push-dialog-status">
-                Nothing to push — the schema is up to date.
-              </div>`
-            : nothing
-      }
-      <ul class="push-dialog-steps">
-        ${steps.map(
-          (step) => html`<li class="push-step push-step-${step.kind}">${step.summary}</li>`,
-        )}
-      </ul>
-      ${warnings.map((w) => html`<div class="push-dialog-warning">${w}</div>`)}
-      ${errors.map((e) => html`<div class="push-dialog-error">${e}</div>`)}
-    </div>
-  `;
-}
-
-function renderPushDialog(): void {
-  if (!pushDialog) {
+  if (pushDialog !== state) {
     return;
   }
-  const state = pushDialog;
-  const confirmable = state.phase === "confirm" && (state.plan?.plan.length ?? 0) > 0;
-  const tpl = html`
-    <sp-underlay open @close=${closePushDialog}></sp-underlay>
-    <div class="settings-modal push-dialog">
-      <div class="settings-modal-header">
-        <h2 class="settings-modal-title">
-          Push Schema${state.connection ? html` — ${state.connection}` : nothing}
-        </h2>
-      </div>
-      <div class="settings-modal-body">${pushDialogBody(state)}</div>
-      <div class="push-dialog-actions">
-        <sp-action-button size="s" class="push-cancel" @click=${closePushDialog}>
-          ${state.phase === "done" ? "Close" : "Cancel"}
-        </sp-action-button>
-        ${
-          confirmable
-            ? html`<sp-action-button
-                size="s"
-                emphasized
-                class="push-apply"
-                @click=${() => {
-                  void applyPush();
-                }}
-                >Apply</sp-action-button
-              >`
-            : nothing
-        }
-      </div>
-    </div>
-  `;
-  state.handle.update(tpl);
+  state.result = result;
+  state.phase = "done";
+  paintPushDialog();
+  state.onDone();
 }
 
 // ─── Contributed-section actions (Test / Push / Open grid) ────────────────────
@@ -172,22 +202,49 @@ interface ActionsState {
 
 let actionsState: ActionsState = { pushing: false, testResult: null, testing: null };
 
+/**
+ * The row mounted in each host the settings machinery has handed us.
+ *
+ * Keyed by the host node, because one settings pane per stage means one host per stage (§4.1) and a
+ * module-level single would make the second pane's row replace the first's.
+ */
+const mounted = new Map<HTMLElement, DataActionsSurfaceHandle>();
+
+/** What the row says right now, for one section and its selected entry. */
+function projectActions(sectionKey: string, selected: string | null): DataActionsView {
+  const { testResult } = actionsState;
+  return {
+    resultOk: testResult?.ok ? "true" : "false",
+    resultState: testResult ? "shown" : "hidden",
+    resultText: testResult
+      ? `${testResult.connection}: ${testResult.ok ? "connected" : (testResult.error ?? "failed")}`
+      : "",
+    resultTitle: testResult?.error ?? "",
+    testDisabled: !selected || actionsState.testing !== null,
+    testLabel: actionsState.testing ? "Testing…" : "Test Connection",
+    testState: sectionKey === "connections" ? "shown" : "hidden",
+  };
+}
+
 /**
  * The actions renderer for a data-domain contributed section, or null when the section is not
  * data-domain or the platform lacks the data routes. Section keys "connections"/"data" are the
  * connector's host wire contract (the same literals the backend's data routes serve) — the generic
  * contributed-section renderer itself stays extension-agnostic.
  *
+ * It is a MOUNT rather than a template: the returned function is handed the host the section
+ * document made, and the second call for the same host projects into the row already there.
+ *
  * @param {string} sectionKey
- * @returns {((ctx: SectionActionsContext) => TemplateResult) | null}
+ * @returns {((host: HTMLElement, ctx: SectionActionsContext) => void) | null}
  */
 export function dataSectionActions(
   sectionKey: string,
-): ((ctx: SectionActionsContext) => TemplateResult) | null {
+): ((host: HTMLElement, ctx: SectionActionsContext) => void) | null {
   if ((sectionKey !== "connections" && sectionKey !== "data") || !dataSurfaceAvailable()) {
     return null;
   }
-  return (ctx) => renderSectionActions(sectionKey, ctx);
+  return (host, ctx) => paintSectionActions(host, sectionKey, ctx);
 }
 
 async function runTest(connection: string, rerender: () => void): Promise<void> {
@@ -200,58 +257,34 @@ async function runTest(connection: string, rerender: () => void): Promise<void>
   rerender();
 }
 
-function renderSectionActions(sectionKey: string, ctx: SectionActionsContext): TemplateResult {
-  const { selected, rerender } = ctx;
-  const { testResult } = actionsState;
+function paintSectionActions(
+  host: HTMLElement,
+  sectionKey: string,
+  ctx: SectionActionsContext,
+): void {
+  const { rerender, selected } = ctx;
+  const existing = mounted.get(host);
+  if (existing) {
+    existing.update(projectActions(sectionKey, selected));
+    return;
+  }
   // On the connections section a selected entry scopes both Test and Push to that connection.
-  const pushTarget = sectionKey === "connections" && selected ? selected : undefined;
-  return html`
-    <div class="data-section-actions">
-      ${
-        sectionKey === "connections"
-          ? html`<sp-action-button
-              size="s"
-              class="data-action-test"
-              ?disabled=${!selected || actionsState.testing !== null}
-              @click=${() => {
-                if (selected) {
-                  void runTest(selected, rerender);
-                }
-              }}
-            >
-              ${actionsState.testing ? "Testing…" : "Test Connection"}
-            </sp-action-button>`
-          : nothing
-      }
-      <sp-action-button
-        size="s"
-        class="data-action-push"
-        @click=${() => {
-          void startPush(pushTarget, rerender);
-        }}
-      >
-        Push Schema
-      </sp-action-button>
-      <sp-action-button
-        size="s"
-        class="data-action-grid"
-        @click=${() => {
-          void openGridSourcePicker();
-        }}
-      >
-        Open Data Grid
-      </sp-action-button>
-      ${
-        testResult
-          ? html`<span
-              class="data-test-result ${testResult.ok ? "ok" : "failed"}"
-              title=${testResult.error ?? ""}
-            >
-              ${testResult.connection}:
-              ${testResult.ok ? "connected" : (testResult.error ?? "failed")}
-            </span>`
-          : nothing
-      }
-    </div>
-  `;
+  const target = () => (sectionKey === "connections" ? (ctx.selected ?? undefined) : undefined);
+  mounted.set(
+    host,
+    mountDataActionsSurface(host, projectActions(sectionKey, selected), {
+      openGrid: () => {
+        void openGridSourcePicker();
+      },
+      push: () => {
+        void startPush(target(), rerender);
+      },
+      test: () => {
+        const connection = ctx.selected;
+        if (connection) {
+          void runTest(connection, rerender);
+        }
+      },
+    }),
+  );
 }

package/src/panels/dnd.ts

@@ -64,16 +64,71 @@ interface DragMonitorDropArgs {
   location: { current: { dropTargets: { data: Record<string, unknown> }[] } };
 }
 
-/** Register DnD on layer rows — called from left-panel.js after render */
+/**
+ * How the drag island addresses the Outline, which is a Jx document and emits no classes.
+ *
+ * `surfaces/panel-outline.json` is the tree; `part` is the only style and query hook a document
+ * offers (`ui.md` §3.1), so these three selectors are the contract between it and this module.
+ *
+ * The two per-row STATES this file writes are `jx-tree-item`'s own, and that is the whole of what
+ * the kit changed here: the element STYLES `data-dragging` and `data-drop` and deliberately BINDS
+ * neither, because a prop mirroring either would be a second writer that a repaint clears mid-drag.
+ * `data-drop-target` is what this file used to write, and it was a name only this file and one
+ * stylesheet rule knew — so the row wore a state the element could not draw. The verb cluster is
+ * `[part="verbs"]` rather than `[part="actions"]` for the neighbouring reason: `actions` is the
+ * name of the ELEMENT's slot container, and a selector that matched both would be answering about
+ * whichever the query happened to reach first.
+ */
+const OUTLINE_ROOT = '[part="outline"]';
+const OUTLINE_ROWS = '[part="row"]';
+const OUTLINE_ACTIONS = '[part="verbs"]';
+
+/**
+ * The frame a queued Outline registration is waiting on, so a second call REPLACES it.
+ *
+ * Null whenever nothing is queued — including from inside the callback, which clears it before it
+ * registers anything, so a completed frame leaves nothing to cancel.
+ */
+let _layersFrame: number | null = null;
+
+/**
+ * Register DnD on the Outline's rows — called from the panel's mount, after every repaint.
+ *
+ * **This function owns `view.dndCleanups`, and that ownership is the fix for 369 warnings a
+ * session.** The caller used to release the list and then call this, which is correct only if the
+ * registrations are made by the time the next caller looks — and they are not: the `rAF` below
+ * defers them past the point the caller believes they happened. Two repaints inside one frame
+ * therefore both found an EMPTY list, released nothing, and queued two registration passes that ran
+ * back to back over the same surviving row elements. Pragmatic-dnd said so, twice per row, forever:
+ * "You have already registered a `draggable` on the same element".
+ *
+ * So the release happens HERE, where the list's contents are known, and it happens at CALL time
+ * rather than in the frame: `view.dndCleanups` then always holds exactly what is registered right
+ * now, and no observer can read a list that has been superseded. The pending frame is cancelled
+ * with it, because a registration nobody has made yet is not one worth making twice.
+ *
+ * The `rAF` itself stays. The Outline's rows arrive when the runtime's reactive scope commits,
+ * which is a microtask the mount cannot await — the surface handle's `ready` promise resolves once,
+ * at the FIRST mount, and every repaint after that settles before the rows it projected exist.
+ * Registering synchronously would walk the previous window's rows.
+ */
 export function registerLayersDnD() {
-  requestAnimationFrame(() => {
-    const container = leftPanel?.querySelector(".layers-container") as HTMLElement | null;
+  if (_layersFrame !== null) {
+    cancelAnimationFrame(_layersFrame);
+  }
+  for (const cleanup of view.dndCleanups) {
+    cleanup();
+  }
+  view.dndCleanups = [];
+  _layersFrame = requestAnimationFrame(() => {
+    _layersFrame = null;
+    const container = leftPanel?.querySelector(OUTLINE_ROOT) as HTMLElement | null;
     if (!container) {
       return;
     }
 
     for (const row of container.querySelectorAll("[data-dnd-row]") as NodeListOf<HTMLElement>) {
-      const rowPath = (row.dataset.path as string)
+      const rowPath = (row.dataset.value as string)
         .split("/")
         .map((s: string) => (/^\d+$/.test(s) ? Math.trunc(Number(s)) : s)) as JxPath;
       const rowDepth = Math.trunc(Number(row.dataset.dndDepth as string)) || 0;
@@ -84,7 +139,7 @@ export function registerLayersDnD() {
         draggable({
           canDrag({ element: _el, input }: DragCanDragArgs) {
             const target = elementAtPoint(input.clientX, input.clientY) as HTMLElement;
-            if (target?.closest(".layer-actions")) {
+            if (target?.closest(OUTLINE_ACTIONS)) {
               return false;
             }
             return true;
@@ -99,14 +154,14 @@ export function registerLayersDnD() {
             disableNativeDragPreview({ nativeSetDragImage });
           },
           onDragStart() {
-            row.classList.add("dragging");
+            row.dataset.dragging = "";
             view.layerDragSourceHeight = row.offsetHeight;
             if (isExpanded) {
               hideDescendantRows(row, container);
             }
           },
           onDrop() {
-            row.classList.remove("dragging");
+            delete row.dataset.dragging;
             if (isExpanded) {
               renderOnly("leftPanel");
             }
@@ -248,7 +303,7 @@ export function registerComponentsDnD() {
 /** Register DnD on element (HTML block) rows */
 export function registerElementsDnD() {
   requestAnimationFrame(() => {
-    const container = leftPanel?.querySelector(".panel-body") as HTMLElement | null;
+    const container = leftPanel?.querySelector('[part="content"]') as HTMLElement | null;
     if (!container) {
       return;
     }
@@ -282,10 +337,10 @@ export function registerElementsDnD() {
  * @param {HTMLElement} container
  */
 function hideDescendantRows(parentRow: HTMLElement, container: HTMLElement) {
-  const prefix = `${parentRow.dataset.path}/`;
-  const rows = container.querySelectorAll(".layers-tree .layer-row");
+  const prefix = `${parentRow.dataset.value}/`;
+  const rows = container.querySelectorAll(OUTLINE_ROWS);
   for (const r of rows) {
-    if ((r as HTMLElement).dataset.path?.startsWith(prefix)) {
+    if ((r as HTMLElement).dataset.value?.startsWith(prefix)) {
       (r as HTMLElement).style.display = "none";
     }
   }
@@ -303,9 +358,9 @@ export function showLayerDropGap(
 ) {
   const instruction = extractInstruction(data);
 
-  // Clear previous drop-target highlight
+  // Clear the previous drop-target mark
   if (view._currentDropTargetRow && view._currentDropTargetRow !== rowEl) {
-    view._currentDropTargetRow.classList.remove("drop-target");
+    delete view._currentDropTargetRow.dataset.drop;
   }
 
   if (!instruction || instruction.type === "instruction-blocked") {
@@ -315,21 +370,21 @@ export function showLayerDropGap(
 
   if (instruction.type === "make-child") {
     clearLayerDropGap(container);
-    rowEl.classList.add("drop-target");
+    rowEl.dataset.drop = "";
     view._currentDropTargetRow = rowEl;
     return;
   }
 
-  rowEl.classList.remove("drop-target");
+  delete rowEl.dataset.drop;
   view._currentDropTargetRow = rowEl;
 
   // Shift rows to create gap
-  const rows = [...container.querySelectorAll(".layers-tree .layer-row")];
+  const rows = [...container.querySelectorAll(OUTLINE_ROWS)];
   const targetIdx = rows.indexOf(rowEl);
   const gap = view.layerDragSourceHeight;
 
   for (let i = 0; i < rows.length; i++) {
-    if ((rows[i] as HTMLElement).classList.contains("dragging")) {
+    if ((rows[i] as HTMLElement).dataset.dragging !== undefined) {
       continue;
     }
     if (instruction.type === "reorder-above") {
@@ -343,13 +398,13 @@ export function showLayerDropGap(
 /** @param {HTMLElement} container */
 export function clearLayerDropGap(container: HTMLElement) {
   if (view._currentDropTargetRow) {
-    view._currentDropTargetRow.classList.remove("drop-target");
+    delete view._currentDropTargetRow.dataset.drop;
     view._currentDropTargetRow = null;
   }
-  const rows = container.querySelectorAll(".layers-tree .layer-row");
+  const rows = container.querySelectorAll(OUTLINE_ROWS);
   for (const r of rows) {
     (r as HTMLElement).style.transform = "";
-    // Also clear `display:none` left by hideDescendantRows. The `.layer-row` div has no `style`
+    // Also clear `display:none` left by hideDescendantRows. The row has no `style`
     // Lit binding, so an imperative style set during the drag survives the post-drop re-render on
     // Whichever row keeps that key — and a move is exactly the edit that hands a key to a different
     // Node. (The rows ARE keyed, by `pathKey`; the earlier form of this note said they were not,

package/src/panels/editors.ts

@@ -5,19 +5,21 @@
  * It used to take over the canvas: `renderFunctionEditor` cleared `canvasWrap`, dropped every
  * canvas panel and mounted Monaco over the stage, so the page whose handler you were writing was
  * the one thing you could not see while writing it. It is a surface of the Bottom dock's **Logic**
- * tab now (plan §12 P8.5); `panels/formula-workspace.ts` owns that tab's record and calls the three
- * exports below — {@link functionEditorTemplate} for the container, {@link syncFunctionEditor} from
- * the panel's `afterRender`, and {@link closeFunctionEditor} for its Close. The canvas keeps
- * rendering the page underneath the dock; `canvas/canvas-render.ts` no longer knows this surface
- * exists.
+ * tab now (plan §12 P8.5); `panels/formula-workspace.ts` owns that tab's record and calls the two
+ * exports below — {@link syncFunctionEditor} from the panel's `afterRender`, and
+ * {@link closeFunctionEditor} for its Close. The container is no longer one of them: the Logic tab
+ * is a Jx document (`surfaces/logic-workspace.json`) and it draws the empty
+ * {@link CODE_HOST_SELECTOR} node itself, which is what an island is (studio-ui-guidelines.md
+ * §9.4). The canvas keeps rendering the page underneath the dock; `canvas/canvas-render.ts` no
+ * longer knows this surface exists.
  *
- * **The mount is driven by the DOM, not by a render call.** A dock tab's body is re-rendered by lit
- * whenever anything it reads changes, and lit will happily replace the container element out from
- * under a live Monaco instance (switching to the formula surface and back does exactly that). So
- * `syncFunctionEditor` asks the one question that matters — is the editor I hold still inside the
- * container I was just handed? — and rebuilds when the answer is no. Re-checking the target string
- * alone, which is all the takeover ever did, would have left a detached editor holding the user's
- * unsaved body.
+ * **The mount is driven by the DOM, not by a render call.** A dock tab's body is re-rendered
+ * whenever anything it reads changes, and a repaint will happily replace the container element out
+ * from under a live Monaco instance (switching to the formula surface and back does exactly that).
+ * So `syncFunctionEditor` asks the one question that matters — is the editor I hold still inside
+ * the container I was just handed? — and rebuilds when the answer is no. Re-checking the target
+ * string alone, which is all the takeover ever did, would have left a detached editor holding the
+ * user's unsaved body.
  *
  * **The move changed the REPAINT rate, not just the teardown rate, and the repaint is the one that
  * runs with the user's hands on the keyboard.** The dock's `afterRender` effect tracks every badge
@@ -32,7 +34,6 @@ import type * as monaco from "monaco-editor";
 import { loadMonaco, mountStillWanted } from "../services/monaco-lazy";
 import { monacoTheme } from "../shell";
 import { isJsonObject } from "@jxsuite/schema/guards";
-import { html } from "lit-html";
 
 import { getNodeAtPath, renderOnly, updateUi } from "../store";
 import { activeTab, tabIsLive } from "../workspace/workspace";
@@ -55,7 +56,6 @@ import type { OxLintDiagnostic } from "../services/code-services";
 import type { JxPrototypeDef } from "@jxsuite/schema/types";
 import type { JxPath } from "../state";
 import type { Tab } from "../tabs/tab";
-import type { TemplateResult } from "lit-html";
 
 type EditingTarget =
   | { type: "def"; defName: string }
@@ -88,10 +88,17 @@ function getFunctionBody(tab: Tab | null | undefined, editing: EditingTarget | n
   return "";
 }
 
-/** Where Monaco goes inside the Logic tab. Empty on purpose — the editor fills it imperatively. */
-export function functionEditorTemplate(): TemplateResult {
-  return html`<div class="fw-code"></div>`;
-}
+/**
+ * The element the Logic tab draws for Monaco to fill.
+ *
+ * `surfaces/logic-workspace.json` renders it and nothing inside it — the island contract of
+ * studio-ui-guidelines.md §9.4 — so the code surface is addressed by `part` rather than by the
+ * `.fw-code` class the lit takeover carried. It is a SELECTOR rather than an announced node on
+ * purpose: this module mounts by asking the painted DOM what is there (see the header), and a node
+ * announced by `onNodeCreated` is one reconcile step short of being in the page, which is exactly
+ * the state an editor that measures its container must not be mounted into.
+ */
+export const CODE_HOST_SELECTOR = '[part="code-host"]';
 
 /**
  * Create, re-target or tear down the Monaco instance for the Logic tab's current body.
@@ -103,7 +110,7 @@ export function functionEditorTemplate(): TemplateResult {
 export function syncFunctionEditor(host: HTMLElement): void {
   const tab = activeTab.value;
   const editing = tab?.session.ui.editingFunction as EditingTarget | null | undefined;
-  const container = editing && tab ? host.querySelector<HTMLElement>(".fw-code") : null;
+  const container = editing && tab ? host.querySelector<HTMLElement>(CODE_HOST_SELECTOR) : null;
   if (!container || !tab || !editing) {
     // Either nothing is open in the code surface, or the formula surface is showing: whichever
     // Monaco instance we hold is detached DOM, and holding it leaks a model plus its listeners.