@wildshard/shard-format 0.0.0 → 0.4.5

package/src/format/standaloneControl.ts

@@ -0,0 +1,44 @@
+import * as v from 'valibot';
+
+// P1-E5.2 (J59 Q7, E5-REPLICATION §6.3): the control port. `boot`, `pause` and save forwarding exist only in the
+// standalone target, so they travel apart from the game Transport and the game protocol stays identical to the MMO's.
+
+const text = v.pipe(v.string(), v.minLength(1), v.maxLength(2048));
+const natural = v.pipe(v.number(), v.finite(), v.integer(), v.minValue(0), v.maxValue(Number.MAX_SAFE_INTEGER));
+const id = natural;
+const lone = v.exactOptional(v.literal(true));
+
+/** What the page sends the server worker. */
+export type ShellMessage =
+  | { readonly kind: 'boot'; readonly slug: string; readonly base: string; readonly build: string; readonly savePrefix: string; readonly saves: Readonly<Record<string, string>>;
+    /** A one-shard page: the server runs this cell alone, with its own walls and no road, whether or not the grid places it. */
+    readonly lone?: true }
+  | { readonly kind: 'ready' } | { readonly kind: 'pause' } | { readonly kind: 'resume' }
+  | { readonly kind: 'save'; readonly id: number } | { readonly kind: 'probe'; readonly id: number }
+  | { readonly kind: 'written'; readonly seq: number; readonly ok: boolean };
+/** The server's exact state of one creature at a frame tick. */
+export interface ProbedRow { readonly id: string; readonly x: number; readonly y: number; readonly z: number; readonly yaw: number; readonly hp: number }
+/** What the server worker sends the page. */
+export type ServerMessage =
+  | { readonly kind: 'booted'; readonly tick: number; readonly restored: boolean }
+  | { readonly kind: 'write'; readonly seq: number; readonly key: string; readonly value: string | null }
+  | { readonly kind: 'saved'; readonly id: number; readonly tick: number; readonly ok: boolean }
+  | { readonly kind: 'probed'; readonly id: number; readonly tick: number; readonly tickMs: number; readonly rows: readonly ProbedRow[] }
+  | { readonly kind: 'failed'; readonly reason: string };
+
+/** The page's messages, checked on arrival in the worker. */
+export const ShellMessageSchema: v.GenericSchema<ShellMessage> = v.variant('kind', [
+  v.strictObject({ kind: v.literal('boot'), slug: text, base: text, build: v.string(), savePrefix: text, saves: v.record(v.string(), v.string()), lone }),
+  v.strictObject({ kind: v.literal('ready') }), v.strictObject({ kind: v.literal('pause') }), v.strictObject({ kind: v.literal('resume') }),
+  v.strictObject({ kind: v.literal('save'), id }), v.strictObject({ kind: v.literal('probe'), id }),
+  v.strictObject({ kind: v.literal('written'), seq: natural, ok: v.boolean() }),
+]);
+const finite = v.pipe(v.number(), v.finite());
+/** The worker's messages, checked on arrival in the page. */
+export const ServerMessageSchema: v.GenericSchema<ServerMessage> = v.variant('kind', [
+  v.strictObject({ kind: v.literal('booted'), tick: natural, restored: v.boolean() }),
+  v.strictObject({ kind: v.literal('write'), seq: natural, key: text, value: v.nullable(v.string()) }),
+  v.strictObject({ kind: v.literal('saved'), id, tick: natural, ok: v.boolean() }),
+  v.strictObject({ kind: v.literal('probed'), id, tick: natural, tickMs: finite, rows: v.array(v.strictObject({ id: text, x: finite, y: finite, z: finite, yaw: finite, hp: finite })) }),
+  v.strictObject({ kind: v.literal('failed'), reason: v.string() }),
+]);

package/src/format/state.ts

