@mudah-cli/vgpu 0.7.0 → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mudah Contributors
+
+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,44 @@
+# @mudah-cli/vgpu
+
+Run [vgpu](https://vgpu.sh/) WGSL effects inside a Mudah app and blit the pixels to the terminal
+(Kitty graphics, with a half-block fallback).
+
+**Optional.** The `@mudah-cli/mudah` umbrella does not depend on this package — install it only
+if you want GPU shaders in the terminal.
+
+## Install
+
+```sh
+npm install @mudah-cli/vgpu
+```
+
+On a machine without a GPU, install the software renderer once:
+
+```sh
+npx vgpu install-software-renderer
+```
+
+## Usage
+
+```ts
+import { ShaderSession } from '@mudah-cli/vgpu';
+
+const session = await ShaderSession.create({
+  shader: /* fragment-only WGSL */,
+  width: 320,
+  height: 180,
+});
+
+await session.frame({ columns: 80, rows: 24 }); // draw + blit
+session.dispose();
+```
+
+Also ships a built-in shader catalog (`SHADER_CATALOG`), WGSL `import` resolution, shader
+hot-reload (`watchShader`), an audio-reactive bridge (`bindAudioReactive`), a parameter-slider
+overlay, and framebuffer capture to PNG.
+
+## Links
+
+- [Full documentation](https://github.com/thesimonharms/mudah#readme)
+- [shader-lab example](https://github.com/thesimonharms/mudah/tree/main/examples/shader-lab)
+- [License: MIT](LICENSE)

package/dist/catalog.d.ts

@@ -0,0 +1,6 @@
+/** Built-in fragment snippets. Keys are lowercase catalog ids. */
+export declare const SHADER_CATALOG: Record<string, string>;
+/** Catalog ids in a stable order. */
+export declare function listShaders(): string[];
+/** Look up a catalog snippet. Names are case-insensitive. */
+export declare function getShader(name: string): string;

package/dist/catalog.js

@@ -0,0 +1,87 @@
+const PARAMS = `
+struct Params {
+  time: f32,
+  energy: f32,
+  bass: f32,
+  mid: f32,
+  high: f32,
+  width: f32,
+  height: f32,
+}
+@group(0) @binding(0) var<uniform> params: Params;
+`;
+/** Built-in fragment snippets. Keys are lowercase catalog ids. */
+export const SHADER_CATALOG = {
+    plasma: `${PARAMS}
+@fragment fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
+  let t = params.time;
+  let e = params.energy;
+  let n = sin(uv.x * 8.0 + t) + sin(uv.y * 6.0 - t * 0.7) + sin((uv.x + uv.y) * 4.0 + t * 1.3);
+  let v = 0.5 + 0.5 * sin(n + e);
+  return vec4f(v, 0.35 + 0.45 * sin(n + 2.1), 0.75 + 0.2 * e, 1.0);
+}
+`,
+    metaballs: `${PARAMS}
+@fragment fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
+  let t = params.time;
+  let a = vec2f(0.35 + 0.2 * sin(t), 0.45 + 0.15 * cos(t * 0.8));
+  let b = vec2f(0.65 + 0.18 * cos(t * 1.1), 0.55 + 0.2 * sin(t * 0.9));
+  let c = vec2f(0.5 + 0.22 * sin(t * 0.6), 0.35 + 0.18 * cos(t * 1.4));
+  let field = 0.12 / max(dot(uv - a, uv - a), 0.001)
+    + 0.10 / max(dot(uv - b, uv - b), 0.001)
+    + 0.08 / max(dot(uv - c, uv - c), 0.001);
+  let m = smoothstep(0.85, 1.15, field + params.energy * 0.25);
+  return vec4f(m * 0.2, m * 0.75, m * 0.95, 1.0);
+}
+`,
+    fire: `${PARAMS}
+@fragment fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
+  let t = params.time;
+  let flicker = sin(uv.x * 18.0 + t * 6.0) * sin(uv.y * 11.0 - t * 4.0);
+  let rise = 1.0 - uv.y;
+  let heat = rise * rise * (0.7 + 0.3 * flicker + params.energy * 0.4);
+  let col = vec3f(heat, heat * 0.45, heat * 0.08);
+  return vec4f(col, 1.0);
+}
+`,
+    voronoi: `${PARAMS}
+@fragment fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
+  let t = params.time * 0.15;
+  var cell = floor(uv * 6.0);
+  var local = fract(uv * 6.0);
+  var md = 8.0;
+  for (var j = -1; j <= 1; j++) {
+    for (var i = -1; i <= 1; i++) {
+      let neighbor = vec2f(f32(i), f32(j));
+      let seed = cell + neighbor;
+      let p = neighbor + 0.5 + 0.5 * sin(vec2f(seed.x * 3.1 + t, seed.y * 2.7 - t));
+      md = min(md, length(local - p));
+    }
+  }
+  let edge = smoothstep(0.0, 0.18, md);
+  let e = params.energy;
+  return vec4f(edge * 0.15 + e * 0.2, edge * 0.55, 0.85 - edge * 0.3, 1.0);
+}
+`,
+};
+const ALIASES = {
+    plasma: 'plasma',
+    metaballs: 'metaballs',
+    metaball: 'metaballs',
+    fire: 'fire',
+    voronoi: 'voronoi',
+};
+/** Catalog ids in a stable order. */
+export function listShaders() {
+    return Object.keys(SHADER_CATALOG);
+}
+/** Look up a catalog snippet. Names are case-insensitive. */
+export function getShader(name) {
+    const key = ALIASES[name.toLowerCase()];
+    const source = key === undefined ? undefined : SHADER_CATALOG[key];
+    if (source === undefined) {
+        throw new Error(`[vgpu] Unknown shader "${name}". Available: ${listShaders().join(', ')}`);
+    }
+    return source;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,GAAG;;;;;;;;;;;CAWd,CAAC;AAEF,kEAAkE;AAClE,MAAM,CAAC,MAAM,cAAc,GAA2B;IACpD,MAAM,EAAE,GAAG,MAAM;;;;;;;;CAQlB;IACC,SAAS,EAAE,GAAG,MAAM;;;;;;;;;;;;CAYrB;IACC,IAAI,EAAE,GAAG,MAAM;;;;;;;;;CAShB;IACC,OAAO,EAAE,GAAG,MAAM;;;;;;;;;;;;;;;;;;CAkBnB;CACA,CAAC;AAEF,MAAM,OAAO,GAA2B;IACtC,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;IACtB,QAAQ,EAAE,WAAW;IACrB,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;CACnB,CAAC;AAEF,qCAAqC;AACrC,MAAM,UAAU,WAAW;IACzB,OAAO,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AACrC,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IACnE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,iBAAiB,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/include.d.ts

@@ -0,0 +1,11 @@
+export interface ResolveWgslOptions {
+    /** File reader for included paths (default `readFileSync`). */
+    readFile?: (path: string) => string;
+    /** Directory that relative includes resolve against. Default `process.cwd()`. */
+    baseDir?: string;
+}
+/**
+ * Expand `#include "foo.wgsl"` and `// @import foo` (or `@import foo`)
+ * directives. Detects include cycles.
+ */
+export declare function resolveWgsl(source: string, options?: ResolveWgslOptions): string;

package/dist/include.js

@@ -0,0 +1,51 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const INCLUDE = /^[ \t]*(?:#include\s+["'<]([^"'>]+)["'>]|\/\/\s*@import\s+["']?([^\s"']+)["']?|@import\s+["']?([^\s"']+)["']?)\s*$/;
+/**
+ * Expand `#include "foo.wgsl"` and `// @import foo` (or `@import foo`)
+ * directives. Detects include cycles.
+ */
+export function resolveWgsl(source, options = {}) {
+    const readFile = options.readFile ?? defaultRead;
+    const baseDir = options.baseDir ?? process.cwd();
+    return expand(source, baseDir, [], readFile, '<source>');
+}
+function defaultRead(path) {
+    return readFileSync(path, 'utf8');
+}
+function parseInclude(line) {
+    const match = INCLUDE.exec(line);
+    if (match === null)
+        return undefined;
+    return match[1] ?? match[2] ?? match[3];
+}
+function withExtension(spec) {
+    return spec.endsWith('.wgsl') ? spec : `${spec}.wgsl`;
+}
+function expand(source, baseDir, stack, readFile, current) {
+    if (stack.includes(current)) {
+        throw new Error(`[vgpu] Circular WGSL include: ${[...stack, current].join(' -> ')}`);
+    }
+    const nextStack = [...stack, current];
+    const lines = source.split(/\r?\n/);
+    const out = [];
+    for (const line of lines) {
+        const spec = parseInclude(line);
+        if (spec === undefined) {
+            out.push(line);
+            continue;
+        }
+        const resolved = join(baseDir, withExtension(spec));
+        let body;
+        try {
+            body = readFile(resolved);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`[vgpu] Cannot read WGSL include "${resolved}" (${reason}).`);
+        }
+        out.push(expand(body, dirname(resolved), nextStack, readFile, resolved));
+    }
+    return out.join('\n');
+}
+//# sourceMappingURL=include.js.map

package/dist/include.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"include.js","sourceRoot":"","sources":["../src/include.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAS1C,MAAM,OAAO,GACX,oHAAoH,CAAC;AAEvH;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,OAAO,GAAuB,EAAE;IAC1E,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,WAAW,CAAC;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACjD,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACrC,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC;AACxD,CAAC;AAED,SAAS,MAAM,CACb,MAAc,EACd,OAAe,EACf,KAAwB,EACxB,QAAkC,EAClC,OAAe;IAEf,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,GAAG,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,SAAS,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACf,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;QACpD,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtE,MAAM,IAAI,KAAK,CAAC,oCAAoC,QAAQ,MAAM,MAAM,IAAI,CAAC,CAAC;QAChF,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,9 @@
+export { getShader, listShaders, SHADER_CATALOG } from './catalog.js';
+export { type ResolveWgslOptions, resolveWgsl } from './include.js';
+export { type ParticleComputeOptions, type ParticleComputeResult, runParticleCompute, } from './particles.js';
+export { capturePng } from './png.js';
 export { FramePresenter, type FramePresenterOptions, type PresentMode, } from './presenter.js';
-export { ShaderSession, type GpuAdapterKind, type ShaderSessionOptions, } from './session.js';
+export { type AudioReactiveBinding, type AudioReactiveSource, type BindAudioReactiveOptions, bindAudioReactive, type ShaderUniformTarget, } from './reactive.js';
+export { type GpuAdapterKind, ShaderSession, type ShaderSessionOptions, } from './session.js';
+export { type ShaderSliderParam, ShaderSliders, type ShaderSlidersOptions, } from './sliders.js';
+export { parseWatchFlag, type ShaderWatchFn, type WatchShaderOptions, watchShader, } from './watch.js';

package/dist/index.js

@@ -1,3 +1,10 @@
+export { getShader, listShaders, SHADER_CATALOG } from './catalog.js';
+export { resolveWgsl } from './include.js';
+export { runParticleCompute, } from './particles.js';
+export { capturePng } from './png.js';
 export { FramePresenter, } from './presenter.js';
+export { bindAudioReactive, } from './reactive.js';
 export { ShaderSession, } from './session.js';
+export { ShaderSliders, } from './sliders.js';
+export { parseWatchFlag, watchShader, } from './watch.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAGf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,aAAa,GAGd,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAA2B,WAAW,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EAGL,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EACL,cAAc,GAGf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAIL,iBAAiB,GAElB,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,aAAa,GAEd,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,aAAa,GAEd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EAGd,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/particles.d.ts

@@ -0,0 +1,21 @@
+export interface ParticleComputeOptions {
+    /** Number of particles (vec2 positions). */
+    count: number;
+    /** Timestep in seconds. */
+    dt: number;
+    /** Interleaved x,y. Length `count * 2`. Allocated when omitted. */
+    positions?: Float32Array;
+    /** Interleaved vx,vy. Length `count * 2`. Allocated when omitted. */
+    velocities?: Float32Array;
+    /** Downward acceleration applied to vy. Default 0. */
+    gravity?: number;
+}
+export interface ParticleComputeResult {
+    positions: Float32Array;
+    velocities: Float32Array;
+}
+/**
+ * Software compute pass for particle physics (semi-implicit Euler).
+ * `ShaderSession` has no GPU compute path, so this runs on the CPU.
+ */
+export declare function runParticleCompute(options: ParticleComputeOptions): ParticleComputeResult;

package/dist/particles.js

@@ -0,0 +1,43 @@
+/**
+ * Software compute pass for particle physics (semi-implicit Euler).
+ * `ShaderSession` has no GPU compute path, so this runs on the CPU.
+ */
+export function runParticleCompute(options) {
+    const count = Math.max(0, Math.floor(options.count));
+    const dt = options.dt;
+    const gravity = options.gravity ?? 0;
+    const positions = ensureVec2(options.positions, count, (i) => seedPosition(i, count));
+    const velocities = ensureVec2(options.velocities, count, () => [0, 0]);
+    for (let i = 0; i < count; i++) {
+        const ix = i * 2;
+        const iy = ix + 1;
+        const vy = (velocities[iy] ?? 0) + gravity * dt;
+        velocities[iy] = vy;
+        positions[ix] = (positions[ix] ?? 0) + (velocities[ix] ?? 0) * dt;
+        positions[iy] = (positions[iy] ?? 0) + vy * dt;
+    }
+    return { positions, velocities };
+}
+function ensureVec2(input, count, fill) {
+    const needed = count * 2;
+    if (input !== undefined && input.length >= needed)
+        return input;
+    const out = new Float32Array(needed);
+    if (input !== undefined)
+        out.set(input.subarray(0, Math.min(input.length, needed)));
+    for (let i = 0; i < count; i++) {
+        if (input !== undefined && i * 2 + 1 < input.length)
+            continue;
+        const [x, y] = fill(i);
+        out[i * 2] = x;
+        out[i * 2 + 1] = y;
+    }
+    return out;
+}
+function seedPosition(index, count) {
+    if (count <= 0)
+        return [0, 0];
+    const angle = (index / count) * Math.PI * 2;
+    return [0.5 + 0.25 * Math.cos(angle), 0.5 + 0.25 * Math.sin(angle)];
+}
+//# sourceMappingURL=particles.js.map

package/dist/particles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"particles.js","sourceRoot":"","sources":["../src/particles.ts"],"names":[],"mappings":"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"}

package/dist/png.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Encode tightly packed RGBA8 pixels as an uncompressed-filter PNG
+ * (IHDR + zlib IDAT + IEND). Filter byte 0 on every scanline.
+ */
+export declare function capturePng(rgba: Uint8Array, width: number, height: number): Uint8Array;

package/dist/png.js

@@ -0,0 +1,82 @@
+import { deflateSync } from 'node:zlib';
+const PNG_SIG = Uint8Array.of(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a);
+const CRC_TABLE = makeCrcTable();
+function makeCrcTable() {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++) {
+            c = (c & 1) === 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        }
+        table[n] = c >>> 0;
+    }
+    return table;
+}
+function crc32(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i++) {
+        c = (CRC_TABLE[(c ^ (bytes[i] ?? 0)) & 0xff] ?? 0) ^ (c >>> 8);
+    }
+    return (c ^ 0xffffffff) >>> 0;
+}
+function u32(value) {
+    const out = new Uint8Array(4);
+    const view = new DataView(out.buffer);
+    view.setUint32(0, value >>> 0, false);
+    return out;
+}
+function concat(parts) {
+    let length = 0;
+    for (const part of parts)
+        length += part.byteLength;
+    const out = new Uint8Array(length);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.byteLength;
+    }
+    return out;
+}
+function chunk(type, data) {
+    const tag = new Uint8Array(4);
+    for (let i = 0; i < 4; i++)
+        tag[i] = type.charCodeAt(i);
+    const body = concat([tag, data]);
+    return concat([u32(data.byteLength), body, u32(crc32(body))]);
+}
+/**
+ * Encode tightly packed RGBA8 pixels as an uncompressed-filter PNG
+ * (IHDR + zlib IDAT + IEND). Filter byte 0 on every scanline.
+ */
+export function capturePng(rgba, width, height) {
+    if (width < 1 || height < 1) {
+        throw new Error(`[vgpu] capturePng needs a positive size, got ${width}x${height}.`);
+    }
+    const expected = width * height * 4;
+    if (rgba.byteLength < expected) {
+        throw new Error(`[vgpu] RGBA buffer is ${rgba.byteLength} bytes, need ${expected}.`);
+    }
+    const ihdr = new Uint8Array(13);
+    const ihdrView = new DataView(ihdr.buffer);
+    ihdrView.setUint32(0, width, false);
+    ihdrView.setUint32(4, height, false);
+    ihdr[8] = 8;
+    ihdr[9] = 6;
+    ihdr[10] = 0;
+    ihdr[11] = 0;
+    ihdr[12] = 0;
+    const stride = width * 4;
+    const raw = new Uint8Array(height * (1 + stride));
+    for (let y = 0; y < height; y++) {
+        const dest = y * (1 + stride);
+        raw[dest] = 0;
+        raw.set(rgba.subarray(y * stride, y * stride + stride), dest + 1);
+    }
+    return concat([
+        PNG_SIG,
+        chunk('IHDR', ihdr),
+        chunk('IDAT', deflateSync(raw)),
+        chunk('IEND', new Uint8Array(0)),
+    ]);
+}
+//# sourceMappingURL=png.js.map

