@joystyk/render3d 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.2.0
+
+### Minor Changes
+
+- bb095c7: Add shared real-time input, pause, pace records and ghost races, plus a WebGL 2 renderer
+  lifecycle with context recovery and adaptive quality. Launch daily fixed-step simulations
+  from published configs and retain their puzzle identity through saved games.
+
+### Patch Changes
+
+- Updated dependencies [bb095c7]
+- Updated dependencies [bb095c7]
+  - @joystyk/contracts@0.2.0
+
+## 0.1.0
+
+Initial shared arcade kit (host policy).

package/README.md

@@ -1,5 +1,23 @@
 # @joystyk/render3d
 
-The first Joystyk library release is not yet available. This placeholder reserves the package name.
+Three.js lifecycle helpers, imported only from a game's `render/` layer.
 
-Source: https://github.com/joystyk-games/game-libraries
+`createRenderStage({ host, build, pause, announce })` creates a strict WebGL 2 surface. The
+`build` callback receives a renderer, scene and `track(resource)` disposal helper, and returns
+`{ camera, draw(view, alpha, quality), resize? }`. Feed snapshots through `stage.draw`;
+identical view/alpha keys are skipped. The host's CSS sizes `.render3d-canvas` to its viewport.
+`stage.dispose()` releases the observer, listeners, geometries, materials, textures and context.
+
+A lost context calls `pause`, blocks drawing and offers **Try 3D again**. Restoring or retrying
+runs `build` again, so GPU resources are recreated. It never resumes the simulation.
+`stage.graphics('auto' | 'low' | 'medium' | 'high')` selects adaptive or pinned quality.
+Auto starts at medium and steps down after three seconds with render-time p95 over 16 ms;
+it never steps up during a run. Pixel-ratio caps are 1, 1.5 and 2. The `development` option
+shows p95, draw calls and triangles. Quality never changes the simulation.
+
+`roomEnvironment`, `pickPlane` and `project` support game scenes. Existing scene classes can
+use `createRenderer`, `webgl2Available` and `bindGraphicsRecovery` to share the same WebGL 2
+boundary and full resource rebuild while retaining their own drawing APIs.
+
+See host policy (Joystyk host reference) for reference-phone budgets. Desktop software
+WebGL tests do not replace measurements on the reference phone.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createRenderStage, roomEnvironment, pickPlane, project, type SceneContext, type SceneDrawing, type RenderOptions, } from './stage.js';
+export { AutoQuality, PIXEL_RATIO, type Quality, type Graphics } from './quality.js';
+export { createRenderer, webgl2Available, bindGraphicsRecovery } from './lifecycle.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+import { AutoQuality, PIXEL_RATIO } from "./quality.js";
+import { createRenderStage, pickPlane, project, roomEnvironment } from "./stage.js";
+import { bindGraphicsRecovery, createRenderer, webgl2Available } from "./lifecycle.js";
+export { AutoQuality, PIXEL_RATIO, bindGraphicsRecovery, createRenderStage, createRenderer, pickPlane, project, roomEnvironment, webgl2Available };

package/dist/lifecycle.d.ts

@@ -0,0 +1,13 @@
+import * as THREE from 'three';
+import { type Quality } from './quality.js';
+/** Existing game scenes share the same strict WebGL 2 renderer boundary. */
+export declare function createRenderer(options?: Omit<THREE.WebGLRendererParameters, 'canvas'> & {
+    canvas?: HTMLCanvasElement;
+}, quality?: Quality): THREE.WebGLRenderer;
+export declare function webgl2Available(): boolean;
+/** Rebuilds all resources using the game's scene factory; it never resumes game time. */
+export declare function bindGraphicsRecovery(host: HTMLElement, canvas: HTMLCanvasElement, o: {
+    pause(): void;
+    rebuild(): void;
+    announce?: (message: string) => void;
+}): () => void;

package/dist/lifecycle.js

