@wildshard/shard-format 0.0.1 → 0.4.5

package/src/format/skinAssets.ts

@@ -0,0 +1,107 @@
+/**
+ * Exported skins as creature looks (SHARD-PLATFORM SF16, the format half of the creature seam). A look row whose recipe
+ * is `platform.skin` draws its species with an SF9c exported skin instead of a procedural view recipe:
+ *
+ *   { id, species, recipe: 'platform.skin', material: null, parameters: { skin: '<json file hash>' },
+ *     animation: { recipe: 'platform.clips', parameters: { attackSpan: 1 } } }
+ *
+ * `skin` names a `json` file (`ShardSkinFileSchema`: the export's rig row and its binding) whose one dependency is the
+ * skin's `glb` file. Both sit in the library closure, so the loader admits, leases and charges them as declared. The
+ * clips are chosen from the creature's state (idle / walk / attack / hit / die, `idle.graze` when grazing);
+ * `attackSpan` is the attack duration the export sampled the attack clip with (seconds).
+ */
+import * as v from 'valibot';
+import { parseSkinBindings, parseSkinRows, validateCreatureBones, type SkinBinding, type SkinRow } from './skinData.ts';
+import type { ShardRows } from './rows.ts';
+import type { Shardfile } from './shardSchema.ts';
+import { parseGlbData as parseGlb } from './glbCost.ts';
+import { skinLayerDecoded } from './skinLayers.ts';
+import { MaterialsSchema } from './materials.ts';
+import { SkinGlbMaterialsSchema, SkinPrimitiveSchema, skinMaterialsFault, skinPartsFault, skinPrimitiveCount } from './skin-materials.ts';
+
+import { SKIN_LOOK_RECIPE, SKIN_CLIPS_RECIPE, SkinLookParametersSchema, SkinClipParametersSchema, ShardSkinFileSchema, type SkinLookParameters } from './skins.ts';
+
+/** Parse a `platform.skin` look row's parameters (throws on anything else). */
+export function skinLookParameters(row: ShardRows['looks'][number]): SkinLookParameters {
+  if (row.recipe !== SKIN_LOOK_RECIPE) throw new Error(`look ${row.id}: not a skin look`);
+  if (row.animation.recipe !== SKIN_CLIPS_RECIPE) throw new Error(`look ${row.id}: a skin look animates with ${SKIN_CLIPS_RECIPE}`);
+  const look = v.safeParse(SkinLookParametersSchema, row.parameters), clips = v.safeParse(SkinClipParametersSchema, row.animation.parameters);
+  if (!look.success || !clips.success) throw new Error(`look ${row.id}: invalid skin parameters`);
+  return { skin: look.output.skin, attackSpan: clips.output.attackSpan };
+}
+/** Decode and validate one skin file's bytes: its rig row and binding, the binding for that row. */
+export function parseSkinFile(bytes: Uint8Array): { row: SkinRow; binding: SkinBinding } {
+  const file = v.parse(ShardSkinFileSchema, JSON.parse(new TextDecoder().decode(bytes)));
+  const [row] = parseSkinRows([file.row]); if (row === undefined) throw new Error('skin file: no row');
+  const [binding] = parseSkinBindings([file.binding], [row]); if (binding === undefined) throw new Error('skin file: no binding');
+  return { row, binding };
+}
+/** Shardfile reference rules for skin looks: a library `json` file whose dependencies are exactly its row's `glb`. */
+export function skinLookRules(source: Pick<Shardfile, 'rows' | 'files' | 'library'>): string[] {
+  const errors: string[] = [], files = new Map(source.files.map((file) => [file.hash, file]));
+  for (const row of source.rows.looks) {
+    if (row.recipe !== SKIN_LOOK_RECIPE) { if (row.animation.recipe === SKIN_CLIPS_RECIPE) errors.push('skin clips without a skin look'); continue; }
+    let skin: string; try { skin = skinLookParameters(row).skin; } catch { errors.push('skin look parameters'); continue; }
+    const file = files.get(skin), glb = file?.dependencies.length === 1 ? files.get(file.dependencies[0] ?? '') : undefined;
+    if (file?.kind !== 'json' || glb?.kind !== 'glb' || !source.library.includes(skin)) errors.push('skin look file references');
+  }
+  return errors;
+}
+
+const glbRigSchema = v.object({
+  nodes: v.array(v.object({ name: v.optional(v.string()), mesh: v.optional(v.number()), skin: v.optional(v.number()) })),
+  meshes: v.array(v.object({ primitives: v.array(SkinPrimitiveSchema) })),
+  materials: SkinGlbMaterialsSchema,
+  skins: v.array(v.object({ joints: v.array(v.number()) })),
+  animations: v.optional(v.array(v.object({ name: v.optional(v.string()) })), []),
+});
+
+/** Check admitted GLB joint order, sockets and clips before a renderer allocates the creature view. */
+function validateRigBytes(glb: Uint8Array, row: SkinRow, parts: Readonly<Record<string, string>> | undefined): void {
+  // parseGlb already bounds and validates the header, JSON chunk and every node/accessor reference.
+  const length = new DataView(glb.buffer, glb.byteOffset, glb.byteLength).getUint32(12, true);
+  const rig = v.parse(glbRigSchema, JSON.parse(new TextDecoder().decode(glb.subarray(20, 20 + length))));
+  function fail(reason: string): never { throw new Error(`skin ${row.id}: ${reason}`); }
+  const named = rig.nodes.flatMap(node => node.name === undefined ? [] : [node.name]);
+  const meshes = rig.nodes.filter(node => node.skin !== undefined && node.mesh !== undefined);
+  const mesh = meshes[0];
+  if (meshes.length !== 1 || mesh?.mesh === undefined || mesh.skin === undefined
+    || !skinPrimitiveCount(rig.meshes[mesh.mesh]?.primitives.length)) fail('expected one skinned mesh');
+  const partsFault = skinPartsFault(rig.meshes[mesh.mesh]?.primitives ?? [], rig.materials, parts);
+  if (partsFault !== '') { fail(partsFault); }
+  const joints = rig.skins[mesh.skin]?.joints.map(index => rig.nodes[index]?.name);
+  const expected = row.rig.joints[0];
+  if (joints === undefined || expected === undefined || joints.length !== expected.length
+    || joints.some((name, index) => name !== expected[index])) fail('skin joint order differs from bake');
+  for (const name of row.rig.sockets) {
+    if (named.filter(actual => actual === name).length !== 1) fail(`missing or ambiguous socket ${name}`);
+  }
+  for (const name of row.rig.clips) {
+    if (rig.animations.filter(clip => clip.name === name).length !== 1) fail(`missing or ambiguous clip ${name}`);
+  }
+}
+
+/** Admit each rig binding and its exact GLB dependency before allocating a client view. */
+export function validateSkinAssets(source: Pick<Shardfile, 'rows' | 'files'> & { readonly look?: Pick<Shardfile['look'], 'materials'> }, assets: ReadonlyMap<string, Uint8Array>): void {
+  const files = new Map(source.files.map((file) => [file.hash, file]));
+  for (const look of source.rows.looks) {
+    if (look.recipe !== SKIN_LOOK_RECIPE) continue;
+    const skinHash = skinLookParameters(look).skin, bytes = assets.get(skinHash);
+    if (bytes === undefined) throw new Error('skin file missing');
+    const { row, binding } = parseSkinFile(bytes);
+    if (files.get(skinHash)?.dependencies[0] !== row.file) throw new Error('skin rig dependency mismatch');
+    validateCreatureBones(look.species, row.rig.sockets);
+    validateCreatureBones(look.species, row.rig.joints[0] ?? []);
+    v.parse(MaterialsSchema, { skin: binding.material });
+    const glb = assets.get(row.file), declared = files.get(row.file);
+    if (glb === undefined || declared === undefined) throw new Error('skin GLB missing');
+    const cost = parseGlb(glb);
+    validateRigBytes(glb, row, binding.materials);
+    const undeclared = skinMaterialsFault(binding.materials, source.look?.materials ?? {});
+    if (undeclared !== '') { throw new Error(undeclared); }
+    cost.decoded += skinLayerDecoded(binding.poseLayers ?? {}, row.rig.joints[0]?.length ?? 0);
+    for (const key of ['decoded', 'gpu', 'triangles', 'draws'] as const) {
+      if (cost[key] > row.cost[key] || cost[key] > declared[key]) throw new Error('skin cost understated');
+    }
+  }
+}