@@ -0,0 +1,61 @@
+import * as v from 'valibot';
+import { SHARDFILE_ADMISSION_LIMITS as limits } from './admissionLimits.ts';
+
+const positive = v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(Number.MAX_SAFE_INTEGER));
+const finite: v.GenericSchema<number, number> & { readonly pipe: readonly [unknown, v.FiniteAction<number, undefined>] } = v.pipe(v.number(), v.finite());
+const field: v.StrictObjectSchema<{ readonly id: v.GenericSchema<StateFieldRowsInput['id'], StateFieldRows['id']>; readonly name: v.GenericSchema<string, string> & { readonly pipe: readonly [unknown, v.RegexAction<string, undefined>, unknown] }; readonly type: v.GenericSchema<StateFieldRowsInput['type'], StateFieldRows['type']>; readonly privacy: v.GenericSchema<StateFieldRowsInput['privacy'], StateFieldRows['privacy']>; readonly default: v.GenericSchema<StateFieldRowsInput['default'], StateFieldRows['default']> & { readonly options: readonly [unknown, typeof finite, unknown] }; readonly min: v.OptionalSchema<v.GenericSchema<Exclude<StateFieldRowsInput['min'], undefined>, Exclude<StateFieldRows['min'], undefined>>, undefined>; readonly max: v.OptionalSchema<v.GenericSchema<Exclude<StateFieldRowsInput['max'], undefined>, Exclude<StateFieldRows['max'], undefined>>, undefined>; }, undefined> = v.strictObject({ id: v.pipe(positive, v.maxValue(0x7fffffff)), name: v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u), v.maxLength(limits.idCharacters)),
+  type: v.picklist(['bool', 'i32', 'f64', 'string']), privacy: v.picklist(['public', 'owner', 'host']),
+  default: v.union([v.boolean(), finite, v.pipe(v.string(), v.maxLength(limits.textCharacters))]), min: v.optional(finite), max: v.optional(finite) });
+const fieldList: v.GenericSchema<StateInput['shared'], State['shared']> & { readonly pipe: readonly [v.ArraySchema<typeof field, undefined>, unknown] } = v.pipe(v.array(field), v.maxLength(limits.stateFields));
+const declaration: v.StrictObjectSchema<{ readonly version: v.GenericSchema<StateInput['version'], State['version']>; readonly sharedOwner: v.GenericSchema<StateInput['sharedOwner'], State['sharedOwner']>; readonly playerKey: v.GenericSchema<StateInput['playerKey'], State['playerKey']>; readonly shared: typeof fieldList; readonly player: typeof fieldList; }, undefined> = v.strictObject({ version: positive, sharedOwner: v.literal('host'), playerKey: v.literal('actorId'), shared: fieldList, player: fieldList });
+
+/** Portable state declarations have the same typed defaults, bounds, identity and capacity rules as current full-format admission. */
+export function stateRules(state: State): string[] {
+  const errors: string[] = [], fields = [...state.shared, ...state.player];
+  for (const list of [state.shared, state.player]) {
+    if (new Set(list.map((item) => item.name)).size !== list.length) errors.push('unique state fields');
+    for (const item of list) if (item.type === 'bool' ? typeof item.default !== 'boolean' : item.type === 'string' ? typeof item.default !== 'string'
+      : typeof item.default !== 'number' || (item.type === 'i32' && (!Number.isInteger(item.default) || item.default < -2147483648 || item.default > 2147483647))) errors.push('typed state default');
+  }
+  if (new Set(fields.map((item) => item.id)).size !== fields.length) errors.push('unique stable state ids');
+  if (fields.filter((item) => item.type !== 'string').length > 24) errors.push('numeric script state capacity');
+  for (const item of fields) {
+    if (item.type === 'string') { if (item.min !== undefined || item.max !== undefined) errors.push('numeric state bounds only'); continue; }
+    const low = item.type === 'bool' ? 0 : item.type === 'i32' ? -2147483648 : -Number.MAX_VALUE;
+    const high = item.type === 'bool' ? 1 : item.type === 'i32' ? 2147483647 : Number.MAX_VALUE;
+    const min = item.min ?? low, max = item.max ?? high, value = typeof item.default === 'boolean' ? Number(item.default) : item.default;
+    if (min < low || max > high || min > max || (item.type !== 'f64' && (!Number.isInteger(min) || !Number.isInteger(max))) || typeof value !== 'number' || value < min || value > max) errors.push('typed state bounds');
+  }
+  return [...new Set(errors)];
+}
+/** Strict renderer-neutral state projection; validating it never admits a cached product's geometry or scripts. */
+export const StateSchema: v.SchemaWithPipe<readonly [typeof declaration, v.CheckAction<State, 'state declaration semantic rules'>]> = v.pipe(declaration, v.check((state) => stateRules(state).length === 0, 'state declaration semantic rules'));
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type StateFieldRowsInput = StateFieldRows;
+interface StateFieldRowsFields {
+    id: number;
+    name: string;
+    type: 'bool' | 'i32' | 'f64' | 'string';
+    privacy: 'public' | 'owner' | 'host';
+    default: (boolean) | (number) | (string);
+    min?: number | undefined;
+    max?: number | undefined;
+}
+export type StateFieldRows = { [Key in keyof StateFieldRowsFields]: StateFieldRowsFields[Key] };
+interface StateInputFields {
+    version: number;
+    sharedOwner: 'host';
+    playerKey: 'actorId';
+    shared: (StateFieldRowsInput)[];
+    player: (StateFieldRowsInput)[];
+}
+export type StateInput = { [Key in keyof StateInputFields]: StateInputFields[Key] };
+interface StateFields {
+    version: number;
+    sharedOwner: 'host';
+    playerKey: 'actorId';
+    shared: (StateFieldRows)[];
+    player: (StateFieldRows)[];
+}
+export type State = { [Key in keyof StateFields]: StateFields[Key] };

package/src/format/stateLineage.ts