package/dist/png.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"png.js","sourceRoot":"","sources":["../src/png.ts"],"names":[],"mappings":"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"}

package/dist/presenter.js

@@ -1,4 +1,4 @@
-import { KittyGraphics, detectCapabilities, encodeHalfBlocks, } from '@mudah-cli/terminal';
+import { detectCapabilities, encodeHalfBlocks, KittyGraphics, } from '@mudah-cli/terminal';
 /**
  * Blit an RGBA/RGB framebuffer to the terminal. Prefers the Kitty graphics
  * protocol; falls back to unicode half-blocks on terminals that cannot
@@ -13,8 +13,7 @@ export class FramePresenter {
         this.writer = options.stdout ?? process.stdout;
         const caps = options.capabilities ?? detectCapabilities();
         const requested = options.mode ?? 'auto';
-        this.mode =
-            requested === 'auto' ? (caps.kittyGraphics ? 'kitty' : 'half') : requested;
+        this.mode = requested === 'auto' ? (caps.kittyGraphics ? 'kitty' : 'half') : requested;
         this.format = options.format ?? 'rgba';
         this.gfx = new KittyGraphics(this.writer, { id: options.id ?? 1 });
     }

package/dist/presenter.js.map

@@ -1 +1 @@
-{"version":3,"file":"presenter.js","sourceRoot":"","sources":["../src/presenter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,gBAAgB,GAIjB,MAAM,qBAAqB,CAAC;AAc7B;;;;GAIG;AACH,MAAM,OAAO,cAAc;IACR,MAAM,CAAY;IAC1B,IAAI,CAA+B;IAC3B,MAAM,CAAc;IACpB,GAAG,CAAgB;IAEpC,YAAY,OAAO,GAA0B,EAAE;QAC7C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;QAC/C,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,IAAI,kBAAkB,EAAE,CAAC;QAC1D,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;QACzC,IAAI,CAAC,IAAI;YACP,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7E,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC;QACvC,IAAI,CAAC,GAAG,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IAED;;;OAGG;IACH,OAAO,CACL,MAAkB,EAClB,KAAa,EACb,MAAc,EACd,MAAM,GAAwC,EAAE;QAEhD,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC1B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE;gBACnC,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EAAE,MAAM,CAAC,IAAI;aAClB,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACnE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;YAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;CACF"}
+{"version":3,"file":"presenter.js","sourceRoot":"","sources":["../src/presenter.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,GAId,MAAM,qBAAqB,CAAC;AAc7B;;;;GAIG;AACH,MAAM,OAAO,cAAc;IACR,MAAM,CAAY;IAC1B,IAAI,CAA+B;IAC3B,MAAM,CAAc;IACpB,GAAG,CAAgB;IAEpC,YAAY,OAAO,GAA0B,EAAE;QAC7C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;QAC/C,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,IAAI,kBAAkB,EAAE,CAAC;QAC1D,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACvF,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC;QACvC,IAAI,CAAC,GAAG,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IAED;;;OAGG;IACH,OAAO,CACL,MAAkB,EAClB,KAAa,EACb,MAAc,EACd,MAAM,GAAwC,EAAE;QAEhD,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC1B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE;gBACnC,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EAAE,MAAM,CAAC,IAAI;aAClB,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACnE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;YAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;CACF"}

package/dist/reactive.d.ts

@@ -0,0 +1,22 @@
+export interface AudioReactiveSource {
+    bands(): number[];
+    energy(): number;
+}
+export interface ShaderUniformTarget {
+    setUniforms?(values: Record<string, unknown>): unknown;
+    set?(values: Record<string, unknown>): unknown;
+}
+export interface BindAudioReactiveOptions {
+    /** Write uniforms flat, nested under `params`, or both. Default `both`. */
+    binding?: 'flat' | 'params' | 'both';
+}
+export interface AudioReactiveBinding {
+    /** Read the source and write uniforms now. */
+    sync(): Record<string, number>;
+    dispose(): void;
+}
+/**
+ * Drive shader uniforms `energy`, `bass`, `mid`, `high` from an audio
+ * source (typically `@mudah-cli/audio` `createReactiveBridge()`).
+ */
+export declare function bindAudioReactive(session: ShaderUniformTarget, source: AudioReactiveSource, options?: BindAudioReactiveOptions): AudioReactiveBinding;

