@promptbook/cli 0.112.0-117 → 0.112.0-118

package/esm/scripts/run-codex-prompts/common/parseDuration.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Parses a human-readable duration string into milliseconds.
+ *
+ * Supported formats: `Xh`, `Xm`, `Xs`, and combinations like `1h30m`, `1h30m5s`.
+ *
+ * @returns Duration in milliseconds
+ * @throws When the string does not match any supported format
+ *
+ * @private internal utility of `ptbk coder run`
+ */
+export declare function parseDuration(durationString: string): number;
+/**
+ * Formats a duration in milliseconds into a compact human-readable string.
+ *
+ * Examples: `3600000` → `"1h"`, `90000` → `"1m 30s"`, `5000` → `"5s"`.
+ *
+ * @private internal utility of `ptbk coder run`
+ */
+export declare function formatDurationMs(ms: number): string;

package/esm/src/_packages/node.index.d.ts

@@ -11,6 +11,11 @@ import type { CliAgentThinkingLevel } from '../book-3.0/CliAgent';
 import type { CliAgentRunOptions } from '../book-3.0/CliAgent';
 import type { CliAgentOptions } from '../book-3.0/CliAgent';
 import { CliAgent } from '../book-3.0/CliAgent';
+import { CLI_AGENT_HARNESS_NAMES } from '../book-3.0/cliAgentEnv';
+import { CLI_AGENT_THINKING_LEVEL_VALUES } from '../book-3.0/cliAgentEnv';
+import { PTBK_HARNESS_ENV } from '../book-3.0/cliAgentEnv';
+import { PTBK_MODEL_ENV } from '../book-3.0/cliAgentEnv';
+import { PTBK_THINKING_LEVEL_ENV } from '../book-3.0/cliAgentEnv';
 import type { LiteAgentOptions } from '../book-3.0/LiteAgent';
 import type { LiteAgentRunOptions } from '../book-3.0/LiteAgent';
 import { LiteAgent } from '../book-3.0/LiteAgent';
@@ -39,6 +44,11 @@ export type { CliAgentThinkingLevel };
 export type { CliAgentRunOptions };
 export type { CliAgentOptions };
 export { CliAgent };
+export { CLI_AGENT_HARNESS_NAMES };
+export { CLI_AGENT_THINKING_LEVEL_VALUES };
+export { PTBK_HARNESS_ENV };
+export { PTBK_MODEL_ENV };
+export { PTBK_THINKING_LEVEL_ENV };
 export type { LiteAgentOptions };
 export type { LiteAgentRunOptions };
 export { LiteAgent };

package/esm/src/book-3.0/BookNodeAgentSource.d.ts

@@ -15,7 +15,7 @@ export type BookNodeAgentSource = Book | string_book;
  */
 export type BookNodeAgentSourceOptions = {
     readonly agentPath?: string;
-    readonly book?: BookNodeAgentSource;
+    readonly book?: string | BookNodeAgentSource;
     readonly currentWorkingDirectory?: string;
 };
 /**

package/esm/src/book-3.0/CliAgent.d.ts

@@ -1,16 +1,17 @@
 import type { BookNodeAgentSourceOptions } from './BookNodeAgentSource';
+import { CLI_AGENT_HARNESS_NAMES, CLI_AGENT_THINKING_LEVEL_VALUES } 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`.
  *
@@ -22,6 +23,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;
@@ -38,6 +40,9 @@ export type CliAgentOptions = BookNodeAgentSourceOptions & CliAgentRunOptions;
  * 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 declare class CliAgent {

package/esm/src/book-3.0/cliAgentEnv.d.ts

@@ -0,0 +1,33 @@
+/**
+ * All CLI harness names supported by `CliAgent` and `ptbk agent exec`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const CLI_AGENT_HARNESS_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
+/**
+ * All supported thinking-level values for CLI coding-agent runners.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const CLI_AGENT_THINKING_LEVEL_VALUES: readonly ["low", "medium", "high", "xhigh"];
+/**
+ * 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 declare 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 declare 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 declare const PTBK_THINKING_LEVEL_ENV = "PTBK_THINKING_LEVEL";

package/esm/src/cli/cli-commands/common/promptRunnerCliOptions.d.ts

@@ -1,29 +1,13 @@
 import { Command as Program } from 'commander';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
+import { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV } from '../../../book-3.0/cliAgentEnv';
+export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
 /**
  * Runner identifiers supported by Promptbook CLI agent orchestration commands.
  *
  * @private internal utility of `promptbookCli`
  */
 export declare const PROMPT_RUNNER_HARNESS_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
