@aethervtt/shard-procgen 0.0.1

package/dist/runtime.js

@@ -0,0 +1,553 @@
+import {
+  AssetStore,
+  assetServer,
+  defineAssetType,
+  findAssetType,
+  sha256Hex
+} from "@aethervtt/shard-assets";
+import {
+  defineResource,
+  isPlainObject,
+  ShardError
+} from "@aethervtt/shard-core";
+import { loadNoiseKernel } from "@aethervtt/shard-noise";
+import { LogResource } from "@aethervtt/shard-runtime";
+import {
+  codeHashOf,
+  guidOf,
+  identityOf,
+  proceduralPath,
+  requestOf,
+  requireGenerator
+} from "./generator.js";
+import { executeJob } from "./job.js";
+import { checkFragment } from "./outputs.js";
+import { decodeRecord, encodeRecord, recordBytes } from "./record.js";
+const encoder = new TextEncoder();
+const GeneratorBindings = defineResource(
+  "procgen/Generators",
+  {
+    description: "Generator assets (a generator and default params) by guid.",
+    init: () => new AssetStore("Generator")
+  }
+);
+const GeneratorAssetType = defineAssetType("Generator", {
+  store: GeneratorBindings,
+  load: (artifact) => artifact.json
+});
+const GeneratedData = defineResource("procgen/Data", {
+  description: "Values of generators whose output is untyped data.",
+  init: () => new AssetStore("Data")
+});
+const DataAssetType = defineAssetType("Data", {
+  store: GeneratedData,
+  load: (artifact) => artifact.json ?? null
+});
+let host = {};
+function configureProcgenHost(options) {
+  host = { ...host, ...options };
+}
+function procgenHost() {
+  return host;
+}
+async function warmGeneratorWorkers() {
+  const { workers } = host;
+  const workerModule = await host.workerModule;
+  if (!workers || workers.size === 0 || !workerModule) return;
+  const jobs = [];
+  for (let i = 0; i < workers.size; i++) jobs.push(workers.run(workerModule, "warmUp", []));
+  await Promise.all(jobs);
+}
+const SLICE_MS = 0.25;
+const waiting = [];
+let sliceStart = -1;
+let pumping = false;
+let stepStart = -1;
+let mainThreadMs = 0;
+const nextTask = typeof setImmediate === "function" ? (run) => void setImmediate(run) : (run) => {
+  const channel = new MessageChannel();
+  channel.port1.onmessage = () => run();
+  channel.port2.postMessage(0);
+};
+function pump() {
+  if (stepStart >= 0) {
+    mainThreadMs += performance.now() - stepStart;
+    stepStart = -1;
+  }
+  if (waiting.length === 0) {
+    sliceStart = -1;
+    pumping = false;
+    return;
+  }
+  if (sliceStart < 0) sliceStart = performance.now();
+  else if (performance.now() - sliceStart > SLICE_MS) {
+    sliceStart = -1;
+    nextTask(pump);
+    return;
+  }
+  stepStart = performance.now();
+  waiting.shift()();
+  queueMicrotask(pump);
+}
+function procgenMainThreadMs() {
+  return mainThreadMs;
+}
+function mainThreadTurn() {
+  return new Promise((resolve) => {
+    waiting.push(resolve);
+    if (!pumping) {
+      pumping = true;
+      nextTask(pump);
+    }
+  });
+}
+let running = 0;
+const queued = [];
+async function runJob(job) {
+  const pool = host.workers;
+  const workerModule = await host.workerModule;
+  if (pool && pool.size > 0 && workerModule && job.deps.every((d) => d.artifact)) {
+    const kernel = await loadNoiseKernel();
+    if (running >= pool.size * 2) await new Promise((resolve) => queued.push(resolve));
+    running++;
+    try {
+      await mainThreadTurn();
+      const posted = {
+        ...job,
+        // The worker bundle can be older than this thread's component schemas.
+        checkComponents: false,
+        deps: job.deps.map(({ object: _o, ...d }) => d),
+        noise: kernel.module,
+        noiseSimd: kernel.simd
+      };
+      const { packed } = await pool.run(workerModule, "runGeneratorJob", [
+        posted
+      ]);
+      const record = decodeRecord(packed);
+      if (!record) {
+        throw new ShardError(
+          "procgen/generator-failed",
+          `${job.generator}: a worker sent back no record`
+        );
+      }
+      const gen = requireGenerator(job.generator);
+      if (gen.output === "entities") {
+        await mainThreadTurn();
+        for (const a of record.assets) if (a.type === "Prefab") checkFragment(gen, a);
+      }
+      return {
+        assets: record.assets,
+        children: record.children,
+        warnings: record.warnings,
+        ms: record.ms,
+        packed
+      };
+    } finally {
+      running--;
+      queued.shift()?.();
+    }
+  }
+  await Promise.resolve();
+  return executeJob(job);
+}
+function artifactOf(asset) {
+  const out = {};
+  if (asset.bytes) out.bytes = asset.bytes;
+  if (asset.json !== void 0) out.json = asset.json;
+  return out;
+}
+function collectHandles(fields, value, out) {
+  if (!isPlainObject(value)) return;
+  for (const [key, field] of Object.entries(fields)) visitHandle(field, value[key], out);
+}
+function visitHandle(field, value, out) {
+  if (value === null || value === void 0) return;
+  if (field.kind === "handle" && isPlainObject(value)) {
+    out.push(value);
+  } else if (field.kind === "struct" && field.fields) {
+    collectHandles(field.fields, value, out);
+  } else if (field.kind === "list" && field.item && Array.isArray(value)) {
+    for (const v of value) visitHandle(field.item, v, out);
+  }
+}
+function paramHandles(gen, params) {
+  const out = [];
+  collectHandles(gen.params.fields, params, out);
+  return out;
+}
+class ProcgenRuntime {
+  world;
+  server;
+  options;
+  stats = { runs: 0, memoryHits: 0, diskHits: 0, failures: 0, mainMs: 0 };
+  memory = /* @__PURE__ */ new Map();
+  memoryBytes = 0;
+  stored = [];
+  storedBytes = 0;
+  inflight = /* @__PURE__ */ new Map();
+  live = /* @__PURE__ */ new Map();
+  requests = /* @__PURE__ */ new Map();
+  /** Imported dependencies' artifacts and hashes, by guid (valid while the version matches). */
+  artifacts = /* @__PURE__ */ new Map();
+  pendingDeps = /* @__PURE__ */ new Set();
+  constructor(world, options = {}) {
+    this.world = world;
+    this.server = assetServer(world);
+    this.options = { cacheDir: ".shard/cache", cacheSize: 256 * 1024 * 1024, ...options };
+    this.server.onEvent((e) => {
+      if (e.kind !== "modified") return;
+      for (const live of this.live.values()) {
+        if (live.deps.has(e.guid)) {
+          this.pendingDeps.add(e.guid);
+          queueMicrotask(() => this.regenerateForDeps());
+          return;
+        }
+      }
+    });
+  }
+  configure(options) {
+    this.options = { ...this.options, ...options };
+    return this;
+  }
+  /** The output entry of a request (label '' or a sub-asset like 'LOD1'), registered lazily. */
+  entryFor(request, label = "") {
+    const gen = requireGenerator(request.generator);
+    const base = guidOf(request);
+    if (!this.requests.has(base)) this.requests.set(base, request);
+    const guid = label === "" ? base : `${base}/${label}`;
+    const existing = this.server.entry(guid);
+    if (existing) return existing;
+    const path = label === "" ? proceduralPath(request) : `${proceduralPath(request)}#${label}`;
+    const type = label === "" ? gen.outputType : "Mesh";
+    return this.server.virtual(guid, path, type, () => this.produceLogged(guid), {
+      lazy: true,
+      collectable: true
+    });
+  }
+  /** Generates (or finds cached) an output and resolves with its ref once it's loaded. */
+  async generate(gen, params = {}, seed = 0) {
+    const request = requestOf(gen, params, seed);
+    const entry = this.entryFor(request);
+    await this.server.load(entry.guid);
+    return { type: gen.outputType, guid: entry.guid, path: entry.path };
+  }
+  /** What the last make of an output did: cache result, key, and time. */
+  lastResult(guid) {
+    const live = this.live.get(guid);
+    return live && { hit: live.hit, key: live.key, ms: live.ms };
+  }
+  /** The cached record behind a loaded output, if it's still in memory. */
+  recordOf(guid) {
+    const key = this.live.get(guid)?.key;
+    return key ? this.memory.get(key) : void 0;
+  }
+  /** `produce`, with failures logged (a GeneratorInstance or scene waiting on it shows why). */
+  async produceLogged(guid) {
+    try {
+      return await this.produce(guid);
+    } catch (err) {
+      this.world.tryResource(LogResource)?.error(err);
+      throw err;
+    }
+  }
+  /** Makes the object of `gen:<identity>[/label]`: the virtual asset's `create`. */
+  async produce(guid) {
+    const slash = guid.indexOf("/");
+    const base = slash === -1 ? guid : guid.slice(0, slash);
+    const label = slash === -1 ? "" : guid.slice(slash + 1);
+    const entry = this.server.entry(guid);
+    const request = this.requests.get(base) ?? this.requestOfPath(entry.path);
+    await mainThreadTurn();
+    const { record, hit, deps, codeHash } = await this.recordFor(request);
+    await mainThreadTurn();
+    const start = performance.now();
+    const asset = record.assets.find((a) => a.label === label);
+    if (!asset) {
+      throw new ShardError("assets/not-found", `${request.generator} made no "${label}"`, {
+        path: entry.path,
+        hint: `Its outputs: ${record.assets.map((a) => a.label || "(main)").join(", ")}.`
+      });
+    }
+    const type = findAssetType(asset.type);
+    if (!type) {
+      throw new ShardError("assets/unknown-type", `No asset type "${asset.type}" is registered`, {
+        path: entry.path,
+        hint: "Add the plugin that defines it (render/forward for meshes, textures)."
+      });
+    }
+    const self = label === "" ? guid : base;
+    const object = await type.load(artifactOf(asset), {
+      guid,
+      path: entry.path,
+      resolve: (p) => p.startsWith("#") ? this.server.resolve(`${self}/${p.slice(1)}`) : this.server.resolve(p)
+    });
+    this.live.set(guid, { request, label, key: record.key, codeHash, deps, hit, ms: record.ms });
+    if (label === "") {
+      for (const a of record.assets) if (a.label !== "") this.entryFor(request, a.label);
+      for (const child of record.children) {
+        try {
+          this.entryFor(child);
+        } catch (err) {
+          this.world.tryResource(LogResource)?.error(err);
+        }
+      }
+      const log = this.world.tryResource(LogResource);
+      for (const w of record.warnings)
+        log?.warn(`${request.generator}: ${w.message}`, { code: "procgen/warning", path: w.path });
+    }
+    this.stats.mainMs += performance.now() - start;
+    return object;
+  }
+  requestOfPath(path) {
+    const hash = path.indexOf("#");
+    const spec = (hash === -1 ? path : path.slice(0, hash)).slice("procedural:".length);
+    return parseRef(spec);
+  }
+  /** The dependencies of a request: loaded, with their artifacts (for workers) and hashes. */
+  async dependencies(gen, request) {
+    const deps = [];
+    const hashes = [];
+    const versions = /* @__PURE__ */ new Map();
+    for (const ref of paramHandles(gen, request.params)) {
+      const entry = this.server.entry(ref);
+      if (!entry) {
+        throw new ShardError(
+          "procgen/dependency-failed",
+          `${gen.name} needs ${ref.path ?? ref.guid}, which isn't in the catalog`,
+          { hint: "Check the path, or run `shard import` for new files." }
+        );
+      }
+      await this.server.load(entry.guid);
+      versions.set(entry.guid, entry.version);
+      const type = findAssetType(entry.type);
+      const object = type ? this.world.initResource(type.store).byGuid(entry.guid) : void 0;
+      const dep = {
+        guid: ref.guid ?? entry.guid,
+        path: ref.path ?? entry.path,
+        type: entry.type,
+        object
+      };
+      if (entry.source !== void 0) {
+        let cached = this.artifacts.get(entry.guid);
+        if (cached?.version !== entry.version) {
+          cached = {
+            version: entry.version,
+            artifact: await this.server.artifact(entry.guid),
+            hash: JSON.stringify(this.server.info(entry.guid).artifact ?? entry.guid)
+          };
+          this.artifacts.set(entry.guid, cached);
+        }
+        dep.artifact = cached.artifact;
+        hashes.push(cached.hash);
+      } else {
+        const live = this.live.get(entry.guid);
+        const record = live?.key ? this.memory.get(live.key) : void 0;
+        const asset = record?.assets.find((a) => a.label === live.label);
+        if (asset) dep.artifact = artifactOf(asset);
+        hashes.push(live?.key ? `${live.key}#${live.label}` : `${entry.guid}@${entry.version}`);
+      }
+      deps.push(dep);
+    }
+    return { deps, hashes, versions };
+  }
+  async recordFor(request) {
+    const gen = requireGenerator(request.generator);
+    const { deps, hashes, versions } = await this.dependencies(gen, request);
+    const codeHash = codeHashOf(gen);
+    const key = await sha256Hex(
+      encoder.encode(
+        JSON.stringify([gen.name, gen.version, codeHash, request.params, request.seed, hashes])
+      )
+    );
+    const cached = this.memory.get(key);
+    if (cached) {
+      this.memory.delete(key);
+      this.memory.set(key, cached);
+      this.stats.memoryHits++;
+      return { record: cached, hit: "memory", deps: versions, codeHash };
+    }
+    const running2 = this.inflight.get(key);
+    if (running2) return { record: await running2.promise, hit: "shared", deps: versions, codeHash };
+    let hit = "run";
+    const promise = (async () => {
+      const stored = await this.readStored(key);
+      if (stored) {
+        hit = "disk";
+        this.stats.diskHits++;
+        return stored;
+      }
+      let result;
+      try {
+        result = await runJob({ ...request, deps, chain: [] });
+      } catch (err) {
+        this.stats.failures++;
+        throw err;
+      }
+      this.stats.runs++;
+      const record = {
+        key,
+        assets: result.assets,
+        children: result.children,
+        warnings: result.warnings,
+        ms: result.ms,
+        bytes: recordBytes(result.assets)
+      };
+      void this.writeStored(record, result.packed).catch(
+        (err) => this.world.tryResource(LogResource)?.error(err)
+      );
+      return record;
+    })();
+    this.inflight.set(key, { promise, generator: gen.name, started: performance.now() });
+    try {
+      const record = await promise;
+      this.remember(record);
+      return { record, hit, deps: versions, codeHash };
+    } finally {
+      this.inflight.delete(key);
+    }
+  }
+  remember(record) {
+    if (this.memory.has(record.key)) return;
+    this.memory.set(record.key, record);
+    this.memoryBytes += record.bytes;
+    for (const [key, r] of this.memory) {
+      if (this.memoryBytes <= this.options.cacheSize || key === record.key) break;
+      this.memory.delete(key);
+      this.memoryBytes -= r.bytes;
+    }
+  }
+  storedPath(key) {
+    return `${this.options.cacheDir}/generated/${key.slice(0, 2)}/${key}`;
+  }
+  async readStored(key) {
+    const fs = this.options.fs;
+    try {
+      let record;
+      if (fs && await fs.exists(this.storedPath(key)))
+        record = decodeRecord(await fs.readBytes(this.storedPath(key)));
+      else {
+        const bytes = await this.options.storage?.read(`procgen/${key}`);
+        record = bytes ? decodeRecord(bytes) : void 0;
+      }
+      if (record) record.key = key;
+      return record;
+    } catch {
+      return void 0;
+    }
+  }
+  async writeStored(record, packed) {
+    const fs = this.options.fs;
+    if (fs?.writable) {
+      await fs.writeBytes(this.storedPath(record.key), packed ?? encodeRecord(record));
+      return;
+    }
+    const storage = this.options.storage;
+    if (!storage) return;
+    await storage.write(`procgen/${record.key}`, packed ?? encodeRecord(record));
+    this.stored.push({ key: record.key, bytes: record.bytes });
+    this.storedBytes += record.bytes;
+    while (this.storedBytes > this.options.cacheSize && this.stored.length > 1) {
+      const old = this.stored.shift();
+      this.storedBytes -= old.bytes;
+      await storage.delete(`procgen/${old.key}`);
+    }
+  }
+  // --- hot reload ------------------------------------------------------------------------------
+  regenerate(guid) {
+    const entry = this.server.entry(guid);
+    if (entry?.state !== "loaded") return;
+    this.server.updateVirtual(guid, entry.path, entry.type, () => this.produceLogged(guid), {
+      collectable: true
+    });
+  }
+  regenerateForDeps() {
+    const changed = this.pendingDeps;
+    if (changed.size === 0) return;
+    this.pendingDeps = /* @__PURE__ */ new Set();
+    for (const [guid, live] of this.live) {
+      if ([...live.deps.keys()].some((g) => changed.has(g))) this.regenerate(guid);
+    }
+  }
+  /**
+   * Regenerates loaded outputs whose generator's code hash changed (or whose generator was
+   * redefined) and those whose dependencies reloaded. They swap in place when ready; returns their
+   * paths.
+   */
+  regenerateStale() {
+    const out = [];
+    for (const [guid, live] of this.live) {
+      const entry = this.server.entry(guid);
+      if (entry?.state !== "loaded") continue;
+      let stale;
+      try {
+        stale = codeHashOf(requireGenerator(live.request.generator)) !== live.codeHash;
+      } catch {
+        continue;
+      }
+      for (const [dep, version] of live.deps) {
+        if (this.server.entry(dep)?.version !== version) stale = true;
+      }
+      if (!stale) continue;
+      this.regenerate(guid);
+      out.push(entry.path);
+    }
+    return out.sort();
+  }
+  /** Jobs running now, for procgen.describe. */
+  inFlight() {
+    const now = performance.now();
+    return [...this.inflight].map(([key, j]) => ({
+      generator: j.generator,
+      key,
+      ms: Math.round(now - j.started)
+    }));
+  }
+  cacheStats() {
+    return {
+      records: this.memory.size,
+      bytes: this.memoryBytes,
+      limit: this.options.cacheSize,
+      live: this.live.size
+    };
+  }
+}
+let parseRef = () => {
+  throw new ShardError("procgen/unknown-generator", "procedural refs are not set up");
+};
+function setRefParser(parse) {
+  parseRef = parse;
+  return parse;
+}
+const ProcgenResource = defineResource("procgen/Runtime", {
+  description: "Generator outputs of this world: caches, in-flight jobs, stats."
+});
+function procgen(world) {
+  let runtime = world.tryResource(ProcgenResource);
+  if (!runtime) {
+    runtime = new ProcgenRuntime(world);
+    world.insertResource(ProcgenResource, runtime);
+  }
+  return runtime;
+}
+function generate(world, gen, params = {}, seed = 0) {
+  return procgen(world).generate(gen, params, seed);
+}
+export {
+  DataAssetType,
+  GeneratedData,
+  GeneratorAssetType,
+  GeneratorBindings,
+  ProcgenResource,
+  ProcgenRuntime,
+  configureProcgenHost,
+  generate,
+  identityOf,
+  mainThreadTurn,
+  paramHandles,
+  procgen,
+  procgenHost,
+  procgenMainThreadMs,
+  runJob,
+  setRefParser,
+  warmGeneratorWorkers
+};