package/dist/reactive.js

@@ -0,0 +1,49 @@
+/**
+ * Drive shader uniforms `energy`, `bass`, `mid`, `high` from an audio
+ * source (typically `@mudah-cli/audio` `createReactiveBridge()`).
+ */
+export function bindAudioReactive(session, source, options = {}) {
+    const binding = options.binding ?? 'both';
+    let disposed = false;
+    const sync = () => {
+        const energy = source.energy();
+        const bands = source.bands();
+        const bass = pickBand(bands, 0, 0, 0.25);
+        const mid = pickBand(bands, 1, 0.25, 0.7);
+        const high = pickBand(bands, 2, 0.7, 1);
+        const values = { energy, bass, mid, high };
+        if (!disposed)
+            writeUniforms(session, values, binding);
+        return values;
+    };
+    return {
+        sync,
+        dispose() {
+            disposed = true;
+        },
+    };
+}
+function pickBand(bands, index, startFrac, endFrac) {
+    if (bands.length === 0)
+        return 0;
+    if (bands.length === 3)
+        return bands[index] ?? 0;
+    const start = Math.floor(startFrac * bands.length);
+    const end = Math.max(start + 1, Math.ceil(endFrac * bands.length));
+    let sum = 0;
+    let n = 0;
+    for (let i = start; i < end && i < bands.length; i++) {
+        sum += bands[i] ?? 0;
+        n += 1;
+    }
+    return n === 0 ? 0 : sum / n;
+}
+function writeUniforms(session, values, binding) {
+    const payload = binding === 'flat' ? values : binding === 'params' ? { params: values } : { ...values, params: values };
+    if (session.setUniforms !== undefined) {
+        session.setUniforms(payload);
+        return;
+    }
+    session.set?.(payload);
+}
+//# sourceMappingURL=reactive.js.map

