@wildshard/shard-format 0.0.0 → 0.4.5

package/src/format/mixedPopulation.ts

@@ -0,0 +1,222 @@
+import * as v from 'valibot';
+import { NumericPoseSchema } from './clientChannels.ts';
+import { ReturnProgramSchema } from './namedJsonContracts.ts';
+import { ReturnProgramWireDocumentSchema, type ReturnProgramDocumentInput } from './returnProgramDocument.ts';
+
+const completeReturn:v.GenericSchema<v.InferInput<typeof ReturnProgramSchema>,v.InferOutput<typeof ReturnProgramSchema>&ReturnProgramDocumentInput>=v.intersect([ReturnProgramSchema,ReturnProgramWireDocumentSchema]);
+
+const finite = v.pipe(v.number(), v.finite());
+const key = v.pipe(v.string(), v.minLength(1), v.maxLength(128));
+const point = v.strictObject({ x: finite, z: finite });
+/** Mixed native roster policy, pose, reserve and physical volley composition. */
+export const MixedPopulationSchema: v.StrictObjectSchema<{ readonly step: v.GenericSchema<MixedPopulationRowsInput['step'], MixedPopulationRows['step']>; readonly limit: v.GenericSchema<MixedPopulationRowsInput['limit'], MixedPopulationRows['limit']>; readonly attackTurnCap: v.GenericSchema<MixedPopulationRowsInput['attackTurnCap'], MixedPopulationRows['attackTurnCap']>; readonly hunted: v.GenericSchema<MixedPopulationRowsInput['hunted'], MixedPopulationRows['hunted']>; readonly floorKinds: v.GenericSchema<MixedPopulationRowsInput['floorKinds'], MixedPopulationRows['floorKinds']>; readonly practice: v.GenericSchema<MixedPopulationRowsInput['practice'], MixedPopulationRows['practice']>; readonly reserve: v.GenericSchema<MixedPopulationRowsInput['reserve'], MixedPopulationRows['reserve']>; readonly volley: v.GenericSchema<MixedPopulationRowsInput['volley'], MixedPopulationRows['volley']>; readonly poses: v.GenericSchema<MixedPopulationRowsInput['poses'], MixedPopulationRows['poses']>; readonly perch: v.GenericSchema<MixedPopulationRowsInput['perch'], MixedPopulationRows['perch']>; }, undefined> = v.strictObject({
+  step: key, limit: v.pipe(finite, v.integer(), v.minValue(1), v.maxValue(256)),
+  attackTurnCap: finite, hunted: v.array(key), floorKinds: v.array(key),
+  practice: v.strictObject({ at: point, fade: finite, delay: finite, away: finite }),
+  reserve: v.strictObject({ kind: key, variant: key, scale: v.tuple([finite, finite]), legacyMemory: v.array(v.strictObject({ from: key, to: key, axis: v.picklist(['x', 'z', 'zero']) })) }),
+  volley: v.strictObject({ owner: key, strike: key, tags: v.array(v.custom<`${string}.${string}`>(value => typeof value === 'string' && /^[a-z][a-zA-Z0-9.-]*\.[a-zA-Z0-9.-]+$/u.test(value))) }),
+  poses: v.array(v.strictObject({ kind: key, clips: v.array(NumericPoseSchema),
+    lift: v.exactOptional(v.tuple([finite, finite, finite, finite])) })),
+  perch: v.strictObject({ kind: key, strike: key, sound: key, sourceHeight: finite, targetHeight: finite,
+    attackStream: v.exactOptional(v.picklist(['ai', 'spawn', 'gameplay', 'cosmetic'])),
+    actions: v.strictObject({ stateKey: key, states: v.array(key), actions: v.array(v.strictObject({ state: finite, phase: finite, effect: key,
+      once: v.strictObject({ key, value: finite, test: v.picklist(['falsy', 'not-value']) }),
+      when: v.exactOptional(v.strictObject({ key, test: v.picklist(['truthy', 'falsy']) })) })) }),
+    score: key, height: key, heightChannel: key,
+    root: v.strictObject({ drop: key, velocity: key, land: key, climb: key, height: key, baseX: key, baseZ: key, x: key, z: key,
+      gravity: finite, speed: finite, landing: finite }) }),
+});
+
+
+/** G1004: the complete two-clip perch binding, not a numeric-pose child alone. */
+export const PerchBodyFileSchema:v.GenericSchema<PerchBodyFileInput,PerchBodyFileRows>=v.strictObject({
+  clips:v.tuple([NumericPoseSchema,NumericPoseSchema]),program:completeReturn,perch:MixedPopulationSchema.entries.perch,
+});
+export interface PerchBodyFileInput {
+  clips:[v.InferInput<typeof NumericPoseSchema>,v.InferInput<typeof NumericPoseSchema>];
+  program:v.InferInput<typeof completeReturn>;
+  perch:MixedPopulationRowsInput['perch'];
+}
+export interface PerchBodyFileRows {
+  clips:[v.InferOutput<typeof NumericPoseSchema>,v.InferOutput<typeof NumericPoseSchema>];
+  program:v.InferOutput<typeof completeReturn>;
+  perch:MixedPopulationRows['perch'];
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+interface MixedPopulationRowsInputFields {
+    step: string;
+    limit: number;
+    attackTurnCap: number;
+    hunted: (string)[];
+    floorKinds: (string)[];
+    practice: {
+        at: {
+            x: number;
+            z: number;
+        };
+        fade: number;
+        delay: number;
+        away: number;
+    };
+    reserve: {
+        kind: string;
+        variant: string;
+        scale: [
+            number,
+            number
+        ];
+        legacyMemory: ({
+            from: string;
+            to: string;
+            axis: 'x' | 'z' | 'zero';
+        })[];
+    };
+    volley: {
+        owner: string;
+        strike: string;
+        tags: (`${string}.${string}`)[];
+    };
+    poses: ({
+        kind: string;
+        clips: (v.InferInput<typeof NumericPoseSchema>)[];
+        lift?: [
+            number,
+            number,
+            number,
+            number
+        ];
+    })[];
+    perch: {
+        kind: string;
+        strike: string;
+        sound: string;
+        sourceHeight: number;
+        targetHeight: number;
+        attackStream?: 'ai' | 'spawn' | 'gameplay' | 'cosmetic';
+        actions: {
+            stateKey: string;
+            states: (string)[];
+            actions: ({
+                state: number;
+                phase: number;
+                effect: string;
+                once: {
+                    key: string;
+                    value: number;
+                    test: 'falsy' | 'not-value';
+                };
+                when?: {
+                    key: string;
+                    test: 'truthy' | 'falsy';
+                };
+            })[];
+        };
+        score: string;
+        height: string;
+        heightChannel: string;
+        root: {
+            drop: string;
+            velocity: string;
+            land: string;
+            climb: string;
+            height: string;
+            baseX: string;
+            baseZ: string;
+            x: string;
+            z: string;
+            gravity: number;
+            speed: number;
+            landing: number;
+        };
+    };
+}
+export type MixedPopulationRowsInput = { [Key in keyof MixedPopulationRowsInputFields]: MixedPopulationRowsInputFields[Key] };
+interface MixedPopulationRowsFields {
+    step: string;
+    limit: number;
+    attackTurnCap: number;
+    hunted: (string)[];
+    floorKinds: (string)[];
+    practice: {
+        at: {
+            x: number;
+            z: number;
+        };
+        fade: number;
+        delay: number;
+        away: number;
+    };
+    reserve: {
+        kind: string;
+        variant: string;
+        scale: [
+            number,
+            number
+        ];
+        legacyMemory: ({
+            from: string;
+            to: string;
+            axis: 'x' | 'z' | 'zero';
+        })[];
+    };
+    volley: {
+        owner: string;
+        strike: string;
+        tags: (`${string}.${string}`)[];
+    };
+    poses: ({
+        kind: string;
+        clips: (v.InferOutput<typeof NumericPoseSchema>)[];
+        lift?: [
+            number,
+            number,
+            number,
+            number
+        ];
+    })[];
+    perch: {
+        kind: string;
+        strike: string;
+        sound: string;
+        sourceHeight: number;
+        targetHeight: number;
+        attackStream?: 'ai' | 'spawn' | 'gameplay' | 'cosmetic';
+        actions: {
+            stateKey: string;
+            states: (string)[];
+            actions: ({
+                state: number;
+                phase: number;
+                effect: string;
+                once: {
+                    key: string;
+                    value: number;
+                    test: 'falsy' | 'not-value';
+                };
+                when?: {
+                    key: string;
+                    test: 'truthy' | 'falsy';
+                };
+            })[];
+        };
+        score: string;
+        height: string;
+        heightChannel: string;
+        root: {
+            drop: string;
+            velocity: string;
+            land: string;
+            climb: string;
+            height: string;
+            baseX: string;
+            baseZ: string;
+            x: string;
+            z: string;
+            gravity: number;
+            speed: number;
+            landing: number;
+        };
+    };
+}
+export type MixedPopulationRows = { [Key in keyof MixedPopulationRowsFields]: MixedPopulationRowsFields[Key] };

package/src/format/modes.ts

@@ -0,0 +1,304 @@
+import * as v from 'valibot';
+
+const finite = v.pipe(v.number(), v.finite());
+const range = (low: number, high: number) => v.pipe(finite, v.minValue(low), v.maxValue(high));
+const id = v.pipe(v.string(), v.regex(/^[a-zA-Z0-9_.-]{1,128}$/));
+const point = v.strictObject({ x: range(-250, 250), y: range(-250, 250), z: range(-250, 250) });
+/** Optional direct cable anchors and their explicit deck release law. */
+export const CableProfileSchema: v.GenericSchema<CableProfileRowsInput, CableProfileRows> = v.strictObject({ anchors: v.literal('direct'), start: range(0, 10), release: range(0, 10),
+  landing: v.strictObject({ back: range(0, 10), deck: range(0, 2), velocity: range(0, 16) }) });
+/** Cable traversal parameters; the endpoints are floor positions, not silently raised cable anchors. */
+export const ZiplineModeSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{ readonly kind: v.GenericSchema<ZiplineModeInput['kind'], ZiplineMode['kind']>; readonly id: v.GenericSchema<ZiplineModeInput['id'], ZiplineMode['id']>; readonly top: v.GenericSchema<ZiplineModeInput['top'], ZiplineMode['top']>; readonly bottom: v.GenericSchema<ZiplineModeInput['bottom'], ZiplineMode['bottom']>; readonly profile: v.ExactOptionalSchema<v.GenericSchema<Exclude<ZiplineModeInput['profile'], undefined>, Exclude<ZiplineMode['profile'], undefined>>, undefined>; readonly landing: v.ExactOptionalSchema<v.GenericSchema<Exclude<ZiplineModeInput['landing'], undefined>, Exclude<ZiplineMode['landing'], undefined>>, undefined>; readonly lifecycle: v.ExactOptionalSchema<v.GenericSchema<Exclude<ZiplineModeInput['lifecycle'], undefined>, Exclude<ZiplineMode['lifecycle'], undefined>>, undefined>; readonly presentation: v.ExactOptionalSchema<v.GenericSchema<Exclude<ZiplineModeInput['presentation'], undefined>, Exclude<ZiplineMode['presentation'], undefined>>, undefined>; readonly sag: v.OptionalSchema<v.GenericSchema<Exclude<ZiplineModeInput['sag'], undefined>, Exclude<ZiplineMode['sag'], undefined>>, 1.6>; readonly hang: v.OptionalSchema<v.GenericSchema<Exclude<ZiplineModeInput['hang'], undefined>, Exclude<ZiplineMode['hang'], undefined>>, 2.9>; readonly gravity: v.OptionalSchema<v.GenericSchema<Exclude<ZiplineModeInput['gravity'], undefined>, Exclude<ZiplineMode['gravity'], undefined>>, 9.8>; readonly drag: v.OptionalSchema<v.GenericSchema<Exclude<ZiplineModeInput['drag'], undefined>, Exclude<ZiplineMode['drag'], undefined>>, 0.012>; readonly maxSpeed: v.OptionalSchema<v.GenericSchema<Exclude<ZiplineModeInput['maxSpeed'], undefined>, Exclude<ZiplineMode['maxSpeed'], undefined>>, 16>; }, undefined>, v.CheckAction<{ [K in keyof ZiplineMode]: ZiplineMode[K] }, 'zipline requires distinct horizontal ends'>]> = v.pipe(v.strictObject({
+  kind: v.literal('zipline'), id, top: point, bottom: point,
+  profile: v.exactOptional(CableProfileSchema), landing: v.exactOptional(point),
+  lifecycle: v.exactOptional(v.strictObject({ endFlag: v.pipe(v.string(), v.regex(/^[a-zA-Z0-9_.:-]{1,128}$/)), carry: v.picklist(['start', 'update']), native: v.picklist(['position', 'motor']) })),
+  presentation: v.exactOptional(v.strictObject({ park: range(0, 10),
+    wind: v.exactOptional(v.strictObject({ frequency: range(0, 10), amplitude: range(0, 0.1) })) })),
+  sag: v.optional(range(0, 20), 1.6),
+  hang: v.optional(range(0, 10), 2.9), gravity: v.optional(range(0, 64), 9.8),
+  drag: v.optional(range(0, 1), 0.012), maxSpeed: v.optional(range(2.5, 32), 16),
+}), v.check(row => Math.hypot(row.top.x - row.bottom.x, row.top.z - row.bottom.z) > 0, 'zipline requires distinct horizontal ends'));
+/** A directional board-only wind column with the shipping open sides and upper ceiling. */
+export const UpdraftModeSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{ readonly kind: v.GenericSchema<UpdraftModeInput['kind'], UpdraftMode['kind']>; readonly id: v.GenericSchema<UpdraftModeInput['id'], UpdraftMode['id']>; readonly from: v.GenericSchema<UpdraftModeInput['from'], UpdraftMode['from']>; readonly to: v.GenericSchema<UpdraftModeInput['to'], UpdraftMode['to']>; readonly width: v.GenericSchema<UpdraftModeInput['width'], UpdraftMode['width']>; readonly margin: v.OptionalSchema<v.GenericSchema<Exclude<UpdraftModeInput['margin'], undefined>, Exclude<UpdraftMode['margin'], undefined>>, 0.5>; readonly lift: v.GenericSchema<UpdraftModeInput['lift'], UpdraftMode['lift']>; }, undefined>, v.CheckAction<{ [K in keyof UpdraftMode]: UpdraftMode[K] }, 'updraft requires a horizontal run'>]> = v.pipe(v.strictObject({
+  kind: v.literal('updraft'), id, from: point, to: point,
+  width: range(0.1, 100), margin: v.optional(range(0, 5), 0.5), lift: range(0, 64),
+}), v.check(row => Math.hypot(row.to.x - row.from.x, row.to.z - row.from.z) > 0, 'updraft requires a horizontal run'));
+/** Vertical capsule route; colliders and the upper landing are authored separately, never generated by the mode. */
+export const LadderModeSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{ readonly kind: v.GenericSchema<LadderModeInput['kind'], LadderMode['kind']>; readonly id: v.GenericSchema<LadderModeInput['id'], LadderMode['id']>; readonly bottom: v.GenericSchema<LadderModeInput['bottom'], LadderMode['bottom']>; readonly top: v.GenericSchema<LadderModeInput['top'], LadderMode['top']>; readonly exit: v.GenericSchema<LadderModeInput['exit'], LadderMode['exit']>; readonly normal: v.GenericSchema<LadderModeInput['normal'], LadderMode['normal']>; readonly reach: v.OptionalSchema<v.GenericSchema<Exclude<LadderModeInput['reach'], undefined>, Exclude<LadderMode['reach'], undefined>>, 0.6>; readonly speed: v.OptionalSchema<v.GenericSchema<Exclude<LadderModeInput['speed'], undefined>, Exclude<LadderMode['speed'], undefined>>, 2>; }, undefined>, v.CheckAction<{ [K in keyof LadderMode]: LadderMode[K] }, 'ladder requires a vertical ascending route'>, v.CheckAction<{ [K in keyof LadderMode]: LadderMode[K] }, 'ladder requires a unit outward normal'>, v.CheckAction<{ [K in keyof LadderMode]: LadderMode[K] }, 'ladder requires a bounded upper landing behind its normal'>]> = v.pipe(v.strictObject({
+  kind: v.literal('ladder'), id, bottom: point, top: point, exit: point,
+  normal: v.strictObject({ x: range(-1, 1), z: range(-1, 1) }),
+  reach: v.optional(range(0.1, 1), 0.6), speed: v.optional(range(0.1, 5), 2),
+}), v.check(row => row.top.x === row.bottom.x && row.top.z === row.bottom.z && row.top.y > row.bottom.y, 'ladder requires a vertical ascending route'),
+  v.check(row => Math.abs(Math.hypot(row.normal.x, row.normal.z) - 1) < 1e-10, 'ladder requires a unit outward normal'),
+  v.check(row => row.exit.y === row.top.y && Math.hypot(row.exit.x - row.top.x, row.exit.z - row.top.z) <= 2
+    && (row.exit.x - row.top.x) * row.normal.x + (row.exit.z - row.top.z) * row.normal.z < -0.1, 'ladder requires a bounded upper landing behind its normal'));
+/** One validated vertical climb route, including its real landing floor position. */
+
+/** Admitted native gait speeds, strictly increasing in metres per second. */
+export const RideGaitsSchema: v.GenericSchema<RideGaitsRowsInput, RideGaitsRows> = v.pipe(v.strictObject({ walk: range(0.1, 30), trot: range(0.1, 30), canter: range(0.1, 30), gallop: range(0.1, 30) }),
+  v.check(g => g.walk < g.trot && g.trot < g.canter && g.canter < g.gallop, 'increasing mounted gaits'));
+/** Mounted control profile; an installed native actor and its owner still decide whether mounting is allowed. */
+export const RideModeSchema: v.GenericSchema<RideModeInput, RideMode> = v.strictObject({ id, gaits: RideGaitsSchema });
+/** One admitted mounted law profile. */
+
+/** Bounded native grapple selection and traversal timings; anchors and safe floors remain real world queries. */
+export const GrappleModeSchema: v.GenericSchema<GrappleModeInput, GrappleMode> = v.pipe(v.strictObject({ id,
+  minRange: v.optional(range(0.1, 64), 2.5), maxRange: v.optional(range(0.1, 64), 38),
+  zipSpeed: v.optional(range(0.1, 40), 22), fireTime: v.optional(range(0.01, 2), 0.27),
+  biteTime: v.optional(range(0.01, 2), 0.10), reelTime: v.optional(range(0.01, 2), 0.48),
+  windowX: v.optional(range(0.01, 1), 0.52), windowY: v.optional(range(0.01, 1), 0.68),
+}), v.check(row => row.minRange < row.maxRange, 'increasing grapple range'));
+/** One admitted native grapple control profile. */
+
+/** Only implemented platform traverse laws cross admission; executable callbacks never do. */
+export const TraverseModeSchema: v.GenericSchema<TraverseModeInput, TraverseMode> = v.variant('kind', [ZiplineModeSchema, UpdraftModeSchema, LadderModeSchema]);
+/** Actual mode parameters admitted from authoring objects; absence retains the ordinary player law. */
+export const ModesSchema: v.GenericSchema<ModeRowsInput, ModeRows> = v.pipe(v.strictObject({
+  ride: v.exactOptional(v.pipe(v.array(RideModeSchema), v.maxLength(64))),
+  grapple: v.exactOptional(v.pipe(v.array(GrappleModeSchema), v.maxLength(64))),
+  traverse: v.optional(v.pipe(v.array(TraverseModeSchema), v.maxLength(64)), []),
+}), v.check(rows => new Set(rows.traverse.map(row => row.id)).size === rows.traverse.length, 'unique traverse identities'), v.check(rows => new Set(rows.grapple?.map(row => row.id)).size === (rows.grapple?.length ?? 0), 'unique grapple identities'), v.check(rows => new Set(rows.ride?.map(row => row.id)).size === (rows.ride?.length ?? 0), 'unique mounted identities'));
+/** Admitted platform traversal rows. */
+
+/** One cable law's admitted parameters. */
+
+/** One wind column's admitted parameters. */
+
+/** One serializable traversal declaration. */
+
+/** Validate every row before its host allocates resources or installs callbacks. */
+export function parseModes(input: unknown): ModeRows { return v.parse(ModesSchema, input); }
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+interface ZiplineModeInputFields {
+    kind: 'zipline';
+    id: string;
+    top: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    bottom: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    profile?: CableProfileRowsInput;
+    landing?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    lifecycle?: {
+        endFlag: string;
+        carry: 'start' | 'update';
+        native: 'position' | 'motor';
+    };
+    presentation?: {
+        park: number;
+        wind?: {
+            frequency: number;
+            amplitude: number;
+        };
+    };
+    sag?: number | undefined;
+    hang?: number | undefined;
+    gravity?: number | undefined;
+    drag?: number | undefined;
+    maxSpeed?: number | undefined;
+}
+export type ZiplineModeInput = { [Key in keyof ZiplineModeInputFields]: ZiplineModeInputFields[Key] };
+interface ZiplineModeFields {
+    kind: 'zipline';
+    id: string;
+    top: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    bottom: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    profile?: CableProfileRows;
+    landing?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    lifecycle?: {
+        endFlag: string;
+        carry: 'start' | 'update';
+        native: 'position' | 'motor';
+    };
+    presentation?: {
+        park: number;
+        wind?: {
+            frequency: number;
+            amplitude: number;
+        };
+    };
+    sag: number;
+    hang: number;
+    gravity: number;
+    drag: number;
+    maxSpeed: number;
+}
+export type ZiplineMode = { [Key in keyof ZiplineModeFields]: ZiplineModeFields[Key] };
+interface UpdraftModeInputFields {
+    kind: 'updraft';
+    id: string;
+    from: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    to: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    width: number;
+    margin?: number | undefined;
+    lift: number;
+}
+export type UpdraftModeInput = { [Key in keyof UpdraftModeInputFields]: UpdraftModeInputFields[Key] };
+interface UpdraftModeFields {
+    kind: 'updraft';
+    id: string;
+    from: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    to: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    width: number;
+    margin: number;
+    lift: number;
+}
+export type UpdraftMode = { [Key in keyof UpdraftModeFields]: UpdraftModeFields[Key] };
+interface LadderModeInputFields {
+    kind: 'ladder';
+    id: string;
+    bottom: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    top: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    exit: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    normal: {
+        x: number;
+        z: number;
+    };
+    reach?: number | undefined;
+    speed?: number | undefined;
+}
+export type LadderModeInput = { [Key in keyof LadderModeInputFields]: LadderModeInputFields[Key] };
+interface LadderModeFields {
+    kind: 'ladder';
+    id: string;
+    bottom: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    top: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    exit: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    normal: {
+        x: number;
+        z: number;
+    };
+    reach: number;
+    speed: number;
+}
+export type LadderMode = { [Key in keyof LadderModeFields]: LadderModeFields[Key] };
+export type CableProfileRowsInput = CableProfileRows;
+interface CableProfileRowsFields {
+    anchors: 'direct';
+    start: number;
+    release: number;
+    landing: {
+        back: number;
+        deck: number;
+        velocity: number;
+    };
+}
+export type CableProfileRows = { [Key in keyof CableProfileRowsFields]: CableProfileRowsFields[Key] };
+export type RideGaitsRowsInput = RideGaitsRows;
+interface RideGaitsRowsFields {
+    walk: number;
+    trot: number;
+    canter: number;
+    gallop: number;
+}
+export type RideGaitsRows = { [Key in keyof RideGaitsRowsFields]: RideGaitsRowsFields[Key] };
+interface RideModeInputFields {
+    id: string;
+    gaits: RideGaitsRowsInput;
+}
+export type RideModeInput = { [Key in keyof RideModeInputFields]: RideModeInputFields[Key] };
+interface RideModeFields {
+    id: string;
+    gaits: RideGaitsRows;
+}
+export type RideMode = { [Key in keyof RideModeFields]: RideModeFields[Key] };
+interface GrappleModeInputFields {
+    id: string;
+    minRange?: number | undefined;
+    maxRange?: number | undefined;
+    zipSpeed?: number | undefined;
+    fireTime?: number | undefined;
+    biteTime?: number | undefined;
+    reelTime?: number | undefined;
+    windowX?: number | undefined;
+    windowY?: number | undefined;
+}
+export type GrappleModeInput = { [Key in keyof GrappleModeInputFields]: GrappleModeInputFields[Key] };
+interface GrappleModeFields {
+    id: string;
+    minRange: number;
+    maxRange: number;
+    zipSpeed: number;
+    fireTime: number;
+    biteTime: number;
+    reelTime: number;
+    windowX: number;
+    windowY: number;
+}
+export type GrappleMode = { [Key in keyof GrappleModeFields]: GrappleModeFields[Key] };
+export type TraverseModeInput = (ZiplineModeInput) | (UpdraftModeInput) | (LadderModeInput);
+export type TraverseMode = (ZiplineMode) | (UpdraftMode) | (LadderMode);
+interface ModeRowsInputFields {
+    ride?: (RideModeInput)[];
+    grapple?: (GrappleModeInput)[];
+    traverse?: (TraverseModeInput)[] | undefined;
+}
+export type ModeRowsInput = { [Key in keyof ModeRowsInputFields]: ModeRowsInputFields[Key] };
+interface ModeRowsFields {
+    ride?: (RideMode)[];
+    grapple?: (GrappleMode)[];
+    traverse: (TraverseMode)[];
+}
+export type ModeRows = { [Key in keyof ModeRowsFields]: ModeRowsFields[Key] };