package/src/format/skinData.ts

@@ -0,0 +1,110 @@
+import * as v from 'valibot';
+import { SkinPoseLayerSchema, validateSkinLayers } from './skinLayers.ts';
+import { SkinMaterialsSchema } from './skin-materials.ts';
+/** Animation clip identity; the native rig uses the same bounded family namespace. */
+export type SkinClipName = `${'idle' | 'walk' | 'run' | 'attack' | 'hit' | 'die' | 'turn' | 'swim' | 'fly'}${'' | `.${string}`}`;
+
+const id = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u), v.maxLength(128));
+const hash = v.pipe(v.string(), v.regex(/^[0-9a-f]{64}$/u));
+/** Admitted clip family and optional lowercase action suffix; its transform is an identity type narrowing. */
+export const SkinClipNameSchema: v.GenericSchema<SkinClipNameRowsInput, SkinClipNameRows> & { readonly pipe: readonly [unknown, unknown, v.TransformAction<string, SkinClipName>] } = v.pipe(v.string(), v.regex(/^(idle|walk|run|attack|hit|die|turn|swim|fly)(\.[a-z][a-z0-9-]*)?$/u), v.transform((name) => name as SkinClipName));
+const joint = v.pipe(v.string(), v.regex(/^[A-Za-z][A-Za-z0-9_.-]*$/u), v.maxLength(64));
+const bytes = v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(25_000_000));
+
+/** One exported skin as the export half writes it (`public/assets/baked/<shard>/skins.json`): the GLB's content hash and its rig. */
+export const SkinRowSchema: v.GenericSchema<SkinRowInput, SkinRow> = v.object({
+  id, file: hash, family: v.picklist(['toon', 'pbr']),
+  rig: v.strictObject({ skeleton: v.pipe(v.string(), v.regex(/^[a-z][A-Za-z0-9.]*$/u), v.maxLength(128)), joints: v.pipe(v.array(v.pipe(v.array(joint), v.minLength(1), v.maxLength(128))), v.length(1)), clips: v.pipe(v.array(SkinClipNameSchema), v.minLength(1), v.maxLength(32)), sockets: v.pipe(v.array(joint), v.maxLength(32)) }),
+  cost: v.strictObject({ decoded: bytes, gpu: bytes, triangles: v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(400_000)), draws: v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(512)) }),
+});
+/** A validated exported skin row. */
+
+/** How a skin plays and draws: the family material entry (SF10a, validated by the family registry) the clips that loop and independent numeric pose clocks; `materials` (TE-ENG10) maps GLB material names to look materials (`./skin-materials`). */
+export const SkinBindingSchema: v.GenericSchema<SkinBindingInput, SkinBinding> = v.strictObject({ skin: id, material: v.record(v.string(), v.unknown()), materials: v.exactOptional(SkinMaterialsSchema), loops: v.pipe(v.array(SkinClipNameSchema), v.maxLength(32)), poseLayers: v.exactOptional(v.record(SkinClipNameSchema, v.pipe(v.array(SkinPoseLayerSchema), v.maxLength(32)))) });
+/** A validated skin binding. */
+
+
+/** Every creature kind, including flying/custom rigs, exposes body and head for collision and view binding. */
+export function validateCreatureBones(species: string, names: readonly string[]): void {
+  for (const bone of ['body', 'head']) {
+    if (!names.includes(bone)) throw new Error(`species '${species}': rig missing required bone '${bone}'`);
+  }
+}
+
+/** Validate the export half's rows; unknown fields (its notes and motion receipt) are ignored. */
+export function parseSkinRows(input: unknown): SkinRow[] {
+  const r = v.safeParse(v.pipe(v.array(SkinRowSchema), v.maxLength(256)), input);
+  if (!r.success) throw new Error(`skins: ${r.issues.map((i) => `${v.getDotPath(i) ?? '(root)'}: ${i.message}`).join('; ')}`);
+  if (new Set(r.output.map((row) => row.id)).size !== r.output.length) throw new Error('skins: unique ids');
+  return r.output;
+}
+/** Validate skin bindings against their rows: one per skin, loops only over the row's clips, with bounded periodic layer tables. */
+export function parseSkinBindings(input: unknown, rows: readonly SkinRow[]): SkinBinding[] {
+  const r = v.safeParse(v.pipe(v.array(SkinBindingSchema), v.maxLength(256)), input);
+  if (!r.success) throw new Error(`skin bindings: ${r.issues.map((i) => `${v.getDotPath(i) ?? '(root)'}: ${i.message}`).join('; ')}`);
+  for (const binding of r.output) {
+    const row = rows.find((candidate) => candidate.id === binding.skin);
+    if (row === undefined) throw new Error(`skin bindings: no skin ${binding.skin}`);
+    if (binding.loops.some((name) => !row.rig.clips.includes(name))) throw new Error(`skin bindings: ${binding.skin} loops an unknown clip`);
+    for (const [name, layers] of Object.entries(binding.poseLayers ?? {})) { if (layers === undefined) continue; if (!binding.loops.includes(name as SkinClipName)) throw new Error('skin layers require a looping base'); validateSkinLayers(layers, row.rig.joints[0] ?? []); }
+  }
+  if (new Set(r.output.map((binding) => binding.skin)).size !== r.output.length) throw new Error('skin bindings: one per skin');
+  return r.output;
+}
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type SkinClipNameRowsInput = string;
+export type SkinClipNameRows = SkinClipName;
+interface SkinRowInputFields {
+    id: string;
+    file: string;
+    family: 'toon' | 'pbr';
+    rig: {
+        skeleton: string;
+        joints: ((string)[])[];
+        clips: (SkinClipNameRowsInput)[];
+        sockets: (string)[];
+    };
+    cost: {
+        decoded: number;
+        gpu: number;
+        triangles: number;
+        draws: number;
+    };
+}
+export type SkinRowInput = { [Key in keyof SkinRowInputFields]: SkinRowInputFields[Key] };
+interface SkinRowFields {
+    id: string;
+    file: string;
+    family: 'toon' | 'pbr';
+    rig: {
+        skeleton: string;
+        joints: ((string)[])[];
+        clips: (SkinClipNameRows)[];
+        sockets: (string)[];
+    };
+    cost: {
+        decoded: number;
+        gpu: number;
+        triangles: number;
+        draws: number;
+    };
+}
+export type SkinRow = { [Key in keyof SkinRowFields]: SkinRowFields[Key] };
+interface SkinBindingInputFields {
+    skin: string;
+    material: Record<string, unknown>;
+    materials?: Record<string, string>;
+    loops: (SkinClipNameRowsInput)[];
+    poseLayers?: v.InferInput<v.RecordSchema<v.GenericSchema<SkinClipNameRowsInput, SkinClipNameRows>, v.GenericSchema<(v.InferInput<typeof SkinPoseLayerSchema>)[], (v.InferOutput<typeof SkinPoseLayerSchema>)[]>, undefined>>;
+}
+export type SkinBindingInput = { [Key in keyof SkinBindingInputFields]: SkinBindingInputFields[Key] };
+interface SkinBindingFields {
+    skin: string;
+    material: Record<string, unknown>;
+    materials?: Record<string, string>;
+    loops: (SkinClipNameRows)[];
+    poseLayers?: v.InferOutput<v.RecordSchema<v.GenericSchema<SkinClipNameRowsInput, SkinClipNameRows>, v.GenericSchema<(v.InferInput<typeof SkinPoseLayerSchema>)[], (v.InferOutput<typeof SkinPoseLayerSchema>)[]>, undefined>>;
+}
+export type SkinBinding = { [Key in keyof SkinBindingFields]: SkinBindingFields[Key] };

