@mudah-cli/vgpu 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { FramePresenter, type FramePresenterOptions, type PresentMode, } from './presenter.js';
+export { ShaderSession, type GpuAdapterKind, type ShaderSessionOptions, } from './session.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { FramePresenter, } from './presenter.js';
+export { ShaderSession, } from './session.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/presenter.d.ts

@@ -0,0 +1,32 @@
+import { type OscWriter, type PixelFormat, type TerminalCapabilities } from '@mudah-cli/terminal';
+export type PresentMode = 'auto' | 'kitty' | 'half';
+export interface FramePresenterOptions {
+    stdout?: OscWriter;
+    capabilities?: TerminalCapabilities;
+    /** Default `auto`: Kitty graphics when the terminal speaks it. */
+    mode?: PresentMode;
+    format?: PixelFormat;
+    /** Image id reused every frame so the placement replaces in place. */
+    id?: number;
+}
+/**
+ * Blit an RGBA/RGB framebuffer to the terminal. Prefers the Kitty graphics
+ * protocol; falls back to unicode half-blocks on terminals that cannot
+ * place images.
+ */
+export declare class FramePresenter {
+    private readonly writer;
+    readonly mode: Exclude<PresentMode, 'auto'>;
+    private readonly format;
+    private readonly gfx;
+    constructor(options?: FramePresenterOptions);
+    /**
+     * Draw `pixels` at the current cursor. For Kitty mode, pass `columns` /
+     * `rows` to scale the image into the cell grid.
+     */
+    present(pixels: Uint8Array, width: number, height: number, layout?: {
+        columns?: number;
+        rows?: number;
+    }): void;
+    clear(): void;
+}

package/dist/presenter.js

@@ -0,0 +1,43 @@
+import { KittyGraphics, detectCapabilities, encodeHalfBlocks, } 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
+ * place images.
+ */
+export class FramePresenter {
+    writer;
+    mode;
+    format;
+    gfx;
+    constructor(options = {}) {
+        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.format = options.format ?? 'rgba';
+        this.gfx = new KittyGraphics(this.writer, { id: options.id ?? 1 });
+    }
+    /**
+     * Draw `pixels` at the current cursor. For Kitty mode, pass `columns` /
+     * `rows` to scale the image into the cell grid.
+     */
+    present(pixels, width, height, layout = {}) {
+        if (this.mode === 'kitty') {
+            this.gfx.draw(pixels, width, height, {
+                format: this.format,
+                columns: layout.columns,
+                rows: layout.rows,
+            });
+            return;
+        }
+        const lines = encodeHalfBlocks(pixels, width, height, this.format);
+        this.writer.write(lines.join('\n'));
+        this.writer.write('\n');
+    }
+    clear() {
+        if (this.mode === 'kitty')
+            this.gfx.delete(true);
+    }
+}
+//# sourceMappingURL=presenter.js.map

package/dist/presenter.js.map

@@ -0,0 +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"}

package/dist/session.d.ts

@@ -0,0 +1,48 @@
+import type { OscWriter } from '@mudah-cli/terminal';
+import { FramePresenter, type PresentMode } from './presenter.js';
+export type GpuAdapterKind = 'auto' | 'hardware' | 'software' | 'mock';
+export interface ShaderSessionOptions {
+    /** Fragment-only WGSL. vgpu injects a fullscreen triangle and `uv`. */
+    shader: string;
+    width?: number;
+    height?: number;
+    /** Initial uniform / texture bindings, keyed by WGSL name. */
+    set?: Record<string, unknown>;
+    adapter?: GpuAdapterKind;
+    stdout?: OscWriter;
+    present?: PresentMode;
+    label?: string;
+}
+/**
+ * A WGSL effect that renders offscreen through vgpu, then blits the pixels
+ * to the terminal. Optional: apps that never import `@mudah-cli/vgpu` never
+ * load Dawn or vgpu.
+ */
+export declare class ShaderSession {
+    readonly width: number;
+    readonly height: number;
+    readonly presenter: FramePresenter;
+    private readonly gpu;
+    private readonly vgpu;
+    private effect;
+    private readonly target;
+    private lastFrame;
+    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;
+    /** Draw one frame and return tightly packed RGBA bytes. */
+    render(): Promise<Uint8Array>;
+    /** Draw, then blit to the terminal. */
+    frame(layout?: {
+        columns?: number;
+        rows?: number;
+    }): Promise<Uint8Array>;
+    /** Re-blit the last rendered frame without another GPU pass. */
+    presentLast(layout?: {
+        columns?: number;
+        rows?: number;
+    }): void;
+    dispose(): void;
+}

