@aethervtt/shard-node 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-node
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/bundle.d.ts

@@ -0,0 +1,53 @@
+import { ShardError } from '@aethervtt/shard-core';
+import { type SourceMap } from '@aethervtt/shard-project';
+export interface BuiltBundle {
+    /** Content hash of the bundle. */
+    hash: string;
+    /** Absolute path of the written file. */
+    file: string;
+    /** `file://` URL, for `import()`. */
+    url: string;
+    code: string;
+    map: SourceMap | undefined;
+    ms: number;
+    /** Inputs and their imports (esbuild's metafile): generators' code hashes come from it. */
+    graph: {
+        inputs: Record<string, {
+            imports: {
+                path: string;
+                external?: boolean;
+            }[];
+        }>;
+    };
+}
+export interface BundlerOptions {
+    /** Project folder. */
+    root: string;
+    /** Entry module, project-relative (the manifest's `entry`). */
+    entry: string;
+    /** Where bundles are written. Default `.shard/build`. */
+    outDir?: string;
+}
+/**
+ * Bundles a project's entry into one ESM file with `@aethervtt/shard-*` left external, so the engine's module
+ * instances are shared. Keeps an incremental esbuild context for fast rebuilds.
+ */
+export declare function createBundler(options: BundlerOptions): Promise<{
+    root: string;
+    readonly last: BuiltBundle | undefined;
+    /**
+     * A URL for importing a bundle that no module cache has seen. Identical code rebuilds to the same
+     * file (content hash), and without this a revert would import a stale, earlier module instance.
+     */
+    importUrl(bundle: BuiltBundle): string;
+    build: () => Promise<BuiltBundle>;
+    /**
+     * Rebuilds (debounced) when anything under the entry's folder changes. `onBuild` gets the bundle
+     * or the error. Returns a stop function.
+     */
+    watch(onBuild: (result: BuiltBundle | ShardError) => void, debounceMs?: number): () => void;
+    /** Removes bundles other than the latest from the output folder. */
+    prune(): Promise<void>;
+    dispose: () => Promise<void>;
+}>;
+export type Bundler = Awaited<ReturnType<typeof createBundler>>;