package/dist/schema.d.ts

@@ -0,0 +1,6 @@
+import type { JsonSchema } from '@aethervtt/shard-core';
+/**
+ * `.shard/schemas/gen.schema.json`: generator files, with `params` checked against the schema of
+ * the generator the file names (one branch per generator).
+ */
+export declare function genFileSchema(): JsonSchema;

package/dist/schema.js

@@ -0,0 +1,35 @@
+import { allGenerators } from "./generator.js";
+function genFileSchema() {
+  const gens = allGenerators();
+  const base = {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    title: "Shard generator file (*.gen.json)",
+    description: "A generator, a seed, and params. Imports as the generator output (a mesh, texture, data value, or prefab-shaped entities).",
+    type: "object",
+    required: ["generator"],
+    properties: {
+      $schema: { type: "string" },
+      generator: {
+        type: "string",
+        description: "The generator, by name.",
+        ...gens.length ? { enum: gens.map((g) => g.name) } : {}
+      },
+      seed: { type: "integer", minimum: 0, maximum: 4294967295, default: 0 },
+      params: { type: "object" }
+    },
+    additionalProperties: false
+  };
+  if (gens.length === 0) return base;
+  return {
+    ...base,
+    oneOf: gens.map((g) => ({
+      properties: {
+        generator: { const: g.name },
+        params: { ...g.params.jsonSchema(), description: g.description ?? `${g.name} params.` }
+      }
+    }))
+  };
+}
+export {
+  genFileSchema
+};

