@runtypelabs/persona 3.34.1 → 3.35.0

package/src/styles/widget.css

@@ -1027,7 +1027,7 @@
   opacity: 1;
 }
 
-/* Hide tooltips on touch devices — hover doesn't exist, and they cause clipping issues */
+/* Hide tooltips on touch devices: hover doesn't exist, and they cause clipping issues */
 @media (hover: none), (max-width: 500px) {
   .persona-send-button-wrapper:hover .persona-send-button-tooltip,
   .persona-send-button-wrapper:focus-within .persona-send-button-tooltip {
@@ -1144,7 +1144,7 @@
   animation: persona-voice-processing-spin 1.2s linear infinite;
 }
 
-/* Voice speaking animation (gentle pulse — slower/subtler than recording) */
+/* Voice speaking animation (gentle pulse: slower/subtler than recording) */
 @keyframes persona-voice-speaking-pulse {
   0%, 100% { opacity: 1; transform: scale(1); }
   50% { opacity: 0.85; transform: scale(1.03); }
@@ -1759,7 +1759,7 @@
   animation: persona-message-actions-fade-in 0.3s ease-out forwards;
 }
 
-/* ask_user_question — collapsed answered state.
+/* ask_user_question: collapsed answered state.
  * When the user picks an option, the interactive card is replaced with a
  * plain assistant bubble showing the question text. A short fade + slight
  * upward slide sells the "card resolved into history" feel.
@@ -1948,6 +1948,18 @@
   opacity: 0.9;
 }
 
+/* Read-aloud loading state: spin the loader icon while audio is prepared
+   (near-instant for browser TTS; visible for a hosted/server engine fetch). */
+.persona-message-action-btn.persona-message-action-loading svg {
+  animation: persona-voice-processing-spin 1s linear infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .persona-message-action-btn.persona-message-action-loading svg {
+    animation: none;
+  }
+}
+
 /* Vote pop animation */
 @keyframes persona-vote-pop {
   0% { transform: scale(1); }
@@ -2228,7 +2240,7 @@
   background-color: var(--cw-container, #f8fafc);
 }
 
-/* Collapsed live preview blocks — match expanded content's 1px border-top with transparent border */
+/* Collapsed live preview blocks: match expanded content's 1px border-top with transparent border */
 [data-persona-root] [data-persona-collapsed-preview] {
   border-top: 1px solid transparent;
 }
@@ -2380,7 +2392,7 @@
 }
 
 /* ============================================
-   Visibility (Tailwind parity — prefix persona-)
+   Visibility (Tailwind parity: prefix persona-)
    Shipped widget.css is hand-maintained; these utilities are used in TS but not generated by Tailwind at build time.
    ============================================ */
 [data-persona-root] .persona-hidden {
@@ -2402,7 +2414,7 @@
   gap: var(--persona-artifact-split-gap, 0.5rem);
 }
 
-/* Document toolbar preset — optional layout vars: --persona-artifact-doc-toolbar-icon-color, etc. */
+/* Document toolbar preset: optional layout vars: --persona-artifact-doc-toolbar-icon-color, etc. */
 [data-persona-root] .persona-artifact-toolbar-document .persona-artifact-doc-icon-btn {
   display: inline-flex;
   align-items: center;
@@ -2495,7 +2507,7 @@
 
 /* ── Composable button utilities ── */
 
-/* Icon button — base for all icon-only buttons created by createIconButton() */
+/* Icon button: base for all icon-only buttons created by createIconButton() */
 [data-persona-root] .persona-icon-btn {
   display: inline-flex;
   align-items: center;
@@ -2525,7 +2537,7 @@
   border-color: var(--persona-icon-btn-active-border, var(--persona-border, #e5e7eb));
 }
 
-/* Label button — icon + text button created by createLabelButton() */
+/* Label button: icon + text button created by createLabelButton() */
 [data-persona-root] .persona-label-btn {
   display: inline-flex;
   align-items: center;
@@ -2644,7 +2656,7 @@
   outline-offset: 2px;
 }
 
-/* Toggle group — mutually exclusive button set created by createToggleGroup() */
+/* Toggle group: mutually exclusive button set created by createToggleGroup() */
 [data-persona-root] .persona-toggle-group {
   display: inline-flex;
   gap: var(--persona-toggle-group-gap, 0);
@@ -2664,7 +2676,7 @@
   border-bottom-right-radius: var(--persona-toggle-group-radius, var(--persona-icon-btn-radius, var(--persona-radius-md, 0.375rem)));
 }
 
-/* Combo button — label + chevron with dropdown */
+/* Combo button: label + chevron with dropdown */
 [data-persona-root] .persona-combo-btn {
   font-size: var(--persona-combo-btn-font-size, 0.8125rem);
   font-weight: var(--persona-combo-btn-font-weight, 600);
@@ -2758,7 +2770,7 @@
   }
 }
 
-/* paneBorderRadius — works on any paneAppearance; overflow clips content to rounded shape */
+/* paneBorderRadius: works on any paneAppearance; overflow clips content to rounded shape */
 [data-persona-root] .persona-artifact-pane {
   border-radius: var(--persona-artifact-pane-radius, 0);
   overflow: hidden;
@@ -2769,7 +2781,7 @@
   );
 }
 
-/* paneAppearance: 'seamless' — flush with chat, no border/shadow/gap */
+/* paneAppearance: 'seamless': flush with chat, no border/shadow/gap */
 /* `position: relative` for resizer overlay; gap 0; positioning is applied in ui.ts */
 [data-persona-root].persona-artifact-appearance-seamless .persona-artifact-split-root {
   position: relative;
@@ -2787,7 +2799,7 @@
   );
 }
 
-/* layout.paneBorder / paneBorderLeft — theme overrides (after appearance defaults) */
+/* layout.paneBorder / paneBorderLeft: theme overrides (after appearance defaults) */
 [data-persona-root].persona-artifact-border-full .persona-artifact-pane {
   border: var(--persona-artifact-pane-border) !important;
 }
@@ -2869,7 +2881,7 @@
 }
 
 /* ============================================================
-   Stream animations — reveal effects for assistant message text
+   Stream animations: reveal effects for assistant message text
    while streaming. Opt-in via `features.streamAnimation.type`.
    Units are staggered via `--char-index` / `--word-index`
    (set inline on each wrapper span). Timing is configured via
@@ -2879,7 +2891,7 @@
 
 /* Per-char/per-word spans need to be inline-block so `transform` works for
    the rise/fade animations. Each span animates from the moment it is first
-   added to the DOM — streaming itself provides the visible stagger, so the
+   added to the DOM: streaming itself provides the visible stagger, so the
    CSS animation has no per-index delay. An index-based delay would compound
    with the stream's arrival cadence and leave later chars permanently hidden. */
 [data-persona-root] .persona-stream-char,