package/src/format/skinLayers.ts

@@ -0,0 +1,90 @@
+import * as v from 'valibot';
+
+const finite = v.pipe(v.number(), v.finite());
+// Copy bounded sample tables once; per-number schema datasets otherwise dominate skin admission allocations.
+function samples(minimum: number, maximum: number): PoseSamples {
+  return v.pipe(v.unknown(), v.rawTransform(({ dataset, addIssue, NEVER }): number[] => {
+    const input = dataset.value;
+    if (!Array.isArray(input) || input.length < minimum || input.length > maximum) {
+      addIssue({ message: 'Skin sample array outside cap' }); return NEVER;
+    }
+    const length = input.length, output: number[] = []; output.length = length;
+    for (let index = 0; index < length; index++) {
+      const value: unknown = input[index];
+      if (typeof value !== 'number' || !Number.isFinite(value)) {
+        addIssue({ message: 'Skin sample must be finite', path: [{ type: 'array', origin: 'value', input, key: index, value }] }); return NEVER;
+      }
+      output[index] = value;
+    }
+    return output;
+  }));
+}
+const trackSchema: v.StrictObjectSchema<PoseTrackEntries, undefined> = v.strictObject({ bone: v.pipe(v.string(), v.maxLength(64)), property: v.picklist(['position', 'rotation', 'scale', 'quaternion']), axis: v.picklist(['x', 'y', 'z']), order: v.picklist(['XYZ', 'YXZ', 'ZXY', 'ZYX', 'YZX', 'XZY']), values: samples(0, 300000) });
+/** Independent sampled clocks supplement a base clip; optional phase tables preserve coupled gait and breath. */
+export const SkinPoseLayerSchema: v.StrictObjectSchema<{ readonly id: v.GenericSchema<SkinPoseLayerInput['id'], SkinPoseLayer['id']>; readonly period: v.GenericSchema<SkinPoseLayerInput['period'], SkinPoseLayer['period']>; readonly times: PoseSamples; readonly phasePeriod: v.GenericSchema<SkinPoseLayerInput['phasePeriod'], SkinPoseLayer['phasePeriod']>; readonly phaseSteps: v.GenericSchema<SkinPoseLayerInput['phaseSteps'], SkinPoseLayer['phaseSteps']>; readonly tracks: v.SchemaWithPipe<readonly [v.ArraySchema<typeof trackSchema, undefined>, v.MaxLengthAction<v.InferOutput<typeof trackSchema>[], 128, undefined>]>; }, undefined> = v.strictObject({ id: v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u), v.maxLength(128)), period: v.pipe(finite, v.minValue(0.01), v.maxValue(120)), times: samples(2, 4097), phasePeriod: v.pipe(finite, v.minValue(0.01), v.maxValue(120)), phaseSteps: v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(64)), tracks: v.pipe(v.array(trackSchema), v.maxLength(128)) });
+/** Callback-free pose samples, bounded and owned by the skin binding. */
+
+/** Validate table sizes, periodic endpoints and joint references before compiling float buffers. */
+export function validateSkinLayers(layers: readonly SkinPoseLayer[], joints: readonly string[]): void {
+  let numbers = 0;
+  if (layers.length > 32 || new Set(layers.map((layer) => layer.id)).size !== layers.length) throw new Error('skin layers identities');
+  for (const layer of layers) {
+    if (layer.times[0] !== 0 || Math.abs((layer.times.at(-1) ?? 0) - layer.period) > 1e-6 || layer.times.some((time, i) => i > 0 && time <= (layer.times[i - 1] ?? 0))) throw new Error('skin layer times');
+    const phase = layer.phaseSteps + 1;
+    for (const t of layer.tracks) {
+      const width = t.property === 'quaternion' ? 4 : 1;
+      if (!joints.includes(t.bone) || t.values.length !== layer.times.length * phase * width || (layer.phaseSteps > 0 && width !== 4)) throw new Error('skin layer shape');
+      numbers += t.values.length;
+      for (let p = 0; p < phase * width; p++) if (Math.abs((t.values[p] ?? 0) - (t.values[(layer.times.length - 1) * phase * width + p] ?? 0)) > 1e-5) throw new Error('skin layer seam');
+      if (layer.phaseSteps > 0) for (let frame = 0; frame < layer.times.length; frame++) for (let component = 0; component < 4; component++) if (Math.abs((t.values[frame * phase * 4 + component] ?? 0) - (t.values[(frame * phase + phase - 1) * 4 + component] ?? 0)) > 1e-5) throw new Error('skin layer phase seam');
+      if (width === 4) for (let i = 0; i < t.values.length; i += 4) if (Math.abs(Math.hypot(t.values[i] ?? 0, t.values[i + 1] ?? 0, t.values[i + 2] ?? 0, t.values[i + 3] ?? 0) - 1) > 1e-5) throw new Error('skin layer quaternion');
+    }
+  }
+  if (numbers > 500000) throw new Error('skin layer sample cap');
+}
+
+/** Charge serialized tables, numeric arrays and per-state cached transforms before compiling layers. */
+export function skinLayerDecoded(layers: Readonly<Record<string, readonly SkinPoseLayer[] | undefined>>, joints: number): number {
+  let numbers = 0, states = 0;
+  for (const data of Object.values(layers)) { if (data === undefined) continue; states++; for (const layer of data) { numbers += layer.times.length; for (const t of layer.tracks) numbers += t.values.length; } }
+  if (states === 0) return 0;
+  return new TextEncoder().encode(JSON.stringify(layers)).length * 2 + numbers * 12 + joints * 80 * states;
+}
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+interface SkinPoseLayerInputFields {
+    id: string;
+    period: number;
+    times: unknown;
+    phasePeriod: number;
+    phaseSteps: number;
+    tracks: ({
+        bone: string;
+        property: 'position' | 'rotation' | 'scale' | 'quaternion';
+        axis: 'x' | 'y' | 'z';
+        order: 'XYZ' | 'YXZ' | 'ZXY' | 'ZYX' | 'YZX' | 'XZY';
+        values: unknown;
+    })[];
+}
+export type SkinPoseLayerInput = { [Key in keyof SkinPoseLayerInputFields]: SkinPoseLayerInputFields[Key] };
+interface SkinPoseLayerFields {
+    id: string;
+    period: number;
+    times: number[];
+    phasePeriod: number;
+    phaseSteps: number;
+    tracks: ({
+        bone: string;
+        property: 'position' | 'rotation' | 'scale' | 'quaternion';
+        axis: 'x' | 'y' | 'z';
+        order: 'XYZ' | 'YXZ' | 'ZXY' | 'ZYX' | 'YZX' | 'XZY';
+        values: number[];
+    })[];
+}
+export type SkinPoseLayer = { [Key in keyof SkinPoseLayerFields]: SkinPoseLayerFields[Key] };
+
+type PoseSamples = v.SchemaWithPipe<readonly [v.UnknownSchema, v.RawTransformAction<unknown, number[]>]>;
+type PoseTrackInput = SkinPoseLayerInput['tracks'][number];
+type PoseTrackOutput = SkinPoseLayer['tracks'][number];
+type PoseTrackEntries = { [Key in Exclude<keyof PoseTrackOutput, 'values'>]: v.GenericSchema<PoseTrackInput[Key], PoseTrackOutput[Key]> } & { readonly values: PoseSamples };

