@wildshard/shard-format 0.0.1 → 0.4.5

package/src/format/shardSections.ts

@@ -0,0 +1,383 @@
+/** Defining root wire sections shared by the authoring SDK and game admission.
+ * Native reference/asset/entry/allocator checks stay in game; look and material contracts await DS1.4. */
+import * as v from 'valibot';
+import { WIRE_CELL, WIRE_TILE_SIZES } from './wireLimits.ts';
+import { SHARDFILE_ADMISSION_LIMITS as limits } from './admissionLimits.ts';
+import { SHARDFILE_VERSION } from './version.ts';
+import { RuntimeCostSchema } from './runtimeCost.ts';
+import { CommonsCostsSchema } from './commonsCosts.ts';
+import { ScriptBindingsSchema } from './scripts.ts';
+
+const CHUNK_HALF = WIRE_CELL.half, CELL_BELOW = WIRE_CELL.below, CELL_ABOVE = WIRE_CELL.above;
+/** Nonnegative safe wire integer. */
+export const ShardNaturalSchema: v.GenericSchema<ShardNaturalInput, ShardNatural> = v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(Number.MAX_SAFE_INTEGER));
+const positive = v.pipe(ShardNaturalSchema, v.minValue(1));
+/** Finite wire number without an imposed gameplay range. */
+export const ShardFiniteSchema: v.GenericSchema<ShardFiniteInput, ShardFinite> = v.pipe(v.number(), v.finite());
+const name = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u), v.maxLength(limits.idCharacters));
+/** Local SHA256 content identity. */
+export const ShardHashSchema: v.GenericSchema<ShardHashInput, ShardHash> = v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/u));
+/** Local or commons-qualified SHA256 content reference. */
+export const ShardReferenceSchema: v.GenericSchema<ShardReferenceInput, ShardReference> = v.pipe(v.string(), v.regex(/^(?:commons:)?[a-f0-9]{64}$/u));
+/** Bounded ordered references to local or commons content. */
+export const ShardReferencesSchema: v.GenericSchema<ShardReferencesInput, ShardReferences> = v.pipe(v.array(ShardReferenceSchema), v.maxLength(limits.files + limits.commons));
+/** Bounded ordered names in a root declaration. */
+export const ShardNamesSchema: v.GenericSchema<ShardNamesInput, ShardNames> = v.pipe(v.array(name), v.maxLength(limits.files));
+const vec3 = v.tuple([ShardFiniteSchema, ShardFiniteSchema, ShardFiniteSchema]);
+/** Ordered local bounds inside the fixed shard cell. */
+export const CellBoundsSchema: v.GenericSchema<CellBoundsInput, CellBounds> = v.pipe(v.strictObject({ min: vec3, max: vec3 }), v.check((b) => b.min.every((n, i) => n <= (b.max[i] ?? -Infinity)), 'ordered bounds'), v.check((b) => b.min[0] >= -CHUNK_HALF && b.max[0] <= CHUNK_HALF && b.min[2] >= -CHUNK_HALF && b.max[2] <= CHUNK_HALF && b.min[1] >= -CELL_BELOW && b.max[1] <= CELL_ABOVE, 'cell bounds'));
+const drawBounds = CellBoundsSchema;
+const costs = { compressed: ShardNaturalSchema, decoded: ShardNaturalSchema, gpu: ShardNaturalSchema, triangles: ShardNaturalSchema, draws: ShardNaturalSchema };
+const tile: v.GenericSchema<ShardTileRowsInput, ShardTileRows> = v.strictObject({ lod: v.picklist([0, 1]), x: ShardNaturalSchema, z: ShardNaturalSchema, bounds: CellBoundsSchema, drawBounds: v.exactOptional(drawBounds), geometricError: v.pipe(ShardFiniteSchema, v.minValue(0)), files: ShardReferencesSchema, ...costs });
+const file: v.StrictObjectSchema<{ readonly hash: v.GenericSchema<ShardFileRowsInput['hash'], ShardFileRows['hash']>; readonly kind: v.GenericSchema<ShardFileRowsInput['kind'], ShardFileRows['kind']>; readonly compressed: v.GenericSchema<ShardFileRowsInput['compressed'], ShardFileRows['compressed']>; readonly decoded: v.GenericSchema<ShardFileRowsInput['decoded'], ShardFileRows['decoded']>; readonly gpu: v.GenericSchema<ShardFileRowsInput['gpu'], ShardFileRows['gpu']>; readonly triangles: v.GenericSchema<ShardFileRowsInput['triangles'], ShardFileRows['triangles']>; readonly draws: v.GenericSchema<ShardFileRowsInput['draws'], ShardFileRows['draws']>; readonly dependencies: v.GenericSchema<ShardFileRowsInput['dependencies'], ShardFileRows['dependencies']>; readonly critical: v.GenericSchema<ShardFileRowsInput['critical'], ShardFileRows['critical']>; }, undefined> = v.strictObject({ hash: ShardHashSchema, kind: v.picklist(['glb', 'ktx2', 'audio', 'json', 'wasm', 'binary', 'image']), ...costs, dependencies: ShardReferencesSchema, critical: v.boolean() });
+const tileCount = (2 * CHUNK_HALF / WIRE_TILE_SIZES.l0) ** 2 + (2 * CHUNK_HALF / WIRE_TILE_SIZES.l1) ** 2;
+
+/** Stable authored shard identity and deterministic seed. */
+export const IdentitySchema: v.GenericSchema<ShardIdentityInput, ShardIdentity> = v.strictObject({ slug: name, name: v.pipe(v.string(), v.minLength(1), v.maxLength(limits.idCharacters)), author: v.pipe(v.string(), v.minLength(1), v.maxLength(limits.idCharacters)), revision: positive, seed: ShardNaturalSchema });
+/** Wire revision, capabilities and exact commons declarations. */
+export const RequiresSchema: v.GenericSchema<ShardRequiresInput, ShardRequires> = v.strictObject({ sdk: v.literal(SHARDFILE_VERSION), capabilities: ShardNamesSchema, commons: v.pipe(v.array(ShardHashSchema), v.maxLength(limits.commons)), commonsWire: v.optional(v.record(ShardHashSchema, ShardNaturalSchema), {}), commonsCosts: v.optional(CommonsCostsSchema, {}) });
+/** Authored compressed and resident ceilings. */
+export const BudgetsSchema: v.GenericSchema<ShardBudgetsInput, ShardBudgets> = v.strictObject({
+  /** Reviewed whole-client floor retained when an opaque runtime becomes declared data. */
+  client: v.exactOptional(RuntimeCostSchema), library: v.strictObject({ resident: ShardNaturalSchema, compressed: ShardNaturalSchema, downloadAllowance: v.exactOptional(ShardNaturalSchema) }), sim: v.strictObject({ resident: ShardNaturalSchema, compressed: ShardNaturalSchema }), overlap: ShardNaturalSchema });
+/** Fixed-step simulation and admitted script binding declarations. */
+export const SimSchema: v.GenericSchema<ShardSimInput, ShardSim> = v.strictObject({ fixedHz: v.literal(60), scriptTickDivisor: v.pipe(positive, v.check((n) => 60 % n === 0, 'script divisor divides 60')), commandVersion: v.literal(0), snapshotVersion: v.literal(0), scripts: ShardReferencesSchema, bindings: v.optional(ScriptBindingsSchema, []) });
+/** Bounded player count and authored movement speed. */
+export const AuthorCapsSchema: v.GenericSchema<ShardAuthorCapsInput, ShardAuthorCaps> = v.strictObject({ players: v.pipe(positive, v.maxValue(32)), speed: v.pipe(ShardFiniteSchema, v.minValue(0), v.maxValue(15)) });
+/** Bounded authoritative simulation resource declarations. */
+export const ServerBudgetSchema: v.GenericSchema<ShardServerBudgetInput, ShardServerBudget> = v.strictObject({ tickMicros: v.pipe(positive, v.maxValue(16_666)), memory: positive, entities: v.pipe(ShardNaturalSchema, v.maxValue(10_000)), commandsPerTick: v.pipe(ShardNaturalSchema, v.maxValue(1024)) });
+/** Content-addressed file inventory and conservative costs. */
+export const FilesSchema: v.GenericSchema<ShardFilesInput, ShardFiles> & { readonly pipe: readonly [v.ArraySchema<typeof file, undefined>, unknown] } = v.pipe(v.array(file), v.maxLength(limits.files));
+/** Finite L0/L1 tile inventory. */
+export const TilesSchema: v.GenericSchema<ShardTilesInput, ShardTiles> = v.pipe(v.array(tile), v.maxLength(tileCount));
+/** Ordered admitted library roots. */
+export const LibrarySchema: typeof ShardReferencesSchema = ShardReferencesSchema;
+/** Ordered admitted critical roots. */
+export const CriticalSchema: typeof ShardReferencesSchema = ShardReferencesSchema;
+/**
+ * G539: the far tier's camera-facing impostor, baked with the proxy (`@wildshard/sdk/bake/farImpostor`): `views` renders
+ * round the cell (view k seen from compass azimuth k × 360° / views), `cols` × rows tiles of `tile` pixels in one image
+ * file, each tile `width` metres wide about the cell centre and spanning `bottom` … `top` metres; texels hold the lit
+ * colour sRGB-encoded over `range` (linear = decoded × range) and a 1-bit coverage alpha. Its costs are in the far row's.
+ */
+export const FarImpostorSchema: v.GenericSchema<FarImpostorInput, FarImpostor> = v.strictObject({
+  file: ShardReferenceSchema, views: v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(16)), cols: v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(16)),
+  tile: v.tuple([v.pipe(v.number(), v.integer(), v.minValue(8), v.maxValue(1024)), v.pipe(v.number(), v.integer(), v.minValue(8), v.maxValue(1024))]),
+  width: v.pipe(ShardFiniteSchema, v.minValue(1), v.maxValue(4 * CHUNK_HALF)), bottom: v.pipe(ShardFiniteSchema, v.minValue(-CELL_BELOW)), top: v.pipe(ShardFiniteSchema, v.maxValue(CELL_ABOVE)),
+  range: v.pipe(ShardFiniteSchema, v.minValue(0.01), v.maxValue(16)),
+});
+/** One far impostor row. */
+
+/** Nullable far proxy references, bounds and conservative costs (its impostor's file is one of `files`). */
+export const FarSchema: v.GenericSchema<ShardFarInput, ShardFar> = v.nullable(v.pipe(v.strictObject({ files: ShardReferencesSchema, bounds: CellBoundsSchema, impostor: v.exactOptional(FarImpostorSchema), ...costs }),
+  v.check((far) => far.impostor === undefined || (far.files.includes(far.impostor.file) && far.impostor.bottom < far.impostor.top), 'far impostor file and span')));
+/** Finite local player position and yaw; its default remains in root composition. */
+export const SpawnSchema: v.GenericSchema<ShardSpawnInput, ShardSpawn> = v.strictObject({ x: ShardFiniteSchema, y: ShardFiniteSchema, z: ShardFiniteSchema, yaw: ShardFiniteSchema });
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type ShardNaturalInput = ShardNatural;
+export type ShardNatural = number;
+export type ShardFiniteInput = ShardFinite;
+export type ShardFinite = number;
+export type ShardHashInput = ShardHash;
+export type ShardHash = string;
+export type ShardReferenceInput = ShardReference;
+export type ShardReference = string;
+export type ShardReferencesInput = (ShardReferenceInput)[];
+export type ShardReferences = (ShardReference)[];
+export type ShardNamesInput = ShardNames;
+export type ShardNames = (string)[];
+interface CellBoundsInputFields {
+    min: [
+        ShardFiniteInput,
+        ShardFiniteInput,
+        ShardFiniteInput
+    ];
+    max: [
+        ShardFiniteInput,
+        ShardFiniteInput,
+        ShardFiniteInput
+    ];
+}
+export type CellBoundsInput = { [Key in keyof CellBoundsInputFields]: CellBoundsInputFields[Key] };
+interface CellBoundsFields {
+    min: [
+        ShardFinite,
+        ShardFinite,
+        ShardFinite
+    ];
+    max: [
+        ShardFinite,
+        ShardFinite,
+        ShardFinite
+    ];
+}
+export type CellBounds = { [Key in keyof CellBoundsFields]: CellBoundsFields[Key] };
+export type ShardTileRowsInput = Omit<{
+    lod: 0 | 1;
+    x: ShardNaturalInput;
+    z: ShardNaturalInput;
+    bounds: CellBoundsInput;
+    drawBounds?: CellBoundsInput;
+    geometricError: ShardFiniteInput;
+    files: ShardReferencesInput;
+}, keyof ({
+    compressed: ShardNaturalInput;
+    decoded: ShardNaturalInput;
+    gpu: ShardNaturalInput;
+    triangles: ShardNaturalInput;
+    draws: ShardNaturalInput;
+})> & {
+    compressed: ShardNaturalInput;
+    decoded: ShardNaturalInput;
+    gpu: ShardNaturalInput;
+    triangles: ShardNaturalInput;
+    draws: ShardNaturalInput;
+};
+export type ShardTileRows = Omit<{
+    lod: 0 | 1;
+    x: ShardNatural;
+    z: ShardNatural;
+    bounds: CellBounds;
+    drawBounds?: CellBounds;
+    geometricError: ShardFinite;
+    files: ShardReferences;
+}, keyof ({
+    compressed: ShardNatural;
+    decoded: ShardNatural;
+    gpu: ShardNatural;
+    triangles: ShardNatural;
+    draws: ShardNatural;
+})> & {
+    compressed: ShardNatural;
+    decoded: ShardNatural;
+    gpu: ShardNatural;
+    triangles: ShardNatural;
+    draws: ShardNatural;
+};
+export type ShardFileRowsInput = Omit<Omit<{
+    hash: ShardHashInput;
+    kind: 'glb' | 'ktx2' | 'audio' | 'json' | 'wasm' | 'binary' | 'image';
+}, keyof ({
+    compressed: ShardNaturalInput;
+    decoded: ShardNaturalInput;
+    gpu: ShardNaturalInput;
+    triangles: ShardNaturalInput;
+    draws: ShardNaturalInput;
+})> & {
+    compressed: ShardNaturalInput;
+    decoded: ShardNaturalInput;
+    gpu: ShardNaturalInput;
+    triangles: ShardNaturalInput;
+    draws: ShardNaturalInput;
+}, keyof ({
+    dependencies: ShardReferencesInput;
+    critical: boolean;
+})> & {
+    dependencies: ShardReferencesInput;
+    critical: boolean;
+};
+export type ShardFileRows = Omit<Omit<{
+    hash: ShardHash;
+    kind: 'glb' | 'ktx2' | 'audio' | 'json' | 'wasm' | 'binary' | 'image';
+}, keyof ({
+    compressed: ShardNatural;
+    decoded: ShardNatural;
+    gpu: ShardNatural;
+    triangles: ShardNatural;
+    draws: ShardNatural;
+})> & {
+    compressed: ShardNatural;
+    decoded: ShardNatural;
+    gpu: ShardNatural;
+    triangles: ShardNatural;
+    draws: ShardNatural;
+}, keyof ({
+    dependencies: ShardReferences;
+    critical: boolean;
+})> & {
+    dependencies: ShardReferences;
+    critical: boolean;
+};
+interface ShardIdentityInputFields {
+    slug: string;
+    name: string;
+    author: string;
+    revision: ShardNaturalInput;
+    seed: ShardNaturalInput;
+}
+export type ShardIdentityInput = { [Key in keyof ShardIdentityInputFields]: ShardIdentityInputFields[Key] };
+interface ShardIdentityFields {
+    slug: string;
+    name: string;
+    author: string;
+    revision: ShardNatural;
+    seed: ShardNatural;
+}
+export type ShardIdentity = { [Key in keyof ShardIdentityFields]: ShardIdentityFields[Key] };
+interface ShardRequiresInputFields {
+    sdk: (typeof SHARDFILE_VERSION);
+    capabilities: ShardNamesInput;
+    commons: (ShardHashInput)[];
+    commonsWire?: Record<string, ShardNaturalInput> | undefined;
+    commonsCosts?: v.InferInput<typeof CommonsCostsSchema> | undefined;
+}
+export type ShardRequiresInput = { [Key in keyof ShardRequiresInputFields]: ShardRequiresInputFields[Key] };
+interface ShardRequiresFields {
+    sdk: (typeof SHARDFILE_VERSION);
+    capabilities: ShardNames;
+    commons: (ShardHash)[];
+    commonsWire: Record<string, ShardNatural>;
+    commonsCosts: v.InferOutput<typeof CommonsCostsSchema>;
+}
+export type ShardRequires = { [Key in keyof ShardRequiresFields]: ShardRequiresFields[Key] };
+interface ShardBudgetsInputFields {
+    client?: v.InferInput<typeof RuntimeCostSchema>;
+    library: {
+        resident: ShardNaturalInput;
+        compressed: ShardNaturalInput;
+        downloadAllowance?: ShardNaturalInput;
+    };
+    sim: {
+        resident: ShardNaturalInput;
+        compressed: ShardNaturalInput;
+    };
+    overlap: ShardNaturalInput;
+}
+export type ShardBudgetsInput = { [Key in keyof ShardBudgetsInputFields]: ShardBudgetsInputFields[Key] };
+interface ShardBudgetsFields {
+    client?: v.InferOutput<typeof RuntimeCostSchema>;
+    library: {
+        resident: ShardNatural;
+        compressed: ShardNatural;
+        downloadAllowance?: ShardNatural;
+    };
+    sim: {
+        resident: ShardNatural;
+        compressed: ShardNatural;
+    };
+    overlap: ShardNatural;
+}
+export type ShardBudgets = { [Key in keyof ShardBudgetsFields]: ShardBudgetsFields[Key] };
+interface ShardSimInputFields {
+    fixedHz: 60;
+    scriptTickDivisor: ShardNaturalInput;
+    commandVersion: 0;
+    snapshotVersion: 0;
+    scripts: ShardReferencesInput;
+    bindings?: v.InferInput<typeof ScriptBindingsSchema> | undefined;
+}
+export type ShardSimInput = { [Key in keyof ShardSimInputFields]: ShardSimInputFields[Key] };
+interface ShardSimFields {
+    fixedHz: 60;
+    scriptTickDivisor: ShardNatural;
+    commandVersion: 0;
+    snapshotVersion: 0;
+    scripts: ShardReferences;
+    bindings: v.InferOutput<typeof ScriptBindingsSchema>;
+}
+export type ShardSim = { [Key in keyof ShardSimFields]: ShardSimFields[Key] };
+interface ShardAuthorCapsInputFields {
+    players: ShardNaturalInput;
+    speed: ShardFiniteInput;
+}
+export type ShardAuthorCapsInput = { [Key in keyof ShardAuthorCapsInputFields]: ShardAuthorCapsInputFields[Key] };
+interface ShardAuthorCapsFields {
+    players: ShardNatural;
+    speed: ShardFinite;
+}
+export type ShardAuthorCaps = { [Key in keyof ShardAuthorCapsFields]: ShardAuthorCapsFields[Key] };
+interface ShardServerBudgetInputFields {
+    tickMicros: ShardNaturalInput;
+    memory: ShardNaturalInput;
+    entities: ShardNaturalInput;
+    commandsPerTick: ShardNaturalInput;
+}
+export type ShardServerBudgetInput = { [Key in keyof ShardServerBudgetInputFields]: ShardServerBudgetInputFields[Key] };
+interface ShardServerBudgetFields {
+    tickMicros: ShardNatural;
+    memory: ShardNatural;
+    entities: ShardNatural;
+    commandsPerTick: ShardNatural;
+}
+export type ShardServerBudget = { [Key in keyof ShardServerBudgetFields]: ShardServerBudgetFields[Key] };
+export type ShardFilesInput = (ShardFileRowsInput)[];
+export type ShardFiles = (ShardFileRows)[];
+export type ShardTilesInput = (ShardTileRowsInput)[];
+export type ShardTiles = (ShardTileRows)[];
+interface FarImpostorInputFields {
+    file: ShardReferenceInput;
+    views: number;
+    cols: number;
+    tile: [
+        number,
+        number
+    ];
+    width: ShardFiniteInput;
+    bottom: ShardFiniteInput;
+    top: ShardFiniteInput;
+    range: ShardFiniteInput;
+}
+export type FarImpostorInput = { [Key in keyof FarImpostorInputFields]: FarImpostorInputFields[Key] };
+interface FarImpostorFields {
+    file: ShardReference;
+    views: number;
+    cols: number;
+    tile: [
+        number,
+        number
+    ];
+    width: ShardFinite;
+    bottom: ShardFinite;
+    top: ShardFinite;
+    range: ShardFinite;
+}
+export type FarImpostor = { [Key in keyof FarImpostorFields]: FarImpostorFields[Key] };
+export type ShardFarInput = (Omit<{
+    files: ShardReferencesInput;
+    bounds: CellBoundsInput;
+    impostor?: FarImpostorInput;
+}, keyof ({
+    compressed: ShardNaturalInput;
+    decoded: ShardNaturalInput;
+    gpu: ShardNaturalInput;
+    triangles: ShardNaturalInput;
+    draws: ShardNaturalInput;
+})> & {
+    compressed: ShardNaturalInput;
+    decoded: ShardNaturalInput;
+    gpu: ShardNaturalInput;
+    triangles: ShardNaturalInput;
+    draws: ShardNaturalInput;
+}) | null;
+export type ShardFar = (Omit<{
+    files: ShardReferences;
+    bounds: CellBounds;
+    impostor?: FarImpostor;
+}, keyof ({
+    compressed: ShardNatural;
+    decoded: ShardNatural;
+    gpu: ShardNatural;
+    triangles: ShardNatural;
+    draws: ShardNatural;
+})> & {
+    compressed: ShardNatural;
+    decoded: ShardNatural;
+    gpu: ShardNatural;
+    triangles: ShardNatural;
+    draws: ShardNatural;
+}) | null;
+interface ShardSpawnInputFields {
+    x: ShardFiniteInput;
+    y: ShardFiniteInput;
+    z: ShardFiniteInput;
+    yaw: ShardFiniteInput;
+}
+export type ShardSpawnInput = { [Key in keyof ShardSpawnInputFields]: ShardSpawnInputFields[Key] };
+interface ShardSpawnFields {
+    x: ShardFinite;
+    y: ShardFinite;
+    z: ShardFinite;
+    yaw: ShardFinite;
+}
+export type ShardSpawn = { [Key in keyof ShardSpawnFields]: ShardSpawnFields[Key] };