@@ -2925,7 +2937,7 @@
     ease-out both;
 }
 
-/* The following animations live in subpath plugin modules — their CSS is
+/* The following animations live in subpath plugin modules: their CSS is
    injected by the plugin when activated, not by the core stylesheet:
    - `wipe`        → @runtypelabs/persona/animations/wipe
    - `glyph-cycle` → @runtypelabs/persona/animations/glyph-cycle */
@@ -2955,6 +2967,13 @@
   animation: persona-stream-blink 1s steps(1) infinite;
 }
 
+/* ---------- inline timestamp (trails the last line of message text) ---------- */
+[data-persona-root] .persona-timestamp-inline {
+  display: inline-block;
+  margin-left: 0.5rem;
+  white-space: nowrap;
+}
+
 /* ---------- skeleton placeholder (pre-first-token) ---------- */
 @keyframes persona-stream-skeleton-shimmer {
   0%   { background-position: 200% 0; }
@@ -3002,7 +3021,7 @@
 }
 
 /* ========================================================================
- * ask_user_question — built-in answer-pill sheet
+ * ask_user_question: built-in answer-pill sheet
  * Slides in over the composer when the assistant invokes `ask_user_question`.
  * Overridable via `config.features.askUserQuestion.styles`.
  * ======================================================================== */
