@jxsuite/studio 4.1.0 → 5.0.0

package/src/panels/bottom-dock.ts

@@ -37,7 +37,7 @@
  * (`panels/problems-panel.ts`) and registered from here, like every other tab of this dock.
  */
 
-import { html, render as litRender, nothing } from "lit-html";
+import { render as litRender, nothing } from "lit-html";
 import { effect, effectScope } from "../reactivity";
 import {
   BOTTOM_TAB_IDS,
@@ -53,11 +53,12 @@ import { getPanel, isPanelVisible, listPanels, panelContext } from "./panel-regi
 import { registerActivityPanel } from "./activity-panel";
 import { registerProblemsPanel } from "./problems-panel";
 import { logicTarget, registerLogicPanel, revealLogicPanel } from "./formula-workspace";
-import { renderEmptyState } from "./empty-state";
+import { emptyState } from "../surfaces/empty-state";
+import { mountBottomDockSurface } from "../surfaces/bottom-dock";
+import type { BottomDockHandle, BottomDockValues } from "../surfaces/bottom-dock";
 import type { CommandContext } from "../commands/context";
 import type { NavigatorPanelContext, NavigatorPanelDeps, PanelRecord } from "./panel-registry";
 import type { EffectScope } from "@vue/reactivity";
-import type { TemplateResult } from "lit-html";
 
 /** The dock's host — a bare `<div id>` in index.html, like every other shell host. */
 export const BOTTOM_DOCK_SELECTOR = "#bottom-dock";
@@ -152,54 +153,46 @@ export function bottomTabLabel(panel: PanelRecord, ctx: CommandContext): string
   return badge === null || badge === 0 || badge === "" ? panel.title : `${panel.title} ${badge}`;
 }
 
-/** The dock, as a template. Exported so a test can render it without a host. */
-export function bottomDockTemplate(ctx: CommandContext = panelContext()): TemplateResult {
-  const panels = visibleBottomPanels(ctx);
+/**
+ * What the strip says right now: one row per admitted tab, and which of them is showing.
+ *
+ * Exported so a test can read the projection without a host — the same reason the template it
+ * replaced was exported, and a stronger one: this is a plain object, so an assertion about a tab's
+ * label or the selected id is a comparison rather than a DOM walk.
+ *
+ * @param {CommandContext} [ctx]
+ * @returns {BottomDockValues}
+ */
+export function bottomDockValues(ctx: CommandContext = panelContext()): BottomDockValues {
   const active = activeBottomPanel(ctx);
-  const body = active
-    ? active.render(bottomContext())
-    : renderEmptyState({ message: "Nothing to show here yet." });
-  return html`
-    <div class="bd-strip">
-      <sp-tabs
-        class="bd-tabs"
-        quiet
-        size="s"
-        selected=${active?.id ?? ""}
-        @change=${(e: Event & { target: { selected: string } }) => {
-          const { selected } = e.target;
-          if (selected && selected !== active?.id) {
-            setBottomTab(selected);
-          }
-        }}
-      >
-        ${panels.map(
-          (panel) => html`<sp-tab value=${panel.id} label=${bottomTabLabel(panel, ctx)}></sp-tab>`,
-        )}
-      </sp-tabs>
-      <button
-        class="bd-close"
-        title="Close the Bottom dock"
-        aria-label="Close the Bottom dock"
-        @click=${() => {
-          setDockCollapsed("bottom", true);
-        }}
-      >
-        <span aria-hidden="true">×</span>
-      </button>
-    </div>
-    ${
-      active
-        ? html`<div class="bd-body" data-jx-region=${bottomPanelRegion(active.id)}>${body}</div>`
-        : html`<div class="bd-body">${body}</div>`
-    }
-  `;
+  return {
+    bodyRegion: active ? bottomPanelRegion(active.id) : "",
+    tab: active?.id ?? "",
+    tabId: active ? `bottom-dock-tab-${active.id}` : "",
+    tabs: visibleBottomPanels(ctx).map((panel) => ({
+      key: panel.id,
+      label: bottomTabLabel(panel, ctx),
+      tabId: `bottom-dock-tab-${panel.id}`,
+    })),
+  };
 }
 
 let _scope: EffectScope | null = null;
 
 let _host: HTMLElement | null = null;
 
+/** The mounted chrome document, live only while the dock is open. */
+let _dock: BottomDockHandle | null = null;
+
+/**
+ * The `[part="dock-body"]` the document announced, or null while nothing is mounted.
+ *
+ * Held rather than re-queried: it is the one element every tab's `afterRender` is measured against,
+ * and a selector that returned a different node between the paint and the hook would hand a tab a
+ * body it had not been painted into.
+ */
+let _body: HTMLElement | null = null;
+
 /**
  * The Logic target the dock has already revealed itself for.
  *
@@ -237,13 +230,79 @@ export function renderBottomDock(): void {
   }
   if (shell.docks.bottom.collapsed) {
     _host.removeAttribute(REGION_ATTR);
-    litRender(nothing, _host);
+    /* The chrome is taken down rather than hidden, and `#bottom-dock:empty { display: none }` is
+       why: the shell's own sheet keeps a dock with nothing in it out of the grid, so a document
+       left mounted behind a `hidden` attribute would make that rule permanently unmatchable. Disposing also
+       makes the collapsed branch mean what it says to a tab — every one of them is handed the
+       emptied HOST, which is the fourth of the four ways Logic stops being on screen. */
+    _dock?.dispose();
+    _dock = null;
+    _body = null;
     runAfterRender(_host);
     return;
   }
   _host.setAttribute(REGION_ATTR, "dock.bottom");