@@ -0,0 +1,64 @@
+import { PIXEL_RATIO } from "./quality.js";
+import * as THREE from "three";
+//#region src/lifecycle.ts
+/** Existing game scenes share the same strict WebGL 2 renderer boundary. */
+function createRenderer(options = {}, quality = "medium") {
+	const canvas = options.canvas ?? document.createElement("canvas");
+	const context = canvas.getContext("webgl2", {
+		antialias: options.antialias ?? true,
+		alpha: options.alpha ?? false,
+		powerPreference: options.powerPreference ?? "low-power"
+	});
+	if (context === null) throw Error("This game needs WebGL 2. Enable hardware acceleration, then try again.");
+	const renderer = new THREE.WebGLRenderer({
+		...options,
+		canvas,
+		context
+	});
+	renderer.setPixelRatio(Math.min(devicePixelRatio || 1, PIXEL_RATIO[quality]));
+	renderer.domElement.setAttribute("aria-hidden", "true");
+	return renderer;
+}
+function webgl2Available() {
+	const context = document.createElement("canvas").getContext("webgl2");
+	if (context === null) return false;
+	context.getExtension("WEBGL_lose_context")?.loseContext();
+	return true;
+}
+/** Rebuilds all resources using the game's scene factory; it never resumes game time. */
+function bindGraphicsRecovery(host, canvas, o) {
+	const abort = new AbortController(), { signal } = abort;
+	const notice = document.createElement("p"), retry = document.createElement("button");
+	notice.hidden = true;
+	retry.hidden = true;
+	retry.className = "retry-graphics";
+	retry.type = "button";
+	retry.textContent = "Try 3D again";
+	const rebuild = () => {
+		o.rebuild();
+	};
+	canvas.addEventListener("webglcontextlost", (e) => {
+		e.preventDefault();
+		o.pause();
+		if (signal.aborted) return;
+		notice.hidden = false;
+		retry.hidden = false;
+		if (!retry.isConnected) host.append(notice, retry);
+		notice.textContent = "Graphics interrupted. Try 3D again to restore the scene.";
+		o.announce?.(notice.textContent);
+	}, { signal });
+	canvas.addEventListener("webglcontextrestored", rebuild, { signal });
+	retry.addEventListener("click", (event) => {
+		event.stopPropagation();
+		rebuild();
+	}, { signal });
+	return () => {
+		abort.abort();
+		notice.remove();
+		retry.remove();
+	};
+}
+//#endregion
+export { bindGraphicsRecovery, createRenderer, webgl2Available };
+
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","names":[],"sources":["../src/lifecycle.ts"],"sourcesContent":["import * as THREE from 'three';\nimport { PIXEL_RATIO, type Quality } from './quality.ts';\n/** Existing game scenes share the same strict WebGL 2 renderer boundary. */\nexport function createRenderer(\n  options: Omit<THREE.WebGLRendererParameters, 'canvas'> & {\n    canvas?: HTMLCanvasElement;\n  } = {},\n  quality: Quality = 'medium',\n): THREE.WebGLRenderer {\n  const canvas = options.canvas ?? document.createElement('canvas');\n  const context = canvas.getContext('webgl2', {\n    antialias: options.antialias ?? true,\n    alpha: options.alpha ?? false,\n    powerPreference: options.powerPreference ?? 'low-power',\n  });\n  if (context === null) throw Error('This game needs WebGL 2. Enable hardware acceleration, then try again.');\n  const renderer = new THREE.WebGLRenderer({ ...options, canvas, context: context as WebGL2RenderingContext });\n  renderer.setPixelRatio(Math.min(devicePixelRatio || 1, PIXEL_RATIO[quality]));\n  renderer.domElement.setAttribute('aria-hidden', 'true');\n  return renderer;\n}\nexport function webgl2Available(): boolean {\n  const canvas = document.createElement('canvas'),\n    context = canvas.getContext('webgl2');\n  if (context === null) return false;\n  context.getExtension('WEBGL_lose_context')?.loseContext();\n  return true;\n}\n/** Rebuilds all resources using the game's scene factory; it never resumes game time. */\nexport function bindGraphicsRecovery(\n  host: HTMLElement,\n  canvas: HTMLCanvasElement,\n  o: {\n    pause(): void;\n    rebuild(): void;\n    announce?: (message: string) => void;\n  },\n): () => void {\n  const abort = new AbortController(),\n    { signal } = abort;\n  const notice = document.createElement('p'),\n    retry = document.createElement('button');\n  notice.hidden = true;\n  retry.hidden = true;\n  retry.className = 'retry-graphics';\n  retry.type = 'button';\n  retry.textContent = 'Try 3D again';\n  const rebuild = (): void => {\n    o.rebuild();\n  };\n  canvas.addEventListener(\n    'webglcontextlost',\n    (e) => {\n      e.preventDefault();\n      o.pause();\n      if (signal.aborted) return;\n      notice.hidden = false;\n      retry.hidden = false;\n      if (!retry.isConnected) host.append(notice, retry);\n      notice.textContent = 'Graphics interrupted. Try 3D again to restore the scene.';\n      o.announce?.(notice.textContent);\n    },\n    { signal },\n  );\n  canvas.addEventListener('webglcontextrestored', rebuild, { signal });\n  retry.addEventListener(\n    'click',\n    (event) => {\n      event.stopPropagation();\n      rebuild();\n    },\n    { signal },\n  );\n  return () => {\n    abort.abort();\n    notice.remove();\n    retry.remove();\n  };\n}\n"],"mappings":";;;;AAGA,SAAgB,eACd,UAEI,CAAC,GACL,UAAmB,UACE;CACrB,MAAM,SAAS,QAAQ,UAAU,SAAS,cAAc,QAAQ;CAChE,MAAM,UAAU,OAAO,WAAW,UAAU;EAC1C,WAAW,QAAQ,aAAa;EAChC,OAAO,QAAQ,SAAS;EACxB,iBAAiB,QAAQ,mBAAmB;CAC9C,CAAC;CACD,IAAI,YAAY,MAAM,MAAM,MAAM,wEAAwE;CAC1G,MAAM,WAAW,IAAI,MAAM,cAAc;EAAE,GAAG;EAAS;EAAiB;CAAkC,CAAC;CAC3G,SAAS,cAAc,KAAK,IAAI,oBAAoB,GAAG,YAAY,QAAQ,CAAC;CAC5E,SAAS,WAAW,aAAa,eAAe,MAAM;CACtD,OAAO;AACT;AACA,SAAgB,kBAA2B;CACzC,MACE,UADa,SAAS,cAAc,QAC1B,CAAA,CAAO,WAAW,QAAQ;CACtC,IAAI,YAAY,MAAM,OAAO;CAC7B,QAAQ,aAAa,oBAAoB,CAAC,EAAE,YAAY;CACxD,OAAO;AACT;;AAEA,SAAgB,qBACd,MACA,QACA,GAKY;CACZ,MAAM,QAAQ,IAAI,gBAAgB,GAChC,EAAE,WAAW;CACf,MAAM,SAAS,SAAS,cAAc,GAAG,GACvC,QAAQ,SAAS,cAAc,QAAQ;CACzC,OAAO,SAAS;CAChB,MAAM,SAAS;CACf,MAAM,YAAY;CAClB,MAAM,OAAO;CACb,MAAM,cAAc;CACpB,MAAM,gBAAsB;EAC1B,EAAE,QAAQ;CACZ;CACA,OAAO,iBACL,qBACC,MAAM;EACL,EAAE,eAAe;EACjB,EAAE,MAAM;EACR,IAAI,OAAO,SAAS;EACpB,OAAO,SAAS;EAChB,MAAM,SAAS;EACf,IAAI,CAAC,MAAM,aAAa,KAAK,OAAO,QAAQ,KAAK;EACjD,OAAO,cAAc;EACrB,EAAE,WAAW,OAAO,WAAW;CACjC,GACA,EAAE,OAAO,CACX;CACA,OAAO,iBAAiB,wBAAwB,SAAS,EAAE,OAAO,CAAC;CACnE,MAAM,iBACJ,UACC,UAAU;EACT,MAAM,gBAAgB;EACtB,QAAQ;CACV,GACA,EAAE,OAAO,CACX;CACA,aAAa;EACX,MAAM,MAAM;EACZ,OAAO,OAAO;EACd,MAAM,OAAO;CACf;AACF"}