package/dist/session.js

@@ -0,0 +1,103 @@
+import { FramePresenter } from './presenter.js';
+async function loadVgpu(adapter) {
+    try {
+        if (adapter === 'mock') {
+            return (await import('vgpu/mock'));
+        }
+        return (await import('vgpu/node'));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`[vgpu] Failed to load the vgpu ${adapter === 'mock' ? 'mock' : 'Node'} adapter (${reason}). Install the vgpu package and, on a machine with no GPU, run \`npx vgpu install-software-renderer\`.`);
+    }
+}
+/**
+ * A WGSL effect that renders offscreen through vgpu, then blits the pixels
+ * to the terminal. Optional: apps that never import `@mudah-cli/vgpu` never
+ * load Dawn or vgpu.
+ */
+export class ShaderSession {
+    width;
+    height;
+    presenter;
+    gpu;
+    vgpu;
+    effect;
+    target;
+    lastFrame;
+    constructor(vgpu, gpu, effect, target, presenter, width, height) {
+        this.vgpu = vgpu;
+        this.gpu = gpu;
+        this.effect = effect;
+        this.target = target;
+        this.presenter = presenter;
+        this.width = width;
+        this.height = height;
+    }
+    static async create(options) {
+        const width = options.width ?? 320;
+        const height = options.height ?? 180;
+        const adapter = options.adapter ?? 'auto';
+        const vgpu = await loadVgpu(adapter);
+        const initOpts = adapter === 'mock' || adapter === 'auto' ? {} : { adapter };
+        const gpu = await vgpu.init(initOpts);
+        const colorTarget = vgpu.target(gpu, { size: [width, height], format: 'rgba8unorm' });
+        const fx = vgpu.effect(gpu, options.shader, {
+            label: options.label ?? 'mudah-vgpu',
+            set: options.set,
+        });
+        const presenter = new FramePresenter({
+            stdout: options.stdout,
+            mode: options.present,
+        });
+        return new ShaderSession(vgpu, gpu, fx, colorTarget, presenter, width, height);
+    }
+    /** Replace the fragment shader without tearing down the GPU device. */
+    useShader(source, set, label) {
+        this.effect = this.vgpu.effect(this.gpu, source, {
+            label: label ?? 'mudah-vgpu',
+            set,
+        });
+        return this;
+    }
+    set(values) {
+        this.effect.set(values);
+        return this;
+    }
+    /** Draw one frame and return tightly packed RGBA bytes. */
+    async render() {
+        const errors = [];
+        const off = this.gpu.onError?.((error) => {
+            errors.push(error);
+        });
+        try {
+            this.effect.draw(this.target);
+            if (this.gpu.settled !== undefined)
+                await this.gpu.settled();
+            if (errors[0] !== undefined)
+                throw errors[0];
+            this.lastFrame = await this.target.read();
+            return this.lastFrame;
+        }
+        finally {
+            off?.();
+        }
+    }
+    /** Draw, then blit to the terminal. */
+    async frame(layout = {}) {
+        const pixels = await this.render();
+        this.presenter.present(pixels, this.width, this.height, layout);
+        return pixels;
+    }
+    /** Re-blit the last rendered frame without another GPU pass. */
+    presentLast(layout = {}) {
+        if (this.lastFrame === undefined)
+            return;
+        this.presenter.present(this.lastFrame, this.width, this.height, layout);
+    }
+    dispose() {
+        this.presenter.clear();
+        this.gpu.dispose();
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@mudah-cli/vgpu",
+  "version": "0.4.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",
+  "engines": {
+    "node": ">=26"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@mudah-cli/terminal": "^0.4.0",
+    "vgpu": "^0.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}