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

package/dist/hooks.d.ts

@@ -0,0 +1,10 @@
+export interface HookSignature {
+    params: string;
+    returns: string;
+}
+export declare function findHooks(source: string): Map<string, HookSignature>;
+/**
+ * Applies hooks and overrides to module sources (keyed by module path like `shard::pbr::material`).
+ * Returns new sources; inputs are not modified.
+ */
+export declare function applyHooks(sources: ReadonlyMap<string, string>, overrides: readonly string[]): Map<string, string>;

package/dist/hooks.js

@@ -0,0 +1,132 @@
+import { ShardError } from "@aethervtt/shard-core";
+const HOOK = /@hook\s+fn\s+([A-Za-z_]\w*)\s*\(([^)]*)\)\s*(?:->\s*([^{]+?))?\s*\{/g;
+const OVERRIDE = /override\s+fn\s+((?:[A-Za-z_]\w*::)*)([A-Za-z_]\w*)\s*\(([^)]*)\)\s*(?:->\s*([^{]+?))?\s*\{/g;
+const normalize = (s) => (s ?? "").replace(/\s+/g, " ").replace(/\s*([,:<>()])\s*/g, "$1").trim();
+function findHooks(source) {
+  const hooks = /* @__PURE__ */ new Map();
+  for (const m of source.matchAll(HOOK)) hooks.set(m[1], { params: m[2], returns: m[3] ?? "" });
+  return hooks;
+}
+function paramNames(params) {
+  const names = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of params) {
+    if (ch === "<" || ch === "(") depth++;
+    if (ch === ">" || ch === ")") depth--;
+    if (ch === "," && depth === 0) {
+      names.push(current);
+      current = "";
+    } else current += ch;
+  }
+  if (current.trim()) names.push(current);
+  return names.map(
+    (p) => p.replace(/@\w+(\([^)]*\))?/g, "").split(":")[0].trim()
+  ).filter(Boolean);
+}
+function insertAfterImports(source, lines) {
+  const importRe = /^\s*import\s[^;]*;/gm;
+  let end = 0;
+  for (const m of source.matchAll(importRe)) end = m.index + m[0].length;
+  return `${source.slice(0, end)}
+${lines}
+${source.slice(end)}`;
+}
+function applyHooks(sources, overrides) {
+  const out = new Map(sources);
+  const hooksByModule = /* @__PURE__ */ new Map();
+  for (const [path, source] of sources) {
+    const hooks = findHooks(source);
+    if (hooks.size > 0) hooksByModule.set(path, hooks);
+  }
+  const winners = /* @__PURE__ */ new Map();
+  overrides.forEach((overrideModule, index) => {
+    const source = out.get(overrideModule);
+    if (source === void 0) {
+      throw new ShardError(
+        "shader/link-unknown-module",
+        `Override module "${overrideModule}" is not registered`
+      );
+    }
+    let rewritten = source;
+    for (const m of source.matchAll(OVERRIDE)) {
+      const name = m[2];
+      let target = m[1].slice(0, -2);
+      if (!target) {
+        const owners = [...hooksByModule].filter(([, hooks]) => hooks.has(name)).map(([p]) => p);
+        if (owners.length !== 1) {
+          throw new ShardError(
+            owners.length === 0 ? "shader/unknown-hook" : "shader/ambiguous-hook",
+            owners.length === 0 ? `"${name}" is not a hook` : `"${name}" is a hook in ${owners.join(" and ")}`,
+            {
+              path: overrideModule,
+              hint: owners.length === 0 ? "Only functions marked @hook can be overridden." : `Qualify it: override fn ${owners[0]}::${name}(...).`
+            }
+          );
+        }
+        target = owners[0];
+      }
+      const hook = hooksByModule.get(target)?.get(name);
+      if (!hook) {
+        throw new ShardError("shader/unknown-hook", `"${target}::${name}" is not a hook`, {
+          path: overrideModule,
+          hint: "Only functions marked @hook can be overridden."
+        });
+      }
+      if (normalize(hook.params) !== normalize(m[3]) || normalize(hook.returns) !== normalize(m[4])) {
+        throw new ShardError(
+          "shader/hook-signature-mismatch",
+          `Override of ${target}::${name} in ${overrideModule} has a different signature`,
+          {
+            path: overrideModule,
+            hint: `Expected fn ${name}(${hook.params.trim()})${hook.returns ? ` -> ${hook.returns.trim()}` : ""}.`
+          }
+        );
+      }
+      const fn = `${name}__override_${index}`;
+      rewritten = rewritten.replace(m[0], `fn ${fn}(${m[3]})${m[4] ? ` -> ${m[4].trim()}` : ""} {`);
+      const importPattern = new RegExp(
+        `(import\\s+${target.replace(/::/g, "::")}::[^;]*?\\b)${name}\\b`,
+        "g"
+      );
+      rewritten = rewritten.replace(importPattern, `$1${name}__default`);
+      winners.set(`${target}::${name}`, {
+        module: overrideModule,
+        fn,
+        params: m[3],
+        returns: m[4] ?? ""
+      });
+    }
+    out.set(overrideModule, rewritten);
+  });
+  for (const [path, hooks] of hooksByModule) {
+    let source = out.get(path);
+    const imports = [];
+    const dispatchers = [];
+    for (const [name, sig] of hooks) {
+      const winner = winners.get(`${path}::${name}`);
+      const header = new RegExp(`@hook\\s+fn\\s+${name}\\s*\\(`);
+      if (!winner) {
+        source = source.replace(header, `fn ${name}(`);
+        continue;
+      }
+      source = source.replace(header, `fn ${name}__default(`);
+      imports.push(`import ${winner.module}::${winner.fn};`);
+      const ret = sig.returns.trim();
+      const call = `${winner.fn}(${paramNames(sig.params).join(", ")})`;
+      dispatchers.push(
+        `fn ${name}(${sig.params})${ret ? ` -> ${ret}` : ""} { ${ret ? "return " : ""}${call}; }`
+      );
+    }
+    if (imports.length > 0)
+      source = `${insertAfterImports(source, imports.join("\n"))}
+${dispatchers.join("\n")}
+`;
+    out.set(path, source);
+  }
+  return out;
+}
+export {
+  applyHooks,
+  findHooks
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { applyHooks, findHooks, type HookSignature } from './hooks.js';
+export { type WgslLayout, wgslLayout } from './layout.js';
+export { type BakedShader, type LinkedShader, type LinkRequest, type ShaderBake, ShaderLibrary, type SourceLocation, } from './library.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+import { applyHooks, findHooks } from "./hooks.js";
+import { wgslLayout } from "./layout.js";
+import {
+  ShaderLibrary
+} from "./library.js";
+export {
+  ShaderLibrary,
+  applyHooks,
+  findHooks,
+  wgslLayout
+};

package/dist/layout.d.ts

@@ -0,0 +1,26 @@
+import { type ComponentDef, type FieldKind, type Fields, type InferFields } from '@aethervtt/shard-core';
+interface FieldLayout {
+    name: string;
+    kind: FieldKind;
+    wgslType: string;
+    offset: number;
+    size: number;
+    align: number;
+}
+export interface WgslLayout<F extends Fields> {
+    /** WGSL struct declaration, e.g. `struct ToonParams { bands: u32, rim: vec4f, width: f32, }`. */
+    readonly wgsl: string;
+    readonly structName: string;
+    /** Size in bytes, rounded up to the struct's alignment (what a uniform/storage binding needs). */
+    readonly size: number;
+    readonly align: number;
+    readonly fields: readonly FieldLayout[];
+    /** Writes a value at a byte offset using WGSL's layout rules. */
+    write(view: DataView, offset: number, value: InferFields<F>): void;
+}
+/**
+ * WGSL struct and byte packer generated from a component schema, so the CPU value, the GPU struct,
+ * and the byte layout come from one definition and can't drift apart.
+ */
+export declare function wgslLayout<F extends Fields>(def: ComponentDef<F>): WgslLayout<F>;
+export {};

package/dist/layout.js

@@ -0,0 +1,105 @@
+import {
+  ShardError
+} from "@aethervtt/shard-core";
+const TYPES = {
+  f32: { type: "f32", size: 4, align: 4 },
+  i8: { type: "i32", size: 4, align: 4 },
+  i16: { type: "i32", size: 4, align: 4 },
+  i32: { type: "i32", size: 4, align: 4 },
+  u8: { type: "u32", size: 4, align: 4 },
+  u16: { type: "u32", size: 4, align: 4 },
+  u32: { type: "u32", size: 4, align: 4 },
+  bool: { type: "u32", size: 4, align: 4 },
+  enum: { type: "u32", size: 4, align: 4 },
+  vec2: { type: "vec2f", size: 8, align: 8 },
+  vec3: { type: "vec3f", size: 12, align: 16 },
+  vec4: { type: "vec4f", size: 16, align: 16 },
+  quat: { type: "vec4f", size: 16, align: 16 },
+  color: { type: "vec4f", size: 16, align: 16 },
+  mat3: { type: "mat3x3f", size: 48, align: 16 },
+  mat4: { type: "mat4x4f", size: 64, align: 16 },
+  affine3x4: { type: "array<vec4f, 3>", size: 48, align: 16 }
+};
+const alignTo = (n, a) => Math.ceil(n / a) * a;
+function wgslLayout(def) {
+  const structName = def.name.split("/").pop();
+  const fields = [];
+  let offset = 0;
+  let structAlign = 4;
+  for (const { name, field, storage } of def.layout) {
+    if (storage === "object") continue;
+    const t = TYPES[field.kind];
+    if (!t) {
+      throw new ShardError(
+        "shader/unsupported-field",
+        `Field "${name}" of ${def.name} (${field.kind}) can't be a GPU struct member`,
+        {
+          hint: "GPU structs take numbers, bools, enums, vectors, colors, and matrices. f64 fields are not allowed; object fields are skipped."
+        }
+      );
+    }
+    offset = alignTo(offset, t.align);
+    fields.push({ name, kind: field.kind, wgslType: t.type, offset, size: t.size, align: t.align });
+    offset += t.size;
+    structAlign = Math.max(structAlign, t.align);
+  }
+  const size = alignTo(Math.max(offset, 4), structAlign);
+  const wgsl = `struct ${structName} {
+${fields.map((f) => `  ${f.name}: ${f.wgslType},`).join("\n")}
+}`;
+  const enumValues = /* @__PURE__ */ new Map();
+  for (const { name, field } of def.layout) {
+    if (field.kind === "enum") {
+      enumValues.set(name, field.jsonSchema().enum);
+    }
+  }
+  return {
+    wgsl,
+    structName,
+    size,
+    align: structAlign,
+    fields,
+    write(view, base, value) {
+      const record = value;
+      for (const f of fields) {
+        const o = base + f.offset;
+        const v = record[f.name];
+        switch (f.kind) {
+          case "f32":
+            view.setFloat32(o, v, true);
+            break;
+          case "i8":
+          case "i16":
+          case "i32":
+            view.setInt32(o, v, true);
+            break;
+          case "u8":
+          case "u16":
+          case "u32":
+            view.setUint32(o, v, true);
+            break;
+          case "bool":
+            view.setUint32(o, v ? 1 : 0, true);
+            break;
+          case "enum":
+            view.setUint32(o, Math.max(0, enumValues.get(f.name).indexOf(v)), true);
+            break;
+          case "mat3": {
+            const m = v;
+            for (let c = 0; c < 3; c++) {
+              for (let r = 0; r < 3; r++) view.setFloat32(o + c * 16 + r * 4, m[c * 3 + r], true);
+            }
+            break;
+          }
+          default: {
+            const arr = v;
+            for (let i = 0; i < arr.length; i++) view.setFloat32(o + i * 4, arr[i], true);
+          }
+        }
+      }
+    }
+  };
+}
+export {
+  wgslLayout
+};

package/dist/library.d.ts

@@ -0,0 +1,111 @@
+import type { GpuContext } from '@aethervtt/shard-gpu';
+import type { Platform } from '@aethervtt/shard-platform';
+export interface LinkRequest {
+    /** Module with the entry points, e.g. `shard::pbr::main` or `project::water`. */
+    root: string;
+    /** Conditions for `@if(...)`. */
+    defines?: Readonly<Record<string, boolean>>;
+    /** Override modules, in order; the last one wins per hook. */
+    overrides?: readonly string[];
+    /** Names what the variant is for in errors, e.g. `material my-game/Lava`. */
+    label?: string;
+}
+export interface SourceLocation {
+    module: string;
+    line: number;
+    column: number;
+}
+export interface LinkedShader {
+    key: string;
+    code: string;
+    /** Maps a character offset in `code` back to the module that produced it. */
+    locate(offset: number): SourceLocation | undefined;
+}
+/** One linked variant, for `ShaderLibrary.preload`. */
+export interface BakedShader {
+    /** The variant: root module, defines, overrides. */
+    key: string;
+    /** Of every module the variant links; a changed module makes the entry stale. */
+    hash: string;
+    code: string;
+}
+/** Linked variants saved from a run (`ShaderLibrary.bake()`), loaded with `preload`. */
+export interface ShaderBake {
+    version: 1;
+    shaders: BakedShader[];
+}
+/**
+ * Shader modules by path (`package::dir::file`), linked on demand with WESL. Engine shaders live
+ * under `shard::`, plugins under their own package, a project's `shaders/` folder under `project::`.
+ */
+export declare class ShaderLibrary {
+    private readonly sources;
+    /** Where each module came from, for error messages (a file path, or the module path). */
+    private readonly origins;
+    private readonly linkCache;
+    private readonly variants;
+    private readonly listeners;
+    private version;
+    private readonly preloaded;
+    /** Every variant linked or served from the bake, for `bake()`. */
+    private readonly used;
+    /** How many variants the bake didn't cover and WESL linked. */
+    linked: number;
+    /**
+     * Serves these variants without linking, as long as the modules they came from haven't changed.
+     * A stale or missing variant is linked as usual (loading WESL if it hasn't loaded yet).
+     */
+    preload(bake: ShaderBake): void;
+    /**
+     * The variants this library has used so far, to save and `preload` next time. Bake after a run
+     * that draws everything the app draws: a variant that wasn't used isn't in it.
+     */
+    bake(): ShaderBake;
+    /** Adds or replaces a module. `origin` is shown in errors (e.g. `shaders/toon.wesl`). */
+    register(path: string, source: string, origin?: string): void;
+    private rebuildScheduled;
+    /**
+     * After a change, rebuilds every variant already in use at once (in a microtask, so a batch of
+     * registrations rebuilds once), instead of waiting for its next `module()` call: an edited
+     * shader has usually compiled by the frame that draws it.
+     */
+    private scheduleRebuild;
+    has(path: string): boolean;
+    /** Called with the changed module paths whenever a module is registered or replaced. */
+    onChange(listener: (paths: readonly string[]) => void): () => void;
+    /**
+     * Reloads modules from files when they change. `dir` maps to `pkg`: with `('shaders', 'project')`,
+     * `shaders/water/foam.wesl` is `project::water::foam`.
+     */
+    watch(platform: Platform, dir: string, pkg: string): Promise<() => void>;
+    /**
+     * Registers every `.wesl`/`.wgsl` file under `dir` (recursively) as `pkg::path::name`. Hosts load a
+     * project's `shaders/` folder with it, then `watch` for edits.
+     */
+    loadDir(platform: Platform, dir: string, pkg: string): Promise<string[]>;
+    /** Links a variant. Results are cached until any module changes. */
+    link(request: LinkRequest): Promise<LinkedShader>;
+    /**
+     * A compiled shader module for a variant, or undefined while the first version compiles. After an
+     * edit, keeps returning the previous module until the new code compiles cleanly; if it doesn't,
+     * the error is reported through the GPU context and the old module stays in use.
+     */
+    module(gpu: GpuContext, request: LinkRequest): GPUShaderModule | undefined;
+    private rebuild;
+    /** Waits until every variant requested through `module()` has finished compiling. */
+    whenIdle(): Promise<void>;
+    /** Module graph and hooks, for agents. */
+    describe(root?: string): {
+        modules: string[];
+        imports: {
+            [k: string]: string[];
+        };
+        hooks: {
+            [k: string]: readonly string[];
+        };
+        defines: string[];
+    };
+    /** Of the source of every module a variant links: its root's imports, and the overrides'. */
+    private hashOf;
+    private doLink;
+}

package/dist/library.js

@@ -0,0 +1,413 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { applyHooks, findHooks } from "./hooks.js";
+let wesl;
+const loadWesl = () => {
+  wesl ??= import("wesl");
+  return wesl;
+};
+const PATH = /^[a-z_][a-z0-9_]*(::[a-z_][a-z0-9_]*)+$/;
+function splitPath(path) {
+  const [pkg, ...rest] = path.split("::");
+  return { pkg, file: `./${rest.join("/")}.wesl` };
+}
+function lineColumn(text, offset) {
+  let line = 1;
+  let lineStart = 0;
+  for (let i = 0; i < offset && i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) {
+      line++;
+      lineStart = i + 1;
+    }
+  }
+  return { line, column: offset - lineStart + 1 };
+}
+class ShaderLibrary {
+  sources = /* @__PURE__ */ new Map();
+  /** Where each module came from, for error messages (a file path, or the module path). */
+  origins = /* @__PURE__ */ new Map();
+  linkCache = /* @__PURE__ */ new Map();
+  variants = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  version = 0;
+  preloaded = /* @__PURE__ */ new Map();
+  /** Every variant linked or served from the bake, for `bake()`. */
+  used = /* @__PURE__ */ new Map();
+  /** How many variants the bake didn't cover and WESL linked. */
+  linked = 0;
+  /**
+   * Serves these variants without linking, as long as the modules they came from haven't changed.
+   * A stale or missing variant is linked as usual (loading WESL if it hasn't loaded yet).
+   */
+  preload(bake) {
+    if (bake.version !== 1) {
+      throw new ShardError("shader/bake-version", `Unknown shader bake version ${bake.version}`, {
+        hint: "Bake again with this version of Shard."
+      });
+    }
+    for (const entry of bake.shaders) this.preloaded.set(entry.key, entry);
+    this.linkCache.clear();
+  }
+  /**
+   * The variants this library has used so far, to save and `preload` next time. Bake after a run
+   * that draws everything the app draws: a variant that wasn't used isn't in it.
+   */
+  bake() {
+    const shaders = [...this.used.values()].sort((a, b) => a.key < b.key ? -1 : 1);
+    return { version: 1, shaders };
+  }
+  /** Adds or replaces a module. `origin` is shown in errors (e.g. `shaders/toon.wesl`). */
+  register(path, source, origin) {
+    if (!PATH.test(path)) {
+      throw new ShardError("shader/invalid-path", `Invalid shader module path "${path}"`, {
+        hint: "Use lowercase `package::dir::name`, e.g. `project::water`."
+      });
+    }
+    if (this.sources.get(path) === source) return;
+    this.sources.set(path, source);
+    this.origins.set(path, origin ?? path);
+    this.version++;
+    this.linkCache.clear();
+    for (const listener of this.listeners) listener([path]);
+    this.scheduleRebuild();
+  }
+  rebuildScheduled = false;
+  /**
+   * After a change, rebuilds every variant already in use at once (in a microtask, so a batch of
+   * registrations rebuilds once), instead of waiting for its next `module()` call: an edited
+   * shader has usually compiled by the frame that draws it.
+   */
+  scheduleRebuild() {
+    if (this.rebuildScheduled || this.variants.size === 0) return;
+    this.rebuildScheduled = true;
+    queueMicrotask(() => {
+      this.rebuildScheduled = false;
+      for (const s of this.variants.values()) {
+        if (s.gpu && s.request && s.version !== this.version && s.pending === void 0) {
+          this.rebuild(s.gpu, s.request, s);
+        }
+      }
+    });
+  }
+  has(path) {
+    return this.sources.has(path);
+  }
+  /** Called with the changed module paths whenever a module is registered or replaced. */
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /**
+   * Reloads modules from files when they change. `dir` maps to `pkg`: with `('shaders', 'project')`,
+   * `shaders/water/foam.wesl` is `project::water::foam`.
+   */
+  async watch(platform, dir, pkg) {
+    if (!platform.fs.watch) {
+      throw new ShardError(
+        "shader/watch-unsupported",
+        `The ${platform.name} platform can't watch files`
+      );
+    }
+    const prefix = dir.replace(/\/+$/, "");
+    return platform.fs.watch(prefix, (event) => {
+      if (event.kind === "remove" || !/\.(wesl|wgsl)$/.test(event.path)) return;
+      const rel = event.path.startsWith(`${prefix}/`) ? event.path.slice(prefix.length + 1) : event.path;
+      const path = `${pkg}::${rel.replace(/\.(wesl|wgsl)$/, "").split("/").join("::")}`;
+      void platform.fs.readText(event.path).then((text) => this.register(path, text, event.path));
+    });
+  }
+  /**
+   * Registers every `.wesl`/`.wgsl` file under `dir` (recursively) as `pkg::path::name`. Hosts load a
+   * project's `shaders/` folder with it, then `watch` for edits.
+   */
+  async loadDir(platform, dir, pkg) {
+    const list = platform.fs.list;
+    if (!list) return [];
+    const loaded = [];
+    const prefix = dir.replace(/\/+$/, "");
+    const walk = async (rel) => {
+      for (const entry of await list.call(platform.fs, rel ? `${prefix}/${rel}` : prefix)) {
+        const path = rel ? `${rel}/${entry.name}` : entry.name;
+        if (entry.kind === "dir") await walk(path);
+        else if (/\.(wesl|wgsl)$/.test(entry.name)) {
+          const module = `${pkg}::${path.replace(/\.(wesl|wgsl)$/, "").split("/").join("::")}`;
+          const file = `${prefix}/${path}`;
+          this.register(module, await platform.fs.readText(file), file);
+          loaded.push(module);
+        }
+      }
+    };
+    await walk("");
+    return loaded;
+  }
+  /** Links a variant. Results are cached until any module changes. */
+  link(request) {
+    const key = variantKey(request);
+    let result = this.linkCache.get(key);
+    if (!result) {
+      result = this.doLink(request, key);
+      this.linkCache.set(key, result);
+      result.catch(() => this.linkCache.delete(key));
+    }
+    return result;
+  }
+  /**
+   * A compiled shader module for a variant, or undefined while the first version compiles. After an
+   * edit, keeps returning the previous module until the new code compiles cleanly; if it doesn't,
+   * the error is reported through the GPU context and the old module stays in use.
+   */
+  module(gpu, request) {
+    const key = variantKey(request);
+    let state = this.variants.get(key);
+    if (!state) {
+      state = { good: void 0, pending: void 0, version: -1, gpu, request };
+      this.variants.set(key, state);
+    }
+    const s = state;
+    s.gpu = gpu;
+    if (s.version !== this.version && s.pending === void 0) this.rebuild(gpu, request, s);
+    if (s.good && s.good.generation !== gpu.generation) {
+      s.good = { ...s.good, module: moduleFor(gpu, s.good.linked), generation: gpu.generation };
+    }
+    return s.good?.module;
+  }
+  rebuild(gpu, request, s) {
+    s.version = this.version;
+    s.pending = "linking";
+    this.link(request).then(
+      async (linked) => {
+        if (s.good?.code !== linked.code) {
+          s.pending = linked.code;
+          const error = await compile(gpu, linked);
+          if (error) gpu.reportError(labelled(error, request.label));
+          else
+            s.good = {
+              code: linked.code,
+              module: moduleFor(gpu, linked),
+              linked,
+              generation: gpu.generation
+            };
+        }
+        s.pending = void 0;
+      },
+      (err) => {
+        gpu.reportError(
+          labelled(
+            err instanceof ShardError ? err : new ShardError("shader/link", String(err)),
+            request.label
+          )
+        );
+        s.pending = void 0;
+      }
+    );
+  }
+  /** Waits until every variant requested through `module()` has finished compiling. */
+  async whenIdle() {
+    for (let i = 0; i < 200; i++) {
+      if (![...this.variants.values()].some((v) => v.pending !== void 0)) return;
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+  }
+  /** Module graph and hooks, for agents. */
+  describe(root) {
+    const modules = [...this.sources.keys()].sort();
+    const imports = (path) => importsOf(this.sources.get(path) ?? "");
+    const reachable = root ? [...closure(root, imports)] : modules;
+    return {
+      modules: reachable,
+      imports: Object.fromEntries(reachable.map((m) => [m, imports(m)])),
+      hooks: Object.fromEntries(
+        reachable.map((m) => [m, [...findHooks(this.sources.get(m) ?? "").keys()]]).filter(([, h]) => h.length > 0)
+      ),
+      defines: [...new Set(reachable.flatMap((m) => definesOf(this.sources.get(m) ?? "")))].sort()
+    };
+  }
+  /** Of the source of every module a variant links: its root's imports, and the overrides'. */
+  hashOf(request) {
+    const imports = (p) => importsOf(this.sources.get(p) ?? "");
+    const paths = /* @__PURE__ */ new Set();
+    for (const root of [request.root, ...request.overrides ?? []])
+      for (const p of closure(root, imports)) paths.add(p);
+    let a = 2166136261;
+    let b = 2538058380;
+    for (const path of [...paths].sort()) {
+      const text = `${path}
+${this.sources.get(path) ?? ""}
+`;
+      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);
+      }
+    }
+    return `${(a >>> 0).toString(16).padStart(8, "0")}${(b >>> 0).toString(16).padStart(8, "0")}`;
+  }
+  async doLink(request, key) {
+    const overrides = request.overrides ?? [];
+    for (const path of [request.root, ...overrides]) {
+      if (!this.sources.has(path)) {
+        throw new ShardError(
+          "shader/link-unknown-module",
+          `Shader module "${path}" is not registered`,
+          {
+            hint: `Registered modules: ${[...this.sources.keys()].sort().join(", ") || "none"}.`
+          }
+        );
+      }
+    }
+    for (const path of closure(request.root, (p) => importsOf(this.sources.get(p) ?? ""))) {
+      if (!this.sources.has(path)) {
+        const importer = [...this.sources].find(([, src]) => importsOf(src).includes(path))?.[0];
+        throw new ShardError("shader/link-unknown-module", `Unknown shader module "${path}"`, {
+          path: importer ? this.origins.get(importer) : void 0,
+          hint: "Check the import path, or register the module."
+        });
+      }
+    }
+    const hash = this.hashOf(request);
+    const baked = this.preloaded.get(key);
+    if (baked && baked.hash === hash) {
+      this.used.set(key, baked);
+      return { key, code: baked.code, locate: () => void 0 };
+    }
+    const { link } = await loadWesl();
+    this.linked++;
+    const hooked = applyHooks(this.sources, overrides);
+    const root = splitPath(request.root);
+    const packages = /* @__PURE__ */ new Map();
+    const fileToModule = /* @__PURE__ */ new Map();
+    for (const [path, source] of hooked) {
+      const { pkg, file } = splitPath(path);
+      if (!packages.has(pkg)) packages.set(pkg, {});
+      packages.get(pkg)[file] = source;
+      fileToModule.set(`${pkg}|${file}`, path);
+    }
+    const libs = [...packages].filter(([pkg]) => pkg !== root.pkg).map(([pkg, modules]) => ({ name: pkg, edition: "unstable_2025", modules }));
+    let linked;
+    try {
+      linked = await link({
+        weslSrc: packages.get(root.pkg),
+        rootModuleName: root.file,
+        packageName: root.pkg,
+        libs,
+        conditions: { ...request.defines }
+      });
+    } catch (err) {
+      throw linkError(
+        err,
+        (file) => {
+          const lib = /^\.\/([a-z_][a-z0-9_]*)\/(.*)$/.exec(file);
+          const module = fileToModule.get(`${root.pkg}|${file}`) ?? (lib ? fileToModule.get(`${lib[1]}|./${lib[2]}`) : void 0);
+          return module ? this.origins.get(module) : void 0;
+        },
+        this.origins.get(request.root)
+      );
+    }
+    const code = linked.dest;
+    this.used.set(key, { key, hash, code });
+    const origins = this.origins;
+    return {
+      key,
+      code,
+      locate(offset) {
+        try {
+          const pos = linked.sourceMap.destToSrc(offset);
+          const srcPath = pos.src.path ?? "";
+          const match = /^\.\/([a-z_][a-z0-9_]*)\/(.*)$/.exec(srcPath);
+          const module = fileToModule.get(`${root.pkg}|${srcPath}`) ?? (match ? fileToModule.get(`${match[1]}|./${match[2]}`) : void 0) ?? srcPath;
+          const { line, column } = lineColumn(pos.src.text, pos.position);
+          return { module: origins.get(module) ?? module, line, column };
+        } catch {
+          return void 0;
+        }
+      }
+    };
+  }
+}
+const moduleCache = /* @__PURE__ */ new WeakMap();
+function moduleFor(gpu, linked) {
+  let cache = moduleCache.get(gpu);
+  if (!cache || cache.generation !== gpu.generation) {
+    cache = /* @__PURE__ */ new Map();
+    cache.generation = gpu.generation;
+    moduleCache.set(gpu, cache);
+  }
+  let module = cache.get(linked.code);
+  if (!module) {
+    module = gpu.device.createShaderModule({ label: linked.key, code: linked.code });
+    cache.set(linked.code, module);
+  }
+  return module;
+}
+function linkError(err, originOf, fallback) {
+  let message = (err instanceof Error ? err.message : String(err)).split("\n")[0];
+  let loc = err.weslLocation;
+  const prefix = /^(\.\/\S+?):(\d+):(\d+)\s+error:\s*(.*)$/.exec(message);
+  if (!loc && prefix) {
+    loc = { file: prefix[1], line: Number(prefix[2]), column: Number(prefix[3]) };
+    message = prefix[4];
+  }
+  const origin = (loc && originOf(loc.file)) ?? fallback;
+  const path = origin && loc ? `${origin}:${loc.line}:${loc.column}` : origin;
+  return new ShardError("shader/link-unresolved", message.replace(/ in file: \S+$/, ""), { path });
+}
+async function compile(gpu, linked) {
+  gpu.device.pushErrorScope("validation");
+  const probe = gpu.device.createShaderModule({ label: `${linked.key} (check)`, code: linked.code });
+  void gpu.device.popErrorScope();
+  const info = await probe.getCompilationInfo();
+  const first = info.messages.find((m) => m.type === "error");
+  if (!first) return void 0;
+  const where = linked.locate(first.offset);
+  const path = where ? `${where.module}:${where.line}:${where.column}` : void 0;
+  return new ShardError("shader/compile", `${first.message}${path ? ` (${path})` : ""}`, { path });
+}
+function labelled(error, label) {
+  if (!label) return error;
+  return new ShardError(error.code, `${label}: ${error.message}`, {
+    path: error.path,
+    hint: error.hint
+  });
+}
+function variantKey(request) {
+  const defines = Object.entries(request.defines ?? {}).filter(([, on]) => on).map(([name]) => name).sort();
+  return `${request.root}|${defines.join(",")}|${(request.overrides ?? []).join(",")}`;
+}
+function importsOf(source) {
+  const out = [];
+  for (const m of source.matchAll(/^\s*import\s+([^;]+);/gm)) {
+    const spec = m[1].replace(/\s+/g, "");
+    const braced = /^(.*?)::\{(.*)\}$/.exec(spec);
+    if (braced) {
+      for (const item of braced[2].split(",")) {
+        const name = item.split(/as/)[0];
+        const parts = `${braced[1]}::${name}`.split("::");
+        out.push(parts.slice(0, -1).join("::"));
+      }
+    } else {
+      out.push(spec.split("::").slice(0, -1).join("::"));
+    }
+  }
+  return [...new Set(out.filter((p) => p.includes("::") && !p.startsWith("constants")))];
+}
+function definesOf(source) {
+  const out = [];
+  for (const m of source.matchAll(/@(?:if|elif)\s*\(([^)]*)\)/g)) {
+    for (const id of m[1].matchAll(/[A-Za-z_]\w*/g))
+      if (id[0] !== "true" && id[0] !== "false") out.push(id[0]);
+  }
+  return out;
+}
+function closure(root, next) {
+  const seen = /* @__PURE__ */ new Set();
+  const stack = [root];
+  while (stack.length > 0) {
+    const path = stack.pop();
+    if (seen.has(path)) continue;
+    seen.add(path);
+    stack.push(...next(path));
+  }
+  return seen;
+}
+export {
+  ShaderLibrary
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@aethervtt/shard-shader",
+  "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-core": "0.0.1",
+    "@aethervtt/shard-gpu": "0.0.1",
+    "@aethervtt/shard-platform": "0.0.1",
+    "wesl": "0.7.31"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/shader"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+  }
+}