@@ -0,0 +1,71 @@
+import * as v from 'valibot';
+import { assertMigrationCompatibility } from './migrations.ts';
+import { StateSchema } from './state.ts';
+import type { Shardfile } from './shardSchema.ts';
+import { isJsonDataWithFileSchemas } from './json.ts';
+import { SHARDFILE_VERSION } from './version.ts';
+import { SHARDFILE_ADMISSION_LIMITS as limits } from './admissionLimits.ts';
+
+const identity = v.object({ slug: v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u)),
+  revision: v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(Number.MAX_SAFE_INTEGER)) });
+const lineage: v.GenericSchema<StateLineageInput, StateLineage> = v.object({ identity, state: StateSchema });
+
+/** Read only strict portable state and identity from a previously visited product. Its legacy geometry and scripts remain unadmitted. */
+export function parseStateLineage(input: unknown): StateLineage { return v.parse(lineage, input); }
+
+const path = v.pipe(v.string(), v.maxLength(240), v.regex(/^(?:[a-zA-Z0-9_-][a-zA-Z0-9_.-]*\/)*[a-zA-Z0-9_-][a-zA-Z0-9_.-]*$/u));
+const measured = { path, hash: v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/u)),
+  bytes: v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(Number.MAX_SAFE_INTEGER)) };
+const inventory = v.object({ format: v.literal('wildshard.shardfile'), formatVersion: v.literal(2), sdk: v.literal('0.2'),
+  version: v.literal(SHARDFILE_VERSION), identity,
+  sections: v.pipe(v.array(v.strictObject({ ...measured, name: v.pipe(v.string(), v.regex(/^[a-z][a-zA-Z0-9-]*\/[a-zA-Z][a-zA-Z0-9_-]*$/u)),
+    schema: v.pipe(v.string(), v.maxLength(240)) })), v.maxLength(256)),
+  schemas: v.pipe(v.array(v.strictObject(measured)), v.maxLength(128)) });
+export interface OutputLineageIndex {
+  readonly identity: { readonly slug: string; readonly revision: number };
+  readonly sections: readonly { readonly path: string; readonly hash: string; readonly bytes: number; readonly name: string; readonly schema: string }[];
+  readonly schemas: readonly { readonly path: string; readonly hash: string; readonly bytes: number }[];
+}
+/** Cached historical inventory proves only bounded, immutable section transport.
+ * Obsolete host/asset declarations are never parsed or admitted by this reader. */
+export function parseOutputLineageIndex(input: unknown): OutputLineageIndex {
+  if (!isJsonDataWithFileSchemas(input)) throw new Error('Shardfile descriptor requires bounded plain JSON');
+  const index = v.parse(inventory, input), paths = new Set(['shard.json', 'validation.json']), names = new Set<string>();
+  if (index.sections.reduce((total, row) => total + row.bytes, 0) > limits.sourceBytes) throw new Error('Output sections exceed the source byte cap');
+  for (const row of [...index.sections, ...index.schemas]) {
+    if (row.path.split('/').some(part => part === '.' || part === '..') || paths.has(row.path)) throw new Error('Duplicate or escaping output path');
+    paths.add(row.path);
+  }
+  for (const row of index.sections) {
+    if (names.has(row.name) || row.path !== `sections/${row.name}.json`) throw new Error('Duplicate or mismatched section path');
+    names.add(row.name);
+  }
+  if (!index.sections.some(row => row.name === 'state/state' && row.schema === 'wildshard:state/state@1')) throw new Error('Missing historical state section');
+  return index;
+}
+
+/** Preserve saved field identities across validated author revisions; declaration ordering is immaterial. */
+export function assertStateCompatibility(previous: StateLineage, next: Shardfile): void {
+  v.parse(v.literal(previous.identity.slug, 'State revisions must name the same shard'), next.identity.slug);
+  if (next.identity.revision < previous.identity.revision) throw new Error('State revisions cannot move backwards');
+  assertMigrationCompatibility(previous.state, next.state, next.migrations);
+}
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+interface StateLineageInputFields {
+    identity: {
+        slug: string;
+        revision: number;
+    };
+    state: v.InferInput<typeof StateSchema>;
+}
+export type StateLineageInput = { [Key in keyof StateLineageInputFields]: StateLineageInputFields[Key] };
+interface StateLineageFields {
+    identity: {
+        slug: string;
+        revision: number;
+    };
+    state: v.InferOutput<typeof StateSchema>;
+}
+export type StateLineage = { [Key in keyof StateLineageFields]: StateLineageFields[Key] };

package/src/format/stealth.ts

