@runtypelabs/persona 4.7.0 → 4.8.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/code-highlight.test.ts

@@ -0,0 +1,186 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from "vitest";
+import {
+  highlightCode,
+  resolveHighlightLanguage,
+  MAX_HIGHLIGHT_LENGTH,
+} from "./code-highlight";
+
+/** Reconstruct the source from a highlighted fragment (invariant helper). */
+const textOf = (frag: DocumentFragment): string => {
+  const holder = document.createElement("div");
+  holder.appendChild(frag.cloneNode(true));
+  return holder.textContent ?? "";
+};
+
+/** Collect token classes present in a highlighted fragment. */
+const tokenClasses = (frag: DocumentFragment): string[] => {
+  const holder = document.createElement("div");
+  holder.appendChild(frag.cloneNode(true));
+  return Array.from(holder.querySelectorAll("span[class^='persona-code-token-']"))
+    .map((el) => el.className);
+};
+
+const classFor = (source: string, lang: string, snippet: string): string | null => {
+  const holder = document.createElement("div");
+  holder.appendChild(highlightCode(source, lang));
+  const spans = Array.from(
+    holder.querySelectorAll("span[class^='persona-code-token-']")
+  );
+  const hit = spans.find((el) => el.textContent === snippet);
+  return hit ? hit.className : null;
+};
+
+describe("resolveHighlightLanguage", () => {
+  it("prefers explicit language and maps aliases", () => {
+    expect(resolveHighlightLanguage("html")).toBe("html");
+    expect(resolveHighlightLanguage("htm")).toBe("html");
+    expect(resolveHighlightLanguage("mjs")).toBe("js");
+    expect(resolveHighlightLanguage("tsx")).toBe("js");
+    expect(resolveHighlightLanguage("typescript")).toBe("js");
+    expect(resolveHighlightLanguage("jsonc")).toBe("json");
+  });
+
+  it("falls back to the file extension", () => {
+    expect(resolveHighlightLanguage(undefined, "src/app.css")).toBe("css");
+    expect(resolveHighlightLanguage(undefined, "a/b/main.ts")).toBe("js");
+    expect(resolveHighlightLanguage(undefined, "index.html")).toBe("html");
+  });
+
+  it("returns null for unknown languages and extensionless paths", () => {
+    expect(resolveHighlightLanguage("rust")).toBeNull();
+    expect(resolveHighlightLanguage(undefined, "Makefile")).toBeNull();
+    expect(resolveHighlightLanguage(undefined)).toBeNull();
+  });
+});
+
+describe("highlightCode token classification", () => {
+  it("classifies js keywords, strings, numbers, and comments", () => {
+    expect(classFor("const x = 1;", "js", "const")).toBe(
+      "persona-code-token-keyword"
+    );
+    expect(classFor('const s = "hi";', "js", '"hi"')).toBe(
+      "persona-code-token-string"
+    );
+    expect(classFor("const n = 42;", "js", "42")).toBe(
+      "persona-code-token-number"
+    );
+    expect(classFor("// note\nx", "js", "// note")).toBe(
+      "persona-code-token-comment"
+    );
+    expect(classFor("const b = true;", "js", "true")).toBe(
+      "persona-code-token-keyword"
+    );
+  });
+
+  it("classifies json keys as property and values as string", () => {
+    const src = '{"name": "cat", "n": 3, "ok": true}';
+    expect(classFor(src, "json", '"name"')).toBe("persona-code-token-property");
+    expect(classFor(src, "json", '"cat"')).toBe("persona-code-token-string");
+    expect(classFor(src, "json", "3")).toBe("persona-code-token-number");
+    expect(classFor(src, "json", "true")).toBe("persona-code-token-keyword");
+  });
+
+  it("classifies css properties, values, at-rules, and comments", () => {
+    const src = "@media all { .a { color: #fff; margin: 4px; } } /* c */";
+    expect(classFor(src, "css", "color")).toBe("persona-code-token-property");
+    expect(classFor(src, "css", "#fff")).toBe("persona-code-token-number");
+    expect(classFor(src, "css", "@media")).toBe("persona-code-token-keyword");
+    expect(classFor(src, "css", "/* c */")).toBe("persona-code-token-comment");
+  });
+
+  it("classifies html tags, attributes, attribute values, and comments", () => {
+    const src = '<a href="x">hi</a><!-- c -->';
+    expect(classFor(src, "html", "href")).toBe("persona-code-token-attr");
+    expect(classFor(src, "html", '"x"')).toBe("persona-code-token-string");
+    expect(classFor(src, "html", "<!-- c -->")).toBe(
+      "persona-code-token-comment"
+    );
+    // Tag bracket + name.
+    expect(classFor(src, "html", "<a")).toBe("persona-code-token-tag");
+  });
+
+  it("highlights embedded <script> bodies with the js tokenizer", () => {
+    const src = "<script>const y = 2;</script>";
+    expect(classFor(src, "html", "const")).toBe("persona-code-token-keyword");
+  });
+});
+
+describe("highlightCode line + newline invariants", () => {
+  it("splits a multi-line block comment across lines without newlines in spans", () => {
+    const src = "/* line one\nline two */\nvar x;";
+    const frag = highlightCode(src, "js");
+    const holder = document.createElement("div");
+    holder.appendChild(frag.cloneNode(true));
+    const commentSpans = holder.querySelectorAll(".persona-code-token-comment");
+    // The block comment spans two lines → two comment spans, neither with "\n".
+    expect(commentSpans.length).toBe(2);
+    commentSpans.forEach((el) => expect(el.textContent).not.toContain("\n"));
+    // No token span anywhere contains a newline.
+    holder
+      .querySelectorAll("span[class^='persona-code-token-']")
+      .forEach((el) => expect(el.textContent).not.toContain("\n"));
+  });
+
+  it("reconstructs the source verbatim (textContent === source)", () => {
+    for (const [src, lang] of [
+      ["const x = 1;\nconst y = 2;\n", "js"],
+      ["line1\nline2\nline3", "js"],
+      ["a\n\nb\n", "js"],
+      ['{"k": "v"}\n', "json"],
+      ["<div>\n  <span>hi</span>\n</div>\n", "html"],
+      ["", "js"],
+    ] as const) {
+      expect(textOf(highlightCode(src, lang))).toBe(src);
+    }
+  });
+
+  it("does not emit a phantom numbered line for a trailing newline", () => {
+    const holder = document.createElement("div");
+    holder.appendChild(highlightCode("a\nb\n", "js"));
+    // "a\nb\n" → 2 numbered lines, trailing newline preserved in textContent.
+    expect(holder.querySelectorAll(".persona-code-line").length).toBe(2);
+    expect(holder.textContent).toBe("a\nb\n");
+  });
+
+  it("keeps one line for wholly empty source", () => {
+    const holder = document.createElement("div");
+    holder.appendChild(highlightCode("", "js"));
+    expect(holder.querySelectorAll(".persona-code-line").length).toBe(1);
+    expect(holder.textContent).toBe("");
+  });
+});
+
+describe("highlightCode fallbacks and safety", () => {
+  it("returns plain line-numbered text for an unknown language", () => {
+    const frag = highlightCode("const x = 1;", "rust");
+    expect(tokenClasses(frag)).toEqual([]);
+  });
+
+  it("skips tokenization for oversized sources", () => {
+    const big = "const x = 1;\n".repeat(
+      Math.ceil((MAX_HIGHLIGHT_LENGTH + 100) / 13)
+    );
+    expect(big.length).toBeGreaterThan(MAX_HIGHLIGHT_LENGTH);
+    const frag = highlightCode(big, "js");
+    expect(tokenClasses(frag)).toEqual([]);
+    // Still line-numbered (line spans present) and verbatim.
+    const holder = document.createElement("div");
+    holder.appendChild(frag);
+    expect(holder.querySelector(".persona-code-line")).toBeTruthy();
+  });
+
+  it("never emits any element other than spans for hostile input", () => {
+    // XSS-shaped content embedded as a JS string literal.
+    const src = 'const html = "<img src=x onerror=alert(1)>";';
+    const holder = document.createElement("div");
+    holder.appendChild(highlightCode(src, "js"));
+    // Only <span> elements exist; no <img> (or anything else) was created.
+    const all = Array.from(holder.querySelectorAll("*"));
+    expect(all.every((el) => el.tagName === "SPAN")).toBe(true);
+    expect(holder.querySelector("img")).toBeNull();
+    // The dangerous text survives as inert text content.
+    expect(holder.textContent).toContain("<img src=x onerror=alert(1)>");
+  });
+});