prts-terrarchive 0.2.0

package/ui/rhine/original/decryption.ts

@@ -0,0 +1,185 @@
+// Measured against the local reference at 25 fps. Times here are ORIGINAL video
+// seconds, unlike the camera's historical (original minus five) time convention.
+export const DECRYPTION_START = 34.12;
+export const DECRYPTION_END = 39.56;
+const INTERACTIVE_RATE = 1.5;
+const clamp = (value: number) => Math.max(0, Math.min(1, value));
+const smooth = (value: number) => {
+  const x = clamp(value);
+  return x * x * x * (10 + x * (-15 + x * 6));
+};
+
+type Knot = readonly [number, number];
+// Monotone cubic Hermite interpolation preserves the measured easing without
+// overshoot or velocity jumps at a frame sample. End velocities are zero.
+export function sampleCurve(knots: readonly Knot[], time: number) {
+  if (time <= knots[0][0]) return knots[0][1];
+  if (time >= knots[knots.length - 1][0]) return knots[knots.length - 1][1];
+  const secant = (i: number) =>
+    (knots[i + 1][1] - knots[i][1]) / (knots[i + 1][0] - knots[i][0]);
+  const slope = (i: number) => {
+    if (i === 0 || i === knots.length - 1) return 0;
+    const a = secant(i - 1),
+      b = secant(i);
+    if (a * b <= 0) return 0;
+    const left = knots[i][0] - knots[i - 1][0],
+      right = knots[i + 1][0] - knots[i][0];
+    const w1 = 2 * right + left,
+      w2 = right + 2 * left;
+    return (w1 + w2) / (w1 / a + w2 / b);
+  };
+  let i = 0;
+  while (time > knots[i + 1][0]) i++;
+  const span = knots[i + 1][0] - knots[i][0],
+    t = (time - knots[i][0]) / span,
+    t2 = t * t,
+    t3 = t2 * t;
+  return (
+    (2 * t3 - 3 * t2 + 1) * knots[i][1] +
+    (t3 - 2 * t2 + t) * span * slope(i) +
+    (-2 * t3 + 3 * t2) * knots[i + 1][1] +
+    (t3 - t2) * span * slope(i + 1)
+  );
+}
+
+const GROW: readonly Knot[] = [
+  [34.24, 0],
+  [34.4, 0.19],
+  [34.64, 0.57],
+  [34.96, 0.79],
+  [35.28, 0.92],
+  [35.6, 0.973],
+  [36.04, 1],
+];
+// The clearing front starts when the line finishes retracting. At 39.0 s
+// the upper half is already readable; height-dependent roughness moves with it.
+const REVEAL: readonly Knot[] = [
+  [38.84, 0],
+  [38.92, 0.28],
+  [39.0, 0.51],
+  [39.16, 0.74],
+  [39.32, 0.94],
+  [39.56, 1],
+];
+const RETRACT: readonly Knot[] = [
+  [37.72, 1],
+  [37.88, 0.72],
+  [38.0, 0.38],
+  [38.12, 0.22],
+  [38.24, 0.14],
+  [38.4, 0.075],
+  [38.64, 0.024],
+  [38.84, 0],
+];
+
+// Endpoints measured on the face at 37 seconds. Every moving endpoint is on
+// this ONE diagonal in model space; projection carries it with the camera.
+export const SCAN_FROM = [-1.6, 0.5] as const;
+export const SCAN_TO = [1.98, 3.24] as const;
+export const SCAN_CORNERS = [
+  [-1.88, 3.2],
+  [2.14, 3.36],
+  [-1.77, 0.36],
+  [2.17, 0.65],
+] as const;
+
+export function decryptionFrame(time: number) {
+  const grow = sampleCurve(GROW, time);
+  const remaining = sampleCurve(RETRACT, time);
+  const intervals: [number, number][] = [];
+  if (time >= 34.24 && time < 36.04 && grow > 0)
+    intervals.push([0, grow * 0.5], [1 - grow * 0.5, 1]);
+  else if (time >= 36.04 && time < 38.84)
+    intervals.push([0.5 - remaining * 0.5, 0.5 + remaining * 0.5]);
+  const markers =
+    smooth((time - 34.2) / 0.12) * (1 - smooth((time - 37.76) / 0.56));
+  return {
+    time,
+    intervals,
+    markers,
+    point: smooth((time - 38.58) / 0.2) * (1 - smooth((time - 39.08) / 0.22)),
+    label: smooth((time - 34.32) / 0.36) * (1 - smooth((time - 37.68) / 0.24)),
+    labelValue: smooth((time - 35.64) / 0.56),
+    clarity: sampleCurve(REVEAL, time),
+    phase:
+      time < 34.24
+        ? "waiting"
+        : time < 36.04
+          ? "joining"
+          : time < 37.72
+            ? "connected"
+            : time < 38.84
+              ? "retracting"
+              : time < DECRYPTION_END
+                ? "revealing"
+                : "clear",
+  };
+}
+export type DecryptionFrame = ReturnType<typeof decryptionFrame>;
+
+export class DecryptionController {
+  clarity = 0;
+  private active = false;
+  private elapsed: number | null = null;
+  frame: DecryptionFrame = decryptionFrame(-1);
+
+  enter(alreadyClear = false) {
+    if (this.active) return;
+    this.active = true;
+    this.elapsed = alreadyClear
+      ? (DECRYPTION_END - DECRYPTION_START) / INTERACTIVE_RATE
+      : null;
+    if (alreadyClear) this.finish();
+  }
+  leave() {
+    this.active = false;
+    this.elapsed = null;
+    this.frame = decryptionFrame(-1);
+  }
+  select(clarity = 0) {
+    this.leave();
+    this.clarity = clarity;
+  }
+  finish() {
+    this.elapsed = (DECRYPTION_END - DECRYPTION_START) / INTERACTIVE_RATE;
+    this.clarity = 1;
+    this.frame = decryptionFrame(DECRYPTION_END);
+  }
+  update(dt: number, ready: boolean, reduced: boolean, referenceTime?: number) {
+    if (referenceTime !== undefined) {
+      this.frame = decryptionFrame(referenceTime);
+      this.clarity = this.frame.clarity;
+      return;
+    }
+    if (!this.active) {
+      this.clarity = reduced
+        ? 0
+        : this.clarity * Math.exp(-Math.max(0, dt) * 9);
+      if (this.clarity < 0.0001) this.clarity = 0;
+      this.frame = decryptionFrame(-1);
+      return;
+    }
+    if (reduced) {
+      this.finish();
+      return;
+    }
+    if (this.elapsed === null && ready) this.elapsed = 0;
+    else if (this.elapsed !== null)
+      this.elapsed = Math.min(
+        this.elapsed + Math.max(0, dt),
+        (DECRYPTION_END - DECRYPTION_START) / INTERACTIVE_RATE,
+      );
+    if (this.elapsed !== null) {
+      this.frame = decryptionFrame(
+        DECRYPTION_START + this.elapsed * INTERACTIVE_RATE,
+      );
+      // Re-entry during refrosting starts from the displayed material state.
+      this.clarity =
+        this.frame.clarity > this.clarity
+          ? this.frame.clarity
+          : this.frame.phase === "clear"
+            ? 1
+            : this.clarity * Math.exp(-Math.max(0, dt) * 9);
+    }
+  }
+}