-  litRender(bottomDockTemplate(), _host);
-  runAfterRender(_host.querySelector<HTMLElement>(".bd-body") ?? _host);
+  if (!_dock) {
+    /* The mount is asynchronous (the kit has to be defined first), so the body is painted from the
+       announcement rather than from here — `onBody` fires while the host is still inside the
+       runtime's fragment, one append before the strip is in the page. */
+    _dock = mountBottomDockSurface(
+      _host,
+      bottomDockValues(),
+      {
+        closeDock: () => {
+          setDockCollapsed("bottom", true);
+        },
+        selectTab: (id) => {
+          if (id !== "" && id !== activeBottomPanel()?.id) {
+            setBottomTab(id);
+          }
+        },
+      },
+      {
+        onBody: (host) => {
+          _body = host;
+          /* A MICROTASK, not this call. `onNodeCreated` fires the moment the element is CONSTRUCTED
+             — the runtime applies its attributes on the next line — so a tab's `afterRender` run
+             from here would be handed a body with no `part` and no `data-jx-region` on it yet, and
+             every tab that identifies its own container by attribute would decide it is off screen.
+             By the time a microtask runs, the synchronous render that created this node has
+             finished and the element is fully written. */
+          queueMicrotask(() => {
+            if (_body === host) {
+              paintBody();
+            }
+          });
+        },
+      },
+    );
+    return;
+  }
+  _dock.update(bottomDockValues());
+  paintBody();
+}
+
+/**
+ * Draw the selected tab into the one body the document leaves empty, and tell every tab about it.
+ *
+ * The record's `render` returns a lit template — that is what a `PanelRecord` is — so this is the
+ * one place lit still paints inside the dock, into an island the document owns and never touches
+ * (studio-ui-guidelines.md §9.4). With no visible tab at all there is still a body: the empty state
+ * is what a dock whose every tab is gated off says, and a blank box is not.
+ */
+function paintBody(): void {
+  const host = _body;
+  if (!host) {
+    return;
+  }
+  const active = activeBottomPanel();
+  litRender(
+    active
+      ? active.render(bottomContext())
+      : emptyState(host, { message: "Nothing to show here yet." }),
+    host,
+  );
+  runAfterRender(host);
 }
 
 /**
@@ -328,9 +387,15 @@ export function unmountBottomDock(): void {
   _scope?.stop();
   _scope = null;
   _revealedLogicKey = null;
+  _dock?.dispose();
+  _dock = null;
+  _body = null;
   if (_host) {
     _host.removeAttribute(REGION_ATTR);
+    /* The document's dispose removed its own root; this clears anything a caller left beside it,
+       so the host is `:empty` again and the shell's sheet takes the dock out of the grid. */
     litRender(nothing, _host);
