@wildshard/shard-format 0.0.1 → 0.4.6

package/src/format/terrain.ts

@@ -0,0 +1,241 @@
+import * as v from 'valibot';
+import { CELL_ABOVE, CELL_BELOW } from './contentBounds.ts';
+import { WaterBodySchema,WaterBodyIdSchema,waterBodiesOrdered } from './water.ts';
+import { isJsonData } from './json.ts';
+import { ScalarChannelSchema,ScalarLatticeSchema } from './scalarChannel.ts';
+
+const ref = v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/u));
+const address = v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(7));
+/**
+ * The terrain tiles' shadow flags: `cast` lets an L0 tile inside the client's shadow disc cast, `receive` lets every tile
+ * receive. Absent: both on (the default every shard drew with before the row).
+ */
+const shadow = v.strictObject({ cast: v.boolean(), receive: v.boolean() });
+/** How far (m) the viewer moves before the client's tile residency re-centres; absent: 5 m (the data client's `FOLLOW`). */
+const follow = v.pipe(v.number(), v.finite(), v.minValue(1), v.maxValue(62.5));
+/** A separate original lattice used only for native placement queries; it never installs collision. */
+const sampling = v.strictObject({ law: v.literal('bilinear'), file: ref,
+  normalEpsilon: v.pipe(v.number(), v.finite(), v.minValue(0.001), v.maxValue(4)),
+  datum: v.pipe(v.number(), v.finite(), v.minValue(-CELL_BELOW), v.maxValue(CELL_ABOVE)) });
+/**
+ * The tiles' draw order among the opaque surfaces (three's renderOrder): a lower order draws first, so it decides which
+ * surface wins where two lie at the same depth (a ground drawn before a far horizon ring). Absent: -1, the ground first
+ * (game/shardfile/clientViews.ts `TERRAIN_ORDER`).
+ */
+const order = v.pipe(v.number(), v.integer(), v.minValue(-100), v.maxValue(100));
+/** The terrain's render files address the ordinary tile grid; the collider file is a separate critical sim root. */
+const renderedTerrain: v.GenericSchema<RenderedTerrainRowsInput, RenderedTerrainRows> = v.pipe(v.strictObject({ version: v.literal(1), form: v.exactOptional(v.literal('render')), family: v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u)), collider: ref,
+  tiles: v.pipe(v.array(v.strictObject({ lod: v.picklist([0, 1]), x: address, z: address, file: ref })), v.length(80)),
+  shadow: v.exactOptional(shadow), follow: v.exactOptional(follow), sampling: v.exactOptional(sampling), order: v.exactOptional(order) }),
+v.check((terrain) => new Set(terrain.tiles.map((tile) => `${tile.lod}/${tile.x}/${tile.z}`)).size === 80 && terrain.tiles.every((tile) => tile.x < (tile.lod === 0 ? 8 : 4) && tile.z < (tile.lod === 0 ? 8 : 4)), 'complete terrain tile grids'));
+const queryTerrain: v.GenericSchema<QueryTerrainRowsInput, QueryTerrainRows> & { readonly pipe: readonly [unknown, v.TransformAction<Omit<QueryTerrainRows, 'collider'> & { collider?: string }, QueryTerrainRows>] } = v.pipe(v.strictObject({ version: v.literal(1), form: v.literal('query'),
+  family: v.optional(v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u)), 'toon'), collider: v.exactOptional(ref),
+  tiles: v.pipe(v.array(v.strictObject({ lod: v.picklist([0, 1]), x: address, z: address, file: ref })), v.length(0)),
+  sampling, shadow: v.exactOptional(shadow), follow: v.exactOptional(follow), order: v.exactOptional(order) }),
+v.transform((row) => ({ ...row, collider: row.collider ?? row.sampling.file })));
+/** Rendered terrain retains its original defaults; query terrain has no render tiles and requires a runtime terrain owner.
+ * An omitted query collider reference derives from sampling.file; this does not allocate collision. */
+export const TerrainSchema: v.UnionSchema<[typeof renderedTerrain, typeof queryTerrain], undefined> = v.union([renderedTerrain, queryTerrain]);
+/** A validated terrain section, containing no landscape closures. */
+
+
+const metre = v.pipe(v.number(), v.finite(), v.minValue(-1000), v.maxValue(1000));
+const groundPoint = v.tuple([metre, metre]);
+const seed = v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(0xffffffff));
+/**
+ * A hybrid shard's declared ground (G4): its baked terrain by key and seed, the trails, pads and pond its terrain metadata
+ * reads (grading masks, grass and forest clearings), its rest water level and render datum. Ordinary bodies use the
+ * shardfile's water grammar; a ground-only basin borrows this field's mask and live water level. The game builds the
+ * manifest ground from these rows (`declaredGround`); no shard code. Generated from the shard's own layout.
+ */
+export const GroundRowsSchema: v.GenericSchema<GroundRowsInput, GroundRows> = v.pipe(v.unknown(),v.check(isJsonData,'Ground rows require plain JSON'),v.strictObject({
+  /** the baked terrain field by key, or a flat placement datum at `flat` (a structure-first world's ground) */
+  terrain: v.union([v.strictObject({ key: v.pipe(v.string(), v.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/u)), seed }), v.strictObject({ flat: metre, seed })]),
+  trails: v.pipe(v.array(v.pipe(v.array(groundPoint), v.minLength(2), v.maxLength(256))), v.maxLength(64)),
+  cabinSites: v.pipe(v.array(v.strictObject({ x: metre, z: metre, rot: v.pipe(v.number(), v.finite()) })), v.maxLength(64)),
+  pond: v.exactOptional(v.strictObject({ x: metre, z: metre, r: v.pipe(metre, v.minValue(0)) })),
+  water: metre,
+  datum: v.exactOptional(v.pipe(v.number(), v.finite(), v.minValue(-CELL_BELOW), v.maxValue(CELL_ABOVE))),
+  /** A sampled pond has the original clamped native lattice, never an implied cell-edge clip. */
+  mask: v.exactOptional(ScalarLatticeSchema),
+  bodies: v.pipe(v.array(v.union([WaterBodySchema,v.strictObject({ id: WaterBodyIdSchema,kind: v.literal('terrain-basin') })])),
+    v.maxLength(64),v.check(rows => waterBodiesOrdered(rows),'unique water ids and sea last')),
+  /** the shard's own runtime grades its paths (the plugin's `paths`), as the manifest ground declares */
+  paths: v.exactOptional(v.literal('plugin')),
+}),v.check(row => row.pond === undefined || row.mask === undefined,'Geometric pond and sampled mask are exclusive'));
+
+
+const finite = v.pipe(v.number(), v.finite());
+/** A declared forest's exact candidate answers (the manifest's `forestQueries`, G4): every jittered sample's density, scale
+ *  and species mix, read from a generated geography file's `forest` rows (its other rows are not read). */
+const forestCandidate = v.strictObject({ x: finite,z: finite,density: finite,
+  scale: finite,species: v.record(v.pipe(v.string(),v.minLength(1),v.maxLength(64)),finite) });
+export const ForestRowsSchema: v.GenericSchema<ForestRowsInput, ForestRows> = v.union([
+  v.object({ forest: v.pipe(v.array(forestCandidate),v.maxLength(65536)),density: v.exactOptional(v.never()) }),
+  v.pipe(v.object({ forest: v.pipe(v.array(v.omit(forestCandidate,['density'])),v.maxLength(65536)),density: ScalarChannelSchema }),
+    v.check(rows => rows.density.type === 'f64' && rows.density.count === rows.forest.length,'Forest density requires one f64 per candidate')),
+]);
+/** A declared clip (the manifest's `pondClip`, G4): the pond surface's grid (`segs` cells a side of `cell` m from its corner
+ *  `x0`, `z0`) and the row-major indices of the cells another water body draws instead. */
+export const PondClipSchema: v.GenericSchema<PondClipRowsInput, PondClipRows> = v.strictObject({ x0: finite, z0: finite, cell: v.pipe(finite, v.minValue(Number.MIN_VALUE)),
+  segs: v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(1024)), cells: v.pipe(v.array(v.pipe(v.number(), v.integer(), v.minValue(0))), v.maxLength(65536)) });
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type RenderedTerrainRowsInput = RenderedTerrainRows;
+interface RenderedTerrainRowsFields {
+    version: 1;
+    form?: 'render';
+    family: string;
+    collider: string;
+    tiles: ({
+        lod: 0 | 1;
+        x: number;
+        z: number;
+        file: string;
+    })[];
+    shadow?: {
+        cast: boolean;
+        receive: boolean;
+    };
+    follow?: number;
+    sampling?: {
+        law: 'bilinear';
+        file: string;
+        normalEpsilon: number;
+        datum: number;
+    };
+    order?: number;
+}
+export type RenderedTerrainRows = { [Key in keyof RenderedTerrainRowsFields]: RenderedTerrainRowsFields[Key] };
+interface QueryTerrainRowsInputFields {
+    version: 1;
+    form: 'query';
+    family?: string | undefined;
+    collider?: string;
+    tiles: ({
+        lod: 0 | 1;
+        x: number;
+        z: number;
+        file: string;
+    })[];
+    sampling: {
+        law: 'bilinear';
+        file: string;
+        normalEpsilon: number;
+        datum: number;
+    };
+    shadow?: {
+        cast: boolean;
+        receive: boolean;
+    };
+    follow?: number;
+    order?: number;
+}
+export type QueryTerrainRowsInput = { [Key in keyof QueryTerrainRowsInputFields]: QueryTerrainRowsInputFields[Key] };
+export type QueryTerrainRows = Omit<{
+    version: 1;
+    form: 'query';
+    family: string;
+    collider?: string;
+    tiles: ({
+        lod: 0 | 1;
+        x: number;
+        z: number;
+        file: string;
+    })[];
+    sampling: {
+        law: 'bilinear';
+        file: string;
+        normalEpsilon: number;
+        datum: number;
+    };
+    shadow?: {
+        cast: boolean;
+        receive: boolean;
+    };
+    follow?: number;
+    order?: number;
+}, 'collider'> & {
+    collider: string;
+};
+export type ShardTerrain = (RenderedTerrainRows) | (QueryTerrainRows);
+export type GroundRowsInput = unknown;
+interface GroundRowsFields {
+    terrain: ({
+        key: string;
+        seed: number;
+    }) | ({
+        flat: number;
+        seed: number;
+    });
+    trails: (([
+        number,
+        number
+    ])[])[];
+    cabinSites: ({
+        x: number;
+        z: number;
+        rot: number;
+    })[];
+    pond?: {
+        x: number;
+        z: number;
+        r: number;
+    };
+    water: number;
+    datum?: number;
+    mask?: v.InferOutput<typeof ScalarLatticeSchema>;
+    bodies: ((v.InferOutput<typeof WaterBodySchema>) | ({
+        id: v.InferOutput<typeof WaterBodyIdSchema>;
+        kind: 'terrain-basin';
+    }))[];
+    paths?: 'plugin';
+}
+export type GroundRows = { [Key in keyof GroundRowsFields]: GroundRowsFields[Key] };
+export type ForestRowsInput = ({
+    forest: ({
+        x: number;
+        z: number;
+        density: number;
+        scale: number;
+        species: Record<string, number>;
+    })[];
+    density?: never;
+}) | ({
+    forest: (Omit<{
+        x: number;
+        z: number;
+        density: number;
+        scale: number;
+        species: Record<string, number>;
+    }, 'density'>)[];
+    density: v.InferInput<typeof ScalarChannelSchema>;
+});
+export type ForestRows = ({
+    forest: ({
+        x: number;
+        z: number;
+        density: number;
+        scale: number;
+        species: Record<string, number>;
+    })[];
+    density?: never;
+}) | ({
+    forest: (Omit<{
+        x: number;
+        z: number;
+        density: number;
+        scale: number;
+        species: Record<string, number>;
+    }, 'density'>)[];
+    density: v.InferOutput<typeof ScalarChannelSchema>;
+});
+export type PondClipRowsInput = PondClipRows;
+interface PondClipRowsFields {
+    x0: number;
+    z0: number;
+    cell: number;
+    segs: number;
+    cells: (number)[];
+}
+export type PondClipRows = { [Key in keyof PondClipRowsFields]: PondClipRowsFields[Key] };