@@ -3011,7 +3030,7 @@
   display: none !important;
 }
 
-/* In-transcript stub — small "Awaiting…" chip. */
+/* In-transcript stub: small "Awaiting…" chip. */
 [data-persona-root] .persona-ask-stub {
   padding: 0.35rem 0.7rem;
   border-radius: 999px;
@@ -3025,7 +3044,7 @@
   font-weight: 500;
 }
 
-/* Sheet container — absolute inside composerOverlay. */
+/* Sheet container: absolute inside composerOverlay. */
 [data-persona-root] .persona-ask-sheet {
   position: absolute;
   left: 0.75rem;
@@ -3053,7 +3072,7 @@
   pointer-events: none;
 }
 
-/* Header row — question + close button */
+/* Header row: question + close button */
 [data-persona-root] .persona-ask-sheet-header {
   margin-bottom: 0.55rem;
 }
@@ -3094,7 +3113,7 @@
   display: none;
 }
 
-/* Option list — stacked one per row by default ("rows" layout). The "pills"
+/* Option list: stacked one per row by default ("rows" layout). The "pills"
    layout opt-in switches to horizontal wrap with compact pills; see also
    horizontalPillsAskPlugin example for a custom variant. */
 [data-persona-root] .persona-ask-pills {
@@ -3111,7 +3130,7 @@
   gap: 0.4rem;
 }
 
-/* Pills layout opt-in — horizontal wrap, auto-width compact pills. */
+/* Pills layout opt-in: horizontal wrap, auto-width compact pills. */
 [data-persona-root] .persona-ask-sheet--pills .persona-ask-pills:not(.persona-ask-pills--rows) {
   flex-direction: row;
   flex-wrap: wrap;
@@ -3188,7 +3207,7 @@
   100% { background-position: -100% 50%; }
 }
 
-/* Row layout — full-width stacked rows with always-visible description
+/* Row layout: full-width stacked rows with always-visible description
    and a right-edge affordance (number badge for single-select, check for
    multi-select). Layered on top of .persona-ask-pill base styles. */
 [data-persona-root] .persona-ask-row {
@@ -3291,7 +3310,7 @@
   height: 3rem;
 }
 
-/* Other row (rows mode) — composite row that contains the free-text input
+/* Other row (rows mode): composite row that contains the free-text input
  * directly. The input fills the row body; the badge sits on the right. */
 [data-persona-root] .persona-ask-row--other {
   cursor: text;
@@ -3358,7 +3377,7 @@
   cursor: not-allowed;
 }
 
-/* Nav row — Back / Skip / Next-or-Submit buttons for grouped payloads. */
+/* Nav row: Back / Skip / Next-or-Submit buttons for grouped payloads. */
 [data-persona-root] .persona-ask-nav-back,
 [data-persona-root] .persona-ask-nav-skip {
   padding: 0.45rem 0.85rem;
@@ -3416,11 +3435,11 @@
  * `applyComposerBarGeometry()` in ui.ts. The pill composer
  * (`pill-composer-builder.ts`) ships with its own clean className
  * (`persona-pill-composer`, no `persona-flex-col` / `persona-rounded-2xl`
- * baggage), so layout CSS does not need to fight utility classes — no
+ * baggage), so layout CSS does not need to fight utility classes: no
  * !important. The pill is the visible element in both collapsed and
  * expanded states; only the panel above it appears/disappears.
  *