+    _host.textContent = "";
     runAfterRender(_host);
     _host = null;
   }

package/src/panels/chat-panel.ts

@@ -17,15 +17,17 @@
  * and never tears down on tab switches — the assistant's module state and DOM (composer draft,
  * scroll position) persist.
  *
- * Deliberately NOT built on createPanelScheduler: ai-panel owns a focus-guard-free rAF render loop
- * (streaming must repaint while the composer is focused). This module only provides the host
- * container, the initial paint, and the pending-agent-prompt handoff; ai-panel's watcher drives all
- * chat-state repaints through the same lit part cache.
+ * **This module is the SEAM, and it has no markup of its own.** The assistant is a Jx document
+ * (`surfaces/ai-chat.json`), and a document CLEARS the host it is given — so it needs a container
+ * nobody else writes into. That container is the one thing created here; `.ai-panel-host` is its
+ * layout rule in `styles/inspector.css`, which is why the class stays on a node the surface does
+ * not own. Everything below it is the surface's, and `ai-panel.ts` drives it from one effect —
+ * there is no scheduler, and there is no frame loop, because a document's bindings re-run per
+ * property and a streaming token never reaches the composer.
  *
  * @license MIT
  */
 
-import { render as litRender } from "lit-html";
 import { effect, effectScope } from "../reactivity";
 import { workspace } from "../workspace/workspace";
 import { consumePendingAgentPrompt, hasPendingAgentPrompt } from "../services/agent-seed";
@@ -33,7 +35,7 @@ import { REGION_ATTR } from "../ui/regions";
 import {
   bindAiPanelHost,
   mountAiPanel,
-  renderAiPanelTemplate,
+  renderAiPanel,
   revealAssistant,
   seedAssistantPrompt,
 } from "./ai-panel";
@@ -49,9 +51,8 @@ let _scope: EffectScope | null = null;
 
 /**
  * Mount the assistant into the host the Inspector hands it. Idempotent per host: the persistent
- * `.ai-panel-host` container is created once and bound as the ai-panel render host (lit needs a
- * single render target for its part cache). A missing host (a reduced test fixture with no
- * inspector) is a no-op.
+ * `.ai-panel-host` container is created once and handed to `ai-panel.ts` as the surface's mount
+ * point. A missing host (a reduced test fixture with no inspector) is a no-op.
  *
  * @param {HTMLElement | null} host
  */
