@runtypelabs/persona 4.7.0 → 4.9.0

package/src/utils/artifact-custom-actions.ts

@@ -0,0 +1,128 @@
+import type {
+  PersonaArtifactActionContext,
+  PersonaArtifactCustomAction,
+  PersonaArtifactRecord,
+} from "../types";
+import { createIconButton, createLabelButton } from "./buttons";
+import { createElement } from "./dom";
+
+/** Base class applied to every custom artifact action button. */
+const CUSTOM_ACTION_CLASS = "persona-artifact-custom-action-btn";
+
+/**
+ * Builds a toolbar/card button for a {@link PersonaArtifactCustomAction}.
+ *
+ * The result always carries `persona-artifact-custom-action-btn` after the
+ * button-system base classes. When `opts.documentChrome` is set, the button
+ * also picks up the document-toolbar styling used by the built-in controls.
+ *
+ * A string `icon` routes through the shared button helpers; a factory `icon`
+ * is hand-assembled to match the same class structure so author-owned SVGs
+ * slot in without duplicating the button system. A throwing factory falls back
+ * to a no-icon button rather than breaking the toolbar.
+ *
+ * `opts.onClick` (used by the toolbar path) is attached as a click listener;
+ * the card path omits it and wires clicks via event delegation instead.
+ */
+export function buildArtifactActionButton(
+  action: PersonaArtifactCustomAction,
+  opts?: { documentChrome?: boolean; onClick?: () => void }
+): HTMLButtonElement {
+  const documentChrome = opts?.documentChrome ?? false;
+
+  let btn: HTMLButtonElement;
+
+  if (typeof action.icon === "function") {
+    // Hand-assemble to mirror createIconButton/createLabelButton, with the
+    // author-provided element in place of a Lucide icon.
+    if (action.showLabel) {
+      const className =
+        "persona-label-btn persona-label-btn--sm " +
+        CUSTOM_ACTION_CLASS +
+        (documentChrome ? " persona-artifact-doc-copy-btn" : "");
+      btn = createElement("button", className);
+    } else {
+      const className =
+        "persona-icon-btn " +
+        CUSTOM_ACTION_CLASS +
+        (documentChrome ? " persona-artifact-doc-icon-btn" : "");
+      btn = createElement("button", className);
+    }
+    btn.type = "button";
+    btn.setAttribute("aria-label", action.label);
+    btn.title = action.label;
+
+    try {
+      const el = action.icon();
+      if (el) {
+        btn.appendChild(el);
+      }
+    } catch {
+      /* a throwing factory must not break the toolbar; fall back to no icon */
+    }
+
+    if (action.showLabel) {
+      const span = createElement("span");
+      span.textContent = action.label;
+      btn.appendChild(span);
+    }
+  } else if (action.showLabel || !action.icon) {
+    // Visible label, or no icon at all: icon-less actions fall back to a text
+    // button so the control always has a visible affordance (an empty
+    // icon-only button would render as a bare chip and warn on every render).
+    btn = createLabelButton({
+      icon: action.icon,
+      label: action.label,
+      className:
+        CUSTOM_ACTION_CLASS + (documentChrome ? " persona-artifact-doc-copy-btn" : ""),
+    });
+  } else {
+    // Icon-only: icon is a registry name.
+    btn = createIconButton({
+      icon: action.icon,
+      label: action.label,
+      className:
+        CUSTOM_ACTION_CLASS + (documentChrome ? " persona-artifact-doc-icon-btn" : ""),
+    });
+  }
+
+  if (opts?.onClick) {
+    btn.addEventListener("click", opts.onClick);
+  }
+
+  return btn;
+}
+
+/**
+ * Derives an action context from a persisted artifact record, mirroring how the
+ * artifact pane discriminates record shapes. Returns `null` when no record is
+ * available so callers can skip evaluating visibility gates / handlers.
+ */
+export function artifactRecordActionContext(
+  record: PersonaArtifactRecord | undefined
+): PersonaArtifactActionContext | null {
+  if (!record) {
+    return null;
+  }
+
+  const ctx: PersonaArtifactActionContext = {
+    artifactId: record.id,
+    title: record.title ?? "",
+    artifactType: record.artifactType,
+  };
+
+  if (record.artifactType === "markdown") {
+    ctx.markdown = record.markdown ?? "";
+    if (record.file) {
+      ctx.file = record.file;
+    }
+  } else {
+    ctx.jsonPayload = JSON.stringify(
+      { component: record.component, props: record.props },
+      null,
+      2
+    );
+  }
+
+  return ctx;
+}