- * Avoid `transform: scale(...)` on the wrapper — it breaks the textarea
+ * Avoid `transform: scale(...)` on the wrapper: it breaks the textarea
  * caret/IME.
  * ======================================================================= */
 .persona-widget-wrapper[data-persona-composer-bar] {
@@ -3446,14 +3465,14 @@
  * so `top/left/transform` resolve to their auto/none defaults) to its
  * expanded position. The default `transform 220ms ease` transition would
  * interpolate `none → translate(...)` and visibly slide the wrapper from
- * its static-default origin toward its target — diagonally for modal,
+ * its static-default origin toward its target: diagonally for modal,
  * horizontally from the right for anchored. Neither mode is morphing
  * something the user can see (the wrapper is invisible when collapsed
  * because the pill lives in pillRoot, not the wrapper), so the slide
  * is pure motion noise. Disable geometry transitions for both; the
  * container's opacity fade-in keyframe is the reveal.
  *
- * Fullscreen intentionally keeps its geometry transition — that's the
+ * Fullscreen intentionally keeps its geometry transition: that's the
  * one mode where the wrapper genuinely morphs (empty → full viewport),
  * and the staggered fade-in cascade below is built to mask the
  * outer-edge/inner-content desync during that morph. */
@@ -3489,7 +3508,7 @@
   padding: 4px 0;
 }
 
-/* Responsive default width for the collapsed pill — applied only when
+/* Responsive default width for the collapsed pill: applied only when
  * `applyComposerBarGeometry()` leaves the wrapper's inline width empty
  * (i.e., the user did NOT set `composerBar.collapsedMaxWidth`). Inline
  * width from a user config still wins via specificity (inline > class). */
@@ -3543,8 +3562,7 @@
  * In composer-bar mode the pill (`footer`) and peek banner live in a
  * viewport-fixed sibling of the wrapper, NOT inside the wrapper. Reason:
  * modal mode applies `transform: translate(-50%, -50%)` to the wrapper,
- * which establishes a containing block for `position: fixed` descendants —
- * a fixed pill inside a transformed wrapper would be positioned relative
+ * which establishes a containing block for `position: fixed` descendants: * a fixed pill inside a transformed wrapper would be positioned relative
  * to the wrapper, not the viewport.
  *
  * Bottom offset and (optionally) width are written inline by ui.ts based
@@ -3574,7 +3592,7 @@
   }
 }
 
-/* Container hidden when the chat is collapsed — only the pill is visible. */
+/* Container hidden when the chat is collapsed: only the pill is visible. */
 [data-persona-composer-bar][data-state="collapsed"] .persona-widget-container {
   display: none;
 }
@@ -3614,7 +3632,7 @@
     transform 150ms ease,
     background-color 150ms ease;
   text-align: left;
-  /* Full-width row that matches the pill below — text takes the middle
+  /* Full-width row that matches the pill below: text takes the middle
    * (flex: 1 1 auto) and the chevron pins to the right edge. */
   width: 100%;
   align-self: stretch;
@@ -3700,7 +3718,7 @@
  * (including the area behind the fixed pill) so messages scroll under the
  * pill. The body itself drops its bottom padding so its background extends
  * to the viewport edge; reachability for the last bubble comes from