-/**
- * Environment variable used as the default runner identifier when `--harness` is omitted.
- *
- * @private internal utility of `promptbookCli`
- */
-export declare const PTBK_HARNESS_ENV = "PTBK_HARNESS";
-/**
- * Environment variable used as the default runner model when `--model` is omitted.
- *
- * @private internal utility of `promptbookCli`
- */
-export declare const PTBK_MODEL_ENV = "PTBK_MODEL";
-/**
- * Environment variable used as the default runner thinking level when `--thinking-level` is omitted.
- *
- * @private internal utility of `promptbookCli`
- */
-export declare const PTBK_THINKING_LEVEL_ENV = "PTBK_THINKING_LEVEL";
 /**
  * Runner identifier supported by Promptbook CLI agent orchestration commands.
  *

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.112.0-116`).
+ * It follows semantic versioning (e.g., `0.112.0-117`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.112.0-117",
+    "version": "0.112.0-118",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/src/_packages/node.index.ts

@@ -14,6 +14,11 @@ import type { CliAgentThinkingLevel } from '../book-3.0/CliAgent';
 import type { CliAgentRunOptions } from '../book-3.0/CliAgent';
 import type { CliAgentOptions } from '../book-3.0/CliAgent';
 import { CliAgent } from '../book-3.0/CliAgent';
+import { CLI_AGENT_HARNESS_NAMES } from '../book-3.0/cliAgentEnv';
+import { CLI_AGENT_THINKING_LEVEL_VALUES } from '../book-3.0/cliAgentEnv';
+import { PTBK_HARNESS_ENV } from '../book-3.0/cliAgentEnv';
+import { PTBK_MODEL_ENV } from '../book-3.0/cliAgentEnv';
+import { PTBK_THINKING_LEVEL_ENV } from '../book-3.0/cliAgentEnv';
 import type { LiteAgentOptions } from '../book-3.0/LiteAgent';
 import type { LiteAgentRunOptions } from '../book-3.0/LiteAgent';
 import { LiteAgent } from '../book-3.0/LiteAgent';
@@ -48,6 +53,11 @@ export type { CliAgentThinkingLevel };
 export type { CliAgentRunOptions };
 export type { CliAgentOptions };
 export { CliAgent };
+export { CLI_AGENT_HARNESS_NAMES };
+export { CLI_AGENT_THINKING_LEVEL_VALUES };
+export { PTBK_HARNESS_ENV };
+export { PTBK_MODEL_ENV };
+export { PTBK_THINKING_LEVEL_ENV };
 export type { LiteAgentOptions };
 export type { LiteAgentRunOptions };
 export { LiteAgent };

package/src/avatars/avatarAnimationScheduler.ts

@@ -7,6 +7,24 @@
  */
 type AvatarAnimationListener = (now: number) => void;
 
+/**
+ * Target frames per second for the shared avatar animation loop.
+ *
+ * Animated octopus visuals change slowly enough that 24 fps is indistinguishable
+ * from 60 fps in practice, while cutting rendering work by ~60% when multiple
+ * avatars are on screen simultaneously.
+ *
+ * @private utility of the avatar rendering system
+ */
+const AVATAR_TARGET_FPS = 24;
+
+/**
+ * Minimum elapsed time in milliseconds required between avatar render passes.
+ *
+ * @private utility of the avatar rendering system
+ */
+const AVATAR_TARGET_FRAME_INTERVAL_MS = 1000 / AVATAR_TARGET_FPS;
+
 /**
  * Next registration id used by the shared avatar animation scheduler.
  *
@@ -28,6 +46,15 @@ const avatarAnimationListeners = new Map<number, AvatarAnimationListener>();
  */
 let avatarAnimationFrameId: number | null = null;
 