package/src/format/sketch.ts

@@ -0,0 +1,79 @@
+import { SHARDFILE_ADMISSION_LIMITS as L } from './admissionLimits.ts';
+
+const prefix = 'data:image/svg+xml,';
+const hash = /^(?:commons:)?[0-9a-f]{64}$/u;
+const tags = new Set(['svg', 'g', 'path', 'rect', 'circle', 'ellipse', 'line', 'polyline', 'polygon']);
+const lengths = new Set(['x', 'y', 'width', 'height', 'rx', 'ry', 'cx', 'cy', 'r', 'x1', 'x2', 'y1', 'y2', 'stroke-width']);
+const colours = new Set(['fill', 'stroke']);
+const units = new Set(['opacity', 'fill-opacity', 'stroke-opacity']);
+const number = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/iu;
+const numbers = (value: string): number[] => {
+  const tokens = value.trim().split(/[\s,]+/u);
+  if (tokens.length === 0 || tokens.some(token => !number.test(token))) throw new Error('Invalid sketch numbers');
+  const result = tokens.map(Number);
+  if (result.some(n => !Number.isFinite(n) || Math.abs(n) > 1_000_000)) throw new Error('Sketch coordinate limit');
+  return result;
+};
+
+/** An inert vector sketch and its one bounded CPU/GPU raster expansion, separate from admitted wire-file costs. */
+export interface CompendiumSketch { data: string; width: number; height: number; decoded: number; gpu: number }
+
+/** Parse a small shape-only SVG without DOM allocation, entities, active tags, styles or external resource attributes. */
+export function parseSketchSvg(xml: string): CompendiumSketch {
+  if (new TextEncoder().encode(xml).length > L.textCharacters || /[&]/u.test(xml)) throw new Error('Sketch SVG size or entities');
+  const stack: string[] = []; let cursor = 0, count = 0, width = 0, height = 0, root = false;
+  for (const match of xml.matchAll(/<([^<>]+)>/gu)) {
+    if (xml.slice(cursor, match.index).trim() !== '') throw new Error('Sketch SVG must contain only inert shapes');
+    cursor = match.index + match[0].length;
+    const token = match[1]; if (token === undefined || ++count > 256) throw new Error('Sketch SVG shape limit');
+    if (token.startsWith('/')) { if (stack.pop() !== token.slice(1).trim()) throw new Error('Sketch SVG closing tag'); continue; }
+    const header = /^([a-z]+)(?=\s|\/|$)/u.exec(token), tag = header?.[1];
+    if (tag === undefined || !tags.has(tag) || (tag === 'svg' ? root || stack.length > 0 : stack.length === 0)) throw new Error('Sketch SVG tag refused');
+    if (tag === 'svg') root = true;
+    const selfClosing = token.endsWith('/'), body = token.slice(tag.length, selfClosing ? -1 : undefined), attrs = new Map<string, string>();
+    let at = 0;
+    for (const attr of body.matchAll(/([a-zA-Z-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/gu)) {
+      if (body.slice(at, attr.index).trim() !== '') throw new Error('Sketch SVG attribute syntax');
+      at = attr.index + attr[0].length;
+      const key = attr[1], value = attr[2] ?? attr[3];
+      if (key === undefined || value === undefined || attrs.has(key) || attrs.size >= 24) throw new Error('Sketch SVG attributes');
+      attrs.set(key, value);
+      if (lengths.has(key)) { if (numbers(value).length !== 1) throw new Error('Sketch SVG length'); }
+      else if (colours.has(key)) { if (!/^(?:#[0-9a-f]{3,8}|[a-z]{1,32})$/iu.test(value)) throw new Error('Sketch SVG paint refused'); }
+      else if (units.has(key)) { const n = numbers(value); if (n.length !== 1 || n.some(x => x < 0 || x > 1)) throw new Error('Sketch SVG opacity'); }
+      else if (key === 'xmlns') { if (tag !== 'svg' || value !== 'http://www.w3.org/2000/svg') throw new Error('Sketch SVG namespace'); }
+      else if (key === 'viewBox') { const n = numbers(value); if (tag !== 'svg' || n.length !== 4 || (n[2] ?? 0) <= 0 || (n[3] ?? 0) <= 0) throw new Error('Sketch SVG viewBox'); }
+      else if (key === 'd') {
+        if (tag !== 'path' || !/^[MmZzLlHhVvCcSsQqTtAaEe0-9+.,\s-]+$/u.test(value)) throw new Error('Sketch SVG path');
+        for (const coordinate of value.matchAll(/[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?/giu)) numbers(coordinate[0]);
+      }
+      else if (key === 'points') { if (tag !== 'polygon' && tag !== 'polyline') throw new Error('Sketch SVG points'); numbers(value); }
+      else if (key === 'transform') {
+        let end = 0;
+        for (const transform of value.matchAll(/(?:matrix|translate|scale|rotate|skewX|skewY)\(([^()]*)\)/gu)) {
+          if (value.slice(end, transform.index).trim() !== '') throw new Error('Sketch SVG transform');
+          numbers(transform[1] ?? ''); end = transform.index + transform[0].length;
+        }
+        if (end === 0 || value.slice(end).trim() !== '') throw new Error('Sketch SVG transform');
+      } else if (key === 'fill-rule') { if (!['nonzero', 'evenodd'].includes(value)) throw new Error('Sketch SVG fill rule'); }
+      else throw new Error('Sketch SVG resource or active attribute refused');
+    }
+    if (body.slice(at).trim() !== '') throw new Error('Sketch SVG attribute syntax');
+    if (tag === 'svg') {
+      width = Number(attrs.get('width')); height = Number(attrs.get('height'));
+      if (attrs.get('xmlns') !== 'http://www.w3.org/2000/svg' || ![width, height].every(n => Number.isInteger(n) && n >= 1 && n <= 1024)) throw new Error('Sketch SVG raster dimensions');
+    }
+    if (!selfClosing) stack.push(tag);
+    if (stack.length > 32) throw new Error('Sketch SVG nesting limit');
+  }
+  if (!root || stack.length > 0 || xml.slice(cursor).trim() !== '') throw new Error('Incomplete sketch SVG');
+  return { data: prefix + encodeURIComponent(xml), width, height, decoded: width * height * 4, gpu: width * height * 4 };
+}
+
+/** Author references are bounded inline SVG data or immutable hashes; arbitrary URLs never reach the journal. */
+export function sketchReference(value: string): boolean {
+  if (value.length > L.textCharacters) return false;
+  if (hash.test(value)) return true;
+  if (!value.startsWith(prefix)) return false;
+  try { parseSketchSvg(decodeURIComponent(value.slice(prefix.length))); return true; } catch { return false; }
+}

package/src/format/skin-materials.ts

@@ -0,0 +1,172 @@
+/**
+ * Named skin materials (TE-ENG10, meta TEMPLATE-E2E-PLAN): a skin's binding (the `{ row, binding }` skin file a
+ * `platform.skin` look names) may map a material name in its GLB to a `look.materials` ID, the way `props.materials`
+ * does for props:
+ *
+ *   binding: { skin, material: { family: 'pbr', ... }, materials: { Gullet: 'brasscap.gullet' }, loops }
+ *
+ * The GLB's one skinned mesh may then carry up to eight primitives (one per GLB material, the same channels). A
+ * primitive drawn in a mapped material draws with that look material (an emissive eye or gullet), each mapped name one
+ * more draw per rig; every other primitive draws with the binding's family material, merged into one draw. Without
+ * `materials` a skin draws as before, in its one family material.
+ */
+import {
+  array,
+  check,
+  maxLength,
+  minLength,
+  number,
+  object,
+  optional,
+  pipe,
+  record,
+  regex,
+  string,
+} from 'valibot'
+
+import type { GenericSchema } from 'valibot'
+
+interface SkinPrimitive {
+  readonly attributes: Readonly<Record<string, number>>
+  readonly indices?: number | undefined
+  readonly material?: number | undefined
+}
+interface SkinGlbMaterial {
+  readonly name?: string | undefined
+}
+type Names = Readonly<Record<string, string>>
+
+/** The most named parts a skin may map: with its family material, a rig draws in at most eight materials. */
+const SKIN_MATERIAL_PARTS = 7
+const ONE = 1
+/** The most primitives of a skin's one skinned mesh. */
+const SKIN_PRIMITIVES = SKIN_MATERIAL_PARTS + ONE
+const NAME_LENGTH = 128
+const NONE = 0
+const ID = /^[a-z][a-z0-9.-]*$/u
+const CONTROL = /\p{Cc}/u
+const RESERVED: ReadonlySet<string> = new Set([
+  '__proto__',
+  'prototype',
+  'constructor',
+])
+
+function isGlbName(name: string): boolean {
+  return name.trim() === name && !RESERVED.has(name) && !CONTROL.test(name)
+}
+function partCount(rows: Names): boolean {
+  const count = Object.keys(rows).length
+  return count > NONE && count <= SKIN_MATERIAL_PARTS
+}
+
+const glbName = pipe(
+  string(),
+  minLength(ONE),
+  maxLength(NAME_LENGTH),
+  check(isGlbName, 'a GLB material name'),
+)
+const lookId = pipe(string(), regex(ID), maxLength(NAME_LENGTH))
+
+/** `parameters.materials`: GLB material name → `look.materials` ID (1–7 names). */
+const SkinMaterialsSchema: GenericSchema<
+  Record<string, string>,
+  Record<string, string>
+> = pipe(record(glbName, lookId), check(partCount, '1–7 named skin materials'))
+
+const attributes = record(string(), number())
+/** A skinned primitive as the rig check reads it: its channels, index and material. */
+const SkinPrimitiveSchema: GenericSchema<SkinPrimitive, SkinPrimitive> = object(
+  { attributes, indices: optional(number()), material: optional(number()) },
+)
+const glbMaterial = object({ name: optional(string()) })
+/** The GLB's materials, by index (only their names are read). */
+const SkinGlbMaterialsSchema: GenericSchema<
+  SkinGlbMaterial[] | undefined,
+  SkinGlbMaterial[]
+> = optional(array(glbMaterial), [])
+
+/** A skin's primitive count is one to eight. */
+function skinPrimitiveCount(count: number | undefined): boolean {
+  return count !== undefined && count > NONE && count <= SKIN_PRIMITIVES
+}
+
+/** Two primitives with the same channels and index presence (the client merges them into one geometry). */
+function sameChannels(left: SkinPrimitive, right: SkinPrimitive): boolean {
+  const names = Object.keys(left.attributes)
+  const shared = names.filter((name: string): boolean =>
+    Object.hasOwn(right.attributes, name),
+  )
+  const count = Object.keys(right.attributes).length
+  const indexed = (left.indices === undefined) === (right.indices === undefined)
+  return indexed && shared.length === names.length && count === names.length
+}
+
+/** Why a skin's primitives refuse their mapped names, or '': one set of channels, every mapped name drawn. */
+function skinPartsFault(
+  primitives: readonly SkinPrimitive[],
+  materials: readonly SkinGlbMaterial[],
+  parts: Names | undefined,
+): string {
+  const [first] = primitives
+  const same = (primitive: SkinPrimitive): boolean =>
+    first === undefined || sameChannels(first, primitive)
+  if (
+    !primitives.every((primitive: SkinPrimitive): boolean => same(primitive))
+  ) {
+    return 'skin primitives differ in their channels'
+  }
+  const nameOf = (primitive: SkinPrimitive): string | undefined =>
+    primitive.material === undefined
+      ? undefined
+      : materials[primitive.material]?.name
+  const used = new Set(
+    primitives.map((primitive: SkinPrimitive): string | undefined =>
+      nameOf(primitive),
+    ),
+  )
+  const drawn = (name: string): boolean => used.has(name)
+  const missing = Object.keys(parts ?? {}).find(
+    (name: string): boolean => !drawn(name),
+  )
+  return missing === undefined ? '' : `no GLB material ${missing}`
+}
+
+/** Why a binding's mapped IDs refuse, or '': each is a declared `look.materials` ID of a family (not a graph) material. */
+function skinMaterialsFault(
+  parts: Names | undefined,
+  declared: Readonly<Record<string, unknown>>,
+): string {
+  const missing = Object.values(parts ?? {}).find(
+    (id: string): boolean => !Object.hasOwn(declared, id),
+  )
+  if (missing !== undefined) {
+    return `skin material ${missing} is not a declared look material`
+  }
+  // A part flashes with the body through its family's emissive or colour; a graph has neither port for certain
+  const isGraph = (id: string): boolean => {
+    const entry: unknown = declared[id]
+    return (
+      typeof entry === 'object' &&
+      entry !== null &&
+      Reflect.get(entry, 'family') === 'graph'
+    )
+  }
+  const graph = Object.values(parts ?? {}).find((id: string): boolean =>
+    isGraph(id),
+  )
+  return graph === undefined
+    ? ''
+    : `skin material ${graph} is a graph material: a skin part takes a family material`
+}
+
+export {
+  SKIN_MATERIAL_PARTS,
+  SkinGlbMaterialsSchema,
+  SkinMaterialsSchema,
+  SkinPrimitiveSchema,
+  skinMaterialsFault,
+  skinPartsFault,
+  skinPrimitiveCount,
+  type SkinGlbMaterial,
+  type SkinPrimitive,
+}