- * padding-bottom on the messages wrapper (body's last child) — that
+ * padding-bottom on the messages wrapper (body's last child): that
  * pushes the final message above the pill area rather than hiding it
  * behind. */
 .persona-widget-wrapper[data-persona-composer-bar][data-expanded-size="fullscreen"] .persona-widget-body {
@@ -3726,7 +3744,7 @@
  *   so the box appears to materialize as it grows rather than snap into
  *   existence at frame 0.
  * - Body content (intro card, messages, composer overlay) fades in AFTER
- *   the geometry has settled — `animation-delay: 220ms` plus
+ *   the geometry has settled: `animation-delay: 220ms` plus
  *   `animation-fill-mode: both` keeps it at opacity 0 during the morph.
  *
  * Because `[data-state="collapsed"] .persona-widget-container { display:

package/src/suggest-replies-tool.test.ts

@@ -331,11 +331,11 @@ describe("AgentWidgetSession - suggest_replies fire-and-forget auto-resolve", ()
     for (let i = 0; i < 6; i++) await Promise.resolve();
   };
 
-  it("auto-POSTs ONE /resume with the canned output after stream idle — no bridge, no WebMCP config", async () => {
+  it("auto-POSTs ONE /resume with the canned output after stream idle: no bridge, no WebMCP config", async () => {
     const { session, executeSpy, resumeSpy } = makeSession();
 
     feed(session, suggestAwait("toolu_S"));
-    // Not resolved at step_await receipt — only after the stream ends.
+    // Not resolved at step_await receipt: only after the stream ends.
     expect(resumeSpy).not.toHaveBeenCalled();
 
     endStream(session);
@@ -423,7 +423,7 @@ describe("AgentWidgetSession - suggest_replies fire-and-forget auto-resolve", ()
     expect(resumeSpy).toHaveBeenCalledTimes(1);
 
     // Hydration (e.g. storage restore) wipes webMcpInflightKeys /
-    // webMcpResolvedKeys — only the suggestRepliesResolved metadata persisted
+    // webMcpResolvedKeys: only the suggestRepliesResolved metadata persisted
     // on the message survives to block a replayed step_await.
     const resolved = (
       session as unknown as { messages: AgentWidgetMessage[] }

package/src/suggest-replies-tool.ts

@@ -2,11 +2,11 @@
  * Built-in `suggest_replies` client tool.
  *
  * The widget can advertise this tool to the agent on every dispatch via
- * `clientTools[]` (set `features.suggestReplies.expose: true`) — the same
+ * `clientTools[]` (set `features.suggestReplies.expose: true`): the same
  * wire surface as `ask_user_question` and WebMCP page tools. When the model
  * calls it, the execution pauses with a `step_await`
  * (`awaitReason: "local_tool_required"`); unlike `ask_user_question`, the
- * widget resolves it FIRE-AND-FORGET — it renders the suggestions as tappable
+ * widget resolves it FIRE-AND-FORGET: it renders the suggestions as tappable
  * chips above the composer and immediately resumes the execution with a
  * canned "shown" result, so the agent's turn completes without waiting on the
  * user. Tapping a chip sends its text verbatim as the user's next message.
@@ -26,7 +26,7 @@ import type {
 
 export const SUGGEST_REPLIES_TOOL_NAME = "suggest_replies";
 
-/** Renderer cap — payloads beyond this are truncated with a console warning. */
+/** Renderer cap: payloads beyond this are truncated with a console warning. */
 export const SUGGEST_REPLIES_MAX = 4;
 
 /**
@@ -64,7 +64,7 @@ export const SUGGEST_REPLIES_CLIENT_TOOL: ClientToolDefinition = {
     "complete. Each suggestion is sent verbatim as the user's next message, " +
     'so phrase suggestions in the user\'s voice (e.g. "Tell me more about ' +
     'pricing"). Keep them short and distinct. The result only confirms the ' +
-    "suggestions were shown — do not add further commentary after calling " +
+    "suggestions were shown: do not add further commentary after calling " +
     "this tool; end your turn.",
   parametersSchema: SUGGEST_REPLIES_PARAMETERS_SCHEMA,
   origin: "sdk",
@@ -141,7 +141,7 @@ export const latestAgentSuggestions = (
 /**
  * Gate for advertising the tool: `expose` opts it into the agent's catalog,
  * and `enabled !== false` guarantees the widget will actually auto-resolve
- * and render chips for it — exposing the tool with the feature disabled
+ * and render chips for it: exposing the tool with the feature disabled
  * would park the execution on a generic tool bubble with no resume coming.
  */
 export const shouldExposeSuggestReplies = (

package/src/testing/index.ts

@@ -1,4 +1,4 @@
-/** @runtypelabs/persona/testing — Helpers for mocking SSE streams in demos, previews, and tests. */
+/** @runtypelabs/persona/testing: Helpers for mocking SSE streams in demos, previews, and tests. */
 
 export {
   createMockSSEStream,

package/src/theme-editor/color-utils.ts

@@ -1,4 +1,4 @@
-/** Color parsing, normalization, and scale generation utilities (pure functions — no DOM) */
+/** Color parsing, normalization, and scale generation utilities (pure functions: no DOM) */
 
 import type { ColorShade } from '../types/theme';
 
@@ -68,7 +68,7 @@ export function isValidHex(value: string): boolean {
  * Parse an `rgb()` / `rgba()` string into `#rrggbb`. Accepts integer (0-255) or
  * percentage channels; any alpha component is dropped. Returns `null` when the
  * string is not a parseable rgb/rgba value, so callers can fall back. This lets
- * the HSL/luminance paths — which otherwise `parseInt` hex digits — accept the
+ * the HSL/luminance paths, which otherwise `parseInt` hex digits, accept the
  * `rgb()` inputs that `coerceColor` admits without producing `#NaNNaNNaN`.
  */
 export function rgbToHex(value: string): string | null {

package/src/theme-editor/index.ts

@@ -1,4 +1,4 @@
-/** @runtypelabs/persona/theme-editor — Headless theme editor core */
+/** @runtypelabs/persona/theme-editor: Headless theme editor core */
 
 // Types
 export type {
@@ -55,18 +55,9 @@ export {
   getThemeEditorPreset,
 } from './presets';
 
-// Preview renderer
-export { createThemePreview } from './preview';
-export type {
-  ThemePreviewOptions,
-  ThemePreviewHandle,
-  PreviewLifecycleContext,
-  PreviewDevice,
-  PreviewShellMode,
-  CompareMode,
-} from './preview';
-
-// Preview building blocks (for advanced/custom preview renderers)
+// Preview building blocks (for advanced/custom preview renderers).
+// For the full iframe preview helper (`createThemePreview`), use
+// `@runtypelabs/persona/theme-editor/preview`.
 export {
   DEVICE_DIMENSIONS,
   ZOOM_MIN,

package/src/theme-editor/presets.ts

@@ -1,4 +1,4 @@
-/** Theme editor presets — unified collection of built-in presets */
+/** Theme editor presets: unified collection of built-in presets */
 
 import type { ThemeEditorPreset } from './types';
 

package/src/theme-editor/preview-utils.ts

@@ -212,9 +212,9 @@ export type PreviewTranscriptEntryPreset =
 const PREVIEW_TRANSCRIPT_PRESET_LABELS: Record<PreviewTranscriptEntryPreset, string> = {
   'user-message': 'User message',
   'assistant-message': 'Assistant message',
-  'assistant-code-block': 'Assistant — code block',
-  'assistant-markdown-table': 'Assistant — markdown table',
-  'assistant-image': 'Assistant — image',
+  'assistant-code-block': 'Assistant: code block',
+  'assistant-markdown-table': 'Assistant: markdown table',
+  'assistant-image': 'Assistant: image',
   'reasoning-streaming': 'Reasoning (streaming)',
   'reasoning-complete': 'Reasoning (complete)',
   'tool-running': 'Tool call (running)',
@@ -290,7 +290,7 @@ export function createPreviewTranscriptEntry(
         id: `preview-seq-assistant-image-${suffix}`,
         role: 'assistant',
         content: [
-          "Here's the reference diagram you asked for — let me know if you'd like a different view:",
+          "Here's the reference diagram you asked for: let me know if you'd like a different view:",
           '',
           '![Stream animation reference](https://placehold.co/320x200/png?text=Stream+Animation)',
           '',
@@ -600,22 +600,30 @@ export interface PreviewConfigOptions {
   appendedMessages?: AgentWidgetMessage[];
 }
 
-export function buildPreviewConfig(
+function buildPreviewBaseConfig(
   options: PreviewConfigOptions,
   shellModeOverride?: 'light' | 'dark'
 ): AgentWidgetConfig {
   const theme = options.theme ? createTheme(options.theme, { validate: false }) : createTheme();
-  const scene = options.scene ?? 'conversation';
-
-  const base = {
+  return {
     ...DEFAULT_WIDGET_CONFIG,
     ...options.config,
     theme,
     darkTheme: options.darkTheme,
     colorScheme: shellModeOverride ?? (options.config?.colorScheme as string) ?? 'light',
   } as AgentWidgetConfig;
+}
 
-  return applySceneConfig(base, scene, options.appendedMessages ?? []);
+export function buildPreviewConfig(
+  options: PreviewConfigOptions,
+  shellModeOverride?: 'light' | 'dark'
+): AgentWidgetConfig {
+  const scene = options.scene ?? 'conversation';
+  return applySceneConfig(
+    buildPreviewBaseConfig(options, shellModeOverride),
+    scene,
+    options.appendedMessages ?? []
+  );
 }
 
 export function buildPreviewConfigWithMessages(
@@ -623,16 +631,10 @@ export function buildPreviewConfigWithMessages(
   messages: AgentWidgetMessage[],
   shellModeOverride?: 'light' | 'dark'
 ): AgentWidgetConfig {
-  const theme = options.theme ? createTheme(options.theme, { validate: false }) : createTheme();
   const scene = options.scene ?? 'conversation';
-
-  const base = {
-    ...DEFAULT_WIDGET_CONFIG,
-    ...options.config,
-    theme,
-    darkTheme: options.darkTheme,
-    colorScheme: shellModeOverride ?? (options.config?.colorScheme as string) ?? 'light',
-  } as AgentWidgetConfig;
-
-  return applySceneConfig(base, scene, messages);
+  return applySceneConfig(
+    buildPreviewBaseConfig(options, shellModeOverride),
+    scene,
+    messages
+  );
 }

package/src/theme-editor/preview.ts

@@ -1,7 +1,10 @@
 /**
  * Imperative preview renderer for the theme editor.
+ * Import from `@runtypelabs/persona/theme-editor/preview` (not the headless
+ * `@runtypelabs/persona/theme-editor` subpath, which omits the widget runtime).
+ *
  * Manages iframe-based widget previews with device frames, zoom, scenes, and compare mode.
- * No external DOM dependencies — only needs a container element to mount into.
+ * No external DOM dependencies: only needs a container element to mount into.
  *
  * For advanced preview needs (background URLs, inline editing, contrast checking),
  * use the lifecycle hooks in `ThemePreviewOptions` and import shared building blocks

package/src/theme-editor/role-mappings.ts

@@ -3,7 +3,7 @@
  *
  * Maps high-level editor choices (family + intensity) to concrete palette
  * token references across multiple component/semantic paths. This is the
- * core of the "Interface Roles" editor section — one picker writes to
+ * core of the "Interface Roles" editor section: one picker writes to
  * many tokens atomically.
  *
  * All functions are pure and headless (no DOM).
@@ -202,7 +202,7 @@ function resolveTarget(
     return resolveHeaderTarget(family, solid, target);
   }
 
-  // Input has special handling — foreground target is the placeholder
+  // Input has special handling: foreground target is the placeholder
   if (roleId === 'role-input') {
     return resolveInputTarget(family, solid, target);
   }
@@ -329,7 +329,7 @@ export function detectRoleAssignment(
     : null;
   if (!family) return null;
 
-  // Try both intensities — shade-based guessing doesn't work for all target kinds
+  // Try both intensities: shade-based guessing doesn't work for all target kinds
   for (const intensity of ['solid', 'soft'] as const) {
     const expected = resolveRoleAssignment(family, intensity, role);
     const allMatch = role.targets.every((t) => {