+/**
+ * Timestamp of the most recently rendered avatar frame.
+ *
+ * Used to throttle callbacks to `AVATAR_TARGET_FRAME_INTERVAL_MS`.
+ *
+ * @private utility of the avatar rendering system
+ */
+let lastAvatarFrameTime = 0;
+
 /**
  * Registers one avatar animation callback in the shared animation loop.
  *
@@ -68,8 +95,12 @@ function ensureAvatarAnimationLoop(): void {
     const runFrame = (now: number) => {
         avatarAnimationFrameId = null;
 
-        for (const avatarAnimationListener of [...avatarAnimationListeners.values()]) {
-            avatarAnimationListener(now);
+        if (now - lastAvatarFrameTime >= AVATAR_TARGET_FRAME_INTERVAL_MS) {
+            lastAvatarFrameTime = now;
+
+            for (const avatarAnimationListener of [...avatarAnimationListeners.values()]) {
+                avatarAnimationListener(now);
+            }
         }
 
         ensureAvatarAnimationLoop();

package/src/avatars/visuals/fractalAvatarVisual.ts

@@ -290,7 +290,7 @@ function drawDragonCurveLayer(
         layerIndex: number;
     },
 ): void {
-    const { size, primaryColor, secondaryColor, tertiaryColor, shadowColor, strokeWidth, timeMs, layerIndex } = options;
+    const { primaryColor, secondaryColor, tertiaryColor, shadowColor, strokeWidth, timeMs, layerIndex } = options;
     const firstPoint = points[0]!;
     const lastPoint = points[points.length - 1]!;
     const ribbonGradient = context.createLinearGradient(firstPoint.x, firstPoint.y, lastPoint.x, lastPoint.y);
@@ -298,14 +298,15 @@ function drawDragonCurveLayer(
     ribbonGradient.addColorStop(0.5, `${secondaryColor}e6`);
     ribbonGradient.addColorStop(1, `${tertiaryColor}f2`);
 
+    // Approximate the blurred shadow stroke with a wider semi-transparent stroke instead of
+    // context.filter blur, which triggers a costly software rasterization pass every frame.
     context.save();
     context.beginPath();
     tracePolyline(context, points);
-    context.strokeStyle = `${shadowColor}82`;
-    context.lineWidth = strokeWidth * 1.8;
+    context.strokeStyle = `${shadowColor}48`;
+    context.lineWidth = strokeWidth * 4.5;
     context.lineJoin = 'round';
     context.lineCap = 'round';
-    context.filter = `blur(${size * 0.022}px)`;
     context.stroke();
     context.restore();
 

package/src/avatars/visuals/minecraft2AvatarVisual.ts

@@ -218,19 +218,24 @@ function drawMinecraftShadow(
     },
     timeMs: number,
 ): void {
+    const cx = size * 0.5 + interaction.gazeX * size * 0.03;
+    const cy = size * 0.85 + Math.sin(timeMs / 880) * size * 0.01;
+    const rx = size * (0.16 + interaction.intensity * 0.015);
+    const ry = size * 0.055;
+
+    // Radial gradient approximates the blurry ellipse shadow without context.filter blur.
     context.save();
-    context.fillStyle = `${palette.shadow}66`;
-    context.filter = `blur(${size * 0.02}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.03,
-        size * 0.85 + Math.sin(timeMs / 880) * size * 0.01,
-        size * (0.16 + interaction.intensity * 0.015),
-        size * 0.055,
-        0,
-        0,
-        Math.PI * 2,
-    );
+    context.arc(0, 0, blurRadius, 0, Math.PI * 2);
     context.fill();
     context.restore();
 }

package/src/avatars/visuals/minecraftAvatarVisual.ts

@@ -45,13 +45,27 @@ export const minecraftAvatarVisual: AvatarVisualDefinition = {
         context.fillStyle = spotlight;
         context.fillRect(0, 0, size, size);
 
-        context.save();
-        context.fillStyle = 'rgba(0, 0, 0, 0.22)';
-        context.filter = `blur(${size * 0.018}px)`;
-        context.beginPath();
-        context.ellipse(size * 0.5, size * 0.86, size * 0.2, size * 0.06, 0, 0, Math.PI * 2);
-        context.fill();
-        context.restore();
+        {
+            // Radial gradient approximates the blurry ellipse shadow without context.filter blur.
+            const cx = size * 0.5;
+            const cy = size * 0.86;
+            const rx = size * 0.2;
+            const ry = size * 0.06;
+            const blurRadius = rx * 1.4;
+            const shadowGradient = context.createRadialGradient(0, 0, 0, 0, 0, blurRadius);
+            shadowGradient.addColorStop(0, 'rgba(0,0,0,0.28)');
+            shadowGradient.addColorStop(0.45, 'rgba(0,0,0,0.14)');
+            shadowGradient.addColorStop(0.8, 'rgba(0,0,0,0.05)');
+            shadowGradient.addColorStop(1, 'rgba(0,0,0,0)');
+            context.save();
+            context.translate(cx, cy);
+            context.scale(1, ry / rx);
+            context.fillStyle = shadowGradient;
+            context.beginPath();
+            context.arc(0, 0, blurRadius, 0, Math.PI * 2);
+            context.fill();
+            context.restore();
+        }
 
         drawVoxelCuboid(context, {
             x: bodyX,

package/src/avatars/visuals/octopus3d2AvatarVisual.ts

@@ -55,6 +55,53 @@ const LIGHT_DIRECTION: Point3D = normalizeVector3({
     z: 0.98,
 });
 
+/**
+ * Per-avatar stable state derived once from the seeded random factory and reused across frames.
+ *
+ * @private helper of `octopus3d2AvatarVisual`
+ */
+type Octopus3d2StableState = {
+    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 `octopus3d2AvatarVisual`
+ */
+const octopus3d2StableStateCache = new WeakMap<(salt: string) => () => number, Octopus3d2StableState>();
+
+/**
+ * Returns the stable per-avatar state, computing it on first access and caching for subsequent frames.
+ *
+ * @private helper of `octopus3d2AvatarVisual`
+ */
+function getOctopus3d2StableState(createRandom: (salt: string) => () => number): Octopus3d2StableState {
+    const cached = octopus3d2StableStateCache.get(createRandom);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const animationRandom = createRandom('octopus3d2-animation-profile');
+    const eyeRandom = createRandom('octopus3d2-eye-profile');
+    const leftEyePhaseOffset = eyeRandom() * 0.7;
+    const rightEyePhaseOffset = eyeRandom() * 0.7;
+    const state: Octopus3d2StableState = {
+        morphologyProfile: createOctopus3MorphologyProfile(createRandom),
+        animationPhase: animationRandom() * Math.PI * 2,
+        leftEyePhaseOffset,
+        rightEyePhaseOffset,
+    };
+
+    octopus3d2StableStateCache.set(createRandom, state);
+
+    return state;
+}
+
 /**
  * Octopus 3D 2 avatar visual.
  *
@@ -67,10 +114,8 @@ export const octopus3d2AvatarVisual: AvatarVisualDefinition = {
     isAnimated: true,
     supportsPointerTracking: true,
     render({ context, size, palette, createRandom, timeMs, interaction }) {
-        const morphologyProfile = createOctopus3MorphologyProfile(createRandom);
-        const animationRandom = createRandom('octopus3d2-animation-profile');
-        const eyeRandom = createRandom('octopus3d2-eye-profile');
-        const animationPhase = animationRandom() * Math.PI * 2;
+        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset } =
+            getOctopus3d2StableState(createRandom);
         const sceneCenterX = size * 0.5;
         const sceneCenterY = size * 0.575;
         const bob = Math.sin(timeMs / 940 + animationPhase) * size * 0.013;
@@ -152,7 +197,7 @@ export const octopus3d2AvatarVisual: AvatarVisualDefinition = {
             size,
             palette,
             timeMs,
-            animationPhase + eyeRandom() * 0.7,
+            animationPhase + leftEyePhaseOffset,
             interaction,
             morphologyProfile.face.eyeStyle,
         );
@@ -169,7 +214,7 @@ export const octopus3d2AvatarVisual: AvatarVisualDefinition = {
             size,
             palette,
             timeMs,
-            animationPhase + 0.9 + eyeRandom() * 0.7,
+            animationPhase + 0.9 + rightEyePhaseOffset,
             interaction,
             morphologyProfile.face.eyeStyle,
         );
@@ -249,6 +294,9 @@ function drawBlobbyOctopusAtmosphere(
 /**
  * Draws the soft floor shadow that anchors the single mesh in the 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 `octopus3d2AvatarVisual`
  */
 function drawBlobbyOctopusShadow(
@@ -262,19 +310,23 @@ function drawBlobbyOctopusShadow(
     timeMs: number,
     morphologyProfile: Octopus3MorphologyProfile,
 ): void {
+    const cx = size * 0.5 + interaction.gazeX * size * 0.045;
+    const cy = size * 0.88 + Math.sin(timeMs / 940) * size * 0.008;
+    const rx = size * (0.18 + (morphologyProfile.body.horizontalStretch - 1) * 0.04 + interaction.intensity * 0.018);
+    const ry = size * 0.062;
+
     context.save();
-    context.fillStyle = `${palette.shadow}66`;
-    context.filter = `blur(${size * 0.024}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.88 + Math.sin(timeMs / 940) * size * 0.008,
-        size * (0.18 + (morphologyProfile.body.horizontalStretch - 1) * 0.04 + interaction.intensity * 0.018),
-        size * 0.062,
-        0,
-        0,
-        Math.PI * 2,
-    );
+    context.arc(0, 0, blurRadius, 0, Math.PI * 2);
     context.fill();
     context.restore();
 }

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();
 }