@@ -0,0 +1,106 @@
+import * as v from 'valibot';
+
+const id=v.pipe(v.string(),v.minLength(1),v.maxLength(128)),text=v.pipe(v.string(),v.maxLength(4096)),n=v.pipe(v.number(),v.finite());
+/** Bounded static baseline-HUD markup; detection decisions are admitted separately as ABI-v1 programs. */
+interface Frame {tag?:'div'|'span'|'b'|'i';cls?:string;ref?:string;text?:string;data?:Record<string,string>;children?:Frame[]}
+interface Icon {svg:'svg'|'path'|'circle'|'g'|'rect'|'line'|'polyline'|'polygon'|'ellipse';attrs?:[string,string][];children?:Icon[]}
+const frame:v.GenericSchema<unknown,Frame>=v.lazy(()=>v.strictObject({tag:v.exactOptional(v.picklist(['div','span','b','i'])),cls:v.exactOptional(text),ref:v.exactOptional(id),text:v.exactOptional(text),data:v.exactOptional(v.record(id,text)),children:v.exactOptional(v.pipe(v.array(frame),v.maxLength(32)))}));
+const icon:v.GenericSchema<unknown,Icon>=v.lazy(()=>v.strictObject({svg:v.picklist(['svg','path','circle','g','rect','line','polyline','polygon','ellipse']),attrs:v.exactOptional(v.pipe(v.array(v.tuple([text,text])),v.maxLength(32))),children:v.exactOptional(v.pipe(v.array(icon),v.maxLength(32)))}));
+/** Ordered native roster observations; sensing and detection keep their original owners. */
+export const StealthSourcesSchema: v.GenericSchema<StealthSourcesInput, StealthSources>=v.strictObject({
+ take:v.pipe(n,v.integer(),v.minValue(1),v.maxValue(8)),
+ sources:v.pipe(v.array(v.variant('kind',[
+  v.strictObject({kind:v.literal('packs'),groups:v.pipe(n,v.integer(),v.minValue(1),v.maxValue(96)),members:v.pipe(n,v.integer(),v.minValue(1),v.maxValue(96)),alert:n,hunting:v.pipe(v.array(v.picklist(['roam','shadow','encircle','regroup','break'])),v.maxLength(5))}),
+  v.strictObject({kind:v.literal('herds'),groups:v.pipe(n,v.integer(),v.minValue(1),v.maxValue(96)),members:v.pipe(n,v.integer(),v.minValue(1),v.maxValue(96)),alert:n,exclude:v.pipe(v.array(v.picklist(['ridden','owned'])),v.maxLength(2))}),
+ ])),v.minLength(1),v.maxLength(8)),
+ melee:v.exactOptional(id),
+});
+
+/** G478 stealth-and-detection rows, shared by independent shard profiles. Client markup is presentation only. */
+export const StealthRowsSchema: v.GenericSchema<StealthRowsInput, StealthRows>=v.strictObject({observations:v.exactOptional(StealthSourcesSchema),program:v.unknown(),tuning:v.pipe(v.record(id,n),v.check(rows=>Object.keys(rows).length<=64)),
+ states:v.pipe(v.array(id),v.minLength(1),v.maxLength(16)),labels:v.record(id,text),panels:v.strictObject({layer:frame,row:frame,grass:frame}),icons:v.record(id,icon),
+ disc:text,discLabel:text,threatStates:v.pipe(v.array(id),v.maxLength(16)),hint:text,hintSeconds:v.pipe(n,v.minValue(0),v.maxValue(60)),system:id,
+ input:v.strictObject({id,actions:v.pipe(v.array(v.picklist(['crouch','crouch.hold'])),v.maxLength(2)),keys:v.record(v.picklist(['crouch','crouch.hold']),v.pipe(v.array(id),v.maxLength(16)))}),
+ sneak:v.strictObject({state:id,seconds:v.pipe(n,v.minValue(0),v.maxValue(60)),multiplier:v.pipe(n,v.minValue(0),v.maxValue(100))})});
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type StealthSourcesInput = StealthSources;
+interface StealthSourcesFields {
+    take: number;
+    sources: (({
+        kind: 'packs';
+        groups: number;
+        members: number;
+        alert: number;
+        hunting: ('roam' | 'shadow' | 'encircle' | 'regroup' | 'break')[];
+    }) | ({
+        kind: 'herds';
+        groups: number;
+        members: number;
+        alert: number;
+        exclude: ('ridden' | 'owned')[];
+    }))[];
+    melee?: string;
+}
+export type StealthSources = { [Key in keyof StealthSourcesFields]: StealthSourcesFields[Key] };
+interface StealthRowsInputFields {
+    observations?: StealthSourcesInput;
+    program: unknown;
+    tuning: Record<string, number>;
+    states: (string)[];
+    labels: Record<string, string>;
+    panels: {
+        layer: v.InferInput<typeof frame>;
+        row: v.InferInput<typeof frame>;
+        grass: v.InferInput<typeof frame>;
+    };
+    icons: Record<string, v.InferInput<typeof icon>>;
+    disc: string;
+    discLabel: string;
+    threatStates: (string)[];
+    hint: string;
+    hintSeconds: number;
+    system: string;
+    input: {
+        id: string;
+        actions: ('crouch' | 'crouch.hold')[];
+        keys: Record<string, (string)[]>;
+    };
+    sneak: {
+        state: string;
+        seconds: number;
+        multiplier: number;
+    };
+}
+export type StealthRowsInput = { [Key in keyof StealthRowsInputFields]: StealthRowsInputFields[Key] };
+interface StealthRowsFields {
+    observations?: StealthSources;
+    program: unknown;
+    tuning: Record<string, number>;
+    states: (string)[];
+    labels: Record<string, string>;
+    panels: {
+        layer: v.InferOutput<typeof frame>;
+        row: v.InferOutput<typeof frame>;
+        grass: v.InferOutput<typeof frame>;
+    };
+    icons: Record<string, v.InferOutput<typeof icon>>;
+    disc: string;
+    discLabel: string;
+    threatStates: (string)[];
+    hint: string;
+    hintSeconds: number;
+    system: string;
+    input: {
+        id: string;
+        actions: ('crouch' | 'crouch.hold')[];
+        keys: Record<string, (string)[]>;
+    };
+    sneak: {
+        state: string;
+        seconds: number;
+        multiplier: number;
+    };
+}
+export type StealthRows = { [Key in keyof StealthRowsFields]: StealthRowsFields[Key] };

