@wildshard/shard-format 0.0.0 → 0.4.5

package/src/format/panelTemplate.ts

@@ -0,0 +1,139 @@
+import * as v from 'valibot';
+
+/** Bounded, read-only expressions over caller-owned panel values. */
+export type PanelValue = string | number | boolean | { read: string } | { concat: PanelValue[] }
+  | { choose: PanelCondition; yes: PanelValue; no: PanelValue }
+  | { lookup: Record<string, string | number>; key: PanelValue; fallback: string | number };
+/** Comparisons do not mutate gameplay state. */
+export interface PanelCondition { left: PanelValue; op: 'eq' | 'lt' | 'gte'; right: PanelValue }
+/** A button delivers a named existing owner action, optionally reading a text field before closing. */
+export interface PanelAction { id: string; arg?: PanelValue; input?: string; close?: boolean }
+/** Markup and its finite repeated children; input and view lifetimes remain platform-owned. */
+export interface PanelTemplate {
+  tag?: 'div' | 'span' | 'b' | 'i' | 'small' | 'p' | 'strong' | 'em' | 'button' | 'input' | 'meter';
+  cls?: PanelValue; text?: PanelValue; ref?: PanelValue; button?: 'button' | 'submit' | 'reset';
+  attrs?: [string, string][]; props?: [string, PanelValue][];
+  input?: { type?: string; maxLength?: number; value?: PanelValue; autocomplete?: 'off'; spellcheck?: boolean };
+  when?: PanelCondition; repeat?: { source: string; as: string; index?: string };
+  action?: PanelAction; children?: PanelTemplate[];
+}
+const text = v.pipe(v.string(), v.maxLength(4096));
+const path = v.pipe(v.string(), v.regex(/^[a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*$/u), v.maxLength(128),
+  v.check(value => value.split('.').every(key => !['__proto__', 'constructor', 'prototype'].includes(key))));
+const attribute = v.pipe(text, v.regex(/^(?:aria-[a-z-]+|data-[a-z-]+|autocapitalize|enterkeyhint|role|title)$/u));
+const scalar = v.union([text, v.pipe(v.number(), v.minValue(-Number.MAX_VALUE), v.maxValue(Number.MAX_VALUE)), v.boolean()]);
+const value: v.GenericSchema<unknown, PanelValue> = v.lazy(() => v.union([scalar,
+  v.strictObject({ read: path }), v.strictObject({ concat: v.pipe(v.array(value), v.maxLength(32)) }),
+  v.strictObject({ choose: conditionSchema(), yes: value, no: value }),
+  v.strictObject({ lookup: v.record(text, v.union([text, v.number()])), key: value, fallback: v.union([text, v.number()]) }),
+]));
+function conditionSchema(): v.GenericSchema<unknown, PanelCondition> {
+  return v.strictObject({ left: value, op: v.picklist(['eq', 'lt', 'gte']), right: value });
+}
+const action: v.GenericSchema<unknown, PanelAction> = v.strictObject({ id: path, arg: v.exactOptional(value), input: v.exactOptional(path), close: v.exactOptional(v.boolean()) });
+const template: v.GenericSchema<unknown, PanelTemplate> = v.lazy(() => v.strictObject({
+  tag: v.exactOptional(v.picklist(['div', 'span', 'b', 'i', 'small', 'p', 'strong', 'em', 'button', 'input', 'meter'])),
+  cls: v.exactOptional(value), text: v.exactOptional(value), ref: v.exactOptional(value), button: v.exactOptional(v.picklist(['button', 'submit', 'reset'])),
+  attrs: v.exactOptional(v.pipe(v.array(v.tuple([attribute, text])), v.maxLength(32))),
+  props: v.exactOptional(v.pipe(v.array(v.tuple([text, value])), v.maxLength(32))),
+  input: v.exactOptional(v.strictObject({ type: v.exactOptional(text), maxLength: v.exactOptional(v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(4096))),
+    value: v.exactOptional(value), autocomplete: v.exactOptional(v.literal('off')), spellcheck: v.exactOptional(v.boolean()) })),
+  when: v.exactOptional(conditionSchema()), repeat: v.exactOptional(v.strictObject({ source: path, as: path, index: v.exactOptional(path) })),
+  action: v.exactOptional(action), children: v.exactOptional(v.pipe(v.array(template), v.maxLength(256))),
+}));
+export const PanelDefinitionSchema: v.GenericSchema<PanelDefinitionInput, PanelDefinition> = v.strictObject({ frame: template, body: v.exactOptional(v.pipe(v.array(template), v.maxLength(256))),
+  lifetime: v.picklist(['persistent', 'open']), showClass: v.exactOptional(text), closeRef: v.exactOptional(text),
+  closeKeys: v.exactOptional(v.pipe(v.array(text), v.maxLength(32))),
+  stopEvents: v.exactOptional(v.pipe(v.array(v.picklist(['pointerdown', 'touchstart', 'mousedown'])), v.maxLength(3))),
+  keys: v.exactOptional(v.pipe(v.array(v.strictObject({ codes: v.pipe(v.array(text), v.maxLength(16)), action })), v.maxLength(16))),
+  stopTyping: v.exactOptional(v.boolean()), focus: v.exactOptional(text),
+  inputGuard: v.exactOptional(v.strictObject({ ref: text, milliseconds: v.pipe(v.number(), v.minValue(0), v.maxValue(1000)) })),
+  layer: v.exactOptional(v.strictObject({ order: v.number() })),
+  transient: v.exactOptional(v.strictObject({ milliseconds: v.pipe(v.number(), v.minValue(0), v.maxValue(60000)),
+    flags: v.pipe(v.array(v.strictObject({ cls: text, when: conditionSchema() })), v.maxLength(16)) })),
+});
+/** Admitted content shared by renderer-free expansion and the page adapter. */
+
+/** Refuse deep/unbounded programs before recursive schema admission. */
+export function parsePanelDefinition(input: unknown): PanelDefinition {
+  let nodes = 0;
+  const visit = (entry: unknown, depth: number): void => {
+    if (++nodes > 8192 || depth > 32) throw new RangeError('Panel template exceeds its bound');
+    if (typeof entry === 'object' && entry !== null) for (const child of Object.values(entry)) visit(child, depth + 1);
+  };
+  visit(input, 0);
+  const parsed = v.parse(PanelDefinitionSchema, input);
+  if (parsed.transient !== undefined && (parsed.lifetime !== 'persistent' || parsed.showClass === undefined)) throw new Error('Transient panel requires a persistent shown frame');
+  return parsed;
+}
+
+/** Whole catalogue used by the existing Pine and Nalati quest-panel readers.
+ * The native parser retains the original 16-panel and per-panel bounds. */
+export const QuestPanelCatalogueSchema: v.GenericSchema<Record<string, PanelDefinitionInput>, Readonly<Record<string, PanelDefinition>>> = v.pipe(v.record(v.string(), PanelDefinitionSchema), v.maxEntries(16));
+/** Preserve the original outer refusal before bounded per-panel admission. */
+export function parseQuestPanelCatalogue(input: unknown): Readonly<Record<string, PanelDefinition>> {
+  if (typeof input !== 'object' || input === null || Array.isArray(input) || Object.keys(input).length > 16) throw new Error('Invalid named panels');
+  return Object.fromEntries(Object.entries(input).map(([name, definition]) => [name, parsePanelDefinition(definition)]));
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+interface PanelDefinitionInputFields {
+    frame: v.InferInput<typeof template>;
+    body?: (v.InferInput<typeof template>)[];
+    lifetime: 'persistent' | 'open';
+    showClass?: string;
+    closeRef?: string;
+    closeKeys?: (string)[];
+    stopEvents?: ('pointerdown' | 'touchstart' | 'mousedown')[];
+    keys?: ({
+        codes: (string)[];
+        action: v.InferInput<typeof action>;
+    })[];
+    stopTyping?: boolean;
+    focus?: string;
+    inputGuard?: {
+        ref: string;
+        milliseconds: number;
+    };
+    layer?: {
+        order: number;
+    };
+    transient?: {
+        milliseconds: number;
+        flags: ({
+            cls: string;
+            when: v.InferInput<ReturnType<typeof conditionSchema>>;
+        })[];
+    };
+}
+export type PanelDefinitionInput = { [Key in keyof PanelDefinitionInputFields]: PanelDefinitionInputFields[Key] };
+interface PanelDefinitionFields {
+    frame: v.InferOutput<typeof template>;
+    body?: (v.InferOutput<typeof template>)[];
+    lifetime: 'persistent' | 'open';
+    showClass?: string;
+    closeRef?: string;
+    closeKeys?: (string)[];
+    stopEvents?: ('pointerdown' | 'touchstart' | 'mousedown')[];
+    keys?: ({
+        codes: (string)[];
+        action: v.InferOutput<typeof action>;
+    })[];
+    stopTyping?: boolean;
+    focus?: string;
+    inputGuard?: {
+        ref: string;
+        milliseconds: number;
+    };
+    layer?: {
+        order: number;
+    };
+    transient?: {
+        milliseconds: number;
+        flags: ({
+            cls: string;
+            when: v.InferOutput<ReturnType<typeof conditionSchema>>;
+        })[];
+    };
+}
+export type PanelDefinition = { [Key in keyof PanelDefinitionFields]: PanelDefinitionFields[Key] };

package/src/format/placeholderSource.ts

@@ -0,0 +1,209 @@
+import * as v from 'valibot';
+
+/**
+ * G348 (Jake: the near and far placeholders are generic features for any shard, with no per-shard code): what a shard
+ * declares, as its own data, to steer the placeholder bake. Absent fields take the bake's generic defaults: the ground
+ * is the shard's baked `terrain.bin`, and a forest drawn by its own tree model is stood in by one generic conifer.
+ */
+const byte = v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(255));
+const unit = v.pipe(v.number(), v.minValue(0), v.maxValue(1));
+/** sRGB 0..255 */
+const rgb = v.tuple([byte, byte, byte]);
+/**
+ * One stand-in tree shape, unit high (scaled by the placement's height): an optional stem (top, radius, colour) and the
+ * crown's rings (height, radius) under its apex, in the crown colour; `species` matches the forest placement's species.
+ */
+export const PlaceholderTreeSchema: v.GenericSchema<PlaceholderTreeInput, PlaceholderTree> = v.strictObject({
+  species: v.pipe(v.string(), v.regex(/^[a-z][a-z0-9-]{0,31}$/u)),
+  stem: v.nullable(v.tuple([unit, unit, rgb])),
+  rings: v.pipe(v.array(v.tuple([unit, unit])), v.maxLength(6)),
+  crown: rgb,
+});
+/** A named export of one of the shard's own bake-time modules (under its `look/` or `generators/`). */
+const ModuleExportSchema = v.strictObject({
+  module: v.pipe(v.string(), v.regex(/^(?:look|generators)\/[A-Za-z0-9_/-]+\.ts$/u)),
+  export: v.pipe(v.string(), v.regex(/^[A-Za-z_$][A-Za-z0-9_$]*$/u)),
+});
+/**
+ * How the shard's far proxy is coloured and shaped (G348; was `scripts/bake/farProxiesSource.ts`'s per-shard tables):
+ * its far look (a `FarLookSource`), an optional grid its look builds when its land is structures (a `() => FarGrid`),
+ * and optional model parts when its land is models (`(tools) => Promise<FarPart[]>`). Without a grid the bake reads the
+ * shard's baked `terrain.bin`, else its shardfile terrain collider.
+ */
+export const PlaceholderFarSchema: v.GenericSchema<PlaceholderFarRowsInput, PlaceholderFarRows> = v.strictObject({
+  look: ModuleExportSchema,
+  grid: v.optional(ModuleExportSchema),
+  parts: v.optional(ModuleExportSchema),
+});
+/**
+ * A shard's whole placeholder steer (`src/shards/<slug>/data/placeholder.ts`'s `PLACEHOLDER`, the one place the bakes
+ * look): where its ground comes from, how its forest is stood in and how its far proxy is coloured; every field is
+ * optional and an empty row means the bake's generic defaults.
+ */
+export const PlaceholderSourceSchema: v.GenericSchema<PlaceholderSourceInput, PlaceholderSource> = v.strictObject({
+  /** a ground built by the shard's own generator instead of its `terrain.bin`: a module under its `generators/` and the
+   *  export that returns the native terrain bytes */
+  ground: v.optional(v.strictObject({
+    generator: v.pipe(v.string(), v.regex(/^generators\/[A-Za-z0-9_/-]+\.ts$/u)),
+    export: v.pipe(v.string(), v.regex(/^[A-Za-z_$][A-Za-z0-9_$]*$/u)),
+  })),
+  /** the forest's stand-in shapes by species; a species without a row takes the first row */
+  trees: v.optional(v.pipe(v.array(PlaceholderTreeSchema), v.minLength(1), v.maxLength(16))),
+  /** the far proxy's look, and its grid or model parts when its land is not a height field */
+  far: v.optional(PlaceholderFarSchema),
+  /** the near placeholder's steer: `floors`, the fewest triangles a named prototype (a placed model's id, as the bake's
+   *  `--report` lists it) is simplified to, on top of the cell's content budget (a palm whose trunk the common ratio
+   *  removes keeps its silhouette); `world: 'tiles'`, its world is its shardfile's coarse tiles (a world built from its
+   *  product, with no authored host to visit); `owns`, its near view owns its cell over its own tiles (G630: tiles whose
+   *  looks are lit only inside their world, Nine Dragon's night city, never refine over it); `floor`, the flat floor such a
+   *  world stands on (its height in metres and its linear colour) when its streets are not in its tiles; `base`, a stack
+   *  under such a world raised off that floor (Nine Dragon's city at +125 m floated over it from a neighbour's road): a
+   *  column under every `cell`-metre square of its footprint from the floor up into its lowest content, its linear colour
+   *  going from `lip` at the top to `foot` at the floor */
+  near: v.optional(v.strictObject({
+    floors: v.optional(v.pipe(v.array(v.strictObject({
+      prototype: v.pipe(v.string(), v.regex(/^[A-Za-z0-9][A-Za-z0-9_./-]{0,63}$/u)),
+      triangles: v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(4096)),
+    })), v.minLength(1), v.maxLength(16))),
+    world: v.optional(v.literal('tiles')),
+    owns: v.optional(v.boolean()),
+    floor: v.optional(v.strictObject({
+      y: v.pipe(v.number(), v.minValue(-50), v.maxValue(50)),
+      colour: v.tuple([v.pipe(v.number(), v.minValue(0), v.maxValue(1)), v.pipe(v.number(), v.minValue(0), v.maxValue(1)), v.pipe(v.number(), v.minValue(0), v.maxValue(1))]),
+    })),
+    base: v.optional(v.strictObject({
+      cell: v.pipe(v.number(), v.minValue(2), v.maxValue(50)),
+      lip: v.tuple([v.pipe(v.number(), v.minValue(0), v.maxValue(1)), v.pipe(v.number(), v.minValue(0), v.maxValue(1)), v.pipe(v.number(), v.minValue(0), v.maxValue(1))]),
+      foot: v.tuple([v.pipe(v.number(), v.minValue(0), v.maxValue(1)), v.pipe(v.number(), v.minValue(0), v.maxValue(1)), v.pipe(v.number(), v.minValue(0), v.maxValue(1))]),
+    })),
+  })),
+});
+/** One admitted stand-in tree shape (`PlaceholderTreeSchema`): species, optional stem, crown rings and colour, unit high. */
+
+/** A shard's admitted placeholder steer (`PlaceholderSourceSchema`), as the near / far bake reads it. */
+
+
+/** Admit a shard's declared placeholder source; throws with the shard's name on a malformed row. */
+export function placeholderSource(slug: string, value: unknown): PlaceholderSource {
+  if (value === undefined) return {};
+  const result = v.safeParse(PlaceholderSourceSchema, value);
+  if (!result.success) throw new Error(`${slug}: invalid placeholder source: ${result.issues.map((issue) => issue.message).join('; ')}`);
+  return result.output;
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type PlaceholderTreeInput = PlaceholderTree;
+interface PlaceholderTreeFields {
+    species: string;
+    stem: ([
+        number,
+        number,
+        [
+            number,
+            number,
+            number
+        ]
+    ]) | null;
+    rings: ([
+        number,
+        number
+    ])[];
+    crown: [
+        number,
+        number,
+        number
+    ];
+}
+export type PlaceholderTree = { [Key in keyof PlaceholderTreeFields]: PlaceholderTreeFields[Key] };
+export type PlaceholderFarRowsInput = PlaceholderFarRows;
+interface PlaceholderFarRowsFields {
+    look: {
+        module: string;
+        export: string;
+    };
+    grid?: {
+        module: string;
+        export: string;
+    } | undefined;
+    parts?: {
+        module: string;
+        export: string;
+    } | undefined;
+}
+export type PlaceholderFarRows = { [Key in keyof PlaceholderFarRowsFields]: PlaceholderFarRowsFields[Key] };
+interface PlaceholderSourceInputFields {
+    ground?: {
+        generator: string;
+        export: string;
+    } | undefined;
+    trees?: (PlaceholderTreeInput)[] | undefined;
+    far?: PlaceholderFarRowsInput | undefined;
+    near?: {
+        floors?: ({
+            prototype: string;
+            triangles: number;
+        })[] | undefined;
+        world?: 'tiles' | undefined;
+        owns?: boolean | undefined;
+        floor?: {
+            y: number;
+            colour: [
+                number,
+                number,
+                number
+            ];
+        } | undefined;
+        base?: {
+            cell: number;
+            lip: [
+                number,
+                number,
+                number
+            ];
+            foot: [
+                number,
+                number,
+                number
+            ];
+        } | undefined;
+    } | undefined;
+}
+export type PlaceholderSourceInput = { [Key in keyof PlaceholderSourceInputFields]: PlaceholderSourceInputFields[Key] };
+interface PlaceholderSourceFields {
+    ground?: {
+        generator: string;
+        export: string;
+    } | undefined;
+    trees?: (PlaceholderTree)[] | undefined;
+    far?: PlaceholderFarRows | undefined;
+    near?: {
+        floors?: ({
+            prototype: string;
+            triangles: number;
+        })[] | undefined;
+        world?: 'tiles' | undefined;
+        owns?: boolean | undefined;
+        floor?: {
+            y: number;
+            colour: [
+                number,
+                number,
+                number
+            ];
+        } | undefined;
+        base?: {
+            cell: number;
+            lip: [
+                number,
+                number,
+                number
+            ];
+            foot: [
+                number,
+                number,
+                number
+            ];
+        } | undefined;
+    } | undefined;
+}
+export type PlaceholderSource = { [Key in keyof PlaceholderSourceFields]: PlaceholderSourceFields[Key] };

package/src/format/platformDataSections.ts

@@ -0,0 +1,146 @@
+import { CollectionDisplaysSchema, type CollectionDisplaysRows } from './collectionDisplay.ts';
+import { ResolvedIslandLibrarySchema, type ResolvedIslandLibraryRows } from './islandLibrary.ts';
+import { DeclaredBodyOpsSchema, type DeclaredBodyOpsRows } from './bodySlots.ts';
+import {StealthRowsSchema,type StealthRows} from './stealth.ts';
+import { PaintedLookSchema, type PaintedLookRow } from './paintedLook.ts';
+import { ColourFunctionBookSchema, type ColourFunctionBook } from './colourFunction.ts';
+import { RiggedHullBookSchema, type RiggedHullBook } from './riggedHulls.ts';
+import { HullLookBookSchema, type HullLookBookRows } from './speciesLooks.ts';
+import { ExplorerCatalogueSchema, type ExplorerCatalogue } from './explorerCatalogue.ts';
+import { ToonLookSchema, type ToonLookRow } from './toonLook.ts';
+import { KEYED_SKY, type KeyedSkyStyle } from './keyedSky.ts';
+import { ClientPlanSchema, type ClientPlan } from './clientPlan.ts';
+import { SpawnScriptsSchema, type SpawnScriptRows } from './spawnScripts.ts';
+import { WorldScenesSchema, type WorldScenesSection } from './worldScenes.ts';
+import { HeldArmsSchema, type HeldArmsRows } from './heldArms.ts';
+import { LoadoutSchema, type LoadoutRows } from './loadout.ts';
+import { HeldFinishesSchema, type HeldFinishesRows } from './heldFinishes.ts';
+import { HeldGearSchema, type HeldGearRows } from './heldGear.ts';
+import * as v from 'valibot';
+import { HeldEquipmentSchema, type HeldEquipmentRows } from './heldEquipment.ts';
+import { CompletionSchema, type CompletionRows } from './completion.ts';
+import { SpeciesProgramsSchema, type SpeciesPrograms } from './speciesPrograms.ts';
+import { CreatureStrikesSchema, type CreatureStrikes } from './creatures.ts';
+import { ActorMovesSchema, type ActorMoves } from './actorMoves.ts';
+import { DecisionScriptsSchema, type DecisionScripts } from './decisionScripts.ts';
+import { UiStringsSchema, type UiStrings } from './uiStrings.ts';
+import { WorldPhysicsSchema, type WorldPhysics } from './worldPhysics.ts';
+import { WorldTargetsSchema, type WorldTargets } from './worldTargets.ts';
+import { WorldMoversSchema } from './movers.ts';
+import { ReturnModulesSchema, type ReturnModuleRow, ViewModulesSchema, type ViewModuleRow } from './scriptContract.ts';
+import { NativeRuntimePlanSchema, type NativeRuntimePlanData } from './nativeRuntimePlan.ts';
+import { TreeSetSchema, type TreeSetRows } from './treeSetRows.ts';
+
+/** New plain-value sections supplement the unchanged v1 model assembled from the older section envelopes. */
+export interface PlatformDataSections {
+  'collections/displays': CollectionDisplaysRows;
+  'models/island-library': ResolvedIslandLibraryRows;
+  'player/stealth':StealthRows;
+  'explore/catalogue': ExplorerCatalogue;
+  'look/rigged-hulls': RiggedHullBook;
+  'look/hull-book': HullLookBookRows;
+  'look/toon': ToonLookRow;
+  'look/painted': PaintedLookRow;
+  'look/colour-functions': ColourFunctionBook;
+  'look/keyed-sky': KeyedSkyStyle;
+  'client/plan': ClientPlan;
+  'view/modules': ViewModuleRow[];
+  'held/arms': HeldArmsRows;
+  'held/gear': HeldGearRows;
+  'held/finishes': HeldFinishesRows;
+  'held/loadout': LoadoutRows;
+  'held/equipment': HeldEquipmentRows;
+  'ui/completion': CompletionRows;
+  'sim/runtime-plan': NativeRuntimePlanData;
+  'actors/species-programs': SpeciesPrograms;
+  'actors/moves': ActorMoves;
+  'actors/spawn-scripts': SpawnScriptRows[];
+  'actors/return-scripts': ReturnModuleRow[];
+  'actors/strikes': CreatureStrikes;
+  'sim/scripts': DecisionScripts;
+  'sim/bodies': DeclaredBodyOpsRows;
+  'ui/strings': UiStrings;
+  'world/physics': WorldPhysics;
+  'world/targets': WorldTargets;
+  'world/scenes': WorldScenesSection;
+  'world/trees': TreeSetRows;
+}
+
+/** Defining parsers for the first independently authored platform sections. */
+export const PLATFORM_DATA_SECTIONS: Readonly<{ [Name in keyof PlatformDataSections]: { readonly schema: v.GenericSchema<unknown, PlatformDataSections[Name]> } }> = {
+  'collections/displays': { schema: CollectionDisplaysSchema },
+  'models/island-library': { schema: ResolvedIslandLibrarySchema },
+  'player/stealth':{schema:StealthRowsSchema},
+  'explore/catalogue': { schema: ExplorerCatalogueSchema },
+  'look/rigged-hulls': { schema: RiggedHullBookSchema },
+  'look/hull-book': { schema: HullLookBookSchema },
+  'look/toon': { schema: ToonLookSchema },
+  'look/painted': { schema: PaintedLookSchema },
+  'look/colour-functions': { schema: ColourFunctionBookSchema },
+  'look/keyed-sky': { schema: KEYED_SKY },
+  'client/plan': { schema: ClientPlanSchema },
+  'view/modules': { schema: ViewModulesSchema },
+  'held/arms': { schema: HeldArmsSchema },
+  'held/gear': { schema: HeldGearSchema },
+  'held/finishes': { schema: HeldFinishesSchema },
+  'held/loadout': { schema: LoadoutSchema },
+  'held/equipment': { schema: HeldEquipmentSchema },
+  'ui/completion': { schema: CompletionSchema },
+  'sim/runtime-plan': { schema: NativeRuntimePlanSchema },
+  'actors/species-programs': { schema: SpeciesProgramsSchema },
+  'actors/moves': { schema: ActorMovesSchema },
+  'actors/spawn-scripts': { schema: SpawnScriptsSchema },
+  'actors/return-scripts': { schema: ReturnModulesSchema },
+  'actors/strikes': { schema: CreatureStrikesSchema },
+  'sim/scripts': { schema: DecisionScriptsSchema },
+  'sim/bodies': { schema: DeclaredBodyOpsSchema },
+  'ui/strings': { schema: UiStringsSchema },
+  'world/physics': { schema: WorldPhysicsSchema },
+  'world/targets': { schema: WorldTargetsSchema },
+  'world/scenes': { schema: WorldScenesSchema },
+  'world/trees': { schema: TreeSetSchema },
+} as const;
+
+/** Client feature inputs that remain legacy root envelopes. These defining
+ * schemas do not become independent platform sections or leave root assembly. */
+export const CLIENT_ENVELOPE_SECTIONS: { readonly 'world/movers': { readonly schema: typeof WorldMoversSchema } } = { 'world/movers': { schema: WorldMoversSchema } } as const;
+
+/** An explicitly declared new platform-section name; no shard-private name is inferred. */
+export type PlatformDataSectionName = keyof PlatformDataSections;
+
+/** Parse the named section without treating its plain payload as fields of the v1 Shardfile. */
+export function parsePlatformDataSection(name: 'collections/displays', value: unknown): CollectionDisplaysRows;
+export function parsePlatformDataSection(name: 'models/island-library', value: unknown): ResolvedIslandLibraryRows;
+export function parsePlatformDataSection(name:'player/stealth',value:unknown):StealthRows;
+export function parsePlatformDataSection(name: 'explore/catalogue', value: unknown): ExplorerCatalogue;
+export function parsePlatformDataSection(name: 'look/rigged-hulls', value: unknown): RiggedHullBook;
+export function parsePlatformDataSection(name: 'look/hull-book', value: unknown): HullLookBookRows;
+export function parsePlatformDataSection(name: 'look/toon', value: unknown): ToonLookRow;
+export function parsePlatformDataSection(name: 'look/painted', value: unknown): PaintedLookRow;
+export function parsePlatformDataSection(name: 'look/colour-functions', value: unknown): ColourFunctionBook;
+export function parsePlatformDataSection(name: 'look/keyed-sky', value: unknown): KeyedSkyStyle;
+export function parsePlatformDataSection(name: 'client/plan', value: unknown): ClientPlan;
+export function parsePlatformDataSection(name: 'view/modules', value: unknown): ViewModuleRow[];
+export function parsePlatformDataSection(name: 'held/arms', value: unknown): HeldArmsRows;
+export function parsePlatformDataSection(name: 'held/loadout', value: unknown): LoadoutRows;
+export function parsePlatformDataSection(name: 'held/finishes', value: unknown): HeldFinishesRows;
+export function parsePlatformDataSection(name: 'held/gear', value: unknown): HeldGearRows;
+export function parsePlatformDataSection(name: 'held/equipment', value: unknown): HeldEquipmentRows;
+export function parsePlatformDataSection(name: 'actors/species-programs', value: unknown): SpeciesPrograms;
+export function parsePlatformDataSection(name: 'actors/moves', value: unknown): ActorMoves;
+export function parsePlatformDataSection(name: 'actors/strikes', value: unknown): CreatureStrikes;
+export function parsePlatformDataSection(name: 'actors/spawn-scripts', value: unknown): SpawnScriptRows[];
+export function parsePlatformDataSection(name: 'actors/return-scripts', value: unknown): ReturnModuleRow[];
+export function parsePlatformDataSection(name: 'sim/scripts', value: unknown): DecisionScripts;
+export function parsePlatformDataSection(name: 'sim/bodies', value: unknown): DeclaredBodyOpsRows;
+export function parsePlatformDataSection(name: 'ui/completion', value: unknown): CompletionRows;
+export function parsePlatformDataSection(name: 'ui/strings', value: unknown): UiStrings;
+export function parsePlatformDataSection(name: 'world/physics', value: unknown): WorldPhysics;
+export function parsePlatformDataSection(name: 'world/scenes', value: unknown): WorldScenesSection;
+export function parsePlatformDataSection(name: 'world/trees', value: unknown): TreeSetRows;
+export function parsePlatformDataSection(name: 'world/targets', value: unknown): WorldTargets;
+export function parsePlatformDataSection(name: 'sim/runtime-plan', value: unknown): NativeRuntimePlanData;
+export function parsePlatformDataSection(name: PlatformDataSectionName, value: unknown): PlatformDataSections[PlatformDataSectionName];
+export function parsePlatformDataSection(name: PlatformDataSectionName, value: unknown): PlatformDataSections[PlatformDataSectionName] {
+  return v.parse(PLATFORM_DATA_SECTIONS[name].schema, value);
+}