wgsl-play 0.0.2 → 0.0.5

package/README.md

@@ -12,13 +12,44 @@ Web component for rendering WESL/WGSL fragment shaders.
 
 That's it. The component auto-fetches dependencies and starts animating.
 
+### Shader API
+
+Write a fragment shader with entry point `fs_main`. WESL extensions are supported (imports, conditional compilation).
+
+Standard uniforms are provided at binding 0:
+
+```wgsl
+import test::Uniforms;
+
+@group(0) @binding(0) var<uniform> u: Uniforms;
+
+@fragment fn fs_main(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+  let uv = pos.xy / u.resolution;
+  return vec4f(uv, sin(u.time) * 0.5 + 0.5, 1.0);
+}
+```
+
+| Uniform | Type | Description |
+|---------|------|-------------|
+| `resolution` | `vec2f` | Canvas dimensions in pixels |
+| `time` | `f32` | Elapsed time in seconds |
+| `mouse` | `vec2f` | Mouse position (normalized 0-1) |
+
 ### Inline source
 
+You can include shader code inline if you'd prefer. Use a `<script type="text/wgsl">` (or `<script type="text/wesl">`) tag.
+
 ```html
 <wgsl-play>
-  @fragment fn fs_main() -> @location(0) vec4f {
-    return vec4f(1.0, 0.0, 0.0, 1.0);
-  }
+  <script type="text/wesl">
+    import test::Uniforms;
+    @group(0) @binding(0) var<uniform> u: Uniforms;
+
+    @fragment fn fs_main(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+      let uv = pos.xy / u.resolution;
+      return vec4f(uv, sin(u.time) * 0.5 + 0.5, 1.0);
+    }
+  </script>
 </wgsl-play>
 ```
 
@@ -32,10 +63,22 @@ player.rewind();
 player.play();
 ```
 
+### Importing shaders (Vite)
+
+```typescript
+import shader from './examples/noise.wesl?raw';
+
+const player = document.querySelector("wgsl-play");
+player.source = shader;
+```
+
+The `?raw` suffix imports the file as a string. This keeps shaders alongside your source files with HMR support.
+
 ## API
 
 ### Attributes
 - `src` - URL to .wesl/.wgsl file
+- `shader-root` - Root path for internal imports (default: `/shaders`)
 
 ### Properties
 - `source: string` - Get/set shader source
@@ -69,6 +112,70 @@ wgsl-play::part(canvas) {
 }
 ```
 
