@tty-pt/lamina 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, tty-pt
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @tty-pt/lamina
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/badge/npm-v0.1.0-CB3837?logo=npm)](#)
+[![License: BSD-2-Clause](https://img.shields.io/badge/License-BSD--2--Clause-blue)](#)
+[![TypeScript Ready](https://img.shields.io/badge/TypeScript-Ready-3178C6?logo=typescript)](#)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success)](#)
+
+> Universal Node.js and Browser bindings for **`liblamina`**, the 2D immediate-mode canvas graphics, tilemap rendering, and WebGL viewport engine.
+
+---
+
+## 1. Quickstart
+
+```bash
+npm install @tty-pt/lamina
+```
+
+```typescript
+import { ViewportController } from "@tty-pt/lamina";
+
+const viewport = new ViewportController(1280, 720);
+viewport.setCamera(100, 200, 1.5 /* zoom */);
+
+// Transform game/map coordinates to canvas screen pixels
+const screen = viewport.worldToScreen(100, 200);
+console.log(screen); // { x: 640, y: 360 }
+```
+
+---
+
+## 2. JavaScript / TypeScript API Reference
+
+### `ViewportController`
+2D tilemap and canvas camera viewport controller:
+* `constructor(width?: number, height?: number)`: Initializes viewport with dimensions (default: 640x480).
+* `.setCamera(x: number, y: number, zoom?: number): void`: Updates camera center position and zoom factor.
+* `.worldToScreen(worldX: number, worldY: number): { x: number, y: number }`: Projects continuous world coordinates to screen canvas pixels. **Executes strictly in compiled WebAssembly / C** via `lamina_wasm_world_to_screen()`.
+* `.screenToWorld(screenX: number, screenY: number): { x: number, y: number }`: Unprojects screen canvas pixel coordinates back to continuous world coordinates strictly via WebAssembly.
+
+### `getLaminaWasm(): WebAssembly.Instance`
+Returns the WebAssembly instance loaded on the Stele shared-memory substrate.
+
+### `version(): string`
+Returns the library semantic version string.
+
+---
+
+## 3. C Development Headers via NPM
+
+```makefile
+CFLAGS += -I./node_modules/@tty-pt/lamina/include
+```
+
+## License
+
+BSD 2-Clause License. Copyright (c) 2026, tty-pt.

package/dist/bridge.d.ts

@@ -0,0 +1,10 @@
+export function createLaminaBridge(root?: any, getWasm?: () => any): {
+  mount(): void;
+  makeLaminaImports(): {
+    lam_canvas_flush(buf_ptr: number, width: number, height: number): void;
+    lam_fill(): void;
+    lam_tile_draw(): void;
+    lam_flush(): void;
+  };
+  destroy(): void;
+};

package/dist/bridge.js

@@ -0,0 +1,430 @@
+/*
+ * lamina-bridge.js — Browser WebAssembly bridge for liblamina 2D canvas flush.
+ * Provides the "lamina" WASM import module.
+ *
+ * Automatically mounts onto active [data-bud-canvas] elements.
+ * All 3D scene, shader, camera, mesh, and billboard logic lives in pure C over <ttypt/webgl.h>.
+ */
+
+function getExport(exports, names) {
+	if (!exports) return null;
+	for (const name of names) {
+		if (typeof exports[name] === 'function') return exports[name];
+	}
+	return null;
+}
+
+const VS_QUAD = `attribute vec2 a_pos;
+attribute vec2 a_uv;
+varying vec2 v_uv;
+void main() {
+	v_uv = a_uv;
+	gl_Position = vec4(a_pos, 0.0, 1.0);
+}`;
+
+const FS_QUAD = `precision mediump float;
+varying vec2 v_uv;
+uniform sampler2D u_tex;
+void main() {
+	gl_FragColor = texture2D(u_tex, v_uv);
+}`;
+
+const shaderDefs = new Map();
+let nextShaderId = 1;
+let activeShaderId = 0;
+
+const imageIdsByUrl = new Map();
+const imageCache = new Map();
+let nextImageId = 1;
+
+function compileProgram(gl, vsSrc, fsSrc) {
+	try {
+		const vs = gl.createShader(gl.VERTEX_SHADER);
+		gl.shaderSource(vs, vsSrc);
+		gl.compileShader(vs);
+		if (!gl.getShaderParameter(vs, gl.COMPILE_STATUS)) return null;
+
+		const fs = gl.createShader(gl.FRAGMENT_SHADER);
+		gl.shaderSource(fs, fsSrc);
+		gl.compileShader(fs);
+		if (!gl.getShaderParameter(fs, gl.COMPILE_STATUS)) return null;
+
+		const prog = gl.createProgram();
+		gl.attachShader(prog, vs);
+		gl.attachShader(prog, fs);
+		gl.linkProgram(prog);
+		if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) return null;
+
+		const aPos = gl.getAttribLocation(prog, 'a_pos');
+		const aUv = gl.getAttribLocation(prog, 'a_uv');
+		const uTex = gl.getUniformLocation(prog, 'u_tex');
+		const uTime = gl.getUniformLocation(prog, 'u_time');
+		const uRes = gl.getUniformLocation(prog, 'u_res');
+		const uParams = gl.getUniformLocation(prog, 'u_params');
+		return { prog, aPos, aUv, uTex, uTime, uRes, uParams };
+	} catch (e) {
+		return null;
+	}
+}
+
+function initGlPipeline(gl) {
+	try {
+		const basePipe = compileProgram(gl, VS_QUAD, FS_QUAD);
+		if (!basePipe) return null;
+		gl.useProgram(basePipe.prog);
+
+		const verts = new Float32Array([
+			-1.0, -1.0,  0.0,  1.0,
+			 1.0, -1.0,  1.0,  1.0,
+			-1.0,  1.0,  0.0,  0.0,
+			-1.0,  1.0,  0.0,  0.0,
+			 1.0, -1.0,  1.0,  1.0,
+			 1.0,  1.0,  1.0,  0.0
+		]);
+
+		const vbo = gl.createBuffer();
+		gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
+		gl.bufferData(gl.ARRAY_BUFFER, verts, gl.STATIC_DRAW);
+
+		const tex = gl.createTexture();
+		gl.bindTexture(gl.TEXTURE_2D, tex);
+		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+		gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+
+		return { prog: basePipe.prog, aPos: basePipe.aPos, aUv: basePipe.aUv, tex, vbo, uTex: basePipe.uTex, uTime: basePipe.uTime, uRes: basePipe.uRes };
+	} catch (e) {
+		return null;
+	}
+}
+
+export function createLaminaBridge(root, getWasm) {
+	const targets = new WeakMap();
+	const kicked = new WeakSet();
+	const globalScope = typeof window !== 'undefined' ? window : globalThis;
+
+	function allCanvases() {
+		if (root && typeof root.querySelectorAll === 'function') {
+			let list = root.querySelectorAll('[data-bud-canvas]');
+			if (!list.length && typeof document !== 'undefined' && root !== document && typeof document.querySelectorAll === 'function') {
+				list = document.querySelectorAll('[data-bud-canvas]');
+			}
+			return list;
+		}
+		if (typeof document !== 'undefined' && typeof document.querySelectorAll === 'function') {
+			return document.querySelectorAll('[data-bud-canvas]');
+		}
+		if (globalScope.__stele_worker_canvases instanceof Map) {
+			const res = [];
+			for (const entry of globalScope.__stele_worker_canvases.values()) {
+				if (entry && entry.canvas) res.push(entry.canvas);
+			}
+			return res;
+		}
+		return [];
+	}
+
+	function isFitCanvas(c) {
+		if (!c) return false;
+		if (c.__stele_fit) return true;
+		return !!(c.hasAttribute && c.hasAttribute('data-bud-canvas-fit'));
+	}
+
+	function pickCanvas(width, height) {
+		const list = allCanvases();
+		let first = null, fit = null, fixed = null;
+		for (const c of list) {
+			if (!first) first = c;
+			const isFit = isFitCanvas(c);
+			if (!isFit && c.width === width && c.height === height) return c;
+			if (!fixed && !isFit) fixed = c;
+			if (!fit && isFit) fit = c;
+		}
+		if (fixed && (!fit || (width <= 320 && height <= 320))) {
+			return fixed;
+		}
+		if (fit && width > 0 && height > 0) {
+			fit.width = width;
+			fit.height = height;
+			return fit;
+		}
+		return fixed || fit || first;
+	}
+
+	function targetFor(el) {
+		let t = targets.get(el);
+		if (t) return t;
+		t = { gl: null, glPipe: null, canvas2d: null, shaderPrograms: new Map() };
+		try {
+			const glOpts = { preserveDrawingBuffer: true, alpha: true, antialias: true, depth: true };
+			t.gl = el.getContext('webgl2', glOpts) || el.getContext('webgl', glOpts);
+			if (t.gl) {
+				t.glPipe = initGlPipeline(t.gl);
+			}
+		} catch (e) {
+			t.gl = null;
+			t.glPipe = null;
+		}
+		if (!t.gl || !t.glPipe) {
+			t.gl = null;
+			t.glPipe = null;
+			try {
+				t.canvas2d = el.getContext('2d');
+			} catch (e) {
+				t.canvas2d = null;
+			}
+		}
+		targets.set(el, t);
+		return t;
+	}
+
+	function kickRender() {
+		const fn = getExport(getWasm ? getWasm() : null, ['wasm_canvas_render']);
+		if (fn && typeof requestAnimationFrame === 'function') requestAnimationFrame(() => fn());
+	}
+
+	return {
+		mount() {
+			for (const c of allCanvases()) {
+				if (!kicked.has(c)) {
+					kicked.add(c);
+					kickRender();
+				}
+			}
+		},
+		makeLaminaImports() {
+			return {
+				lam_canvas_flush(buf_ptr, width, height) {
+					const canvasEl = pickCanvas(width, height);
+					if (!canvasEl) return;
+					const t = targetFor(canvasEl);
+					if (!kicked.has(canvasEl)) {
+						kicked.add(canvasEl);
+						kickRender();
+					}
+					const exports = getWasm();
+					if (!exports || !exports.memory) return;
+					const uptr = buf_ptr >>> 0;
+					const byteLen = width * height * 4;
+					if (uptr + byteLen > exports.memory.buffer.byteLength) return;
+
+					const bytes = new Uint8Array(exports.memory.buffer, uptr, byteLen);
+
+					if (t.gl && t.glPipe) {
+						const gl = t.gl;
+						gl.viewport(0, 0, canvasEl.width || width, canvasEl.height || height);
+						gl.disable(gl.DEPTH_TEST);
+						gl.disable(gl.BLEND);
+						gl.depthMask(true);
+						gl.colorMask(true, true, true, true);
+						gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, null);
+
+						let pipe = t.glPipe;
+						let def = null;
+						if (activeShaderId > 0 && shaderDefs.has(activeShaderId)) {
+							def = shaderDefs.get(activeShaderId);
+							if (!t.shaderPrograms.has(activeShaderId)) {
+								const cp = compileProgram(gl, VS_QUAD, def.fragSrc);
+								t.shaderPrograms.set(activeShaderId, cp);
+							}
+							const cp = t.shaderPrograms.get(activeShaderId);
+							if (cp) pipe = cp;
+						}
+
+						gl.useProgram(pipe.prog);
+						if (pipe.uTime) gl.uniform1f(pipe.uTime, performance.now() * 0.001);
+						if (pipe.uRes) gl.uniform2f(pipe.uRes, width, height);
+						if (pipe.uParams && def && def.uniforms) gl.uniform4fv(pipe.uParams, def.uniforms);
+
+						gl.bindBuffer(gl.ARRAY_BUFFER, t.glPipe.vbo);
+						if (pipe.aPos >= 0) {
+							gl.enableVertexAttribArray(pipe.aPos);
+							gl.vertexAttribPointer(pipe.aPos, 2, gl.FLOAT, false, 16, 0);
+						}
+						if (pipe.aUv >= 0) {
+							gl.enableVertexAttribArray(pipe.aUv);
+							gl.vertexAttribPointer(pipe.aUv, 2, gl.FLOAT, false, 16, 8);
+						}
+
+						gl.bindTexture(gl.TEXTURE_2D, t.glPipe.tex);
+						gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, bytes);
+						gl.drawArrays(gl.TRIANGLES, 0, 6);
+						canvasEl.__stele_dirty = true;
+						return;
+					}
+
+					if (t.canvas2d) {
+						const clamped = new Uint8ClampedArray(exports.memory.buffer, uptr, byteLen);
+						const imgData = new ImageData(clamped, width, height);
+						t.canvas2d.putImageData(imgData, 0, 0);
+						canvasEl.__stele_dirty = true;
+					}
+				},
+				lam_shader_register(name_ptr, frag_ptr) {
+					const exports = getWasm();
+					if (!exports || !exports.memory) return 0;
+					const mem = new Uint8Array(exports.memory.buffer);
+					let p = name_ptr >>> 0, name = "";
+					while (p < mem.length && mem[p] !== 0) name += String.fromCharCode(mem[p++]);
+					p = frag_ptr >>> 0;
+					let fragSrc = "";
+					while (p < mem.length && mem[p] !== 0) fragSrc += String.fromCharCode(mem[p++]);
+
+					const id = nextShaderId++;
+					shaderDefs.set(id, { name, fragSrc, uniforms: new Float32Array(16) });
+					return id;
+				},
+				lam_shader_bind(shader_id) {
+					activeShaderId = shader_id >>> 0;
+				},
+				lam_shader_uniforms(shader_id, vals_ptr, count) {
+					const exports = getWasm();
+					if (!exports || !exports.memory) return;
+					const id = shader_id >>> 0;
+					const def = shaderDefs.get(id);
+					if (!def) return;
+					const n = Math.min(count >>> 0, 16);
+					const f32 = new Float32Array(exports.memory.buffer, vals_ptr >>> 0, n);
+					def.uniforms.set(f32);
+				},
+				lam_cam_set_3d() {},
+				lam_cam_set_2d() {},
+				lam_terrain_mesh_flush() {},
+				lam_billboard_batch_flush() {},
+				lam_fill() {},
+				lam_tile_draw() {},
+				lam_flush() {},
+				lam_image_request(url_ptr) {
+					const exports = getWasm();
+					if (!exports || !exports.memory) return 0;
+					const mem = new Uint8Array(exports.memory.buffer);
+					let p = url_ptr >>> 0, url = "";
+					while (p < mem.length && mem[p] !== 0) url += String.fromCharCode(mem[p++]);
+					if (!url) return 0;
+					if (imageIdsByUrl.has(url)) return imageIdsByUrl.get(url);
+
+					const id = nextImageId++;
+					imageIdsByUrl.set(url, id);
+					const rec = { status: 0, w: 0, h: 0, data: null };
+					imageCache.set(id, rec);
+
+					const fetchUrl = (url.startsWith('/') && globalScope.__stele_origin)
+						? `${globalScope.__stele_origin}${url}`
+						: url;
+
+					if (typeof Image !== 'undefined') {
+						const img = new Image();
+						img.decoding = 'async';
+						img.onload = () => {
+							try {
+								const w = img.naturalWidth || img.width || 0;
+								const h = img.naturalHeight || img.height || 0;
+								if (w > 0 && h > 0) {
+									let off = null;
+									if (typeof OffscreenCanvas !== 'undefined') {
+										off = new OffscreenCanvas(w, h);
+									} else if (typeof document !== 'undefined' && document.createElement) {
+										off = document.createElement('canvas');
+										off.width = w;
+										off.height = h;
+									}
+									if (off) {
+										const ctx = off.getContext('2d');
+										if (ctx) {
+											ctx.clearRect(0, 0, w, h);
+											ctx.drawImage(img, 0, 0);
+											const idata = ctx.getImageData(0, 0, w, h);
+											rec.w = w;
+											rec.h = h;
+											rec.data = new Uint8Array(idata.data.buffer.slice(0));
+											rec.status = 1;
+											kickRender();
+											return;
+										}
+									}
+								}
+								rec.status = 2;
+							} catch (e) {
+								rec.status = 2;
+							}
+						};
+						img.onerror = () => { rec.status = 2; };
+						img.src = fetchUrl;
+					} else if (typeof fetch === 'function' && typeof createImageBitmap === 'function' && typeof OffscreenCanvas !== 'undefined') {
+						fetch(fetchUrl)
+							.then((res) => {
+								if (!res.ok) throw new Error('HTTP ' + res.status);
+								return res.blob();
+							})
+							.then((blob) => createImageBitmap(blob))
+							.then((bmp) => {
+								try {
+									const w = bmp.width || 0;
+									const h = bmp.height || 0;
+									if (w > 0 && h > 0) {
+										const off = new OffscreenCanvas(w, h);
+										const ctx = off.getContext('2d');
+										if (ctx) {
+											ctx.clearRect(0, 0, w, h);
+											ctx.drawImage(bmp, 0, 0);
+											const idata = ctx.getImageData(0, 0, w, h);
+											rec.w = w;
+											rec.h = h;
+											rec.data = new Uint8Array(idata.data.buffer.slice(0));
+											rec.status = 1;
+											if (typeof bmp.close === 'function') bmp.close();
+											kickRender();
+											return;
+										}
+									}
+									if (typeof bmp.close === 'function') bmp.close();
+									rec.status = 2;
+								} catch (_) {
+									if (bmp && typeof bmp.close === 'function') bmp.close();
+									rec.status = 2;
+								}
+							})
+							.catch(() => {
+								rec.status = 2;
+							});
+					}
+					return id;
+				},
+				lam_image_read(img_id, dst_ptr, max_bytes, out_w_ptr, out_h_ptr) {
+					const exports = getWasm();
+					if (!exports || !exports.memory) return 0;
+					const rec = imageCache.get(img_id >>> 0);
+					if (!rec || rec.status !== 1 || !rec.data) return 0;
+					const buf = exports.memory.buffer;
+					const dv = new DataView(buf);
+					if (out_w_ptr) dv.setUint32(out_w_ptr >>> 0, rec.w >>> 0, true);
+					if (out_h_ptr) dv.setUint32(out_h_ptr >>> 0, rec.h >>> 0, true);
+					const need = rec.data.byteLength;
+					const uptr = dst_ptr >>> 0;
+					if (uptr && (max_bytes >>> 0) >= need && uptr + need <= buf.byteLength) {
+						new Uint8Array(buf, uptr, need).set(rec.data);
+						return 1;
+					}
+					return 0;
+				}
+			};
+		},
+		destroy() {}
+	};
+}
+
+const _lamGlobal = typeof window !== 'undefined' ? window : globalThis;
+_lamGlobal.__wasm_capability_registry = _lamGlobal.__wasm_capability_registry || {};
+const _lamFactory = (root, getWasm) => {
+	const b = createLaminaBridge(root, getWasm);
+	return {
+		mount() { b.mount(); },
+		destroy() { b.destroy(); },
+		makeImports() { return b.makeLaminaImports(); }
+	};
+};
+_lamGlobal.__wasm_capability_registry.lamina = _lamFactory;
+if (typeof _lamGlobal.registerWasmCapability === 'function') {
+	_lamGlobal.registerWasmCapability('lamina', _lamFactory);
+}

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+export function getLaminaWasm(): any;
+export function createLaminaRenderer(canvasEl: any): {
+  isWebGL(): boolean;
+  render(rgbaBytes: ArrayBufferView, width: number, height: number): void;
+  destroy(): void;
+};
+export function createLaminaBridge(root?: any, getWasm?: () => any): any;
+
+export function rgba(r: number, g: number, b: number, a?: number): number;
+export function rgb(r: number, g: number, b: number): number;
+export function colorR(c: number): number;
+export function colorG(c: number): number;
+export function colorB(c: number): number;
+export function colorA(c: number): number;
+
+export function attachCanvas(canvasEl: any): {
+  isWebGL(): boolean;
+  present(surface: LaminaSurface): void;
+  destroy(): void;
+};
+
+export class LaminaSurface {
+  width: number;
+  height: number;
+  wasmHandle: number;
+  canvas?: any;
+  constructor(width: number, height: number, options?: { canvas?: any });
+  free(): void;
+  clear(color?: number): this;
+  fill(x: number, y: number, w: number, h: number, color: number): this;
+  rect(x: number, y: number, w: number, h: number, color: number, thickness?: number): this;
+  line(x0: number, y0: number, x1: number, y1: number, color: number, thickness?: number): this;
+  paint(x: number, y: number, color: number): this;
+  pick(x: number, y: number): number;
+  getPixels(): Uint32Array;
+  getClampedPixels(): Uint8ClampedArray;
+  flush(targetCanvas?: any): this;
+}
+
+export class ViewportController {
+  width: number;
+  height: number;
+  cameraX: number;
+  cameraY: number;
+  zoom: number;
+  constructor(width?: number, height?: number);
+  setCamera(x: number, y: number, zoom?: number): void;
+  worldToScreen(worldX: number, worldY: number): { x: number; y: number };
+  screenToWorld(screenX: number, screenY: number): { x: number; y: number };
+}
+
+export class FlexNode {
+  wasmHandle: number;
+  constructor(direction?: "row" | "column");
+  setSize(w: number, h: number): this;
+  setPadding(l: number, t: number, r: number, b: number): this;
+  setFlex(grow?: number, shrink?: number): this;
+  addChild(child: FlexNode): this;
+  computeLayout(availableWidth: number, availableHeight: number, startX?: number, startY?: number): this;
+  getBounds(): { x: number; y: number; width: number; height: number };
+  free(): void;
+}
+
+export function version(): string;