@jxsuite/studio 1.0.0 → 1.1.0

package/src/ui/formula-chips.ts

@@ -0,0 +1,216 @@
+/// <reference lib="dom" />
+/**
+ * Formula chips — a horizontal presentation layer summarizing an expression tree as left-to-right
+ * chips (spec §19.9). The `target` chain unrolls deepest-first: the head chip is the innermost
+ * target operand (ref/literal), followed by each operator up to the root. Nested non-target
+ * operands render as parenthesized group chips. Pure presentation — no editing logic; clicking a
+ * chip reports the node path to the caller.
+ */
+
+import { html, nothing } from "lit-html";
+import { isJsonObject, isRef } from "@jxsuite/schema/guards";
+
+import type { TemplateResult } from "lit-html";
+import type { EditorPreview } from "./expression-editor";
+
+type NodePath = (string | number)[];
+
+interface ChainLink {
+  node: Record<string, unknown>;
+  path: NodePath;
+}
+
+interface Chain {
+  /** The innermost target operand (ref/literal), absent for target-less roots. */
+  head: { value: unknown; path: NodePath } | null;
+  /** Operator nodes, deepest target first → outermost operator last. */
+  links: ChainLink[];
+}
+
+function isExprNode(value: unknown): value is Record<string, unknown> {
+  return isJsonObject(value) && typeof value.operator === "string";
+}
+
+/** Human label for a pointer ref: strips the #/state/ and window#/ prefixes. */
+function refLabel(ref: string): string {
+  if (ref.startsWith("#/state/")) {
+    return ref.slice("#/state/".length);
+  }
+  if (ref.startsWith("window#/")) {
+    return ref.slice("window#/".length).replaceAll("/", ".");
+  }
+  return ref || "?";
+}
+
+/** Compact label for a non-node operand (ref or literal). */
+function operandLabel(value: unknown): string {
+  if (isRef(value)) {
+    return refLabel(value.$ref);
+  }
+  if (isExprNode(value)) {
+    return `(${chipSummary(value)})`;
+  }
+  if (typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+
+/** The chain path for `hops` target descents below `basePath`. */
+function targetPath(basePath: NodePath, hops: number): NodePath {
+  return [...basePath, ...Array.from({ length: hops }, () => "target")];
+}
+
+/** Unroll a node's target chain into head operand + operator links (deepest first). */
+function unrollChain(node: Record<string, unknown>, basePath: NodePath): Chain {
+  // Collect the chain root-first, then materialize each link's path from its descent depth.
+  const nodes: Record<string, unknown>[] = [];
+  let current: Record<string, unknown> = node;
+  for (;;) {
+    nodes.push(current);
+    const next = current.target;
+    if (isExprNode(next)) {
+      current = next;
+    } else {
+      break;
+    }
+  }
+  const deepest = nodes.at(-1)!;
+  const head: Chain["head"] =
+    "target" in deepest || deepest.target !== undefined
+      ? { path: targetPath(basePath, nodes.length), value: deepest.target }
+      : null;
+  const rootFirst = nodes.map((n, i) => ({ node: n, path: targetPath(basePath, i) }));
+  return { head, links: rootFirst.toReversed() };
+}
+
+/** Compact one-line text form of a node: head operand followed by the operator chain. */
+export function chipSummary(node: unknown): string {
+  if (!isExprNode(node)) {
+    return operandLabel(node);
+  }
+  const { head, links } = unrollChain(node, []);
+  const parts: string[] = [];
+  if (head) {
+    parts.push(operandLabel(head.value));
+  }
+  for (const link of links) {
+    parts.push(String(link.node.operator));
+  }
+  return parts.join(" › ");
+}
+
+// ─── Rendering ──────────────────────────────────────────────────────────────
+
+const CHIP_STYLE =
+  "display:inline-flex;align-items:center;gap:4px;max-width:180px;padding:1px 7px;" +
+  "border:1px solid var(--spectrum-gray-300, #3c3c3c);border-radius:10px;cursor:pointer;" +
+  "background:var(--spectrum-gray-100, #232323);color:var(--spectrum-gray-800, #d0d0d0);" +
+  "font-size:11px;font-family:var(--spectrum-code-font-family, monospace);line-height:18px";
+
+/** Live value badge — same styling convention as the expression editor's `.expr-live-badge`. */
+function renderChipBadge(preview: EditorPreview | null | undefined, pathKey: string) {
+  const text = preview?.values.get(pathKey);
+  if (text === undefined) {
+    return nothing;
+  }
+  return html`
+    <span
+      class="expr-live-badge"
+      title=${text}
+      style="font-family:var(--spectrum-code-font-family, monospace);font-size:10px;line-height:16px;padding:0 5px;border-radius:4px;background:var(--spectrum-gray-200, #323232);color:var(--spectrum-seafoam-900, #35a690);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:120px;flex-shrink:1"
+      >${text}</span
+    >
+  `;
+}
+
+function renderChip(
+  label: string,
+  path: NodePath,
+  onSelect: (path: NodePath) => void,
+  preview: EditorPreview | null | undefined,
+  group = false,
+) {
+  return html`
+    <button
+      type="button"
+      class=${group ? "formula-chip formula-chip--group" : "formula-chip"}
+      data-path=${path.join("/")}
+      style=${CHIP_STYLE}
+      title=${label}
+      @click=${() => onSelect(path)}
+    >
+      <span style="white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:110px"
+        >${label}</span
+      >
+      ${renderChipBadge(preview, path.join("/"))}
+    </button>
+  `;
+}
+
+/** Collect group chips for a link's non-target expression operands (value/initial/cases). */
+function groupChips(
+  link: ChainLink,
+  onSelect: (path: NodePath) => void,
+  preview: EditorPreview | null | undefined,
+): TemplateResult[] {
+  const chips: TemplateResult[] = [];
+  const add = (operand: unknown, path: NodePath) => {
+    if (isExprNode(operand)) {
+      chips.push(renderChip(`(${chipSummary(operand)})`, path, onSelect, preview, true));
+    }
+  };
+  const { value, initial, cases } = link.node;
+  if (Array.isArray(value)) {
+    for (const [i, item] of value.entries()) {
+      add(item, [...link.path, "value", i]);
+    }
+  } else {
+    add(value, [...link.path, "value"]);
+  }
+  add(initial, [...link.path, "initial"]);
+  if (isJsonObject(cases)) {
+    for (const [key, operand] of Object.entries(cases)) {
+      add(operand, [...link.path, "cases", key]);
+    }
+  }
+  add(link.node.default, [...link.path, "default"]);
+  return chips;
+}
+
+/**
+ * Render an expression node as a horizontal chip pipeline. Each chip carries the node's live value
+ * badge when a preview is supplied; clicking a chip calls `onSelect` with the node path.
+ */
+export function renderFormulaChips(
+  node: unknown,
+  onSelect: (path: NodePath) => void,
+  opts: { preview?: EditorPreview | null; path?: NodePath } = {},
+): TemplateResult {
+  if (!isExprNode(node)) {
+    return html`${nothing}`;
+  }
+  const preview = opts.preview ?? null;
+  const basePath = opts.path ?? [];
+  const { head, links } = unrollChain(node, basePath);
+
+  const chips: TemplateResult[] = [];
+  if (head) {
+    chips.push(renderChip(operandLabel(head.value), head.path, onSelect, preview));
+  }
+  for (const link of links) {
+    chips.push(
+      renderChip(String(link.node.operator), link.path, onSelect, preview),
+      ...groupChips(link, onSelect, preview),
+    );
+  }
+
+  return html`
+    <div
+      class="formula-chips"
+      style="display:flex;flex-wrap:wrap;gap:4px;align-items:center;padding:2px 0 6px"
+    >
+      ${chips}
+    </div>
+  `;
+}

package/src/ui/formula-palette.ts

@@ -0,0 +1,211 @@
+/// <reference lib="dom" />
+/**
+ * Formula palette — a command-palette overlay for browsing/searching the formula catalog (spec
+ * §19.9). Clones the quick-search pattern: a plain overlay div (no nested sp-overlay), a search
+ * field, grouped results, and keyboard navigation. Picking an entry calls `onPick` with it; the
+ * caller decides what to insert.
+ */
+
+import { html, render as litRender, nothing } from "lit-html";
+import { classMap } from "lit-html/directives/class-map.js";
+import { live } from "lit-html/directives/live.js";
+import { ref } from "lit-html/directives/ref.js";
+import { getLayerSlot } from "./layers";
+import { rectOf } from "../utils/geometry";
+
+import type { FormulaCatalogEntry } from "./formula-catalog";
+
+export interface FormulaPaletteOpts {
+  entries: FormulaCatalogEntry[];
+  onPick: (entry: FormulaCatalogEntry) => void;
+  /** Optional anchor element the panel is positioned under; centered when absent. */
+  anchor?: HTMLElement | null;
+}
+
+let _open = false;
+let _opts: FormulaPaletteOpts | null = null;
+let _query = "";
+let _selectedIndex = 0;
+
+function getContainer() {
+  return getLayerSlot("popover", "formula-palette");
+}
+
+export function openFormulaPalette(opts: FormulaPaletteOpts) {
+  _open = true;
+  _opts = opts;
+  _query = "";
+  _selectedIndex = 0;
+  renderOverlay();
+}
+
+export function closeFormulaPalette() {
+  _open = false;
+  _opts = null;
+  renderOverlay();
+}
+
+/** Entries matching the current query (label, name, group, or description substring). */
+function filteredEntries(): FormulaCatalogEntry[] {
+  const entries = _opts?.entries ?? [];
+  const needle = _query.trim().toLowerCase();
+  if (!needle) {
+    return entries;
+  }
+  return entries.filter(
+    (e) =>
+      e.label.toLowerCase().includes(needle) ||
+      e.name.toLowerCase().includes(needle) ||
+      e.group.toLowerCase().includes(needle) ||
+      e.description.toLowerCase().includes(needle),
+  );
+}
+
+/** Group entries for display, preserving first-seen group order. */
+function groupedEntries(entries: FormulaCatalogEntry[]): [string, FormulaCatalogEntry[]][] {
+  const groups = new Map<string, FormulaCatalogEntry[]>();
+  for (const entry of entries) {
+    const bucket = groups.get(entry.group);
+    if (bucket) {
+      bucket.push(entry);
+    } else {
+      groups.set(entry.group, [entry]);
+    }
+  }
+  return [...groups.entries()];
+}
+
+function pickEntry(entry: FormulaCatalogEntry) {
+  const opts = _opts;
+  closeFormulaPalette();
+  opts?.onPick(entry);
+}
+
+function onInput(e: Event) {
+  _query = (e.target as HTMLInputElement).value;
+  _selectedIndex = 0;
+  renderOverlay();
+}
+
+function onKeydown(e: KeyboardEvent) {
+  const entries = filteredEntries();
+  switch (e.key) {
+    case "ArrowDown": {
+      e.preventDefault();
+      _selectedIndex = Math.min(_selectedIndex + 1, entries.length - 1);
+      renderOverlay();
+      break;
+    }
+    case "ArrowUp": {
+      e.preventDefault();
+      _selectedIndex = Math.max(_selectedIndex - 1, 0);
+      renderOverlay();
+      break;
+    }
+    case "Enter": {
+      e.preventDefault();
+      if (entries[_selectedIndex]) {
+        pickEntry(entries[_selectedIndex]!);
+      }
+      break;
+    }
+    case "Escape": {
+      e.preventDefault();
+      closeFormulaPalette();
+      break;
+    }
+    default: {
+      break;
+    }
+  }
+}
+
+/** Inline position style for the panel when anchored to an element. */
+function panelStyle(): string {
+  const anchor = _opts?.anchor;
+  if (!anchor) {
+    return "";
+  }
+  const rect = rectOf(anchor);
+  if (!rect || (rect.top === 0 && rect.left === 0 && rect.width === 0)) {
+    return "";
+  }
+  const left = Math.max(8, Math.min(rect.left, (globalThis.innerWidth || 1200) - 568));
+  return `position:fixed;left:${left}px;top:${rect.bottom + 4}px;margin:0`;
+}
+
+function renderOverlay() {
+  const container = getContainer();
+  if (!_open) {
+    litRender(nothing, container);
+    return;
+  }
+
+  const entries = filteredEntries();
+  const groups = groupedEntries(entries);
+  const hasQuery = _query.trim().length > 0;
+
+  const tpl = html`
+    <div class="quick-search-overlay formula-palette-overlay" @click=${closeFormulaPalette}>
+      <div
+        class="quick-search-panel formula-palette"
+        style=${panelStyle()}
+        @click=${(e: Event) => e.stopPropagation()}
+      >
+        <input
+          class="quick-search-input formula-palette-input"
+          type="text"
+          placeholder="Search formulas, operators, globals…"
+          .value=${live(_query)}
+          @input=${onInput}
+          @keydown=${onKeydown}
+          ${ref((el) => {
+            if (el) {
+              requestAnimationFrame(() => (el as HTMLInputElement).focus());
+            }
+          })}
+        />
+        <div class="quick-search-results">
+          ${entries.length === 0
+            ? html`<div class="quick-search-empty">
+                ${hasQuery ? "No results" : "No entries available"}
+              </div>`
+            : nothing}
+          ${groups.map(
+            ([group, groupEntries]) => html`
+              <div class="quick-search-section-label">${group}</div>
+              ${groupEntries.map((entry) => {
+                const index = entries.indexOf(entry);
+                return html`
+                  <div
+                    class=${classMap({
+                      "quick-search-item": true,
+                      selected: index === _selectedIndex,
+                    })}
+                    @click=${() => pickEntry(entry)}
+                    @mouseenter=${() => {
+                      _selectedIndex = index;
+                      renderOverlay();
+                    }}
+                  >
+                    <span
+                      class="quick-search-name"
+                      style="font-family:var(--spectrum-code-font-family, monospace)"
+                      >${entry.label}</span
+                    >
+                    <span class="quick-search-path" title=${entry.description}
+                      >${entry.description}</span
+                    >
+                    <span class="quick-search-badge">${entry.kind}</span>
+                  </div>
+                `;
+              })}
+            `,
+          )}
+        </div>
+      </div>
+    </div>
+  `;
+
+  litRender(tpl, container);
+}

package/src/ui/layers.ts

@@ -78,6 +78,46 @@ export function showConfirmDialog(
   );
 }
 
+/**
+ * Show a three-way Save / Discard / Cancel dialog. Resolves "save", "discard", or "cancel"
+ * (dismiss/close counts as cancel).
+ *
+ * @param {string} headline
+ * @param {string | import("lit-html").TemplateResult} message
+ * @param {{ saveLabel?: string; discardLabel?: string; cancelLabel?: string }} [opts]
+ * @returns {Promise<"save" | "discard" | "cancel">}
+ */
+export function showSaveDiscardDialog(
+  headline: string,
+  message: string | TemplateResult,
+  opts: {
+    saveLabel?: string;
+    discardLabel?: string;
+    cancelLabel?: string;
+  } = {},
+): Promise<"save" | "discard" | "cancel"> {
+  const { saveLabel = "Save", discardLabel = "Discard", cancelLabel = "Cancel" } = opts;
+  return showDialog<"save" | "discard" | "cancel">(
+    (done) => html`
+      <sp-dialog-wrapper
+        open
+        underlay
+        headline=${headline}
+        confirm-label=${saveLabel}
+        secondary-label=${discardLabel}
+        cancel-label=${cancelLabel}
+        size="s"
+        @confirm=${() => done("save")}
+        @secondary=${() => done("discard")}
+        @cancel=${() => done("cancel")}
+        @close=${() => done("cancel")}
+      >
+        <p>${message}</p>
+      </sp-dialog-wrapper>
+    `,
+  );
+}
+
 /**
  * Open a persistent modal. Returns a handle with update() and close() methods.
  *

package/src/ui/media-picker.ts

@@ -93,7 +93,7 @@ async function loadMediaCache() {
   // Re-render the host panels so the Browse button (gated on mediaCache.length) appears once the
   // Async listing resolves — including when an image value is already set, so the current image can
   // Be replaced. Mirrors loadLayoutEntries()'s renderOnly() in head-panel.
-  renderOnly("leftPanel", "rightPanel");
+  renderOnly("leftPanel", "rightPanel", "frontmatterPanel");
 }
 
 /** Force media cache reload (e.g. after upload). */

package/src/ui/panel-resize.ts

@@ -13,6 +13,7 @@ const MIN_WIDTH = 160;
 const MAX_RATIO = 0.5; // Max 50% of viewport
 const DEFAULT_LEFT = 240;
 const DEFAULT_RIGHT = 280;
+const DEFAULT_CHAT = 320;
 
 const root = document.documentElement;
 
@@ -27,8 +28,10 @@ try {
   const saved = JSON.parse(localStorage.getItem(STORAGE_KEY) || "{}") as {
     left?: number;
     right?: number;
+    chat?: number;
     leftCollapsed?: boolean;
     rightCollapsed?: boolean;
+    chatCollapsed?: boolean;
   };
   if (saved.left) {
     root.style.setProperty("--panel-w-left", `${saved.left}px`);
@@ -36,12 +39,18 @@ try {
   if (saved.right) {
     root.style.setProperty("--panel-w-right", `${saved.right}px`);
   }
+  if (saved.chat) {
+    root.style.setProperty("--panel-w-chat", `${saved.chat}px`);
+  }
   if (saved.leftCollapsed) {
     view.leftPanelCollapsed = true;
   }
   if (saved.rightCollapsed) {
     view.rightPanelCollapsed = true;
   }
+  if (saved.chatCollapsed) {
+    view.chatPanelCollapsed = true;
+  }
   applyPanelCollapse();
 } catch {
   // Ignore
@@ -111,8 +120,9 @@ function setupHandle(
 function persistWidths() {
   const left = readPxVar("--panel-w-left") || DEFAULT_LEFT;
   const right = readPxVar("--panel-w-right") || DEFAULT_RIGHT;
+  const chat = readPxVar("--panel-w-chat") || DEFAULT_CHAT;
   try {
-    localStorage.setItem(STORAGE_KEY, JSON.stringify({ left, right }));
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ chat, left, right }));
   } catch {
     // Storage full or unavailable
   }
@@ -122,6 +132,7 @@ function persistWidths() {
 
 const resizeLeft = document.querySelector<HTMLElement>("#resize-left");
 const resizeRight = document.querySelector<HTMLElement>("#resize-right");
+const resizeChat = document.querySelector<HTMLElement>("#resize-chat");
 
 if (resizeLeft) {
   setupHandle(resizeLeft, "--panel-w-left", "left", DEFAULT_LEFT);
@@ -129,3 +140,6 @@ if (resizeLeft) {
 if (resizeRight) {
   setupHandle(resizeRight, "--panel-w-right", "right", DEFAULT_RIGHT);
 }
+if (resizeChat) {
+  setupHandle(resizeChat, "--panel-w-chat", "right", DEFAULT_CHAT);
+}

package/src/utils/preview-format.ts

@@ -0,0 +1,26 @@
+/**
+ * Display formatting for live expression-preview values, shared by the parent-side snapshot
+ * evaluator (services/preview-eval.ts) and the in-iframe live evaluator (canvas/iframe-eval.ts) so
+ * both realms badge values with identical truncation rules. Dependency-light and DOM-free (the
+ * strip-events pattern) so importing it never grows the iframe bundle.
+ */
+
+const MAX_BADGE_LENGTH = 48;
+
+/** Format a runtime value as a short badge string. */
+export function formatPreviewValue(value?: unknown): string {
+  if (value === undefined) {
+    return "undefined";
+  }
+  let text: string;
+  try {
+    text =
+      typeof value === "string" ? JSON.stringify(value) : (JSON.stringify(value) ?? "undefined");
+  } catch {
+    text = String(value);
+  }
+  if (text.length > MAX_BADGE_LENGTH) {
+    text = `${text.slice(0, MAX_BADGE_LENGTH - 1)}…`;
+  }
+  return text;
+}

package/src/view.ts

@@ -46,7 +46,7 @@ interface ViewState {
   leftTab: string;
   leftPanelCollapsed: boolean;
   rightPanelCollapsed: boolean;
-  autosaveTimer: ReturnType<typeof setTimeout> | null;
+  chatPanelCollapsed: boolean;
   _layersCollapsed: Set<string> | null;
   [key: string]: unknown;
 }
@@ -104,9 +104,7 @@ export const view: ViewState = {
   leftTab: "layers",
   leftPanelCollapsed: false,
   rightPanelCollapsed: false,
-
-  // Autosave
-  autosaveTimer: null,
+  chatPanelCollapsed: false,
 
   // Layers panel collapsed state
   _layersCollapsed: null,
@@ -121,6 +119,7 @@ export function applyPanelCollapse() {
   }
   app.classList.toggle("left-collapsed", view.leftPanelCollapsed);
   app.classList.toggle("right-collapsed", view.rightPanelCollapsed);
+  app.classList.toggle("chat-collapsed", view.chatPanelCollapsed);
   try {
     const saved = JSON.parse(localStorage.getItem(COLLAPSE_STORAGE_KEY) || "{}") as Record<
       string,
@@ -128,6 +127,7 @@ export function applyPanelCollapse() {
     >;
     saved.leftCollapsed = view.leftPanelCollapsed;
     saved.rightCollapsed = view.rightPanelCollapsed;
+    saved.chatCollapsed = view.chatPanelCollapsed;
     localStorage.setItem(COLLAPSE_STORAGE_KEY, JSON.stringify(saved));
   } catch {
     // Storage unavailable

package/src/workspace/workspace.ts

@@ -57,6 +57,20 @@ export const activeTab = computed(() =>
   workspace.activeTabId ? (workspace.tabs.get(workspace.activeTabId) ?? null) : null,
 ) as unknown as ComputedRef<Tab | null>;
 
+/**
+ * Record the open project on the reactive workspace. `root` must be the absolute project root (the
+ * same value `createProject` returns and the pending-agent-prompt handoff is keyed by) — not the
+ * "."-relative root projectState sometimes holds. Consumers: AI session scoping, system-prompt
+ * project context, and the chat panel's pending-prompt effect.
+ *
+ * @param {string | null} root
+ * @param {object | null} [config]
+ */
+export function setWorkspaceProject(root: string | null, config: object | null = null) {
+  workspace.projectRoot = root;
+  workspace.projectConfig = config;
+}
+
 /**
  * Whether `tab` is the active tab. Identity check survives reactive-proxy wrapping (activeTab.value
  * is a proxy; callers may hold either the raw tab or a proxy of it).