+## Multi-file Shaders
+
+For apps with multiple shader files, use `shader-root`. 
+
+```
+public/
+  shaders/
+    utils.wesl       # import package::utils
+    effects/
+      main.wesl      # import super::common
+      common.wesl
+```
+
+```html
+<wgsl-play src="/shaders/effects/main.wesl" shader-root="/shaders"></wgsl-play>
+```
+
+Local shader modules referenced via `package::` or `super::`
+will be fetched from the web server.
+
+```wgsl
+// effects/main.wesl
+import package::utils::noise;
+import super::common::tint;
+
+@fragment fn fs_main(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+  return tint(noise(pos.xy));
+}
+```
+
+## Using with wesl-plugin
+
+For more control, use the [wesl-plugin](https://github.com/wgsl-tooling-wg/wesl-js/tree/main/tools/packages/wesl-plugin) to
+assemble shaders and libraries at build time and provide
+them wgsl-play in JavaScript or TypeScript.
+- provides full support for Hot Module Reloading during development
+- allows specifying fixed library dependency versions
+
+### Runtime linking (?link)
+
+With Runtime linking, WGSL is constructed from WGSL/WESL at runtime. 
+Use runtime linking to enable virtual modules, 
+conditional transpilation, and injecting shader constants from JavaScript.
+
+```typescript
+// vite.config.ts
+import { linkBuildExtension } from "wesl-plugin";
+import viteWesl from "wesl-plugin/vite";
+
+export default {
+  plugins: [viteWesl({ extensions: [linkBuildExtension] })]
+};
+
+// app.ts
+import shaderConfig from "./shader.wesl?link";
+
+// wgsl-play links internally, allowing runtime conditions/constants
+player.project = {
+  ...shaderConfig,
+  conditions: { MOBILE: isMobileGPU },
+  constants: { num_lights: 4 }
+};
+```
+
 ## Exports
 
 ```typescript
@@ -77,4 +184,9 @@ import "wgsl-play";
 
 // Element class only (manual registration)
 import { WgslPlay } from "wgsl-play/element";
+
+// Configuration
+import { defaults } from "wgsl-play";
+
+defaults({ shaderRoot: "/custom/shaders" });
 ```

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "wgsl-play",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "type": "module",
+  "repository": "github:wgsl-tooling-wg/wesl-js",
   "exports": {
     ".": "./src/index.ts",
     "./element": "./src/WgslPlay.ts"
@@ -10,14 +11,16 @@
     "es-module-lexer": "^1.7.0",
     "fflate": "^0.8.2",
     "nanotar": "^0.2.0",
-    "wesl-gpu": "0.1.1",
-    "wesl": "0.6.47"
+    "resolve.exports": "^2.0.3",
+    "wesl": "0.7.1",
+    "wesl-gpu": "0.1.4"
   },
   "devDependencies": {
-    "@playwright/test": "^1.53.2"
+    "@playwright/test": "^1.53.2",
+    "wesl-plugin": "x"
   },
   "scripts": {
-    "dev": "vite test-page",
+    "dev": "vite test-page --config vite.config.ts",
     "test": "vitest",
     "test:e2e": "playwright test",
     "typecheck": "tsgo"

package/src/BundleLoader.ts

@@ -3,6 +3,14 @@ import { type ParsedTarFileItem, parseTar } from "nanotar";
 import type { WeslBundle } from "wesl";
 import { loadBundlesFromFiles, type WeslBundleFile } from "./BundleHydrator.ts";
 
+/** Fetch bundle files from an npm package (without evaluating). */
+export async function fetchBundleFilesFromNpm(
+  packageName: string,
+): Promise<WeslBundleFile[]> {
+  const tgzUrl = await npmPackageToUrl(packageName);
+  return fetchBundleFilesFromUrl(tgzUrl);
+}
+
 /** Load bundles from URL or npm package name, return bundles, package name, and resolved tgz URL. */
 export async function loadBundlesWithPackageName(
   input: string,
@@ -28,7 +36,8 @@ export async function loadBundlesWithPackageName(
   return { bundles, packageName, tgzUrl };
 }
 
-/** Load WESL bundles from a tgz URL. */
+/** Load WESL bundles from a tgz URL.
+ * (handy for privately published packages) */
 export async function loadBundlesFromTgz(
   tgzUrl: string,
   packageName: string,
@@ -41,16 +50,11 @@ export async function loadBundlesFromTgz(
   return loadBundlesFromFiles(bundleFiles);
 }
 
-/** Custom tgz URL for lygia (npm package is outdated). */
-export const lygiaTgzUrl =
-  "https://raw.githubusercontent.com/mighdoll/big-files/refs/heads/main/lygia-1.3.5-rc.2.tgz";
-
 /** Resolve input to a tgz URL (converts npm package names to registry URLs). */
 async function resolvePackageInput(input: string): Promise<string> {
   if (input.startsWith("http://") || input.startsWith("https://")) {
     return input;
   }
-  if (input === "lygia") return lygiaTgzUrl;
   return npmPackageToUrl(input);
 }
 
@@ -77,7 +81,7 @@ async function fetchAndExtractTgz(
 }
 
 /** Fetch bundle files from a tgz URL (without evaluating). */
-export async function fetchBundleFilesFromUrl(
+async function fetchBundleFilesFromUrl(
   tgzUrl: string,
 ): Promise<WeslBundleFile[]> {
   const entries = await fetchAndExtractTgz(tgzUrl);
@@ -91,16 +95,8 @@ export async function fetchBundleFilesFromUrl(
   return bundleFilesWithoutPkg.map(f => ({ ...f, packageName: pkgName }));
 }
 
-/** Fetch bundle files from an npm package (without evaluating). */
-export async function fetchBundleFilesFromNpm(
-  packageName: string,
-): Promise<WeslBundleFile[]> {
-  const tgzUrl = await npmPackageToUrl(packageName);
-  return fetchBundleFilesFromUrl(tgzUrl);
-}
-
 /** Fetch npm package tarball URL from registry metadata. */
-export async function npmPackageToUrl(packageName: string): Promise<string> {
+async function npmPackageToUrl(packageName: string): Promise<string> {
   const metadataUrl = `https://registry.npmjs.org/${packageName}`;
   const response = await fetch(metadataUrl);
   if (!response.ok) {

package/src/Config.ts

@@ -0,0 +1,26 @@
+/** Configuration for wgsl-play. */
+export interface WgslPlayConfig {
+  /** Root path for internal imports (package::, super::). Default: "/shaders" */
+  shaderRoot: string;
+}
+
+const defaultConfig: WgslPlayConfig = {
+  shaderRoot: "/shaders",
+};
+
+let globalConfig: WgslPlayConfig = { ...defaultConfig };
+
+/** Set global defaults for all wgsl-play instances. */
+export function defaults(config: Partial<WgslPlayConfig>): void {
+  globalConfig = { ...globalConfig, ...config };
+}
+
+/** Get resolved config, merging element overrides with global defaults. */
+export function getConfig(overrides?: Partial<WgslPlayConfig>): WgslPlayConfig {
+  return { ...globalConfig, ...overrides };
+}
+
+/** Reset config to defaults (useful for testing). */
+export function resetConfig(): void {
+  globalConfig = { ...defaultConfig };
+}

package/src/FetchingResolver.ts

@@ -0,0 +1,146 @@
+/**
+ * FetchingResolver - A resolver that can fetch modules from URLs.
+ *
+ * Provides both sync and async APIs:
+ * - Sync `resolveModule`: for compatibility with current `findUnboundIdents`
+ * - Async `resolveModuleAsync`: the future API with built-in HTTP fetching
+ *
+ * When wesl gets async BindIdents, the sync method and external shim loop
+ * can be removed, and BindIdents will call resolveModuleAsync directly.
+ */
+
+import type { ModuleResolver, WeslAST } from "wesl";
+import { modulePartsToRelativePath, parseSrcModule } from "wesl";
+
+export interface FetchingResolverOptions {
+  /** Base URL for fetching internal modules. */
+  shaderRoot: string;
+  /** Module path of the source file (for super:: resolution). */
+  srcModulePath?: string;
+}
+
+/** Resolver with sync interface for findUnboundIdents and async API for fetching. */
+export class FetchingResolver implements ModuleResolver {
+  private readonly astCache = new Map<string, WeslAST>();
+  readonly sources: Record<string, string>;
+  private readonly requested = new Set<string>();
+  private readonly shaderRoot: string;
+  private readonly srcModuleParts?: string[];
+
+  constructor(
+    initialSources: Record<string, string>,
+    options: FetchingResolverOptions,
+  ) {
+    this.sources = { ...initialSources };
+    const { shaderRoot, srcModulePath } = options;
+    this.shaderRoot = shaderRoot.replace(/\/$/, "");
+    this.srcModuleParts = srcModulePath
+      ? this.urlToModuleParts(srcModulePath)
+      : undefined;
+  }
+
+  // ── Sync API (for findUnboundIdents compatibility) ──
+
+  /** Sync lookup - returns cached AST or undefined, records misses. */
+  resolveModule(modulePath: string): WeslAST | undefined {
+    const cached = this.astCache.get(modulePath);
+    if (cached) return cached;
+
+    const source = this.sources[modulePath];
+    if (!source) {
+      this.requested.add(modulePath);
+      return undefined;
+    }
+
+    return this.parseAndCache(modulePath, source);
+  }
+
+  /** Module paths that were requested but not found. */
+  getUnresolved(): string[] {
+    return [...this.requested].filter(p => !this.astCache.has(p));
+  }
+
+  /** Get all parsed modules. */
+  allModules(): Iterable<[string, WeslAST]> {
+    for (const modulePath of Object.keys(this.sources)) {
+      if (!this.astCache.has(modulePath)) {
+        this.resolveModule(modulePath);
+      }
+    }
+    return this.astCache.entries();
+  }
+
+  // ── Async API (future BindIdents interface) ──
+
+  /** Async lookup - returns cached AST or fetches, parses, and caches. */
+  async resolveModuleAsync(modulePath: string): Promise<WeslAST | undefined> {
+    const cached = this.astCache.get(modulePath);
+    if (cached) return cached;
+
+    if (this.sources[modulePath]) {
+      return this.resolveModule(modulePath);
+    }
+
+    const source = await this.fetchInternal(modulePath);
+    if (!source) return undefined;
+
+    this.sources[modulePath] = source;
+    this.requested.delete(modulePath);
+    return this.parseAndCache(modulePath, source);
+  }
+
+  // ── Internal fetching ──
+
+  private async fetchInternal(modulePath: string): Promise<string | undefined> {
+    const url = this.modulePathToUrl(modulePath);
+    if (!url) return undefined;
+    return fetchWithExtensions(url);
+  }
+
+  private modulePathToUrl(modulePath: string): string | undefined {
+    const parts = modulePath.split("::");
+    const filePath = modulePartsToRelativePath(
+      parts,
+      "package",
+      this.srcModuleParts,
+    );
+    if (!filePath) {
+      if (parts[0] === "super" && !this.srcModuleParts) {
+        const msg = `Cannot resolve super:: without file context: ${modulePath}`;
+        throw new Error(msg);
+      }
+      return undefined; // external module
+    }
+    return `${this.shaderRoot}/${filePath}`;
+  }
+
+  private parseAndCache(modulePath: string, source: string): WeslAST {
+    const params = { modulePath, debugFilePath: modulePath, src: source };
+    const ast = parseSrcModule(params);
+    this.astCache.set(modulePath, ast);
+    return ast;
+  }
+
+  private urlToModuleParts(urlPath: string): string[] {
+    const path = urlPath
+      .replace(this.shaderRoot, "")
+      .replace(/^\//, "")
+      .replace(/\.w[eg]sl$/, "");
+    return ["package", ...path.split("/").filter(Boolean)];
+  }
+}
+
+/** Try fetching URL with .wesl then .wgsl extension. */
+async function fetchWithExtensions(
+  baseUrl: string,
+): Promise<string | undefined> {
+  for (const ext of [".wesl", ".wgsl"]) {
+    try {
+      const response = await fetch(baseUrl + ext);
+      if (response.ok) return response.text();
+    } catch {
+      // Try next extension
+    }
+  }
+  return undefined;
+}

package/src/HttpPackageLoader.ts

@@ -0,0 +1,239 @@
+import { resolve } from "resolve.exports";
+import type { WeslBundle } from "wesl";
+import { findUnboundIdents, RecordResolver } from "wesl";
+import type { WeslBundleFile } from "./BundleHydrator.ts";
+import { bundleRegistry, hydrateBundleRegistry } from "./BundleHydrator.ts";
+
+/** Resolution mode for package loading. (Note: disconnected from main flow) */
+type PackageMode = "source" | "bundle";
+
+/** Loaded sources for source mode. */
+export interface SourcePackage {
+  sources: Record<string, string>;
+  packageName: string;
+}
+
+/** Cached package.json data. */
+interface PackageJson {
+  name: string;
+  exports?: Record<string, unknown>;
+}
+
+const packageJsonCache = new Map<string, PackageJson>();
+
+/** Fetch packages from HTTP base URL in bundle or source mode. */
+export async function fetchPackagesFromHttp(
+  pkgNames: string[],
+  packageBase: string,
+  mode: PackageMode,
+): Promise<WeslBundle[] | SourcePackage[]> {
+  if (mode === "source") {
+    return fetchSourcePackages(pkgNames, packageBase);
+  }
+  return fetchBundlePackages(pkgNames, packageBase);
+}
+
+/** Clear package.json cache (useful for testing). */
+export function clearHttpCache(): void {
+  packageJsonCache.clear();
+}
+
+/** Fetch raw .wesl source files for source mode using findUnboundIdents. */
+async function fetchSourcePackages(
+  pkgNames: string[],
+  packageBase: string,
+): Promise<SourcePackage[]> {
+  const results: SourcePackage[] = [];
+  for (const pkgName of pkgNames) {
+    const pkg = await fetchSourcePackage(pkgName, packageBase);
+    results.push(pkg);
+  }
+  return results;
+}
+
+/** Fetch a single package's source files starting from lib.wesl. */
+async function fetchSourcePackage(
+  pkgName: string,
+  packageBase: string,
+): Promise<SourcePackage> {
+  const sources: Record<string, string> = {};
+  const fetched = new Set<string>();
+  const pending = ["lib"];
+
+  while (pending.length > 0) {
+    const modulePath = pending.pop()!;
+    if (fetched.has(modulePath)) continue;
+    fetched.add(modulePath);
+
+    const source = await fetchSourceFile(pkgName, modulePath, packageBase);
+    if (!source) continue;
+
+    const fileName = modulePath === "lib" ? "lib.wgsl" : `${modulePath}.wesl`;
+    sources[fileName] = source;
+
+    const internalRefs = findInternalReferences(source, pkgName);
+    for (const ref of internalRefs) {
+      if (!fetched.has(ref)) pending.push(ref);
+    }
+  }
+
+  return { sources, packageName: pkgName };
+}
+
+/** Find references to modules within the same package. */
+function findInternalReferences(source: string, pkgName: string): string[] {
+  const resolver = new RecordResolver(
+    { main: source },
+    { packageName: pkgName },
+  );
+  const unbound = findUnboundIdents(resolver);
+  return unbound
+    .filter(path => path[0] === pkgName && path.length > 1)
+    .map(path => path.slice(1).join("/"));
+}
+
+/** Fetch a single source file, trying various paths and extensions. */
+async function fetchSourceFile(
+  pkgName: string,
+  modulePath: string,
+  packageBase: string,
+): Promise<string | null> {
+  const basePath = modulePath === "lib" ? "lib" : modulePath;
+  const prefixes = ["", "shaders/", "src/"];
+  const extensions = ["wesl", "wgsl"];
+
+  for (const prefix of prefixes) {
+    for (const ext of extensions) {
+      const url = normalizeUrl(
+        `${packageBase}/${pkgName}/${prefix}${basePath}.${ext}`,
+      );
+      try {
+        const response = await fetch(url);
+        if (response.ok) {
+          const contentType = response.headers.get("content-type") || "";
+          // Skip HTML error pages (Vite returns 200 with HTML for missing files)
+          if (contentType.includes("text/html")) continue;
+          return response.text();
+        }
+      } catch {
+        // Try next combination
+      }
+    }
+  }
+  return null;
+}
+
+/** Fetch weslBundle.js files for bundle mode. */
+async function fetchBundlePackages(
+  pkgNames: string[],
+  packageBase: string,
+): Promise<WeslBundle[]> {
+  const loaded = new Set<string>();
+  const allFiles: WeslBundleFile[] = [];
+
+  for (const pkgName of pkgNames) {
+    const files = await fetchBundlePackage(pkgName, packageBase, loaded);
+    allFiles.push(...files);
+  }
+
+  const registry = await bundleRegistry(allFiles);
+  return hydrateBundleRegistry(registry, pkgId =>
+    fetchBundlePackage(pkgId, packageBase, loaded),
+  );
+}
+
+/** Fetch bundle files for a single package. */
+async function fetchBundlePackage(
+  pkgName: string,
+  packageBase: string,
+  loaded: Set<string>,
+): Promise<WeslBundleFile[]> {
+  if (loaded.has(pkgName)) return [];
+  loaded.add(pkgName);
+
+  const pkg = await fetchPackageJson(pkgName, packageBase);
+  if (!pkg) {
+    throw new Error(`Could not fetch package.json for ${pkgName}`);
+  }
+
+  const bundleFiles: WeslBundleFile[] = [];
+
+  // Try root bundle first (single-bundle package)
+  const rootBundlePath = resolveBundlePath(pkg, ".");
+  if (rootBundlePath) {
+    const content = await fetchBundleFile(pkgName, rootBundlePath, packageBase);
+    if (content) {
+      bundleFiles.push({
+        packagePath: `package/${rootBundlePath}`,
+        content,
+        packageName: pkgName,
+      });
+    }
+  }
+
+  // For multi-bundle packages, bundles are fetched on-demand by the hydrator
+
+  return bundleFiles;
+}
+
+/** Fetch and cache package.json. */
+async function fetchPackageJson(
+  pkgName: string,
+  packageBase: string,
+): Promise<PackageJson | null> {
+  const key = `${packageBase}/${pkgName}`;
+  const cached = packageJsonCache.get(key);
+  if (cached) return cached;
+
+  const url = normalizeUrl(`${packageBase}/${pkgName}/package.json`);
+  try {
+    const response = await fetch(url);
+    if (!response.ok) return null;
+    const pkg = await response.json();
+    packageJsonCache.set(key, pkg);
+    return pkg;
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve bundle path using package.json exports via resolve.exports library. */
+function resolveBundlePath(pkg: PackageJson, subpath: string): string | null {
+  if (!pkg.exports) {
+    // No exports field - assume single bundle at dist/weslBundle.js
+    return "dist/weslBundle.js";
+  }
+
+  try {
+    const resolved = resolve(pkg, subpath);
+    if (resolved) {
+      const path = Array.isArray(resolved) ? resolved[0] : resolved;
+      return path.startsWith("./") ? path.slice(2) : path;
+    }
+  } catch {
+    // resolve.exports throws on no match
+  }
+
+  return null;
+}
+
+/** Fetch a single bundle file. */
+async function fetchBundleFile(
+  pkgName: string,
+  bundlePath: string,
+  packageBase: string,
+): Promise<string | null> {
+  const url = normalizeUrl(`${packageBase}/${pkgName}/${bundlePath}`);
+  try {
+    const response = await fetch(url);
+    if (!response.ok) return null;
+    return response.text();
+  } catch {
+    return null;
+  }
+}
+
+/** Normalize URL by removing double slashes (except after protocol). */
+function normalizeUrl(url: string): string {
+  return url.replace(/([^:])\/+/g, "$1/");
+}