package/src/utils/artifact-display.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import { resolveArtifactDisplayMode } from "./artifact-display";
+
+describe("resolveArtifactDisplayMode", () => {
+  it("returns 'panel' when the feature is undefined", () => {
+    expect(resolveArtifactDisplayMode(undefined, "markdown")).toBe("panel");
+  });
+
+  it("returns 'panel' when display is unset", () => {
+    expect(resolveArtifactDisplayMode({ enabled: true }, "markdown")).toBe("panel");
+  });
+
+  it("returns the string form directly", () => {
+    expect(resolveArtifactDisplayMode({ display: "inline" }, "markdown")).toBe("inline");
+    expect(resolveArtifactDisplayMode({ display: "card" }, "component")).toBe("card");
+  });
+
+  it("uses the object default when no byType entry matches", () => {
+    expect(resolveArtifactDisplayMode({ display: { default: "card" } }, "markdown")).toBe("card");
+  });
+
+  it("prefers a byType override over the default", () => {
+    const feature = {
+      display: { default: "panel" as const, byType: { markdown: "inline" as const } }
+    };
+    expect(resolveArtifactDisplayMode(feature, "markdown")).toBe("inline");
+  });
+
+  it("falls back to the default on a byType miss", () => {
+    const feature = {
+      display: { default: "card" as const, byType: { markdown: "inline" as const } }
+    };
+    expect(resolveArtifactDisplayMode(feature, "component")).toBe("card");
+  });
+
+  it("returns 'panel' for an object with neither default nor a matching byType", () => {
+    expect(resolveArtifactDisplayMode({ display: {} }, "markdown")).toBe("panel");
+    expect(
+      resolveArtifactDisplayMode({ display: { byType: { component: "inline" } } }, "markdown")
+    ).toBe("panel");
+  });
+});

package/src/utils/artifact-display.ts

@@ -0,0 +1,84 @@
+import type {
+  AgentWidgetArtifactsFeature,
+  PersonaArtifactDisplayMode,
+  PersonaArtifactFileMeta
+} from "../types";
+
+/**
+ * Resolves the display mode for an artifact of the given type from
+ * `features.artifacts.display`.
+ *
+ * Resolution order: `display.byType[artifactType]`, else `display.default`,
+ * else `display` (string form), else `"panel"` (current behavior).
+ */
+export function resolveArtifactDisplayMode(
+  feature: AgentWidgetArtifactsFeature | undefined,
+  artifactType: string
+): PersonaArtifactDisplayMode {
+  const display = feature?.display;
+  if (!display) return "panel";
+  if (typeof display === "string") return display;
+  const byType = display.byType as
+    | Partial<Record<string, PersonaArtifactDisplayMode>>
+    | undefined;
+  return byType?.[artifactType] ?? display.default ?? "panel";
+}
+
+/** Props embedded in an in-thread artifact block's rawContent JSON. */
+export type ArtifactRefBlockProps = {
+  artifactId: string;
+  title?: string;
+  artifactType: string;
+  status: "streaming" | "complete";
+  /** File metadata for previewable file artifacts (persists the download path). */
+  file?: PersonaArtifactFileMeta;
+  /**
+   * Component name for component-type artifacts. Only embedded for the
+   * "inline" display mode: the inline block renders component artifacts
+   * through the registry, so it needs the name in its props; the card never
+   * reads it.
+   */
+  component?: string;
+  /**
+   * Props for component-type artifacts. Embedded alongside `component` for the
+   * "inline" display mode so a refreshed session re-invokes the registered
+   * renderer with its real props (the session artifact registry is not
+   * persisted); the card never reads them.
+   */
+  componentProps?: Record<string, unknown>;
+  /** Final markdown content, embedded once complete so hydration/download work after refresh. */
+  markdown?: string;
+};
+
+/**
+ * Builds the `rawContent` JSON for the synthetic assistant message that
+ * anchors an artifact in the transcript (message id `artifact-ref-<id>`).
+ *
+ * "card"/"panel" modes render the compact `PersonaArtifactCard`; "inline"
+ * renders the `PersonaArtifactInline` preview block. Both share this shape so
+ * transcript persistence and hydration work unchanged. Used by the streaming
+ * client (`artifact_start`) and the programmatic `session.upsertArtifact()`.
+ */
+export function buildArtifactRefRawContent(
+  displayMode: PersonaArtifactDisplayMode,
+  props: ArtifactRefBlockProps
+): string {
+  return JSON.stringify({
+    component:
+      displayMode === "inline" ? "PersonaArtifactInline" : "PersonaArtifactCard",
+    props: {
+      artifactId: props.artifactId,
+      title: props.title,
+      artifactType: props.artifactType,
+      status: props.status,
+      ...(props.file ? { file: props.file } : {}),
+      ...(displayMode === "inline" && props.component
+        ? { component: props.component }
+        : {}),
+      ...(displayMode === "inline" && props.componentProps
+        ? { componentProps: props.componentProps }
+        : {}),
+      ...(props.markdown !== undefined ? { markdown: props.markdown } : {})
+    }
+  });
+}

