inscription atlas: procedural loading spinner + rename "saturation" → "atlas full"

Loading indicator
-----------------
TxSprite's render state is now tristate: 0 = flat colour, 1 = procedural
loading spinner, 2 = atlas texture. The spinner is shader-only — no asset,
no second sampler — drawn in slot-local UV space (vCorner) using the
existing `now` uniform: a rotating arc inside an annulus, ~10 GPU
instructions per fragment. New tx-sprite.setLoading() flips the flag the
moment the atlas takes a slot, atlas calls setTexture() once the image
arrives, clearTexture() on terminal failure or release.

So the spinner keeps turning while waiting on slow fetches, the atlas
exposes hasPendingFetches() and the render loop's continuation condition
adds it alongside the existing scene-animation gate.

Naming
------
Replaced "saturation" / "saturated" wording with "atlas full" /
"runs out of room" everywhere — "saturation" reads as colour-saturation
in image-rendering code. saturationLogged → atlasFullLogged,
logSaturationOnce → logAtlasFullOnce, plus matching docstring + comment
updates in the atlas, the quadtree, and the spec.

Author: hans-crypto

frontend/src/app/components/block-overview-graph/_ordpool/ordpool-inscription-atlas.ts

@@ -14,7 +14,7 @@
  *
  * # Pipeline
  *
