@jxsuite/studio 2.2.1 → 2.3.0

package/src/hosting/layout.ts

@@ -0,0 +1,211 @@
+/**
+ * What `@jxsuite/studio` ships, where it goes, and how a host addresses it.
+ *
+ * The package's internal cross-references are already correct and self-locating — `dist/studio.css`
+ * reaches `./codicon.ttf`, `styles/tokens.css` reaches `../fonts/*.woff2`, the entry reaches
+ * `./chunks/*` and `./workers/*`. What it never shipped was a STATEMENT that they are, so four
+ * hosts re-derived the file list by hand, two of them flattened the tree, that broke the
+ * references, and they rewrote the shipped HTML to compensate. This module is the statement.
+ *
+ * **Pure by contract.** No `node:`, no DOM, nothing beyond the language — so a wrangler build, a
+ * Vite plugin, a Deno host or a Nix derivation can read it. `./hosting` (stage.ts) is the `node:fs`
+ * convenience the two Bun consumers share, and it is the only entry that binds a runtime. The build
+ * also emits `dist/manifest.json` from {@link STUDIO_ASSETS} for a host that cannot import
+ * TypeScript at all.
+ *
+ * **It names no adapter, no backend and no transport.** `@jxsuite/studio` may contain PAL adapters
+ * — `platforms/devserver.ts` and `platforms/cloud.ts` both ship, the latter because it owns the
+ * collab client's `Y.Doc` and a second bundled `yjs` breaks cross-module `instanceof` — but it must
+ * not depend on a backend PACKAGE. `scripts/check-dep-rules.ts` cannot catch a violation (it
+ * forbids only core-to-extension edges, and server and studio are both core), so
+ * `scripts/check-studio-package.ts` does.
+ */
+
+/** What a manifest entry is, which decides how a host must treat it. */
+export type StudioAssetKind =
+  | "document"
+  | "entry"
+  | "style"
+  | "chunk"
+  | "worker"
+  | "font"
+  | "asset";
+
+export interface StudioAsset {
+  /** POSIX, relative to the package root. */
+  readonly path: string;
+  readonly kind: StudioAssetKind;
+  /** A DIRECTORY copied wholesale; the names inside it are part of the contract. */
+  readonly dir: boolean;
+  /** Absence is a boot failure, not a degradation. */
+  readonly required: boolean;
+  /** Printed verbatim when it is missing, so the error explains itself. */
+  readonly why: string;
+}
+
+/**
+ * Everything a host serves.
+ *
+ * `required: false` means a host may leave it out and get a working editor with something switched
+ * off; everything else is load-bearing. The `why` is not decoration — it is what a staging error
+ * prints, and the difference between "a file is missing" and "the code view will silently have no
+ * schema validation".
+ */
+export const STUDIO_ASSETS: readonly StudioAsset[] = [
+  {
+    dir: false,
+    kind: "document",
+    path: "index.html",
+    required: true,
+    why: "the editor document. Generated from studioShellHtml(); a host serving the shell at its own path should render its own rather than copy this one.",
+  },
+  {
+    dir: false,
+    kind: "document",
+    path: "canvas.html",
+    required: true,
+    why: "the canvas iframe document. Without it every canvas frame 404s at boot.",
+  },
+  {
+    dir: false,
+    kind: "entry",
+    path: "dist/studio.js",
+    required: true,
+    why: "the editor bundle. Its path is a contract (studio.md 11.1) and is never hashed, because it anchors every other url the bundle resolves.",
+  },
+  {
+    dir: false,
+    kind: "entry",
+    path: "dist/iframe-entry.js",
+    required: true,
+    why: "the canvas bundle, loaded by canvas.html. Same unhashed-path contract.",
+  },
+  {
+    dir: false,
+    kind: "style",
+    path: "dist/studio.css",
+    required: true,
+    why: "the bundle's own stylesheet — Monaco's tokens and Tabulator's theme. Distinct from styles/, which is hand-authored.",
+  },
+  {
+    dir: false,
+    kind: "asset",
+    path: "dist/codicon.ttf",
+    required: true,
+    why: "Monaco's icon font, referenced by dist/studio.css and by three chunk stylesheets. It shipped in no tarball and no copy list for months, so every host drew tofu where Monaco draws icons.",
+  },
+  {
+    dir: false,
+    kind: "asset",
+    path: "dist/manifest.json",
+    required: false,
+    why: "this manifest as data, for a host that cannot import TypeScript — a Nix derivation, a shell script, a build in another language. Not required: a host that CAN import it has the same facts with types on them.",
+  },
+  {
+    dir: true,
+    kind: "chunk",
+    path: "dist/chunks",
+    required: true,
+    why: "the split chunks — Monaco, yjs, ajv and every on-demand import. The entry reaches them by url relative to itself, so the directory ships wholesale with its emitted names intact. A bundle that cannot find them dies at boot with a bare module-resolution error.",
+  },
+  {
+    dir: true,
+    kind: "worker",
+    path: "dist/workers",
+    required: true,
+    why: "Monaco's pre-bundled web workers. Missing, they do not 404 loudly: the code view simply has no JSON language service, so no schema validation, no completion and no hover, with nothing in the console.",
+  },
+  {
+    dir: true,
+    kind: "style",
+    path: "styles",
+    required: true,
+    why: "the hand-authored chrome stylesheet, linked by the document in cascade order. No bundler sees it. Missing, the editor boots with no tokens, no grid and no panel chrome.",
+  },
+  {
+    dir: true,
+    kind: "font",
+    path: "fonts",
+    required: true,
+    why: "the vendored JetBrains Mono faces, reached from styles/tokens.css by ../fonts/. They stay a directory rather than being bundled: Bun inlines a woff2 under its size threshold as base64, which would put about 85 KB into a render-blocking stylesheet.",
+  },
+];
+
+/** Never staged and never published, whatever the entries above would otherwise match. */
+export const STUDIO_ASSET_EXCLUDE: readonly string[] = ["**/*.map"];
+
+/**
+ * Published beyond the served tree: the source graph the `exports` map points at, and the data it
+ * reads. `data/` is here because six modules import it — `src/studio.ts` among them — so without it
+ * the package's own `.` export does not resolve from a tarball.
+ */
+export const PUBLISHED_EXTRAS: readonly string[] = ["src", "data"];
+
+export const STUDIO_SHELL = "index.html";
+export const STUDIO_CANVAS = "canvas.html";
+export const STUDIO_ENTRY = "dist/studio.js";
+export const STUDIO_IFRAME_ENTRY = "dist/iframe-entry.js";
+export const STUDIO_BUNDLE_CSS = "dist/studio.css";
+
+/** Monaco's workers, by the names scripts/build-workers.ts emits and monaco-setup.ts asks for. */
+export const STUDIO_WORKERS: readonly string[] = [
+  "editor.worker.js",
+  "json.worker.js",
+  "ts.worker.js",
+];
+
+/**
+ * The chrome stylesheets, IN CASCADE ORDER.
+ *
+ * Order is behaviour, not presentation: `forced-colors.css` is last because it redraws what Windows
+ * High Contrast deletes. This list is what the document's link tags are generated from, so a
+ * stylesheet added to `styles/` and not added here is simply never loaded — which is the 2.1.0
+ * outage exactly, where the cloud shipped seven dead link tags and the build exited 0.
+ * `scripts/check-studio-package.ts` holds it equal to `styles/*.css` on disk.
+ */
+export const STUDIO_STYLESHEETS: readonly string[] = [
+  "styles/tokens.css",
+  "styles/shell.css",
+  "styles/canvas.css",
+  "styles/panels.css",
+  "styles/inspector.css",
+  "styles/overlays.css",
+  "styles/forced-colors.css",
+];
+
+/** Bump when a host-visible export changes shape. A consumer may assert against it. */
+export const STUDIO_HOST_API = 1;
+
+/**
+ * How a host lays the tree out.
+ *
+ * `nested` keeps the package's own shape. `flat` hoists the contents of `dist/` up one level, which
+ * is what jx-platform's `public/` has always done.
+ */
+export type StudioLayoutMode = "nested" | "flat";
+
+export interface AssetBase {
+  /** URL prefix the tree is served under, as the BROWSER sees it. Non-empty values end in "/". */
+  readonly prefix: string;
+  readonly mode: StudioLayoutMode;
+}
+
+/**
+ * Map a package-relative path to the url a host serving under `base` answers.
+ *
+ * `flat` strips exactly ONE leading `dist/` segment and nothing else, and that single rule is what
+ * makes flattening a contract rather than a rewrite. Every reference that lives inside `dist/` is
+ * dist-relative — the entry reaches `./chunks/`, `dist/studio.css` reaches `./codicon.ttf`, a chunk
+ * stylesheet reaches `../codicon.ttf` — so stripping one segment uniformly moves all of them
+ * together and none of them breaks. `styles/` and `fonts/` are untouched in both modes, which is
+ * why `tokens.css`'s `url("../fonts/…")` holds either way.
+ *
+ * @param base Where the tree is mounted.
+ * @param packagePath A path from {@link STUDIO_ASSETS}, or a file inside one of its directories.
+ * @returns The url, with `base.prefix` applied.
+ */
+export function assetUrl(base: AssetBase, packagePath: string): string {
+  const path = packagePath.replace(/^\.?\//, "");
+  const laid = base.mode === "flat" ? path.replace(/^dist\//, "") : path;
+  return `${base.prefix}${laid}`;
+}

package/src/hosting/stage.ts

@@ -0,0 +1,166 @@
+/**
+ * Copy the studio tree somewhere a host can serve it.
+ *
+ * CONVENIENCE, not contract. Everything a subscriber strictly needs is in `./layout` (the manifest
+ * and {@link assetUrl}) and `./document` (the two generators), both of which are pure and run
+ * anywhere. This module exists so the two Bun consumers — the desktop's asset staging and
+ * jx-platform's `public/` build — do not each write the same copier, and it is the ONLY module
+ * under `src/` that imports `node:`. A host in another runtime reads the manifest and moves the
+ * bytes however it likes.
+ *
+ * @docs extending/embedding/hosting
+ */
+
+import { cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { Glob } from "bun";
+import { STUDIO_ASSETS, STUDIO_CANVAS, STUDIO_SHELL } from "./layout";
+import type { AssetBase, StudioAsset, StudioAssetKind, StudioLayoutMode } from "./layout";
+import { canvasShellHtml } from "./document";
+import type { DocumentOptions } from "./document";
+
+/** The installed package root, resolved off this module rather than off a caller's cwd. */
+export const STUDIO_PACKAGE_DIR = resolve(import.meta.dir, "..", "..");
+
+export interface StageOptions {
+  /** Package root to read from — an installed copy, or a `--link` checkout. */
+  readonly from?: string | undefined;
+  /** Kinds to leave out. The cloud passes `["document"]`; see the note on {@link stageStudioAssets}. */
+  readonly exclude?: readonly StudioAssetKind[] | undefined;
+  /** Copy `*.map` too. Default false: the chunk maps alone are about 24 MB. */
+  readonly sourceMaps?: boolean | undefined;
+  /**
+   * Remove the manifest's own paths under `destDir` first. Default true.
+   *
+   * Only those paths, never the whole directory. `packages/desktop/scripts/pre-build.ts` writes its
+   * launcher's PAL-init bundle to `assets/studio/dist/init.js` BEFORE staging, so a blanket wipe
+   * deletes it and the packaged app boots with no platform registered. Not cleaning at all is
+   * equally wrong: content-hashed chunks would accumulate in a staged tree forever.
+   */
+  readonly clean?: boolean | undefined;
+  /** Layout to report in {@link StageResult.base}. Default `"nested"`. */
+  readonly layout?: StudioLayoutMode | undefined;
+  /** Url prefix to report in {@link StageResult.base}. Default `"./"`. */
+  readonly prefix?: string | undefined;
+}
+
+export interface StageResult {
+  /**
+   * The base the tree was staged at — hand it straight to {@link studioShellHtml}, so the stager and
+   * the document cannot disagree about where the files went.
+   */
+  readonly base: AssetBase;
+  /** Package-relative paths written, in manifest order. */
+  readonly written: readonly string[];
+  readonly bytes: number;
+}
+
+/** Manifest entries absent from `root`. Empty means the tree is complete. */
+export function missingStudioAssets(root: string = STUDIO_PACKAGE_DIR): readonly StudioAsset[] {
+  return STUDIO_ASSETS.filter((a) => a.required && !existsSync(join(root, a.path)));
+}
+
+/** Where a package-relative path lands under `destDir`, honouring the layout. */
+function destOf(destDir: string, path: string, layout: StudioLayoutMode): string {
+  return join(destDir, layout === "flat" ? path.replace(/^dist\//, "") : path);
+}
+
+/**
+ * Copy the tree into `destDir`.
+ *
+ * @throws {Error} Naming the entry AND its `why` when a required one is missing — a staging failure
+ *   should say what the reader will lose, not just which file was absent.
+ */
+export async function stageStudioAssets(
+  destDir: string,
+  options: StageOptions = {},
+): Promise<StageResult> {
+  const from = options.from ?? STUDIO_PACKAGE_DIR;
+  const layout = options.layout ?? "nested";
+  const exclude = new Set(options.exclude);
+  const entries = STUDIO_ASSETS.filter((a) => !exclude.has(a.kind));
+
+  const absent = entries.filter((a) => a.required && !existsSync(join(from, a.path)));
+  if (absent.length > 0) {
+    const listed = absent.map((a) => `  ${a.path} — ${a.why}`).join("\n");
+    throw new Error(
+      `@jxsuite/studio is missing ${absent.length} required asset(s) at ${from}:\n${listed}\n` +
+        `Run \`bun run build\` in packages/studio, or check the package's published files list.`,
+    );
+  }
+
+  if (options.clean !== false) {
+    for (const a of entries) {
+      await rm(destOf(destDir, a.path, layout), { force: true, recursive: true });
+    }
+  }
+
+  const written: string[] = [];
+  let bytes = 0;
+  const skipMap = (p: string) => !options.sourceMaps && p.endsWith(".map");
+
+  for (const a of entries) {
+    const src = join(from, a.path);
+    if (!existsSync(src)) {
+      continue;
+    }
+    const dest = destOf(destDir, a.path, layout);
+    if (a.dir) {
+      await mkdir(dest, { recursive: true });
+      for (const rel of new Glob("**/*").scanSync(src)) {
+        const posix = rel.replaceAll("\\", "/");
+        if (skipMap(posix)) {
+          continue;
+        }
+        const file = join(src, rel);
+        const to = join(dest, rel);
+        await mkdir(dirname(to), { recursive: true });
+        await cp(file, to);
+        written.push(`${a.path}/${posix}`);
+        const info = await stat(file);
+        bytes += info.size;
+      }
+    } else {
+      if (skipMap(a.path)) {
+        continue;
+      }
+      await mkdir(dirname(dest), { recursive: true });
+      await cp(src, dest);
+      written.push(a.path);
+      const info = await stat(src);
+      bytes += info.size;
+    }
+  }
+
+  return { base: { mode: layout, prefix: options.prefix ?? "./" }, bytes, written };
+}
+
+export interface ReadDocumentOptions extends DocumentOptions {
+  /** Package root to read `canvas.html` from. */
+  readonly from?: string | undefined;
+}
+
+/* There is no shellDocument() here. The editor document needs no file read, so it would be a
+   re-export of studioShellHtml under a second name — a host imports `./hosting/document` for it,
+   which is also the entry that stays pure. */
+
+/** The canvas document, read from the package and rebased. */
+export async function canvasDocument(options: ReadDocumentOptions = {}): Promise<string> {
+  const from = options.from ?? STUDIO_PACKAGE_DIR;
+  const html = await readFile(join(from, STUDIO_CANVAS), "utf8");
+  return canvasShellHtml(html, options.base);
+}
+
+/**
+ * Write `dist/manifest.json` — {@link STUDIO_ASSETS} as data, for a host that cannot import
+ * TypeScript. Called by the build; gated against the manifest by check-studio-dist.ts.
+ */
+export async function writeAssetManifest(root: string = STUDIO_PACKAGE_DIR): Promise<void> {
+  const out = join(root, "dist", "manifest.json");
+  await mkdir(dirname(out), { recursive: true });
+  await writeFile(
+    out,
+    `${JSON.stringify({ assets: STUDIO_ASSETS, shell: STUDIO_SHELL }, null, 2)}\n`,
+  );
+}

package/src/hosting/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "//": "The hosting contract is compiled under a CONSUMER's flags, not this repo's.",
+  "//why": "These three modules are published for other repositories to import, and jx-platform — the first real subscriber — sets exactOptionalPropertyTypes, verbatimModuleSyntax and isolatedModules, none of which the jx root tsconfig sets. Two type errors were found by consuming the API rather than by building it: `from: string | undefined` did not satisfy `from?: string` under exactOptionalPropertyTypes. Compiling this directory under the stricter set means the next one is found here instead of after a release. `types: []` and a bare lib are the other half: layout.ts and document.ts must not depend on node or DOM globals, because a Worker build, a Vite plugin or a Deno host has to be able to read them.",
+  "compilerOptions": {
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "module": "preserve",
+    "moduleResolution": "bundler",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "types": ["bun"]
+  },
+  "include": ["layout.ts", "document.ts"]
+}

package/src/panels/ai-chat/chat-view.ts

@@ -32,6 +32,7 @@
  */
 
 import { html, nothing } from "lit-html";
+import { repeat } from "lit-html/directives/repeat.js";
 import type { TemplateResult } from "lit-html";
 import { ref } from "lit-html/directives/ref.js";
 import type { Message, ToolCallRecord } from "@jxsuite/ai/chat-state";
@@ -443,21 +444,31 @@ export function renderMessageList(opts: MessageListOptions): TemplateResult {
             `
           : nothing
       }
-      ${messages.map((msg, i) => {
-        if (msg.role === "user") {
-          return renderUserMessage(msg);
-        }
-        if (msg.role === "tool") {
-          return renderToolMessage(msg);
-        }
-        if (msg.role === "assistant") {
-          if (status === "streaming" && i === lastIdx) {
-            return renderStreamingTail(msg);
+      ${repeat(
+        messages,
+        /* Keyed on msg.id, for two reasons a reader can see. The last assistant row swaps between
+           renderStreamingTail and renderAssistantMessage the moment a stream completes, so an
+           unkeyed list tears down and rebuilds the longest node in the transcript every time one
+           finishes. And an assistant row holds the reader's OWN open/closed state on its
+           ai-msg-changes details element, which position-based reuse hands to a different
+           message. */
+        (msg) => msg.id,
+        (msg, i) => {
+          if (msg.role === "user") {
+            return renderUserMessage(msg);
           }
-          return renderAssistantMessage(msg, opts.onRestore);
-        }
-        return nothing;
-      })}
+          if (msg.role === "tool") {
+            return renderToolMessage(msg);
+          }
+          if (msg.role === "assistant") {
+            if (status === "streaming" && i === lastIdx) {
+              return renderStreamingTail(msg);
+            }
+            return renderAssistantMessage(msg, opts.onRestore);
+          }
+          return nothing;
+        },
+      )}
       ${
         status !== "streaming" && opts.error
           ? html`

package/src/panels/git-panel.ts

@@ -13,7 +13,7 @@ import { repeat } from "lit-html/directives/repeat.js";
 import { getPlatform } from "../platform";
 import { now } from "../services/clock";
 import { formatForPath } from "../format/format-host";
-import { projectState } from "../store";
+import { projectState, renderOnly } from "../store";
 import { activeTab } from "../workspace/workspace";
 import type { Tab } from "../tabs/tab";
 import { shell } from "../shell";
@@ -245,6 +245,16 @@ async function doPull() {
  */
 let _pollTimer = null as ReturnType<typeof setInterval> | null;
 
+/**
+ * Whether the commit button's split menu is showing.
+ *
+ * State rather than a `hidden` attribute toggled on a node found by selector. The two were fighting
+ * by construction: the template declared the menu `hidden` unconditionally, so lit had committed
+ * that attribute, and every repaint of the panel — the 30-second git poll among them — would leave
+ * whatever the handler had last done to it standing, with no way for the template to take it back.
+ */
+let _splitMenuOpen = false;
+
 async function fetchGitLog() {
   const plat = getPlatform();
   try {
@@ -583,25 +593,18 @@ export function renderGitPanel(ctx: {
           <sp-action-button
             class="git-split-trigger"
             size="s"
-            @click=${(e: Event) => {
-              const menu = (
-                (e.currentTarget as HTMLElement).parentElement as HTMLElement
-              ).querySelector(".git-split-menu");
-              if (menu) {
-                menu.toggleAttribute("hidden");
-              }
+            @click=${() => {
+              _splitMenuOpen = !_splitMenuOpen;
+              renderOnly("leftPanel");
             }}
           >
             <sp-icon-chevron-down slot="icon" size="xs"></sp-icon-chevron-down>
           </sp-action-button>
-          <div class="git-split-menu" hidden>
+          <div class="git-split-menu" ?hidden=${!_splitMenuOpen}>
             <button
               class="git-split-menu-item"
-              @click=${(e: Event) => {
-                ((e.currentTarget as HTMLElement).parentElement as HTMLElement).setAttribute(
-                  "hidden",
-                  "",
-                );
+              @click=${() => {
+                _splitMenuOpen = false;
                 void doCommit();
               }}
             >

package/src/panels/head-panel.ts

@@ -7,6 +7,7 @@
  */
 
 import { html, nothing } from "lit-html";
+import { createRef, ref } from "lit-html/directives/ref.js";
 import { renderFieldRow } from "../ui/field-row";
 import { spTextArea, spTextField } from "../ui/field-input";
 import { renderMediaPicker } from "../ui/media-picker";
@@ -28,6 +29,18 @@ import type { JxHeadEntry, JxMutableNode } from "@jxsuite/schema/types";
 import type { Tab } from "../tabs/tab";
 import type { TemplateResult } from "lit-html";
 
+/**
+ * The add-a-tag draft fields.
+ *
+ * Uncontrolled by design — the draft is not state anything else reads, and rendering it back on
+ * every keystroke would fight the typist. Held as refs rather than re-found by selector: the row is
+ * rebuilt on every Head repaint, so a node resolved once is detached by the time it is used, and
+ * with a second pane open a document-wide query can return the other pane's field.
+ */
+const _addTag = createRef<HTMLInputElement>();
+const _addAttr = createRef<HTMLInputElement>();
+const _addVal = createRef<HTMLInputElement>();
+
 interface MetaField {
   label: string;
   attr: "name" | "property";
@@ -982,7 +995,7 @@ export function renderHeadTemplate({
 
         <!-- Add custom tag form -->
         <div class="head-add-form">
-          <sp-picker size="s" label="Tag" class="head-add-tag" value="meta">
+          <sp-picker size="s" label="Tag" class="head-add-tag" ${ref(_addTag)}>
             <sp-menu-item value="meta">meta</sp-menu-item>
             <sp-menu-item value="link">link</sp-menu-item>
             <sp-menu-item value="script">script</sp-menu-item>
@@ -991,28 +1004,33 @@ export function renderHeadTemplate({
             placeholder="Attribute (e.g. name)"
             size="s"
             class="head-add-attr"
+            ${ref(_addAttr)}
+          ></sp-textfield>
+          <sp-textfield
+            placeholder="Value"
+            size="s"
+            class="head-add-val"
+            ${ref(_addVal)}
           ></sp-textfield>
-          <sp-textfield placeholder="Value" size="s" class="head-add-val"></sp-textfield>
           <sp-action-button
             quiet
             size="xs"
             title="Add tag"
-            @click=${(e: Event) => {
-              const form = (e.target as HTMLElement).closest(".head-add-form");
-              const tagPicker = form?.querySelector(".head-add-tag") as HTMLInputElement | null;
-              const attrField = form?.querySelector(".head-add-attr") as HTMLInputElement | null;
-              const valField = form?.querySelector(".head-add-val") as HTMLInputElement | null;
-              const tagName = tagPicker?.value || "meta";
-              const attrKey = attrField?.value?.trim();
-              const attrVal = valField?.value?.trim();
+            @click=${() => {
+              /* Handles, not a closest() walk back up to a form this same template drew three lines
+                 above. The fields are uncontrolled on purpose — the draft is not state anything
+                 else reads — so a ref is exactly what reading and clearing them needs. */
+              const tagName = _addTag.value?.value || "meta";
+              const attrKey = _addAttr.value?.value?.trim();
+              const attrVal = _addVal.value?.value?.trim();
               if (!attrKey || !attrVal) {
                 return;
               }
-              if (attrField) {
-                attrField.value = "";
+              if (_addAttr.value) {
+                _addAttr.value.value = "";
               }
-              if (valField) {
-                valField.value = "";
+              if (_addVal.value) {
+                _addVal.value.value = "";
               }
 
               const entry: JxHeadEntry = { attributes: {}, tagName };

package/src/panels/imports-panel.ts

@@ -9,6 +9,7 @@
  */
 
 import { html, nothing } from "lit-html";
+import { createRef, ref } from "lit-html/directives/ref.js";
 import { componentRegistry } from "../files/components";
 import {
   disableElement,
@@ -30,6 +31,10 @@ import type { ComponentEntry } from "../files/components";
 import type { ElementsEntry } from "../files/elements";
 import type { JxElement, JxMutableNode } from "@jxsuite/schema/types";
 
+/** The add-an-import draft fields — uncontrolled, held rather than re-found. See head-panel.ts. */
+const _addName = createRef<HTMLInputElement>();
+const _addPath = createRef<HTMLInputElement>();
+
 interface ImportsContext {
   renderLeftPanel: () => void;
   documentPath: string | null;
@@ -142,23 +147,37 @@ function renderSiteLevelImports(renderLeftPanel: () => void) {
               })
         }
         <div class="import-add-form">
-          <sp-textfield placeholder="Name" size="s" class="import-add-name"></sp-textfield>
-          <sp-textfield placeholder="Path" size="s" class="import-add-path"></sp-textfield>
+          <sp-textfield
+            placeholder="Name"
+            size="s"
+            class="import-add-name"
+            ${ref(_addName)}
+          ></sp-textfield>
+          <sp-textfield
+            placeholder="Path"
+            size="s"
+            class="import-add-path"
+            ${ref(_addPath)}
+          ></sp-textfield>
           <sp-action-button
             quiet
             size="xs"
             title="Add import"
-            @click=${async (e: Event) => {
-              const form = (e.target as HTMLElement).closest(".import-add-form");
-              const nameField = form?.querySelector(".import-add-name") as HTMLInputElement;
-              const pathField = form?.querySelector(".import-add-path") as HTMLInputElement;
-              const name = nameField?.value?.trim();
-              const path = pathField?.value?.trim();
+            @click=${async () => {
+              /* Handles rather than a closest() walk back to a form drawn six lines above. The
+                 fields are an uncontrolled draft, so a ref is what reading and clearing them
+                 wants — and the panel is rebuilt on every repaint, so a node found once is gone. */
+              const name = _addName.value?.value?.trim();
+              const path = _addPath.value?.value?.trim();
               if (!name || !path) {
                 return;
               }
-              nameField.value = "";
-              pathField.value = "";
+              if (_addName.value) {
+                _addName.value.value = "";
+              }
+              if (_addPath.value) {
+                _addPath.value.value = "";
+              }
               const updated = { ...siteImports, [name]: path };
               await updateSiteConfig({ imports: updated });
               renderLeftPanel();
@@ -326,10 +345,10 @@ function renderDocumentLevelImports({
 
   const packageGroups = groupByPackage();
 
-  /** @param {string} ref */
-  const removeRef = (ref: string) => {
+  /** @param {string} elementRef The element reference to drop. Not `ref` — that is lit's directive. */
+  const removeRef = (elementRef: string) => {
     applyMutation((doc: JxMutableNode) => {
-      doc.$elements = removeElementRef((doc.$elements ?? []) as ElementsEntry[], ref) as (
+      doc.$elements = removeElementRef((doc.$elements ?? []) as ElementsEntry[], elementRef) as (
         | string
         | JxElement
       )[];