package/dist/bundle.js

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto";
+import { watch as fsWatch } from "node:fs";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { builtinModules } from "node:module";
+import { dirname, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { ShardError } from "@aethervtt/shard-core";
+import { inlineSourceMap } from "@aethervtt/shard-project";
+import * as esbuild from "esbuild";
+const BUILTINS = new Set(builtinModules.flatMap((m) => [m, `node:${m}`]));
+const noNodeBuiltins = {
+  name: "shard-no-node-builtins",
+  setup(build) {
+    build.onResolve({ filter: /^[a-z:/_]+$/ }, (args) => {
+      if (!BUILTINS.has(args.path)) return void 0;
+      return {
+        errors: [
+          {
+            text: `"${args.path}" is a Node built-in; project code must run in browsers too`,
+            detail: "project/node-builtin"
+          }
+        ]
+      };
+    });
+  }
+};
+function bundleError(root, failure) {
+  const first = failure.errors?.[0];
+  if (!first) {
+    return new ShardError("project/bundle-failed", failure.message, { cause: failure });
+  }
+  const code = first.detail === "project/node-builtin" ? "project/node-builtin" : "project/bundle-failed";
+  const loc = first.location;
+  const file = loc ? relative(root, resolve(root, loc.file)).split("\\").join("/") : void 0;
+  const source = loc ? `${file}:${loc.line}:${loc.column + 1}` : void 0;
+  const err = new ShardError(code, source ? `${source}: ${first.text}` : first.text, {
+    path: file,
+    hint: code === "project/node-builtin" ? "Use @aethervtt/shard-platform services (files, storage) instead of Node APIs." : "Fix the error and save; the last good code keeps running.",
+    cause: failure
+  });
+  return Object.assign(err, { source });
+}
+async function createBundler(options) {
+  const root = resolve(options.root);
+  const outDir = resolve(root, options.outDir ?? ".shard/build");
+  let last;
+  const context = await esbuild.context({
+    absWorkingDir: root,
+    entryPoints: [resolve(root, options.entry)],
+    // Only names the output so source-map paths are relative to it; nothing is written by esbuild.
+    outfile: join(outDir, "main.mjs"),
+    bundle: true,
+    format: "esm",
+    platform: "browser",
+    target: "es2023",
+    sourcemap: "inline",
+    sourcesContent: false,
+    external: ["@aethervtt/shard-*"],
+    write: false,
+    metafile: true,
+    logLevel: "silent",
+    plugins: [noNodeBuiltins]
+  });
+  const build = async () => {
+    const start = performance.now();
+    let result;
+    try {
+      result = await context.rebuild();
+    } catch (err) {
+      throw bundleError(root, err);
+    }
+    const code = result.outputFiles[0].text;
+    const hash = createHash("sha256").update(code).digest("hex").slice(0, 16);
+    const file = join(outDir, `main.${hash}.mjs`);
+    if (last?.hash !== hash) {
+      await mkdir(outDir, { recursive: true });
+      await writeFile(file, code);
+    }
+    last = {
+      hash,
+      file,
+      url: pathToFileURL(file).href,
+      code,
+      map: inlineSourceMap(code),
+      ms: performance.now() - start,
+      graph: result.metafile
+    };
+    return last;
+  };
+  let imports = 0;
+  return {
+    root,
+    get last() {
+      return last;
+    },
+    /**
+     * A URL for importing a bundle that no module cache has seen. Identical code rebuilds to the same
+     * file (content hash), and without this a revert would import a stale, earlier module instance.
+     */
+    importUrl(bundle) {
+      return `${bundle.url}?r=${++imports}`;
+    },
+    build,
+    /**
+     * Rebuilds (debounced) when anything under the entry's folder changes. `onBuild` gets the bundle
+     * or the error. Returns a stop function.
+     */
+    watch(onBuild, debounceMs = 50) {
+      const dir = dirname(resolve(root, options.entry));
+      let timer;
+      const watcher = fsWatch(dir, { recursive: true }, () => {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => {
+          timer = void 0;
+          build().then(onBuild, (err) => onBuild(err));
+        }, debounceMs);
+      });
+      return () => {
+        if (timer) clearTimeout(timer);
+        watcher.close();
+      };
+    },
+    /** Removes bundles other than the latest from the output folder. */
+    async prune() {
+      const files = await readdir(outDir).catch(() => []);
+      await Promise.all(
+        files.filter(
+          (f) => f.startsWith("main.") && f.endsWith(".mjs") && join(outDir, f) !== last?.file
+        ).map((f) => rm(join(outDir, f), { force: true }))
+      );
+    },
+    dispose: () => context.dispose()
+  };
+}
+export {
+  createBundler
+};

package/dist/generators.d.ts

@@ -0,0 +1,53 @@
+import type { Workers } from '@aethervtt/shard-platform';
+/** What an esbuild metafile says about inputs: each file and what it imports. */
+export interface ModuleGraph {
+    inputs: Record<string, {
+        imports: readonly {
+            path: string;
+            external?: boolean;
+        }[];
+    }>;
+}
+/**
+ * Each generator's code hash: the hash of the module that defines it and every project module it
+ * imports (transitively), from the bundler's module graph. The entry and the module that calls
+ * `defineProject` are left out (with what only they import), so editing game systems there never
+ * regenerates outputs. Keys are generator names (`<namespace>/<Name>`).
+ */
+export declare function generatorCodeHashes(root: string, namespace: string, entry: string, graph: ModuleGraph): Promise<Record<string, string>>;
+/** The module graph of a project's code (engine packages external), without writing anything. */
+export declare function projectModuleGraph(root: string, entry: string): Promise<ModuleGraph>;
+export interface GeneratorWorkerBundle {
+    /** `file://` URL of the module, for `configureProcgenHost({ workerModule })`. */
+    url: string;
+    file: string;
+    hash: string;
+    ms: number;
+}
+/**
+ * Bundles the project's code with `@aethervtt/shard-procgen/worker` into one self-contained module (the
+ * engine inlined, so a worker thread loads it with no resolver or loader): what generator jobs run
+ * on the worker pool. Written to `.shard/build/procgen-worker.<hash>.mjs`.
+ */
+export declare function buildGeneratorWorker(options: {
+    root: string;
+    entry: string;
+    outDir?: string;
+}): Promise<GeneratorWorkerBundle>;
+export declare function prepareGenerators(options: {
+    root: string;
+    namespace: string;
+    entry: string;
+    workers?: Workers;
+    graph?: ModuleGraph;
+    /** Build the worker bundle (default true); false runs jobs inline. */
+    worker?: boolean;
+    /**
+     * Resolve once the code hashes are set, building the worker bundle behind (hot reloads): jobs
+     * wait for the new bundle, and `worker` in the result is a promise.
+     */
+    background?: boolean;
+}): Promise<{
+    codeHashes: Record<string, string>;
+    worker: GeneratorWorkerBundle | Promise<GeneratorWorkerBundle> | undefined;
+}>;