package/src/format/skins.ts

@@ -0,0 +1,37 @@
+import * as v from 'valibot';
+
+/** The look recipe for an exported skin, and its animation recipe. */
+export const SKIN_LOOK_RECIPE = 'platform.skin';
+/** The animation recipe that consumes the exported skin clip parameters. */
+export const SKIN_CLIPS_RECIPE = 'platform.clips';
+const hash = v.pipe(v.string(), v.regex(/^[0-9a-f]{64}$/u));
+/** The look row's parameters. */
+export const SkinLookParametersSchema: v.GenericSchema<SkinLookParametersRowsInput, SkinLookParametersRows> = v.strictObject({ skin: hash });
+/** The animation recipe's parameters. */
+export const SkinClipParametersSchema: v.GenericSchema<SkinClipParametersRowsInput, SkinClipParametersRows> = v.strictObject({ attackSpan: v.optional(v.pipe(v.number(), v.finite(), v.minValue(0.05), v.maxValue(10)), 1) });
+/** The content-addressed skin file: one export row and its binding (validated together by the SF9c parsers). */
+export const ShardSkinFileSchema: v.GenericSchema<ShardSkinFileRowsInput, ShardSkinFileRows> = v.strictObject({ row: v.unknown(), binding: v.unknown() });
+
+/** A parsed skin look: the file it names and the attack span its clip was sampled with. */
+export interface SkinLookParameters { skin: string; attackSpan: number }
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type SkinLookParametersRowsInput = SkinLookParametersRows;
+interface SkinLookParametersRowsFields {
+    skin: string;
+}
+export type SkinLookParametersRows = { [Key in keyof SkinLookParametersRowsFields]: SkinLookParametersRowsFields[Key] };
+interface SkinClipParametersRowsInputFields {
+    attackSpan?: number | undefined;
+}
+export type SkinClipParametersRowsInput = { [Key in keyof SkinClipParametersRowsInputFields]: SkinClipParametersRowsInputFields[Key] };
+interface SkinClipParametersRowsFields {
+    attackSpan: number;
+}
+export type SkinClipParametersRows = { [Key in keyof SkinClipParametersRowsFields]: SkinClipParametersRowsFields[Key] };
+export type ShardSkinFileRowsInput = ShardSkinFileRows;
+interface ShardSkinFileRowsFields {
+    row: unknown;
+    binding: unknown;
+}
+export type ShardSkinFileRows = { [Key in keyof ShardSkinFileRowsFields]: ShardSkinFileRowsFields[Key] };

