@runtypelabs/persona 4.7.0 → 4.9.0

package/src/utils/artifact-gate.ts

@@ -39,6 +39,26 @@ function clearDocumentToolbarLayoutVars(mount: HTMLElement): void {
   mount.style.removeProperty("--persona-artifact-doc-toggle-active-border");
 }
 
+const ARTIFACT_APPEARANCE_MODES = ["panel", "seamless", "detached"] as const;
+type ArtifactAppearance = (typeof ARTIFACT_APPEARANCE_MODES)[number];
+
+/** Resolve the effective pane appearance, applying the detached-panel coordinated default. */
+function resolveArtifactPaneAppearance(config: AgentWidgetConfig): ArtifactAppearance {
+  const raw = config.features?.artifacts?.layout?.paneAppearance;
+  if (raw && (ARTIFACT_APPEARANCE_MODES as readonly string[]).includes(raw)) {
+    return raw as ArtifactAppearance;
+  }
+  if (raw) return "panel";
+  // Coordinated default: a detached panel gets a detached pane unless overridden.
+  return config.launcher?.detachedPanel ? "detached" : "panel";
+}
+
+/** True when the effective pane appearance resolves to "detached" (explicit or coordinated default). */
+export function isArtifactPaneAppearanceDetached(config: AgentWidgetConfig | undefined): boolean {
+  if (!config || !artifactsSidebarEnabled(config)) return false;
+  return resolveArtifactPaneAppearance(config) === "detached";
+}
+
 export function applyArtifactLayoutCssVars(mount: HTMLElement, config: AgentWidgetConfig): void {
   if (!artifactsSidebarEnabled(config)) {
     mount.style.removeProperty("--persona-artifact-split-gap");
@@ -52,7 +72,12 @@ export function applyArtifactLayoutCssVars(mount: HTMLElement, config: AgentWidg
     return;
   }
   const l = config.features?.artifacts?.layout;
-  mount.style.setProperty("--persona-artifact-split-gap", l?.splitGap ?? "0.5rem");
+  // Detached shows the canvas between columns; panel/seamless weld at gap 0.
+  const gapDefault =
+    resolveArtifactPaneAppearance(config) === "detached"
+      ? "var(--persona-panel-inset)"
+      : "0";
+  mount.style.setProperty("--persona-artifact-split-gap", l?.splitGap ?? gapDefault);
   mount.style.setProperty("--persona-artifact-pane-width", l?.paneWidth ?? "40%");
   mount.style.setProperty("--persona-artifact-pane-max-width", l?.paneMaxWidth ?? "28rem");
   if (l?.paneMinWidth) {
@@ -95,22 +120,18 @@ export function applyArtifactLayoutCssVars(mount: HTMLElement, config: AgentWidg
   applyArtifactPaneBorderTheme(mount, config);
 }
 
-const ARTIFACT_APPEARANCE_MODES = ["panel", "seamless"] as const;
-
-/** Toggle root classes for artifact pane appearance, radius, shadow, and unified chrome. */
+/** Toggle root classes for artifact pane appearance, radius, and shadow vars. */
 export function applyArtifactPaneAppearance(mount: HTMLElement, config: AgentWidgetConfig): void {
   for (const m of ARTIFACT_APPEARANCE_MODES) {
     mount.classList.remove(`persona-artifact-appearance-${m}`);
   }
-  mount.classList.remove("persona-artifact-unified-split");
   mount.style.removeProperty("--persona-artifact-pane-radius");
   mount.style.removeProperty("--persona-artifact-pane-shadow");
-  mount.style.removeProperty("--persona-artifact-unified-outer-radius");
+  mount.style.removeProperty("--persona-artifact-chat-shadow");
   if (!artifactsSidebarEnabled(config)) return;
 
   const layout = config.features?.artifacts?.layout;
-  const raw = layout?.paneAppearance ?? "panel";
-  const mode = (ARTIFACT_APPEARANCE_MODES as readonly string[]).includes(raw) ? raw : "panel";
+  const mode = resolveArtifactPaneAppearance(config);
   mount.classList.add(`persona-artifact-appearance-${mode}`);
 
   const radius = layout?.paneBorderRadius?.trim();
@@ -123,13 +144,17 @@ export function applyArtifactPaneAppearance(mount: HTMLElement, config: AgentWid
     mount.style.setProperty("--persona-artifact-pane-shadow", shadow);
   }
 
-  if (layout?.unifiedSplitChrome === true) {
-    mount.classList.add("persona-artifact-unified-split");
-    const outer = layout.unifiedSplitOuterRadius?.trim() || radius;
-    if (outer) {
-      mount.style.setProperty("--persona-artifact-unified-outer-radius", outer);
-    }
+  // Chat card gains its own front shadow lookup so a detached split can flatten
+  // the chat column while the pane stays raised. Unset falls back to the pane chain.
+  const chatShadow = layout?.chatShadow?.trim();
+  if (chatShadow) {
+    mount.style.setProperty("--persona-artifact-chat-shadow", chatShadow);
   }
+
+  // Panel/seamless splits weld by default; `unifiedSplitChrome` is a deprecated
+  // no-op. The welded outer-right radius (`--persona-artifact-welded-outer-radius`)
+  // is owned by ui.ts syncPanelChrome so it derives from the same resolved panel
+  // radius as the chat card; `unifiedSplitOuterRadius` / `paneBorderRadius` win there.
 }
 
 /** Widen floating panel when artifacts show (default true); `false` opts out. */

package/src/utils/artifact-loading-status.ts

@@ -0,0 +1,55 @@
+import type { AgentWidgetArtifactsFeature } from "../types";
+import { appendCharSpans } from "./tool-loading-animation";
+
+/**
+ * Apply the artifact "Generating …" streaming animation to a status element.
+ *
+ * Shared by the artifact reference card and the inline chrome so both surfaces
+ * honor `features.artifacts.loadingAnimation` (and the color / duration knobs)
+ * identically. Character-by-character modes (`shimmer`, `shimmer-color`,
+ * `rainbow`) wrap each character in a `persona-tool-char` span; `pulse` fades
+ * the whole element; `none` renders plain text.
+ *
+ * The caller owns the element and its reset — pass a fresh (or cleared) span so
+ * stale animation classes from a previous streaming render do not linger.
+ */
+export function applyArtifactLoadingStatus(
+  statusText: HTMLElement,
+  text: string,
+  artifactsCfg: AgentWidgetArtifactsFeature | undefined
+): void {
+  const loadingAnimation = artifactsCfg?.loadingAnimation ?? "shimmer";
+  const duration = artifactsCfg?.loadingAnimationDuration ?? 2000;
+
+  if (loadingAnimation === "none") {
+    statusText.textContent = text;
+    return;
+  }
+
+  if (loadingAnimation === "pulse") {
+    statusText.setAttribute("data-preserve-animation", "true");
+    statusText.classList.add("persona-tool-loading-pulse");
+    statusText.style.setProperty("--persona-tool-anim-duration", `${duration}ms`);
+    statusText.textContent = text;
+    return;
+  }
+
+  statusText.setAttribute("data-preserve-animation", "true");
+  statusText.classList.add(`persona-tool-loading-${loadingAnimation}`);
+  statusText.style.setProperty("--persona-tool-anim-duration", `${duration}ms`);
+  if (loadingAnimation === "shimmer-color") {
+    if (artifactsCfg?.loadingAnimationColor) {
+      statusText.style.setProperty(
+        "--persona-tool-anim-color",
+        artifactsCfg.loadingAnimationColor
+      );
+    }
+    if (artifactsCfg?.loadingAnimationSecondaryColor) {
+      statusText.style.setProperty(
+        "--persona-tool-anim-secondary-color",
+        artifactsCfg.loadingAnimationSecondaryColor
+      );
+    }
+  }
+  appendCharSpans(statusText, text, 0);
+}

package/src/utils/artifact-status-label.ts

@@ -0,0 +1,190 @@
+import type {
+  AgentWidgetArtifactsFeature,
+  PersonaArtifactRecord,
+  PersonaArtifactStatusLabelContext
+} from "../types";
+import { createElement } from "./dom";
+import { fileTypeLabel } from "./artifact-file";
+import { applyArtifactLoadingStatus } from "./artifact-loading-status";
+
+/**
+ * Shared resolver + applier for the artifact streaming status label
+ * (`features.artifacts.statusLabel`).
+ *
+ * Three surfaces render the "Generating …" status while an artifact streams:
+ * the reference card status line, the inline chrome meta span, and the inline
+ * streaming status body. All three resolve their text through
+ * {@link resolveArtifactStatusLabel} and paint it through
+ * {@link applyArtifactStatus}, so a host `statusLabel` string / function reads
+ * identically everywhere.
+ *
+ * Animation-stability contract: the animated label span is (re)built only when
+ * its text changes, so a per-delta detail update (live counters) never restarts
+ * the shimmer/pulse/typewriter animation. `applyArtifactStatus` enforces this by
+ * tracking the last-applied label text on the label span and by keeping the
+ * plain detail span as a separate sibling the animation never touches.
+ */
+
+export type ArtifactStatusSurface = "card" | "inline-chrome" | "status-body";
+
+export type ResolvedArtifactStatus = { label: string; detail?: string };
+
+/** Class on the animated label span managed inside a status container. */
+export const STATUS_LABEL_CLASS = "persona-artifact-status-label";
+/** Class on the plain, freely-updating detail span. */
+export const STATUS_DETAIL_CLASS = "persona-artifact-status-detail";
+/** Attribute recording the last label text applied to the label span. */
+const APPLIED_LABEL_ATTR = "data-artifact-status-label";
+
+/**
+ * First-seen streaming timestamp per artifact id, so `elapsedMs` starts near 0
+ * and a completed → re-streamed artifact restarts cleanly. Set on the first
+ * streaming resolve; cleared on complete (see {@link clearArtifactStatusTracking})
+ * so the map cannot grow without bound.
+ */
+const firstSeenAt = new Map<string, number>();
+
+const now = (): number =>
+  typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+
+/** Drop the elapsed-time tracking for an artifact. Call on complete. */
+export function clearArtifactStatusTracking(id: string): void {
+  if (id) firstSeenAt.delete(id);
+}
+
+/** Type subject used to build the default label; mirrors the card/chrome logic. */
+function typeLabelFor(record: PersonaArtifactRecord): string {
+  const file = record.artifactType === "markdown" ? record.file : undefined;
+  if (file) return fileTypeLabel(file);
+  return record.artifactType === "component" ? "Component" : "Document";
+}
+
+/**
+ * Resolve the streaming status label + optional detail for one surface.
+ *
+ * - `statusLabel` unset → the default `Generating <type>...`.
+ * - string → that string as the label (no detail).
+ * - function → called with a per-surface context; a string return is the label,
+ *   an object return is `{ label, detail }`. A throw falls back to the default.
+ */
+export function resolveArtifactStatusLabel(
+  record: PersonaArtifactRecord,
+  cfg: AgentWidgetArtifactsFeature | undefined,
+  surface: ArtifactStatusSurface
+): ResolvedArtifactStatus {
+  const typeLabel = typeLabelFor(record);
+  const defaultLabel = `Generating ${typeLabel.toLowerCase()}...`;
+
+  const statusLabel = cfg?.statusLabel;
+  if (typeof statusLabel === "string") {
+    return { label: statusLabel };
+  }
+  if (typeof statusLabel !== "function") {
+    return { label: defaultLabel };
+  }
+
+  // Track first-seen only while streaming (the surfaces only resolve while
+  // streaming); elapsedMs measures from that instant.
+  const id = record.id;
+  let firstSeen = firstSeenAt.get(id);
+  if (record.status !== "complete" && firstSeen === undefined) {
+    firstSeen = now();
+    firstSeenAt.set(id, firstSeen);
+  }
+  const elapsedMs = firstSeen === undefined ? 0 : Math.max(0, now() - firstSeen);
+
+  const isComponent = record.artifactType === "component";
+  const markdown =
+    !isComponent && typeof record.markdown === "string" ? record.markdown : "";
+  const chars = isComponent ? 0 : markdown.length;
+  const lines = isComponent || markdown === "" ? 0 : markdown.split("\n").length;
+  const file = record.artifactType === "markdown" ? record.file : undefined;
+
+  const ctx: PersonaArtifactStatusLabelContext = {
+    artifactId: id,
+    artifactType: record.artifactType,
+    title: record.title,
+    typeLabel,
+    file,
+    chars,
+    lines,
+    elapsedMs,
+    // Lazy: only materialize the accumulated source if the host asks for it.
+    content: () => (isComponent ? "" : markdown),
+    surface
+  };
+
+  try {
+    const result = statusLabel(ctx);
+    if (typeof result === "string") return { label: result };
+    if (
+      result &&
+      typeof result === "object" &&
+      typeof result.label === "string"
+    ) {
+      return {
+        label: result.label,
+        detail: typeof result.detail === "string" ? result.detail : undefined
+      };
+    }
+    // A malformed return (null/number/etc.) falls back like a throw.
+    return { label: defaultLabel };
+  } catch {
+    // A bad host callback must never break rendering.
+    return { label: defaultLabel };
+  }
+}
+
+/** Restore the label span to its base state before re-applying the animation. */
+function resetLabelSpan(labelEl: HTMLElement): void {
+  labelEl.className = STATUS_LABEL_CLASS;
+  labelEl.removeAttribute("data-preserve-animation");
+  labelEl.style.removeProperty("--persona-tool-anim-duration");
+  labelEl.style.removeProperty("--persona-tool-anim-color");
+  labelEl.style.removeProperty("--persona-tool-anim-secondary-color");
+  labelEl.replaceChildren();
+}
+
+/**
+ * Paint a resolved status into `container`, which owns exactly two children: an
+ * animated label span and an optional plain detail span.
+ *
+ * The label span is rebuilt (and its animation re-applied) ONLY when its text
+ * differs from the last application, so a detail-only update never restarts the
+ * loading animation. The detail span updates its `textContent` freely and is
+ * removed when the resolved detail is empty.
+ */
+export function applyArtifactStatus(
+  container: HTMLElement,
+  resolved: ResolvedArtifactStatus,
+  cfg: AgentWidgetArtifactsFeature | undefined
+): void {
+  let labelEl = container.querySelector<HTMLElement>(
+    `:scope > .${STATUS_LABEL_CLASS}`
+  );
+  if (!labelEl) {
+    labelEl = createElement("span", STATUS_LABEL_CLASS);
+    container.appendChild(labelEl);
+  }
+  if (labelEl.getAttribute(APPLIED_LABEL_ATTR) !== resolved.label) {
+    resetLabelSpan(labelEl);
+    applyArtifactLoadingStatus(labelEl, resolved.label, cfg);
+    labelEl.setAttribute(APPLIED_LABEL_ATTR, resolved.label);
+  }
+
+  let detailEl = container.querySelector<HTMLElement>(
+    `:scope > .${STATUS_DETAIL_CLASS}`
+  );
+  const detail = resolved.detail;
+  if (detail) {
+    if (!detailEl) {
+      detailEl = createElement("span", STATUS_DETAIL_CLASS);
+      container.appendChild(detailEl);
+    }
+    if (detailEl.textContent !== detail) detailEl.textContent = detail;
+  } else if (detailEl) {
+    detailEl.remove();
+  }
+}

package/src/utils/buttons.ts

@@ -149,6 +149,8 @@ export interface ToggleGroupItem {
   icon?: string;
   /** Accessible label for the button. */
   label: string;
+  /** Extra CSS class(es) appended after "persona-icon-btn". */
+  className?: string;
 }
 
 /** Options for {@link createToggleGroup}. */
@@ -202,6 +204,7 @@ export function createToggleGroup(options: CreateToggleGroupOptions): ToggleGrou
       btn = createIconButton({
         icon: item.icon,
         label: item.label,
+        className: item.className,
         onClick: () => {
           currentId = item.id;
           updatePressed();
@@ -209,7 +212,10 @@ export function createToggleGroup(options: CreateToggleGroupOptions): ToggleGrou
         },
       });
     } else {
-      btn = createElement("button", "persona-icon-btn");
+      btn = createElement(
+        "button",
+        "persona-icon-btn" + (item.className ? " " + item.className : ""),
+      );
       btn.type = "button";
       btn.setAttribute("aria-label", item.label);
       btn.title = item.label;

package/src/utils/chunk-loader.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi } from "vitest";
+import { createChunkLoader } from "./chunk-loader";
+
+type FakeModule = { value: number };
+
+describe("createChunkLoader", () => {
+  it("uses the fallback import when no loader is registered", async () => {
+    const mod: FakeModule = { value: 1 };
+    const fallbackImport = vi.fn(async () => mod);
+    const { load } = createChunkLoader<FakeModule>({ fallbackImport });
+
+    await expect(load()).resolves.toBe(mod);
+    expect(fallbackImport).toHaveBeenCalledTimes(1);
+  });
+
+  it("memoizes the resolved module and shares the in-flight promise", async () => {
+    const mod: FakeModule = { value: 2 };
+    const loader = vi.fn(async () => mod);
+    const { setLoader, load } = createChunkLoader<FakeModule>({
+      fallbackImport: async () => ({ value: -1 }),
+    });
+    setLoader(loader);
+
+    // Concurrent callers share one import.
+    const [a, b] = await Promise.all([load(), load()]);
+    expect(a).toBe(mod);
+    expect(b).toBe(mod);
+    // A later call returns the cached module without importing again.
+    await expect(load()).resolves.toBe(mod);
+    expect(loader).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries after a rejected load instead of caching the failure", async () => {
+    const mod: FakeModule = { value: 3 };
+    const loader = vi
+      .fn<() => Promise<FakeModule>>()
+      .mockRejectedValueOnce(new Error("network"))
+      .mockResolvedValueOnce(mod);
+    const { setLoader, load } = createChunkLoader<FakeModule>({
+      fallbackImport: async () => ({ value: -1 }),
+    });
+    setLoader(loader);
+
+    await expect(load()).rejects.toThrow("network");
+    // The failed promise was cleared, so a later call retries and resolves.
+    await expect(load()).resolves.toBe(mod);
+    expect(loader).toHaveBeenCalledTimes(2);
+    // Once resolved, the module is cached (no third loader call).
+    await expect(load()).resolves.toBe(mod);
+    expect(loader).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not invalidate the cache on setLoader by default", async () => {
+    const first: FakeModule = { value: 4 };
+    const second: FakeModule = { value: 5 };
+    const { setLoader, load } = createChunkLoader<FakeModule>({
+      fallbackImport: async () => ({ value: -1 }),
+    });
+
+    setLoader(async () => first);
+    await expect(load()).resolves.toBe(first);
+    // Registering a new loader after a resolved load has no effect: cache holds.
+    setLoader(async () => second);
+    await expect(load()).resolves.toBe(first);
+  });
+
+  it("invalidates the cache on setLoader when resetOnSetLoader is set", async () => {
+    const first: FakeModule = { value: 6 };
+    const second: FakeModule = { value: 7 };
+    const { setLoader, load } = createChunkLoader<FakeModule>({
+      fallbackImport: async () => ({ value: -1 }),
+      resetOnSetLoader: true,
+    });
+
+    setLoader(async () => first);
+    await expect(load()).resolves.toBe(first);
+    // A swapped loader takes effect: the previous module is discarded.
+    setLoader(async () => second);
+    await expect(load()).resolves.toBe(second);
+  });
+
+  it("provide() seeds the cache and getSync() reads it", async () => {
+    const mod: FakeModule = { value: 8 };
+    const loader = vi.fn(async () => ({ value: -1 }));
+    const { setLoader, load, provide, getSync } = createChunkLoader<FakeModule>({
+      fallbackImport: async () => ({ value: -1 }),
+    });
+    setLoader(loader);
+
+    expect(getSync()).toBeNull();
+    provide(mod);
+    expect(getSync()).toBe(mod);
+    // A provided module short-circuits load(): the loader is never called.
+    await expect(load()).resolves.toBe(mod);
+    expect(loader).not.toHaveBeenCalled();
+  });
+});

package/src/utils/chunk-loader.ts

@@ -0,0 +1,88 @@
+/**
+ * Generic memoized loader for a lazy code-split chunk.
+ *
+ * Backs the near-identical loader indirections in the core/eager bundle
+ * (`context-mentions-loader.ts`, `context-mentions-inline-loader.ts`,
+ * `markdown-parsers-loader.ts`): each registers a runtime loader (IIFE/CDN
+ * sibling-URL chunk) and falls back to an external/relative dynamic import for
+ * ESM/CJS consumers. The shared semantics are:
+ *
+ * - `load()` memoizes the resolved module (`moduleCache`) and the in-flight
+ *   promise (`loadPromise`) so concurrent callers share one import.
+ * - A rejected load clears `loadPromise` so a later call retries after a
+ *   transient failure (one dropped fetch must not disable the feature for the
+ *   whole session); the current caller still sees the rejection.
+ * - The registered loader wins over `fallbackImport`; if no loader is
+ *   registered, `fallbackImport` is used.
+ *
+ * IMPORTANT: this module must import nothing beyond types. It sits in the core
+ * bundle, so any value import here could drag chunk code back into core and
+ * defeat the split (see `context-mentions-bundle.test.ts`).
+ */
+
+export type ChunkLoaderOptions<T> = {
+  /**
+   * Dynamic import used when no runtime loader has been registered. Keep the
+   * `import(...)` literal in the calling module (not here) so the bundler
+   * resolves it as an external subpath / relative chunk at that call site.
+   */
+  fallbackImport: () => Promise<T>;
+  /**
+   * When true, registering a new loader clears the cached module and any
+   * in-flight promise, so a swapped loader (test injection) takes effect
+   * deterministically. Production registers its loader once before any load, so
+   * this only matters mid-session.
+   */
+  resetOnSetLoader?: boolean;
+};
+
+export type ChunkLoader<T> = {
+  setLoader: (l: () => Promise<T>) => void;
+  load: () => Promise<T>;
+  /** Register a resolved module synchronously (eager builds that bundle it). */
+  provide: (mod: T) => void;
+  /** The cached module, or null if not loaded/provided yet. */
+  getSync: () => T | null;
+};
+
+export const createChunkLoader = <T>(
+  options: ChunkLoaderOptions<T>
+): ChunkLoader<T> => {
+  const { fallbackImport, resetOnSetLoader = false } = options;
+
+  let loader: (() => Promise<T>) | null = null;
+  let moduleCache: T | null = null;
+  let loadPromise: Promise<T> | null = null;
+
+  const setLoader = (l: () => Promise<T>): void => {
+    loader = l;
+    if (resetOnSetLoader) {
+      moduleCache = null;
+      loadPromise = null;
+    }
+  };
+
+  const load = (): Promise<T> => {
+    if (moduleCache) return Promise.resolve(moduleCache);
+    if (loadPromise) return loadPromise;
+    const importChunk = loader ?? fallbackImport;
+    loadPromise = importChunk()
+      .then((mod) => {
+        moduleCache = mod;
+        return mod;
+      })
+      .catch((err) => {
+        loadPromise = null;
+        throw err;
+      });
+    return loadPromise;
+  };
+
+  const provide = (mod: T): void => {
+    moduleCache = mod;
+  };
+
+  const getSync = (): T | null => moduleCache;
+
+  return { setLoader, load, provide, getSync };
+};