package/dist/generators.js

@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { ShardError } from "@aethervtt/shard-core";
+import { configureProcgenHost, setGeneratorCodeHashes } from "@aethervtt/shard-procgen";
+import * as esbuild from "esbuild";
+const PROJECT_GENERATOR = /\.generator\(\s*['"]([A-Za-z][A-Za-z0-9]*)['"]/g;
+const ENGINE_GENERATOR = /\bdefineGenerator\(\s*['"]([a-z][a-z0-9-]*\/[A-Za-z][A-Za-z0-9]*)['"]/g;
+async function generatorCodeHashes(root, namespace, entry, graph) {
+  const scriptsDir = relative(root, dirname(resolve(root, entry))).split("\\").join("/");
+  const own = (p) => !p.includes("node_modules/") && !p.startsWith("..") && (scriptsDir === "" || p.startsWith(`${scriptsDir}/`));
+  const files = Object.keys(graph.inputs).filter(own);
+  const text = /* @__PURE__ */ new Map();
+  await Promise.all(files.map(async (f) => text.set(f, await readFile(resolve(root, f), "utf8"))));
+  const entryPath = relative(root, resolve(root, entry)).split("\\").join("/");
+  const excluded = new Set(
+    files.filter((f) => f === entryPath || /\bdefineProject\s*\(/.test(text.get(f)))
+  );
+  const out = {};
+  for (const file of files) {
+    const source = text.get(file);
+    const names = [];
+    for (const m of source.matchAll(PROJECT_GENERATOR)) names.push(`${namespace}/${m[1]}`);
+    for (const m of source.matchAll(ENGINE_GENERATOR)) names.push(m[1]);
+    if (names.length === 0) continue;
+    const seen = /* @__PURE__ */ new Set([file]);
+    const stack = [file];
+    while (stack.length > 0) {
+      const at = stack.pop();
+      for (const imp of graph.inputs[at]?.imports ?? []) {
+        if (imp.external || !own(imp.path) || seen.has(imp.path) || excluded.has(imp.path)) continue;
+        seen.add(imp.path);
+        stack.push(imp.path);
+      }
+    }
+    const hash = createHash("sha256");
+    for (const f of [...seen].sort()) hash.update(`${f}
+${text.get(f)}
+`);
+    const digest = hash.digest("hex").slice(0, 16);
+    for (const name of names) out[name] = digest;
+  }
+  return out;
+}
+async function projectModuleGraph(root, entry) {
+  const result = await esbuild.build({
+    absWorkingDir: resolve(root),
+    entryPoints: [resolve(root, entry)],
+    bundle: true,
+    format: "esm",
+    platform: "browser",
+    external: ["@aethervtt/shard-*", "node:*"],
+    write: false,
+    metafile: true,
+    logLevel: "silent"
+  });
+  return result.metafile;
+}
+async function buildGeneratorWorker(options) {
+  const start = performance.now();
+  const root = resolve(options.root);
+  const require2 = createRequire(import.meta.url);
+  const worker = require2.resolve("@aethervtt/shard-procgen/worker");
+  const entry = resolve(root, options.entry);
+  let result;
+  try {
+    result = await esbuild.build({
+      absWorkingDir: root,
+      stdin: {
+        contents: `import ${JSON.stringify(entry)}
+export { runGeneratorJob, warmUp } from ${JSON.stringify(worker)}
+`,
+        resolveDir: root,
+        sourcefile: "procgen-worker.ts",
+        loader: "ts"
+      },
+      bundle: true,
+      format: "esm",
+      platform: "browser",
+      target: "es2023",
+      // Host-only fallbacks (reading .wasm files from disk) stay dynamic imports that never run here.
+      external: ["node:*"],
+      // Keep every engine module, ignoring `sideEffects: false`. A worker runs no plugins, so their
+      // `provides` can't keep definitions alive, and a job may load any asset type (a noise graph,
+      // a mesh, a data asset) whose definition registers on import.
+      ignoreAnnotations: true,
+      write: false,
+      logLevel: "silent"
+    });
+  } catch (err) {
+    const first = err.errors?.[0];
+    throw new ShardError(
+      "procgen/worker-bundle-failed",
+      `Couldn't bundle the generator worker: ${first?.text ?? err.message}`,
+      { hint: "The project code has to bundle for browsers (no Node built-ins).", cause: err }
+    );
+  }
+  const code = result.outputFiles[0].contents;
+  const hash = createHash("sha256").update(code).digest("hex").slice(0, 16);
+  const outDir = resolve(root, options.outDir ?? ".shard/build");
+  const file = join(outDir, `procgen-worker.${hash}.mjs`);
+  const exists = await access(file).then(
+    () => true,
+    () => false
+  );
+  if (!exists) {
+    await mkdir(outDir, { recursive: true });
+    await writeFile(file, code);
+  }
+  return { url: pathToFileURL(file).href, file, hash, ms: performance.now() - start };
+}
+let lastWorker;
+async function prepareGenerators(options) {
+  const graph = options.graph ?? await projectModuleGraph(options.root, options.entry);
+  const codeHashes = await generatorCodeHashes(
+    options.root,
+    options.namespace,
+    options.entry,
+    graph
+  );
+  setGeneratorCodeHashes(codeHashes);
+  let worker;
+  if (options.worker !== false && options.workers && options.workers.size > 0) {
+    const key = `${resolve(options.root)}
+${JSON.stringify(codeHashes)}`;
+    if (lastWorker?.key !== key) {
+      const previous = lastWorker?.building;
+      lastWorker = {
+        key,
+        building: (previous ?? Promise.resolve()).catch(() => {
+        }).then(() => buildGeneratorWorker({ root: options.root, entry: options.entry }))
+      };
+    }
+    const building = lastWorker.building;
+    const mine = lastWorker;
+    building.catch(() => {
+      if (lastWorker === mine) lastWorker = void 0;
+    });
+    if (options.background) {
+      worker = building;
+      const url = building.then((b) => b.url);
+      url.catch(() => {
+      });
+      configureProcgenHost({ workers: options.workers, workerModule: url });
+    } else {
+      worker = await building;
+      configureProcgenHost({ workers: options.workers, workerModule: worker.url });
+    }
+  } else {
+    configureProcgenHost({ workers: void 0, workerModule: void 0 });
+  }
+  return { codeHashes, worker };
+}
+export {
+  buildGeneratorWorker,
+  generatorCodeHashes,
+  prepareGenerators,
+  projectModuleGraph
+};

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+import { type AssetServer, type ScanReport } from '@aethervtt/shard-assets';
+import { type World } from '@aethervtt/shard-core';
+import type { GpuContext } from '@aethervtt/shard-gpu';
+import { type Platform } from '@aethervtt/shard-platform';
+import { type ErrorCode, type ManifestValue, ProjectSession } from '@aethervtt/shard-project';
+import { type ProtocolServer } from '@aethervtt/shard-protocol';
+import { OffscreenTarget } from '@aethervtt/shard-render';
+import { type App, type Plugin } from '@aethervtt/shard-runtime';
+import { type LoadedSceneHandle } from '@aethervtt/shard-scene';
+import { type Bundler } from './bundle.js';
+export { createNodePlatform } from '@aethervtt/shard-platform-node';
+export interface OpenProjectOptions {
+    /** Project folder (with shard.json). */
+    root: string;
+    /** Headless render size; defaults to the manifest's window. */
+    width?: number;
+    height?: number;
+    /** Load the manifest's start scene (default true). */
+    loadStartScene?: boolean;
+    /** Share a GPU context across projects (tests); otherwise one is created. */
+    gpu?: GpuContext;
+    /** Overrides the manifest's `seed`. */
+    seed?: number;
+    /** Hot reload assets and project code when files change (default false). */
+    watch?: boolean;
+    /**
+     * 'bundle' (default): esbuild bundles `entry` and hot reload works. 'source': imports `entry`
+     * directly (gameplay tests, where test files import the same modules).
+     */
+    code?: 'bundle' | 'source';
+    /**
+     * Run generator jobs on worker threads (default true): the project's code is bundled with the
+     * engine into `.shard/build/procgen-worker.<hash>.mjs`. False runs them inline.
+     */
+    generatorWorkers?: boolean;
+    /**
+     * Where saves and settings go. 'memory' (default): gone when the process exits, so runs, tests,
+     * and screenshots never depend on what an earlier session saved. 'files': `.shard/user` in the
+     * project, kept across sessions (`shard serve`, `shard mcp`).
+     */
+    userData?: 'memory' | 'files';
+}
+export interface HeadlessProject {
+    root: string;
+    manifest: ManifestValue;
+    platform: Platform;
+    app: App;
+    server: ProtocolServer;
+    gpu: GpuContext;
+    target: OffscreenTarget;
+    scene: LoadedSceneHandle | undefined;
+    assets: AssetServer;
+    /** What the startup scan imported, skipped, and failed. */
+    imports: ScanReport;
+    /** The project's code: reloads, status, errors. */
+    session: ProjectSession;
+    /** The bundler, in 'bundle' mode. */
+    bundler: Bundler | undefined;
+    close(): void;
+}
+/** Imports the project plugin (default export of `entry`). */
+export declare function importProjectPlugin(root: string, manifest: ManifestValue): Promise<Plugin>;
+/** Opens a project headless: manifest, project code, Dawn GPU, offscreen target, protocol server. */
+export declare function openProject(options: OpenProjectOptions): Promise<HeadlessProject>;
+/** The first stack frame in project source (not node_modules or .shard), as `path:line:col`. */
+export declare function locateInProject(error: unknown, root: string): string | undefined;
+/** Scene files under `scenes/`, as project-relative paths. */
+export declare function listScenes(root: string): Promise<string[]>;
+/**
+ * A stable hash of every entity's serializable components (and parents). Equal worlds hash equal,
+ * so determinism checks compare one string. `core/Derived` entities (rebuilt from other state, like
+ * terrain chunks) are left out, and entity ids are numbered by rank among the rest, so a run that
+ * spawns render-only chunks (a GPU) hashes like one that doesn't (headless).
+ */
+export declare function worldHash(world: World): string;
+/**
+ * Error codes the engine can raise, scanned from the engine packages' sources (with the hint written
+ * next to each). Feeds `.agents/errors.md`.
+ */
+export declare function collectErrorCodes(): Promise<ErrorCode[]>;
+export { type BuiltBundle, type Bundler, createBundler } from './bundle.js';
+export { buildGeneratorWorker, type GeneratorWorkerBundle, generatorCodeHashes, type ModuleGraph, prepareGenerators, projectModuleGraph, } from './generators.js';

package/dist/index.js

@@ -0,0 +1,331 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { assetServer } from "@aethervtt/shard-assets";
+import {
+  ChildOf,
+  Derived,
+  ShardError
+} from "@aethervtt/shard-core";
+import { createNodeGpuContext } from "@aethervtt/shard-gpu/node";
+import { createMemoryStorage } from "@aethervtt/shard-platform";
+import { createNodePlatform } from "@aethervtt/shard-platform-node";
+import { configureProcgenHost, procgenHost } from "@aethervtt/shard-procgen";
+import {
+  buildApp,
+  loadProject,
+  loadProjectNavCache,
+  loadProjectShaders,
+  loadProjectStrings,
+  locateInBundle,
+  ProjectSession
+} from "@aethervtt/shard-project";
+import { createProtocolServer } from "@aethervtt/shard-protocol";
+import { OffscreenTarget } from "@aethervtt/shard-render";
+import { LogResource } from "@aethervtt/shard-runtime";
+import { loadScene, whenSceneReady } from "@aethervtt/shard-scene";
+import { createBundler } from "./bundle.js";
+import { prepareGenerators } from "./generators.js";
+import { createNodePlatform as createNodePlatform2 } from "@aethervtt/shard-platform-node";
+async function importProjectPlugin(root, manifest) {
+  const file = resolve(root, manifest.entry);
+  let mod;
+  try {
+    mod = await import(pathToFileURL(file).href);
+  } catch (cause) {
+    throw new ShardError(
+      "project/entry-failed",
+      `Couldn't load ${manifest.entry}: ${cause.message}`,
+      {
+        path: manifest.entry,
+        hint: "The entry must be a module whose default export is defineProject({...}).",
+        cause
+      }
+    );
+  }
+  const plugin = mod.default;
+  if (!plugin || typeof plugin.build !== "function" || typeof plugin.name !== "string") {
+    throw new ShardError(
+      "project/entry-invalid",
+      `${manifest.entry} has no project plugin as its default export`,
+      {
+        path: manifest.entry,
+        hint: "End the file with `export default project`, where project = defineProject({...})."
+      }
+    );
+  }
+  return plugin;
+}
+async function openProject(options) {
+  const root = resolve(options.root);
+  const files = createNodePlatform({ root });
+  const platform = options.userData === "files" ? files : { ...files, storage: createMemoryStorage() };
+  const loaded = (await loadProject(platform)).manifest;
+  const manifest = options.seed === void 0 ? loaded : { ...loaded, seed: options.seed };
+  const code = options.code ?? "bundle";
+  let bundler;
+  let project;
+  if (code === "bundle") {
+    bundler = await createBundler({ root, entry: manifest.entry });
+    let built;
+    try {
+      built = await bundler.build();
+    } catch (err) {
+      await bundler.dispose();
+      throw err;
+    }
+    project = await importBundle(built, manifest);
+  } else {
+    project = await importProjectPlugin(root, manifest);
+  }
+  const generators = {
+    root,
+    namespace: manifest.name,
+    entry: manifest.entry,
+    workers: platform.workers,
+    worker: options.generatorWorkers ?? true
+  };
+  await prepareGenerators({ ...generators, graph: bundler?.last?.graph });
+  const ownGpu = !options.gpu;
+  const gpu = options.gpu ?? await createNodeGpuContext({ features: ["timestamp-query"] });
+  const target = new OffscreenTarget(gpu, {
+    label: "headless",
+    width: options.width ?? manifest.window.width,
+    height: options.height ?? manifest.window.height
+  });
+  const app = buildApp({ manifest, project, gpu, target, platform });
+  await app.init();
+  await loadProjectNavCache(app, platform);
+  const stopShaders = await loadProjectShaders(app, platform, { watch: options.watch });
+  const assets = assetServer(app.world).configure({ platform, roots: manifest.assetRoots });
+  const imports = await assets.scan();
+  await loadProjectStrings(app);
+  const stopWatching = options.watch ? await assets.watch() : () => {
+  };
+  let scene;
+  if (options.loadStartScene ?? true) {
+    const json = JSON.parse(await platform.fs.readText(manifest.startScene));
+    scene = loadScene(app.world, json, { id: manifest.startScene });
+    await whenSceneReady(app.world, manifest.startScene);
+  }
+  const log = app.world.resource(LogResource);
+  log.annotate = (err) => {
+    const last = bundler?.last;
+    for (let e = err, depth = 0; e && depth < 5; e = e.cause, depth++) {
+      const mapped = last?.map && locateInBundle(
+        e,
+        last.url,
+        last.map,
+        (s) => relative(root, resolve(dirname(last.file), s)).split("\\").join("/")
+      );
+      const source = mapped || locateInProject(e, root);
+      if (source) return { source };
+    }
+    return void 0;
+  };
+  const session = new ProjectSession(app, {
+    namespace: manifest.name,
+    current: project,
+    ...bundler?.last ? { bundle: { hash: bundler.last.hash, ms: bundler.last.ms } } : {}
+  });
+  if (bundler) {
+    const b = bundler;
+    session.rebuild = async () => {
+      const built = await b.build();
+      await prepareGenerators({ ...generators, graph: built.graph, background: true });
+      return { load: () => import(b.importUrl(built)), hash: built.hash, ms: built.ms };
+    };
+  }
+  const server = createProtocolServer(app, {
+    frames: "manual",
+    platform,
+    methods: session.methods()
+  });
+  session.onChange((status) => server.publish("project", status));
+  let stopCode = () => {
+  };
+  if (options.watch && bundler) {
+    session.watching = true;
+    stopCode = bundler.watch((result) => {
+      if (result instanceof Error) session.buildFailed(result);
+      else
+        void prepareGenerators({ ...generators, graph: result.graph, background: true }).then(
+          () => session.reload(() => import(bundler.importUrl(result)), {
+            hash: result.hash,
+            ms: result.ms
+          })
+        ).catch((err) => session.buildFailed(err));
+    });
+  }
+  return {
+    root,
+    manifest,
+    platform,
+    app,
+    server,
+    gpu,
+    target,
+    scene,
+    assets,
+    imports,
+    session,
+    bundler,
+    close() {
+      stopWatching();
+      stopShaders();
+      stopCode();
+      void bundler?.dispose();
+      server.close();
+      target.destroy();
+      if (ownGpu) gpu.destroy();
+      if (procgenHost().workers === platform.workers)
+        configureProcgenHost({ workers: void 0, workerModule: void 0 });
+      platform.workers?.dispose();
+    }
+  };
+}
+async function importBundle(built, manifest) {
+  let mod;
+  try {
+    mod = await import(built.url);
+  } catch (cause) {
+    const source = built.map ? locateInBundle(cause, built.url, built.map) : void 0;
+    throw Object.assign(
+      new ShardError(
+        "project/entry-failed",
+        `Couldn't start ${manifest.entry}: ${cause.message}`,
+        {
+          path: manifest.entry,
+          hint: 'The error is in the project code; see "source" for where.',
+          cause
+        }
+      ),
+      { source }
+    );
+  }
+  const plugin = mod.default;
+  if (!plugin || typeof plugin.build !== "function" || typeof plugin.name !== "string") {
+    throw new ShardError(
+      "project/entry-invalid",
+      `${manifest.entry} has no project plugin as its default export`,
+      {
+        path: manifest.entry,
+        hint: "End the file with `export default project`, where project = defineProject({...})."
+      }
+    );
+  }
+  return plugin;
+}
+function locateInProject(error, root) {
+  const stack = error?.stack;
+  if (typeof stack !== "string") return void 0;
+  const prefix = resolve(root);
+  for (const line of stack.split("\n")) {
+    const m = /(?:file:\/\/)?(\/[^\s():]+):(\d+):(\d+)/.exec(line);
+    if (!m) continue;
+    const file = decodeURIComponent(m[1]);
+    if (!file.startsWith(`${prefix}/`)) continue;
+    const rel = relative(prefix, file).split("\\").join("/");
+    if (rel.startsWith(".shard/") || rel.includes("node_modules/")) continue;
+    return `${rel}:${m[2]}:${m[3]}`;
+  }
+  return void 0;
+}
+async function listScenes(root) {
+  const dir = join(resolve(root), "scenes");
+  const entries = await readdir(dir, { recursive: true }).catch(() => []);
+  return entries.filter((f) => f.endsWith(".scene.json")).map((f) => relative(resolve(root), join(dir, f)).split("\\").join("/")).sort();
+}
+function worldHash(world) {
+  const kept = [];
+  for (const table of world.allTables()) {
+    if (table.has(Derived)) continue;
+    for (let row = 0; row < table.count; row++) kept.push(table.entities[row]);
+  }
+  kept.sort((a, b) => a - b);
+  const rank = /* @__PURE__ */ new Map();
+  for (let i = 0; i < kept.length; i++) rank.set(kept[i], i);
+  const id = (e) => typeof e === "number" && e >= 0 ? rank.get(e) ?? -1 : e;
+  const remap = (field, value) => {
+    if (value === null || value === void 0) return value;
+    if (field.kind === "entity") return id(value);
+    if (field.kind === "list" && field.item && Array.isArray(value))
+      return value.map((v) => remap(field.item, v));
+    if (field.kind === "struct" && field.fields && typeof value === "object")
+      return remapFields(field.fields, value);
+    return value;
+  };
+  const remapFields = (fields, value) => {
+    const out = { ...value };
+    for (const key in fields) if (key in out) out[key] = remap(fields[key], out[key]);
+    return out;
+  };
+  const rows = [];
+  for (const table of world.allTables()) {
+    if (table.has(Derived)) continue;
+    const components = table.components.filter((c) => c.serializable || c === ChildOf);
+    for (let row = 0; row < table.count; row++) {
+      const entity = table.entities[row];
+      const values = components.map((c) => [
+        c.name,
+        remapFields(c.fields, c.serialize(table.readComponent(c, row)))
+      ]);
+      rows.push(JSON.stringify([rank.get(entity), values]));
+    }
+  }
+  return createHash("sha256").update(rows.sort().join("\n")).digest("hex");
+}
+async function collectErrorCodes() {
+  const require2 = createRequire(import.meta.url);
+  const packagesDir = dirname(dirname(dirname(require2.resolve("@aethervtt/shard-core"))));
+  const found = /* @__PURE__ */ new Map();
+  const pkgs = await readdir(packagesDir).catch(() => []);
+  for (const pkg of pkgs) {
+    const src = join(packagesDir, pkg, "src");
+    const files = await readdir(src, { recursive: true }).catch(() => []);
+    for (const file of files) {
+      if (!file.endsWith(".ts") || file.endsWith(".test.ts")) continue;
+      const text = await readFile(join(src, file), "utf8");
+      const re = /new ShardError\(\s*['"]([a-z0-9-]+\/[a-z0-9-]+)['"]/g;
+      for (let m = re.exec(text); m; m = re.exec(text)) {
+        const code = m[1];
+        const window = text.slice(m.index, m.index + 700);
+        const next = window.indexOf("new ShardError", 10);
+        const hint = /hint:\s*(['"`])((?:(?!\1).)+)\1/.exec(
+          next === -1 ? window : window.slice(0, next)
+        )?.[2];
+        if (!found.has(code) || !found.get(code).hint && hint) {
+          found.set(code, {
+            code,
+            source: `@aethervtt/shard-${pkg}`,
+            ...hint && !hint.includes("${") ? { hint } : {}
+          });
+        }
+      }
+    }
+  }
+  return [...found.values()];
+}
+import { createBundler as createBundler2 } from "./bundle.js";
+import {
+  buildGeneratorWorker,
+  generatorCodeHashes,
+  prepareGenerators as prepareGenerators2,
+  projectModuleGraph
+} from "./generators.js";
+export {
+  buildGeneratorWorker,
+  collectErrorCodes,
+  createBundler2 as createBundler,
+  createNodePlatform2 as createNodePlatform,
+  generatorCodeHashes,
+  importProjectPlugin,
+  listScenes,
+  locateInProject,
+  openProject,
+  prepareGenerators2 as prepareGenerators,
+  projectModuleGraph,
+  worldHash
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@aethervtt/shard-node",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aethervtt/shard-assets": "0.0.1",
+    "@aethervtt/shard-core": "0.0.1",
+    "@aethervtt/shard-gpu": "0.0.1",
+    "@aethervtt/shard-platform": "0.0.1",
+    "@aethervtt/shard-platform-node": "0.0.1",
+    "@aethervtt/shard-procgen": "0.0.1",
+    "@aethervtt/shard-project": "0.0.1",
+    "@aethervtt/shard-protocol": "0.0.1",
+    "@aethervtt/shard-render": "0.0.1",
+    "@aethervtt/shard-runtime": "0.0.1",
+    "@aethervtt/shard-scene": "0.0.1",
+    "esbuild": "^0.28.2",
+    "webgpu": "0.6.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/node"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+  }
+}