wgsl-play 0.0.2 → 0.0.4

package/src/PackageLoader.ts

@@ -1,5 +1,30 @@
+/**
+ * Module Discovery Phase
+ *
+ * Before linking, we run a discovery phase to find and fetch all needed modules.
+ * This uses a lightweight binding pass (findUnboundIdents) that walks the scope tree
+ * to find module references without fully resolving them.
+ *
+ * Module paths (e.g., foo::bar::baz) come from import statements or inline qualified
+ * references. We categorize them as:
+ *   - internal: package:: and super:: paths, fetched from local URLs (shaderRoot)
+ *   - external: other packages, fetched from npm
+ *
+ * The discovery loop uses FetchingResolver which provides:
+ *   - Sync resolveModule() for findUnboundIdents compatibility
+ *   - Async resolveModuleAsync() as prototype for future async BindIdents
+ *
+ * When wesl gets async BindIdents, the shim loop disappears and BindIdents
+ * will call resolveModuleAsync directly.
+ */
+
 import type { WeslBundle } from "wesl";
-import { findUnboundIdents, npmNameVariations, RecordResolver } from "wesl";
+import {
+  fileToModulePath,
+  findUnboundIdents,
+  npmNameVariations,
+  partition,
+} from "wesl";
 import type { WeslBundleFile } from "./BundleHydrator.ts";
 import { bundleRegistry, hydrateBundleRegistry } from "./BundleHydrator.ts";
 import {
@@ -7,40 +32,119 @@ import {
   fetchBundleFilesFromUrl,
   lygiaTgzUrl,
 } from "./BundleLoader.ts";
+import { getConfig, type WgslPlayConfig } from "./Config.ts";
+import { FetchingResolver } from "./FetchingResolver.ts";
 
-/** Shader source with resolved dependency bundles. */
-export interface ShaderWithDeps {
-  source: string;
-  bundles: WeslBundle[];
+/** Resolved sources ready for the linker. */
+export interface ResolvedSources {
+  /** All sources keyed by module path. */
+  weslSrc: Record<string, string>;
+  libs: WeslBundle[];
+  /** Module name for the root/main module. */
+  rootModuleName?: string;
 }
 
-/** Fetch bundles for external dependencies detected in shader source. */
-export async function fetchDependenciesForSource(
-  source: string,
-): Promise<WeslBundle[]> {
-  const packageNames = detectPackageDeps(source);
-  return fetchPackages(packageNames);
+const virtualModules = ["constants", "test"];
+
+/** Resolve dependencies: internal modules via HTTP, external packages from npm. */
+export async function fetchDependencies(
+  rootModuleSource: string,
+  configOverrides?: Partial<WgslPlayConfig>,
+  currentPath?: string,
+  existingSources?: Record<string, string>,
+): Promise<ResolvedSources> {
+  const config = getConfig(configOverrides);
+  const rootModuleName = currentPath
+    ? urlToModulePath(currentPath, config.shaderRoot)
+    : "package::main";
+  const initialSources = {
+    ...existingSources,
+    [rootModuleName]: rootModuleSource,
+  };
+  const resolverOpts = {
+    shaderRoot: config.shaderRoot,
+    srcModulePath: currentPath,
+  };
+  const resolver = new FetchingResolver(initialSources, resolverOpts);
+
+  const libs: WeslBundle[] = [];
+  const fetched = new Set<string>();
+
+  // Discovery loop (LATER we'll make BindIdents async, and this can go away)
+  while (true) {
+    findUnboundIdents(resolver);
+
+    const unresolved = getNonVirtualUnresolved(resolver, fetched);
+    if (unresolved.length === 0) break;
+
+    const [internal, external] = partition(unresolved, isInternal);
+    await Promise.all(internal.map(p => resolver.resolveModuleAsync(p)));
+
+    const newLibs = await fetchExternalBundles(external, fetched);
+    libs.push(...newLibs);
+  }
+
+  const weslSrc = extractWeslSrc(resolver);
+  return { libs, weslSrc };
 }
 
-/** Load shader text from a url and recursively fetch imported bundles */
-export async function loadShaderFromUrl(url: string): Promise<ShaderWithDeps> {
-  const source = await fetchShaderSource(url);
-  const packageNames = detectPackageDeps(source);
-  const bundles = await fetchPackages(packageNames);
-  return { source, bundles };
+/** Load shader from URL, resolving all dependencies. */
+export async function loadShaderFromUrl(
+  url: string,
+  configOverrides?: Partial<WgslPlayConfig>,
+): Promise<ResolvedSources> {
+  const source = await fetchText(url);
+  const currentPath = new URL(url, window.location.href).pathname;
+  const config = getConfig(configOverrides);
+  const rootModuleName = urlToModulePath(currentPath, config.shaderRoot);
+  const { weslSrc, libs } = await fetchDependencies(
+    source,
+    configOverrides,
+    currentPath,
+  );
+  return { weslSrc, libs, rootModuleName };
 }
 
-/** Detect external package dependencies from shader source. */
-function detectPackageDeps(source: string): string[] {
-  const resolver = new RecordResolver({ "./main.wesl": source });
-  const unbound = findUnboundIdents(resolver);
-  const pkgRefs = unbound.filter(p => p[0] !== "constants" && p[0] !== "test"); // LATER make dynamic
-  const weslPackages = pkgRefs.map(p => p[0]);
-  return [...new Set(weslPackages)];
+function getNonVirtualUnresolved(
+  resolver: FetchingResolver,
+  fetched: Set<string>,
+): string[] {
+  return resolver.getUnresolved().filter(p => {
+    const pkg = p.split("::")[0];
+    return !virtualModules.includes(pkg) && !fetched.has(pkg);
+  });
 }
 
-/** Fetch WESL bundles for packages, auto-fetching dependencies recursively. */
-async function fetchPackages(pkgIds: string[]): Promise<WeslBundle[]> {
+function isInternal(modulePath: string): boolean {
+  return modulePath.startsWith("package::") || modulePath.startsWith("super::");
+}
+
+/** Extract all sources from resolver (including main). */
+function extractWeslSrc(resolver: FetchingResolver): Record<string, string> {
+  const weslSrc: Record<string, string> = {};
+  for (const [path] of resolver.allModules()) {
+    if (resolver.sources[path]) {
+      weslSrc[path] = resolver.sources[path];
+    }
+  }
+  return weslSrc;
+}
+
+/** Fetch external packages from npm. */
+async function fetchExternalBundles(
+  modulePaths: string[],
+  fetched: Set<string>,
+): Promise<WeslBundle[]> {
+  const pkgNames = [...new Set(modulePaths.map(p => p.split("::")[0]))];
+  const newPkgs = pkgNames.filter(p => !fetched.has(p));
+  if (newPkgs.length === 0) return [];
+
+  for (const p of newPkgs) fetched.add(p);
+  return fetchPackagesFromNpm(newPkgs);
+}
+
+/** Fetch WESL bundles from npm, auto-fetching dependencies recursively. */
+async function fetchPackagesFromNpm(pkgIds: string[]): Promise<WeslBundle[]> {
   const loaded = new Set<string>();
 
   const promisedBundles = pkgIds.map(id => fetchOnePackage(id, loaded));
@@ -55,7 +159,7 @@ async function fetchOnePackage(
   pkgId: string,
   loaded: Set<string>,
 ): Promise<WeslBundleFile[]> {
-  if (loaded.has(pkgId)) return []; // already loaded
+  if (loaded.has(pkgId)) return [];
   loaded.add(pkgId);
 
   // Special case for lygia - use custom tgz URL (npm package is outdated)
@@ -73,8 +177,15 @@ async function fetchOnePackage(
   throw new Error(`Package not found: ${pkgId}`);
 }
 
-/** Fetch shader source from URL. */
-async function fetchShaderSource(url: string): Promise<string> {
+/** Convert URL path to module path (e.g., "/shaders/effects/main.wesl" -> "package::effects::main"). */
+function urlToModulePath(urlPath: string, shaderRoot: string): string {
+  const cleanRoot = shaderRoot.replace(/\/$/, "");
+  const relativePath = urlPath.replace(cleanRoot, "").replace(/^\//, "");
+  return fileToModulePath(relativePath, "package", false);
+}
+
+/** Fetch text content from URL. */
+async function fetchText(url: string): Promise<string> {
   const response = await fetch(url);
   if (!response.ok) {
     throw new Error(`HTTP ${response.status}: ${response.statusText}`);

package/src/Renderer.ts

@@ -1,9 +1,15 @@
-import type { LinkParams, WeslBundle } from "wesl";
-import { requestWeslDevice } from "wesl";
+import type { ModuleResolver } from "wesl";
+import {
+  BundleResolver,
+  CompositeResolver,
+  RecordResolver,
+  requestWeslDevice,
+} from "wesl";
 import {
   linkAndCreatePipeline,
   renderFrame,
   updateRenderUniforms,
+  type WeslOptions,
 } from "wesl-gpu";
 
 /** WebGPU state */
@@ -16,6 +22,7 @@ export interface RenderState {
   pipelineLayout: GPUPipelineLayout;
   bindGroup: GPUBindGroup;
   pipeline?: GPURenderPipeline;
+  frameCount: number;
 }
 
 /** Animation state */
@@ -25,6 +32,9 @@ export interface PlaybackState {
   pausedDuration: number;
 }
 
+/** Options for linking shaders - re-exports wesl-gpu's WeslOptions */
+export type LinkOptions = WeslOptions;
+
 /** Initialize WebGPU for a canvas element. */
 export async function initWebGPU(
   canvas: HTMLCanvasElement,
@@ -68,30 +78,39 @@ export async function initWebGPU(
     uniformBuffer,
     pipelineLayout,
     bindGroup,
+    frameCount: 0,
   };
 }
 
-export type LinkOptions = Pick<
-  LinkParams,
-  "packageName" | "conditions" | "constants"
->;
-
 /** Compile WESL fragment shader and create render pipeline. */
 export async function createPipeline(
   state: RenderState,
   fragmentSource: string,
-  bundles: WeslBundle[],
   options?: LinkOptions,
 ): Promise<void> {
+  const { weslSrc, libs = [], conditions, constants } = options ?? {};
+  const { packageName, rootModuleName } = options ?? {};
+
+  // Build resolver from weslSrc/libs if provided
+  let resolver: ModuleResolver | undefined;
+  if (weslSrc || libs.length > 0) {
+    const resolvers: ModuleResolver[] = [];
+    if (weslSrc) resolvers.push(new RecordResolver(weslSrc));
+    for (const bundle of libs) resolvers.push(new BundleResolver(bundle));
+    resolver =
+      resolvers.length === 1 ? resolvers[0] : new CompositeResolver(resolvers);
+  }
+
   state.pipeline = await linkAndCreatePipeline({
     device: state.device,
     fragmentSource,
-    bundles,
+    resolver,
     format: state.presentationFormat,
     layout: state.pipelineLayout,
-    conditions: options?.conditions,
-    constants: options?.constants,
-    packageName: options?.packageName,
+    conditions,
+    constants,
+    packageName,
+    rootModuleName,
   });
 }
 
@@ -128,11 +147,11 @@ export function startRenderLoop(
       bindGroup: state.bindGroup,
       targetView: state.context.getCurrentTexture().createView(),
     });
+    state.frameCount++;
     animationId = requestAnimationFrame(render);
   }
 
   animationId = requestAnimationFrame(render);
-
   return () => cancelAnimationFrame(animationId);
 }
 

package/src/WgslPlay.css

@@ -4,6 +4,8 @@
 }
 
 canvas {
+  position: absolute;
+  inset: 0;
   width: 100%;
   height: 100%;
   display: block;

package/src/WgslPlay.ts

@@ -1,9 +1,8 @@
 import type { LinkParams, WeslBundle } from "wesl";
+import { fileToModulePath } from "wesl";
+import type { WgslPlayConfig } from "./Config.ts";
 import { ErrorOverlay } from "./ErrorOverlay.ts";
-import {
-  fetchDependenciesForSource,
-  loadShaderFromUrl,
-} from "./PackageLoader.ts";
+import { fetchDependencies, loadShaderFromUrl } from "./PackageLoader.ts";
 import {
   createPipeline,
   initWebGPU,
@@ -14,6 +13,8 @@ import {
 } from "./Renderer.ts";
 import cssText from "./WgslPlay.css?inline";
 
+export { defaults, getConfig, resetConfig } from "./Config.ts";
+
 /** Project configuration for multi-file shaders (subset of wesl link() API). */
 export type WeslProject = Pick<
   LinkParams,
@@ -49,7 +50,7 @@ let template: HTMLTemplateElement | null = null;
  * </wgsl-play>
  */
 export class WgslPlay extends HTMLElement {
-  static observedAttributes = ["src"];
+  static observedAttributes = ["src", "shader-root"];
 
   private canvas: HTMLCanvasElement;
   private errorOverlay: ErrorOverlay;
@@ -63,10 +64,20 @@ export class WgslPlay extends HTMLElement {
     pausedDuration: 0,
   };
 
-  private _source = "";
+  private _weslSrc: Record<string, string> = {};
+  private _rootModuleName = "package::main";
+  private _libs?: WeslBundle[];
   private _linkOptions: LinkOptions = {};
+  private _fromFullProject = false;
   private _initialized = false;
 
+  /** Get config overrides from element attributes. */
+  private getConfigOverrides(): Partial<WgslPlayConfig> | undefined {
+    const shaderRoot = this.getAttribute("shader-root");
+    if (!shaderRoot) return undefined;
+    return { shaderRoot };
+  }
+
   constructor() {
     super();
     const shadow = this.attachShadow({ mode: "open" });
@@ -110,33 +121,57 @@ export class WgslPlay extends HTMLElement {
     }
   }
 
-  /** Current shader source code. */
+  /** Current shader source code (main module). */
   get source(): string {
-    return this._source;
+    return this._weslSrc[this._rootModuleName] ?? "";
   }
 
   /** Set shader source directly. */
   set source(value: string) {
-    this._source = value;
-    this.compileSource(value);
+    this._weslSrc = { [this._rootModuleName]: value };
+    this._libs = undefined;
+    this._fromFullProject = false;
+    this.discoverAndRebuild();
   }
 
   /** Set project configuration (mirrors wesl link() API). */
   set project(value: WeslProject) {
     const { weslSrc, rootModuleName, libs } = value;
     const { packageName, conditions, constants } = value;
-    if (!weslSrc || !rootModuleName) return;
-    const mainSource = weslSrc[rootModuleName];
-    if (!mainSource) return;
 
-    this._source = mainSource;
-    this._linkOptions = { packageName, conditions, constants };
+    // Update link options if provided
+    if (packageName || conditions || constants) {
+      this._linkOptions = { packageName, conditions, constants };
+    }
+    if (libs) this._libs = libs;
 
-    if (libs?.length) {
-      this.compileWithLibs(mainSource, libs);
-    } else {
-      this.compileSource(mainSource);
+    if (weslSrc) {
+      this.setProjectSources(weslSrc, rootModuleName);
+      return;
     }
+
+    // Partial update - may need to refetch if conditions changed
+    if (Object.keys(this._weslSrc).length === 0) return;
+    if (this._fromFullProject) this.rebuildPipeline();
+    else this.discoverAndRebuild();
+  }
+
+  /** Set sources from a full project with weslSrc. */
+  private setProjectSources(
+    weslSrc: Record<string, string>,
+    rootModuleName?: string,
+  ): void {
+    // Convert file paths to module paths if needed (for ?link imports)
+    const entries = Object.entries(weslSrc).map(([k, v]) => [
+      toModulePath(k),
+      v,
+    ]);
+    this._weslSrc = Object.fromEntries(entries);
+    this._rootModuleName = rootModuleName
+      ? toModulePath(rootModuleName)
+      : "package::main";
+    this._fromFullProject = true;
+    this.rebuildPipeline();
   }
 
   /** Whether the shader is currently playing. */
@@ -146,10 +181,14 @@ export class WgslPlay extends HTMLElement {
 
   /** Current animation time in seconds. */
   get time(): number {
-    const currentTime = this.playback.isPlaying
-      ? performance.now()
-      : this.playback.startTime + this.playback.pausedDuration;
-    return (currentTime - this.playback.startTime) / 1000;
+    const { isPlaying, startTime, pausedDuration } = this.playback;
+    const now = isPlaying ? performance.now() : startTime + pausedDuration;
+    return (now - startTime) / 1000;
+  }
+
+  /** Number of frames rendered (for testing/debugging). */
+  get frameCount(): number {
+    return this.renderState?.frameCount ?? 0;
   }
 
   /** Whether there's a compilation error. */
@@ -164,10 +203,9 @@ export class WgslPlay extends HTMLElement {
 
   /** Start playback. */
   play(): void {
-    if (this.playback.isPlaying) return;
-    const pauseTime = this.playback.startTime + this.playback.pausedDuration;
-    this.playback.startTime =
-      performance.now() - (pauseTime - this.playback.startTime);
+    const { isPlaying, pausedDuration } = this.playback;
+    if (isPlaying) return;
+    this.playback.startTime = performance.now() - pausedDuration;
     this.setPlaying(true);
   }
 
@@ -194,23 +232,24 @@ export class WgslPlay extends HTMLElement {
 
   /** Display error message in overlay. Pass empty string to clear. */
   showError(message: string): void {
-    if (message) {
-      this.errorOverlay.show(message);
-      this.pause();
-    } else {
+    if (!message) {
       this.errorOverlay.hide();
+      return;
     }
+    this.errorOverlay.show(message);
+    this.pause();
   }
 
-  /** Set up WebGPU and load initial shader from src attribute or inline content. */
-  private async initialize(): Promise<void> {
-    if (this._initialized) return;
+  /** Set up WebGPU and load initial shader. Returns true if successful. */
+  private async initialize(): Promise<boolean> {
+    if (this._initialized) return !!this.renderState;
     this._initialized = true;
 
     try {
       this.renderState = await initWebGPU(this.canvas);
       await this.loadInitialContent();
       this.stopRenderLoop = startRenderLoop(this.renderState, this.playback);
+      return true;
     } catch (error) {
       const message = `WebGPU initialization failed: ${error}`;
       this.errorOverlay.show(message);
@@ -218,18 +257,26 @@ export class WgslPlay extends HTMLElement {
       this.dispatchEvent(
         new CustomEvent("init-error", { detail: { message } }),
       );
+      return false;
     }
   }
 
-  /** Load from src attribute or inline textContent. */
+  /** Load from src attribute, script child, or inline textContent. */
   private async loadInitialContent(): Promise<void> {
     const src = this.getAttribute("src");
-    if (src) {
-      await this.loadFromUrl(src);
-    } else {
-      const inlineSource = this.textContent?.trim();
-      if (inlineSource) await this.compileSource(inlineSource);
-    }
+    if (src) return this.loadFromUrl(src);
+
+    // Prefer <script type="text/wgsl"> or <script type="text/wesl"> (no HTML escaping needed)
+    const script = this.querySelector(
+      'script[type="text/wgsl"], script[type="text/wesl"]',
+    );
+    const inlineSource =
+      script?.textContent?.trim() ?? this.textContent?.trim();
+    if (!inlineSource) return;
+
+    this._weslSrc = { [this._rootModuleName]: inlineSource };
+    this._fromFullProject = false;
+    await this.discoverAndRebuild();
   }
 
   /** Fetch shader from URL, auto-fetching any imported dependencies. */
@@ -238,45 +285,73 @@ export class WgslPlay extends HTMLElement {
 
     try {
       this.errorOverlay.hide();
-      const { source, bundles } = await loadShaderFromUrl(url);
-      this._source = source;
-      await createPipeline(this.renderState, source, bundles);
+      const { weslSrc, libs, rootModuleName } = await loadShaderFromUrl(
+        url,
+        this.getConfigOverrides(),
+      );
+      this._weslSrc = weslSrc;
+      this._libs = libs;
+      this._fromFullProject = false;
+      if (rootModuleName) this._rootModuleName = rootModuleName;
+
+      const mainSource = weslSrc[this._rootModuleName];
+      if (!mainSource) return;
+
+      await createPipeline(this.renderState, mainSource, {
+        ...this._linkOptions,
+        weslSrc,
+        libs,
+        rootModuleName: this._rootModuleName,
+      });
     } catch (error) {
       this.handleCompileError(error);
     }
   }
 
-  /** Compile source string, auto-fetching any imported dependencies. */
-  private async compileSource(source: string): Promise<void> {
-    if (!this.renderState) return;
+  /** Rebuild GPU pipeline using stored state. For full projects with all sources. */
+  private async rebuildPipeline(): Promise<void> {
+    if (!(await this.initialize())) return;
+
+    const mainSource = this._weslSrc[this._rootModuleName];
+    if (!mainSource) return;
 
     try {
       this.errorOverlay.hide();
-      const bundles = await fetchDependenciesForSource(source);
-      await createPipeline(
-        this.renderState,
-        source,
-        bundles,
-        this._linkOptions,
-      );
+      await createPipeline(this.renderState!, mainSource, {
+        ...this._linkOptions,
+        weslSrc: this._weslSrc,
+        libs: this._libs,
+        rootModuleName: this._rootModuleName,
+      });
     } catch (error) {
       this.handleCompileError(error);
     }
   }
 
-  /** Compile with pre-loaded library bundles (no network fetch for libs). */
-  private async compileWithLibs(
-    source: string,
-    libs: WeslBundle[],
-  ): Promise<void> {
-    if (!this.renderState) {
-      await this.initialize();
-    }
-    if (!this.renderState) return;
+  /** Discover dependencies and rebuild. For HTTP/inline sources that may need fetching. */
+  private async discoverAndRebuild(): Promise<void> {
+    if (!(await this.initialize())) return;
+
+    const mainSource = this._weslSrc[this._rootModuleName];
+    if (!mainSource) return;
 
     try {
       this.errorOverlay.hide();
-      await createPipeline(this.renderState, source, libs, this._linkOptions);
+      const { weslSrc, libs } = await fetchDependencies(
+        mainSource,
+        this.getConfigOverrides(),
+        undefined,
+        this._weslSrc,
+      );
+      this._weslSrc = { ...this._weslSrc, ...weslSrc };
+      this._libs = [...(this._libs ?? []), ...libs];
+
+      await createPipeline(this.renderState!, mainSource, {
+        ...this._linkOptions,
+        weslSrc: this._weslSrc,
+        libs: this._libs,
+        rootModuleName: this._rootModuleName,
+      });
     } catch (error) {
       this.handleCompileError(error);
     }
@@ -306,3 +381,8 @@ function getStyles(): CSSStyleSheet {
   }
   return styles;
 }
+
+/** Convert file path to module path (e.g., "effects/main.wesl" -> "package::effects::main"). */
+function toModulePath(filePath: string): string {
+  return fileToModulePath(filePath, "package", false);
+}

package/src/index.ts

@@ -1,5 +1,7 @@
 export * from "./BundleHydrator.ts";
 export * from "./BundleLoader.ts";
+export * from "./Config.ts";
+export * from "./HttpPackageLoader.ts";
 export * from "./PackageLoader.ts";
 export * from "./WgslPlay.ts";
 

package/src/test/BundleHydrator.test.ts

@@ -9,7 +9,7 @@ import { loadBundlesFromFiles } from "../BundleHydrator.ts";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const testPkgDir = join(__dirname, "../../../../test_pkg");
+const testPkgDir = join(__dirname, "../../../test_pkg");
 
 function loadBundlesFromTgz(tgzPath: string, packageName: string) {
   const gzipData = readFileSync(tgzPath);