package/src/utils/artifact-file.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "vitest";
+import {
+  extractFileSource,
+  fileKindOf,
+  fileTypeLabel,
+  downloadInfoFor,
+  basenameOf,
+} from "./artifact-file";
+
+// Canonical cross-repo fixture. The zero-width space is written as a
+// backslash-u200b escape sequence (not a literal invisible char) so the bytes
+// are unambiguous in source.
+// Mirrors core/packages/shared/src/file-artifact.ts escapeFenceTerminators fixture — keep byte-identical.
+const ZWSP = "\u200b";
+const FIXTURE_RAW = "# Title\n\n```js\nconsole.log('hi')\n```\n";
+const FIXTURE_ESCAPED =
+  "# Title\n\n`" + ZWSP + "``js\nconsole.log('hi')\n`" + ZWSP + "``\n";
+const FIXTURE_WIRE = "```md\n" + FIXTURE_ESCAPED + "\n```";
+
+describe("extractFileSource", () => {
+  it("round-trips the canonical cross-repo fixture byte-for-byte", () => {
+    expect(extractFileSource(FIXTURE_WIRE)).toBe(FIXTURE_RAW);
+  });
+
+  it("passes through content without a leading fence unchanged", () => {
+    const plain = "just some text\nwith lines\n";
+    expect(extractFileSource(plain)).toBe(plain);
+  });
+
+  it("reverses multiple escaped fences", () => {
+    const raw = "```a\n```b\n```c\n";
+    const escaped = raw.split("```").join("`" + ZWSP + "``");
+    const wire = "```md\n" + escaped + "\n```";
+    expect(extractFileSource(wire)).toBe(raw);
+  });
+
+  it("unfences a simple html file", () => {
+    const raw = "<h1>hi</h1>\n";
+    const wire = "```html\n" + raw + "\n```";
+    expect(extractFileSource(wire)).toBe(raw);
+  });
+
+  it("handles empty file content", () => {
+    const wire = "```md\n\n```";
+    expect(extractFileSource(wire)).toBe("");
+  });
+
+  it("returns empty string for non-string input", () => {
+    // @ts-expect-error deliberate misuse
+    expect(extractFileSource(undefined)).toBe("");
+  });
+});
+
+describe("fileKindOf", () => {
+  it("classifies by extension", () => {
+    expect(fileKindOf({ path: "a/cat.html", mimeType: "text/html" })).toBe("html");
+    expect(fileKindOf({ path: "cat.htm", mimeType: "text/html" })).toBe("html");
+    expect(fileKindOf({ path: "logo.svg", mimeType: "image/svg+xml" })).toBe("svg");
+    expect(fileKindOf({ path: "notes.md", mimeType: "text/markdown" })).toBe("markdown");
+    expect(fileKindOf({ path: "notes.mdx", mimeType: "text/markdown" })).toBe("markdown");
+    expect(fileKindOf({ path: "data.json", mimeType: "application/json" })).toBe("other");
+  });
+
+  it("falls back to mimeType when there is no extension", () => {
+    expect(fileKindOf({ path: "README", mimeType: "text/html" })).toBe("html");
+    expect(fileKindOf({ path: "drawing", mimeType: "image/svg+xml" })).toBe("svg");
+    expect(fileKindOf({ path: "doc", mimeType: "text/markdown" })).toBe("markdown");
+    expect(fileKindOf({ path: "blob", mimeType: "application/octet-stream" })).toBe("other");
+  });
+});
+
+describe("fileTypeLabel", () => {
+  it("produces human labels", () => {
+    expect(fileTypeLabel({ path: "cat.html", mimeType: "text/html" })).toBe("HTML");
+    expect(fileTypeLabel({ path: "logo.svg", mimeType: "image/svg+xml" })).toBe("SVG");
+    expect(fileTypeLabel({ path: "notes.md", mimeType: "text/markdown" })).toBe("Markdown");
+    expect(fileTypeLabel({ path: "data.csv", mimeType: "text/csv" })).toBe("CSV");
+    expect(fileTypeLabel({ path: "blob", mimeType: "application/octet-stream" })).toBe("File");
+  });
+});
+
+describe("basenameOf", () => {
+  it("returns the last path segment", () => {
+    expect(basenameOf("/mnt/session/outputs/cat.html")).toBe("cat.html");
+    expect(basenameOf("cat.html")).toBe("cat.html");
+    expect(basenameOf("a\\b\\c.txt")).toBe("c.txt");
+  });
+});
+
+describe("downloadInfoFor", () => {
+  it("uses basename + real MIME + unfenced source for file records", () => {
+    const info = downloadInfoFor({
+      title: "outputs/cat.html",
+      markdown: "```html\n<h1>hi</h1>\n\n```",
+      file: { path: "outputs/cat.html", mimeType: "text/html" },
+    });
+    expect(info.filename).toBe("cat.html");
+    expect(info.mime).toBe("text/html");
+    expect(info.content).toBe("<h1>hi</h1>\n");
+  });
+
+  it("preserves legacy .md / text/markdown behavior for non-file records", () => {
+    const info = downloadInfoFor({
+      title: "My Doc",
+      markdown: "## Hello\n\nbody",
+    });
+    expect(info.filename).toBe("My Doc.md");
+    expect(info.mime).toBe("text/markdown");
+    expect(info.content).toBe("## Hello\n\nbody");
+  });
+
+  it("defaults filename for a titleless non-file record", () => {
+    const info = downloadInfoFor({ markdown: "x" });
+    expect(info.filename).toBe("artifact.md");
+  });
+});

