@promptbook/cli 0.112.0-125 → 0.112.0-127

package/src/avatars/avatarAnimationScheduler.ts

@@ -8,56 +8,75 @@
 type AvatarAnimationListener = (now: number) => void;
 
 /**
- * Target frames per second for the shared avatar animation loop.
+ * One scheduled avatar animation entry tracked by the shared 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
+ */
+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 avatar render passes.
+ * 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;
 
 /**
- * Next registration id used by the shared avatar animation scheduler.
+ * 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
  */
-let nextAvatarAnimationListenerId = 1;
+const MAX_AVATAR_LISTENERS_PER_FRAME = 2;
 
 /**
- * Active avatar animation callbacks keyed by their registration id.
+ * Next registration id used by the shared avatar animation scheduler.
  *
  * @private utility of the avatar rendering system
  */
-const avatarAnimationListeners = new Map<number, AvatarAnimationListener>();
+let nextAvatarAnimationListenerId = 1;
 
 /**
- * Active shared animation-frame handle.
+ * Active avatar animation callbacks keyed by their registration id.
  *
  * @private utility of the avatar rendering system
  */
-let avatarAnimationFrameId: number | null = null;
+const avatarAnimationListeners = new Map<number, AvatarAnimationListenerEntry>();
 
 /**
- * Timestamp of the most recently rendered avatar frame.
- *
- * Used to throttle callbacks to `AVATAR_TARGET_FRAME_INTERVAL_MS`.
+ * Active shared animation-frame handle.
  *
  * @private utility of the avatar rendering system
  */
-let lastAvatarFrameTime = 0;
+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.
  *