package/src/format/terrainTileBytes.ts

@@ -0,0 +1,104 @@
+import type { BakedGrid } from './bakedTerrainBytes.ts';
+import { isJsonData } from './json.ts';
+import { CELL_ABOVE, CELL_BELOW, CHUNK_HALF } from './contentBounds.ts';
+import { bakedSamplers, type BakedTerrainSamplers } from './bakedTerrainSampling.ts';
+
+const MAGIC = 0x31545457, HEADER = 32;
+/** Baked row-major heights in a shard-local square; optional linear RGB values describe the rendered vertices. */
+export interface TerrainTileData {
+  resolution: number; x: number; z: number; size: number;
+  heights: Float32Array; colours?: Float32Array;
+  /** Original normalized-on-query four-channel byte weights; absent preserves the existing wire bytes. */
+  splat?: Uint8Array;
+}
+function check(data: TerrainTileData): void {
+  const { resolution: r, x, z, size, heights, colours, splat } = data;
+  if (!Number.isInteger(r) || r < 2 || r > 257 || ![x, z, size].every(Number.isFinite) || size <= 0 || x < -CHUNK_HALF || z < -CHUNK_HALF || x + size > CHUNK_HALF || z + size > CHUNK_HALF || heights.length !== r * r || (colours !== undefined && colours.length !== r * r * 3) || (splat !== undefined && splat.length !== r * r * 4)) throw new Error('Invalid terrain dimensions');
+  // js-heap H9: plain loops (a per-sample callback boxed every float: ~3 MiB a boot)
+  for (let i = 0; i < heights.length; i++) { const h = heights[i] ?? Number.NaN; if (!(h >= -CELL_BELOW && h <= CELL_ABOVE)) throw new Error('Invalid terrain samples'); }
+  if (colours !== undefined) for (let i = 0; i < colours.length; i++) { const c = colours[i] ?? Number.NaN; if (!(c >= 0 && c <= 1)) throw new Error('Invalid terrain samples'); }
+}
+/** Recognise the terrain wire format before its full bounded decoder checks the payload. */
+export function isTerrainTileData(bytes: Uint8Array): boolean {
+  return bytes.length >= 4 && new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0, true) === MAGIC;
+}
+/** Encode version-one terrain using explicit little-endian floats, without host paths or timestamps. */
+export function encodeTerrainTile(data: TerrainTileData): Uint8Array {
+  check(data);
+  const stride = 4 + (data.colours === undefined ? 0 : 12) + (data.splat === undefined ? 0 : 4);
+  const bytes = new Uint8Array(HEADER + data.heights.length * stride);
+  const view = new DataView(bytes.buffer);
+  view.setUint32(0, MAGIC, true); view.setUint16(4, 1, true); view.setUint16(6, data.resolution, true);
+  view.setUint32(8, (data.colours === undefined ? 0 : 1) | (data.splat === undefined ? 0 : 2), true);
+  view.setFloat32(12, data.x, true); view.setFloat32(16, data.z, true); view.setFloat32(20, data.size, true);
+  data.heights.forEach((height, i) => view.setFloat32(HEADER + i * 4, height, true));
+  data.colours?.forEach((colour, i) => view.setFloat32(HEADER + data.heights.length * 4 + i * 4, colour, true));
+  if (data.splat !== undefined) bytes.set(data.splat, HEADER + data.heights.length * (data.colours === undefined ? 4 : 16));
+  return bytes;
+}
+/** Finite centred query-grid dimensions; typed samples stay owned by the tile decoder. */
+export interface TerrainSamplingRows { readonly resolution: number; readonly size: number; readonly seed: number }
+function samplingGrid(data: TerrainTileData, rows: TerrainSamplingRows): BakedGrid {
+  if (data.splat === undefined || data.colours !== undefined || data.resolution !== rows.resolution || data.size !== rows.size
+    || data.x !== -rows.size/2 || data.z !== -rows.size/2) throw new Error('Invalid terrain sampling profile');
+  return { res: data.resolution,size: data.size,seed: rows.seed,landscapeHash: 0,heights: data.heights,splat: data.splat,undergrowth: null };
+}
+/** Validate dimensions and exact byte counts before allocating sample arrays; reject unknown versions and flags.
+ * Optional strict sampling rows return the same decoded arrays in the native baked-grid shape, without another read. */
+export function decodeTerrainTile(bytes: Uint8Array): TerrainTileData;
+export function decodeTerrainTile(bytes: Uint8Array | undefined, sampling: TerrainSamplingRows): BakedGrid;
+export function decodeTerrainTile(bytes: Uint8Array | undefined, sampling?: TerrainSamplingRows): TerrainTileData | BakedGrid {
+  if (sampling !== undefined && (!isJsonData(sampling) || Object.keys(sampling).sort().join(',') !== 'resolution,seed,size'
+    || !Number.isInteger(sampling.resolution) || sampling.resolution < 2 || sampling.resolution > 257
+    || !Number.isFinite(sampling.size) || sampling.size <= 0 || sampling.size > 500 || !Number.isFinite(sampling.seed))) throw new Error('Invalid terrain sampling rows');
+  if (bytes === undefined || bytes.length < HEADER || !isTerrainTileData(bytes)) throw new Error('Invalid terrain header');
+  const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength), r = v.getUint16(6, true), flags = v.getUint32(8, true);
+  const colour = (flags & 1) !== 0, splat = (flags & 2) !== 0;
+  if (v.getUint16(4, true) !== 1 || r < 2 || r > 257 || flags > 3 || v.getUint32(24, true) !== 0 || v.getUint32(28, true) !== 0 || bytes.length !== HEADER + r * r * (4 + (colour ? 12 : 0) + (splat ? 4 : 0))) throw new Error('Invalid terrain version or length');
+  const heights = new Float32Array(r * r);
+  for (let i = 0; i < heights.length; i++) heights[i] = v.getFloat32(HEADER + i * 4, true);
+  const data: TerrainTileData = { resolution: r, x: v.getFloat32(12, true), z: v.getFloat32(16, true), size: v.getFloat32(20, true), heights };
+  if (colour) {
+    const colours = new Float32Array(r * r * 3);
+    for (let i = 0; i < colours.length; i++) colours[i] = v.getFloat32(HEADER + r * r * 4 + i * 4, true);
+    data.colours = colours;
+  }
+  if (splat) data.splat = Uint8Array.from(bytes.subarray(HEADER + r * r * (colour ? 16 : 4)));
+  check(data); return sampling === undefined ? data : samplingGrid(data,sampling);
+}
+/** Sample the same diagonal split as Rapier heightfields, rather than a bilinear surface that differs from collision. */
+export function terrainTileHeight(data: TerrainTileData, x: number, z: number, policy?: { layout?: 'column-major'; boundary?: 'clamp' }): number {
+  if (policy?.boundary !== 'clamp' && (!Number.isFinite(x) || !Number.isFinite(z) || x < data.x || z < data.z || x > data.x + data.size || z > data.z + data.size)) throw new Error('Point outside terrain');
+  const n = data.resolution - 1, column = policy?.layout === 'column-major', step = data.size / n;
+  const gridX = column ? (x - data.x) / step : (x - data.x) / data.size * n, gridZ = column ? (z - data.z) / step : (z - data.z) / data.size * n;
+  const gx = policy?.boundary === 'clamp' ? Math.min(n, Math.max(0, gridX)) : gridX, gz = policy?.boundary === 'clamp' ? Math.min(n, Math.max(0, gridZ)) : gridZ;
+  const ix = Math.min(n - 1, Math.floor(gx)), iz = Math.min(n - 1, Math.floor(gz)), u = gx - ix, v = gz - iz;
+  const base = column ? ix * data.resolution + iz : iz * data.resolution + ix;
+  const xStep = column ? data.resolution : 1, zStep = column ? 1 : data.resolution, empty = column ? Number.NaN : 0;
+  const h10 = data.heights[base + xStep] ?? empty, h01 = data.heights[base + zStep] ?? empty;
+  if (u + v <= 1) {
+    const h00 = data.heights[base] ?? empty;
+    return h00 + (h10 - h00) * u + (h01 - h00) * v;
+  }
+  const h11 = data.heights[base + xStep + zStep] ?? empty;
+  return h11 + (h01 - h11) * (1 - u) + (h10 - h11) * (1 - v);
+}
+/** Native bilinear queries on an admitted whole-cell original lattice, with its original central-difference normal law.
+ * Datum shifts height only; normals are computed before the shift, preserving the native floating-point operation order. */
+export function bilinearTerrainSamplers(data: TerrainTileData, normalEpsilon: number, datum = 0): BakedTerrainSamplers {
+  check(data);
+  if ((data.resolution !== 256 && data.resolution !== 257) || data.x !== -250 || data.z !== -250 || data.size !== 500
+    || data.colours !== undefined || data.splat === undefined || !Number.isFinite(normalEpsilon) || normalEpsilon < 0.001 || normalEpsilon > 4
+    || !Number.isFinite(datum) || datum < -CELL_BELOW || datum > CELL_ABOVE) throw new Error('Invalid bilinear terrain sampling profile');
+  const native = bakedSamplers(samplingGrid(data,{ resolution: data.resolution,size: data.size,seed: 0 }));
+  return { heightAt: datum === 0 ? native.heightAt : (x, z) => native.heightAt(x, z) + datum,
+    normalAt: (x, z, eps = normalEpsilon) => native.normalAt(x, z, eps), splatAt: native.splatAt };
+}
+/** Conservative sample/mesh residency and draws, including an L0 shadow pass; collider-only payloads have no draws. */
+export function terrainTileCost(data: TerrainTileData): { decoded: number; gpu: number; triangles: number; draws: number } {
+  const vertices = data.resolution ** 2, cells = (data.resolution - 1) ** 2, skirt = data.resolution === 17 && data.size === 125 ? 0 : 4 * (data.resolution - 1);
+  const indexBytes = (cells * 6 + skirt * 6) * (vertices + skirt > 65535 ? 4 : 2);
+  const splatBytes = data.splat === undefined ? 0 : vertices * 8;
+  return data.colours === undefined ? { decoded: HEADER + vertices * 8 + splatBytes, gpu: 0, triangles: 0, draws: 0 }
+    : { decoded: HEADER + vertices * (skirt === 0 ? 56 : 68) + skirt * 36 + indexBytes + splatBytes, gpu: (vertices + skirt) * 36 + indexBytes, triangles: cells * 2 + skirt * 2, draws: data.size === 62.5 ? 2 : 1 };
+}