package/src/format/mountedSpecimenRows.ts

@@ -0,0 +1,64 @@
+import { SceneBakedGeometrySchema } from './sceneDressing.ts';
+import { BinaryFileSchema } from './binarySource.ts';
+import * as v from 'valibot';
+import { ClipRowsSchema } from './kitFigure.ts';
+import { isJsonData } from './json.ts';
+import { PrivateSceneSchema } from './clientChannels.ts';
+import { SpecimenModelMetadataSchema } from './specimenCatalogue.ts';
+
+const id=v.pipe(v.string(),v.minLength(1)),number=v.pipe(v.number(),v.finite());
+/** A look lent to the figure's port material, by look id (G603 L10): the painterly look's rim and bands. */
+const SeatLookSchema=v.variant('look',[v.strictObject({look:v.literal('painterly'),id,rim:number,bands:number})]);
+/** A rider seated on a mount (G603 L10): the mount's joint, the figure's private scene and clip rows, its geometry as raw file or legacy inline
+ * fixed-draw rows (key, file or data, geometry), an optional lent look for a port material (absent, the scene declares its own
+ * standard materials), the speed clock and the gestures its cue kinds start. */
+export const MountedSpecimenSeatSchema: v.GenericSchema<MountedSpecimenSeatRowsInput, MountedSpecimenSeatRows>=v.pipe(v.unknown(),v.check(isJsonData),v.strictObject({mount:id,figure:PrivateSceneSchema,material:v.exactOptional(SeatLookSchema),
+  shapes:v.pipe(v.array(v.union([v.strictObject({key:id,data:id,geometry:SceneBakedGeometrySchema}),v.strictObject({key:id,...BinaryFileSchema.entries,geometry:SceneBakedGeometrySchema})])),v.minLength(1),v.maxLength(8)),
+  clips:ClipRowsSchema,speed:id,gestures:v.pipe(v.array(v.strictObject({cue:id,clock:id,duration:v.pipe(number,v.minValue(.01))})),v.maxLength(16))}));
+
+/** A mounted specimen (G603 L10): its model card, the product (slug) and file of its seat rows, the species rig and variant
+ * it sits on, and the rig's fur tint (0..1). */
+export const MountedSpecimenSchema: v.GenericSchema<MountedSpecimenRowsInput, MountedSpecimenRows>=v.pipe(v.unknown(),v.check(isJsonData),v.strictObject({model:SpecimenModelMetadataSchema,slug:id,json:id,
+  species:id,variant:id,tint:v.pipe(number,v.minValue(0),v.maxValue(1))}));
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type MountedSpecimenSeatRowsInput = unknown;
+interface MountedSpecimenSeatRowsFields {
+    mount: string;
+    figure: v.InferOutput<typeof PrivateSceneSchema>;
+    material?: ({
+        look: 'painterly';
+        id: string;
+        rim: number;
+        bands: number;
+    });
+    shapes: (({
+        key: string;
+        data: string;
+        geometry: v.InferOutput<typeof SceneBakedGeometrySchema>;
+    }) | (Omit<Omit<{
+        key: string;
+    }, keyof (v.InferOutput<typeof BinaryFileSchema>)> & v.InferOutput<typeof BinaryFileSchema>, keyof ({
+        geometry: v.InferOutput<typeof SceneBakedGeometrySchema>;
+    })> & {
+        geometry: v.InferOutput<typeof SceneBakedGeometrySchema>;
+    }))[];
+    clips: v.InferOutput<typeof ClipRowsSchema>;
+    speed: string;
+    gestures: ({
+        cue: string;
+        clock: string;
+        duration: number;
+    })[];
+}
+export type MountedSpecimenSeatRows = { [Key in keyof MountedSpecimenSeatRowsFields]: MountedSpecimenSeatRowsFields[Key] };
+export type MountedSpecimenRowsInput = unknown;
+interface MountedSpecimenRowsFields {
+    model: v.InferOutput<typeof SpecimenModelMetadataSchema>;
+    slug: string;
+    json: string;
+    species: string;
+    variant: string;
+    tint: number;
+}
+export type MountedSpecimenRows = { [Key in keyof MountedSpecimenRowsFields]: MountedSpecimenRowsFields[Key] };