- *   1. CPU side: HTMLCanvasElement (1024² → 2048² after first saturation).
+ *   1. CPU side: HTMLCanvasElement (1024² → 2048² when the smaller atlas runs out of room).
  *      `requestSlot()` allocates a power-of-two pixel rectangle via the
  *      quadtree allocator and kicks off a fetch for `/content/<txid>` (or
  *      `/stamp-content/<txid>`, `/atomical-content/<txid>` depending on
@@ -40,13 +40,15 @@
  * fetches retry twice (500 ms / 2 s) before being added to a FIFO failure
  * cache so transient flaps don't permanently blacklist a txid.
  *
- * # Saturation
+ * # Running out of room ("atlas full")
  *
- * On first full, the atlas expands once from 1024² to 2048² (4× capacity)
- * by allocating a larger canvas, blitting the existing pixel buffer at
- * (0, 0) — slot positions are preserved — and recreating the GPU texture.
- * The second saturation is logged once via `console.error` and the
- * affected sprite stays at flat colour; further saturations are silent.
+ * On the first allocation that doesn't fit, the atlas expands once from
+ * 1024² to 2048² (4× capacity) by allocating a larger canvas, blitting the
+ * existing pixel buffer at (0, 0) — slot positions are preserved — and
+ * recreating the GPU texture. If the 2048² atlas also fills, one
+ * `console.error` reports it and the affected sprite stays at flat colour;
+ * further "atlas full" events are silent so the console doesn't flood when
+ * a single scene rebuild fires the same condition for many sprites.
  *
  * # No spinner
  *
@@ -61,10 +63,11 @@ import * as quadtree from './ordpool-quadtree-allocator';
 /** Initial atlas edge length in pixels. Used by the component as the default
  *  uniform value before any allocation has happened. */
 export const ATLAS_SIZE = 1024;
-/** Maximum atlas edge length. The atlas doubles once on first saturation;
- *  any further fills emit a one-shot console.error and fall back to the
- *  flat-colour rendering path. 2048² stays well below `gl.MAX_TEXTURE_SIZE`
- *  (≥ 4096 universally, typically 8192–16384) and uses ~16 MB of GPU memory. */
+/** Maximum atlas edge length. The atlas doubles once when it first runs out
+ *  of room; any further "atlas full" event emits a one-shot console.error and
+ *  the sprite falls back to flat colour. 2048² stays well below
+ *  `gl.MAX_TEXTURE_SIZE` (≥ 4096 universally, typically 8192–16384) and uses
+ *  ~16 MB of GPU memory. */
 export const MAX_ATLAS_SIZE = 2048;
 const SLOT_QUANTUM = 32;
 const MIN_SLOT = 32;
@@ -114,7 +117,7 @@ export class OrdpoolInscriptionAtlas {
   private dirtyTexture = false;
   /** True after we've run out of room at MAX_ATLAS_SIZE. Used to suppress
    *  repeat console.error spam when many sprites can't fit in the same scene. */
-  private saturationLogged = false;
+  private atlasFullLogged = false;
 
   constructor() {
     this.canvas = document.createElement('canvas');
@@ -125,8 +128,9 @@ export class OrdpoolInscriptionAtlas {
   }
 
   /** Current atlas edge length in pixels. Starts at `ATLAS_SIZE`, doubles to
-   *  `MAX_ATLAS_SIZE` on first saturation. The shader's `atlasSize` uniform
-   *  must track this — the component reads it every frame in the run loop. */
+   *  `MAX_ATLAS_SIZE` when the smaller atlas runs out of room. The shader's
+   *  `atlasSize` uniform must track this — the component reads it every frame
+   *  in the run loop. */
   get size(): number {
     return this.currentSize;
   }
@@ -197,20 +201,24 @@ export class OrdpoolInscriptionAtlas {
       existing.sprite = sprite;
       if (existing.status === 'loaded') {
         sprite.setTexture(quadtree.packSlot(existing.node));
+      } else {
+        // status === 'pending' (failed entries are deleted, not parked here).
+        // Match the new-entry path so the rejoiner sees a spinner, not a flat tile.
+        sprite.setLoading();
       }
       return true;
     }
     const slotPx = computeSlotSize(vsize);
     let node = quadtree.insert(this.root, slotPx);
     if (!node && this.currentSize < MAX_ATLAS_SIZE) {
-      // First saturation: double the atlas (1024 → 2048) and try again.
-      // The expansion preserves every existing slot, so already-loaded
-      // textures stay correctly addressed by their existing packed slots.
+      // First time we run out of room: double the atlas (1024 → 2048) and
+      // try again. The expansion preserves every existing slot, so already-
+      // loaded textures stay correctly addressed by their existing packed slots.
       this.expand();
       node = quadtree.insert(this.root, slotPx);
     }
     if (!node) {
-      this.logSaturationOnce(slotPx);
+      this.logAtlasFullOnce(slotPx);
       return false;
     }
     const entry: AtlasEntry = {
@@ -224,10 +232,29 @@ export class OrdpoolInscriptionAtlas {
       abort: () => undefined,
     };
     this.entries.set(txid, entry);
+    // Show the loading spinner immediately. Stays visible through retry
+    // backoffs until either onload (→ setTexture) or final onerror (→ clearTexture).
+    sprite.setLoading();
     this.queueFetch(entry);
     return true;
   }
 
+  /**
+   * True iff at least one entry is still pending (in flight, queued, or
+   * waiting on a retry backoff). The component reads this every frame in
+   * its render loop so the procedural spinner keeps animating while images
+   * are loading — without it the loop would settle and the spinner would
+   * freeze mid-rotation.
+   */
+  hasPendingFetches(): boolean {
+    for (const entry of this.entries.values()) {
+      if (entry.status === 'pending') {
+        return true;
+      }
+    }
+    return false;
+  }
+
   releaseSlot(txid: string): void {
     const entry = this.entries.get(txid);
     if (!entry) {
@@ -248,7 +275,7 @@ export class OrdpoolInscriptionAtlas {
 
   /**
    * Tear down: cancel in-flight fetches, drop the GPU texture, reset the
-   * saturation log gate. Called from the component's `ngOnDestroy`.
+   * atlas-full log gate. Called from the component's `ngOnDestroy`.
    */
   destroy(): void {
     for (const entry of this.entries.values()) {
@@ -258,7 +285,7 @@ export class OrdpoolInscriptionAtlas {
     this.failed.clear();
     this.fetchQueue = [];
     this.inFlight = 0;
-    this.saturationLogged = false;
+    this.atlasFullLogged = false;
     if (this.gl && this.texture) {
       this.gl.deleteTexture(this.texture);
     }
@@ -339,9 +366,9 @@ export class OrdpoolInscriptionAtlas {
    * since the quadtree expansion makes the old root the top-left child of
    * the new root — and recreates the GPU texture.
    *
-   * Called once per atlas instance, on first saturation in `requestSlot`.
-   * Beyond `MAX_ATLAS_SIZE` we don't expand further; further full conditions
-   * are reported by `logSaturationOnce`.
+   * Called once per atlas instance, the first time `requestSlot` runs out
+   * of room. Beyond `MAX_ATLAS_SIZE` we don't expand further; further
+   * "atlas full" conditions are reported by `logAtlasFullOnce`.
    */
   private expand(): void {
     const newSize = this.currentSize * 2;
@@ -360,16 +387,16 @@ export class OrdpoolInscriptionAtlas {
     this.allocateTexture();
   }
 
-  private logSaturationOnce(slotPx: number): void {
-    if (this.saturationLogged) {
+  private logAtlasFullOnce(slotPx: number): void {
+    if (this.atlasFullLogged) {
       return;
     }
-    this.saturationLogged = true;
+    this.atlasFullLogged = true;
     // eslint-disable-next-line no-console
     console.error(
-      `[ordpool-atlas] saturated at ${this.currentSize}×${this.currentSize}px ` +
+      `[ordpool-atlas] atlas full at ${this.currentSize}×${this.currentSize}px ` +
       `(${this.entries.size} slots in flight); refusing slot of ${slotPx}px. ` +
-      `Sprite will fall back to flat colour. Subsequent saturations are silent.`
+      `Sprite will fall back to flat colour. Subsequent atlas-full events are silent.`
     );
   }
 

frontend/src/app/components/block-overview-graph/_ordpool/ordpool-quadtree-allocator.spec.ts

@@ -123,12 +123,12 @@ describe('ordpool-quadtree-allocator', () => {
       expect(root.full).toBe(true);
     });
 
-    it('skips fully-saturated subtrees on subsequent inserts', () => {
+    it('skips fully-allocated subtrees on subsequent inserts', () => {
       const root = createRoot(ATLAS);
       const half = ATLAS / 2;
       const quarter = ATLAS / 4;
 
-      // Saturate the first quadrant with quarter-size slots.
+      // Fill the first quadrant with quarter-size slots.
       insert(root, quarter);
       insert(root, quarter);
       insert(root, quarter);
@@ -139,7 +139,7 @@ describe('ordpool-quadtree-allocator', () => {
       expect(firstQuadrant.full).toBe(true);
       expect(root.full).toBe(false);
 
-      // Next half-size insert must skip the saturated first quadrant
+      // Next half-size insert must skip the now-full first quadrant
       // and land in the next available quadrant (top-right at half,0).
       const next = insert(root, half)!;
       expect(next.x).toBe(half);
@@ -186,12 +186,12 @@ describe('ordpool-quadtree-allocator', () => {
       const half = ATLAS / 2;
       const quarter = ATLAS / 4;
 
-      // Saturate the first quadrant with quarter-size slots.
+      // Fill the first quadrant with quarter-size slots.
       const q1 = insert(root, quarter)!;
       insert(root, quarter);
       insert(root, quarter);
       insert(root, quarter);
-      // Saturate the rest of the atlas with half-size slots.
+      // Fill the rest of the atlas with half-size slots.
       insert(root, half);
       insert(root, half);
       insert(root, half);
@@ -314,7 +314,7 @@ describe('ordpool-quadtree-allocator', () => {
 
     it('makes ~3/4 of the new atlas available for fresh allocations', () => {
       const root = createRoot(1024);
-      // Saturate the original 1024² with 512² slots (4 slots = full)
+      // Fill the original 1024² with 512² slots (4 slots = full)
       insert(root, 512);
       insert(root, 512);
       insert(root, 512);

frontend/src/app/components/block-overview-graph/_ordpool/ordpool-quadtree-allocator.ts

@@ -7,12 +7,12 @@
  * # Layout
  *
  * The atlas is a square of `size` pixels (currently 1024, expandable to 2048
- * on first saturation). Allocation requests are power-of-two slot sizes
- * (32, 64, 128, 256, 512). Free space is tracked as a tree of nodes; when a
- * request lands deeper than the current subdivision, the parent node is
- * "budded" into 4 equal quadrants and recursion continues into them. The
- * `full` flag propagates upward so we can short-circuit search through
- * saturated subtrees.
+ * when the smaller atlas runs out of room). Allocation requests are
+ * power-of-two slot sizes (32, 64, 128, 256, 512). Free space is tracked as
+ * a tree of nodes; when a request lands deeper than the current
+ * subdivision, the parent node is "budded" into 4 equal quadrants and
+ * recursion continues into them. The `full` flag propagates upward so we
+ * can short-circuit search through fully-allocated subtrees.
  *
  * # Coordinate convention
  *
@@ -63,7 +63,7 @@ export interface QuadNode {
   budded: boolean;
   /** True when the node holds an allocation (only meaningful on leaves). */
   filled: boolean;
-  /** Saturation flag — true when this subtree has zero free leaves. Used to short-circuit insert(). */
+  /** True when this subtree has zero free leaves. Used to short-circuit insert(). */
   full: boolean;
   /** Four equal-size sub-quadrants (top-left, top-right, bottom-left, bottom-right) when budded. */
   children: QuadNode[] | null;

frontend/src/app/components/block-overview-graph/_ordpool/ordpool-shaders.ts

@@ -13,10 +13,14 @@
     coordinate is flipped to match the un-flipped texImage2D upload of a
     canvas2d (which has top-left origin, while WebGL textures default to
     bottom-left).
-  - The fragment shader has a two-way branch: sample the atlas when
-    `vIsTexture > 0.5`, fall back to the flat colour otherwise. The atlas
-    sample is composited over the colour using the texture's own alpha,
-    so transparent pixels in the inscription show the underlying tx tint.
+  - The fragment shader has a tristate branch on `vIsTexture`:
+      `> 1.5` — sample the atlas. The texture is composited over the flat
+        colour using the image's own alpha, so transparent pixels in the
+        inscription show the underlying tx tint.
+      `> 0.5` — render a procedural rotating-arc spinner over the flat
+        colour, driven by the existing `now` uniform. No texture asset
+        required; arc + ring math runs in ~10 GPU instructions per pixel.
+      `else`  — flat colour fallback.
 
   Atlas size and slot quantum match `OrdpoolInscriptionAtlas` (1024 px /
   32 px). The numeric constants in the shader match `packSlot()`'s
@@ -27,6 +31,7 @@ export const ordpoolVertexShaderSrc = `
 varying lowp vec4 vColor;
 varying lowp float vIsTexture;
 varying mediump vec2 vCoord;
+varying mediump vec2 vCorner;
 
 attribute vec4 offset;
 attribute vec4 posX;
@@ -70,6 +75,9 @@ void main() {
   vColor = vec4(red, green, blue, alpha);
 
   vIsTexture = offset.z;
+  // Slot-local UV. Interpolates linearly to (0..1, 0..1) across the quad,
+  // used by the loading-spinner branch in the fragment shader.
+  vCorner = corner;
   float spriteX = mod(offset.w, 512.0) * 32.0;
   float spriteY = mod(floor(offset.w / 512.0), 512.0) * 32.0;
   float pxSize = floor(offset.w / 262144.0) * 32.0;
@@ -84,17 +92,41 @@ precision mediump float;
 varying lowp vec4 vColor;
 varying lowp float vIsTexture;
 varying mediump vec2 vCoord;
+varying mediump vec2 vCorner;
 
 uniform sampler2D uSampler;
+uniform float now;
+
+// Procedural rotating-arc spinner drawn in slot-local UV space (vCorner).
+// Returns a [0..1] intensity; 1 = full white sweep highlight, 0 = leave the
+// underlying color alone. Width and rotation speed are tuned for visibility
+// at small (32–64 px) slot sizes without dominating large slots.
+float ordpoolSpinnerIntensity(vec2 vc, float t) {
+  vec2 p = vc - 0.5;
+  float dist = length(p);
+  // Annulus between 0.30 and 0.45 of the slot, anti-aliased on both edges.
+  float ring = smoothstep(0.45, 0.42, dist) * (1.0 - smoothstep(0.30, 0.33, dist));
+  // Rotating sweep: bright at the leading edge of an arc, fading away
+  // around the rest of the circle. now is in ms, 0.003 ≈ one rev / 2 s.
+  float angle = atan(p.y, p.x);
+  float rotation = t * 0.003;
+  float arc = mod(angle + rotation, 6.283185);
+  float sweep = smoothstep(2.5, 0.0, arc);
+  return ring * sweep;
+}
 
 void main() {
-  if (vIsTexture > 0.5) {
+  vec4 base = vColor;
+  if (vIsTexture > 1.5) {
     vec4 tex = texture2D(uSampler, vCoord);
-    gl_FragColor.rgb = tex.rgb * tex.a + vColor.rgb * (1.0 - tex.a);
-    gl_FragColor.a = vColor.a;
-  } else {
-    gl_FragColor = vColor;
+    base.rgb = tex.rgb * tex.a + vColor.rgb * (1.0 - tex.a);
+    base.a = vColor.a;
+  } else if (vIsTexture > 0.5) {
+    float lit = ordpoolSpinnerIntensity(vCorner, now);
+    base.rgb = mix(vColor.rgb, vec3(1.0), lit * 0.85);
+    base.a = vColor.a;
   }
+  gl_FragColor = base;
   gl_FragColor.rgb *= gl_FragColor.a;
 }
 `;

frontend/src/app/components/block-overview-graph/block-overview-graph.component.ts

@@ -83,7 +83,7 @@ export class BlockOverviewGraphComponent implements AfterViewInit, OnDestroy, On
   // HACK -- Ordpool artifact image previews: atlas owns the inscription/stamp/atomical texture.
   ordpoolAtlas: OrdpoolInscriptionAtlas;
   // HACK -- Ordpool: cached atlasSize uniform location. Pushed every frame
-  // because the atlas can expand at runtime (1024 → 2048 on first saturation).
+  // because the atlas can expand at runtime (1024 → 2048 when it first runs out of room).
   ordpoolAtlasSizeUniform: WebGLUniformLocation | null = null;
   running: boolean;
   scene: BlockScene;
@@ -544,7 +544,13 @@ export class BlockOverviewGraphComponent implements AfterViewInit, OnDestroy, On
     }
 
     /* LOOP */
-    if (this.running && this.scene && now <= (this.scene.animateUntil + 500)) {
+    // HACK -- Ordpool artifact image previews: the procedural loading spinner
+    // is driven by the `now` uniform, so the render loop must keep firing
+    // while any fetch is in flight. Without this the loop would settle to
+    // the 1s heartbeat as soon as scene animation ended, freezing the spinner.
+    const stillAnimating = this.scene && now <= (this.scene.animateUntil + 500);
+    const stillLoading = this.ordpoolAtlas?.hasPendingFetches() === true;
+    if (this.running && (stillAnimating || stillLoading)) {
       this.doRun();
     } else {
       clearTimeout(this.animationHeartBeat);