package/dist/quality.d.ts

@@ -0,0 +1,11 @@
+export type Quality = 'low' | 'medium' | 'high';
+export type Graphics = 'auto' | Quality;
+export declare const PIXEL_RATIO: Readonly<Record<Quality, number>>;
+/** Measurement window and sustained-pressure timer use the caller's monotonic clock. */
+export declare class AutoQuality {
+    #private;
+    get level(): Quality;
+    get p95(): number;
+    set(setting: Graphics): void;
+    sample(ms: number, now: number): boolean;
+}

package/dist/quality.js

@@ -0,0 +1,44 @@
+//#region src/quality.ts
+var PIXEL_RATIO = {
+	low: 1,
+	medium: 1.5,
+	high: 2
+};
+/** Measurement window and sustained-pressure timer use the caller's monotonic clock. */
+var AutoQuality = class {
+	#samples = [];
+	#slowSince = null;
+	#level = "medium";
+	#setting = "auto";
+	get level() {
+		return this.#setting === "auto" ? this.#level : this.#setting;
+	}
+	get p95() {
+		const sorted = this.#samples.map((s) => s.ms).sort((a, b) => a - b);
+		return sorted[Math.max(0, Math.ceil(sorted.length * .95) - 1)] ?? 0;
+	}
+	set(setting) {
+		this.#setting = setting;
+		this.#slowSince = null;
+	}
+	sample(ms, now) {
+		this.#samples.push({
+			at: now,
+			ms
+		});
+		this.#samples = this.#samples.filter((s) => s.at >= now - 1e3);
+		if (this.#setting !== "auto" || this.p95 <= 16) {
+			this.#slowSince = null;
+			return false;
+		}
+		this.#slowSince ??= now;
+		if (now - this.#slowSince < 3e3 || this.#level === "low") return false;
+		this.#level = this.#level === "high" ? "medium" : "low";
+		this.#slowSince = null;
+		return true;
+	}
+};
+//#endregion
+export { AutoQuality, PIXEL_RATIO };
+
+//# sourceMappingURL=quality.js.map