package/ui/rhine/original/detail-signature.ts

@@ -0,0 +1,18 @@
+import type * as THREE from "three";
+
+/** Triangle order and authored front normals bind the bake to this exact mesh.
+ * Independent of attribute compaction/index renumbering in the interior bake.
+ */
+export function detailSignature(geometry: THREE.BufferGeometry) {
+  if (!geometry.index || !geometry.attributes.position || !geometry.attributes.normal) return "";
+  let hash = 2166136261;
+  const buffer = new ArrayBuffer(4), value = new DataView(buffer);
+  for (let i = 0; i < geometry.index.count; i++) {
+    const index = geometry.index.getX(i);
+    for (const name of ["position", "normal"]) for (let c = 0; c < 3; c++) {
+      value.setFloat32(0, geometry.attributes[name].getComponent(index, c), true);
+      for (let b = 0; b < 4; b++) hash = Math.imul(hash ^ value.getUint8(b), 16777619);
+    }
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}

package/ui/rhine/original/glass-reveal.ts

@@ -0,0 +1,45 @@
+// A feathered clearing front travels from the top to the bottom of the cover.
+// Progress endpoints are wholly frosted / wholly clear, including the rim.
+const FEATHER = 0.12;
+export const FROSTED_ROUGHNESS = 0.42;
+export const CLEAR_ROUGHNESS = 0.025;
+const FROST_SPAN = 0.016;
+
+// Three's default mip rule grows blur relative to an object as the viewport
+// shrinks. Bound the frosted footprint to 1.6% of the projected cover height.
+export function frostedTransmissionLod(
+  panelPixels: number,
+  textureWidth: number,
+  roughness: number,
+  quality = 1,
+  ior = 1.46,
+) {
+  const clamp = (v: number) => Math.max(0, Math.min(1, v));
+  const strength = clamp((roughness - CLEAR_ROUGHNESS) / (FROSTED_ROUGHNESS - CLEAR_ROUGHNESS));
+  const native = Math.log2(textureWidth) * roughness * clamp(ior * 2 - 2);
+  const clearLod = Math.log2(textureWidth) * CLEAR_ROUGHNESS * clamp(ior * 2 - 2);
+  const bounded = Math.log2(Math.max(2 ** clearLod, panelPixels * FROST_SPAN * Math.pow(strength, 1.15)));
+  return native + (Math.min(native, bounded) - native) * quality;
+}
+export const frostedTransmissionGLSL = `
+float archiveTransmissionLod(float roughness, float ior, vec2 samplerSize) {
+  float nativeLod = log2(samplerSize.x) * roughness * clamp(ior * 2.0 - 2.0, 0.0, 1.0);
+  float strength = clamp((roughness - ${CLEAR_ROUGHNESS}) / ${FROSTED_ROUGHNESS - CLEAR_ROUGHNESS}, 0.0, 1.0);
+  float panelPixels = length(vArchiveProjectedAxis * samplerSize);
+  float clearLod = log2(samplerSize.x) * ${CLEAR_ROUGHNESS} * clamp(ior * 2.0 - 2.0, 0.0, 1.0);
+  float boundedLod = log2(max(exp2(clearLod), panelPixels * ${FROST_SPAN} * pow(strength, 1.15)));
+  return mix(nativeLod, min(nativeLod, boundedLod), archiveQuality);
+}`;
+export function glassRevealAtHeight(progress: number, height: number) {
+  const edge = 1 - (1 + 2 * FEATHER) * Math.max(0, Math.min(1, progress));
+  const x = Math.max(
+    0,
+    Math.min(1, (Math.max(0, Math.min(1, height)) - edge) / (2 * FEATHER)),
+  );
+  return x * x * (3 - 2 * x);
+}
+export const glassRevealGLSL = `
+float glassRevealAtHeight(float progress, float height) {
+  float edge = 1.0 - ${1 + 2 * FEATHER} * clamp(progress, 0.0, 1.0);
+  return smoothstep(edge, edge + ${2 * FEATHER}, clamp(height, 0.0, 1.0));
+}`;

package/ui/rhine/original/internal-optics.ts

@@ -0,0 +1,70 @@
+import * as THREE from "three";
+
+const surfaces: Record<
+  string,
+  { color: string; roughness: number; opacity: number; order: number }
+> = {
+  Optical_Glass_Body: {
+    color: "#929894",
+    roughness: 0.38,
+    opacity: 0.27,
+    order: 20,
+  },
+  Optical_Glass_Roof: {
+    color: "#929b94",
+    roughness: 0.34,
+    opacity: 0.42,
+    order: 24,
+  },
+  Optical_Glass_Edge: {
+    color: "#edf0e7",
+    roughness: 0.19,
+    opacity: 0.9,
+    order: 28,
+  },
+  Optical_Bridge_Glass: {
+    color: "#a0aca2",
+    roughness: 0.32,
+    opacity: 0.36,
+    order: 26,
+  },
+};
+
+export function configureInternalOptics(
+  name: string,
+  mat: THREE.MeshPhysicalMaterial,
+) {
+  const surface = surfaces[name];
+  if (!surface) return;
+  mat.color.set(surface.color);
+  mat.roughness = surface.roughness;
+  mat.metalness = 0.015;
+  mat.clearcoat = 0.42;
+  mat.clearcoatRoughness = 0.24;
+  mat.opacity = surface.opacity;
+  // Three's outer transmission pass samples its opaque capture and omits other
+  // transmissive meshes. Composite these thin frosted layers into that capture
+  // with explicit alpha blending, after the opaque ribs/substrate. The exterior
+  // cover can then refract the complete interior in both scenes.
+  mat.transmission = 0;
+  mat.transparent = false;
+  mat.blending = THREE.CustomBlending;
+  mat.blendEquation = THREE.AddEquation;
+  mat.blendSrc = THREE.SrcAlphaFactor;
+  mat.blendDst = THREE.OneMinusSrcAlphaFactor;
+  mat.blendSrcAlpha = THREE.OneFactor;
+  mat.blendDstAlpha = THREE.OneMinusSrcAlphaFactor;
+  mat.depthWrite = false;
+  // These are closed volumes; rendering both shell faces doubles their density.
+  mat.side = THREE.FrontSide;
+  mat.userData.opticalOrder = surface.order;
+}
+
+export function internalOpticsFragment(source: string) {
+  // Grazing edges accumulate density while the face stays lightly frosted.
+  return source.replace(
+    "#include <opaque_fragment>",
+    `diffuseColor.a = min(0.86, opacity + 0.42 * pow(1.0 - abs(dot(normal, normalize(vViewPosition))), 3.0));
+     #include <opaque_fragment>`,
+  );
+}

package/ui/rhine/original/label-renderer.ts

@@ -0,0 +1,119 @@
+import * as THREE from 'three';
+import { Pass, FullScreenQuad } from 'three/addons/postprocessing/Pass.js';
+import type { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
+
+export const ARCHIVE_LABEL_LAYER = 1;
+
+/** Save the beauty pass's existing depth before later effects reuse its buffer. */
+class LabelDepthCapture extends Pass {
+  readonly target = new THREE.WebGLRenderTarget(1, 1, {
+    depthBuffer: false, stencilBuffer: false,
+    minFilter: THREE.NearestFilter, magFilter: THREE.NearestFilter,
+  });
+  private readonly material = new THREE.ShaderMaterial({
+    uniforms: { sourceDepth: { value: null } },
+    vertexShader: 'varying vec2 vUv; void main(){ vUv = uv; gl_Position = vec4(position.xy, 0., 1.); }',
+    fragmentShader: `uniform sampler2D sourceDepth;
+      varying vec2 vUv;
+      #include <packing>
+      void main(){ gl_FragColor = packDepthToRGBA(texture2D(sourceDepth, vUv).x); }`,
+    depthTest: false, depthWrite: false, blending: THREE.NoBlending,
+  });
+  private readonly quad = new FullScreenQuad(this.material);
+  private disposed = false;
+  constructor() { super(); this.needsSwap = false; this.target.texture.name = 'Archive label occlusion'; }
+  render(renderer: THREE.WebGLRenderer, _write: THREE.WebGLRenderTarget, read: THREE.WebGLRenderTarget) {
+    const previous = renderer.getRenderTarget();
+    this.target.setSize(read.width, read.height);
+    this.material.uniforms.sourceDepth.value = read.depthTexture;
+    try { renderer.setRenderTarget(this.target); this.quad.render(renderer); }
+    finally { renderer.setRenderTarget(previous); }
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true; this.target.dispose(); this.material.dispose(); this.quad.dispose();
+  }
+}
+
+/** Sharp final-resolution print, using scene depth instead of redrawing geometry. */
+export class ArchiveLabelRenderer {
+  readonly capture = new LabelDepthCapture();
+  private readonly uniforms = {
+    archiveSceneDepth: { value: this.capture.target.texture },
+    archiveOutputSize: { value: new THREE.Vector2(1, 1) },
+    archiveDepthSize: { value: new THREE.Vector2(1, 1) },
+    archiveCameraNear: { value: 5 }, archiveCameraFar: { value: 300 },
+  };
+  private active = false;
+  private disposed = false;
+
+  attach(composer: EffectComposer) {
+    // The normal beauty pass already computes these values. Both alternating
+    // targets need an attachment; the capture is one fullscreen GPU copy only.
+    for (const target of [composer.renderTarget1, composer.renderTarget2]) {
+      target.depthTexture = new THREE.DepthTexture(1, 1, THREE.UnsignedIntType);
+    }
+    composer.insertPass(this.capture, 1);
+  }
+  createMaterial(map: THREE.Texture, options: { alignDepthSamples?: boolean } = {}) {
+    const material = new THREE.MeshBasicMaterial({ map, toneMapped: false,
+      transparent: true, depthWrite: false, depthTest: false, fog: false });
+    material.onBeforeCompile = shader => {
+      Object.assign(shader.uniforms, this.uniforms);
+      shader.fragmentShader = `uniform sampler2D archiveSceneDepth;
+        uniform vec2 archiveOutputSize;
+        uniform vec2 archiveDepthSize;
+        uniform float archiveCameraNear;
+        uniform float archiveCameraFar;
+        #include <packing>\n` + shader.fragmentShader;
+      shader.fragmentShader = shader.fragmentShader.replace('#include <clipping_planes_fragment>',
+        `#include <clipping_planes_fragment>
+        float sceneDepth = unpackRGBAToDepth(texture2D(archiveSceneDepth, gl_FragCoord.xy / archiveOutputSize));
+        float sceneDistance = -perspectiveDepthToViewZ(sceneDepth, archiveCameraNear, archiveCameraFar);
+        float printDepth = gl_FragCoord.z;
+        ${options.alignDepthSamples ? `
+        // Compare both planes at the coarse depth texel's center. Otherwise a
+        // slanted sheet intermittently occludes itself on the finer print grid.
+        vec2 depthPixel = floor(gl_FragCoord.xy / archiveOutputSize * archiveDepthSize);
+        vec2 samplePosition = (depthPixel + 0.5) / archiveDepthSize * archiveOutputSize;
+        printDepth += dot(vec2(dFdx(gl_FragCoord.z), dFdy(gl_FragCoord.z)), samplePosition - gl_FragCoord.xy);
+        ` : ''}
+        float printDistance = -perspectiveDepthToViewZ(printDepth, archiveCameraNear, archiveCameraFar);
+        if (printDistance > sceneDistance + 0.006) discard;`);
+    };
+    material.customProgramCacheKey = () => options.alignDepthSamples
+      ? 'archive-print-scene-depth-aligned-v1' : 'archive-print-scene-depth-v1';
+    return material;
+  }
+  prepare(scene: THREE.Scene) {
+    this.active = false;
+    scene.traverseVisible(object => {
+      if (this.active || !(object instanceof THREE.Mesh) || !object.layers.isEnabled(ARCHIVE_LABEL_LAYER)) return;
+      const materials = Array.isArray(object.material) ? object.material : [object.material];
+      this.active = materials.some(material => material.visible && material.opacity > 0);
+    });
+    this.capture.enabled = this.active;
+  }
+  render(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.PerspectiveCamera) {
+    if (this.disposed || !this.active) return;
+    renderer.getDrawingBufferSize(this.uniforms.archiveOutputSize.value);
+    this.uniforms.archiveDepthSize.value.set(this.capture.target.width, this.capture.target.height);
+    this.uniforms.archiveCameraNear.value = camera.near;
+    this.uniforms.archiveCameraFar.value = camera.far;
+    const autoClear = renderer.autoClear, background = scene.background;
+    const override = scene.overrideMaterial, layers = camera.layers.mask;
+    const target = renderer.getRenderTarget(), face = renderer.getActiveCubeFace(), mip = renderer.getActiveMipmapLevel();
+    const shadowAuto = renderer.shadowMap.autoUpdate, shadowUpdate = renderer.shadowMap.needsUpdate;
+    try {
+      renderer.autoClear = false; scene.background = null; scene.overrideMaterial = null;
+      renderer.shadowMap.autoUpdate = false; renderer.shadowMap.needsUpdate = false;
+      renderer.setRenderTarget(null); camera.layers.set(ARCHIVE_LABEL_LAYER);
+      renderer.render(scene, camera);
+    } finally {
+      renderer.autoClear = autoClear; scene.background = background; scene.overrideMaterial = override;
+      camera.layers.mask = layers; renderer.shadowMap.autoUpdate = shadowAuto; renderer.shadowMap.needsUpdate = shadowUpdate;
+      renderer.setRenderTarget(target, face, mip);
+    }
+  }
+  dispose() { if (!this.disposed) { this.disposed = true; this.capture.dispose(); } }
+}

package/ui/rhine/original/label-textures.ts

@@ -0,0 +1,117 @@
+import * as THREE from "three";
+import { ARCHIVE_LABEL_WIDTH, ARCHIVE_LABEL_HEIGHT, archiveLabelKey, paintArchiveLabel, type ArchiveLabel } from "./archive-label";
+import type { RenderPerformanceCapture } from "../temporary-performance";
+
+type Family = "hero-label" | "moving-label" | "shelf-label";
+type Entry = { id: number; texture: THREE.CanvasTexture; refs: number; used: number; prepared: boolean };
+export type LabelPrefetchContext = { plan: number; slot: number; intent?: 'row' | 'lane' | 'pointer' | 'activity' };
+
+/** Immutable prints; active owners and the bounded next-navigation working set share storage. */
+export class ArchiveLabelTextures {
+  private readonly entries = new Map<string, Entry>();
+  private readonly bindings = new Map<THREE.MeshBasicMaterial, Entry>();
+  private candidates = new Set<string>();
+  private readonly evicted = new Map<string, number>();
+  private sequence = 0;
+  private clock = 0;
+  private hits = 0;
+  private misses = 0;
+  private evictions = 0;
+  private disposed = false;
+  constructor(private readonly mark: HTMLImageElement, private readonly anisotropy: number,
+    private readonly probe: () => RenderPerformanceCapture | undefined, private readonly idleLimit = 6) {}
+  private key(content: ArchiveLabel) { return `${archiveLabelKey(content)}:${document.fonts?.status || "loaded"}`; }
+  private get(content: ArchiveLabel, family: Family, use: 'bind' | 'prefetch', context?: LabelPrefetchContext) {
+    if (this.disposed) throw new Error("Archive label cache is disposed");
+    const key = this.key(content);
+    let entry = this.entries.get(key);
+    const hit = Boolean(entry), previousEntry = this.evicted.get(key);
+    if (entry) this.hits++;
+    else {
+      this.misses++;
+      const id = ++this.sequence;
+      const canvas = document.createElement("canvas"); canvas.width = ARCHIVE_LABEL_WIDTH; canvas.height = ARCHIVE_LABEL_HEIGHT;
+      const texture = new THREE.CanvasTexture(canvas);
+      texture.colorSpace = THREE.SRGBColorSpace; texture.anisotropy = this.anisotropy;
+      texture.userData.archivePrint = true; texture.userData.sharedArchiveLabel = true;
+      const created: Entry = { id, texture, refs: 0, used: 0, prepared: false };
+      // Natural draws and explicit preloads both submit the texture. The probe
+      // chains this callback; submission does not imply GPU completion.
+      texture.onUpdate = () => { created.prepared = true; };
+      const paint = () => { paintArchiveLabel(canvas, this.mark, content); texture.needsUpdate = true; };
+      try { const probe = this.probe(); if (probe) probe.texturePaint(texture, family, paint, id); else paint(); }
+      catch (error) { texture.dispose(); throw error; }
+      entry = created; this.entries.set(key, entry);
+    }
+    this.probe()?.observeTexture(entry.texture, family, entry.id);
+    entry.used = ++this.clock;
+    this.probe()?.diagnostic('resourceUpdates', { kind: 'label-cache', family, use, hit, cacheEntry: entry.id,
+      prepared: entry.prepared, candidate: this.candidates.has(key), fontStatus: document.fonts?.status || 'loaded',
+      missReason: hit ? undefined : previousEntry ? 'evicted' : 'not-resident', previousEntry: hit ? undefined : previousEntry,
+      ...context, ...this.stats() });
+    return entry;
+  }
+  /** Protect at most idleLimit candidates; never increase the idle texture budget. */
+  setPrefetchCandidates(contents: readonly ArchiveLabel[]) {
+    if (this.disposed) return;
+    this.candidates = new Set(contents.map(content => this.key(content)).slice(0, this.idleLimit));
+    this.trim();
+  }
+  bind(material: THREE.MeshBasicMaterial, content: ArchiveLabel, family: Family) {
+    const current = this.bindings.get(material);
+    if (current && this.entries.get(this.key(content)) === current) return current.texture;
+    const next = this.get(content, family, 'bind');
+    next.refs++;
+    if (current) { current.refs--; current.used = ++this.clock; }
+    this.bindings.set(material, next); material.map = next.texture; this.trim();
+    return next.texture;
+  }
+  /** Keep the exact visible print when returning, including across font readiness changes. */
+  share(source: THREE.MeshBasicMaterial, target: THREE.MeshBasicMaterial) {
+    const next = this.bindings.get(source); if (!next) return undefined;
+    const current = this.bindings.get(target);
+    this.probe()?.observeTexture(next.texture, 'moving-label', next.id);
+    if (current !== next) {
+      next.refs++; if (current) { current.refs--; current.used = ++this.clock; }
+      next.used = ++this.clock; this.bindings.set(target, next); target.map = next.texture;
+      this.hits++; this.trim();
+      this.probe()?.diagnostic('resourceUpdates', { kind: 'label-cache', family: 'moving-label', use: 'share', hit: true,
+        cacheEntry: next.id, prepared: next.prepared, reason: 'retain-visible-print', ...this.stats() });
+    }
+    return next.texture;
+  }
+  prepare(content: ArchiveLabel, renderer: THREE.WebGLRenderer, context?: LabelPrefetchContext) {
+    const entry = this.get(content, 'hero-label', 'prefetch', context);
+    renderer.initTexture(entry.texture); entry.prepared = true; this.trim();
+    this.probe()?.diagnostic('resourceUpdates', { kind: 'label-prefetch-submitted', cacheEntry: entry.id, ...context });
+  }
+  invalidateResidency() { for (const entry of this.entries.values()) entry.prepared = false; }
+  isPrepared(content: ArchiveLabel) { return this.entries.get(this.key(content))?.prepared === true; }
+  release(material: THREE.MeshBasicMaterial) {
+    const entry = this.bindings.get(material); if (!entry) return;
+    this.bindings.delete(material); entry.refs--; entry.used = ++this.clock; this.trim();
+  }
+  private trim() {
+    const idle = [...this.entries.entries()].filter(([, entry]) => entry.refs === 0).sort((a, b) =>
+      Number(this.candidates.has(a[0])) - Number(this.candidates.has(b[0])) || a[1].used - b[1].used);
+    for (const [key, entry] of idle.slice(0, Math.max(0, idle.length - this.idleLimit))) {
+      this.entries.delete(key); entry.texture.dispose(); this.evictions++;
+      this.evicted.delete(key); this.evicted.set(key, entry.id);
+      if (this.evicted.size > 32) this.evicted.delete(this.evicted.keys().next().value!);
+      this.probe()?.diagnostic('resourceUpdates', { kind: 'label-cache-evict', cacheEntry: entry.id,
+        reason: this.candidates.has(key) ? 'candidate-budget' : 'idle-budget', prepared: entry.prepared, ...this.stats() });
+    }
+  }
+  stats() {
+    let active = 0, protectedIdle = 0;
+    for (const [key, entry] of this.entries) { if (entry.refs) active++; else if (this.candidates.has(key)) protectedIdle++; }
+    return { textures: this.entries.size, active, idle: this.entries.size - active, references: this.bindings.size,
+      idleLimit: this.idleLimit, protectedIdle, candidates: this.candidates.size, hits: this.hits, misses: this.misses, evictions: this.evictions,
+      rgba8BaseBytes: this.entries.size * ARCHIVE_LABEL_WIDTH * ARCHIVE_LABEL_HEIGHT * 4 };
+  }
+  dispose() {
+    if (this.disposed) return; this.disposed = true;
+    for (const entry of this.entries.values()) entry.texture.dispose();
+    this.entries.clear(); this.bindings.clear(); this.candidates.clear(); this.evicted.clear();
+  }
+}