package/src/format/tierSelection.ts

@@ -0,0 +1,195 @@
+import type { LateFile } from './admissionLate.ts';
+import { parseWorldScenes, worldScenesForTier } from './worldScenes.ts';
+import { parseRiggedHullBook } from './riggedHulls.ts';
+import { PosedLibrarySchema } from './namedJsonContracts.ts';
+import { parseClientPlan } from './clientPlan.ts';
+import * as v from 'valibot';
+
+/** Only immutable addressing and typed alternatives are needed for selection.
+ * Other root fields are retained by the conservative string walk at runtime. */
+export interface TierSelectionSource {
+  readonly identity: { readonly slug: string };
+  readonly files: readonly { readonly hash: string; readonly kind: string; readonly decoded: number; readonly dependencies: readonly string[] }[];
+  readonly library: readonly string[]; readonly critical: readonly string[];
+  /** Scheduling metadata never creates a synchronous consumer or a tier pin. */
+  readonly late?: readonly LateFile[];
+  readonly manifest?: { readonly horizonStrips?: { readonly day: string; readonly night: string; readonly phone?: { readonly day: string; readonly night: string } } };
+}
+
+/** Pure typed-alternative selection, shared by boot compilation and admission.
+ * No runtime owner, current device, storage or transport is read here. */
+export function* stringsSteps(roots: readonly unknown[], found: (text: string) => void): Generator<void> {
+  const pending: unknown[] = [...roots];
+  let visited = 0;
+  while (pending.length > 0) {
+    const value = pending.pop();
+    if (++visited % 4096 === 0) yield;
+    if (typeof value === 'string') found(value);
+    else if (Array.isArray(value)) {
+      const items: readonly unknown[] = value;
+      for (const item of items) {
+        if (typeof item === 'string' || typeof item === 'object' && item !== null) pending.push(item);
+        else if (++visited % 4096 === 0) yield;
+      }
+    }
+    // Preserve every own key and string callback, without queueing numeric pose
+    // words (they cannot name an asset). Count their scan toward paint
+    // checkpoints anyway; schema validation still checks those values.
+    else if (typeof value === 'object' && value !== null) for (const key in value) if (Object.hasOwn(value, key)) {
+      found(key); const child: unknown = Reflect.get(value, key);
+      if (typeof child === 'string' || typeof child === 'object' && child !== null) pending.push(child);
+      else if (++visited % 4096 === 0) yield;
+    }
+  }
+}
+
+/** Entry transport omits manifest-only URL-image copies. Their authored URL
+ * readers do not consume admitted buffers; any other host or dependency does.
+ * Cost projection stays separate and retains URL-image pixels and wire. */
+export function* entryFileSteps(source: TierSelectionSource, tier: 'phone' | 'desktop', descriptor: Parameters<typeof tierLibrarySteps>[2]): Generator<void, ReadonlySet<string>> {
+  const alternatives = yield* tierLibrarySteps(source, tier, descriptor);
+  const inactive = new Set(alternatives);
+  if (source.manifest === undefined) return inactive;
+  const images = new Set(source.files.filter(file => file.kind === 'image').map(file => file.hash));
+  const names = new Map<string, string>();
+  for (const file of descriptor.index.files) if (images.has(file.hash)) {
+    for (const name of [file.hash, file.path, `/shardfiles/${source.identity.slug}/${file.path}`]) names.set(name, file.hash);
+    if (file.name !== undefined) names.set(file.name, file.hash);
+  }
+  const eligible = new Set<string>(), used = new Set(source.critical);
+  yield* stringsSteps([source.manifest], text => { const hash = names.get(text); if (hash !== undefined) eligible.add(hash); });
+  const { files: _files, library: _library, critical: _critical, manifest: _manifest, late: _late, ...fields } = source;
+  const sections = [...descriptor.sections].map(([name, row]) => name === 'ui/level' && typeof row === 'object' && row !== null
+    ? Object.fromEntries(Object.entries(row).filter(([key]) => key !== 'manifest')) : row);
+  yield* stringsSteps([fields, ...sections], text => { const hash = names.get(text); if (hash !== undefined) used.add(hash); });
+  for (const file of source.files) for (const dependency of file.dependencies) used.add(dependency);
+  for (const hash of eligible) if (!used.has(hash)) inactive.add(hash);
+  return inactive;
+}
+
+export function* tierLibrarySteps(source: TierSelectionSource, tier: 'phone' | 'desktop', descriptor: { readonly index: { readonly files: readonly { readonly hash: string; readonly path: string; readonly name?: string; readonly tier?: 'phone' | 'desktop'; readonly variantOf?: string; readonly compressed?: number }[] }; readonly sections: ReadonlyMap<string, unknown> }, assets?: ReadonlyMap<string, Uint8Array>): Generator<void, ReadonlySet<string>> {
+  const names = new Map<string, string>();
+  for (const file of descriptor.index.files) {
+    for (const name of [file.hash, file.path, `/shardfiles/${source.identity.slug}/${file.path}`]) names.set(name, file.hash);
+    if (file.name !== undefined) names.set(file.name, file.hash);
+  }
+  const inactive = new Set<string>(), used = new Set(source.critical);
+  // a named file marked for the other device tier is that tier's download only, even where an active row names it (an
+  // alias table naming both tiers' payloads); only a critical pin or a file dependency keeps it
+  const otherTier = new Set(descriptor.index.files.filter(file => file.tier !== undefined && file.tier !== tier).map(file => file.hash));
+  // variants of one payload (its texture modes' alternatives): the device fetches one, so this tier keeps only its largest
+  const variants = new Map<string, { readonly hash: string; readonly compressed: number }[]>();
+  for (const file of descriptor.index.files) if (file.variantOf !== undefined && !otherTier.has(file.hash))
+    variants.set(file.variantOf, [...variants.get(file.variantOf) ?? [], { hash: file.hash, compressed: file.compressed ?? 0 }]);
+  for (const group of variants.values()) {
+    const kept = group.reduce((best, row) => row.compressed > best.compressed || (row.compressed === best.compressed && row.hash < best.hash) ? row : best);
+    for (const row of group) if (row !== kept) otherTier.add(row.hash);
+  }
+  for (const hash of otherTier) inactive.add(hash);
+  const alternative = (selected: string, other: string): void => {
+    const off = names.get(other); if (off !== undefined) inactive.add(off);
+    const on = names.get(selected); if (on !== undefined) used.add(on);
+  };
+  const sections = new Map(descriptor.sections);
+  const metadata = source.manifest;
+  let manifest = source.manifest;
+  if (metadata?.horizonStrips?.phone !== undefined) {
+    const horizon = metadata.horizonStrips, selected = tier === 'phone' ? horizon.phone : horizon;
+    const other = tier === 'phone' ? horizon : horizon.phone;
+    if (selected !== undefined && other !== undefined) {
+      alternative(selected.day, other.day); alternative(selected.night, other.night);
+      const { phone: _phone, ...base } = horizon;
+      manifest = { ...metadata, horizonStrips: { ...base, day: selected.day, night: selected.night } };
+      sections.set('ui/level', { manifest });
+    }
+  }
+  const scenes = sections.get('world/scenes');
+  if (scenes !== undefined) {
+    const declared = parseWorldScenes(scenes);
+    for (const library of declared.libraries) if (library.kind === 'owned') for (const model of library.models) {
+      if (model.tier === undefined || model.tier === tier) continue;
+      for (const file of typeof model.file === 'string' ? [model.file] : Object.values(model.file)) {
+        const ref = names.get(file); if (ref !== undefined) inactive.add(ref);
+      }
+    }
+    for (const placement of declared.placements) if (placement.tier !== undefined && placement.tier !== tier && 'file' in placement) {
+      const ref = names.get(placement.file); if (ref !== undefined) inactive.add(ref);
+    }
+    const row = worldScenesForTier(declared, tier);
+    const libraries: typeof row.libraries = [];
+    for (const library of row.libraries) {
+      if (library.kind !== 'owned') { libraries.push(library); continue; }
+      const models: typeof library.models = [];
+      for (const model of library.models) {
+        if (typeof model.file === 'string') models.push(model);
+        else {
+          alternative(model.file[tier], model.file[tier === 'phone' ? 'desktop' : 'phone']);
+          models.push({ ...model, file: model.file[tier] });
+        }
+      }
+      libraries.push({ ...library, models });
+    }
+    sections.set('world/scenes', { ...row, libraries });
+  }
+  const client = sections.get('client/plan');
+  if (client !== undefined) {
+    const plan = parseClientPlan(client);
+    // iPhone downloads I8: a water row draws its page tier's grid and a baked row its tier's tiles, lightmaps, wear and
+    // plan (clientWaterSurfaces, bakedTiles): every { phone, desktop } pair keeps only this tier's files
+    const strings = (input: unknown, into: (text: string) => void): void => {
+      if (typeof input === 'string') into(input);
+      else if (typeof input === 'object' && input !== null) for (const value of Object.values(input)) strings(value, into);
+    };
+    const tiered = (input: unknown): unknown => {
+      if (Array.isArray(input)) return input.map(tiered);
+      if (typeof input !== 'object' || input === null) return input;
+      if (Object.keys(input).length === 2 && 'phone' in input && 'desktop' in input) {
+        strings(tier === 'phone' ? input.desktop : input.phone, text => { const ref = names.get(text); if (ref !== undefined) inactive.add(ref); });
+        const selected = tiered(tier === 'phone' ? input.phone : input.desktop);
+        return { phone: selected, desktop: selected };
+      }
+      return Object.fromEntries(Object.entries(input).map(([key, value]) => [key, tiered(value)]));
+    };
+    const features: unknown[] = plan.features.map(feature => {
+      if (feature.kind === 'world.water' || feature.kind === 'world.baked') return { ...feature, rows: tiered(feature.rows) };
+      if (feature.kind !== 'world.assembly' || feature.rows.construction?.cells === undefined) return feature;
+      const construction = feature.rows.construction, cells = construction.cells;
+      if (cells === undefined) return feature;
+      // WorldAssembly.construct reads exactly cells[TIER], including on a
+      // restored entry. Other sections, critical pins and dependencies below
+      // still protect a shared file; the descriptor itself is never changed.
+      alternative(cells[tier], cells[tier === 'phone' ? 'desktop' : 'phone']);
+      return { ...feature, rows: { ...feature.rows, construction: { ...construction,
+        cells: { phone: cells[tier], desktop: cells[tier] } } } };
+    });
+    sections.set('client/plan', { ...plan, features });
+  }
+  const hulls = sections.get('look/rigged-hulls');
+  if (hulls !== undefined) {
+    // The rigged-hull loader reads only its page tier's resources (looks/riggedHulls.ts).
+    const book = parseRiggedHullBook(hulls);
+    const off = (input: unknown): void => {
+      if (typeof input === 'string') { const hash = names.get(input); if (hash !== undefined) inactive.add(hash); }
+      else if (typeof input === 'object' && input !== null) for (const value of Object.values(input)) off(value);
+    };
+    off(book.tiers[tier === 'phone' ? 'desktop' : 'phone']);
+    sections.set('look/rigged-hulls', { ...book, tiers: { [tier]: book.tiers[tier] } });
+  }
+  // Posed libraries (looks/posedInstances.ts) read only their page tier's geometry and atlas.
+  // Only a small named JSON can be one; the strict schema, not a name, identifies it.
+  if (assets !== undefined) for (const file of source.files) {
+    const bytes = file.kind === 'json' && file.decoded <= 65_536 ? assets.get(file.hash) : undefined;
+    const text = bytes === undefined ? '' : new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    if (!text.includes('"tiers"')) continue;
+    const row = v.safeParse(PosedLibrarySchema, JSON.parse(text));
+    if (!row.success) continue;
+    const selected = row.output.tiers[tier], other = row.output.tiers[tier === 'phone' ? 'desktop' : 'phone'];
+    alternative(selected.geometry, other.geometry); if (selected.atlas !== undefined && other.atlas !== undefined) alternative(selected.atlas, other.atlas);
+  }
+  if (inactive.size === 0) return inactive;
+  const { files: _files, library: _library, critical: _critical, manifest: _manifest, late: _late, ...fields } = source;
+  yield* stringsSteps([{ ...fields, manifest }, ...sections.values()], text => { const hash = names.get(text); if (hash !== undefined) used.add(hash); });
+  const pinned = new Set([...source.critical, ...source.files.flatMap(file => file.dependencies)]);
+  for (const file of source.files) for (const ref of file.dependencies) used.add(ref);
+  return new Set([...inactive].filter(hash => otherTier.has(hash) ? !pinned.has(hash) : !used.has(hash)));
+}

package/src/format/toonLighting.ts

@@ -0,0 +1,32 @@
+import * as v from 'valibot';
+
+const finite = v.pipe(v.number(), v.finite());
+const vector = v.tuple([finite, finite, finite]);
+/** Shared presentation lighting identity, initialized from admitted data. */
+export const ToonLightingSchema: v.GenericSchema<ToonLightingRowInput, ToonLightingRow> = v.strictObject({ id: v.pipe(v.string(), v.minLength(1), v.maxLength(512)),
+  initial: v.strictObject({ uToonLift: vector, uToonRim: vector,
+    uCloudShadow: finite, uToonNight: finite, uSeaLevel: finite, uCloudTime: finite }) });
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type ToonLightingRowInput = ToonLightingRow;
+interface ToonLightingRowFields {
+    id: string;
+    initial: {
+        uToonLift: [
+            number,
+            number,
+            number
+        ];
+        uToonRim: [
+            number,
+            number,
+            number
+        ];
+        uCloudShadow: number;
+        uToonNight: number;
+        uSeaLevel: number;
+        uCloudTime: number;
+    };
+}
+export type ToonLightingRow = { [Key in keyof ToonLightingRowFields]: ToonLightingRowFields[Key] };