package/src/utils/artifact-file.ts

@@ -0,0 +1,117 @@
+/**
+ * Helpers for previewable file artifacts.
+ *
+ * When a Claude Managed agent writes a file, the core backend encodes it as a
+ * markdown artifact whose content is a fenced code block (extension → fence
+ * language) plus a `file` metadata field on `artifact_start`. The content stays
+ * fenced on the wire for backward compatibility; these helpers recover the raw
+ * source and classify the file for preview / download.
+ */
+import type { PersonaArtifactFileMeta } from "../types";
+
+const ZERO_WIDTH_SPACE = "​";
+
+/** basename of a POSIX or Windows style path. */
+export function basenameOf(path: string): string {
+  const parts = String(path).split(/[\\/]/);
+  return parts[parts.length - 1] ?? "";
+}
+
+/** lowercase file extension (without the dot), or "" when there is none. */
+function extensionOf(path: string): string {
+  const base = basenameOf(path);
+  const dot = base.lastIndexOf(".");
+  // dot at index 0 (dotfile) or no dot means "no extension"
+  if (dot <= 0) return "";
+  return base.slice(dot + 1).toLowerCase();
+}
+
+/**
+ * Recover raw file source from core's fenced wire content.
+ *
+ * The producer builds content as `` ```${lang}\n${escaped}\n``` `` where every
+ * literal triple-backtick in the source is replaced with backtick + U+200B
+ * (zero-width space) + backtick backtick. So the content is exactly
+ * `firstline + "\n" + escapedSource + "\n" + lastline`; dropping the first and
+ * last lines yields the escaped source, then the ZWSP escape is reversed.
+ *
+ * Graceful: if `markdown` does not start with a fence line, it is returned
+ * unchanged.
+ */
+export function extractFileSource(markdown: string): string {
+  if (typeof markdown !== "string") return "";
+  const firstNl = markdown.indexOf("\n");
+  if (firstNl === -1) return markdown;
+  const firstLine = markdown.slice(0, firstNl);
+  if (!firstLine.startsWith("```")) return markdown;
+  const rest = markdown.slice(firstNl + 1);
+  const lastNl = rest.lastIndexOf("\n");
+  const escaped = lastNl === -1 ? rest : rest.slice(0, lastNl);
+  // Reverse core's fence-terminator escape (backtick + ZWSP + backtick backtick).
+  return escaped.split("`" + ZERO_WIDTH_SPACE + "``").join("```");
+}
+
+/** Coarse file kind used to pick a preview strategy. */
+export function fileKindOf(
+  meta: PersonaArtifactFileMeta
+): "html" | "svg" | "markdown" | "other" {
+  const ext = extensionOf(meta.path);
+  if (ext) {
+    if (ext === "html" || ext === "htm") return "html";
+    if (ext === "svg") return "svg";
+    if (ext === "md" || ext === "mdx") return "markdown";
+    return "other";
+  }
+  const mime = (meta.mimeType || "").toLowerCase();
+  if (mime.includes("html")) return "html";
+  if (mime.includes("svg")) return "svg";
+  if (mime.includes("markdown")) return "markdown";
+  return "other";
+}
+
+/** Human-readable file type label for card subtitles / pane titles. */
+export function fileTypeLabel(meta: PersonaArtifactFileMeta): string {
+  switch (fileKindOf(meta)) {
+    case "html":
+      return "HTML";
+    case "svg":
+      return "SVG";
+    case "markdown":
+      return "Markdown";
+    default: {
+      const ext = extensionOf(meta.path);
+      return ext ? ext.toUpperCase() : "File";
+    }
+  }
+}
+
+/** Minimal record shape needed to compute download info. */
+export interface ArtifactDownloadSource {
+  title?: string;
+  markdown?: string;
+  file?: PersonaArtifactFileMeta;
+}
+
+/**
+ * Resolve the download filename, MIME type, and content for an artifact.
+ *
+ * File artifacts download the raw unfenced source under their basename with
+ * their real MIME type. Non-file markdown artifacts preserve the legacy
+ * behavior exactly: `<title>.md`, `text/markdown`, raw fenced/markdown content.
+ */
+export function downloadInfoFor(record: ArtifactDownloadSource): {
+  filename: string;
+  mime: string;
+  content: string;
+} {
+  const raw = record.markdown ?? "";
+  if (record.file) {
+    return {
+      filename: basenameOf(record.file.path) || "artifact",
+      mime: record.file.mimeType || "application/octet-stream",
+      content: extractFileSource(raw),
+    };
+  }
+  const title = record.title || "artifact";
+  return { filename: `${title}.md`, mime: "text/markdown", content: raw };
+}