package/dist/reactive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactive.js","sourceRoot":"","sources":["../src/reactive.ts"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA4B,EAC5B,MAA2B,EAC3B,OAAO,GAA6B,EAAE;IAEtC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAC1C,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,MAAM,IAAI,GAAG,GAA2B,EAAE;QACxC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;QACzC,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;QAC3C,IAAI,CAAC,QAAQ;YAAE,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QACvD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IAEF,OAAO;QACL,IAAI;QACJ,OAAO;YACL,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,KAAe,EAAE,KAAa,EAAE,SAAiB,EAAE,OAAe;IAClF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACjC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrD,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC,IAAI,CAAC,CAAC;IACT,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,aAAa,CACpB,OAA4B,EAC5B,MAA8B,EAC9B,OAAmC;IAEnC,MAAM,OAAO,GACX,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1G,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACtC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC7B,OAAO;IACT,CAAC;IACD,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC"}

package/dist/session.d.ts

@@ -27,11 +27,19 @@ export declare class ShaderSession {
     private effect;
     private readonly target;
     private lastFrame;
+    private lastUniforms;
     private constructor();
     static create(options: ShaderSessionOptions): Promise<ShaderSession>;
     /** Replace the fragment shader without tearing down the GPU device. */
     useShader(source: string, set?: Record<string, unknown>, label?: string): this;
     set(values: Record<string, unknown>): this;
+    /**
+     * Merge a uniform record for audio-reactive / slider helpers.
+     * Best-effort GPU write: missing WGSL bindings are kept on the session.
+     */
+    setUniforms(values: Record<string, unknown>): this;
+    /** Last values passed to `set` / `setUniforms` / `useShader`. */
+    uniforms(): Record<string, unknown>;
     /** Draw one frame and return tightly packed RGBA bytes. */
     render(): Promise<Uint8Array>;
     /** Draw, then blit to the terminal. */
@@ -44,5 +52,7 @@ export declare class ShaderSession {
         columns?: number;
         rows?: number;
     }): void;