package/src/format/stillImage.ts

@@ -0,0 +1,135 @@
+/** Bounded inert SHARD SELECT images. These limits apply before a browser decoder sees any bytes. */
+export const STILL_IMAGE_LIMITS = { bytes: 4_194_304, dimension: 4096, chunks: 1024 } as const;
+/** Texture strips may be wide, but never exceed a title image's pixel area or wire cap. */
+export const IMAGE_ASSET_LIMITS: { readonly dimension: 8192; readonly pixels: number; readonly bytes: 4194304; readonly chunks: 1024; } = { ...STILL_IMAGE_LIMITS, dimension: 8192, pixels: STILL_IMAGE_LIMITS.dimension ** 2 } as const;
+/** Byte-derived image envelope and conservative CPU/data-URL and compositor residency. */
+export interface StillImage { mime: 'image/png' | 'image/jpeg' | 'image/webp'; width: number; height: number; decoded: number; gpu: number }
+const crcTable = Uint32Array.from({ length: 256 }, (_unused, value) => {
+  let result = value;
+  for (let bit = 0; bit < 8; bit++) result = (result >>> 1) ^ ((result & 1) === 0 ? 0 : 0xedb88320);
+  return result;
+});
+function crc(view: DataView, start: number, end: number): number {
+  let value = 0xffffffff;
+  for (let at = start; at < end; at++) value = (value >>> 8) ^ (crcTable[(value ^ view.getUint8(at)) & 255] ?? 0);
+  return (value ^ 0xffffffff) >>> 0;
+}
+
+function envelope(bytes: Uint8Array, mime: StillImage['mime'], width: number, height: number): StillImage {
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1 || width > IMAGE_ASSET_LIMITS.dimension || height > IMAGE_ASSET_LIMITS.dimension || width * height > IMAGE_ASSET_LIMITS.pixels) throw new Error('Still image dimensions exceed admission bounds');
+  const pixels = width * height * 4;
+  // Include the immutable wire bytes and the UTF-16 base64 URL, rounded conservatively to four times wire.
+  return { mime, width, height, decoded: pixels + bytes.length * 4, gpu: pixels };
+}
+
+function png(bytes: Uint8Array, view: DataView): StillImage {
+  let offset = 8, width = 0, height = 0, chunks = 0, data = false, endedData = false;
+  while (offset + 12 <= bytes.length && ++chunks <= STILL_IMAGE_LIMITS.chunks) {
+    const length = view.getUint32(offset), type = view.getUint32(offset + 4), end = offset + 12 + length;
+    if (end > bytes.length) throw new Error('Truncated PNG chunk');
+    if (chunks === 1) {
+      if (type !== 0x49484452 || length !== 13) throw new Error('PNG requires one leading IHDR');
+      width = view.getUint32(offset + 8); height = view.getUint32(offset + 12);
+      envelope(bytes, 'image/png', width, height);
+      const colour = view.getUint8(offset + 17), depth = view.getUint8(offset + 16);
+      if (![0, 2, 3, 4, 6].includes(colour) || ![1, 2, 4, 8].includes(depth) || (colour !== 0 && colour !== 3 && depth !== 8)
+        || view.getUint8(offset + 18) !== 0 || view.getUint8(offset + 19) !== 0 || view.getUint8(offset + 20) > 1) throw new Error('Unsupported PNG encoding');
+    } else if (type === 0x49484452) throw new Error('Duplicate PNG dimensions');
+    if (type === 0x6163544c || type === 0x6663544c || type === 0x66644154) throw new Error('Animated PNG is not a still image');
+    // Compressed metadata can expand independently of the admitted pixel envelope.
+    if ([0x69434350, 0x7a545874, 0x69545874].includes(type)) throw new Error('Compressed PNG metadata is not admitted');
+    if ((view.getUint8(offset + 4) & 32) === 0 && ![0x49484452, 0x504c5445, 0x49444154, 0x49454e44].includes(type)) throw new Error('Unknown critical PNG chunk');
+    if (crc(view, offset + 4, end - 4) !== view.getUint32(end - 4)) throw new Error('PNG chunk checksum differs');
+    if (type === 0x49444154) { if (endedData) throw new Error('Noncontiguous PNG image data'); data = true; }
+    else if (data) endedData = true;
+    if (type === 0x49454e44) {
+      if (length !== 0 || !data || end !== bytes.length) throw new Error('Invalid PNG end');
+      return envelope(bytes, 'image/png', width, height);
+    }
+    offset = end;
+  }
+  throw new Error('PNG has no bounded complete image');
+}
+
+function jpeg(bytes: Uint8Array, view: DataView): StillImage {
+  let offset = 2, width = 0, height = 0, scans = 0, markers = 0;
+  while (offset < bytes.length && ++markers <= STILL_IMAGE_LIMITS.chunks) {
+    if (view.getUint8(offset++) !== 0xff) throw new Error('Invalid JPEG marker');
+    while (offset < bytes.length && view.getUint8(offset) === 0xff) offset++;
+    const marker = view.getUint8(offset++);
+    if (marker === 0xd9) {
+      if (offset !== bytes.length || scans === 0) throw new Error('Invalid JPEG end');
+      return envelope(bytes, 'image/jpeg', width, height);
+    }
+    if (marker === 0xd8 || marker === 0 || marker === 1 || marker >= 0xd0 && marker <= 0xd7) throw new Error('Unexpected JPEG marker');
+    const length = view.getUint16(offset), end = offset + length;
+    if (length < 2 || end > bytes.length) throw new Error('Truncated JPEG segment');
+    if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+      if (![0xc0, 0xc1, 0xc2].includes(marker) || width !== 0 || length < 8 || view.getUint8(offset + 2) !== 8) throw new Error('Unsupported JPEG frame');
+      height = view.getUint16(offset + 3); width = view.getUint16(offset + 5);
+      const components = view.getUint8(offset + 7);
+      if (![1, 3, 4].includes(components) || length !== 8 + components * 3) throw new Error('Invalid JPEG components');
+    }
+    offset = end;
+    if (marker === 0xda) {
+      if (width === 0) throw new Error('JPEG scan precedes its frame');
+      scans++;
+      // Entropy bytes may stuff FF00 or contain restart markers. Other markers end this scan.
+      while (offset + 1 < bytes.length) {
+        if (view.getUint8(offset) !== 0xff) { offset++; continue; }
+        const next = view.getUint8(offset + 1);
+        if (next === 0 || next >= 0xd0 && next <= 0xd7) offset += 2; else break;
+      }
+    }
+  }
+  throw new Error('JPEG has no bounded complete image');
+}
+
+function webp(bytes: Uint8Array, view: DataView): StillImage {
+  if (view.getUint32(4, true) + 8 !== bytes.length) throw new Error('Invalid WebP RIFF length');
+  let offset = 12, width = 0, height = 0, chunks = 0, images = 0, extended = false;
+  const u24 = (at: number): number => view.getUint8(at) + view.getUint8(at + 1) * 256 + view.getUint8(at + 2) * 65536;
+  while (offset + 8 <= bytes.length && ++chunks <= STILL_IMAGE_LIMITS.chunks) {
+    const type = view.getUint32(offset), length = view.getUint32(offset + 4, true), at = offset + 8, end = at + length;
+    if (end > bytes.length) throw new Error('Truncated WebP chunk');
+    if (type === 0x414e494d || type === 0x414e4d46) throw new Error('Animated WebP is not a still image');
+    if (type === 0x56503858) {
+      if (chunks !== 1 || length !== 10 || (view.getUint8(at) & 0xc3) !== 0 || view.getUint8(at + 1) + view.getUint8(at + 2) + view.getUint8(at + 3) !== 0) throw new Error('Invalid or animated WebP extension');
+      width = u24(at + 4) + 1; height = u24(at + 7) + 1; extended = true;
+    }
+    if (type === 0x56503820 || type === 0x5650384c) {
+      if (++images !== 1) throw new Error('Multiple WebP images');
+      let w: number, h: number;
+      if (type === 0x56503820) {
+        if (length < 10 || (view.getUint8(at) & 1) !== 0 || view.getUint8(at + 3) !== 0x9d || view.getUint8(at + 4) !== 1 || view.getUint8(at + 5) !== 0x2a) throw new Error('Invalid WebP key frame');
+        w = view.getUint16(at + 6, true) & 0x3fff; h = view.getUint16(at + 8, true) & 0x3fff;
+      } else {
+        if (length < 5 || view.getUint8(at) !== 0x2f || (view.getUint8(at + 4) & 0xe0) !== 0) throw new Error('Invalid lossless WebP frame');
+        const bits = view.getUint32(at + 1, true); w = (bits & 0x3fff) + 1; h = ((bits >>> 14) & 0x3fff) + 1;
+      }
+      if (extended && (width !== w || height !== h)) throw new Error('WebP canvas differs from its image');
+      width = w; height = h;
+    }
+    offset = end + (length % 2);
+  }
+  if (offset !== bytes.length || images !== 1) throw new Error('WebP has no bounded complete image');
+  return envelope(bytes, 'image/webp', width, height);
+}
+
+/** Admit image blobs, including wide texture strips: at most 8192 per dimension,
+ * 4096² pixels and 4 MiB wire. PNG/JPEG/WebP header and animation rules stay shared. */
+export function parseImageAsset(bytes: Uint8Array): StillImage {
+  if (bytes.length < 12 || bytes.length > STILL_IMAGE_LIMITS.bytes) throw new Error('Still image wire exceeds admission bounds');
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (view.getUint32(0) === 0x89504e47 && view.getUint32(4) === 0x0d0a1a0a) return png(bytes, view);
+  if (view.getUint16(0) === 0xffd8) return jpeg(bytes, view);
+  if (view.getUint32(0) === 0x52494646 && view.getUint32(8) === 0x57454250) return webp(bytes, view);
+  throw new Error('Only bounded PNG, JPEG and WebP still images are admitted');
+}
+
+/** Title images keep the stricter 4096-per-dimension cap before browser decoding. */
+export function parseStillImage(bytes: Uint8Array): StillImage {
+  const image = parseImageAsset(bytes);
+  if (image.width > STILL_IMAGE_LIMITS.dimension || image.height > STILL_IMAGE_LIMITS.dimension) throw new Error('Still image dimensions exceed admission bounds');
+  return image;
+}

