@wildshard/shard-format 0.0.0 → 0.4.5

package/src/format/clientPlan.ts

@@ -0,0 +1,306 @@
+import { QuestRuntimeFileSchema } from './questRuntime.ts';
+import { EliteEntryPageRowsSchema } from './eliteEntryRows.ts';
+import { GrappleHooksSchema, GrappleProfileSchema } from './grapple.ts';
+import { DeclaredPortalRideSchema } from './portalRide.ts';
+import { CatalogueEconomySchema } from './catalogueEconomy.ts';
+import { PagePathRampSchema } from './pagePreparation.ts';
+import { ViewProgramSchema } from './viewProgram.ts';
+import { BakedSourceSchema, BakedTilesSchema } from './bakedTiles.ts';
+import { WaterSurfaceSchema } from './water.ts';
+import { ClientCuesSchema } from './clientCues.ts';
+import { ClientTrailsSchema } from './clientTrails.ts';
+import * as v from 'valibot';
+import { DeclaredCombatTargetsSchema } from './targets.ts';
+import { WorldUpdatesSchema } from './worldUpdates.ts';
+import { WorldAssemblySchema } from './worldAssembly.ts';
+import { isJsonData } from './json.ts';
+import { LightEmittersSchema } from './lightEmitters.ts';
+import { EasedFieldsSchema } from './easedFields.ts';
+import { SceneMotionSchema } from './sceneMotion.ts';
+import { ClientHeldMeleeSchema, ClientSpeciesProgramSchema, ClientQuestPageSchema, ClientPopulationSchema, ClientHeldBossSchema, ClientSpawnedBossSchema, ClientPlayerEnterSchema, ClientBossTelegraphSchema } from './clientNative.ts';
+
+const finite=v.pipe(v.number(),v.finite()),rgb=v.tuple([finite,finite,finite]);
+const label=v.pipe(v.string(),v.minLength(1),v.maxLength(512));
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(128), v.regex(/^[a-zA-Z][a-zA-Z0-9.-]*$/u));
+/** A page-mode texture cap (game/shard/pagePolicy pageModeCap): inputs through `through` are held to `max`. */
+const PageCapSchema = v.strictObject({ through: v.pipe(finite, v.minValue(0)), max: v.pipe(finite, v.minValue(0)) });
+const attribute = v.pipe(v.string(), v.minLength(1), v.maxLength(64), v.regex(/^[_a-zA-Z][_a-zA-Z0-9]*$/u));
+/** O7: a water row's own draw (WaterSurface.draw): its grid per tier (custom attributes renamed for its graph), level,
+ *  baked floor, dry rectangles, foam boxes, and params lent from the product's toon lighting uniforms. */
+const WaterDrawSchema = v.strictObject({
+  grid: v.strictObject({ phone: BakedSourceSchema, desktop: BakedSourceSchema }),
+  attributes: v.pipe(v.record(attribute, attribute), v.maxEntries(8)),
+  level: finite,
+  floor: v.exactOptional(BakedSourceSchema),
+  dry: v.pipe(v.array(v.pipe(v.strictObject({ minX: finite, minZ: finite, maxX: finite, maxZ: finite }),
+    v.check(rect => rect.minX < rect.maxX && rect.minZ < rect.maxZ, 'positive dry rectangle'))), v.maxLength(16)),
+  foam: v.pipe(v.array(v.strictObject({ x: finite, z: finite, hw: finite, hd: finite, rot: finite, yTop: finite, yBottom: finite })), v.maxLength(2048)),
+  lent: v.pipe(v.record(attribute, v.picklist(['uCloudShadow', 'uToonNight', 'uSeaLevel', 'uCloudTime'])), v.maxEntries(8)),
+  /** the toon lighting's sea level is this water's level */
+  toonSeaLevel: v.boolean(),
+});
+/** A finite play rectangle with its authored fall floor inside the central square. */
+export const RuntimeBoundsSchema: v.GenericSchema<RuntimeBounds> = v.pipe(v.strictObject({
+  x: v.tuple([finite, finite]), z: v.tuple([finite, finite]),
+  outer: v.strictObject({ maxAbsXZ: v.pipe(finite, v.minValue(0)), floor: finite }),
+}), v.check(row => row.x[0] < row.x[1] && row.z[0] < row.z[1], 'ordered play bounds'));
+/** Client-only declarations select compiled platform features, never modules, owners or property paths. */
+export const ClientFeatureSchema: v.GenericSchema<ClientFeatureInput, ClientFeatureRow> = v.variant('kind', [
+  v.strictObject({ kind: v.literal('strings.register') }),
+  v.strictObject({ kind: v.literal('content.catalogue'), quests: v.boolean(), finishes: v.boolean(),
+    economy: v.exactOptional(CatalogueEconomySchema),
+    weapons: v.pipe(v.array(id), v.maxLength(256)), ammunition: v.pipe(v.array(id), v.maxLength(256)),
+    effects: v.pipe(v.array(v.picklist(['starter', 'finishes'])), v.maxLength(2)),
+    compendiums: v.pipe(v.array(id), v.maxLength(64)),
+    encounters: v.pipe(v.array(v.strictObject({ id, displayName: label, showHeadBar: v.boolean() })), v.maxLength(64)) }),
+  v.strictObject({ kind: v.literal('state.adventure'), file: label, id: v.exactOptional(id), progress: v.exactOptional(v.literal(true)) }),
+  v.strictObject({ kind: v.literal('world.meadow'), file: label }),
+  v.strictObject({ kind: v.literal('world.ambient-life'), file: label,
+    flocks: v.pipe(v.array(v.strictObject({ id, owner: id })), v.maxLength(64),
+      v.check(rows => new Set(rows.map(row => row.id)).size === rows.length && new Set(rows.map(row => row.owner)).size === rows.length, 'unique ambient ids and owners')) }),
+  v.strictObject({ kind: v.literal('world.updates'), rows: WorldUpdatesSchema }),
+  DeclaredCombatTargetsSchema,
+  // G748 farStandIn: beyond the render ring the entered cell draws its own near view for its occupied tiles (a shard whose
+  // drawn world is tiled; one that draws its world whole leaves it out)
+  v.pipe(v.strictObject({ kind: v.literal('world.assembly'), native: v.exactOptional(v.strictObject({ groups: id })), library: v.exactOptional(id), catalogue: v.exactOptional(label), farStandIn: v.exactOptional(v.literal(true)), entered: v.exactOptional(v.strictObject({ root: id, blocks: v.pipe(v.array(id), v.minLength(1), v.maxLength(64), v.check(blocks => new Set(blocks).size === blocks.length, 'unique entered blocks')) })), rows: WorldAssemblySchema }),
+    v.check(row => (row.library === undefined) === (row.catalogue === undefined), 'World assembly library and catalogue must be declared together'),
+    v.check(row => row.native === undefined || row.library === undefined && row.catalogue === undefined && row.entered === undefined, 'Native assembly retains its original context without a library or entered-piece adapter')),
+  v.strictObject({ kind: v.literal('world.runtime-hooks'), bounds: v.exactOptional(RuntimeBoundsSchema), floor: v.exactOptional(id),
+    overhead: v.pipe(v.array(id), v.maxLength(64), v.check(rows => new Set(rows).size === rows.length, 'unique overhead owners')),
+    meleeSilent: v.exactOptional(v.boolean()) }),
+  v.strictObject({ kind: v.literal('world.movers'), system: id,
+    bindings: v.pipe(v.array(v.variant('kind', [
+      v.strictObject({ kind: v.literal('object'), id, owner: id, order: v.exactOptional(v.picklist(['XYZ', 'YXZ'])),
+        visibility: v.exactOptional(v.literal('enabled')),
+        moor: v.exactOptional(v.strictObject({ look: id, water: finite, cleats: v.tuple([finite, finite]) })) }),
+      v.strictObject({ kind: v.literal('chain'), id, owner: id }),
+    ])), v.minLength(1), v.maxLength(64), v.check(rows => new Set(rows.map(row => row.id)).size === rows.length, 'unique mover ids')) }),
+  v.strictObject({ kind: v.literal('world.bind-sets'),
+    placed: v.pipe(v.array(id), v.maxLength(1024)),
+    groups: v.pipe(v.array(v.strictObject({ id, placed: v.pipe(v.array(id), v.maxLength(1024)) })), v.maxLength(128),
+      v.check(rows => new Set(rows.map(row => row.id)).size === rows.length, 'unique named-place groups')),
+    quest: v.exactOptional(id) }),
+  v.strictObject({ kind: v.literal('world.paths'), rows: PagePathRampSchema }),
+  v.strictObject({ kind: v.literal('world.dressing') }),
+  // Optional publish borrows the built wildlife at the platform play slot, after chapter views.
+  v.strictObject({ kind: v.literal('population.wildlife'), file: label,
+    crowd: v.strictObject({ json: label, binary: label }), navSteer: v.boolean(), publish: v.exactOptional(id),
+    frame: v.strictObject({ id, after: v.pipe(v.array(id), v.maxLength(16)), before: v.pipe(v.array(id), v.maxLength(16)) }) }),
+  v.strictObject({kind:v.literal('world.sets'),rows:v.pipe(v.array(v.strictObject({place:label,id:label,name:label,file:label,pois:v.optional(v.pipe(v.array(label),v.maxLength(128),v.check(names=>new Set(names).size===names.length)),[]),x:finite,z:finite,r:v.pipe(finite,v.minValue(0)),mode:v.exactOptional(v.picklist(['centre','bounds']))})),v.maxLength(128),v.check(rows=>new Set(rows.map(row=>row.id)).size===rows.length))}),
+  v.strictObject({ kind: v.literal('riding.session'), file: label, owner: v.exactOptional(id) }),
+  v.strictObject({ kind: v.literal('stealth.entry'), owner: id, claims: id, riding: id, night: id, bow: id, melee: id,
+    impactExclusion: v.pipe(finite, v.minValue(0)), debugRiding: v.exactOptional(id),
+    frame: v.strictObject({ id, after: v.pipe(v.array(id), v.maxLength(16)), before: v.pipe(v.array(id), v.maxLength(16)) }) }),
+  v.strictObject({ kind: v.literal('elite.construct'), owner: id, rows: EliteEntryPageRowsSchema, admission: label, fight: id, models: id, program: id, weather: id, night: id,
+    ledges: v.strictObject({part: id, anchor: id}) }),
+  v.strictObject({ kind: v.literal('timed.encounters'), owner: id, file: label, draws: id, species: id, guest: id, weather: id,
+    sites: v.exactOptional(id), figures: v.strictObject({rider: id, captain: id, storm: v.picklist(['rider', 'captain'])}) }),
+  v.strictObject({ kind: v.literal('practice.course'), course: v.picklist(['horse', 'grapple']),
+    title: label, blurb: label, icon: v.pipe(v.string(), v.minLength(1), v.maxLength(4096)), art: label, file: label }),
+  v.strictObject({ kind: v.literal('held.claims.prepare'), id, source: v.exactOptional(v.strictObject({ slots: label, library: label })) }),
+  v.strictObject({ kind: v.literal('population.product-creatures') }),
+  v.strictObject({ kind: v.literal('population.hull-book') }),
+  v.strictObject({ kind: v.literal('held.claims.install'), claims: id, preparation: v.exactOptional(v.picklist(['kit','world'])) }),
+  v.strictObject({ kind: v.literal('held.claims.enter'), claims: id,
+    grapple: v.strictObject({ item: id, profile: GrappleProfileSchema, hooks: GrappleHooksSchema, presentation: label }) }),
+  v.strictObject({ kind: v.literal('portal.ride'), rows: DeclaredPortalRideSchema }),
+  v.strictObject({ kind: v.literal('held.cosmetics') }),
+  v.strictObject({ kind: v.literal('held.ranged-feel') }),
+  v.strictObject({kind:v.literal('bag.finds'),id,quest:id,file:label}),
+  v.strictObject({kind:v.literal('look.painterly'),shadeTint:rgb,rimColor:rgb,wind:v.strictObject({x:finite,z:finite,strength:finite})}),
+  v.strictObject({ kind: v.literal('audio.scene') }),
+  // G571: a shard's declared forest page (and its cave at the page-mode texture cap), its weather and its ambient life
+  v.strictObject({ kind: v.literal('world.forest-page'), file: label, cave: v.exactOptional(v.strictObject({ file: label,
+    cap: v.strictObject({ shard: v.nullable(PageCapSchema), grid: v.nullable(PageCapSchema) }),
+    spots: v.exactOptional(v.strictObject({ ranged: label, zone: id, fade: finite, max: v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(256)) })) })) }),
+  v.strictObject({ kind: v.literal('weather.forest'), file: label, owner: v.exactOptional(id), hud: v.exactOptional(v.literal(true)) }),
+  v.strictObject({ kind: v.literal('page.life'), file: label, ranged: label, object: v.exactOptional(id) }),
+  v.strictObject({ kind: v.literal('held.ranged-page'), file: label, shadowBatch: v.exactOptional(v.strictObject({ shard: v.boolean(), grid: v.boolean() })) }),
+  v.strictObject({ kind: v.literal('arena-room.entry'), owner: id, claims: id, reward: id, publish: id, equipment: v.exactOptional(v.literal('held-finishes')) }),
+  v.strictObject({ kind: v.literal('taming.entry'), riding: id, publish: id, object: v.exactOptional(id) }),
+  v.strictObject({ kind: v.literal('elite.entry'), owner: id, adventure: id, body: id, rock: v.strictObject({ x: finite, z: finite, top: finite }), taming: v.exactOptional(id) }),
+  v.strictObject({ kind: v.literal('quest.chapter-view'), chapterView: label, story: label, arena: id, fight: id, taming: v.exactOptional(id) }),
+  v.strictObject({ kind: v.literal('quest.continuation'), file: label }),
+  v.strictObject({ kind: v.literal('quest.views'), file: label }),
+  v.strictObject({ kind: v.literal('view.program'), id, rows: ViewProgramSchema, module: label }),
+  v.strictObject({ kind: v.literal('quest.world'), file: label, ambient: v.exactOptional(id) }),
+  v.strictObject({ kind: v.literal('quest.reference'), id }),
+  v.strictObject({ kind: v.literal('quest.composition'), id, file: label,
+    equipment: v.exactOptional(v.strictObject({ ranged: id, animals: id, sounds: id })),
+    figures: v.exactOptional(v.strictObject({ file: label, draws: id })), reference: v.exactOptional(id) }),
+  v.strictObject({ kind: v.literal('quest.spawns'), id, source: QuestRuntimeFileSchema, quest: id, animals: id, sounds: id }),
+  v.strictObject({kind:v.literal('world.water'),rows:v.pipe(v.array(v.union([v.strictObject({id,surface:WaterSurfaceSchema,geometry:v.pipe(v.string(),v.minLength(1),v.maxLength(256))}),v.strictObject({id,surface:WaterSurfaceSchema,draw:WaterDrawSchema})])),v.minLength(1),v.maxLength(8),v.check(rows=>new Set(rows.map(row=>row.id)).size===rows.length))}),
+  v.strictObject({ kind: v.literal('world.scenes') }),
+  v.strictObject({ kind: v.literal('world.baked'), rows: v.pipe(v.array(BakedTilesSchema), v.minLength(1), v.maxLength(4), v.check(rows => new Set(rows.map(row => row.id)).size === rows.length, 'unique baked tile ids')) }),
+  v.strictObject({ kind: v.literal('motion.channels'), rows: SceneMotionSchema }),
+  ClientHeldMeleeSchema, ClientSpeciesProgramSchema, ClientQuestPageSchema, ClientPopulationSchema, ClientTrailsSchema, ClientCuesSchema,
+  ClientHeldBossSchema, ClientSpawnedBossSchema, ClientPlayerEnterSchema, ClientBossTelegraphSchema,
+  v.strictObject({ kind: v.literal('light.emitters'), rows: LightEmittersSchema }),
+  v.strictObject({ kind: v.literal('weather.fields'), rows: EasedFieldsSchema, quest: id }),
+  v.pipe(v.strictObject({ kind: v.literal('debug.expose'), name: id, objects: v.exactOptional(v.pipe(v.array(id), v.minLength(1), v.maxLength(16), v.check(keys => new Set(keys).size === keys.length, 'Unique debug object keys'))),
+    source:v.exactOptional(v.variant('kind',[
+      v.strictObject({kind:v.literal('runtime-object'),id}),v.strictObject({kind:v.literal('dressing')}),
+      v.strictObject({kind:v.literal('timed-riders'),owner:id}),v.strictObject({kind:v.literal('world-weather'),owner:id}),
+      v.strictObject({kind:v.literal('arena-room'),owner:id}),
+    ])) }),v.check(row=>row.objects===undefined||row.source===undefined,'Debug exposure requires one concrete source')),
+]);
+/** Rows are unordered. Phase, rank and lifetime belong exclusively to the compiled registry. */
+export const ClientPlanSchema: v.GenericSchema<unknown, ClientPlan> = v.pipe(v.unknown(), v.check(isJsonData, 'Client plan requires plain JSON'), v.strictObject({ version: v.literal(1), features: v.pipe(v.array(ClientFeatureSchema), v.maxLength(64)) }),
+  v.check(plan => new Set(plan.features.map(row => row.kind === 'debug.expose' ? `${row.kind}:${row.name}` : row.kind === 'view.program' ? `${row.kind}:${row.id}` : row.kind === 'arena-room.entry' ? `${row.kind}:${row.owner}` : row.kind)).size === plan.features.length, 'Duplicate client feature'),
+  v.check(plan => { const entries=plan.features.filter(row=>row.kind==='arena-room.entry');return new Set(entries.map(row=>row.publish)).size===entries.length; },'Duplicate arena entry publication'));
+export interface ClientPlan { version: 1; features: ClientFeatureRow[] }
+export type ClientFeatureInput = { kind: 'strings.register'; } | { kind: 'content.catalogue'; quests: boolean;
+  finishes: boolean; economy?: v.InferInput<typeof CatalogueEconomySchema>; weapons: (string)[]; ammunition:
+  (string)[]; effects: ('starter' | 'finishes')[]; compendiums: (string)[]; encounters: ({ id: string;
+  displayName: string; showHeadBar: boolean; })[]; } | { kind: 'state.adventure'; file: string; id?: string;
+  progress?: true; } | { kind: 'world.meadow'; file: string; } | { kind: 'world.ambient-life'; file: string;
+  flocks: ({ id: string; owner: string; })[]; } | { kind: 'world.updates'; rows: v.InferInput<typeof
+  WorldUpdatesSchema>; } | v.InferInput<typeof DeclaredCombatTargetsSchema> | { kind: 'world.assembly'; native?:
+  { groups: string; }; library?: string; catalogue?: string; farStandIn?: true; entered?: { root: string; blocks: (string)[]; };
+  rows: v.InferInput<typeof WorldAssemblySchema>; } | { kind: 'world.runtime-hooks'; bounds?: RuntimeBounds;
+  floor?: string; overhead: (string)[]; meleeSilent?: boolean; } | { kind: 'world.movers'; system: string;
+  bindings: ({ kind: 'object'; id: string; owner: string; order?: 'XYZ' | 'YXZ'; visibility?: 'enabled'; moor?:
+  { look: string; water: number; cleats: [number, number]; }; } | { kind: 'chain'; id: string; owner: string;
+  })[]; } | { kind: 'world.bind-sets'; placed: (string)[]; groups: ({ id: string; placed: (string)[]; })[];
+  quest?: string; } | { kind: 'world.paths'; rows: v.InferInput<typeof PagePathRampSchema>; } | { kind:
+  'world.dressing'; } | { kind: 'population.wildlife'; file: string; crowd: { json: string; binary: string; };
+  navSteer: boolean; publish?: string; frame: { id: string; after: (string)[]; before: (string)[]; }; } | {
+  kind: 'world.sets'; rows: ({ place: string; id: string; name: string; file: string; pois?: (string)[] |
+  undefined; x: number; z: number; r: number; mode?: 'centre' | 'bounds'; })[]; } | { kind: 'riding.session';
+  file: string; owner?: string; } | { kind: 'stealth.entry'; owner: string; claims: string; riding: string;
+  night: string; bow: string; melee: string; impactExclusion: number; debugRiding?: string; frame: { id: string;
+  after: (string)[]; before: (string)[]; }; } | { kind: 'elite.construct'; owner: string; rows: v.InferInput<typeof EliteEntryPageRowsSchema>;
+  admission: string; fight: string; models: string; program: string; weather: string; night: string; ledges: {
+  part: string; anchor: string; }; } | { kind: 'timed.encounters'; owner: string; file: string; draws: string;
+  species: string; guest: string; weather: string; sites?: string; figures: { rider: string; captain: string;
+  storm: 'rider' | 'captain'; }; } | { kind: 'practice.course'; course: 'horse' | 'grapple'; title: string;
+  blurb: string; icon: string; art: string; file: string; } | { kind: 'held.claims.prepare'; id: string;
+  source?: { slots: string; library: string; }; } | { kind: 'population.product-creatures'; } | { kind:
+  'population.hull-book'; } | { kind: 'held.claims.install'; claims: string; preparation?: 'kit' | 'world'; } |
+  { kind: 'held.claims.enter'; claims: string; grapple: { item: string; profile: v.InferInput<typeof GrappleProfileSchema>; hooks: v.InferOutput<typeof GrappleHooksSchema>; presentation: string; };
+  } | { kind: 'portal.ride'; rows: v.InferInput<typeof DeclaredPortalRideSchema>; } | { kind: 'held.cosmetics'; } | { kind: 'held.ranged-feel'; } | {
+  kind: 'bag.finds'; id: string; quest: string; file: string; } | { kind: 'look.painterly'; shadeTint: [number,
+  number, number]; rimColor: [number, number, number]; wind: { x: number; z: number; strength: number; }; } | {
+  kind: 'audio.scene'; } | { kind: 'world.forest-page'; file: string; cave?: { file: string; cap: { shard: ({
+  through: number; max: number; }) | null; grid: ({ through: number; max: number; }) | null; }; spots?: {
+  ranged: string; zone: string; fade: number; max: number; }; }; } | { kind: 'weather.forest'; file: string;
+  owner?: string; hud?: true; } | { kind: 'page.life'; file: string; ranged: string; object?: string; } | {
+  kind: 'held.ranged-page'; file: string; shadowBatch?: { shard: boolean; grid: boolean; }; } | { kind:
+  'arena-room.entry'; owner: string; claims: string; reward: string; publish: string; equipment?:
+  'held-finishes'; } | { kind: 'taming.entry'; riding: string; publish: string; object?: string; } | { kind:
+  'elite.entry'; owner: string; adventure: string; body: string; rock: { x: number; z: number; top: number; };
+  taming?: string; } | { kind: 'quest.chapter-view'; chapterView: string; story: string; arena: string; fight:
+  string; taming?: string; } | { kind: 'quest.continuation'; file: string; } | { kind: 'quest.views'; file:
+  string; } | { kind: 'view.program'; id: string; rows: v.InferInput<typeof ViewProgramSchema>; module: string;
+  } | { kind: 'quest.world'; file: string; ambient?: string; } | { kind: 'quest.reference'; id: string; } | {
+  kind: 'quest.composition'; id: string; file: string; equipment?: { ranged: string; animals: string; sounds:
+  string; }; figures?: { file: string; draws: string; }; reference?: string; } | { kind: 'quest.spawns'; id:
+  string; source: string; quest: string; animals: string; sounds: string; } | { kind: 'world.water'; rows: ({
+  id: string; surface: v.InferInput<typeof WaterSurfaceSchema>; geometry: string; } | { id: string; surface:
+  v.InferInput<typeof WaterSurfaceSchema>; draw: { grid: { phone: v.InferInput<typeof BakedSourceSchema>;
+  desktop: v.InferInput<typeof BakedSourceSchema>; }; attributes: Record<string, string>; level: number; floor?:
+  v.InferInput<typeof BakedSourceSchema>; dry: ({ minX: number; minZ: number; maxX: number; maxZ: number; })[];
+  foam: ({ x: number; z: number; hw: number; hd: number; rot: number; yTop: number; yBottom: number; })[]; lent:
+  Record<string, 'uCloudShadow' | 'uToonNight' | 'uSeaLevel' | 'uCloudTime'>; toonSeaLevel: boolean; }; })[]; }
+  | { kind: 'world.scenes'; } | { kind: 'world.baked'; rows: (v.InferInput<typeof BakedTilesSchema>)[]; } | {
+  kind: 'motion.channels'; rows: v.InferInput<typeof SceneMotionSchema>; } | v.InferInput<typeof
+  ClientHeldMeleeSchema> | v.InferInput<typeof ClientSpeciesProgramSchema> | v.InferInput<typeof
+  ClientQuestPageSchema> | v.InferInput<typeof ClientPopulationSchema> | v.InferInput<typeof ClientTrailsSchema>
+  | v.InferInput<typeof ClientCuesSchema> | v.InferInput<typeof ClientHeldBossSchema> | v.InferInput<typeof
+  ClientSpawnedBossSchema> | v.InferInput<typeof ClientPlayerEnterSchema> | v.InferInput<typeof
+  ClientBossTelegraphSchema> | { kind: 'light.emitters'; rows: v.InferInput<typeof LightEmittersSchema>; } | {
+  kind: 'weather.fields'; rows: v.InferInput<typeof EasedFieldsSchema>; quest: string; } | { kind:
+  'debug.expose'; name: string; objects?: (string)[]; source?: { kind: 'runtime-object'; id: string; } | { kind:
+  'dressing'; } | { kind: 'timed-riders'; owner: string; } | { kind: 'world-weather'; owner: string; } | { kind:
+  'arena-room'; owner: string; }; };
+export type ClientFeatureRow = { kind: 'strings.register'; } | { kind: 'content.catalogue'; quests: boolean;
+  finishes: boolean; economy?: v.InferOutput<typeof CatalogueEconomySchema>; weapons: (string)[]; ammunition:
+  (string)[]; effects: ('starter' | 'finishes')[]; compendiums: (string)[]; encounters: ({ id: string;
+  displayName: string; showHeadBar: boolean; })[]; } | { kind: 'state.adventure'; file: string; id?: string;
+  progress?: true; } | { kind: 'world.meadow'; file: string; } | { kind: 'world.ambient-life'; file: string;
+  flocks: ({ id: string; owner: string; })[]; } | { kind: 'world.updates'; rows: v.InferOutput<typeof
+  WorldUpdatesSchema>; } | v.InferOutput<typeof DeclaredCombatTargetsSchema> | { kind: 'world.assembly';
+  native?: { groups: string; }; library?: string; catalogue?: string; farStandIn?: true; entered?: { root: string; blocks:
+  (string)[]; }; rows: v.InferOutput<typeof WorldAssemblySchema>; } | { kind: 'world.runtime-hooks'; bounds?:
+  RuntimeBounds; floor?: string; overhead: (string)[]; meleeSilent?: boolean; } | { kind: 'world.movers';
+  system: string; bindings: ({ kind: 'object'; id: string; owner: string; order?: 'XYZ' | 'YXZ'; visibility?:
+  'enabled'; moor?: { look: string; water: number; cleats: [number, number]; }; } | { kind: 'chain'; id: string;
+  owner: string; })[]; } | { kind: 'world.bind-sets'; placed: (string)[]; groups: ({ id: string; placed:
+  (string)[]; })[]; quest?: string; } | { kind: 'world.paths'; rows: v.InferOutput<typeof PagePathRampSchema>; }
+  | { kind: 'world.dressing'; } | { kind: 'population.wildlife'; file: string; crowd: { json: string; binary:
+  string; }; navSteer: boolean; publish?: string; frame: { id: string; after: (string)[]; before: (string)[]; };
+  } | { kind: 'world.sets'; rows: ({ place: string; id: string; name: string; file: string; pois: (string)[]; x:
+  number; z: number; r: number; mode?: 'centre' | 'bounds'; })[]; } | { kind: 'riding.session'; file: string;
+  owner?: string; } | { kind: 'stealth.entry'; owner: string; claims: string; riding: string; night: string;
+  bow: string; melee: string; impactExclusion: number; debugRiding?: string; frame: { id: string; after:
+  (string)[]; before: (string)[]; }; } | { kind: 'elite.construct'; owner: string; rows: v.InferOutput<typeof EliteEntryPageRowsSchema>; admission:
+  string; fight: string; models: string; program: string; weather: string; night: string; ledges: { part:
+  string; anchor: string; }; } | { kind: 'timed.encounters'; owner: string; file: string; draws: string;
+  species: string; guest: string; weather: string; sites?: string; figures: { rider: string; captain: string;
+  storm: 'rider' | 'captain'; }; } | { kind: 'practice.course'; course: 'horse' | 'grapple'; title: string;
+  blurb: string; icon: string; art: string; file: string; } | { kind: 'held.claims.prepare'; id: string;
+  source?: { slots: string; library: string; }; } | { kind: 'population.product-creatures'; } | { kind:
+  'population.hull-book'; } | { kind: 'held.claims.install'; claims: string; preparation?: 'kit' | 'world'; } |
+  { kind: 'held.claims.enter'; claims: string; grapple: { item: string; profile: v.InferOutput<typeof GrappleProfileSchema>; hooks: v.InferOutput<typeof GrappleHooksSchema>; presentation: string; };
+  } | { kind: 'portal.ride'; rows: v.InferOutput<typeof DeclaredPortalRideSchema>; } | { kind: 'held.cosmetics'; } | { kind: 'held.ranged-feel'; } | {
+  kind: 'bag.finds'; id: string; quest: string; file: string; } | { kind: 'look.painterly'; shadeTint: [number,
+  number, number]; rimColor: [number, number, number]; wind: { x: number; z: number; strength: number; }; } | {
+  kind: 'audio.scene'; } | { kind: 'world.forest-page'; file: string; cave?: { file: string; cap: { shard: ({
+  through: number; max: number; }) | null; grid: ({ through: number; max: number; }) | null; }; spots?: {
+  ranged: string; zone: string; fade: number; max: number; }; }; } | { kind: 'weather.forest'; file: string;
+  owner?: string; hud?: true; } | { kind: 'page.life'; file: string; ranged: string; object?: string; } | {
+  kind: 'held.ranged-page'; file: string; shadowBatch?: { shard: boolean; grid: boolean; }; } | { kind:
+  'arena-room.entry'; owner: string; claims: string; reward: string; publish: string; equipment?:
+  'held-finishes'; } | { kind: 'taming.entry'; riding: string; publish: string; object?: string; } | { kind:
+  'elite.entry'; owner: string; adventure: string; body: string; rock: { x: number; z: number; top: number; };
+  taming?: string; } | { kind: 'quest.chapter-view'; chapterView: string; story: string; arena: string; fight:
+  string; taming?: string; } | { kind: 'quest.continuation'; file: string; } | { kind: 'quest.views'; file:
+  string; } | { kind: 'view.program'; id: string; rows: v.InferOutput<typeof ViewProgramSchema>; module: string;
+  } | { kind: 'quest.world'; file: string; ambient?: string; } | { kind: 'quest.reference'; id: string; } | {
+  kind: 'quest.composition'; id: string; file: string; equipment?: { ranged: string; animals: string; sounds:
+  string; }; figures?: { file: string; draws: string; }; reference?: string; } | { kind: 'quest.spawns'; id:
+  string; source: string; quest: string; animals: string; sounds: string; } | { kind: 'world.water'; rows: ({
+  id: string; surface: v.InferOutput<typeof WaterSurfaceSchema>; geometry: string; } | { id: string; surface:
+  v.InferOutput<typeof WaterSurfaceSchema>; draw: { grid: { phone: v.InferOutput<typeof BakedSourceSchema>;
+  desktop: v.InferOutput<typeof BakedSourceSchema>; }; attributes: Record<string, string>; level: number;
+  floor?: v.InferOutput<typeof BakedSourceSchema>; dry: ({ minX: number; minZ: number; maxX: number; maxZ:
+  number; })[]; foam: ({ x: number; z: number; hw: number; hd: number; rot: number; yTop: number; yBottom:
+  number; })[]; lent: Record<string, 'uCloudShadow' | 'uToonNight' | 'uSeaLevel' | 'uCloudTime'>; toonSeaLevel:
+  boolean; }; })[]; } | { kind: 'world.scenes'; } | { kind: 'world.baked'; rows: (v.InferOutput<typeof
+  BakedTilesSchema>)[]; } | { kind: 'motion.channels'; rows: v.InferOutput<typeof SceneMotionSchema>; } |
+  v.InferOutput<typeof ClientHeldMeleeSchema> | v.InferOutput<typeof ClientSpeciesProgramSchema> |
+  v.InferOutput<typeof ClientQuestPageSchema> | v.InferOutput<typeof ClientPopulationSchema> |
+  v.InferOutput<typeof ClientTrailsSchema> | v.InferOutput<typeof ClientCuesSchema> | v.InferOutput<typeof
+  ClientHeldBossSchema> | v.InferOutput<typeof ClientSpawnedBossSchema> | v.InferOutput<typeof
+  ClientPlayerEnterSchema> | v.InferOutput<typeof ClientBossTelegraphSchema> | { kind: 'light.emitters'; rows:
+  v.InferOutput<typeof LightEmittersSchema>; } | { kind: 'weather.fields'; rows: v.InferOutput<typeof
+  EasedFieldsSchema>; quest: string; } | { kind: 'debug.expose'; name: string; objects?: (string)[]; source?: {
+  kind: 'runtime-object'; id: string; } | { kind: 'dressing'; } | { kind: 'timed-riders'; owner: string; } | {
+  kind: 'world-weather'; owner: string; } | { kind: 'arena-room'; owner: string; }; };
+export type ClientFeatureKind = ClientFeatureRow['kind'];
+const parsedPlans = new WeakMap<object, ClientPlan>();
+function freezePlanRows(value: unknown): void {
+  if (typeof value !== 'object' || value === null) return;
+  for (const child of Object.values(value)) freezePlanRows(child);
+  Object.freeze(value);
+}
+/** Strict admission rejects unknown kinds and executable/reflected settings before
+ * installation. Ownership checks can reuse only this parser's immutable output;
+ * raw product sections and author copies always pass the complete schema. */
+export function parseClientPlan(input: unknown): ClientPlan {
+  const known = typeof input === 'object' && input !== null ? parsedPlans.get(input) : undefined;
+  if (known !== undefined) return known;
+  const plan = v.parse(ClientPlanSchema, input);
+  freezePlanRows(plan);
+  parsedPlans.set(plan, plan);
+  return plan;
+}
+
+/** Optional code selected by defining rows; debug borrows dressing only when named. */
+export function clientPlanModuleGroups(plan: { readonly features: readonly ClientFeatureRow[] }): string[] {
+  return plan.features.filter(row => row.kind !== 'debug.expose' || row.source?.kind === 'dressing').map(row => row.kind);
+}
+
+/** Validated play bounds, independent of the validator implementation. */
+export interface RuntimeBounds { x: [number, number]; z: [number, number]; outer: { maxAbsXZ: number; floor:
+  number; }; }