package/dist/quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality.js","names":[],"sources":["../src/quality.ts"],"sourcesContent":["export type Quality = 'low' | 'medium' | 'high';\nexport type Graphics = 'auto' | Quality;\nexport const PIXEL_RATIO: Readonly<Record<Quality, number>> = { low: 1, medium: 1.5, high: 2 };\n/** Measurement window and sustained-pressure timer use the caller's monotonic clock. */\nexport class AutoQuality {\n  #samples: {\n    at: number;\n    ms: number;\n  }[] = [];\n  #slowSince: number | null = null;\n  #level: Quality = 'medium';\n  #setting: Graphics = 'auto';\n  get level(): Quality {\n    return this.#setting === 'auto' ? this.#level : this.#setting;\n  }\n  get p95(): number {\n    const sorted = this.#samples.map((s) => s.ms).sort((a, b) => a - b);\n    return sorted[Math.max(0, Math.ceil(sorted.length * 0.95) - 1)] ?? 0;\n  }\n  set(setting: Graphics): void {\n    this.#setting = setting;\n    this.#slowSince = null;\n  }\n  sample(ms: number, now: number): boolean {\n    this.#samples.push({ at: now, ms });\n    this.#samples = this.#samples.filter((s) => s.at >= now - 1000);\n    if (this.#setting !== 'auto' || this.p95 <= 16) {\n      this.#slowSince = null;\n      return false;\n    }\n    this.#slowSince ??= now;\n    if (now - this.#slowSince < 3000 || this.#level === 'low') return false;\n    this.#level = this.#level === 'high' ? 'medium' : 'low';\n    this.#slowSince = null;\n    return true;\n  }\n}\n"],"mappings":";AAEA,IAAa,cAAiD;CAAE,KAAK;CAAG,QAAQ;CAAK,MAAM;AAAE;;AAE7F,IAAa,cAAb,MAAyB;CACvB,WAGM,CAAC;CACP,aAA4B;CAC5B,SAAkB;CAClB,WAAqB;CACrB,IAAI,QAAiB;EACnB,OAAO,KAAK,aAAa,SAAS,KAAK,SAAS,KAAK;CACvD;CACA,IAAI,MAAc;EAChB,MAAM,SAAS,KAAK,SAAS,KAAK,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC;EAClE,OAAO,OAAO,KAAK,IAAI,GAAG,KAAK,KAAK,OAAO,SAAS,GAAI,IAAI,CAAC,MAAM;CACrE;CACA,IAAI,SAAyB;EAC3B,KAAK,WAAW;EAChB,KAAK,aAAa;CACpB;CACA,OAAO,IAAY,KAAsB;EACvC,KAAK,SAAS,KAAK;GAAE,IAAI;GAAK;EAAG,CAAC;EAClC,KAAK,WAAW,KAAK,SAAS,QAAQ,MAAM,EAAE,MAAM,MAAM,GAAI;EAC9D,IAAI,KAAK,aAAa,UAAU,KAAK,OAAO,IAAI;GAC9C,KAAK,aAAa;GAClB,OAAO;EACT;EACA,KAAK,eAAe;EACpB,IAAI,MAAM,KAAK,aAAa,OAAQ,KAAK,WAAW,OAAO,OAAO;EAClE,KAAK,SAAS,KAAK,WAAW,SAAS,WAAW;EAClD,KAAK,aAAa;EAClB,OAAO;CACT;AACF"}

package/dist/stage.d.ts

@@ -0,0 +1,41 @@
+import * as THREE from 'three';
+import { type Graphics, type Quality } from './quality.js';
+export type Disposable = {
+    dispose(): void;
+};
+export type SceneContext = {
+    readonly renderer: THREE.WebGLRenderer;
+    readonly scene: THREE.Scene;
+    track<T extends Disposable>(resource: T): T;
+};
+export type SceneDrawing<View> = {
+    readonly camera: THREE.Camera;
+    draw(view: View, alpha: number, quality: Quality): void;
+    resize?(width: number, height: number): void;
+};
+export type RenderOptions<View> = {
+    readonly host: HTMLElement;
+    readonly build: (context: SceneContext) => SceneDrawing<View>;
+    readonly pause: () => void;
+    readonly announce: (message: string) => void;
+    readonly development?: boolean;
+    readonly now?: () => number;
+};
+export declare function roomEnvironment({ renderer, scene, track }: SceneContext): void;
+export declare function createRenderStage<View>(o: RenderOptions<View>): {
+    readonly canvas: HTMLCanvasElement | null;
+    readonly available: boolean;
+    readonly measurement: {
+        p95: number;
+        calls: number;
+        triangles: number;
+        quality: Quality;
+    };
+    draw(view: View, alpha?: number, key?: string): void;
+    graphics(value: Graphics): void;
+    retry: () => void;
+    dispose(): void;
+};
+/** Camera-space pointer picking on a game's plane. */
+export declare function pickPlane(canvas: HTMLCanvasElement, camera: THREE.Camera, x: number, y: number, plane?: THREE.Plane): THREE.Vector3 | null;
+export declare function project(point: THREE.Vector3, camera: THREE.Camera): THREE.Vector3;

package/dist/stage.js

@@ -0,0 +1,187 @@
+import { AutoQuality, PIXEL_RATIO } from "./quality.js";
+import * as THREE from "three";
+import { RoomEnvironment } from "three/addons/environments/RoomEnvironment.js";
+//#region src/stage.ts
+function roomEnvironment({ renderer, scene, track }) {
+	const room = new RoomEnvironment(), pmrem = new THREE.PMREMGenerator(renderer);
+	scene.environment = track(pmrem.fromScene(room, .04)).texture;
+	room.dispose();
+	pmrem.dispose();
+}
+function createRenderStage(o) {
+	const quality = new AutoQuality(), now = o.now ?? (() => performance.now());
+	let renderer = null, drawing = null;
+	let scene = null, canvas = null;
+	let resources = /* @__PURE__ */ new Set(), events = null;
+	let last = null, drawn = "", disposed = false, lost = false;
+	let width = 1, height = 1;
+	const notice = document.createElement("p"), retry = document.createElement("button"), overlay = document.createElement("output");
+	retry.type = "button";
+	retry.textContent = "Try 3D again";
+	retry.hidden = true;
+	overlay.hidden = !o.development;
+	overlay.setAttribute("aria-label", "Rendering performance");
+	o.host.append(notice, retry, overlay);
+	const release = () => {
+		events?.abort();
+		events = null;
+		if (scene !== null) scene.traverse((object) => {
+			if (object instanceof THREE.InstancedMesh) resources.add(object);
+			const mesh = object;
+			if (mesh.geometry !== void 0) resources.add(mesh.geometry);
+			const materials = mesh.material === void 0 ? [] : Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+			for (const material of materials) {
+				resources.add(material);
+				for (const value of Object.values(material)) if (value instanceof THREE.Texture) resources.add(value);
+			}
+		});
+		for (const resource of resources) resource.dispose();
+		resources = /* @__PURE__ */ new Set();
+		renderer?.dispose();
+		renderer?.forceContextLoss();
+		renderer = null;
+		drawing = null;
+		scene = null;
+		canvas?.remove();
+		canvas = null;
+	};
+	const resize = () => {
+		width = Math.max(1, o.host.clientWidth);
+		height = Math.max(1, o.host.clientHeight || width * .7);
+		if (renderer !== null) renderer.shadowMap.enabled = quality.level === "high";
+		renderer?.setPixelRatio(Math.min(devicePixelRatio || 1, PIXEL_RATIO[quality.level]));
+		renderer?.setSize(width, height, false);
+		drawing?.resize?.(width, height);
+		drawn = "";
+		redraw();
+	};
+	const redraw = () => {
+		if (disposed || lost || renderer === null || drawing === null || scene === null || last === null) return;
+		const key = `${last.key}:${last.alpha}:${quality.level}:${width}:${height}`;
+		if (key === drawn) return;
+		const started = now();
+		drawing.draw(last.view, last.alpha, quality.level);
+		renderer.render(scene, drawing.camera);
+		if (quality.sample(now() - started, now())) {
+			renderer.shadowMap.enabled = quality.level === "high";
+			renderer.setPixelRatio(Math.min(devicePixelRatio || 1, PIXEL_RATIO[quality.level]));
+			renderer.setSize(width, height, false);
+		}
+		overlay.textContent = `p95 ${quality.p95.toFixed(1)} ms · ${renderer.info.render.calls} calls · ${renderer.info.render.triangles} triangles · ${quality.level}`;
+		drawn = key;
+	};
+	const rebuild = () => {
+		if (disposed) return;
+		release();
+		lost = false;
+		drawn = "";
+		try {
+			canvas = document.createElement("canvas");
+			const context = canvas.getContext("webgl2", {
+				antialias: true,
+				alpha: false,
+				powerPreference: "low-power"
+			});
+			if (context === null) throw new Error("WebGL 2 unavailable");
+			renderer = new THREE.WebGLRenderer({
+				canvas,
+				context,
+				antialias: true
+			});
+			renderer.outputColorSpace = THREE.SRGBColorSpace;
+			renderer.toneMapping = THREE.ACESFilmicToneMapping;
+			canvas.setAttribute("aria-hidden", "true");
+			canvas.classList.add("render3d-canvas");
+			o.host.prepend(canvas);
+			scene = new THREE.Scene();
+			drawing = o.build({
+				renderer,
+				scene,
+				track: (resource) => {
+					resources.add(resource);
+					return resource;
+				}
+			});
+			events = new AbortController();
+			canvas.addEventListener("webglcontextlost", (e) => {
+				e.preventDefault();
+				lost = true;
+				o.pause();
+				notice.textContent = "Graphics interrupted. Your game is paused.";
+				retry.hidden = false;
+				o.announce(notice.textContent);
+			}, { signal: events.signal });
+			canvas.addEventListener("webglcontextrestored", () => {
+				rebuild();
+				o.announce("Graphics restored. Resume when ready.");
+			}, { signal: events.signal });
+			notice.textContent = "";
+			retry.hidden = true;
+			resize();
+		} catch {
+			release();
+			lost = true;
+			o.pause();
+			notice.textContent = "This game needs WebGL 2. Enable hardware acceleration, then try again.";
+			retry.hidden = false;
+		}
+	};
+	retry.addEventListener("click", rebuild);
+	const observer = new ResizeObserver(resize);
+	observer.observe(o.host);
+	rebuild();
+	return {
+		get canvas() {
+			return canvas;
+		},
+		get available() {
+			return renderer !== null && !lost;
+		},
+		get measurement() {
+			return {
+				p95: quality.p95,
+				calls: renderer?.info.render.calls ?? 0,
+				triangles: renderer?.info.render.triangles ?? 0,
+				quality: quality.level
+			};
+		},
+		draw(view, alpha = 1, key = JSON.stringify(view)) {
+			last = {
+				view,
+				alpha,
+				key
+			};
+			redraw();
+		},
+		graphics(value) {
+			quality.set(value);
+			resize();
+		},
+		retry: rebuild,
+		dispose() {
+			if (disposed) return;
+			disposed = true;
+			observer.disconnect();
+			release();
+			retry.removeEventListener("click", rebuild);
+			notice.remove();
+			retry.remove();
+			overlay.remove();
+		}
+	};
+}
+/** Camera-space pointer picking on a game's plane. */
+function pickPlane(canvas, camera, x, y, plane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0)) {
+	const rect = canvas.getBoundingClientRect();
+	if (rect.width === 0 || rect.height === 0) return null;
+	const ray = new THREE.Raycaster();
+	ray.setFromCamera(new THREE.Vector2((x - rect.left) / rect.width * 2 - 1, 1 - (y - rect.top) / rect.height * 2), camera);
+	return ray.ray.intersectPlane(plane, new THREE.Vector3());
+}
+function project(point, camera) {
+	return point.clone().project(camera);
+}
+//#endregion
+export { createRenderStage, pickPlane, project, roomEnvironment };
+
+//# sourceMappingURL=stage.js.map