package/src/format/streamedCover.ts

@@ -0,0 +1,105 @@
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+
+const finite = v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(1e7));
+const positive = v.pipe(finite, v.minValue(0.0001));
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(256));
+const span = v.pipe(v.tuple([finite, positive]), v.check(([lo, hi]) => lo < hi));
+const tier = v.strictObject({ phone: positive, desktop: positive });
+const cap = v.pipe(finite, v.integer(), v.minValue(1), v.maxValue(1e6));
+/** Client-only cover streams. Density/placement is baked in version-1 cells; rows set capacity,
+ * reach/fade bands, far stand-ins, slope response, graph ids and upload budgets. Geometry keys
+ * resolve in the platform's SceneHandles, never in a shard callback or subclass. */
+export const StreamedCoverSchema: v.GenericSchema<StreamedCoverRowInput, StreamedCoverRow> = v.pipe(v.unknown(), v.check(isJsonData, 'Cover requires plain JSON'),
+  v.object({ cell: v.pipe(positive, v.integer()), refill: positive, cacheMin: cap, growShare: v.pipe(positive, v.maxValue(1)),
+    farRefill: positive, farSlack: positive, farIn: positive, eyeSlack: finite, uploadBytes: cap, nearLag: positive,
+    look: id, meshPrefix: id, lighting: id, params: v.strictObject({ reach: id, lodReach: id, mode: id, keep: id, viewer: id, slope: id, growIn: id }), reachK: tier, capK: tier, farBudgetMs: tier,
+    slopeReach: v.pipe(v.strictObject({ up: v.pipe(positive, v.minValue(1)), lo: finite, hi: positive, fadeFrom: finite, fadeTo: positive }),
+      v.check(row => row.lo < row.hi && row.fadeFrom < row.fadeTo)),
+    kinds: v.pipe(v.array(v.strictObject({ name: id, geometry: id, cap, reach: span, scale: span,
+      far: v.exactOptional(v.strictObject({ geometry: id, reach: span, cap, keep: v.pipe(positive, v.maxValue(1)) })) })),
+      v.minLength(1), v.maxLength(32), v.check(rows => new Set(rows.map(row => row.name)).size === rows.length)),
+  }), v.check(row => row.nearLag < row.refill && row.kinds.every(kind => (Math.max(kind.cap, (kind.far?.cap ?? 0) * (kind.far?.keep ?? 1))) * Math.max(row.capK.phone, row.capK.desktop) <= 1e6)));
+
+export function parseStreamedCover(input: unknown): StreamedCoverRow { return v.parse(StreamedCoverSchema, input); }
+
+/** The original placed log companion and cover root metadata, validated as one named blob. */
+const text = v.pipe(v.string(), v.maxLength(512));
+export const CoverCompositionSchema: v.GenericSchema<CoverCompositionRowsInput, CoverCompositionRows> = v.strictObject({ name: text, placement: text, mesh: text, userData: v.record(text, v.boolean()) });
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type StreamedCoverRowInput = unknown;
+interface StreamedCoverRowFields {
+    cell: number;
+    refill: number;
+    cacheMin: number;
+    growShare: number;
+    farRefill: number;
+    farSlack: number;
+    farIn: number;
+    eyeSlack: number;
+    uploadBytes: number;
+    nearLag: number;
+    look: string;
+    meshPrefix: string;
+    lighting: string;
+    params: {
+        reach: string;
+        lodReach: string;
+        mode: string;
+        keep: string;
+        viewer: string;
+        slope: string;
+        growIn: string;
+    };
+    reachK: {
+        phone: number;
+        desktop: number;
+    };
+    capK: {
+        phone: number;
+        desktop: number;
+    };
+    farBudgetMs: {
+        phone: number;
+        desktop: number;
+    };
+    slopeReach: {
+        up: number;
+        lo: number;
+        hi: number;
+        fadeFrom: number;
+        fadeTo: number;
+    };
+    kinds: ({
+        name: string;
+        geometry: string;
+        cap: number;
+        reach: [
+            number,
+            number
+        ];
+        scale: [
+            number,
+            number
+        ];
+        far?: {
+            geometry: string;
+            reach: [
+                number,
+                number
+            ];
+            cap: number;
+            keep: number;
+        };
+    })[];
+}
+export type StreamedCoverRow = { [Key in keyof StreamedCoverRowFields]: StreamedCoverRowFields[Key] };
+export type CoverCompositionRowsInput = CoverCompositionRows;
+interface CoverCompositionRowsFields {
+    name: string;
+    placement: string;
+    mesh: string;
+    userData: Record<string, boolean>;
+}
+export type CoverCompositionRows = { [Key in keyof CoverCompositionRowsFields]: CoverCompositionRowsFields[Key] };

