@promptbook/cli 0.112.0-99 → 0.113.0-0

package/src/_packages/types.index.ts

@@ -5,8 +5,17 @@ import type { BookParameter } from '../book-2.0/agent-source/AgentBasicInformati
 import type { AgentCapability } from '../book-2.0/agent-source/AgentBasicInformation';
 import type { AgentBasicInformation } from '../book-2.0/agent-source/AgentBasicInformation';
 import type { AgentModelRequirements } from '../book-2.0/agent-source/AgentModelRequirements';
+import type { AgentVisibility } from '../book-2.0/agent-source/agentSourceVisibility';
 import type { CreateAgentModelRequirementsOptions } from '../book-2.0/agent-source/CreateAgentModelRequirementsOptions';
 import type { string_book } from '../book-2.0/agent-source/string_book';
+import type { BookNodeAgentSource } from '../book-3.0/BookNodeAgentSource';
+import type { BookNodeAgentSourceOptions } from '../book-3.0/BookNodeAgentSource';
+import type { CliAgentHarness } from '../book-3.0/CliAgent';
+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 type { LiteAgentOptions } from '../book-3.0/LiteAgent';
+import type { LiteAgentRunOptions } from '../book-3.0/LiteAgent';
 import type { AvatarChipProps } from '../book-components/AvatarProfile/AvatarChip/AvatarChip';
 import type { AvatarChipFromSourceProps } from '../book-components/AvatarProfile/AvatarChip/AvatarChipFromSource';
 import type { AvatarProfileProps } from '../book-components/AvatarProfile/AvatarProfile/AvatarProfile';
@@ -50,6 +59,7 @@ import type { ChatProgressCard } from '../book-components/Chat/types/ChatMessage
 import type { ChatMessageReplyingTo } from '../book-components/Chat/types/ChatMessage';
 import type { ChatMessage } from '../book-components/Chat/types/ChatMessage';
 import type { ChatParticipant } from '../book-components/Chat/types/ChatParticipant';
+import type { CitationLabelResolver } from '../book-components/Chat/types/CitationLabelResolver';
 import type { ParsedCitation } from '../book-components/Chat/utils/parseCitationsFromContent';
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import type { TeamToolResult } from '../book-components/Chat/utils/toolCallParsing/TeamToolResult';
@@ -440,8 +450,17 @@ export type { BookParameter };
 export type { AgentCapability };
 export type { AgentBasicInformation };
 export type { AgentModelRequirements };
+export type { AgentVisibility };
 export type { CreateAgentModelRequirementsOptions };
 export type { string_book };
+export type { BookNodeAgentSource };
+export type { BookNodeAgentSourceOptions };
+export type { CliAgentHarness };
+export type { CliAgentThinkingLevel };
+export type { CliAgentRunOptions };
+export type { CliAgentOptions };
+export type { LiteAgentOptions };
+export type { LiteAgentRunOptions };
 export type { AvatarChipProps };
 export type { AvatarChipFromSourceProps };
 export type { AvatarProfileProps };
@@ -485,6 +504,7 @@ export type { ChatProgressCard };
 export type { ChatMessageReplyingTo };
 export type { ChatMessage };
 export type { ChatParticipant };
+export type { CitationLabelResolver };
 export type { ParsedCitation };
 export type { MessageButton };
 export type { TeamToolResult };

package/src/avatars/avatarAnimationScheduler.ts

@@ -7,6 +7,48 @@
  */
 type AvatarAnimationListener = (now: number) => void;
 