package/dist/stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage.js","names":[],"sources":["../src/stage.ts"],"sourcesContent":["import * as THREE from 'three';\nimport { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';\nimport { AutoQuality, PIXEL_RATIO, type Graphics, type Quality } from './quality.ts';\nexport type Disposable = {\n  dispose(): void;\n};\nexport type SceneContext = {\n  readonly renderer: THREE.WebGLRenderer;\n  readonly scene: THREE.Scene;\n  track<T extends Disposable>(resource: T): T;\n};\nexport type SceneDrawing<View> = {\n  readonly camera: THREE.Camera;\n  draw(view: View, alpha: number, quality: Quality): void;\n  resize?(width: number, height: number): void;\n};\nexport type RenderOptions<View> = {\n  readonly host: HTMLElement;\n  readonly build: (context: SceneContext) => SceneDrawing<View>;\n  readonly pause: () => void;\n  readonly announce: (message: string) => void;\n  readonly development?: boolean;\n  readonly now?: () => number;\n};\nexport function roomEnvironment({ renderer, scene, track }: SceneContext): void {\n  const room = new RoomEnvironment(),\n    pmrem = new THREE.PMREMGenerator(renderer);\n  const target = track(pmrem.fromScene(room, 0.04));\n  scene.environment = target.texture;\n  room.dispose();\n  pmrem.dispose();\n}\nexport function createRenderStage<View>(o: RenderOptions<View>) {\n  const quality = new AutoQuality(),\n    now = o.now ?? (() => performance.now());\n  let renderer: THREE.WebGLRenderer | null = null,\n    drawing: SceneDrawing<View> | null = null;\n  let scene: THREE.Scene | null = null,\n    canvas: HTMLCanvasElement | null = null;\n  let resources = new Set<Disposable>(),\n    events: AbortController | null = null;\n  let last: {\n      view: View;\n      alpha: number;\n      key: string;\n    } | null = null,\n    drawn = '',\n    disposed = false,\n    lost = false;\n  let width = 1,\n    height = 1;\n  const notice = document.createElement('p'),\n    retry = document.createElement('button'),\n    overlay = document.createElement('output');\n  retry.type = 'button';\n  retry.textContent = 'Try 3D again';\n  retry.hidden = true;\n  overlay.hidden = !o.development;\n  overlay.setAttribute('aria-label', 'Rendering performance');\n  o.host.append(notice, retry, overlay);\n  const release = (): void => {\n    events?.abort();\n    events = null;\n    if (scene !== null)\n      scene.traverse((object) => {\n        if (object instanceof THREE.InstancedMesh) resources.add(object);\n        const mesh = object as THREE.Mesh;\n        if (mesh.geometry !== undefined) resources.add(mesh.geometry);\n        const materials =\n          mesh.material === undefined ? [] : Array.isArray(mesh.material) ? mesh.material : [mesh.material];\n        for (const material of materials) {\n          resources.add(material);\n          for (const value of Object.values(material)) if (value instanceof THREE.Texture) resources.add(value);\n        }\n      });\n    for (const resource of resources) resource.dispose();\n    resources = new Set();\n    renderer?.dispose();\n    renderer?.forceContextLoss();\n    renderer = null;\n    drawing = null;\n    scene = null;\n    canvas?.remove();\n    canvas = null;\n  };\n  const resize = (): void => {\n    width = Math.max(1, o.host.clientWidth);\n    height = Math.max(1, o.host.clientHeight || width * 0.7);\n    if (renderer !== null) renderer.shadowMap.enabled = quality.level === 'high';\n    renderer?.setPixelRatio(Math.min(devicePixelRatio || 1, PIXEL_RATIO[quality.level]));\n    renderer?.setSize(width, height, false);\n    drawing?.resize?.(width, height);\n    drawn = '';\n    redraw();\n  };\n  const redraw = (): void => {\n    if (disposed || lost || renderer === null || drawing === null || scene === null || last === null) return;\n    const key = `${last.key}:${last.alpha}:${quality.level}:${width}:${height}`;\n    if (key === drawn) return;\n    const started = now();\n    drawing.draw(last.view, last.alpha, quality.level);\n    renderer.render(scene, drawing.camera);\n    if (quality.sample(now() - started, now())) {\n      renderer.shadowMap.enabled = quality.level === 'high';\n      renderer.setPixelRatio(Math.min(devicePixelRatio || 1, PIXEL_RATIO[quality.level]));\n      renderer.setSize(width, height, false);\n    }\n    overlay.textContent = `p95 ${quality.p95.toFixed(1)} ms · ${renderer.info.render.calls} calls · ${renderer.info.render.triangles} triangles · ${quality.level}`;\n    drawn = key;\n  };\n  const rebuild = (): void => {\n    if (disposed) return;\n    release();\n    lost = false;\n    drawn = '';\n    try {\n      canvas = document.createElement('canvas');\n      const context = canvas.getContext('webgl2', { antialias: true, alpha: false, powerPreference: 'low-power' });\n      if (context === null) throw new Error('WebGL 2 unavailable');\n      renderer = new THREE.WebGLRenderer({ canvas, context, antialias: true });\n      renderer.outputColorSpace = THREE.SRGBColorSpace;\n      renderer.toneMapping = THREE.ACESFilmicToneMapping;\n      canvas.setAttribute('aria-hidden', 'true');\n      canvas.classList.add('render3d-canvas');\n      o.host.prepend(canvas);\n      scene = new THREE.Scene();\n      drawing = o.build({\n        renderer,\n        scene,\n        track: (resource) => {\n          resources.add(resource);\n          return resource;\n        },\n      });\n      events = new AbortController();\n      canvas.addEventListener(\n        'webglcontextlost',\n        (e) => {\n          e.preventDefault();\n          lost = true;\n          o.pause();\n          notice.textContent = 'Graphics interrupted. Your game is paused.';\n          retry.hidden = false;\n          o.announce(notice.textContent);\n        },\n        { signal: events.signal },\n      );\n      canvas.addEventListener(\n        'webglcontextrestored',\n        () => {\n          rebuild();\n          o.announce('Graphics restored. Resume when ready.');\n        },\n        { signal: events.signal },\n      );\n      notice.textContent = '';\n      retry.hidden = true;\n      resize();\n    } catch {\n      release();\n      lost = true;\n      o.pause();\n      notice.textContent = 'This game needs WebGL 2. Enable hardware acceleration, then try again.';\n      retry.hidden = false;\n    }\n  };\n  retry.addEventListener('click', rebuild);\n  const observer = new ResizeObserver(resize);\n  observer.observe(o.host);\n  rebuild();\n  return {\n    get canvas(): HTMLCanvasElement | null {\n      return canvas;\n    },\n    get available(): boolean {\n      return renderer !== null && !lost;\n    },\n    get measurement() {\n      return {\n        p95: quality.p95,\n        calls: renderer?.info.render.calls ?? 0,\n        triangles: renderer?.info.render.triangles ?? 0,\n        quality: quality.level,\n      };\n    },\n    draw(view: View, alpha = 1, key = JSON.stringify(view)): void {\n      last = { view, alpha, key };\n      redraw();\n    },\n    graphics(value: Graphics): void {\n      quality.set(value);\n      resize();\n    },\n    retry: rebuild,\n    dispose(): void {\n      if (disposed) return;\n      disposed = true;\n      observer.disconnect();\n      release();\n      retry.removeEventListener('click', rebuild);\n      notice.remove();\n      retry.remove();\n      overlay.remove();\n    },\n  };\n}\n/** Camera-space pointer picking on a game's plane. */\nexport function pickPlane(\n  canvas: HTMLCanvasElement,\n  camera: THREE.Camera,\n  x: number,\n  y: number,\n  plane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0),\n): THREE.Vector3 | null {\n  const rect = canvas.getBoundingClientRect();\n  if (rect.width === 0 || rect.height === 0) return null;\n  const ray = new THREE.Raycaster();\n  ray.setFromCamera(\n    new THREE.Vector2(((x - rect.left) / rect.width) * 2 - 1, 1 - ((y - rect.top) / rect.height) * 2),\n    camera,\n  );\n  return ray.ray.intersectPlane(plane, new THREE.Vector3());\n}\nexport function project(point: THREE.Vector3, camera: THREE.Camera): THREE.Vector3 {\n  return point.clone().project(camera);\n}\n"],"mappings":"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"}

package/package.json

@@ -1,20 +1,51 @@
 {
   "name": "@joystyk/render3d",
-  "version": "0.0.0",
-  "description": "Reserved for the first Joystyk library release.",
+  "version": "0.2.0",
+  "description": "Shared Three.js rendering, lifecycle and adaptive quality.",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@types/three": "0.186.0",
+    "three": "0.186.1",
+    "@joystyk/contracts": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "vite": "8.3.3",
+    "vitest": "4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=24.15.0"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/joystyk-games/game-libraries.git",
     "directory": "packages/render3d"
   },
-  "homepage": "https://github.com/joystyk-games/game-libraries",
-  "files": [
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ],
-  "publishConfig": {
-    "access": "public"
+  "homepage": "https://github.com/joystyk-games/game-libraries/tree/main/packages/render3d#readme",
+  "bugs": {
+    "url": "https://github.com/joystyk-games/game-libraries/issues"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../scripts/build-package.ts"
   }
-}
+}