@promptbook/cli 0.112.0-117 → 0.112.0-119

package/src/avatars/visuals/octopus3d3AvatarVisual.ts

@@ -93,6 +93,63 @@ const LIGHT_DIRECTION: Point3D = normalizeVector3({
  */
 const OCTOPUS_TENTACLE_COUNT = 8;
 
+/**
+ * Per-avatar stable state derived once from the seeded random factory and reused across frames.
+ *
+ * These values depend only on the avatar definition (name + hash + colors) and never change
+ * while the avatar is mounted, so computing them once and caching eliminates the largest
+ * allocation/computation spike in the hot render path.
+ *
+ * @private helper of `octopus3d3AvatarVisual`
+ */
+type Octopus3d3StableState = {
+    readonly morphologyProfile: Octopus3MorphologyProfile;
+    readonly animationPhase: number;
+    readonly leftEyePhaseOffset: number;
+    readonly rightEyePhaseOffset: number;
+    readonly tentacleProfiles: ReadonlyArray<ContinuousOctopusTentacleProfile>;
+};
+
+/**
+ * Cache keyed by the `createRandom` factory reference, which is stable for the lifetime of one
+ * mounted `<Avatar/>` component (created inside `resolveAvatarRenderDefinition` and held in a
+ * React `useMemo`).  Using a `WeakMap` ensures the entry is collected when the component unmounts.
+ *
+ * @private helper of `octopus3d3AvatarVisual`
+ */
+const stableStateCache = new WeakMap<(salt: string) => () => number, Octopus3d3StableState>();
+
+/**
+ * Returns the stable per-avatar state, computing it on first access and returning the cached
+ * result on every subsequent call within the same `<Avatar/>` mount.
+ *
+ * @private helper of `octopus3d3AvatarVisual`
+ */
+function getOctopus3d3StableState(createRandom: (salt: string) => () => number): Octopus3d3StableState {
+    const cached = stableStateCache.get(createRandom);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const morphologyProfile = createOctopus3MorphologyProfile(createRandom);
+    const animationRandom = createRandom('octopus3d3-animation-profile');
+    const eyeRandom = createRandom('octopus3d3-eye-profile');
+    const leftEyePhaseOffset = eyeRandom() * 0.7;
+    const rightEyePhaseOffset = eyeRandom() * 0.7;
+    const state: Octopus3d3StableState = {
+        morphologyProfile,
+        animationPhase: animationRandom() * Math.PI * 2,
+        leftEyePhaseOffset,
+        rightEyePhaseOffset,
+        tentacleProfiles: createContinuousTentacleProfiles(createRandom, morphologyProfile),
+    };
+
+    stableStateCache.set(createRandom, state);
+
+    return state;
+}
+
 /**
  * Octopus 3D 3 avatar visual.
  *
@@ -106,11 +163,8 @@ export const octopus3d3AvatarVisual: AvatarVisualDefinition = {
     isAnimated: true,
     supportsPointerTracking: true,
     render({ context, size, palette, createRandom, timeMs, interaction }) {
-        const morphologyProfile = createOctopus3MorphologyProfile(createRandom);
-        const animationRandom = createRandom('octopus3d3-animation-profile');
-        const eyeRandom = createRandom('octopus3d3-eye-profile');
-        const animationPhase = animationRandom() * Math.PI * 2;
-        const tentacleProfiles = createContinuousTentacleProfiles(createRandom, morphologyProfile);
+        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset, tentacleProfiles } =
+            getOctopus3d3StableState(createRandom);
         const sceneCenterX = size * 0.5;
         const sceneCenterY = size * 0.535;
         const bob = Math.sin(timeMs / 960 + animationPhase) * size * 0.012;
@@ -213,7 +267,7 @@ export const octopus3d3AvatarVisual: AvatarVisualDefinition = {
             size,
             palette,
             timeMs,
-            animationPhase + eyeRandom() * 0.7,
+            animationPhase + leftEyePhaseOffset,
             interaction,
             morphologyProfile.face.eyeStyle,
         );
@@ -230,7 +284,7 @@ export const octopus3d3AvatarVisual: AvatarVisualDefinition = {
             size,
             palette,
             timeMs,
-            animationPhase + 0.85 + eyeRandom() * 0.7,
+            animationPhase + 0.85 + rightEyePhaseOffset,
             interaction,
             morphologyProfile.face.eyeStyle,
         );
@@ -338,6 +392,9 @@ function drawContinuousOctopusAtmosphere(
 /**
  * Draws the soft lower shadow that anchors the octopus in the avatar frame.
  *
+ * Uses a scaled radial gradient instead of `context.filter = 'blur()'` to approximate the
+ * blurry ellipse without triggering a costly software rasterization pass on every frame.
+ *
  * @private helper of `octopus3d3AvatarVisual`
  */
 function drawContinuousOctopusShadow(
@@ -351,19 +408,25 @@ function drawContinuousOctopusShadow(
     timeMs: number,
     morphologyProfile: Octopus3MorphologyProfile,
 ): void {
+    const cx = size * 0.5 + interaction.gazeX * size * 0.045;
+    const cy = size * 0.9 + Math.sin(timeMs / 980) * size * 0.007;
+    const rx = size * (0.19 + morphologyProfile.tentacles.rootSpreadScale * 0.022 + interaction.intensity * 0.02);
+    const ry = size * 0.06;
+
+    // Scale the context so that drawing a circle produces the correct ellipse aspect ratio,
+    // then fill with a radial gradient that approximates the blurry edge without context.filter.
     context.save();
-    context.fillStyle = `${palette.shadow}66`;
-    context.filter = `blur(${size * 0.025}px)`;
+    context.translate(cx, cy);
+    context.scale(1, ry / rx);
+    const blurRadius = rx * 1.4;
+    const shadowGradient = context.createRadialGradient(0, 0, 0, 0, 0, blurRadius);
+    shadowGradient.addColorStop(0, `${palette.shadow}7a`);
+    shadowGradient.addColorStop(0.45, `${palette.shadow}44`);
+    shadowGradient.addColorStop(0.8, `${palette.shadow}1a`);
+    shadowGradient.addColorStop(1, `${palette.shadow}00`);
+    context.fillStyle = shadowGradient;
     context.beginPath();
-    context.ellipse(
-        size * 0.5 + interaction.gazeX * size * 0.045,
-        size * 0.9 + Math.sin(timeMs / 980) * size * 0.007,
-        size * (0.19 + morphologyProfile.tentacles.rootSpreadScale * 0.022 + interaction.intensity * 0.02),
-        size * 0.06,
-        0,
-        0,
-        Math.PI * 2,
-    );
+    context.arc(0, 0, blurRadius, 0, Math.PI * 2);
     context.fill();
     context.restore();
 }

package/src/avatars/visuals/octopus3dAvatarVisual.ts

@@ -55,6 +55,53 @@ const LIGHT_DIRECTION: Point3D = normalizeVector3({
     z: 0.94,
 });
 
+/**
+ * Per-avatar stable state derived once from the seeded random factory and reused across frames.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+type Octopus3dStableState = {
+    readonly morphologyProfile: Octopus3MorphologyProfile;
+    readonly animationPhase: number;
+    readonly leftEyePhaseOffset: number;
+    readonly rightEyePhaseOffset: number;
+};
+
+/**
+ * Cache keyed by the `createRandom` factory reference (stable per mounted `<Avatar/>`).
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+const octopus3dStableStateCache = new WeakMap<(salt: string) => () => number, Octopus3dStableState>();
+
+/**
+ * Returns the stable per-avatar state, computing it on first access and caching for subsequent frames.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function getOctopus3dStableState(createRandom: (salt: string) => () => number): Octopus3dStableState {
+    const cached = octopus3dStableStateCache.get(createRandom);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const animationRandom = createRandom('octopus3d-animation-profile');
+    const eyeRandom = createRandom('octopus3d-eye-profile');
+    const leftEyePhaseOffset = eyeRandom() * 0.6;
+    const rightEyePhaseOffset = eyeRandom() * 0.6;
+    const state: Octopus3dStableState = {
+        morphologyProfile: createOctopus3MorphologyProfile(createRandom),
+        animationPhase: animationRandom() * Math.PI * 2,
+        leftEyePhaseOffset,
+        rightEyePhaseOffset,
+    };
+
+    octopus3dStableStateCache.set(createRandom, state);
+
+    return state;
+}
+
 /**
  * Proper 3D Octopus visual built from projected organic meshes and tentacles.
  *
@@ -67,10 +114,8 @@ export const octopus3dAvatarVisual: AvatarVisualDefinition = {
     isAnimated: true,
     supportsPointerTracking: true,
     render({ context, size, palette, createRandom, timeMs, interaction }) {
-        const morphologyProfile = createOctopus3MorphologyProfile(createRandom);
-        const animationRandom = createRandom('octopus3d-animation-profile');
-        const eyeRandom = createRandom('octopus3d-eye-profile');
-        const animationPhase = animationRandom() * Math.PI * 2;
+        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset } =
+            getOctopus3dStableState(createRandom);
         const sceneCenterX = size * 0.5;
         const sceneCenterY = size * 0.56;
         const bob = Math.sin(timeMs / 920 + animationPhase) * size * 0.014;
@@ -201,7 +246,7 @@ export const octopus3dAvatarVisual: AvatarVisualDefinition = {
             size,
             palette,
             timeMs,
-            animationPhase + eyeRandom() * 0.6,
+            animationPhase + leftEyePhaseOffset,
             interaction,
             morphologyProfile.face.eyeStyle,
         );
@@ -228,7 +273,7 @@ export const octopus3dAvatarVisual: AvatarVisualDefinition = {
             size,
             palette,
             timeMs,
-            animationPhase + 0.7 + eyeRandom() * 0.6,
+            animationPhase + 0.7 + rightEyePhaseOffset,
             interaction,
             morphologyProfile.face.eyeStyle,
         );
@@ -334,6 +379,9 @@ function drawOctopus3dAtmosphere(
 /**
  * Draws the soft ground shadow below the octopus.
  *
+ * Uses a scaled radial gradient instead of `context.filter = 'blur()'` to approximate the
+ * blurry ellipse without triggering a costly software rasterization pass on every frame.
+ *
  * @private helper of `octopus3dAvatarVisual`
  */
 function drawOctopus3dShadow(
@@ -346,19 +394,23 @@ function drawOctopus3dShadow(
     },
     timeMs: number,
 ): void {
+    const cx = size * 0.5 + interaction.gazeX * size * 0.04;
+    const cy = size * 0.87 + Math.sin(timeMs / 920) * size * 0.008;
+    const rx = size * (0.18 + interaction.intensity * 0.02);
+    const ry = size * 0.06;
+
     context.save();
-    context.fillStyle = `${palette.shadow}66`;
-    context.filter = `blur(${size * 0.022}px)`;
+    context.translate(cx, cy);
+    context.scale(1, ry / rx);
+    const blurRadius = rx * 1.4;
+    const shadowGradient = context.createRadialGradient(0, 0, 0, 0, 0, blurRadius);
+    shadowGradient.addColorStop(0, `${palette.shadow}7a`);
+    shadowGradient.addColorStop(0.45, `${palette.shadow}44`);
+    shadowGradient.addColorStop(0.8, `${palette.shadow}1a`);
+    shadowGradient.addColorStop(1, `${palette.shadow}00`);
+    context.fillStyle = shadowGradient;
     context.beginPath();
-    context.ellipse(
-        size * 0.5 + interaction.gazeX * size * 0.04,
-        size * 0.87 + Math.sin(timeMs / 920) * size * 0.008,
-        size * (0.18 + interaction.intensity * 0.02),
-        size * 0.06,
-        0,
-        0,
-        Math.PI * 2,
-    );
+    context.arc(0, 0, blurRadius, 0, Math.PI * 2);
     context.fill();
     context.restore();
 }

package/src/book-3.0/Book.ts

@@ -215,7 +215,9 @@ function parseBookMessageHeader(line: string): Pick<BookMessageBlock, 'marker' |
  * @private internal utility of `Book`
  */
 function parseCommitmentHeader(line: string): Commitment | null {
-    const match = /^([A-Z][A-Z0-9]*(?: [A-Z0-9]+)*)(?:\s+(.*))?$/u.exec(line);
+    // Require at least 2 characters in the first keyword word to avoid treating common
+    // single-letter words (e.g. "V" in Czech, "I" or "A" in English) as commitment headers.
+    const match = /^([A-Z][A-Z0-9]+(?: [A-Z0-9]+)*)(?:\s+(.*))?$/u.exec(line);
     if (!match) {
         return null;
     }

package/src/book-3.0/BookNodeAgentSource.ts

@@ -23,7 +23,7 @@ export type BookNodeAgentSource = Book | string_book;
  */
 export type BookNodeAgentSourceOptions = {
     readonly agentPath?: string;
-    readonly book?: BookNodeAgentSource;
+    readonly book?: string | BookNodeAgentSource;
     readonly currentWorkingDirectory?: string;
 };
 
@@ -92,7 +92,7 @@ export async function resolveBookNodeAgentSource(
  *
  * @private internal utility of `resolveBookNodeAgentSource`
  */
-function normalizeBookNodeAgentSource(book: BookNodeAgentSource): string_book {
+function normalizeBookNodeAgentSource(book: string | BookNodeAgentSource): string_book {
     if (book instanceof Book) {
         return book.stringify();
     }

package/src/book-3.0/CliAgent.ts

@@ -3,22 +3,30 @@ import { dirname } from 'path';
 import { executeAgentChatTurn } from '../../scripts/run-agent-chat/executeAgentChatTurn';
 import { NotAllowed } from '../errors/NotAllowed';
 import { resolvePromptbookTemporaryPath } from '../utils/filesystem/promptbookTemporaryPath';
+import { spaceTrim } from '../utils/organization/spaceTrim';
 import type { BookNodeAgentSourceOptions, ResolvedBookNodeAgentSource } from './BookNodeAgentSource';
 import { resolveBookNodeAgentSource } from './BookNodeAgentSource';
+import {
+    CLI_AGENT_HARNESS_NAMES,
+    CLI_AGENT_THINKING_LEVEL_VALUES,
+    PTBK_HARNESS_ENV,
+    PTBK_MODEL_ENV,
+    PTBK_THINKING_LEVEL_ENV,
+} from './cliAgentEnv';
 
 /**
  * CLI harness names supported by `ptbk agent exec`.
  *
  * @public exported from `@promptbook/node`
  */
-export type CliAgentHarness = 'openai-codex' | 'github-copilot' | 'cline' | 'claude-code' | 'opencode' | 'gemini';
+export type CliAgentHarness = (typeof CLI_AGENT_HARNESS_NAMES)[number];
 
 /**
  * Thinking levels supported by CLI coding harnesses.
  *
  * @public exported from `@promptbook/node`
  */
-export type CliAgentThinkingLevel = 'low' | 'medium' | 'high' | 'xhigh';
+export type CliAgentThinkingLevel = (typeof CLI_AGENT_THINKING_LEVEL_VALUES)[number];
 
 /**
  * Per-run CLI options exposed by `CliAgent`.
@@ -31,6 +39,7 @@ export type CliAgentRunOptions = {
     readonly allowCredits?: boolean;
     readonly context?: string;
     readonly harness?: CliAgentHarness;
+    readonly isVerbose?: boolean;
     readonly model?: string;
     readonly noUi?: boolean;
     readonly thinkingLevel?: CliAgentThinkingLevel;
@@ -56,6 +65,9 @@ const DEFAULT_CLI_AGENT_IS_NO_UI = true;
  * It uses the same harnesses and execution path as `ptbk agent exec`, running the runner
  * in-process instead of spawning a separate CLI process.
  *
+ * When no `harness` is provided in the constructor or per-run options, `CliAgent` falls back
+ * to the `PTBK_HARNESS` environment variable, mirroring `ptbk agent exec` behavior.
+ *
  * @public exported from `@promptbook/node`
  */
 export class CliAgent {
@@ -81,15 +93,30 @@ export class CliAgent {
         const agentPath = await this.resolveExecutableAgentPath(resolvedSource);
         const mergedOptions = mergeCliAgentRunOptions(this.options, options);
 
+        const harness = mergedOptions.harness ?? resolveCliAgentHarnessFromEnv();
+
+        if (!harness) {
+            throw new NotAllowed(
+                spaceTrim(`
+                    No harness specified for \`CliAgent\`. Pass \`harness\` in the constructor options or per-run options,
+                    or set the \`${PTBK_HARNESS_ENV}\` environment variable.
+
+                    Available harnesses: ${CLI_AGENT_HARNESS_NAMES.join(', ')}
+
+                    Example: \`PTBK_HARNESS=claude-code\`
+                `),
+            );
+        }
+
         const result = await executeAgentChatTurn({
             agentPath,
             messages: [{ sender: 'USER', content: normalizedMessage }],
-            agentName: mergedOptions.harness,
-            model: mergedOptions.model,
+            agentName: harness,
+            model: mergedOptions.model ?? process.env[PTBK_MODEL_ENV],
             noUi: mergedOptions.noUi ?? DEFAULT_CLI_AGENT_IS_NO_UI,
-            thinkingLevel: mergedOptions.thinkingLevel,
+            thinkingLevel: mergedOptions.thinkingLevel ?? resolveCliAgentThinkingLevelFromEnv(),
             allowCredits: mergedOptions.allowCredits ?? false,
-            isVerbose: false,
+            isVerbose: mergedOptions.isVerbose ?? false,
             context: mergedOptions.context,
             currentWorkingDirectory: resolvedSource.currentWorkingDirectory,
         });
@@ -128,12 +155,63 @@ function mergeCliAgentRunOptions(defaults: CliAgentRunOptions, overrides: CliAge
         allowCredits: overrides.allowCredits ?? defaults.allowCredits,
         context: overrides.context ?? defaults.context,
         harness: overrides.harness ?? defaults.harness,
+        isVerbose: overrides.isVerbose ?? defaults.isVerbose,
         model: overrides.model ?? defaults.model,
         noUi: overrides.noUi ?? defaults.noUi,
         thinkingLevel: overrides.thinkingLevel ?? defaults.thinkingLevel,
     };
 }
 
+/**
+ * Reads and validates the harness name from the `PTBK_HARNESS` environment variable.
+ *
+ * @private internal utility of `CliAgent`
+ */
+function resolveCliAgentHarnessFromEnv(): CliAgentHarness | undefined {
+    const envValue = process.env[PTBK_HARNESS_ENV];
+
+    if (!envValue) {
+        return undefined;
+    }
+
+    if (!(CLI_AGENT_HARNESS_NAMES as ReadonlyArray<string>).includes(envValue)) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`${PTBK_HARNESS_ENV}\` environment variable: \`${envValue}\`
+
+                Must be one of: ${CLI_AGENT_HARNESS_NAMES.join(', ')}
+            `),
+        );
+    }
+
+    return envValue as CliAgentHarness;
+}
+
+/**
+ * Reads and validates the thinking level from the `PTBK_THINKING_LEVEL` environment variable.
+ *
+ * @private internal utility of `CliAgent`
+ */
+function resolveCliAgentThinkingLevelFromEnv(): CliAgentThinkingLevel | undefined {
+    const envValue = process.env[PTBK_THINKING_LEVEL_ENV];
+
+    if (!envValue) {
+        return undefined;
+    }
+
+    if (!(CLI_AGENT_THINKING_LEVEL_VALUES as ReadonlyArray<string>).includes(envValue)) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`${PTBK_THINKING_LEVEL_ENV}\` environment variable: \`${envValue}\`
+
+                Must be one of: ${CLI_AGENT_THINKING_LEVEL_VALUES.join(', ')}
+            `),
+        );
+    }
+
+    return envValue as CliAgentThinkingLevel;
+}
+
 /**
  * Creates the stable temporary path used when `CliAgent` is initialized from in-memory Book source.
  *

package/src/book-3.0/LiteAgent.ts

@@ -305,7 +305,7 @@ async function resolveLiteAgentScriptExecutionTools(
     if (options.scriptExecutionTools) {
         return Array.isArray(options.scriptExecutionTools)
             ? options.scriptExecutionTools
-            : [options.scriptExecutionTools];
+            : [options.scriptExecutionTools as ScriptExecutionTools];
     }
 
     return $provideScriptingForNode({

package/src/book-3.0/cliAgentEnv.ts

@@ -0,0 +1,46 @@
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
+/**
+ * All CLI harness names supported by `CliAgent` and `ptbk agent exec`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const CLI_AGENT_HARNESS_NAMES = [
+    'openai-codex',
+    'github-copilot',
+    'cline',
+    'claude-code',
+    'opencode',
+    'gemini',
+] as const;
+
+/**
+ * All supported thinking-level values for CLI coding-agent runners.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const CLI_AGENT_THINKING_LEVEL_VALUES = ['low', 'medium', 'high', 'xhigh'] as const;
+
+/**
+ * Environment variable used as the default runner identifier when `--harness` is omitted or not set in `CliAgent`.
+ *
+ * Set this to one of the harness names (`openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`)
+ * so that `CliAgent` and `ptbk agent exec` can run without an explicit `harness` option.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const PTBK_HARNESS_ENV = 'PTBK_HARNESS';
+
+/**
+ * Environment variable used as the default runner model when `--model` is omitted or not set in `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const PTBK_MODEL_ENV = 'PTBK_MODEL';
+
+/**
+ * Environment variable used as the default thinking level when `--thinking-level` is omitted or not set in `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export const PTBK_THINKING_LEVEL_ENV = 'PTBK_THINKING_LEVEL';

package/src/book-components/BookEditor/BookEditor.tsx

@@ -2,7 +2,7 @@
 // <- Note: [👲] 'use client' is enforced by Next.js when building the https://book-components.ptbk.io/ but in ideal case,
 //          this would not be here because the `@promptbook/components` package should be React library independent of Next.js specifics
 
-import { CSSProperties, useState } from 'react';
+import { type CSSProperties, useState } from 'react';
 import { createPortal } from 'react-dom';
 import type { Promisable } from 'type-fest';
 import type { string_book } from '../../book-2.0/agent-source/string_book';
@@ -14,8 +14,8 @@ import type { string_css_value } from '../../types/string_markdown';
 import { countLines } from '../../utils/expectation-counters/countLines';
 import type { HoistedMenuItem } from '../_common/MenuHoisting/MenuHoistingContext';
 import { classNames } from '../_common/react-utils/classNames';
-import { DEFAULT_IS_VERBOSE } from './BookEditorBrowserConfig';
 import styles from './BookEditor.module.css';
+import { DEFAULT_IS_VERBOSE } from './BookEditorBrowserConfig';
 import { BookEditorMonaco } from './BookEditorMonaco';
 import type { BookEditorTheme } from './BookEditorTheme';
 import { BOOK_EDITOR_RENDER_THEME, resolveBookEditorRenderTheme } from './BookEditorTheme';
@@ -300,11 +300,11 @@ export function BookEditor(props: BookEditorProps) {
         isBorderRadiusDisabled = false,
         isReadonly = false,
         translations,
-        isUploadButtonShown = true,
+        isUploadButtonShown = false,
         isCameraButtonShown,
-        isDownloadButtonShown = true,
-        isAboutButtonShown = true,
-        isFullscreenButtonShown = true,
+        isDownloadButtonShown = false,
+        isAboutButtonShown = false,
+        isFullscreenButtonShown = false,
         sync,
         monacoModelPath,
         hoistedMenuItems,

package/src/book-components/BookEditor/BookEditorForClient.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import { BookEditorProps } from './BookEditor';
+import type { BookEditorProps } from './BookEditor';
 
 type BookEditorComponent = typeof import('./BookEditor').BookEditor;
 

package/src/book-components/Chat/Chat/Chat.module.css

@@ -3311,6 +3311,51 @@
     display: block;
 }
 
+.citationIframeLoading {
+    width: 100%;
+    height: 60vh;
+    min-height: 400px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: #888;
+    font-size: 0.9em;
+}
+
+.citationScreenshotFallback {
+    width: 100%;
+    position: relative;
+    display: flex;
+    flex-direction: column;
+}
+
+.citationScreenshotImage {
+    width: 100%;
+    max-height: 60vh;
+    min-height: 400px;
+    object-fit: cover;
+    object-position: top;
+    display: block;
+}
+
+.citationScreenshotLink {
+    display: block;
+    text-align: center;
+    padding: 10px 16px;
+    background: #f0f0f0;
+    color: #333;
+    font-size: 0.9em;
+    font-weight: 500;
+    text-decoration: none;
+    border-top: 1px solid #ddd;
+    transition: background 0.15s;
+}
+
+.citationScreenshotLink:hover {
+    background: #e0e0e0;
+    text-decoration: underline;
+}
+
 .citationMetadata {
     background: #f8f8f8;
     padding: 16px;

package/src/book-components/Chat/Chat/ChatCitationModal.tsx

@@ -8,6 +8,7 @@ import type { ChatParticipant } from '../types/ChatParticipant';
 import { getCitationLabel, isPlainTextCitation, resolveCitationPreviewUrl } from '../utils/citationHelpers';
 import type { ParsedCitation } from '../utils/parseCitationsFromContent';
 import styles from './Chat.module.css';
+import { CitationIframePreview } from './CitationIframePreview';
 import type { ChatSoundSystem } from './ChatProps';
 
 /**
@@ -84,9 +85,8 @@ export function ChatCitationModal(props: ChatCitationModalProps) {
                                         }}
                                     />
                                 ) : (
-                                    <iframe
+                                    <CitationIframePreview
                                         src={previewUrl ?? citation.source}
-                                        className={styles.citationIframe}
                                         title={`Preview of ${label}`}
                                     />
                                 )}