@genesislcap/ai-assistant 14.479.0 → 14.480.0

package/src/components/chat-driver/chat-driver.ts

@@ -208,6 +208,16 @@ export class ChatDriver extends EventTarget implements AiDriver {
     }
   >();
 
+  // GENC-1410 (Error 3): when several assistant views share this one driver (e.g. a bubble and a
+  // docked panel), each interaction's widget must be rendered live — and thus fire any side
+  // effect — on exactly ONE view. These fields elect that owner and de-dupe execution.
+  /** Assistant host ids currently wired to this driver, in registration (insertion) order. */
+  private hosts = new Set<string>();
+  /** The host whose subtree the user most recently interacted in — the primary owner signal. */
+  private lastActiveHostId?: string;
+  /** Interaction id → host id that claimed its side effect (first-writer-wins latch). */
+  private startedSideEffects = new Map<string, string>();
+
   private systemPrompt?: SystemPromptInput;
   /**
    * Resolved tool definitions visible to the LLM. Folds mutate this in place
@@ -1078,6 +1088,59 @@ export class ChatDriver extends EventTarget implements AiDriver {
     return this.busy;
   }
 
+  // --- GENC-1410 (Error 3): single-instance execution of side-effecting widgets --------------
+
+  /** Register an assistant view (host) wired to this shared driver. @internal */
+  registerHost(hostId: string): void {
+    this.hosts.add(hostId);
+  }
+
+  /** Deregister a host on unwire/disconnect. @internal */
+  unregisterHost(hostId: string): void {
+    this.hosts.delete(hostId);
+  }
+
+  /**
+   * Record the host whose subtree the user most recently interacted in — the primary signal for
+   * electing which single view renders an interaction's widget. Sticky (unlike focus): it only
+   * moves when the user actually uses a different assistant view, not when they click elsewhere
+   * in the layout. @internal
+   */
+  setActiveHost(hostId: string): void {
+    this.lastActiveHostId = hostId;
+  }
+
+  /**
+   * First-writer-wins latch guarding a side effect. A host claims before rendering the live
+   * widget: the first host to claim an interaction id gets `true` (run it); a *different* host
+   * gets `false` (render passive, do NOT re-fire). Re-claim by the SAME host returns `true`, so a
+   * benign re-render of the owner keeps its widget. Single-threaded, so check-and-set is race-free
+   * — the backstop that makes duplicate execution impossible even if owner election ever slips. @internal
+   */
+  claimSideEffect(interactionId: string, hostId: string): boolean {
+    const existing = this.startedSideEffects.get(interactionId);
+    if (existing === undefined) {
+      this.startedSideEffects.set(interactionId, hostId);
+      return true;
+    }
+    return existing === hostId;
+  }
+
+  /**
+   * Elect the single host that owns (renders + runs) an interaction's widget: the most-recently-
+   * active host if still connected, else a deterministic default (first registered host — `Set`
+   * preserves insertion order) so exactly one owner is always chosen. Returns `undefined` only when
+   * no host is registered, in which case the interaction renders everywhere (fail-open) not nowhere.
+   */
+  private electInteractionOwner(): string | undefined {
+    if (this.lastActiveHostId && this.hosts.has(this.lastActiveHostId)) {
+      return this.lastActiveHostId;
+    }
+    // First registered host (`Set` preserves insertion order); `undefined` when none.
+    const [firstHost] = this.hosts;
+    return firstHost;
+  }
+
   /**
    * Wire a parent driver as the host for this driver's interactions. When set,
    * `requestInteraction` delegates upward so the widget renders in (and
@@ -1128,6 +1191,10 @@ export class ChatDriver extends EventTarget implements AiDriver {
     const chatInputDuringExecution = options?.chatInputDuringExecution;
     const timeoutMs = options?.timeoutMs;
     const presentation = options?.presentation;
+    // GENC-1410 (Error 3): a widget is rendered live by exactly one host. Elect the owner now
+    // (most-recently-active host, deterministic fallback) and stamp it on the interaction so every
+    // host can compare its own id and render passively when it differs — one server call, not N.
+    const ownerHostId = this.electInteractionOwner();
     return new Promise((resolve, reject) => {
       this.pendingInteractions.set(interactionId, {
         resolve,
@@ -1172,6 +1239,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
           componentName,
           data,
           ...(presentation ? { presentation } : {}),
+          ...(ownerHostId ? { ownerHostId } : {}),
         },
       });
     });
@@ -1231,6 +1299,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
       agenticActivityBus.publish('interaction-resolved', undefined);
       interaction.resolve(result);
       this.pendingInteractions.delete(interactionId);
+      // GENC-1410: release the side-effect claim so a re-request with a fresh id starts clean.
+      this.startedSideEffects.delete(interactionId);
     } else {
       logger.warn(`Interaction with ID ${interactionId} not found.`);
     }
@@ -2235,11 +2305,42 @@ export class ChatDriver extends EventTarget implements AiDriver {
           });
         }
         return { reason: 'done' };
-      } else if (isThinkingStep) {
-        this.appendToHistory({ ...response, toolCalls: undefined, thinking: true });
-        this.appendToHistory({ ...response, content: '' });
       } else {
-        this.appendToHistory(response);
+        // Split one model response into separate, individually-toggleable messages so each has its
+        // own visibility toggle and debug-log category:
+        //   - reasoning (chain-of-thought summary) → category 'reasoning', hidden unless showThinkingSteps
+        //   - narration (interstitial prose emitted alongside a tool call) → category 'narration',
+        //     hidden unless showNarration
+        //   - the answer / tool-call message → always shown; carries this turn's usage.
+        // Cost invariant (GENC-1410): exactly ONE message carries cost/tokens and is appended LAST, so
+        // `sumCosts`/`sumTokens` don't double-count and `contextTokens` reads it. Reasoning/narration are
+        // display-only (usage undefined) and are skipped when building the provider request. `model` /
+        // `provider` / `providerName` stay on every split message so each is still attributed.
+        const { reasoning, ...rest } = response;
+        const displayOnly = { cost: undefined, inputTokens: undefined, outputTokens: undefined };
+        if (reasoning) {
+          this.appendToHistory({
+            ...rest,
+            ...displayOnly,
+            content: reasoning,
+            toolCalls: undefined,
+            category: 'reasoning',
+          });
+        }
+        if (isThinkingStep) {
+          // content + tool call → the content is interstitial narration, not the final answer.
+          this.appendToHistory({
+            ...rest,
+            ...displayOnly,
+            toolCalls: undefined,
+            category: 'narration',
+          });
+          this.appendToHistory({ ...rest, content: '' });
+        } else {
+          // No tool call → `content` is the final answer (always shown), or this is a bare tool-call
+          // turn with no narration. Either way it carries this turn's usage; append it last.
+          this.appendToHistory(rest);
+        }
       }
 
       // Reset retry budgets on any productive (non-empty) response, so the caps mean

package/src/components/chat-interaction-wrapper/chat-interaction-wrapper.test.ts

@@ -102,4 +102,85 @@ Suite('forwards resolved in place without rebuilding the widget', async ({ eleme
   assert.equal(widget.resolved, { status: 'approved' }, 'resolved is forwarded to the widget');
 });
 
+/**
+ * GENC-1410 (Error 3): two assistant views (a floating bubble and a docked panel)
+ * share one driver and render the same history, so both mount a wrapper for the
+ * same interaction. Exactly one — the elected owner — must render the live widget
+ * and win the driver's first-writer side-effect latch; the other renders a passive
+ * placeholder. Regression: the claim used to be computed for EVERY host, so if a
+ * non-owner view rendered its wrapper first it grabbed the latch, and the owner's
+ * own claim then returned false — leaving BOTH views on the placeholder so the
+ * widget's side effect never fired (blank + stuck). The claim must be gated behind
+ * ownership, making the outcome independent of inter-host render order.
+ */
+
+/** First-writer-wins latch, mirroring `ChatDriver.claimSideEffect`. */
+function makeSharedLatch() {
+  const started = new Map<string, string>();
+  return (interactionId: string, hostId: string) => {
+    const existing = started.get(interactionId);
+    if (existing === undefined) {
+      started.set(interactionId, hostId);
+      return true;
+    }
+    return existing === hostId;
+  };
+}
+
+/**
+ * Mount a wrapper inside a shadow host that exposes `hostId` + a shared claim,
+ * mimicking one `gc-assistant` view. The wrapper reads these across its shadow
+ * boundary via `getRootNode().host`, so a real ShadowRoot host is required.
+ */
+async function mountWrapperInHost(
+  hostId: string,
+  ownerHostId: string,
+  interactionId: string,
+  claim: (interactionId: string, hostId: string) => boolean,
+) {
+  const hostEl = document.createElement('div');
+  const shadow = hostEl.attachShadow({ mode: 'open' });
+  (hostEl as any).hostId = hostId;
+  (hostEl as any).isEngaged = true;
+  (hostEl as any).claimSideEffect = (id: string) => claim(id, hostId);
+
+  const wrapper = document.createElement('ai-chat-interaction-wrapper') as AiChatInteractionWrapper;
+  shadow.appendChild(wrapper);
+  document.body.appendChild(hostEl);
+  await DOM.nextUpdate();
+
+  wrapper.ownerHostId = ownerHostId;
+  wrapper.data = { label: 'q' };
+  wrapper.interactionId = interactionId;
+  wrapper.componentName = FAKE_WIDGET;
+  await DOM.nextUpdate();
+  return { hostEl, wrapper };
+}
+
+Suite('a non-owner host does not poison the side-effect claim when it renders first', async () => {
+  const claim = makeSharedLatch();
+  const ownerId = 'owner-host';
+  const otherId = 'other-host';
+  const interactionId = 'id-x';
+
+  // The NON-owner (e.g. the hidden bubble) renders FIRST — the race that used to poison the latch.
+  const other = await mountWrapperInHost(otherId, ownerId, interactionId, claim);
+  // The elected owner renders SECOND.
+  const owner = await mountWrapperInHost(ownerId, ownerId, interactionId, claim);
+
+  assert.equal(
+    (other.wrapper.container.firstElementChild as HTMLElement)?.className,
+    'interaction-running-elsewhere',
+    'the non-owner view renders the passive placeholder',
+  );
+  assert.equal(
+    (owner.wrapper.container.firstElementChild as HTMLElement)?.tagName?.toLowerCase(),
+    FAKE_WIDGET,
+    'the owner renders the live widget even though the non-owner rendered first',
+  );
+
+  other.hostEl.remove();
+  owner.hostEl.remove();
+});
+
 Suite.run();