+    /** Encode the last (or a freshly rendered) RGBA frame as PNG. */
+    capturePng(): Promise<Uint8Array>;
     dispose(): void;
 }

package/dist/session.js

@@ -1,3 +1,4 @@
+import { capturePng } from './png.js';
 import { FramePresenter } from './presenter.js';
 async function loadVgpu(adapter) {
     try {
@@ -25,6 +26,7 @@ export class ShaderSession {
     effect;
     target;
     lastFrame;
+    lastUniforms = {};
     constructor(vgpu, gpu, effect, target, presenter, width, height) {
         this.vgpu = vgpu;
         this.gpu = gpu;
@@ -50,7 +52,10 @@ export class ShaderSession {
             stdout: options.stdout,
             mode: options.present,
         });
-        return new ShaderSession(vgpu, gpu, fx, colorTarget, presenter, width, height);
+        const session = new ShaderSession(vgpu, gpu, fx, colorTarget, presenter, width, height);
+        if (options.set !== undefined)
+            session.lastUniforms = { ...options.set };
+        return session;
     }
     /** Replace the fragment shader without tearing down the GPU device. */
     useShader(source, set, label) {
@@ -58,12 +63,38 @@ export class ShaderSession {
             label: label ?? 'mudah-vgpu',
             set,
         });
+        if (set !== undefined)
+            this.lastUniforms = { ...this.lastUniforms, ...set };
         return this;
     }
     set(values) {
+        this.lastUniforms = { ...this.lastUniforms, ...values };
         this.effect.set(values);
         return this;
     }
+    /**
+     * Merge a uniform record for audio-reactive / slider helpers.
+     * Best-effort GPU write: missing WGSL bindings are kept on the session.
+     */
+    setUniforms(values) {
+        this.lastUniforms = { ...this.lastUniforms, ...flattenUniforms(values) };
+        try {
+            this.effect.set(values);
+        }
+        catch {
+            try {
+                this.effect.set({ params: this.lastUniforms });
+            }
+            catch {
+                // Shader has no matching bindings; values stay on `uniforms()`.
+            }
+        }
+        return this;
+    }
+    /** Last values passed to `set` / `setUniforms` / `useShader`. */
+    uniforms() {
+        return { ...this.lastUniforms };
+    }
     /** Draw one frame and return tightly packed RGBA bytes. */
     async render() {
         const errors = [];
@@ -95,9 +126,23 @@ export class ShaderSession {
             return;
         this.presenter.present(this.lastFrame, this.width, this.height, layout);
     }
+    /** Encode the last (or a freshly rendered) RGBA frame as PNG. */
+    async capturePng() {
+        const pixels = this.lastFrame ?? (await this.render());
+        return capturePng(pixels, this.width, this.height);
+    }
     dispose() {
         this.presenter.clear();
         this.gpu.dispose();
     }
 }
+function flattenUniforms(values) {
+    const out = { ...values };
+    const params = values['params'];
+    if (params !== undefined && typeof params === 'object' && params !== null && !Array.isArray(params)) {
+        Object.assign(out, params);
+        delete out['params'];
+    }
+    return out;
+}
 //# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/sliders.d.ts

@@ -0,0 +1,23 @@
+export interface ShaderSliderParam {
+    name: string;
+    min: number;
+    max: number;
+    value: number;
+}
+export interface ShaderSlidersOptions {
+    /** Bar width in cells. Default 8. */
+    width?: number;
+}
+/**
+ * Data model for shader parameter sliders. `renderLines()` is a TUI overlay
+ * fragment — enough to paint next to a framebuffer without a full Program.
+ */
+export declare class ShaderSliders {
+    readonly params: ShaderSliderParam[];
+    private readonly width;
+    constructor(params: readonly ShaderSliderParam[], options?: ShaderSlidersOptions);
+    set(name: string, value: number): void;
+    snapshot(): Record<string, number>;
+    /** One line per param, e.g. `energy [████░░] 0.62`. */
+    renderLines(): string[];
+}

package/dist/sliders.js

@@ -0,0 +1,51 @@
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Data model for shader parameter sliders. `renderLines()` is a TUI overlay
+ * fragment — enough to paint next to a framebuffer without a full Program.
+ */
+export class ShaderSliders {
+    params;
+    width;
+    constructor(params, options = {}) {
+        this.params = params.map((param) => ({
+            name: param.name,
+            min: param.min,
+            max: param.max,
+            value: clamp(param.value, param.min, param.max),
+        }));
+        this.width = options.width ?? 8;
+    }
+    set(name, value) {
+        const param = this.params.find((entry) => entry.name === name);
+        if (param === undefined)
+            throw new Error(`[vgpu] Unknown slider "${name}".`);
+        param.value = clamp(value, param.min, param.max);
+    }
+    snapshot() {
+        const out = {};
+        for (const param of this.params)
+            out[param.name] = param.value;
+        return out;
+    }
+    /** One line per param, e.g. `energy [████░░] 0.62`. */
+    renderLines() {
+        const nameWidth = Math.max(0, ...this.params.map((param) => param.name.length));
+        return this.params.map((param) => {
+            const span = param.max - param.min;
+            const t = span === 0 ? 1 : (param.value - param.min) / span;
+            const filled = Math.round(this.width * clamp(t, 0, 1));
+            const bar = `${'█'.repeat(filled)}${'░'.repeat(this.width - filled)}`;
+            const name = param.name.padEnd(nameWidth);
+            return `${name} [${bar}] ${formatValue(param.value)}`;
+        });
+    }
+}
+function formatValue(value) {
+    const abs = Math.abs(value);
+    if (abs !== 0 && (abs < 0.01 || abs >= 100))
+        return value.toFixed(2);
+    return value.toFixed(2);
+}
+//# sourceMappingURL=sliders.js.map

package/dist/sliders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sliders.js","sourceRoot":"","sources":["../src/sliders.ts"],"names":[],"mappings":"AAYA,SAAS,KAAK,CAAC,KAAa,EAAE,GAAW,EAAE,GAAW;IACpD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,aAAa;IACf,MAAM,CAAsB;IACpB,KAAK,CAAS;IAE/B,YAAY,MAAoC,EAAE,OAAO,GAAyB,EAAE;QAClF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACnC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC;SAChD,CAAC,CAAC,CAAC;QACJ,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,IAAY,EAAE,KAAa;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QAC/D,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,IAAI,IAAI,CAAC,CAAC;QAC7E,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IACnD,CAAC;IAED,QAAQ;QACN,MAAM,GAAG,GAA2B,EAAE,CAAC;QACvC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM;YAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC;QAC/D,OAAO,GAAG,CAAC;IACb,CAAC;IAED,uDAAuD;IACvD,WAAW;QACT,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAChF,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;YACnC,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;YAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACvD,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC;YACtE,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC1C,OAAO,GAAG,IAAI,KAAK,GAAG,KAAK,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACxD,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,IAAI,GAAG,IAAI,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACrE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC1B,CAAC"}

package/dist/watch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal `fs.watch` surface. Tests inject a fake so they never touch the
+ * real filesystem or need a live file.
+ */
+export type ShaderWatchFn = (path: string, listener: (eventType: string, filename: string | Buffer | null) => void) => {
+    close(): void;
+};
+export interface WatchShaderOptions {
+    /** Aborting this signal disposes the watcher. */
+    signal?: AbortSignal;
+    /** Watch implementation (default `fs.watch`). */
+    watch?: ShaderWatchFn;
+    /** File reader invoked when the watcher fires (default `readFileSync`). */
+    readFile?: (path: string) => string;
+}
+/**
+ * Watch a WGSL file and invoke `onChange` with the new source on every
+ * filesystem event. Returns a disposer. `signal` abort is equivalent to
+ * calling the disposer.
+ */
+export declare function watchShader(path: string, onChange: (source: string) => void, options?: WatchShaderOptions): () => void;
+/** True when `argv` contains `--watch` or `-w`. */
+export declare function parseWatchFlag(argv?: readonly string[]): boolean;

package/dist/watch.js

@@ -0,0 +1,53 @@
+import { watch as fsWatch, readFileSync } from 'node:fs';
+/**
+ * Watch a WGSL file and invoke `onChange` with the new source on every
+ * filesystem event. Returns a disposer. `signal` abort is equivalent to
+ * calling the disposer.
+ */
+export function watchShader(path, onChange, options = {}) {
+    const watchFn = options.watch ?? defaultWatch;
+    const read = options.readFile ?? defaultRead;
+    let watcher;
+    const dispose = () => {
+        if (watcher === undefined)
+            return;
+        try {
+            watcher.close();
+        }
+        catch {
+            // already closed
+        }
+        watcher = undefined;
+    };
+    if (options.signal?.aborted)
+        return dispose;
+    const fire = () => {
+        try {
+            onChange(read(path));
+        }
+        catch {
+            // Missing file or the reader rejected the path.
+        }
+    };
+    try {
+        watcher = watchFn(path, () => {
+            fire();
+        });
+    }
+    catch {
+        return dispose;
+    }
+    options.signal?.addEventListener('abort', dispose, { once: true });
+    return dispose;
+}
+function defaultWatch(path, listener) {
+    return fsWatch(path, listener);
+}
+function defaultRead(path) {
+    return readFileSync(path, 'utf8');
+}
+/** True when `argv` contains `--watch` or `-w`. */
+export function parseWatchFlag(argv = process.argv) {
+    return argv.includes('--watch') || argv.includes('-w');
+}
+//# sourceMappingURL=watch.js.map

package/dist/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAoBzD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,IAAY,EACZ,QAAkC,EAClC,OAAO,GAAuB,EAAE;IAEhC,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;IAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,IAAI,WAAW,CAAC;IAC7C,IAAI,OAAsC,CAAC;IAE3C,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO;QAClC,IAAI,CAAC;YACH,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;QAAC,MAAM,CAAC;YACP,iBAAiB;QACnB,CAAC;QACD,OAAO,GAAG,SAAS,CAAC;IACtB,CAAC,CAAC;IAEF,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5C,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,gDAAgD;QAClD,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,CAAC;QACH,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE;YAC3B,IAAI,EAAE,CAAC;QACT,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACnE,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,YAAY,CACnB,IAAY,EACZ,QAAuE;IAEvE,OAAO,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,cAAc,CAAC,IAAI,GAAsB,OAAO,CAAC,IAAI;IACnE,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACzD,CAAC"}

package/package.json

@@ -1,9 +1,24 @@
 {
   "name": "@mudah-cli/vgpu",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Run vgpu WGSL effects inside a Mudah app and blit the pixels to the terminal (Kitty graphics, with a half-block fallback).",
   "type": "module",
   "license": "MIT",
+  "author": "Mudah Contributors",
+  "homepage": "https://github.com/thesimonharms/mudah#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thesimonharms/mudah.git",
+    "directory": "packages/vgpu"
+  },
+  "keywords": [
+    "terminal",
+    "gpu",
+    "wgsl",
+    "shader",
+    "kitty",
+    "typescript"
+  ],
   "engines": {
     "node": ">=26"
   },
@@ -18,7 +33,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@mudah-cli/terminal": "^0.7.0",
+    "@mudah-cli/terminal": "^0.9.0",
     "vgpu": "^0.3.1"
   },
   "publishConfig": {