package/src/format/moverLifecycle.ts

@@ -0,0 +1,34 @@
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+
+const id = v.pipe(v.string(), v.regex(/^[A-Za-z][A-Za-z0-9._:-]*$/u), v.maxLength(128));
+/** Endpoint observations use admitted mover fields, not view callbacks or approximate geometry tests. */
+export const MoverAtEndSchema: v.GenericSchema<MoverAtEndRowsInput, MoverAtEndRows> = v.pipe(v.strictObject({ field: v.picklist([1, 2, 3, 4, 5, 6]), equals: v.pipe(v.number(), v.finite(), v.minValue(-Math.PI), v.maxValue(Math.PI)) }),
+  v.check(row => row.field < 4 || row.equals >= 0 && row.equals <= 1, 'endpoint matches admitted field range'));
+/** Load-only endpoint restoration is distinct from the legacy drivers' nonuniform numeric commands. */
+export const MoverRestoreFromSchema: v.GenericSchema<MoverRestoreFromRowsInput, MoverRestoreFromRows> = v.strictObject({ flag: id, action: v.literal('end') });
+/** Shared lifecycle data also serves collision-free channel movers. */
+export const MoverLifecycleRowsSchema: v.GenericSchema<MoverLifecycleRowsInput, MoverLifecycleRows> = v.pipe(v.unknown(), v.check(isJsonData, 'plain JSON mover lifecycle'), v.array(v.strictObject({ id,
+  atEnd: v.exactOptional(MoverAtEndSchema), restoreFrom: v.exactOptional(MoverRestoreFromSchema) })), v.maxLength(32),
+  v.check(rows => new Set(rows.map(row => row.id)).size === rows.length, 'unique mover lifecycle ids'));
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type MoverAtEndRowsInput = MoverAtEndRows;
+interface MoverAtEndRowsFields {
+    field: 1 | 2 | 3 | 4 | 5 | 6;
+    equals: number;
+}
+export type MoverAtEndRows = { [Key in keyof MoverAtEndRowsFields]: MoverAtEndRowsFields[Key] };
+export type MoverRestoreFromRowsInput = MoverRestoreFromRows;
+interface MoverRestoreFromRowsFields {
+    flag: string;
+    action: 'end';
+}
+export type MoverRestoreFromRows = { [Key in keyof MoverRestoreFromRowsFields]: MoverRestoreFromRowsFields[Key] };
+export type MoverLifecycleRowsInput = unknown;
+export type MoverLifecycleRows = ({
+    id: string;
+    atEnd?: MoverAtEndRows;
+    restoreFrom?: MoverRestoreFromRows;
+})[];