package/src/format/surfaceLooks.ts

@@ -0,0 +1,50 @@
+/**
+ * Surface look rows (SHARD-PLATFORM SF72, look-family rows; DS1.1): the pure row contracts of the small, named
+ * decorations a shard chains onto a standard material. A shard lists its rows in its own `data/`; the game's
+ * `@wildshard/game/systems/looks/surfaceLooks` `applySurfaceLooks` installs them (each family's GLSL lives there). The
+ * families:
+ *
+ * - `firelight`: each burning fire of a shared firelight uniform warms the surface within `reach` metres, falling off as
+ *   `(1 - d / reach) ^ falloff`;
+ * - `viewerLight`: the viewer-side light of a held part and a glancing sheen at the silhouette;
+ * - `leather`: creases and a pebbled grain in the model's own space, as albedo and as a bump on the normal;
+ * - `stoneBand`: the model below a height redrawn as rows of irregular fieldstones with mortar between (a plinth);
+ * - `desaturate`: the map's colour pulled toward its own luma.
+ */
+
+/** RGB, linear. */
+export type SurfaceRgb = readonly [number, number, number];
+
+/** Fires warm the surface: `colour` × each fire's gain × `(1 - d / reach) ^ falloff` × `gain`. */
+export interface FirelightLook { readonly kind: 'firelight'; readonly colour: SurfaceRgb; readonly reach: number; readonly falloff: number; readonly gain: number }
+/**
+ * The eye's own light on a held part: `gain` × (`facing[0]` + `facing[1]` × the face's turn to the eye) × (1 + `dusk` ×
+ * the dusk uniform), and a sheen of `sheenColour` × `sheen` × (1 - turn) ^ `sheenPower`, damped by roughness × `sheenDamp`.
+ */
+export interface ViewerLightLook {
+  readonly kind: 'viewerLight'; readonly gain: SurfaceRgb; readonly facing: readonly [number, number]; readonly dusk: number;
+  readonly sheen: number; readonly sheenColour: SurfaceRgb; readonly sheenPower: number; readonly sheenDamp: number;
+}
+/**
+ * Leather in model space: creases (`crease` frequencies per axis, sharpened by `sharpness`) and a grain (`grain`), mixed
+ * `mix[0]` / `mix[1]`; the albedo darkens to `albedo[0]` + `albedo[1]` × (1 - height); the bump is `depth` view metres.
+ */
+export interface LeatherLook {
+  readonly kind: 'leather'; readonly crease: SurfaceRgb; readonly sharpness: number; readonly grain: number;
+  readonly mix: readonly [number, number]; readonly albedo: readonly [number, number]; readonly depth: number;
+}
+/**
+ * Fieldstones below model height `below` (a smoothstep from `below[0]` to `below[1]`): `rows` rows per model unit, wavy by
+ * `wave` (cycles round, amplitude), `perRow` stones a row (base + a per-row spread), mortar where a stone's edge is within
+ * `mortar` (aspect `aspect`), each stone between `dark` and `light`, speckled `speckle` at `speckleScale`.
+ */
+export interface StoneBandLook {
+  readonly kind: 'stoneBand'; readonly below: readonly [number, number]; readonly rows: number; readonly wave: readonly [number, number];
+  readonly perRow: readonly [number, number]; readonly mortar: readonly [number, number]; readonly aspect: number;
+  readonly dark: SurfaceRgb; readonly light: SurfaceRgb; readonly speckle: readonly [number, number]; readonly speckleScale: number; readonly mortarColour: SurfaceRgb;
+}
+/** The map's colour pulled `amount` of the way to its own luma (Rec. 709). */
+export interface DesaturateLook { readonly kind: 'desaturate'; readonly amount: number }
+
+/** One declared surface look. */
+export type SurfaceLook = FirelightLook | ViewerLightLook | LeatherLook | StoneBandLook | DesaturateLook;