package/src/utils/artifact-gate.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import {
   applyArtifactLayoutCssVars,
   applyArtifactPaneAppearance,
@@ -69,10 +69,9 @@ describe("applyArtifactPaneAppearance", () => {
     );
     expect(mount.classList.contains("persona-artifact-appearance-panel")).toBe(true);
     expect(mount.style.getPropertyValue("--persona-artifact-pane-radius")).toBe("");
-    expect(mount.classList.contains("persona-artifact-unified-split")).toBe(false);
   });
 
-  it("adds unified split class and optional outer radius", () => {
+  it("treats unifiedSplitChrome as a no-op and no longer owns the welded outer radius", () => {
     const mount = createFakeMount();
     applyArtifactPaneAppearance(
       mount,
@@ -82,8 +81,11 @@ describe("applyArtifactPaneAppearance", () => {
         },
       })
     );
-    expect(mount.classList.contains("persona-artifact-unified-split")).toBe(true);
-    expect(mount.style.getPropertyValue("--persona-artifact-unified-outer-radius").trim()).toBe("12px");
+    // Welding is now the default (JS-toggled at runtime), so the deprecated
+    // option adds no class here. The welded outer radius is owned by ui.ts
+    // syncPanelChrome (derived from the resolved panel radius), not this function.
+    expect(mount.classList.contains("persona-artifact-unified-split")).toBe(false);
+    expect(mount.style.getPropertyValue("--persona-artifact-welded-outer-radius").trim()).toBe("");
   });
 
   it("adds seamless class and border radius on any mode", () => {
@@ -134,6 +136,79 @@ describe("applyArtifactPaneAppearance", () => {
     );
     expect(mount.classList.contains("persona-artifact-appearance-panel")).toBe(true);
   });
+
+  it("resolves detached when detachedPanel true and paneAppearance unset", () => {
+    const mount = createFakeMount();
+    applyArtifactPaneAppearance(
+      mount,
+      baseConfig({
+        launcher: { detachedPanel: true },
+        features: { artifacts: { enabled: true } },
+      })
+    );
+    expect(mount.classList.contains("persona-artifact-appearance-detached")).toBe(true);
+    expect(mount.classList.contains("persona-artifact-appearance-panel")).toBe(false);
+  });
+
+  it("explicit panel beats detachedPanel true", () => {
+    const mount = createFakeMount();
+    applyArtifactPaneAppearance(
+      mount,
+      baseConfig({
+        launcher: { detachedPanel: true },
+        features: { artifacts: { enabled: true, layout: { paneAppearance: "panel" } } },
+      })
+    );
+    expect(mount.classList.contains("persona-artifact-appearance-panel")).toBe(true);
+    expect(mount.classList.contains("persona-artifact-appearance-detached")).toBe(false);
+  });
+
+  it("explicit detached works without detachedPanel", () => {
+    const mount = createFakeMount();
+    applyArtifactPaneAppearance(
+      mount,
+      baseConfig({
+        features: { artifacts: { enabled: true, layout: { paneAppearance: "detached" } } },
+      })
+    );
+    expect(mount.classList.contains("persona-artifact-appearance-detached")).toBe(true);
+  });
+
+  it("treats unifiedSplitChrome as a silent no-op when detached", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const mount = createFakeMount();
+    applyArtifactPaneAppearance(
+      mount,
+      baseConfig({
+        features: {
+          artifacts: {
+            enabled: true,
+            layout: { paneAppearance: "detached", unifiedSplitChrome: true },
+          },
+        },
+      })
+    );
+    expect(mount.classList.contains("persona-artifact-appearance-detached")).toBe(true);
+    expect(mount.classList.contains("persona-artifact-unified-split")).toBe(false);
+    // Deprecated no-op: no warning now that welding is the panel/seamless default.
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it("keeps explicit paneShadow over detached defaults", () => {
+    const mount = createFakeMount();
+    applyArtifactPaneAppearance(
+      mount,
+      baseConfig({
+        launcher: { detachedPanel: true },
+        features: { artifacts: { enabled: true, layout: { paneShadow: "0 0 0 red" } } },
+      })
+    );
+    expect(mount.classList.contains("persona-artifact-appearance-detached")).toBe(true);
+    expect(mount.style.getPropertyValue("--persona-artifact-pane-shadow").trim()).toBe(
+      "0 0 0 red"
+    );
+  });
 });
 
 describe("applyArtifactPaneBorderTheme", () => {
@@ -213,6 +288,38 @@ describe("applyArtifactLayoutCssVars", () => {
     expect(mount.style.getPropertyValue("--persona-artifact-pane-padding").trim()).toBe("24px");
   });
 
+  it("defaults split gap to panel inset when detached, explicit splitGap wins", () => {
+    const detached = createFakeMount();
+    applyArtifactLayoutCssVars(
+      detached,
+      baseConfig({
+        launcher: { detachedPanel: true },
+        features: { artifacts: { enabled: true } },
+      })
+    );
+    expect(detached.style.getPropertyValue("--persona-artifact-split-gap").trim()).toBe(
+      "var(--persona-panel-inset)"
+    );
+
+    const explicit = createFakeMount();
+    applyArtifactLayoutCssVars(
+      explicit,
+      baseConfig({
+        launcher: { detachedPanel: true },
+        features: { artifacts: { enabled: true, layout: { splitGap: "2rem" } } },
+      })
+    );
+    expect(explicit.style.getPropertyValue("--persona-artifact-split-gap").trim()).toBe("2rem");
+
+    // Panel/seamless weld at gap 0 by default.
+    const welded = createFakeMount();
+    applyArtifactLayoutCssVars(
+      welded,
+      baseConfig({ features: { artifacts: { enabled: true } } })
+    );
+    expect(welded.style.getPropertyValue("--persona-artifact-split-gap").trim()).toBe("0");
+  });
+
   it("clears pane bg and padding when artifacts disabled", () => {
     const mount = createFakeMount();
     mount.style.setProperty("--persona-artifact-pane-bg", "#000");