package/dist/sheet.d.ts

@@ -0,0 +1,7 @@
+import type { PreviewImage } from '@aethervtt/shard-protocol';
+/** Writes `text` at (x, y) in white on a dark box, each glyph pixel `scale` pixels wide. */
+export declare function drawLabel(image: PreviewImage, text: string, x: number, y: number, scale?: number): void;
+/** Lays images out in a grid (`columns` wide), each in a `cell`×`cell` slot, centred. */
+export declare function contactSheet(images: readonly PreviewImage[], labels: readonly string[], cell: number, columns?: number): PreviewImage;
+/** Parses `3`, `1-9`, or `1,4,9` into seeds. */
+export declare function parseSeeds(spec: string | readonly number[]): number[];

package/dist/sheet.js

@@ -0,0 +1,85 @@
+const GLYPHS = {
+  "0": [".###.", "#...#", "#..##", "#.#.#", "##..#", "#...#", ".###."],
+  "1": ["..#..", ".##..", "..#..", "..#..", "..#..", "..#..", ".###."],
+  "2": [".###.", "#...#", "....#", "...#.", "..#..", ".#...", "#####"],
+  "3": ["####.", "....#", "....#", ".###.", "....#", "....#", "####."],
+  "4": ["...#.", "..##.", ".#.#.", "#..#.", "#####", "...#.", "...#."],
+  "5": ["#####", "#....", "####.", "....#", "....#", "#...#", ".###."],
+  "6": ["..##.", ".#...", "#....", "####.", "#...#", "#...#", ".###."],
+  "7": ["#####", "....#", "...#.", "..#..", ".#...", ".#...", ".#..."],
+  "8": [".###.", "#...#", "#...#", ".###.", "#...#", "#...#", ".###."],
+  "9": [".###.", "#...#", "#...#", ".####", "....#", "...#.", ".##.."],
+  s: [".....", ".....", ".####", "#....", ".###.", "....#", "####."],
+  e: [".....", ".....", ".###.", "#...#", "#####", "#....", ".###."],
+  d: ["....#", "....#", ".##.#", "#..##", "#...#", "#...#", ".####"],
+  "-": [".....", ".....", ".....", "#####", ".....", ".....", "....."],
+  ".": [".....", ".....", ".....", ".....", ".....", ".##..", ".##.."],
+  " ": [".....", ".....", ".....", ".....", ".....", ".....", "....."]
+};
+function drawLabel(image, text, x, y, scale = 2) {
+  const glyphW = 6 * scale;
+  const w = text.length * glyphW + 2 * scale;
+  const h = 9 * scale;
+  const set = (px, py, v, a) => {
+    if (px < 0 || py < 0 || px >= image.width || py >= image.height) return;
+    const i = (py * image.width + px) * 4;
+    for (let c = 0; c < 3; c++) image.data[i + c] = Math.round(image.data[i + c] * (1 - a) + v * a);
+    image.data[i + 3] = 255;
+  };
+  for (let py = 0; py < h; py++) for (let px = 0; px < w; px++) set(x + px, y + py, 0, 0.6);
+  for (let k = 0; k < text.length; k++) {
+    const glyph = GLYPHS[text[k]] ?? GLYPHS[" "];
+    for (let row = 0; row < 7; row++) {
+      for (let col = 0; col < 5; col++) {
+        if (glyph[row][col] !== "#") continue;
+        for (let sy = 0; sy < scale; sy++)
+          for (let sx = 0; sx < scale; sx++)
+            set(x + scale + k * glyphW + col * scale + sx, y + scale + row * scale + sy, 255, 1);
+      }
+    }
+  }
+}
+function contactSheet(images, labels, cell, columns = Math.ceil(Math.sqrt(images.length))) {
+  const rows = Math.ceil(images.length / columns);
+  const gap = 2;
+  const width = columns * cell + (columns + 1) * gap;
+  const height = rows * cell + (rows + 1) * gap;
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0; i < data.length; i += 4) {
+    data[i] = 24;
+    data[i + 1] = 26;
+    data[i + 2] = 30;
+    data[i + 3] = 255;
+  }
+  const sheet = { width, height, data };
+  images.forEach((img, n) => {
+    const cx = gap + n % columns * (cell + gap);
+    const cy = gap + Math.floor(n / columns) * (cell + gap);
+    const ox = cx + (cell - img.width >> 1);
+    const oy = cy + (cell - img.height >> 1);
+    for (let y = 0; y < img.height; y++) {
+      const row = img.data.subarray(y * img.width * 4, (y + 1) * img.width * 4);
+      data.set(row, ((oy + y) * width + ox) * 4);
+    }
+    const label = labels[n];
+    if (label) drawLabel(sheet, label, cx + 4, cy + 4, cell >= 192 ? 2 : 1);
+  });
+  return sheet;
+}
+function parseSeeds(spec) {
+  if (Array.isArray(spec)) return spec.map((n) => n >>> 0);
+  const out = [];
+  for (const part of String(spec).split(",")) {
+    const m = /^\s*(\d+)\s*(?:-\s*(\d+))?\s*$/.exec(part);
+    if (!m) continue;
+    const a = Number(m[1]);
+    const b = m[2] === void 0 ? a : Number(m[2]);
+    for (let s = Math.min(a, b); s <= Math.max(a, b) && out.length < 64; s++) out.push(s);
+  }
+  return out;
+}
+export {
+  contactSheet,
+  drawLabel,
+  parseSeeds
+};

package/dist/worker.d.ts

@@ -0,0 +1,10 @@
+import { type GenJob } from './job.js';
+/**
+ * Runs one generator job with the clock and Math.random guarded for all of it. The result is one
+ * packed record (`encodeRecord`), so its bytes move back to the caller instead of being copied.
+ */
+export declare function runGeneratorJob(job: GenJob): Promise<{
+    packed: Uint8Array;
+}>;
+/** Nothing: loading this module (and the project's code) is the point. */
+export declare function warmUp(): true;