+/**
+ * One scheduled avatar animation entry tracked by the shared loop.
+ *
+ * @private utility of the avatar rendering system
+ */
+type AvatarAnimationListenerEntry = {
+    readonly listener: AvatarAnimationListener;
+    lastRunAtMs: number;
+};
+
+/**
+ * Target frames per second for a single animated avatar.
+ *
+ * Animated octopus visuals change slowly enough that ~24 fps per avatar is indistinguishable
+ * from 60 fps in practice. Combined with `MAX_AVATAR_LISTENERS_PER_FRAME` this bounds total
+ * rendering work even when many avatars are visible.
+ *
+ * @private utility of the avatar rendering system
+ */
+const AVATAR_TARGET_FPS = 24;
+
+/**
+ * Minimum elapsed time in milliseconds required between two consecutive renders of the same avatar.
+ *
+ * @private utility of the avatar rendering system
+ */
+const AVATAR_TARGET_FRAME_INTERVAL_MS = 1000 / AVATAR_TARGET_FPS;
+
+/**
+ * Hard cap on how many avatar listeners can run inside the same animation frame.
+ *
+ * The default visual takes several milliseconds to render, so firing every visible avatar
+ * on the same animation frame stalls the main thread for tens of milliseconds and drops the
+ * overall page FPS to single digits. Bounding the number of listeners that fire per frame
+ * spreads the work across animation frames and keeps the UI responsive even with many
+ * visible avatars — each individual avatar still reaches `AVATAR_TARGET_FPS` because work
+ * is interleaved instead of skipped.
+ *
+ * @private utility of the avatar rendering system
+ */
+const MAX_AVATAR_LISTENERS_PER_FRAME = 2;
+
 /**
  * Next registration id used by the shared avatar animation scheduler.
  *
@@ -19,7 +61,7 @@ let nextAvatarAnimationListenerId = 1;
  *
  * @private utility of the avatar rendering system
  */