package/src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts

@@ -28,6 +28,13 @@ export class AiChatInteractionWrapper extends GenesisElement {
   @observable interactionId: string = '';
   /** The resolved result once the interaction has completed. Forwarded to the rendered component. @internal */
   @observable resolved: InteractionResult<unknown> | undefined = undefined;
+  /**
+   * GENC-1410 (Error 3): id of the host the driver elected to render (and thus run) this
+   * interaction. When several views share one driver, only the matching host renders the live
+   * widget; others show a passive placeholder so the widget fires once. Empty = no owner elected
+   * (single view, or none registered) → render everywhere (fail-open). @internal
+   */
+  @observable ownerHostId = '';
 
   /** @internal */
   container!: HTMLElement;
@@ -66,8 +73,15 @@ export class AiChatInteractionWrapper extends GenesisElement {
 
   resolvedChanged() {
     const element = this.container?.firstElementChild as any;
-    if (element) {
+    // GENC-1410 (Error 3): a non-owner view rendered a passive placeholder for the unresolved
+    // exclusive widget. Now it's resolved (no side effect left to fire), so render the real widget
+    // — the gate below is keyed on `!resolved`, so this instantiates the resolved widget and every
+    // view shows the outcome. The owner already has the live widget: just forward `resolved` to it,
+    // preserving its DOM/state (no re-create).
+    if (element && element.tagName?.toLowerCase() === this.componentName) {
       element.resolved = this.resolved;
+    } else if (this.resolved) {
+      this.renderComponent();
     }
   }
 
@@ -118,6 +132,41 @@ export class AiChatInteractionWrapper extends GenesisElement {
     }
 
     try {
+      // Pierce the wrapper's shadow boundary to read state from the assistant host.
+      const root = this.getRootNode();
+      const host =
+        root instanceof ShadowRoot
+          ? (root.host as {
+              isEngaged?: boolean;
+              hostId?: string;
+              claimSideEffect?: (interactionId: string) => boolean;
+            })
+          : null;
+
+      // GENC-1410 (Error 3): a widget must run on exactly ONE view. When several views share one
+      // driver, render the live widget only if this host is the elected owner AND wins the
+      // first-writer claim; otherwise show a passive placeholder and do NOT instantiate the widget
+      // (whose connectedCallback would fire a duplicate server call). A single-view app has no owner
+      // (or owns it) so it always renders. Resolved interactions always render (display only, no
+      // side effect) so state survives a pop.
+      if (!this.resolved) {
+        const isOwner = !this.ownerHostId || host?.hostId === this.ownerHostId;
+        // Only the elected owner attempts the claim. A non-owner must NEVER touch the latch: both
+        // views render the same history, so if a non-owner view (e.g. the hidden bubble while the
+        // panel is docked) renders its wrapper first, claiming here would grab the first-writer latch
+        // and the owner's own claim would then return false — leaving BOTH views on the placeholder,
+        // so the widget's side effect never fires (the interaction shows blank and hangs forever).
+        // Gating the claim behind `isOwner` makes the outcome independent of inter-host render order.
+        const claimed =
+          isOwner && (host?.claimSideEffect ? host.claimSideEffect(this.interactionId) : true);
+        if (!claimed) {
+          const placeholder = document.createElement('div');
+          placeholder.className = 'interaction-running-elsewhere';
+          this.container.appendChild(placeholder);
+          return;
+        }
+      }
+
       const element = document.createElement(this.componentName) as any;
 
       // Pass data and resolved state to the component
@@ -125,11 +174,8 @@ export class AiChatInteractionWrapper extends GenesisElement {
         element.data = this.data;
       }
       element.resolved = this.resolved;
-      // Pierce the wrapper's shadow boundary to read engagement from the
-      // assistant host. False if the widget is already resolved — re-renders
+      // Engagement gates autofocus. False if the widget is already resolved — re-renders
       // from history (layout remount, dock/undock) must never steal focus.
-      const root = this.getRootNode();
-      const host = root instanceof ShadowRoot ? (root.host as { isEngaged?: boolean }) : null;
       element.shouldAutoFocus = !this.resolved && !!host?.isEngaged;
 
       // Handle completion from the inner component.

package/src/components/flowing-waves-indicator.ts

@@ -24,6 +24,18 @@ const EDGE = 0.16;
 const MORPH_SPEED = 3;
 /** Global multiplier on the harmonic frequencies — raise for narrower peaks. */
 const FREQ_SCALE = 2;
+/** Milliseconds in one second. */
+const MS_PER_SECOND = 1000;
+/** Baseline frame rate (fps) the harmonic speeds are tuned against. */
+const BASELINE_FPS = 60;
+/**
+ * Frame duration (ms) at the baseline rate. The morph is driven by elapsed
+ * wall-clock time divided by this — not by the rAF callback count — so it
+ * advances at a constant real-world rate regardless of the display's refresh
+ * rate or dropped frames. At the baseline rate the resulting frame index
+ * matches the old per-callback counter, preserving the current look.
+ */
+const FRAME_MS = MS_PER_SECOND / BASELINE_FPS;
 /**
  * Half-thickness (viewBox units) each band keeps even between peaks, so the
  * waves emerge from a continuous line rather than leaving gaps. The four bands
@@ -188,9 +200,11 @@ const bandLayersMarkup = BANDS.map(
 export class AiFlowingWavesIndicator extends GenesisElement {
   // A rAF loop morphs the band shapes: pure CSS can't continuously reshape the
   // bumps (different sizes appearing at different times), and the per-frame sine
-  // sums are cheap. Same approach as the sine-tracing waves indicator.
+  // sums are cheap. Same approach as the sine-tracing waves indicator. The morph
+  // is keyed to elapsed wall-clock time (see FRAME_MS), not the rAF callback
+  // count, so it holds a constant speed even when frames are dropped.
 
-  private frame = 0;
+  private startTime?: number;
   private animFrame?: number;
   private bandPaths?: SVGPathElement[];
 
@@ -208,9 +222,11 @@ export class AiFlowingWavesIndicator extends GenesisElement {
       cancelAnimationFrame(this.animFrame);
       this.animFrame = undefined;
     }
+    // Reset the clock so a later reconnect restarts the morph cleanly at frame 0.
+    this.startTime = undefined;
   }
 
-  private tick() {
+  private tick(now?: number) {
     // Stop ticking once disconnected (belt-and-braces alongside the cancel in
     // disconnectedCallback) so no frames are scheduled while detached.
     if (!this.isConnected) {
@@ -221,12 +237,16 @@ export class AiFlowingWavesIndicator extends GenesisElement {
       const paths = this.shadowRoot?.querySelectorAll<SVGPathElement>('.band');
       if (paths?.length) this.bandPaths = Array.from(paths);
     }
+    // Anchor to the first real rAF timestamp; the initial synchronous call (no
+    // timestamp) renders frame 0. `frame` is then elapsed time in 60fps frames.
+    if (now !== undefined && this.startTime === undefined) this.startTime = now;
+    const frame =
+      now === undefined || this.startTime === undefined ? 0 : (now - this.startTime) / FRAME_MS;
     this.bandPaths?.forEach((path, i) => {
       const cfg = BANDS[i];
-      if (cfg) path.setAttribute('d', AiFlowingWavesIndicator.buildBand(cfg, this.frame));
+      if (cfg) path.setAttribute('d', AiFlowingWavesIndicator.buildBand(cfg, frame));
     });
-    this.frame += 1;
-    this.animFrame = requestAnimationFrame(() => this.tick());
+    this.animFrame = requestAnimationFrame((t) => this.tick(t));
   }
 
   /**

package/src/components/halo-overlay.ts

@@ -10,6 +10,17 @@ const HALO_DEFAULT_SPEED = 1.5;
 const HALO_DEFAULT_BORDER_SIZE = 3;
 const HALO_DEFAULT_GLOW_OPACITY = 0.35;
 const HALO_DEFAULT_GLOW_SPREAD = 70;
+/** Milliseconds in one second. */
+const MS_PER_SECOND = 1000;
+/** Baseline frame rate (fps) the `speed` (degrees/frame) is calibrated against. */
+const BASELINE_FPS = 60;
+/**
+ * Frame duration (ms) at the baseline rate. Rotation advances by the elapsed
+ * wall-clock time divided by this — not a fixed step per rAF callback — so it
+ * holds a constant real-world speed regardless of the display's refresh rate or
+ * dropped frames.
+ */
+const FRAME_MS = MS_PER_SECOND / BASELINE_FPS;
 
 /**
  * Animated halo overlay — rotating conic-gradient border with an inward glow.
@@ -135,6 +146,7 @@ export class AiHaloOverlay extends GenesisElement {
   private static readonly FULL_ROTATION_DEG = 360;
 
   private angle = 0;
+  private lastTime?: number;
   private animFrame?: number;
 
   connectedCallback() {
@@ -146,14 +158,27 @@ export class AiHaloOverlay extends GenesisElement {
     super.disconnectedCallback();
     if (this.animFrame !== undefined) {
       cancelAnimationFrame(this.animFrame);
+      this.animFrame = undefined;
     }
+    // Reset the clock so a later reconnect doesn't apply one huge time delta.
+    this.lastTime = undefined;
   }
 
-  private tick() {
-    const step = this.direction === 'ccw' ? -this.speed : this.speed;
-    this.angle =
-      (this.angle + step + AiHaloOverlay.FULL_ROTATION_DEG) % AiHaloOverlay.FULL_ROTATION_DEG;
-    this.style.setProperty('--halo-angle', `${this.angle}deg`);
-    this.animFrame = requestAnimationFrame(() => this.tick());
+  private tick(now?: number) {
+    // Advance by elapsed wall-clock time (expressed in 60fps-equivalent frames)
+    // rather than a fixed step per callback, so the rotation runs at a constant
+    // real-world speed regardless of the display's refresh rate or dropped
+    // frames. The first tick just seeds the clock (no delta yet).
+    if (this.lastTime !== undefined && now !== undefined) {
+      const frames = (now - this.lastTime) / FRAME_MS;
+      const step = this.direction === 'ccw' ? -this.speed : this.speed;
+      const raw = this.angle + step * frames;
+      this.angle =
+        ((raw % AiHaloOverlay.FULL_ROTATION_DEG) + AiHaloOverlay.FULL_ROTATION_DEG) %
+        AiHaloOverlay.FULL_ROTATION_DEG;
+      this.style.setProperty('--halo-angle', `${this.angle}deg`);
+    }
+    this.lastTime = now;
+    this.animFrame = requestAnimationFrame((t) => this.tick(t));
   }
 }

package/src/components/orchestrating-driver/orchestrating-driver.ts

@@ -209,6 +209,24 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
     return this.chatDriver.isBusy();
   }
 
+  // GENC-1410 (Error 3): forward single-instance / side-effect coordination to the inner driver,
+  // which owns the interaction history and pending map.
+  registerHost(hostId: string): void {
+    this.chatDriver.registerHost(hostId);
+  }
+
+  unregisterHost(hostId: string): void {
+    this.chatDriver.unregisterHost(hostId);
+  }
+
+  setActiveHost(hostId: string): void {
+    this.chatDriver.setActiveHost(hostId);
+  }
+
+  claimSideEffect(interactionId: string, hostId: string): boolean {
+    return this.chatDriver.claimSideEffect(interactionId, hostId);
+  }
+
   /** Currently active provider name from the underlying ChatDriver. */
   getActiveProviderName(): string {
     return this.chatDriver.getActiveProviderName();

package/src/components/settings-modal/settings-modal.styles.ts

@@ -128,6 +128,13 @@ export const settingsModalStyles = css`
     gap: calc(var(--design-unit) * 2px);
   }
 
+  .settings-modal-section-note {
+    margin: calc(var(--design-unit) * -2px) 0 calc(var(--design-unit) * 3px);
+    font-size: 12px;
+    line-height: 1.5;
+    color: var(--neutral-foreground-hint);
+  }
+
   .settings-modal-section-body {
     display: flex;
     flex-direction: column;

package/src/components/settings-modal/settings-modal.template.ts

@@ -212,10 +212,23 @@ const chatBotSettingsTemplate = (
       },
     ),
   )}
+  ${when(
+    (x) => x.chatConfig.ui?.showNarration != null,
+    chatBotToggleRow(
+      'Show working',
+      "Show the assistant's running commentary — the short notes it writes alongside its actions as it works, separate from its reasoning and its final answer.",
+      switchTag,
+      'toggle-narration',
+      (x) => x.showNarration,
+      (x, c) => {
+        x.showNarration = readSwitchChecked(c.event);
+      },
+    ),
+  )}
   ${when(
     (x) => x.chatConfig.ui?.showAgentSwitchIndicator != null,
     chatBotToggleRow(
-      'Enable agents',
+      'Show delegation',
       'Show in the chat window when tasks are delegated to different agents.',
       switchTag,
       'toggle-agent-switch',
@@ -225,21 +238,6 @@ const chatBotSettingsTemplate = (
       },
     ),
   )}
-  ${when(
-    (x) => x.chatConfig.ui?.allowDebugDownload === true,
-    settingsToggleRow(
-      'Download agent log',
-      "Export a structured debug timeline of this session's agent activity.",
-      'download-agent-log',
-      html<FoundationAiAssistant>`
-        <${buttonTag}
-          part="download-button"
-          appearance="outline"
-          @click=${(x) => x.downloadDebugLog()}
-        >Download</${buttonTag}>
-      `,
-    ),
-  )}
   ${when(
     (x) => x.chatConfig.ui?.animations?.userConfigurable === true,
     settingsToggleRow(
@@ -480,10 +478,32 @@ export const SettingsModalTemplate = (
           ${appSettingsTemplate(switchTag)}
         </div>
       </section>
+      ${when(
+        (x) => x.chatConfig.ui?.allowDebugDownload === true,
+        html<FoundationAiAssistant>`
+          <section class="settings-modal-section" part="settings-section-agent-log">
+            <div class="settings-modal-section-body">
+              ${settingsToggleRow(
+                'Download agent log',
+                "Export a structured debug timeline of this session's agent activity.",
+                'download-agent-log',
+                html<FoundationAiAssistant>`
+                  <${buttonTag}
+                    part="download-button"
+                    appearance="outline"
+                    @click=${(x) => x.downloadDebugLog()}
+                  >Download</${buttonTag}>
+                `,
+              )}
+            </div>
+          </section>
+        `,
+      )}
       <section class="settings-modal-section" part="settings-section-chat">
         <h3 class="settings-modal-section-title">
           <${iconTag} name="comment"></${iconTag}> AI Chat Bot Settings
         </h3>
+        <p class="settings-modal-section-note">These options only control what you see in the chat window and do not control model behaviour.</p>
         <div class="settings-modal-section-body">
           ${chatBotSettingsTemplate(switchTag, buttonTag)}
         </div>

package/src/components/waves-indicator.ts

@@ -17,6 +17,18 @@ const VIEWBOX = 120;
 const CENTRE = VIEWBOX / 2;
 /** Horizontal sampling step when tracing each wave path. Lower = smoother. */
 const SAMPLE_STEP = 6;
+/** Milliseconds in one second. */
+const MS_PER_SECOND = 1000;
+/** Baseline frame rate (fps) the wave speeds are tuned against. */
+const BASELINE_FPS = 60;
+/**
+ * Frame duration (ms) at the baseline rate. The paths are driven by elapsed
+ * wall-clock time divided by this — not by the rAF callback count — so they
+ * advance at a constant real-world rate regardless of the display's refresh
+ * rate or dropped frames. At the baseline rate the resulting frame index
+ * matches the old per-callback counter, preserving the current look.
+ */
+const FRAME_MS = MS_PER_SECOND / BASELINE_FPS;
 
 /**
  * Per-wave parameters. Each wave is a travelling sine (amplitude/frequency/phase)
@@ -163,8 +175,10 @@ export class AiWavesIndicator extends GenesisElement {
   // A rAF loop drives the wave paths for the same reason `<ai-halo-overlay>`
   // hand-drives its rotation: a pure-CSS approach can't produce per-frame sine
   // geometry, and SMIL/`<animate>` can't express the combined travel + slosh.
+  // The paths are keyed to elapsed wall-clock time (see FRAME_MS), not the rAF
+  // callback count, so they hold a constant speed even when frames are dropped.
 
-  private frame = 0;
+  private startTime?: number;
   private animFrame?: number;
   private wavePaths?: SVGPathElement[];
 
@@ -182,9 +196,11 @@ export class AiWavesIndicator extends GenesisElement {
       cancelAnimationFrame(this.animFrame);
       this.animFrame = undefined;
     }
+    // Reset the clock so a later reconnect restarts the waves cleanly at frame 0.
+    this.startTime = undefined;
   }
 
-  private tick() {
+  private tick(now?: number) {
     // Stop ticking once disconnected (belt-and-braces alongside the cancel in
     // disconnectedCallback) so no frames are scheduled while detached.
     if (!this.isConnected) {
@@ -195,11 +211,15 @@ export class AiWavesIndicator extends GenesisElement {
       const paths = this.shadowRoot?.querySelectorAll<SVGPathElement>('.wave');
       if (paths?.length) this.wavePaths = Array.from(paths);
     }
+    // Anchor to the first real rAF timestamp; the initial synchronous call (no
+    // timestamp) renders frame 0. `frame` is then elapsed time in 60fps frames.
+    if (now !== undefined && this.startTime === undefined) this.startTime = now;
+    const frame =
+      now === undefined || this.startTime === undefined ? 0 : (now - this.startTime) / FRAME_MS;
     this.wavePaths?.forEach((path, i) => {
-      path.setAttribute('d', AiWavesIndicator.buildWavePath(WAVES[i], this.frame));
+      path.setAttribute('d', AiWavesIndicator.buildWavePath(WAVES[i], frame));
     });
-    this.frame += 1;
-    this.animFrame = requestAnimationFrame(() => this.tick());
+    this.animFrame = requestAnimationFrame((t) => this.tick(t));
   }
 
   /** Trace one wave's polyline `d` attribute for the given frame. */

package/src/main/main.styles.ts

@@ -279,6 +279,12 @@ const baseStyles = css`
     font-size: 0.95em;
   }
 
+  /* Narration shares the Thinking bubble but is the assistant's commentary (labelled "Working"),
+     not its inner monologue — keep it upright so it reads as action, distinct from italic reasoning. */
+  .message.ai-thinking.narration {
+    font-style: normal;
+  }
+
   .message.ai-function {
     background: linear-gradient(135deg, rgb(15 32 39 / 90%) 0%, rgb(30 58 58 / 80%) 100%);
     color: var(--ai-function-color, #86efac);