@@ -67,10 +68,7 @@ export function mount(host: HTMLElement | null) {
   host.append(_container);
 
   mountAiPanel();
-  // The AI panel owns a focus-guard-free rAF render loop into this container so
-  // Streaming repaints while the composer is focused (see ai-panel.ts).
   bindAiPanelHost(_container);
-  render();
 
   _scope?.stop();
   _scope = effectScope();
@@ -100,6 +98,8 @@ export function mount(host: HTMLElement | null) {
 export function unmount() {
   _scope?.stop();
   _scope = null;
+  // `null` unbinds the surface: the document is disposed and the chat-state watcher stopped.
+  bindAiPanelHost(null);
   if (_host) {
     _host.textContent = "";
   }
@@ -107,9 +107,14 @@ export function unmount() {
   _container = null;
 }
 
-/** Repaint the assistant template into the persistent container (no-op before mount). */
+/**
+ * Recompute the assistant's projection now (no-op before mount).
+ *
+ * Kept because `store.ts`'s `registerRenderer("chatPanel", …)` compat registry still names it. The
+ * surface follows the projection, so this is one function call rather than a repaint.
+ */
 export function render() {
   if (_container) {
-    litRender(renderAiPanelTemplate(), _container);
+    renderAiPanel();
   }
 }

package/src/panels/data-explorer.ts

@@ -1,12 +1,13 @@
 /// <reference lib="dom" />
 // ─── Data Explorer ──────────────────────────────────────────────────────────
 
-import { html, nothing } from "lit-html";
-import type { TemplateResult } from "lit-html";
+import { nothing } from "lit-html";
 import { activeTab } from "../workspace/workspace";
-import { renderOnly } from "../store";
 import { booleanArg, stringArg, stringProperty } from "../commands/command-args";
+import { renderDataTreeSurface } from "../surfaces/panel-data";
 import { registerPanel } from "./panel-registry";
+import type { PanelBody } from "./panel-registry";
+import type { DataTreeRow } from "../surfaces/panel-data";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 
 /**
@@ -62,32 +63,48 @@ export function raiseDataLimit(path: string, kind: "items" | "keys" | "depth"):
 }
 
 /**
- * One truncation marker: a button that shows more of what is already in hand.
+ * One truncation marker: a row the document draws as a button that shows more of what is in hand.
  *
- * It repaints through `renderOnly("leftPanel")` rather than a callback, because this renderer is
- * called from three places and threading a repaint through all of them to reach one `<button>`
- * would put a required callback on a pure formatter.
+ * It carries the subtree and the limit it raises rather than a callback. The press arrives back
+ * here through the surface's one action, so a pure formatter stays pure and there is a single
+ * repaint to reason about instead of one threaded through every caller.
  */
-function moreTemplate(
+function moreRow(
   path: string,
-  kind: "items" | "keys" | "depth",
+  limit: "items" | "keys" | "depth",
   indent: string,
-  label: string,
-  after?: () => string,
-) {
-  return html`<button
-    type="button"
-    class="data-leaf data-ellipsis data-more"
-    style="padding-left:${indent}"
-    title=${after?.() ?? `Show ${MORE_STEP} more`}
-    @click=${(e: Event) => {
-      e.stopPropagation();
-      raiseDataLimit(path, kind);
-      renderOnly("leftPanel");
-    }}
-  >
-    ${label}
-  </button>`;
+  text: string,
+  title = `Show ${MORE_STEP} more`,
+): DataTreeRow {
+  return {
+    indent,
+    key: `${path}\u0000${limit}`,
+    kind: "more",
+    label: "",
+    limit,
+    path,
+    text,
+    title,
+    tone: "marker",
+  };
+}
+
+/** A value as the tree prints it, capped at `max` characters. `undefined` prints as nothing. */
+function valueText(value: unknown, max: number): string {
+  if (typeof value === "string" && value.length > max) {
+    return `"${value.slice(0, max)}…"`;
+  }
+  return JSON.stringify(value) ?? "";
+}
+
+/** Which colour a value takes. `null` and a summary label are the two the tree actually paints. */
+function toneOf(value: unknown): string {
+  return value === null ? "null" : typeof value;
+}
+
+/** `Array(3)` or `{2}` — what a value you can open says while it is closed. */
+function summaryLabel(value: object): string {
+  return Array.isArray(value) ? `Array(${value.length})` : `{${Object.keys(value).length}}`;
 }
 
 /** Unwrap a Vue ref (has .value and .__v_isRef) to get the underlying value. */
@@ -121,98 +138,110 @@ export function dataTypeLabel(value: unknown) {
    panel listing every state entry with its badge and how it is defined: the same names twice, and
    you read one to understand the other. Plan §11.2 asks for "definitions + live values in one row",
    so the definition row now carries the resolved type and expands to the value tree, and what is
-   left here is the tree renderer, the type label and the row-expansion record the merged rows read.
-   `renderDataTreeTemplate` is unchanged — it was never the redundant half. */
+   left here is the tree WALK, the type label and the row-expansion record the merged rows read. */
+
 /**
- * Recursively render a JSON value as a tree view (Lit template).
+ * Flatten a JSON value into the lines the Data surface draws (`surfaces/panel-data.{json,ts}`).
  *
- * @returns {import("lit-html").TemplateResult}
+ * The tree used to BE a lit template, one recursive call per level. It is a document now, and a
+ * document's one repeater walks a LIST — so the recursion moved here and comes out as rows that
+ * each carry their own indent. Nothing else changed: the caps are the same caps, the text is
+ * truncated at the same lengths, and a capped list still ends in a marker.
+ *
+ * @param {unknown} value The resolved value to read.
+ * @param {number} depth How deep this call already is; the indent is derived from it.
+ * @param {number} [maxDepth] The default depth cap, before whatever the reader has raised.
+ * @param {string} path This subtree's path, which is what a raised limit is remembered against.
+ * @returns {DataTreeRow[]}
  */
-export function renderDataTreeTemplate(
+export function dataTreeRows(
   value: unknown,
   depth: number,
   maxDepth = 5,
   path = "",
-): TemplateResult {
+): DataTreeRow[] {
   const indent = `${(depth + 1) * 12}px`;
+  const row = (label: string, text: string, tone: string, key: string): DataTreeRow => ({
+    indent,
+    key,
+    kind: "row",
+    label,
+    limit: "",
+    path: "",
+    text,
+    title: "",
+    tone,
+  });
 
   if (depth > capFor(path, "depth", maxDepth)) {
-    return moreTemplate(path, "depth", indent, "…", () => `Show ${MORE_STEP} more levels`);
+    return [moreRow(path, "depth", indent, "…", `Show ${MORE_STEP} more levels`)];
   }
-
+  /* The one line a value with nothing under it renders as, keyed by the subtree's own path. That
+     is unique by construction: a descent only ever happens into an object or an array, so this
+     row exists only at the top of a tree, where it has no siblings to collide with. */
   if (value === null || value === undefined) {
-    return html`<div class="data-leaf data-null" style="padding-left:${indent}">
-      ${String(value)}
-    </div>`;
+    return [row("", String(value), "null", path)];
   }
-
   if (typeof value !== "object") {
-    const text =
-      typeof value === "string" && value.length > 200
-        ? `"${value.slice(0, 200)}\u2026"`
-        : JSON.stringify(value);
-    return html`<div class="data-leaf data-${typeof value}" style="padding-left:${indent}">
-      ${text}
-    </div>`;
+    return [row("", valueText(value, 200), toneOf(value), path)];
   }
 
-  if (Array.isArray(value)) {
-    const cap = capFor(path, "items", 20);
-    const items: TemplateResult[] = value.slice(0, cap).map((item, i) => {
-      if (item === null || item === undefined || typeof item !== "object") {
-        const valText =
-          typeof item === "string" && item.length > 80
-            ? `"${item.slice(0, 80)}\u2026"`
-            : JSON.stringify(item);
-        return html`<div class="data-branch" style="padding-left:${indent}">
-          <span class="data-key">[${i}] </span
-          ><span class="data-value data-${item === null ? "null" : typeof item}">${valText}</span>
-        </div>`;
-      }
-      const label = Array.isArray(item)
-        ? `Array(${item.length})`
-        : `{${Object.keys(item as object).length}}`;
-      return html`
-        <div class="data-branch" style="padding-left:${indent}">
-          <span class="data-key">[${i}] </span
-          ><span class="data-value data-object-label">${label}</span>
-        </div>
-        ${renderDataTreeTemplate(item, depth + 1, maxDepth, `${path}/${i}`)}
-      `;
-    });
-    return html`${items}${
-      value.length > cap
-        ? moreTemplate(path, "items", indent, `… ${value.length - cap} more`)
-        : nothing
-    }`;
-  }
+  const array = Array.isArray(value);
+  const entries: [string, string, unknown][] = array
+    ? value.map((item, i) => [`${i}`, `[${i}] `, item])
+    : Object.keys(value).map((key) => [key, `${key}: `, (value as Record<string, unknown>)[key]]);
+  const limit = array ? "items" : "keys";
+  const cap = capFor(path, limit, array ? 20 : 30);
 
-  // Object
-  const obj = value as Record<string, unknown>;
-  const keys = Object.keys(obj);
-  const cap = capFor(path, "keys", 30);
-  const items: TemplateResult[] = keys.slice(0, cap).map((key) => {
-    const v = obj[key];
-    if (v === null || v === undefined || typeof v !== "object") {
-      const valText =
-        typeof v === "string" && v.length > 80 ? `"${v.slice(0, 80)}\u2026"` : JSON.stringify(v);
-      return html`<div class="data-branch" style="padding-left:${indent}">
-        <span class="data-key">${key}: </span
-        ><span class="data-value data-${v === null ? "null" : typeof v}">${valText}</span>
-      </div>`;
+  const rows: DataTreeRow[] = [];
+  for (const [segment, label, item] of entries.slice(0, cap)) {
+    const childPath = `${path}/${segment}`;
+    if (item === null || item === undefined || typeof item !== "object") {
+      rows.push(row(label, valueText(item, 80), toneOf(item), childPath));
+      continue;
     }
-    const label = Array.isArray(v) ? `Array(${v.length})` : `{${Object.keys(v).length}}`;
-    return html`
-      <div class="data-branch" style="padding-left:${indent}">
-        <span class="data-key">${key}: </span
-        ><span class="data-value data-object-label">${label}</span>
-      </div>
-      ${renderDataTreeTemplate(v, depth + 1, maxDepth, `${path}/${key}`)}
-    `;
+    rows.push(
+      row(label, summaryLabel(item), "object", childPath),
+      ...dataTreeRows(item, depth + 1, maxDepth, childPath),
+    );
+  }
+  if (entries.length > cap) {
+    rows.push(moreRow(path, limit, indent, `… ${entries.length - cap} more`));
+  }
+  return rows;
+}
+
+/**
+ * Draw one value tree into the host that was made for it, or bring the one already there up to
+ * date.
+ *
+ * Idempotent, because it runs on EVERY repaint: a host that already holds its document is assigned
+ * to rather than remounted, which is what keeps the reader's place inside a long tree. Taking a
+ * CLOSED tree down is the panel's job rather than this one's — a row the reader collapsed never
+ * reaches here again — so `panels/signals-panel.ts` calls `disposeDetachedDataTrees()` once per
+ * repaint instead of this sweeping per host.
+ *
+ * @param {HTMLElement} host The node the tree is drawn into.
+ * @param {unknown} value What the canvas resolved this entry to.
+ * @param {string} path The subtree's path, which is what a raised limit is remembered against.
+ * @param {() => void} rerender Repaint the panel, so that a raised limit is drawn.
+ * @param {number} [maxDepth] The default depth cap, before whatever the reader has raised.
+ */
+export function paintDataTree(
+  host: HTMLElement,
+  value: unknown,
+  path: string,
+  rerender: () => void,
+  maxDepth = 5,
+): void {
+  renderDataTreeSurface(host, dataTreeRows(value, 0, maxDepth, path), {
+    showMore: (subtree, limit) => {
+      if (limit === "items" || limit === "keys" || limit === "depth") {
+        raiseDataLimit(subtree, limit);
+      }
+      rerender();
+    },
   });
-  return html`${items}${
-    keys.length > cap ? moreTemplate(path, "keys", indent, `… ${keys.length - cap} more`) : nothing
-  }`;
 }
 
 // ─── Commands ─────────────────────────────────────────────────────────────────
@@ -349,6 +378,14 @@ export function registerDataExplorerCommands(
  *
  * Defining and watching are the same task interrupted: you add an entry, then look at what it
  * resolved to. Two panels made that two panels.
+ *
+ * **Both halves are documents now** — `surfaces/panel-signals.{json,ts}` for the entry list and its
+ * editors, `surfaces/panel-data.{json,ts}` for the value tree under an open row. So lit draws
+ * nothing at all here: `render` returns `nothing` and `afterRender` mounts against the painted DOM,
+ * which is the seam `panels/git-panel.ts` uses for the same reason. The mount comes through `deps`
+ * rather than an import — this module owns the expansion store that one reads, so importing it back
+ * would close a cycle — and it is idempotent, so running on every repaint is what keeps the
+ * projection current.
  */
 export function registerDataPanel(): void {
   registerPanel({
@@ -356,14 +393,16 @@ export function registerDataPanel(): void {
     title: "Data",
     level: "document",
     dock: "navigator",
-    icon: "sp-icon-data",
+    icon: "database",
     requiresDocument: "Open a page to give it data — values it can read, compute or fetch.",
-    render: (ctx) =>
+    render: (): PanelBody => nothing,
+    afterRender: (ctx, host) => {
       // `ctx.doc!` — `requiresDocument` means the registry renders the empty state instead of
       // Calling this, the same assertion `head-panel.ts` makes for the same reason.
-      ctx.deps.renderSignalsTemplate(ctx.doc!, {
+      ctx.deps.mountSignalsPanel(host, ctx.doc!, {
         refreshData: ctx.deps.refreshData,
         renderLeftPanel: ctx.rerender,
-      }),
+      });
+    },
   });
 }