-const avatarAnimationListeners = new Map<number, AvatarAnimationListener>();
+const avatarAnimationListeners = new Map<number, AvatarAnimationListenerEntry>();
 
 /**
  * Active shared animation-frame handle.
@@ -31,6 +73,10 @@ let avatarAnimationFrameId: number | null = null;
 /**
  * Registers one avatar animation callback in the shared animation loop.
  *
+ * Each listener is staggered at registration time so it does not fire on the same animation
+ * frame as the existing listeners, and the shared loop further caps how many listeners run
+ * per frame, keeping the main thread responsive when many avatars are mounted.
+ *
  * @param avatarAnimationListener Frame callback invoked on every animation frame.
  * @returns Cleanup function that unregisters the callback.
  *
@@ -42,7 +88,15 @@ export function retainAvatarAnimationListener(avatarAnimationListener: AvatarAni
     }
 
     const listenerId = nextAvatarAnimationListenerId++;
-    avatarAnimationListeners.set(listenerId, avatarAnimationListener);
+    const existingListenerCount = avatarAnimationListeners.size;
+    const staggerOffsetMs =
+        ((existingListenerCount % Math.max(1, MAX_AVATAR_LISTENERS_PER_FRAME)) * AVATAR_TARGET_FRAME_INTERVAL_MS) /
+        Math.max(1, MAX_AVATAR_LISTENERS_PER_FRAME);
+    avatarAnimationListeners.set(listenerId, {
+        listener: avatarAnimationListener,
+        // Phase the listener so multiple new listeners do not synchronize on the same frame.
+        lastRunAtMs: performance.now() - AVATAR_TARGET_FRAME_INTERVAL_MS + staggerOffsetMs,
+    });
     ensureAvatarAnimationLoop();
 
     return () => {
@@ -68,8 +122,26 @@ function ensureAvatarAnimationLoop(): void {
     const runFrame = (now: number) => {
         avatarAnimationFrameId = null;
 
-        for (const avatarAnimationListener of [...avatarAnimationListeners.values()]) {
-            avatarAnimationListener(now);
+        const dueListenerEntries: Array<AvatarAnimationListenerEntry> = [];
+
+        for (const listenerEntry of avatarAnimationListeners.values()) {
+            if (now - listenerEntry.lastRunAtMs >= AVATAR_TARGET_FRAME_INTERVAL_MS) {
+                dueListenerEntries.push(listenerEntry);
+            }
+        }
+
+        // Run the most stale listeners first so each avatar keeps its target FPS even when
+        // total work exceeds the per-frame budget.
+        dueListenerEntries.sort(
+            (firstListenerEntry, secondListenerEntry) => firstListenerEntry.lastRunAtMs - secondListenerEntry.lastRunAtMs,
+        );
+
+        const listenersToRunCount = Math.min(dueListenerEntries.length, MAX_AVATAR_LISTENERS_PER_FRAME);
+
+        for (let listenerIndex = 0; listenerIndex < listenersToRunCount; listenerIndex++) {
+            const listenerEntry = dueListenerEntries[listenerIndex]!;
+            listenerEntry.lastRunAtMs = now;
+            listenerEntry.listener(now);
         }
 
         ensureAvatarAnimationLoop();

package/src/avatars/types/AvatarVisualDefinition.ts

@@ -15,6 +15,8 @@ export type AvatarVisualId =
     | 'octopus3'
     | 'octopus3d'
     | 'octopus3d2'
+    | 'octopus3d3'
+    | 'octopus3d4'
     | 'ascii-octopus'
     | 'minecraft'
     | 'minecraft2'

package/src/avatars/visuals/avatarVisualRegistry.ts

@@ -7,6 +7,8 @@ import { octopus2AvatarVisual } from './octopus2AvatarVisual';
 import { octopus3AvatarVisual } from './octopus3AvatarVisual';
 import { octopus3dAvatarVisual } from './octopus3dAvatarVisual';
 import { octopus3d2AvatarVisual } from './octopus3d2AvatarVisual';
+import { octopus3d3AvatarVisual } from './octopus3d3AvatarVisual';
+import { octopus3d4AvatarVisual } from './octopus3d4AvatarVisual';
 import { octopusAvatarVisual } from './octopusAvatarVisual';
 import { orbAvatarVisual } from './orbAvatarVisual';
 import { pixelArtAvatarVisual } from './pixelArtAvatarVisual';
@@ -25,6 +27,8 @@ export const AVATAR_VISUALS: ReadonlyArray<AvatarVisualDefinition> = [
     octopus3AvatarVisual,
     octopus3dAvatarVisual,
     octopus3d2AvatarVisual,
+    octopus3d3AvatarVisual,
+    octopus3d4AvatarVisual,
     asciiOctopusAvatarVisual,
     minecraftAvatarVisual,
     minecraft2AvatarVisual,

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,26 +310,50 @@ 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();
 }
 
+/**
+ * Number of latitude segments used by the single blobby octopus mesh.
+ *
+ * @private helper of `octopus3d2AvatarVisual`
+ */
+const LATITUDE_PATCH_COUNT = 12;
+
+/**
+ * Number of longitude segments used by the single blobby octopus mesh.
+ *
+ * @private helper of `octopus3d2AvatarVisual`
+ */
+const LONGITUDE_PATCH_COUNT = 24;
+
 /**
  * Resolves all visible projected patches for the single blobby octopus mesh.
  *
+ * Within a single frame, mesh corner samples and longitude-only lobe-wave values are
+ * quantized to the patch grid and computed once each rather than re-evaluated for every
+ * patch corner — the patch loop alone would call `sampleBlobbyOctopusSurfacePoint`
+ * `latitudePatchCount * longitudePatchCount * 4` times without caching, even though most
+ * corners are shared between neighboring patches.
+ *
  * @private helper of `octopus3d2AvatarVisual`
  */
 function resolveVisibleBlobbyOctopusPatches(options: {
@@ -311,29 +383,68 @@ function resolveVisibleBlobbyOctopusPatches(options: {
         animationPhase,
         timeMs,
     } = options;
-    const latitudePatchCount = 12;
-    const longitudePatchCount = 24;
+    const latitudePatchCount = LATITUDE_PATCH_COUNT;
+    const longitudePatchCount = LONGITUDE_PATCH_COUNT;
     const surfacePatches: Array<BlobbyOctopusSurfacePatch> = [];
+    const latitudeBoundaries = new Float64Array(latitudePatchCount + 1);
+    const longitudeBoundaries = new Float64Array(longitudePatchCount + 1);
+
+    for (let boundaryIndex = 0; boundaryIndex <= latitudePatchCount; boundaryIndex++) {
+        latitudeBoundaries[boundaryIndex] = -Math.PI / 2 + (boundaryIndex / latitudePatchCount) * Math.PI;
+    }
+
+    for (let boundaryIndex = 0; boundaryIndex <= longitudePatchCount; boundaryIndex++) {
+        longitudeBoundaries[boundaryIndex] = -Math.PI + (boundaryIndex / longitudePatchCount) * Math.PI * 2;
+    }
+
+    const cachedLobeWavesByCornerLongitude = new Float64Array(longitudePatchCount + 1);
+
+    for (let boundaryIndex = 0; boundaryIndex <= longitudePatchCount; boundaryIndex++) {
+        cachedLobeWavesByCornerLongitude[boundaryIndex] = resolveLowerLobeWave(
+            longitudeBoundaries[boundaryIndex]!,
+            morphologyProfile,
+            animationPhase,
+            timeMs,
+        );
+    }
+
+    const cornerCount = (latitudePatchCount + 1) * (longitudePatchCount + 1);
+    const transformedCornerSamples = new Array<Point3D>(cornerCount);
+
+    for (let latitudeBoundaryIndex = 0; latitudeBoundaryIndex <= latitudePatchCount; latitudeBoundaryIndex++) {
+        const cornerLatitude = latitudeBoundaries[latitudeBoundaryIndex]!;
+
+        for (let longitudeBoundaryIndex = 0; longitudeBoundaryIndex <= longitudePatchCount; longitudeBoundaryIndex++) {
+            const cornerLongitude = longitudeBoundaries[longitudeBoundaryIndex]!;
+            const cornerIndex = latitudeBoundaryIndex * (longitudePatchCount + 1) + longitudeBoundaryIndex;
+            const cornerSample = sampleBlobbyOctopusSurfacePointWithLongitudeCache(
+                options,
+                cornerLatitude,
+                cornerLongitude,
+                cachedLobeWavesByCornerLongitude[longitudeBoundaryIndex]!,
+            );
+            transformedCornerSamples[cornerIndex] = transformScenePoint(cornerSample, center, rotationX, rotationY);
+        }
+    }
 
     for (let latitudeIndex = 0; latitudeIndex < latitudePatchCount; latitudeIndex++) {
-        const startLatitude = -Math.PI / 2 + (latitudeIndex / latitudePatchCount) * Math.PI;
-        const endLatitude = -Math.PI / 2 + ((latitudeIndex + 1) / latitudePatchCount) * Math.PI;
+        const startLatitude = latitudeBoundaries[latitudeIndex]!;
+        const endLatitude = latitudeBoundaries[latitudeIndex + 1]!;
         const centerLatitude = (startLatitude + endLatitude) / 2;
         const verticalProgress = (Math.sin(centerLatitude) + 1) / 2;
+        const startCornerRowOffset = latitudeIndex * (longitudePatchCount + 1);
+        const endCornerRowOffset = (latitudeIndex + 1) * (longitudePatchCount + 1);
 
         for (let longitudeIndex = 0; longitudeIndex < longitudePatchCount; longitudeIndex++) {
-            const startLongitude = -Math.PI + (longitudeIndex / longitudePatchCount) * Math.PI * 2;
-            const endLongitude = -Math.PI + ((longitudeIndex + 1) / longitudePatchCount) * Math.PI * 2;
+            const startLongitude = longitudeBoundaries[longitudeIndex]!;
+            const endLongitude = longitudeBoundaries[longitudeIndex + 1]!;
             const centerLongitude = (startLongitude + endLongitude) / 2;
-            const localCorners = [
-                sampleBlobbyOctopusSurfacePoint(options, startLatitude, startLongitude),
-                sampleBlobbyOctopusSurfacePoint(options, startLatitude, endLongitude),
-                sampleBlobbyOctopusSurfacePoint(options, endLatitude, endLongitude),
-                sampleBlobbyOctopusSurfacePoint(options, endLatitude, startLongitude),
-            ] as const;
-            const transformedCorners = localCorners.map((localCorner) =>
-                transformScenePoint(localCorner, center, rotationX, rotationY),
-            ) as [Point3D, Point3D, Point3D, Point3D];
+            const transformedCorners: [Point3D, Point3D, Point3D, Point3D] = [
+                transformedCornerSamples[startCornerRowOffset + longitudeIndex]!,
+                transformedCornerSamples[startCornerRowOffset + longitudeIndex + 1]!,
+                transformedCornerSamples[endCornerRowOffset + longitudeIndex + 1]!,
+                transformedCornerSamples[endCornerRowOffset + longitudeIndex]!,
+            ];
             const surfaceNormal = normalizeVector3(
                 crossProduct3D(
                     subtractPoint3D(transformedCorners[1], transformedCorners[0]),
@@ -345,14 +456,20 @@ function resolveVisibleBlobbyOctopusPatches(options: {
                 continue;
             }
 
-            const projectedCorners = transformedCorners.map((transformedCorner) =>
-                projectScenePoint(transformedCorner, size, sceneCenterX, sceneCenterY),
-            ) as [ProjectedPoint, ProjectedPoint, ProjectedPoint, ProjectedPoint];
+            const projectedCorners: [ProjectedPoint, ProjectedPoint, ProjectedPoint, ProjectedPoint] = [
+                projectScenePoint(transformedCorners[0], size, sceneCenterX, sceneCenterY),
+                projectScenePoint(transformedCorners[1], size, sceneCenterX, sceneCenterY),
+                projectScenePoint(transformedCorners[2], size, sceneCenterX, sceneCenterY),
+                projectScenePoint(transformedCorners[3], size, sceneCenterX, sceneCenterY),
+            ];
             surfacePatches.push({
                 corners: projectedCorners,
                 averageDepth:
-                    transformedCorners.reduce((depthSum, transformedCorner) => depthSum + transformedCorner.z, 0) /
-                    transformedCorners.length,
+                    (transformedCorners[0].z +
+                        transformedCorners[1].z +
+                        transformedCorners[2].z +
+                        transformedCorners[3].z) /
+                    4,
                 lightIntensity: clampNumber(dotProduct3D(surfaceNormal, LIGHT_DIRECTION), -1, 1),
                 fillStyle: resolveBlobbySurfacePatchFillStyle(
                     palette,
@@ -380,13 +497,33 @@ function sampleBlobbyOctopusSurfacePoint(
     options: BlobbyOctopusSurfaceOptions,
     latitude: number,
     longitude: number,
+): Point3D {
+    const { morphologyProfile, animationPhase, timeMs } = options;
+    return sampleBlobbyOctopusSurfacePointWithLongitudeCache(
+        options,
+        latitude,
+        longitude,
+        resolveLowerLobeWave(longitude, morphologyProfile, animationPhase, timeMs),
+    );
+}
+
+/**
+ * Samples one point on the continuous Octopus 3D 2 surface using a precomputed lower-lobe wave
+ * to skip the per-call trig evaluation for `latitudePatchCount + 1` longitude-shared corners.
+ *
+ * @private helper of `octopus3d2AvatarVisual`
+ */
+function sampleBlobbyOctopusSurfacePointWithLongitudeCache(
+    options: BlobbyOctopusSurfaceOptions,
+    latitude: number,
+    longitude: number,
+    lowerLobeWave: number,
 ): Point3D {
     const { radiusX, radiusY, radiusZ, morphologyProfile, timeMs, animationPhase } = options;
     const cosineLatitude = Math.max(0, Math.cos(latitude));
     const verticalProgress = (Math.sin(latitude) + 1) / 2;
     const upperBlend = Math.pow(1 - verticalProgress, 1.2);
     const lowerBlend = Math.pow(verticalProgress, 1.42);
-    const lowerLobeWave = resolveLowerLobeWave(longitude, morphologyProfile, animationPhase, timeMs);
     const skirtEnvelope = Math.pow(cosineLatitude, 0.5) * lowerBlend;
     const horizontalScale =
         1.02 +