package/src/format/socketLift.ts

@@ -0,0 +1,58 @@
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+
+const name = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u), v.maxLength(128));
+const coordinate = v.pipe(v.number(), v.finite(), v.minValue(-250), v.maxValue(250));
+const point = v.tuple([coordinate, coordinate, coordinate]);
+const approach = v.pipe(v.strictObject({
+  colliders: v.pipe(v.array(name), v.minLength(1), v.maxLength(32)),
+  route: v.pipe(v.array(point), v.minLength(2), v.maxLength(16)),
+}), v.check(row => new Set(row.colliders).size === row.colliders.length
+  && row.route.every(position => position[1] === 0 && Math.abs(position[0]) <= 240 && Math.abs(position[2]) <= 240),
+'unique static approach colliders and road-height route inside the ten metre inset'));
+/** A bounded entry ride names admitted mover/gate rows and feet-level stops; the route is walked, never teleported. */
+export const SocketLiftSchema: v.GenericSchema<SocketLiftInput, SocketLift> = v.pipe(v.strictObject({ mover: name, gate: name,
+  roadStop: point, topStop: point, route: v.pipe(v.array(point), v.minLength(2), v.maxLength(32)),
+  rideTicks: v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(3600)), approach: v.exactOptional(approach),
+}), v.check(row => row.mover !== row.gate && row.roadStop[1] === 0 && row.topStop[1] > 0
+  && row.route[0]?.every((value, axis) => value === row.topStop[axis]) === true,
+'socket lift requires distinct mover/gate, road height zero and an onward route starting at its top stop'));
+/** Data-only lift link; gameplay commands and physics remain platform-owned. */
+
+/** Parse without invoking an accessor or serializer from an author object. */
+export function parseSocketLift(input: unknown): SocketLift {
+  if (!isJsonData(input)) throw new Error('Socket lift must be JSON data only');
+  return v.parse(SocketLiftSchema, input);
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type SocketLiftInput = SocketLift;
+interface SocketLiftFields {
+    mover: string;
+    gate: string;
+    roadStop: [
+        number,
+        number,
+        number
+    ];
+    topStop: [
+        number,
+        number,
+        number
+    ];
+    route: ([
+        number,
+        number,
+        number
+    ])[];
+    rideTicks: number;
+    approach?: {
+        colliders: (string)[];
+        route: ([
+            number,
+            number,
+            number
+        ])[];
+    };
+}
+export type SocketLift = { [Key in keyof SocketLiftFields]: SocketLiftFields[Key] };

package/src/format/socketLiftAssets.ts

@@ -0,0 +1,81 @@
+import { ENTRY_WIDTH } from './contentBounds.ts';
+import { parseMovers, type MoverData } from './movers.ts';
+import { glbPoint, glbTransform } from './glbTriangles.ts';
+import { clipEntryPolygon, type EntryVertex } from './entryGeometry.ts';
+import { validateLiftApproach, type LiftApproachSource } from './liftApproach.ts';
+
+import { parseSocketLift, type SocketLift } from './socketLift.ts';
+
+/** An edge's declared lift; shared structural shape avoids a schema dependency cycle. */
+export interface SocketLiftEntry { edge: 'north' | 'east' | 'south' | 'west'; lift: SocketLift }
+/** Select declared lifts without treating an ordinary entry or a missing link as executable admission. */
+export function socketLiftEntries(entries: readonly { edge: SocketLiftEntry['edge']; kind?: string | undefined; lift?: SocketLift }[]): SocketLiftEntry[] {
+  return entries.flatMap(entry => {
+    if (entry.kind !== 'socketLift') return [];
+    if (entry.lift === undefined) throw new Error('Missing socket lift declaration');
+    return [{ edge: entry.edge, lift: entry.lift }];
+  });
+}
+
+function boxVertices(row: MoverData[number], stop: readonly [number, number, number]): EntryVertex[][] {
+  if (row.euler.x !== 0 || row.euler.y !== 0 || row.euler.z !== 0) throw new Error('Socket lift rests without rotation');
+  return row.boxes.map(box => {
+    const matrix = glbTransform({ translation: [stop[0] + box.x, stop[1] + box.y, stop[2] + box.z], rotation: [box.rot.x, box.rot.y, box.rot.z, box.rot.w] });
+    return Array.from({ length: 8 }, (_unused, index) => glbPoint(matrix, {
+      x: (index & 1) === 0 ? -box.hx : box.hx, y: (index & 2) === 0 ? -box.hy : box.hy, z: (index & 4) === 0 ? -box.hz : box.hz,
+    }));
+  });
+}
+function topTriangles(boxes: readonly EntryVertex[][]): EntryVertex[][] {
+  return boxes.flatMap(box => {
+    const a = box[2], b = box[3], c = box[6], d = box[7];
+    if (a === undefined || b === undefined || c === undefined || d === undefined) throw new Error('Missing lift box vertex');
+    return [[a, b, c], [d, c, b]];
+  });
+}
+function coversLine(triangles: readonly EntryVertex[][], edge: SocketLiftEntry['edge'], along: number, y: number): boolean {
+  const cross = edge === 'north' || edge === 'south' ? 'x' : 'z', half = ENTRY_WIDTH / 2;
+  const line = cross === 'x' ? { minX: -half, maxX: half, minZ: along, maxZ: along } : { minX: along, maxX: along, minZ: -half, maxZ: half };
+  const intervals = triangles.flatMap(triangle => {
+    const clipped = clipEntryPolygon(triangle, line);
+    if (clipped.length === 0 || clipped.some(vertex => Math.abs(vertex.y - y) > 1e-8)) return [];
+    return [[Math.min(...clipped.map(vertex => vertex[cross])), Math.max(...clipped.map(vertex => vertex[cross]))]];
+  }).sort((a, b) => (a[0] ?? 0) - (b[0] ?? 0));
+  let covered = -half;
+  for (const interval of intervals) {
+    const from = interval[0], to = interval[1]; if (from === undefined || to === undefined || from > covered + 1e-8) return false;
+    covered = Math.max(covered, to);
+  }
+  return covered >= half;
+}
+/** Before physics allocation, prove stable references and the real deck's complete road-height boarding line. */
+export function socketLiftRules(entries: readonly SocketLiftEntry[], input: MoverData, source?: LiftApproachSource): string[] {
+  const errors: string[] = [];
+  let movers: MoverData;
+  try { movers = parseMovers(input); } catch { return ['invalid socket lift mover declarations']; }
+  const ids = new Set<string>();
+  for (const entry of entries) {
+    try {
+      const lift = parseSocketLift(entry.lift), mover = movers.find(row => row.id === lift.mover), gate = movers.find(row => row.id === lift.gate);
+      if (ids.has(lift.mover) || ids.has(lift.gate)) throw new Error('Socket lift mover/gate belongs to one entry');
+      ids.add(lift.mover); ids.add(lift.gate);
+      if (mover?.kind !== 'platform' || !mover.enabled) throw new Error('Unknown or inactive socket lift mover');
+      if (gate === undefined || gate.kind === 'chain') throw new Error('Missing socket lift platform gate');
+      if (![mover.at.x, mover.at.y, mover.at.z].every((value, axis) => value === lift.roadStop[axis])) throw new Error('Socket lift must load at its road stop');
+      const boxes = boxVertices(mover, lift.roadStop), top = boxVertices(mover, lift.topStop);
+      if ([...boxes, ...top].flat().some(vertex => Math.abs(vertex.x) > 240 || Math.abs(vertex.z) > 240 || Math.abs(vertex.y) > 250)) throw new Error('Socket lift footprint must remain at least ten metres inside the cell');
+      const along = entry.edge === 'north' || entry.edge === 'east' ? 235 : -235;
+      // A maximum five-centimetre seam is admitted; the executable capsule proof still has to walk it.
+      const boardLine = along + (along > 0 ? -0.05 : 0.05);
+      if (lift.approach === undefined) {
+        if (!coversLine(topTriangles(boxes), entry.edge, boardLine, 0)) throw new Error('Socket lift road stop must cover the eight metre socket boarding line at height zero');
+      } else {
+        if (gate.kind !== 'static') throw new Error('Static approach requires a stationary road gate');
+        if (source === undefined) throw new Error('Missing static approach collider declarations');
+        validateLiftApproach({ edge: entry.edge, lift }, topTriangles(boxes), source);
+      }
+      if (lift.route.every(position => position.every((value, axis) => value === lift.topStop[axis]))) throw new Error('Socket lift needs an onward route to playable ground');
+    } catch (error) { errors.push(error instanceof Error ? error.message : 'Invalid socket lift'); }
+  }
+  return errors;
+}

package/src/format/socketRigCreature.ts

@@ -0,0 +1,66 @@
+import * as v from 'valibot';
+import { SpecimenModelMetadataSchema } from './specimenCatalogue.ts';
+
+/** A socket-dressed creature card: the existing model, coat and socket source rows. */
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(128)), n = v.pipe(v.number(), v.finite()), rgb = v.tuple([n, n, n]);
+const coat = v.strictObject({ id, label: id, weight: n, rarity: v.picklist(['common', 'uncommon', 'rare', 'legendary']), scale: v.tuple([n, n]),
+  hp: v.exactOptional(n), tint: v.exactOptional(v.pipe(v.record(id, rgb), v.maxEntries(32))),
+  traits: v.exactOptional(v.pipe(v.record(id, v.union([n, v.boolean(), id])), v.maxEntries(32))) });
+export const SocketRigCreatureSchema: v.GenericSchema<SocketRigCreatureRowsInput, SocketRigCreatureRows> = v.strictObject({
+  model: v.pick(SpecimenModelMetadataSchema, ['id', 'file', 'pipeline', 'surface']),
+  /** the product whose socket rig rows dress the card, and that rows file */
+  product: id, sockets: id,
+  kind: id, coat,
+});
+
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+interface SocketRigCreatureRowsInputFields {
+    model: Pick<v.InferInput<typeof SpecimenModelMetadataSchema>, 'id' | 'file' | 'pipeline' | 'surface'>;
+    product: string;
+    sockets: string;
+    kind: string;
+    coat: {
+        id: string;
+        label: string;
+        weight: number;
+        rarity: 'common' | 'uncommon' | 'rare' | 'legendary';
+        scale: [
+            number,
+            number
+        ];
+        hp?: number;
+        tint?: Record<string, [
+            number,
+            number,
+            number
+        ]>;
+        traits?: Record<string, (number) | (boolean) | (string)>;
+    };
+}
+export type SocketRigCreatureRowsInput = { [Key in keyof SocketRigCreatureRowsInputFields]: SocketRigCreatureRowsInputFields[Key] };
+interface SocketRigCreatureRowsFields {
+    model: Pick<v.InferOutput<typeof SpecimenModelMetadataSchema>, 'id' | 'file' | 'pipeline' | 'surface'>;
+    product: string;
+    sockets: string;
+    kind: string;
+    coat: {
+        id: string;
+        label: string;
+        weight: number;
+        rarity: 'common' | 'uncommon' | 'rare' | 'legendary';
+        scale: [
+            number,
+            number
+        ];
+        hp?: number;
+        tint?: Record<string, [
+            number,
+            number,
+            number
+        ]>;
+        traits?: Record<string, (number) | (boolean) | (string)>;
+    };
+}
+export type SocketRigCreatureRows = { [Key in keyof SocketRigCreatureRowsFields]: SocketRigCreatureRowsFields[Key] };

