@aethervtt/shard-procgen 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @aethervtt/shard-procgen
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/check.d.ts

@@ -0,0 +1,12 @@
+/** A call a generator module makes that can't be deterministic. */
+export interface NondeterministicCall {
+    file: string;
+    line: number;
+    column: number;
+    call: string;
+}
+/**
+ * Finds `Math.random()`, `Date.now()`, and `performance.now()` in modules that define generators
+ * (`project.generator(` or `defineGenerator(`), for `shard check`. Comments are skipped.
+ */
+export declare function findNondeterminism(file: string, source: string): NondeterministicCall[];

package/dist/check.js

@@ -0,0 +1,18 @@
+const DEFINES = /\.generator\s*\(|\bdefineGenerator\s*\(/;
+const CALLS = /\b(Math\.random|Date\.now|performance\.now)\s*\(/g;
+function findNondeterminism(file, source) {
+  if (!DEFINES.test(source)) return [];
+  const code = source.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, (m) => m.replace(/[^\n]/g, " "));
+  const out = [];
+  CALLS.lastIndex = 0;
+  for (let m = CALLS.exec(code); m; m = CALLS.exec(code)) {
+    const before = code.slice(0, m.index);
+    const line = before.split("\n").length;
+    const column = m.index - before.lastIndexOf("\n");
+    out.push({ file, line, column, call: `${m[1]}()` });
+  }
+  return out;
+}
+export {
+  findNondeterminism
+};

package/dist/context.d.ts

@@ -0,0 +1,61 @@
+import { type AssetRef, type Fields, Rng } from '@aethervtt/shard-core';
+import { type NoiseGraph, sampleGrid2d, sampleNoiseGradient, sampleSpherePatch } from '@aethervtt/shard-noise';
+import type { Generator, GenParams, GenRequest, OutputAsset, OutputSpec } from './generator.js';
+import { type MeshBuilderApi } from './mesh-builder.js';
+/** Noise sampling inside a generator: 0041's sync functions, on the generator's thread. */
+export interface NoiseApi {
+    /** Values at absolute points (`xyz…`); see `sampleNoise`. */
+    sample(graph: NoiseGraph, seed: number, points: Float32Array, out: Float32Array, node?: string): void;
+    /** Values at `origin + local` (precise far from the origin); see `sampleOffset`. */
+    offset(graph: NoiseGraph, seed: number, origin: ArrayLike<number>, local: Float32Array, out: Float32Array, node?: string): void;
+    grid2d: typeof sampleGrid2d;
+    spherePatch: typeof sampleSpherePatch;
+    gradient: typeof sampleNoiseGradient;
+}
+/** What `run` gets besides its params. Everything here is deterministic. */
+export interface GenContext {
+    readonly seed: number;
+    /** Seeded from `hashSeed(seed, generatorName)`: the only randomness a generator has. */
+    readonly rng: Rng;
+    /** `hashSeed(seed, label)`: a stable seed per label, for parts and nested generators. */
+    childSeed(label: string | number): number;
+    readonly noise: NoiseApi;
+    /**
+     * An asset a param points at (a NoiseGraph, a mesh, a data value), loaded before `run`. Only
+     * handles in the params can be loaded, so a generator never does I/O.
+     */
+    load<T = unknown>(ref: AssetRef | {
+        guid?: string;
+        path?: string;
+    } | null | undefined): T;
+    /**
+     * Another generator's output, as a reference to put in this one's output (a mesh handle in a
+     * fragment). It's cached on its own: changing it rebuilds only it.
+     */
+    generate<const P extends Fields, const O extends OutputSpec>(gen: Generator<P, O>, params: GenParams<P>, seed: number): Promise<AssetRef<OutputAsset<O>>>;
+    readonly mesh: MeshBuilderApi;
+    /** A GPU for compute, when one exists. Absent in workers and headless runs. */
+    readonly gpu?: undefined;
+    /** A non-fatal problem, shown by procgen.run and asset.get. */
+    warn(message: string, path?: string): void;
+}
+export interface ContextState {
+    children: GenRequest[];
+    warnings: {
+        message: string;
+        path?: string;
+    }[];
+}
+/** A dependency as the job carries it: the handle's guid and path, and the loaded object. */
+export interface LoadedDependency {
+    guid: string | undefined;
+    path: string | undefined;
+    type: string;
+    object: unknown;
+}
+export declare function createContext(gen: Generator, request: GenRequest, deps: readonly LoadedDependency[], chain: readonly string[], state: ContextState): GenContext;
+/**
+ * Replaces `Math.random`, `Date.now`, and `performance.now` with functions that throw
+ * `procgen/nondeterministic`. Returns a function that restores them.
+ */
+export declare function guardNondeterminism(generator: string): () => void;

package/dist/context.js

@@ -0,0 +1,96 @@
+import { hashSeed, Rng, ShardError } from "@aethervtt/shard-core";
+import {
+  sampleGrid2d,
+  sampleNoise,
+  sampleNoiseGradient,
+  sampleOffset,
+  sampleSpherePatch
+} from "@aethervtt/shard-noise";
+import { guidOf, identityOf, proceduralPath, requestOf } from "./generator.js";
+import { meshBuilder } from "./mesh-builder.js";
+const noiseApi = {
+  sample: sampleNoise,
+  offset: sampleOffset,
+  grid2d: sampleGrid2d,
+  spherePatch: sampleSpherePatch,
+  gradient: sampleNoiseGradient
+};
+function createContext(gen, request, deps, chain, state) {
+  const self = identityOf(request);
+  return {
+    seed: request.seed,
+    rng: new Rng(hashSeed(request.seed, gen.name)),
+    childSeed: (label) => hashSeed(request.seed, label),
+    noise: noiseApi,
+    load(ref) {
+      const dep = ref && deps.find(
+        (d) => ref.guid !== void 0 && d.guid === ref.guid || ref.path !== void 0 && d.path === ref.path
+      );
+      if (!dep) {
+        throw new ShardError(
+          "procgen/undeclared-dependency",
+          `${gen.name} loaded ${JSON.stringify(ref ?? null)}, which isn't one of its params`,
+          {
+            hint: "ctx.load takes the handles in the params (declare a t.handle param and pass the asset in)."
+          }
+        );
+      }
+      return dep.object;
+    },
+    generate: (child, params, seed) => {
+      const req = requestOf(child, params, seed);
+      const id = identityOf(req);
+      if (id === self || chain.includes(id)) {
+        return Promise.reject(
+          new ShardError(
+            "procgen/cycle",
+            `${gen.name} generates ${child.name} with the same inputs as one of its callers`,
+            {
+              hint: "A generator that calls itself needs different params or a different seed (ctx.childSeed) each level."
+            }
+          )
+        );
+      }
+      if (!state.children.some((c) => identityOf(c) === id)) state.children.push(req);
+      return Promise.resolve({
+        type: child.outputType,
+        guid: guidOf(req),
+        path: proceduralPath(req)
+      });
+    },
+    mesh: meshBuilder,
+    warn: (message, path) => state.warnings.push(path === void 0 ? { message } : { message, path })
+  };
+}
+function guardNondeterminism(generator) {
+  const fail = (what) => () => {
+    throw new ShardError("procgen/nondeterministic", `${generator} called ${what}`, {
+      hint: "Generators are pure: use ctx.rng for randomness and pass times in as params."
+    });
+  };
+  const random = Math.random;
+  const now = Date.now;
+  const perf = globalThis.performance;
+  const ownNow = perf ? Object.getOwnPropertyDescriptor(perf, "now") : void 0;
+  Math.random = fail("Math.random()");
+  Date.now = fail("Date.now()");
+  if (perf) {
+    Object.defineProperty(perf, "now", {
+      value: fail("performance.now()"),
+      configurable: true,
+      writable: true
+    });
+  }
+  return () => {
+    Math.random = random;
+    Date.now = now;
+    if (perf) {
+      if (ownNow) Object.defineProperty(perf, "now", ownNow);
+      else delete perf.now;
+    }
+  };
+}
+export {
+  createContext,
+  guardNondeterminism
+};

package/dist/generator.d.ts

@@ -0,0 +1,135 @@
+import type { DataType } from '@aethervtt/shard-assets';
+import { type AssetRef, type ComponentDef, type Fields, type FieldValue, type InferFields, type InitFields, type JsonValue } from '@aethervtt/shard-core';
+import type { MeshData } from '@aethervtt/shard-mesh';
+import type { TextureUsage } from '@aethervtt/shard-texture';
+import type { GenContext } from './context.js';
+/** What a generator makes: a kind, or a data type (0031) whose value it returns. */
+export type OutputSpec = 'mesh' | 'texture' | 'data' | 'entities' | DataType;
+/** A mesh with its levels of detail, as `ctx.mesh.finish` returns it. */
+export interface MeshResult {
+    readonly kind: 'mesh';
+    mesh: MeshData;
+    /** Lower levels of detail, finest first (sub-assets `#LOD1`, `#LOD2`, …). */
+    lods: MeshData[];
+}
+/** A texture as `Texture.create` takes it: RGBA8 levels, or float RGBA for `usage: 'hdr'`. */
+export interface TextureData {
+    width: number;
+    height: number;
+    /** Default `color` (sRGB). `data` and `normal` are linear; `hdr` levels are Float32Array. */
+    usage?: TextureUsage;
+    /** Level 0 first. With `mipmaps` and one level, the rest are generated. */
+    mips: (Uint8Array | Float32Array)[];
+    mipmaps?: boolean;
+}
+/**
+ * One entity of an `entities` output: a prefab file's entity (0030). Components are by name with
+ * JSON values; handles may be refs (`ctx.generate` results, loaded params) or `{ path }`.
+ */
+export interface FragmentEntity {
+    name: string;
+    components?: Record<string, Record<string, unknown>>;
+    children?: FragmentEntity[];
+}
+/** An `entities` output: the root entity (its components merge into the instance), or its children. */
+export type Fragment = FragmentEntity | FragmentEntity[];
+/** What `run` returns for an output spec. */
+export type RunResult<O extends OutputSpec> = O extends 'mesh' ? MeshResult | MeshData : O extends 'texture' ? TextureData : O extends 'entities' ? Fragment : O extends DataType<infer F> ? InferFields<F> : JsonValue;
+/** The asset type an output spec makes. */
+export type OutputAsset<O extends OutputSpec> = O extends 'mesh' ? 'Mesh' : O extends 'texture' ? 'Texture' : O extends 'entities' ? 'Prefab' : O extends DataType<Fields, infer N> ? N : 'Data';
+export interface GeneratorOptions<P extends Fields, O extends OutputSpec> {
+    /** Parameters: a component schema (units, ranges, defaults, handles to what `run` loads). */
+    params: P;
+    output: O;
+    /** Bump for changes the code hash can't see (a vendored table, say). Default 1. */
+    version?: number;
+    description?: string;
+    /**
+     * Makes the output. Pure: only `ctx.rng`, `ctx.noise`, the params, and what `ctx.load` returns.
+     * Returns synchronously, or a promise when it awaits `ctx.generate`.
+     */
+    run(ctx: GenContext, params: InferFields<P>): RunResult<O> | Promise<RunResult<O>>;
+}
+/**
+ * A generator: `(seed, params) → output`, cached by the hash of its inputs. It's also a reference
+ * to itself (`type: 'Generator'`), so it can go in a `t.handle('Generator')` field
+ * (`GeneratorInstance({ generator: StarSystem })`).
+ */
+export interface Generator<P extends Fields = Fields, O extends OutputSpec = OutputSpec> extends AssetRef<'Generator'> {
+    readonly name: string;
+    readonly description: string | undefined;
+    readonly params: ComponentDef<P>;
+    /** The output kind; `data` for data types too. */
+    readonly output: 'mesh' | 'texture' | 'data' | 'entities';
+    /** The asset type outputs load as: `Mesh`, `Texture`, `Prefab`, a data type's name, or `Data`. */
+    readonly outputType: OutputAsset<O>;
+    /** The data type a `data` output is validated against, if any. */
+    readonly dataType: ComponentDef | undefined;
+    readonly version: number;
+    readonly run: GeneratorOptions<P, O>['run'];
+}
+/** A small, stable string hash (two FNV-1a lanes, 64 bits as hex). Not for security. */
+export declare function hashString(text: string): string;
+/**
+ * Defines a generator named `name` (namespaced: `shard/Rock` for engine generators; projects use
+ * `project.generator`, which prefixes the project name). Defining a name again replaces it (hot
+ * reload).
+ */
+export declare function defineGenerator<const P extends Fields, const O extends OutputSpec>(name: string, options: GeneratorOptions<P, O>): Generator<P, O>;
+export declare function findGenerator(name: string): Generator | undefined;
+/** The generator a name or reference names. Throws `procgen/unknown-generator`. */
+export declare function requireGenerator(ref: string | {
+    name?: string;
+    path?: string;
+}): Generator;
+/** Every generator defined in this process, sorted by name. */
+export declare function allGenerators(): Generator[];
+/**
+ * Sets generators' code hashes: the hash of each generator's module and what it imports inside
+ * `scripts/`, from the bundler's module graph. Hosts call it before (re)loading project code; a
+ * generator without one uses the hash of its `run` source.
+ */
+export declare function setGeneratorCodeHashes(hashes: Readonly<Record<string, string>>): void;
+export declare function codeHashOf(gen: Generator | string): string;
+/**
+ * The normalized params: validated, defaults filled in, keys sorted, f32 fields at f32 precision
+ * (so `1` and `1.0000000001` are the same inputs), handles as `{ path }` (or `{ guid }`). Throws
+ * `procgen/bad-params` with every error in `details`.
+ */
+export declare function canonicalParams(gen: Generator, params?: unknown): Record<string, JsonValue>;
+/**
+ * Param values given in code: any subset (the rest take defaults), with handles as refs or as
+ * `{ path }` / `{ guid }`.
+ */
+export type GenParams<P extends Fields> = {
+    [K in keyof P]?: NonNullable<FieldValue<P[K]>> extends AssetRef ? {
+        guid?: string;
+        path?: string;
+    } | null : InitFields<P>[K];
+};
+/** One output: a generator, its canonical params, and a seed. */
+export interface GenRequest {
+    readonly generator: string;
+    readonly params: Record<string, JsonValue>;
+    readonly seed: number;
+}
+/** Makes a request, validating the params. */
+export declare function requestOf(gen: Generator, params: GenParams<Fields> | Record<string, unknown> | undefined, seed: number): GenRequest;
+/**
+ * A request's identity: which output it names, whatever the code or loaded assets are now. Outputs
+ * are registered as `gen:<identity>`, and a code or dependency change swaps the content in place.
+ */
+export declare function identityOf(request: GenRequest): string;
+/** The asset guid of a request's output. */
+export declare function guidOf(request: GenRequest): string;
+/**
+ * The `procedural:` path of a request (`procedural:star-explorer/Rock?radius=2&seed=3`): params
+ * that differ from their defaults, sorted, then the seed. Resolves the same output anywhere.
+ */
+export declare function proceduralPath(request: GenRequest): string;
+/**
+ * Parses `star-explorer/Rock?seed=3&radius=2` (the part after `procedural:`): numbers, bools,
+ * asset paths for handles, JSON for structs and lists. Throws `procgen/unknown-generator` or
+ * `procgen/bad-params` (with `path` set to `at`).
+ */
+export declare function parseProceduralRef(spec: string, at?: string): GenRequest;

package/dist/generator.js

@@ -0,0 +1,269 @@
+import {
+  defineSchema,
+  isPlainObject,
+  ShardError
+} from "@aethervtt/shard-core";
+const generators = /* @__PURE__ */ new Map();
+const codeHashes = /* @__PURE__ */ new Map();
+const sourceHashes = /* @__PURE__ */ new Map();
+function hashString(text) {
+  let a = 2166136261;
+  let b = 16777619 ^ 2654435769;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    a = Math.imul(a ^ c, 16777619);
+    b = Math.imul(b ^ c, 1540483477);
+    b ^= b >>> 13;
+  }
+  a ^= a >>> 15;
+  b ^= b >>> 16;
+  return (a >>> 0).toString(16).padStart(8, "0") + (b >>> 0).toString(16).padStart(8, "0");
+}
+function outputOf(spec) {
+  if (spec === "mesh") return { output: "mesh", outputType: "Mesh", dataType: void 0 };
+  if (spec === "texture") return { output: "texture", outputType: "Texture", dataType: void 0 };
+  if (spec === "entities") return { output: "entities", outputType: "Prefab", dataType: void 0 };
+  if (spec === "data") return { output: "data", outputType: "Data", dataType: void 0 };
+  if (spec && typeof spec === "object" && typeof spec.name === "string") {
+    return { output: "data", outputType: spec.name, dataType: spec };
+  }
+  throw new ShardError("procgen/bad-output", `Unknown generator output ${JSON.stringify(spec)}`, {
+    hint: 'Use "mesh", "texture", "data", "entities", or a data type (project.dataAsset).'
+  });
+}
+function defineGenerator(name, options) {
+  if (!/^[a-z][a-z0-9-]*\/[A-Za-z][A-Za-z0-9]*$/.test(name)) {
+    throw new ShardError("procgen/bad-name", `"${name}" isn't a generator name`, {
+      hint: 'Generator names are "<namespace>/<Name>", e.g. "star-explorer/Rock".'
+    });
+  }
+  const params = defineSchema(`${name}Params`, options.params, {
+    description: `Parameters of the ${name} generator.`
+  });
+  const out = outputOf(options.output);
+  const version = options.version ?? 1;
+  const gen = {
+    type: "Generator",
+    guid: `generator:${name}`,
+    path: name,
+    name,
+    description: options.description,
+    params,
+    output: out.output,
+    outputType: out.outputType,
+    dataType: out.dataType,
+    version,
+    run: options.run
+  };
+  generators.set(name, gen);
+  sourceHashes.set(name, hashString(options.run.toString()));
+  return gen;
+}
+function findGenerator(name) {
+  return generators.get(name);
+}
+function requireGenerator(ref) {
+  const name = typeof ref === "string" ? ref : ref.name ?? ref.path ?? "";
+  const gen = generators.get(name);
+  if (!gen) {
+    throw new ShardError("procgen/unknown-generator", `No generator named "${name}"`, {
+      hint: generators.size ? `Generators: ${[...generators.keys()].sort().join(", ")}.` : "Define one with project.generator (or defineGenerator) in scripts/."
+    });
+  }
+  return gen;
+}
+function allGenerators() {
+  return [...generators.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+function setGeneratorCodeHashes(hashes) {
+  codeHashes.clear();
+  for (const [name, hash] of Object.entries(hashes)) codeHashes.set(name, hash);
+}
+function codeHashOf(gen) {
+  const name = typeof gen === "string" ? gen : gen.name;
+  return codeHashes.get(name) ?? sourceHashes.get(name) ?? "";
+}
+const F32_KINDS = /* @__PURE__ */ new Set([
+  "f32",
+  "vec2",
+  "vec3",
+  "vec4",
+  "quat",
+  "mat3",
+  "mat4",
+  "affine3x4",
+  "color"
+]);
+function normalize(field, value) {
+  if (field?.kind === "handle" && isPlainObject(value))
+    return typeof value.path === "string" ? { path: value.path } : value;
+  if (field && F32_KINDS.has(field.kind)) {
+    if (typeof value === "number") return Math.fround(value);
+    if (Array.isArray(value)) return value.map((v) => typeof v === "number" ? Math.fround(v) : v);
+    return value;
+  }
+  if (field?.kind === "list" && Array.isArray(value))
+    return value.map((v) => normalize(field.item, v));
+  if (field?.kind === "struct" && isPlainObject(value)) return sortFields(field.fields, value);
+  if (Array.isArray(value)) return value.map((v) => normalize(void 0, v));
+  if (isPlainObject(value)) return sortFields(void 0, value);
+  return value;
+}
+function sortFields(fields, value) {
+  const out = {};
+  for (const key of Object.keys(value).sort()) out[key] = normalize(fields?.[key], value[key]);
+  return out;
+}
+function canonicalParams(gen, params = {}) {
+  const json = toParamJson(params ?? {});
+  const errors = gen.params.validate(json);
+  if (errors.length > 0) {
+    const first = errors[0];
+    throw new ShardError("procgen/bad-params", `${gen.name}: ${first.message}`, {
+      path: first.path,
+      hint: first.hint ?? `The ${gen.name} params are listed in .agents/generators.md.`,
+      details: errors
+    });
+  }
+  const value = gen.params.serialize(gen.params.deserialize(json));
+  return sortFields(gen.params.fields, value);
+}
+function toParamJson(value) {
+  if (ArrayBuffer.isView(value)) return Array.from(value);
+  if (Array.isArray(value)) return value.map(toParamJson);
+  if (value && typeof value === "object") {
+    const obj = value;
+    if (typeof obj.type === "string" && ("guid" in obj || "path" in obj) && isRef(obj)) {
+      const out2 = {};
+      if (typeof obj.guid === "string") out2.guid = obj.guid;
+      if (typeof obj.path === "string") out2.path = obj.path;
+      return out2;
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) if (v !== void 0) out[k] = toParamJson(v);
+    return out;
+  }
+  return value;
+}
+function isRef(obj) {
+  for (const key of Object.keys(obj)) {
+    if (key !== "type" && key !== "guid" && key !== "path" && typeof obj[key] !== "function")
+      return false;
+  }
+  return true;
+}
+function requestOf(gen, params, seed) {
+  if (!Number.isInteger(seed) || seed < 0 || seed > 4294967295) {
+    throw new ShardError("procgen/bad-params", `${gen.name}: seed must be a u32, got ${seed}`, {
+      path: "/seed",
+      hint: "Seeds are integers from 0 to 4294967295; derive child seeds with ctx.childSeed."
+    });
+  }
+  return { generator: gen.name, params: canonicalParams(gen, params), seed: seed >>> 0 };
+}
+function identityOf(request) {
+  return hashString(JSON.stringify([request.generator, request.params, request.seed]));
+}
+function guidOf(request) {
+  return `gen:${identityOf(request)}`;
+}
+function shortNumber(n) {
+  if (Math.fround(n) !== n || Number.isInteger(n)) return String(n);
+  for (let digits = 1; digits < 17; digits++) {
+    const text = String(Number(n.toPrecision(digits)));
+    if (Math.fround(Number(text)) === n) return text;
+  }
+  return String(n);
+}
+function formatValue(value) {
+  if (typeof value === "number") return shortNumber(value);
+  if (typeof value === "boolean") return String(value);
+  if (isPlainObject(value) && Object.keys(value).length === 1 && typeof value.path === "string")
+    return encodeURIComponent(value.path);
+  return encodeURIComponent(JSON.stringify(value));
+}
+function proceduralPath(request) {
+  const gen = requireGenerator(request.generator);
+  const defaults = canonicalParams(gen, {});
+  const parts = [];
+  for (const key of Object.keys(request.params)) {
+    const value = request.params[key];
+    if (JSON.stringify(value) === JSON.stringify(defaults[key])) continue;
+    const v = isPlainObject(value) && typeof value.path === "string" ? { path: value.path } : value;
+    parts.push(`${key}=${formatValue(v)}`);
+  }
+  parts.push(`seed=${request.seed}`);
+  return `procedural:${request.generator}?${parts.join("&")}`;
+}
+function parseValue(field, raw) {
+  const text = decodeURIComponent(raw);
+  if (field?.kind === "handle") return { path: text };
+  if (text === "true") return true;
+  if (text === "false") return false;
+  if (text !== "" && Number.isFinite(Number(text))) return Number(text);
+  if (/^[[{"]/.test(text)) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+function parseProceduralRef(spec, at) {
+  const hash = spec.indexOf("#");
+  const body = hash === -1 ? spec : spec.slice(0, hash);
+  const q = body.indexOf("?");
+  const name = q === -1 ? body : body.slice(0, q);
+  let gen;
+  try {
+    gen = requireGenerator(name);
+  } catch (err) {
+    throw new ShardError(err.code, err.message, {
+      path: at,
+      hint: err.hint
+    });
+  }
+  const params = {};
+  let seed = 0;
+  if (q !== -1) {
+    for (const pair of body.slice(q + 1).split("&")) {
+      if (!pair) continue;
+      const eq = pair.indexOf("=");
+      const key = decodeURIComponent(eq === -1 ? pair : pair.slice(0, eq));
+      const raw = eq === -1 ? "" : pair.slice(eq + 1);
+      if (key === "seed") {
+        seed = Number(raw);
+        continue;
+      }
+      if (!(key in gen.params.fields)) {
+        throw new ShardError("procgen/bad-params", `${gen.name} has no parameter "${key}"`, {
+          path: at,
+          hint: `Parameters: ${Object.keys(gen.params.fields).join(", ") || "(none)"}, and seed.`
+        });
+      }
+      params[key] = parseValue(gen.params.fields[key], raw);
+    }
+  }
+  try {
+    return requestOf(gen, params, seed);
+  } catch (err) {
+    const e = err;
+    throw new ShardError(e.code, e.message, { path: at, hint: e.hint, details: e.details });
+  }
+}
+export {
+  allGenerators,
+  canonicalParams,
+  codeHashOf,
+  defineGenerator,
+  findGenerator,
+  guidOf,
+  hashString,
+  identityOf,
+  parseProceduralRef,
+  proceduralPath,
+  requestOf,
+  requireGenerator,
+  setGeneratorCodeHashes
+};

package/dist/importer.d.ts

@@ -0,0 +1,18 @@
+import { type JsonValue } from '@aethervtt/shard-core';
+export declare const generatorDependency: (id: string) => string | undefined;
+export declare const generatorSchema: () => unknown;
+/** The parsed body of a generator file. */
+export interface GenFile {
+    generator: string;
+    seed: number;
+    params: Record<string, JsonValue>;
+}
+/** Parses and checks a `*.gen.json` file's shape (not its params). Errors point into the file. */
+export declare function parseGenFile(text: string, path: string): GenFile;
+/**
+ * `*.gen.json`: a generator, a seed, and params. Imports as the generator's output (a `Mesh` with
+ * `#LOD1…` sub-assets, a `Texture`, a data value, or a `Prefab`), cached like any asset, plus a
+ * `#Generator` sub-asset that `GeneratorInstance` can point at. Re-imports when the file, a loaded
+ * asset, or the generator's code changes.
+ */
+export declare const GeneratorImporter: import("@aethervtt/shard-assets").ImporterDef;