@@ -69,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 () => {
@@ -95,14 +122,28 @@ function ensureAvatarAnimationLoop(): void {
     const runFrame = (now: number) => {
         avatarAnimationFrameId = null;
 
-        if (now - lastAvatarFrameTime >= AVATAR_TARGET_FRAME_INTERVAL_MS) {
-            lastAvatarFrameTime = now;
+        const dueListenerEntries: Array<AvatarAnimationListenerEntry> = [];
 
-            for (const avatarAnimationListener of [...avatarAnimationListeners.values()]) {
-                avatarAnimationListener(now);
+        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/visuals/octopus3d2AvatarVisual.ts

@@ -331,9 +331,29 @@ function drawBlobbyOctopusShadow(
     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: {
@@ -363,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]),
@@ -397,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,
@@ -432,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 +

package/src/avatars/visuals/octopus3d3AvatarVisual.ts

@@ -431,9 +431,29 @@ function drawContinuousOctopusShadow(
     context.restore();
 }
 
+/**
+ * Number of latitude segments used by the continuous Octopus 3D 3 mesh.
+ *
+ * @private helper of `octopus3d3AvatarVisual`
+ */
+const LATITUDE_PATCH_COUNT = 16;
+
+/**
+ * Number of longitude segments used by the continuous Octopus 3D 3 mesh.
+ *
+ * @private helper of `octopus3d3AvatarVisual`
+ */
+const LONGITUDE_PATCH_COUNT = 40;
+
 /**
  * Resolves visible projected patches for the continuous octopus mesh.
  *
+ * Within a single frame, mesh corner samples and longitude-only computations (tentacle
+ * influence and lobe wave) are quantized to the patch grid and computed once each rather
+ * than re-evaluated for every patch corner — the patch loop alone calls `sampleContinuousOctopusSurfacePoint`
+ * for `latitudePatchCount * longitudePatchCount * 4` corners without caching, and each call
+ * triggers an inner 8-iteration `Math.exp` loop, which dominates the per-frame cost.
+ *
  * @private helper of `octopus3d3AvatarVisual`
  */
 function resolveVisibleContinuousOctopusPatches(
@@ -448,29 +468,84 @@ function resolveVisibleContinuousOctopusPatches(
     },
 ): Array<ContinuousOctopusSurfacePatch> {
     const { center, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette } = options;
-    const latitudePatchCount = 16;
-    const longitudePatchCount = 40;
+    const latitudePatchCount = LATITUDE_PATCH_COUNT;
+    const longitudePatchCount = LONGITUDE_PATCH_COUNT;
     const surfacePatches: Array<ContinuousOctopusSurfacePatch> = [];
+    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 cachedTentacleInfluencesByCornerLongitude = new Array<ContinuousOctopusTentacleInfluence>(
+        longitudePatchCount + 1,
+    );
+    const cachedLobeWavesByCornerLongitude = new Float64Array(longitudePatchCount + 1);
+    const cachedTentacleInfluencesByPatchCenterLongitude = new Array<ContinuousOctopusTentacleInfluence>(
+        longitudePatchCount,
+    );
+    const cachedLobeWavesByPatchCenterLongitude = new Float64Array(longitudePatchCount);
+    const cachedCosByPatchCenterLongitude = new Float64Array(longitudePatchCount);
+
+    for (let boundaryIndex = 0; boundaryIndex <= longitudePatchCount; boundaryIndex++) {
+        const cornerLongitude = longitudeBoundaries[boundaryIndex]!;
+        cachedTentacleInfluencesByCornerLongitude[boundaryIndex] = resolveContinuousTentacleInfluence(
+            options,
+            cornerLongitude,
+        );
+        cachedLobeWavesByCornerLongitude[boundaryIndex] = resolveContinuousLobeWave(options, cornerLongitude);
+    }
+
+    for (let longitudeIndex = 0; longitudeIndex < longitudePatchCount; longitudeIndex++) {
+        const patchCenterLongitude = (longitudeBoundaries[longitudeIndex]! + longitudeBoundaries[longitudeIndex + 1]!) / 2;
+        cachedTentacleInfluencesByPatchCenterLongitude[longitudeIndex] = resolveContinuousTentacleInfluence(
+            options,
+            patchCenterLongitude,
+        );
+        cachedLobeWavesByPatchCenterLongitude[longitudeIndex] = resolveContinuousLobeWave(options, patchCenterLongitude);
+        cachedCosByPatchCenterLongitude[longitudeIndex] = Math.max(0, Math.cos(patchCenterLongitude));
+    }
+
+    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 = sampleContinuousOctopusSurfacePointWithLongitudeCache(
+                options,
+                cornerLatitude,
+                cornerLongitude,
+                cachedTentacleInfluencesByCornerLongitude[longitudeBoundaryIndex]!,
+                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 centerLongitude = (startLongitude + endLongitude) / 2;
-            const localCorners = [
-                sampleContinuousOctopusSurfacePoint(options, startLatitude, startLongitude),
-                sampleContinuousOctopusSurfacePoint(options, startLatitude, endLongitude),
-                sampleContinuousOctopusSurfacePoint(options, endLatitude, endLongitude),
-                sampleContinuousOctopusSurfacePoint(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]),
@@ -482,24 +557,28 @@ function resolveVisibleContinuousOctopusPatches(
                 continue;
             }
 
-            const projectedCorners = transformedCorners.map((transformedCorner) =>
-                projectScenePoint(transformedCorner, size, sceneCenterX, sceneCenterY),
-            ) as [ProjectedPoint, ProjectedPoint, ProjectedPoint, ProjectedPoint];
-            const tentacleInfluence = resolveContinuousTentacleInfluence(options, centerLongitude);
-            const lowerLobeWave = resolveContinuousLobeWave(options, centerLongitude);
+            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: resolveContinuousSurfacePatchFillStyle(
                     palette,
                     verticalProgress,
-                    Math.max(0, Math.cos(centerLongitude)),
-                    tentacleInfluence.core,
-                    lowerLobeWave,
+                    cachedCosByPatchCenterLongitude[longitudeIndex]!,
+                    cachedTentacleInfluencesByPatchCenterLongitude[longitudeIndex]!.core,
+                    cachedLobeWavesByPatchCenterLongitude[longitudeIndex]!,
                 ),
                 outlineColor: verticalProgress < 0.54 ? `${palette.highlight}69` : `${palette.shadow}78`,
             });
@@ -521,6 +600,32 @@ function sampleContinuousOctopusSurfacePoint(
     options: ContinuousOctopusSurfaceOptions,
     latitude: number,
     longitude: number,
+): Point3D {
+    return sampleContinuousOctopusSurfacePointWithLongitudeCache(
+        options,
+        latitude,
+        longitude,
+        resolveContinuousTentacleInfluence(options, longitude),
+        resolveContinuousLobeWave(options, longitude),
+    );
+}
+
+/**
+ * Samples one point on the continuous Octopus 3D 3 surface using precomputed longitude-only
+ * values to skip the per-call `Math.exp` tentacle-influence loop and the lobe-wave trig call.
+ *
+ * The patch loop quantizes the mesh into a fixed `(latitudePatchCount + 1) * (longitudePatchCount + 1)`
+ * corner grid, so the same longitude is reused across every latitude row and each
+ * tentacle/lobe value can be computed once per frame instead of `latitudePatchCount * 4` times.
+ *
+ * @private helper of `octopus3d3AvatarVisual`
+ */
+function sampleContinuousOctopusSurfacePointWithLongitudeCache(
+    options: ContinuousOctopusSurfaceOptions,
+    latitude: number,
+    longitude: number,
+    tentacleInfluence: ContinuousOctopusTentacleInfluence,
+    lowerLobeWave: number,
 ): Point3D {
     const { radiusX, radiusY, radiusZ, morphologyProfile, timeMs, animationPhase } = options;
     const cosineLatitude = Math.max(0, Math.cos(latitude));
@@ -528,10 +633,8 @@ function sampleContinuousOctopusSurfacePoint(
     const upperBlend = Math.pow(1 - verticalProgress, 1.28);
     const lowerBlend = smoothStep(0.38, 1, verticalProgress);
     const tipBlend = smoothStep(0.68, 1, verticalProgress);
-    const tentacleInfluence = resolveContinuousTentacleInfluence(options, longitude);
     const centerPull = resolveSignedAngularDistance(longitude, tentacleInfluence.centerLongitude);
     const effectiveLongitude = longitude + centerPull * lowerBlend * tentacleInfluence.core * (0.24 + tipBlend * 0.2);
-    const lowerLobeWave = resolveContinuousLobeWave(options, longitude);
     const mantleRipple =
         Math.sin(
             longitude * morphologyProfile.body.lobeCount +

package/src/book-2.0/agent-source/createAgentModelRequirementsWithCommitments/augmentAgentModelRequirementsFromSource.ts

@@ -282,12 +282,28 @@ function collectExampleInteractionLines(
     const initialMessage = parseResult.commitments.find((commitment) => commitment.type === 'INITIAL MESSAGE')?.content;
 
     if (initialMessage) {
-        examples.push(`**Agent:**\n${initialMessage}`);
+        examples.push(
+            spaceTrim(
+                (block) => `
+                    **Agent:**
+                    ${block(initialMessage)}
+                `,
+            ),
+        );
     }
 
     if (samples && samples.length > 0) {
         for (const sample of samples) {
-            examples.push(`**User:** ${sample.question}\n\n**Agent:**\n${sample.answer}`);
+            examples.push(
+                spaceTrim(
+                    (block) => `
+                        **User:** ${block(String(sample.question))}
+
+                        **Agent:**
+                        ${block(sample.answer)}
+                    `,
+                ),
+            );
         }
     }
 

package/src/book-2.0/book-language-documentation/renderGroupedCommitmentDocumentationMarkdown.ts

@@ -69,7 +69,13 @@ function removeLeadingTopLevelHeading(markdown: string): string {
  * @private internal utility of `createStandaloneBookLanguageMarkdown`
  */
 function renderDocumentationSection(title: string, documentation: string): string {
-    return `#### ${title}\n\n${removeLeadingTopLevelHeading(documentation)}`;
+    return spaceTrim(
+        (block) => `
+            #### ${title}
+
+            ${block(removeLeadingTopLevelHeading(documentation))}
+        `,
+    );
 }
 
 /**

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

@@ -88,6 +88,7 @@ export function Chat(props: ChatProps) {
         feedbackMode = 'stars',
         feedbackTranslations,
         timingTranslations,
+        resolveCitationLabel,
         onFileUpload,
         chatLocale,
         speechRecognition,
@@ -337,6 +338,7 @@ export function Chat(props: ChatProps) {
                         feedbackMode={feedbackMode}
                         feedbackTranslations={feedbackTranslations}
                         timingTranslations={timingTranslations}
+                        resolveCitationLabel={resolveCitationLabel}
                         chatLocale={chatLocale}
                         onCopy={handleCopy}
                         onMessage={onMessage}
@@ -404,6 +406,7 @@ export function Chat(props: ChatProps) {
                 toolCallIdentity={selectedToolCallIdentity}
                 onClose={closeToolCallModal}
                 toolTitles={toolTitles}
+                resolveCitationLabel={resolveCitationLabel}
                 agentParticipant={agentParticipant}
                 buttonColor={buttonColor}
                 teamAgentProfiles={teamAgentProfiles}
@@ -417,6 +420,7 @@ export function Chat(props: ChatProps) {
                 isOpen={citationModalOpen}
                 citation={selectedCitation}
                 participants={participants}
+                resolveCitationLabel={resolveCitationLabel}
                 soundSystem={soundSystem}
                 onClose={closeCitationModal}
             />

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

@@ -5,7 +5,9 @@ import { DownloadIcon } from '../../icons/DownloadIcon';
 import { classNames } from '../../_common/react-utils/classNames';
 import { MarkdownContent } from '../MarkdownContent/MarkdownContent';
 import type { ChatParticipant } from '../types/ChatParticipant';
-import { getCitationLabel, isPlainTextCitation, resolveCitationPreviewUrl } from '../utils/citationHelpers';
+import type { CitationLabelResolver } from '../types/CitationLabelResolver';
+import { useResolvedCitationLabel } from '../hooks/useResolvedCitationLabel';
+import { isPlainTextCitation, resolveCitationPreviewUrl } from '../utils/citationHelpers';
 import type { ParsedCitation } from '../utils/parseCitationsFromContent';
 import styles from './Chat.module.css';
 import { CitationIframePreview } from './CitationIframePreview';
@@ -20,17 +22,30 @@ export type ChatCitationModalProps = {
     isOpen: boolean;
     citation: ParsedCitation | null;
     participants: ReadonlyArray<ChatParticipant>;
+    resolveCitationLabel?: CitationLabelResolver;
     soundSystem?: ChatSoundSystem;
     onClose: () => void;
 };
 
+/**
+ * Empty citation used to keep modal hooks unconditional while the modal is closed.
+ *
+ * @private component constant of `<ChatCitationModal/>`
+ */
+const EMPTY_MODAL_CITATION: ParsedCitation = {
+    id: '',
+    source: '',
+};
+
 /**
  * Modal that previews a citation source or excerpt.
  *
  * @private component of `<Chat/>`
  */
 export function ChatCitationModal(props: ChatCitationModalProps) {
-    const { isOpen, citation, participants, soundSystem, onClose } = props;
+    const { isOpen, citation, participants, resolveCitationLabel, soundSystem, onClose } = props;
+    const resolvedCitation = citation || EMPTY_MODAL_CITATION;
+    const label = useResolvedCitationLabel(resolvedCitation, resolveCitationLabel);
 
     if (!isOpen || !citation) {
         return null;
@@ -43,7 +58,6 @@ export function ChatCitationModal(props: ChatCitationModalProps) {
     const previewSegment = previewBase.split('/').pop() || previewBase;
     const extension = previewSegment.split('.').pop()?.toLowerCase();
     const isImage = ['jpg', 'jpeg', 'png', 'gif', 'svg', 'webp'].includes(extension || '');
-    const label = getCitationLabel(citation);
     const isTextCitation = isPlainTextCitation(citation);
     const hasTextPreview = !isValidUrl && (citation.excerpt || isTextCitation);
     const textPreviewContent = isTextCitation ? citation.source : citation.excerpt ?? '';