package/src/format/sourceResidency.ts

@@ -0,0 +1,16 @@
+import type {Shardfile} from './shardSchema.ts';
+import {preflightShardfile} from './preflight.ts';
+
+/** What `productWireBytes` reads of a product. */
+type Wire=Readonly<{files:readonly Readonly<{compressed:number}>[];requires:Readonly<{commons:readonly string[];commonsWire:Readonly<Record<string,number>>}>}>;
+/** The wire a product claim holds: every file's and pinned common's compressed bytes. No residency figure is below it. */
+function productWireBytes(source:Wire):number{
+  return source.files.reduce((sum,file)=>sum+file.compressed,0)
+    +source.requires.commons.reduce((sum,hash)=>sum+(source.requires.commonsWire[hash]??0),0);
+}
+/** Exact existing source/wire claim, computed once by the publisher for first-party clients. */
+function publishedSourceResidency(source:Shardfile):number{
+  const accounting={heapBytes:0};preflightShardfile(source,accounting);
+  return productWireBytes(source)+accounting.heapBytes*2+(source.files.length+source.requires.commons.length)*128+1024;
+}
+export {productWireBytes,publishedSourceResidency};

package/src/format/spawnCombat.ts

@@ -0,0 +1,26 @@
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+import { CreatureStrikeSchema } from './creatures.ts';
+
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(128));
+const amount = v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(60));
+/** V1 strike capabilities use the existing contact kernel. Effects and presentation edges are rows, never hooks. */
+export const SpawnCombatSchema: v.GenericSchema<SpawnCombatInput, SpawnCombat> = v.pipe(v.unknown(), v.check(isJsonData, 'plain JSON scripted strikes'), v.array(v.strictObject({ id, row: CreatureStrikeSchema,
+  trauma: v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(1)), stun: amount,
+  tell: v.exactOptional(v.picklist(['lane', 'ring'])), startCue: v.exactOptional(id), activeCue: v.exactOptional(id), doneCue: v.exactOptional(id),
+})), v.maxLength(32), v.check(rows => new Set(rows.map(row => row.id)).size === rows.length
+  && new Set(rows.map(row => row.row.id)).size === rows.length, 'unique scripted strikes'));
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type SpawnCombatInput = unknown;
+export type SpawnCombat = ({
+    id: string;
+    row: v.InferOutput<typeof CreatureStrikeSchema>;
+    trauma: number;
+    stun: number;
+    tell?: 'lane' | 'ring';
+    startCue?: string;
+    activeCue?: string;
+    doneCue?: string;
+})[];