package/src/format/clientScripts.ts

@@ -0,0 +1,116 @@
+import * as v from 'valibot';
+import { CLIENT_SCRIPT_LIMITS } from './wireLimits.ts';
+
+const finite = v.pipe(v.number(), v.finite()), positive = v.pipe(finite, v.integer(), v.minValue(1), v.maxValue(0x7fffffff));
+const name = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u), v.maxLength(128));
+const targetId = v.pipe(v.string(), v.regex(/^[a-z][a-zA-Z0-9.:-]*$/u), v.maxLength(128));
+const ref = v.pipe(v.string(), v.regex(/^(?:commons:)?[a-f0-9]{64}$/u));
+const coordinate = v.pipe(finite, v.minValue(-250), v.maxValue(250)), vec3 = v.tuple([coordinate, coordinate, coordinate]);
+const channel = v.pipe(finite, v.minValue(0), v.maxValue(1)), velocity = v.pipe(finite, v.minValue(-15), v.maxValue(15));
+const target = v.variant('kind', [v.strictObject({ kind: v.literal('creature'), id: targetId }), v.strictObject({ kind: v.literal('panel'), id: targetId }), v.strictObject({ kind: v.literal('prop'), id: targetId }),
+  v.strictObject({ kind: v.literal('particles'), id: targetId, at: vec3 })]);
+const emitter = v.strictObject({ id: positive, recipe: v.literal('platform.particles'), perTick: v.pipe(positive, v.maxValue(256)), live: v.pipe(positive, v.maxValue(4096)), lifetimeTicks: v.pipe(positive, v.maxValue(3600)),
+  colour: v.tuple([channel, channel, channel]), size: v.pipe(finite, v.minValue(0.01), v.maxValue(4)), velocity: v.tuple([velocity, velocity, velocity]), gravity: v.pipe(finite, v.minValue(-30), v.maxValue(30)) });
+/** Presentation bytecode binds visual targets and selected numeric state; it never joins the authoritative script lane. */
+export const ClientScriptsSchema: v.GenericSchema<ShardClientScriptsInput, ShardClientScripts> = v.strictObject({ divisor: v.pipe(positive, v.check((n) => 60 % n === 0, 'Client cadence divides 60')),
+  bindings: v.pipe(v.array(v.strictObject({ module: ref, entity: positive, name, target,
+    reads: v.pipe(v.array(v.strictObject({ scope: v.picklist(['shared', 'player']), id: positive })), v.maxLength(CLIENT_SCRIPT_LIMITS.fields)),
+    parameters: v.pipe(v.array(finite), v.maxLength(CLIENT_SCRIPT_LIMITS.parameters)), pose: v.boolean(), maxOffset: v.pipe(finite, v.minValue(0), v.maxValue(50)),
+    minScale: v.pipe(finite, v.minValue(0.01), v.maxValue(1)), maxScale: v.pipe(finite, v.minValue(1), v.maxValue(16)),
+    emitters: v.pipe(v.array(emitter), v.maxLength(CLIENT_SCRIPT_LIMITS.emitters)) })), v.maxLength(CLIENT_SCRIPT_LIMITS.bindings)) });
+/** Renderer-neutral declaration consumed by the client and the frozen-neighbour presentation adapter. */
+
+/** Charge the bounded particle pool: 56 CPU bytes and 32 GPU bytes per live slot. */
+export function clientScriptViewCost(data: ShardClientScripts): { capacity: number; decoded: number; gpu: number; triangles: number; draws: number } {
+  const capacity = Math.min(CLIENT_SCRIPT_LIMITS.particlesLive, data.bindings.reduce((sum, binding) => sum + binding.emitters.reduce((n, row) => n + row.live, 0), 0));
+  return { capacity, decoded: capacity * 56, gpu: capacity * 32, triangles: 0, draws: capacity > 0 ? 1 : 0 };
+}
+/** A declared visual anchor resolved by trusted composition, never by a bytecode physics query. */
+export type ClientScriptTarget = ShardClientScripts['bindings'][number]['target'];
+/** Minimal format view for admission and projection, independent of rendering and author callbacks. */
+export interface ClientScriptContent {
+  identity: { seed: number }; clientScripts: ShardClientScripts;
+  state: { shared: readonly { id: number; name: string; type: string; privacy: string }[]; player: readonly { id: number; name: string; type: string; privacy: string }[] };
+  sim: { scripts: readonly string[] }; files: readonly { hash: string; kind: string; dependencies: readonly string[] }[]; library: readonly string[];
+  creatures: { spawns: readonly { id: string }[] }; props: { panels: readonly { id: string }[]; models: readonly { id: string }[] } | null;
+}
+/** Refuse hidden fields, undeclared targets, competing writers and modules outside the admitted render library. */
+export function clientScriptRules(source: ClientScriptContent): string[] {
+  const bindings = source.clientScripts.bindings, errors: string[] = [], closure = new Set<string>(), files = new Map(source.files.map((file) => [file.hash, file]));
+  const include = (id: string): void => { if (closure.has(id)) return; closure.add(id); for (const dependency of files.get(id)?.dependencies ?? []) include(dependency); };
+  for (const root of source.library) include(root);
+  if (new Set(bindings.map((b) => b.entity)).size !== bindings.length || new Set(bindings.map((b) => b.name)).size !== bindings.length || new Set(bindings.map((b) => `${b.target.kind}/${b.target.id}`)).size !== bindings.length) errors.push('unique client visual bindings');
+  for (const binding of bindings) {
+    if (!closure.has(binding.module) || source.sim.scripts.includes(binding.module) || (!binding.module.startsWith('commons:') && files.get(binding.module)?.kind !== 'wasm')) errors.push('client Wasm module belongs only to library');
+    if (binding.target.kind === 'creature' && !source.creatures.spawns.some((spawn) => spawn.id === binding.target.id)) errors.push('declared client creature target');
+    if (binding.target.kind === 'panel' && !source.props?.panels.some((panel) => panel.id === binding.target.id)) errors.push('declared client panel target');
+    if (binding.target.kind === 'prop' && !source.props?.models.some((model) => model.id === binding.target.id)) errors.push('declared client prop target');
+    if (binding.target.kind === 'particles' && binding.pose) errors.push('particle anchor has no pose writer');
+    if (new Set(binding.emitters.map((row) => row.id)).size !== binding.emitters.length || new Set(binding.reads.map((row) => `${row.scope}/${row.id}`)).size !== binding.reads.length) errors.push('unique client emitters and reads');
+    for (const read of binding.reads) {
+      const field = source.state[read.scope].find((row) => row.id === read.id);
+      if (field === undefined || field.type === 'string' || (read.scope === 'shared' ? field.privacy !== 'public' : field.privacy === 'host')) errors.push('client state read must be public or owned numeric');
+    }
+  }
+  return [...new Set(errors)];
+}
+/** Parse detached strict data before host composition allocates any guest instance. */
+export function parseClientScripts(input: unknown): ShardClientScripts { return v.parse(ClientScriptsSchema, input); }
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type ShardClientScriptsInput = ShardClientScripts;
+interface ShardClientScriptsFields {
+    divisor: number;
+    bindings: ({
+        module: string;
+        entity: number;
+        name: string;
+        target: ({
+            kind: 'creature';
+            id: string;
+        }) | ({
+            kind: 'panel';
+            id: string;
+        }) | ({
+            kind: 'prop';
+            id: string;
+        }) | ({
+            kind: 'particles';
+            id: string;
+            at: [
+                number,
+                number,
+                number
+            ];
+        });
+        reads: ({
+            scope: 'shared' | 'player';
+            id: number;
+        })[];
+        parameters: (number)[];
+        pose: boolean;
+        maxOffset: number;
+        minScale: number;
+        maxScale: number;
+        emitters: ({
+            id: number;
+            recipe: 'platform.particles';
+            perTick: number;
+            live: number;
+            lifetimeTicks: number;
+            colour: [
+                number,
+                number,
+                number
+            ];
+            size: number;
+            velocity: [
+                number,
+                number,
+                number
+            ];
+            gravity: number;
+        })[];
+    })[];
+}
+export type ShardClientScripts = { [Key in keyof ShardClientScriptsFields]: ShardClientScriptsFields[Key] };