package/src/format/tar-fields.ts

@@ -0,0 +1,54 @@
+// Where ustar keeps each header field, for the reader and writer in `tar.ts`.
+
+const BLOCK = 512
+const NAME = { at: 0, length: 100 }
+const MODE = { at: 100, length: 8 }
+const OWNER = { at: 108, length: 8 }
+const GROUP = { at: 116, length: 8 }
+const SIZE = { at: 124, length: 12 }
+const TIME = { at: 136, length: 12 }
+const CHECKSUM = { at: 148, length: 8 }
+const TYPE_AT = 156
+const MAGIC = { at: 257, length: 5 }
+const USTAR_VERSION = { at: 263, length: 2 }
+const PREFIX = { at: 345, length: 155 }
+
+const SPACE = 32
+const START = 0
+
+interface TarField {
+  readonly at: number
+  readonly length: number
+}
+
+/** The header's checksum, with its own field counted as spaces. */
+function checksum(block: Readonly<Uint8Array>): number {
+  const end = CHECKSUM.at + CHECKSUM.length
+  return block.reduce(
+    (total: number, byte: number, index: number): number =>
+      total + (index >= CHECKSUM.at && index < end ? SPACE : byte),
+    START,
+  )
+}
+
+function padded(size: number): number {
+  return Math.ceil(size / BLOCK) * BLOCK
+}
+
+export type { TarField }
+export {
+  BLOCK,
+  CHECKSUM,
+  GROUP,
+  MAGIC,
+  MODE,
+  NAME,
+  OWNER,
+  PREFIX,
+  SIZE,
+  TIME,
+  TYPE_AT,
+  USTAR_VERSION,
+  checksum,
+  padded,
+}