threejs-debug-compose 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio Bonet
+
+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,162 @@
+# threejs-debug-compose
+
+[![npm version](https://img.shields.io/npm/v/threejs-debug-compose.svg)](https://www.npmjs.com/package/threejs-debug-compose)
+[![license](https://img.shields.io/npm/l/threejs-debug-compose.svg)](./LICENSE)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/threejs-debug-compose.svg)](https://bundlephobia.com/package/threejs-debug-compose)
+
+Composable TSL debug views for a Three.js WebGPU render pipeline.
+
+The demo renders the scene into compact WebGPU MRT passes, exposes Beauty/Normal/Depth plus packed material buffers, and composites them through a fullscreen `RenderPipeline`.
+
+![threejs-debug-compose composed viewport banner](./assets/readme-compose-banner.png)
+
+## Quick Start
+
+```tsx
+import { DebugViews } from "./components/debug-views"
+
+<DebugViews
+  views={[
+    { label: "Beauty", source: "beauty", mode: "passthrough" },
+    { label: "Normal", source: "normal", mode: "passthrough" },
+    { label: "Depth", source: "depth", mode: "depth" },
+    { label: "Base Color / Albedo", source: "albedo", mode: "passthrough" },
+  ]}
+  layout="single"
+  activeView={0}
+/>
+```
+
+## Built-in Views
+
+| Mode | Source | Output |
+|------|--------|--------|
+| `passthrough` | scene color output | beauty pass |
+| `passthrough` | 8-bit encoded `normalView` MRT output | RGB normal visualization |
+| `passthrough` | 8-bit encoded material detail MRT | material normal / normal-map visualization |
+| `depth` | pass depth texture converted to view-space distance | inverted grayscale |
+| `passthrough` | packed material MRT | base color/albedo, roughness, AO, metallic, opacity |
+| `passthrough` | material detail MRT | emissive color |
+| `passthrough` | wireframe override pass | white wireframe |
+| `passthrough` | neutral material override pass | lighting-only visualization |
+| `passthrough` | reflective neutral material override pass | reflection-only visualization |
+| `heatmap` | bucketed shader-complexity override pass | estimated shader complexity heatmap |
+
+The material data is packed into one RGBA target:
+
+- `R`: roughness
+- `G`: metallic
+- `B`: AO
+- `A`: opacity
+
+This keeps the composer under the common WebGPU `maxColorAttachmentBytesPerSample` limit instead of allocating one render target per scalar debug view.
+
+Emissive and material-normal/normal-map views use a second small MRT pass. That keeps the main pass below the attachment byte budget while preserving both geometry normals and material-perturbed normals. Lighting-only, reflection-only, estimated shader-complexity, and wireframe use demand-driven override passes, so they add GPU work only when selected by the active layout or viewport plan. `shaderCost` is an estimated complexity view, not a native GPU instruction counter: inferred program/material signals choose a bounded grayscale bucket material, then TSL maps that scalar to a heat color.
+
+## Render Modes
+
+`DebugViews` supports two public modes:
+
+- `compose` - default/current path. One TSL fullscreen compositor presents single, overlay, split, row, column, and grid layouts.
+- `viewport` - explicit viewport-assignment path. `viewportViews` defines the panes to present; the internal render-graph plan dedupes repeated pass construction and presents cells with renderer viewport/scissor bounds.
+
+```tsx
+<DebugViews
+  mode="viewport"
+  views={views}
+  viewportViews={[
+    { view: "beauty", label: "Beauty" },
+    { view: "lightingOnly", label: "Lighting" },
+    { view: "normal", label: "Normals", resolutionScale: 0.5 },
+    { view: "roughness", label: "Roughness", resolutionScale: 0.5 },
+  ]}
+  layout="row"
+  slots={4}
+  showLabels
+/>
+```
+
+Use `compose` for cheap compositing and overlays. Use `viewport` when callers need stable pane assignments, labels, per-pane resolution policy, or scissor-based presentation. `resolutionScale` is quantized to `1`, `0.5`, or `0.25` so render targets can be pooled predictably instead of producing one-off VRAM allocations.
+
+## Layouts
+
+- `single` - one view at a time (switch with `activeView`)
+- `split-h` - left/right split by view index
+- `split-v` - top/bottom split by view index
+- `quad` - 2x2 grid; empty cells repeat the beauty view
+- `row` - N views side by side with `slots`
+- `column` - N stacked views with `slots`
+- `grid` - explicit `columns` x `rows` topology
+- `overlay` - alpha blend views over the beauty pass
+
+```tsx
+<DebugViews views={views} layout="row" slots={4} />
+<DebugViews views={views} layout="row" slots={3} />
+<DebugViews views={views} layout="grid" columns={4} rows={1} />
+```
+
+The render plan still selects only the visible slot budget, so a four-wide row does not force every registered debug source to allocate.
+
+## Viewport Labels
+
+Enable labels to identify each viewport in split, row, column, or grid layouts:
+
+```tsx
+<DebugViews
+  views={views}
+  layout="row"
+  slots={4}
+  showLabels
+  viewportLabels={["Beauty", "Normals", "Depth", "Albedo"]}
+/>
+```
+
+## Custom TSL Nodes
+
+You can provide a custom node per view. If omitted, the component resolves a built-in source node from the scene pass.
+
+```tsx
+import { float, vec4 } from "three/tsl"
+
+{ label: "Constant", node: float(0.5), mode: "depth", scale: 1 }
+{ label: "Custom Color", node: vec4(1, 0, 0, 1), mode: "passthrough" }
+```
+
+## Leva Controls
+
+Interactive GUI for switching views at runtime:
+
+```tsx
+import { useDebugViewsControls } from "./components/debug-views"
+
+const controls = useDebugViewsControls({
+  viewLabels: ["Beauty", "Normal", "Depth", "Base Color / Albedo"],
+})
+```
+
+## Verification
+
+```bash
+pnpm typecheck
+pnpm test
+```
+
+
+### Stable Custom Debug Views
+
+For custom shader/debug nodes that may be recreated between React renders, prefer `createCustomDebugView` with a stable `id`:
+
+```tsx
+import { float, vec4 } from "three/tsl"
+import { createCustomDebugView, DEFAULT_DEBUG_VIEWS, DebugViews } from "./components/debug-views"
+
+const fresnelView = createCustomDebugView({
+  id: "shader:fresnel",
+  label: "Fresnel",
+  node: vec4(float(1), float(0), float(0), float(1)),
+})
+
+<DebugViews views={[...DEFAULT_DEBUG_VIEWS, fresnelView]} />
+```
+
+The viewport render graph uses the stable `id` to dedupe equivalent custom node views. If the custom debug output needs its own render target, material override, or disposal lifecycle, model it as a dedicated pass provider instead of forcing it into a compositor-only node.

package/dist/custom-debug-view.js

@@ -0,0 +1,13 @@
+//#region components/debug-views/custom-debug-view.ts
+function e({ id: e, label: t, node: n, mode: r = "passthrough", scale: i, bias: a }) {
+	return {
+		id: e,
+		label: t,
+		node: n,
+		mode: r,
+		scale: i,
+		bias: a
+	};
+}
+//#endregion
+export { e as createCustomDebugView };

package/dist/debug-render-graph-plan.js

@@ -0,0 +1,38 @@
+import { getDefaultDebugViewSource as e, getResolvedDebugViewMode as t } from "./debug-view-selection.js";
+//#region components/debug-views/debug-render-graph-plan.ts
+function n(e) {
+	let t = [], n = /* @__PURE__ */ new Map();
+	return {
+		passes: t,
+		cells: e.cells.map((e) => {
+			let r = a(e), i = n.get(r);
+			return i === void 0 && (i = t.length, n.set(r, i), t.push({
+				key: r,
+				view: e.view,
+				camera: e.camera,
+				resolutionScale: e.resolutionScale
+			})), {
+				...e,
+				passIndex: i
+			};
+		})
+	};
+}
+var r = /* @__PURE__ */ new WeakMap(), i = 0;
+function a(n) {
+	return [
+		e(n.view),
+		t(n.view),
+		n.view.id ? `id:${n.view.id}` : n.view.node ? `node:${o(n.view.node)}` : "default",
+		n.camera ? `camera:${n.camera.uuid}` : "camera:default",
+		n.resolutionScale,
+		n.view.scale ?? "scale:default",
+		n.view.bias ?? "bias:default"
+	].join("|");
+}
+function o(e) {
+	let t = r.get(e);
+	return t === void 0 && (t = i, i += 1, r.set(e, t)), t;
+}
+//#endregion
+export { n as createDebugViewportRenderGraphPlan };

package/dist/debug-render-plan.js

@@ -0,0 +1,86 @@
+import { getDefaultDebugViewSource as e, selectPipelineViews as t } from "./debug-view-selection.js";
+import { UnsignedByteType as n } from "three";
+//#region components/debug-views/debug-render-plan.ts
+function r(e, n, r) {
+	let i = t(e, n, r), l = a(i), d = o(i);
+	return {
+		views: i,
+		sceneOutputs: l,
+		materialDetailOutputs: d,
+		usesMaterialDetailPass: f(d),
+		usesWireframePass: u(i, "wireframe"),
+		usesLightingOnlyPass: u(i, "lightingOnly"),
+		usesReflectionOnlyPass: u(i, "reflectionOnly"),
+		usesShaderCostPass: u(i, "shaderCost"),
+		usesAoFallback: u(i, "ao"),
+		sceneTextureTypes: s(l),
+		materialDetailTextureTypes: c(d)
+	};
+}
+function i(e, t) {
+	for (let n of t) e.getTexture(n.name).type = n.type;
+}
+function a(t) {
+	let n = {}, r = {};
+	for (let i of t) if (!i.node) switch (e(i)) {
+		case "normal":
+			n.normal = !0;
+			break;
+		case "albedo":
+		case "baseColor":
+			n.albedo = !0;
+			break;
+		case "roughness":
+			r.roughness = !0;
+			break;
+		case "metalness":
+		case "metallic":
+			r.metalness = !0;
+			break;
+		case "ao":
+			r.ao = !0;
+			break;
+		case "opacity":
+		case "transparency":
+			r.opacity = !0;
+			break;
+	}
+	return d(r) && (n.material = r), n;
+}
+function o(t) {
+	let n = {};
+	for (let r of t) if (!r.node) switch (e(r)) {
+		case "materialNormal":
+		case "normalMap":
+			n.materialNormal = !0;
+			break;
+		case "emissive":
+			n.emissive = !0;
+			break;
+	}
+	return n;
+}
+function s(e) {
+	let t = [];
+	return e.normal && t.push(l("normal")), e.albedo && t.push(l("albedo")), e.material && t.push(l("material")), t;
+}
+function c(e) {
+	return e.materialNormal ? [l("materialNormal")] : [];
+}
+function l(e) {
+	return {
+		name: e,
+		type: n
+	};
+}
+function u(t, n) {
+	return t.some((t) => !t.node && e(t) === n);
+}
+function d(e) {
+	return !!(e.roughness || e.metalness || e.ao || e.opacity);
+}
+function f(e) {
+	return !!(e.materialNormal || e.emissive);
+}
+//#endregion
+export { i as applyDebugTextureTypes, r as createDebugRenderPlan };

package/dist/debug-view-definitions.js

@@ -0,0 +1,91 @@
+//#region components/debug-views/debug-view-definitions.ts
+var e = [
+	"albedo",
+	"materialNormal",
+	"normalMap",
+	"emissive",
+	"roughness",
+	"ao",
+	"metallic",
+	"opacity",
+	"wireframe",
+	"lightingOnly",
+	"reflectionOnly",
+	"shaderCost"
+], t = [
+	{
+		label: "Beauty",
+		source: "beauty",
+		mode: "passthrough"
+	},
+	{
+		label: "Normal",
+		source: "normal",
+		mode: "passthrough"
+	},
+	{
+		label: "Depth",
+		source: "depth",
+		mode: "depth"
+	},
+	{
+		label: "Base Color / Albedo",
+		source: "albedo",
+		mode: "passthrough"
+	},
+	{
+		label: "Material Normal / Normal Map",
+		source: "materialNormal",
+		mode: "passthrough"
+	},
+	{
+		label: "Emissive",
+		source: "emissive",
+		mode: "passthrough"
+	},
+	{
+		label: "Roughness",
+		source: "roughness",
+		mode: "passthrough"
+	},
+	{
+		label: "AO",
+		source: "ao",
+		mode: "passthrough"
+	},
+	{
+		label: "Metallic",
+		source: "metallic",
+		mode: "passthrough"
+	},
+	{
+		label: "Opacity",
+		source: "opacity",
+		mode: "passthrough"
+	},
+	{
+		label: "Wireframe",
+		source: "wireframe",
+		mode: "passthrough"
+	},
+	{
+		label: "Lighting Only",
+		source: "lightingOnly",
+		mode: "passthrough"
+	},
+	{
+		label: "Reflection Only",
+		source: "reflectionOnly",
+		mode: "passthrough"
+	},
+	{
+		label: "Estimated Shader Complexity",
+		source: "shaderCost",
+		mode: "heatmap"
+	}
+];
+function n(e = t) {
+	return e.map((e) => e.label);
+}
+//#endregion
+export { t as DEFAULT_DEBUG_VIEWS, e as MATERIAL_DEBUG_VIEW_SOURCES, n as getDebugViewLabels };

package/dist/debug-view-layout.js

@@ -0,0 +1,65 @@
+//#region components/debug-views/debug-view-layout.ts
+var e = {
+	single: 0,
+	overlay: 1,
+	"split-h": 2,
+	"split-v": 3,
+	quad: 4,
+	row: 5,
+	column: 6,
+	grid: 7
+}, t = 4;
+function n(e = "single", n = {}) {
+	let r = i(e, n);
+	switch (r.mode) {
+		case "single": return o(r.mode, "single", 1, 1);
+		case "overlay": return o(r.mode, "overlay", 1, 1, 2);
+		case "split-h": return o(r.mode, "grid", 2, 1);
+		case "split-v": return o(r.mode, "grid", 1, 2);
+		case "quad": return o(r.mode, "grid", 2, 2);
+		case "row": {
+			let e = s(r.slots, t);
+			return o(r.mode, "grid", e, 1, e);
+		}
+		case "column": {
+			let e = s(r.slots, t);
+			return o(r.mode, "grid", 1, e, e);
+		}
+		case "grid": {
+			let e = s(r.columns, 2), t = s(r.rows, 2);
+			return o(r.mode, "grid", e, t, r.slots);
+		}
+	}
+}
+function r(e) {
+	return typeof e == "object" && "presentation" in e;
+}
+function i(e, t) {
+	let n = a(t);
+	return typeof e == "string" ? {
+		mode: e,
+		...n
+	} : {
+		...e,
+		...n
+	};
+}
+function a(e) {
+	let t = {};
+	return e.slots !== void 0 && (t.slots = e.slots), e.columns !== void 0 && (t.columns = e.columns), e.rows !== void 0 && (t.rows = e.rows), t;
+}
+function o(e, t, n, r, i = n * r) {
+	let a = n * r;
+	return {
+		mode: e,
+		presentation: t,
+		columns: n,
+		rows: r,
+		slots: Math.min(s(i, a), a)
+	};
+}
+function s(e, t) {
+	return e === void 0 || !Number.isFinite(e) ? t : Math.max(1, Math.floor(e));
+}
+//#endregion
+export { e as LAYOUT_INDEX, r as isResolvedDebugViewLayout, n as resolveDebugViewLayout };

package/dist/debug-view-selection.js

@@ -0,0 +1,33 @@
+import { isResolvedDebugViewLayout as e, resolveDebugViewLayout as t } from "./debug-view-layout.js";
+//#region components/debug-views/debug-view-selection.ts
+function n(e) {
+	return e.source ? e.source : e.mode === "normal" ? "normal" : e.mode === "depth" ? "depth" : "beauty";
+}
+function r(e) {
+	let t = e.mode ?? "passthrough";
+	if (e.node) return t;
+	switch (n(e)) {
+		case "normal":
+		case "materialNormal":
+		case "normalMap": return "passthrough";
+		default: return t;
+	}
+}
+function i(n, r, i) {
+	if (n.length === 0) return [];
+	let s = e(i) ? i : t(i), c = n[o(r, n.length)];
+	switch (s.presentation) {
+		case "single": return [c];
+		case "overlay": return a(n, c);
+		case "grid": return n.slice(0, s.slots);
+	}
+}
+function a(e, t) {
+	let r = e.find((e) => n(e) === "beauty") ?? e[0];
+	return r === t ? [r] : [r, t];
+}
+function o(e, t) {
+	return Math.max(0, Math.min(e, t - 1));
+}
+//#endregion
+export { n as getDefaultDebugViewSource, r as getResolvedDebugViewMode, i as selectPipelineViews };

package/dist/debug-viewport-labels.js

@@ -0,0 +1,28 @@
+//#region components/debug-views/debug-viewport-labels.ts
+function e(e, t, i) {
+	if (e.length === 0) return [];
+	if (t.presentation === "overlay") return [n(e, i)];
+	if (t.presentation === "single") return [r(e[0], 0, i)];
+	let a = [];
+	for (let n = 0; n < t.slots; n++) {
+		let t = e[n] ?? e[0];
+		a.push(r(t, n, i));
+	}
+	return a;
+}
+function t(e, t) {
+	return e.cells.map((e) => r(e.view, e.index, t));
+}
+function n(e, t) {
+	let n = i(e[0], 0, t);
+	return n === void 0 ? e.map((e) => e.label).join(" + ") : n;
+}
+function r(e, t, n) {
+	return i(e, t, n) ?? e.label;
+}
+function i(e, t, n) {
+	let r = typeof n == "function" ? n(e, t) : n?.[t];
+	if (r !== void 0) return r;
+}
+//#endregion
+export { e as createDebugViewportLabels, t as createDebugViewportPlanLabels };

package/dist/debug-viewport-plan.js

@@ -0,0 +1,51 @@
+import { resolveDebugViewLayout as e } from "./debug-view-layout.js";
+import { getDefaultDebugViewSource as t, selectPipelineViews as n } from "./debug-view-selection.js";
+//#region components/debug-views/debug-viewport-plan.ts
+function r({ views: t, viewportViews: r, activeView: o = 0, layout: s = "single" }) {
+	let l = i(s) ? s : e(s), u = (r?.length ? r.slice(0, l.slots).map((e) => a(t, e)) : n(t, o, l).slice(0, l.slots).map((e) => ({
+		view: e,
+		resolutionScale: 1
+	}))).map((e, t) => ({
+		index: t,
+		view: e.view,
+		camera: e.camera,
+		resolutionScale: c(e.resolutionScale)
+	}));
+	return {
+		layout: l,
+		views: u.map((e) => e.view),
+		cells: u
+	};
+}
+function i(e) {
+	return typeof e == "object" && "presentation" in e;
+}
+function a(e, t) {
+	let n = o(e, t.view);
+	return {
+		view: t.label ? {
+			...n,
+			label: t.label
+		} : n,
+		camera: t.camera,
+		resolutionScale: c(t.resolutionScale)
+	};
+}
+function o(e, n) {
+	return typeof n == "number" ? e[l(n, e.length)] ?? s("beauty") : typeof n == "string" ? e.find((e) => t(e) === n) ?? s(n) : n;
+}
+function s(e) {
+	return {
+		label: e,
+		source: e,
+		mode: "passthrough"
+	};
+}
+function c(e) {
+	return e === void 0 || !Number.isFinite(e) || e >= .75 ? 1 : e >= .375 ? .5 : .25;
+}
+function l(e, t) {
+	return t <= 0 ? 0 : Math.max(0, Math.min(e, t - 1));
+}
+//#endregion
+export { r as createDebugViewportPlan };

package/dist/debug-viewport-presenter.js

@@ -0,0 +1,33 @@
+//#region components/debug-views/debug-viewport-presenter.ts
+function e(e) {
+	let { columns: t, rows: r } = e.layout, i = 1 / t, a = 1 / r;
+	return e.cells.map((e) => {
+		let r = e.index % t, o = Math.floor(e.index / t);
+		return {
+			index: e.index,
+			css: {
+				column: r + 1,
+				row: o + 1
+			},
+			scissor: {
+				x: n(r * i),
+				y: n(1 - (o + 1) * a),
+				width: n(i),
+				height: n(a)
+			}
+		};
+	});
+}
+function t(e, t) {
+	return {
+		x: Math.round(e.x * t.width),
+		y: Math.round(e.y * t.height),
+		width: Math.round(e.width * t.width),
+		height: Math.round(e.height * t.height)
+	};
+}
+function n(e) {
+	return Math.round(e * 1e6) / 1e6;
+}
+//#endregion
+export { e as createDebugViewportRects, t as toDebugViewportPixels };