@replayablejs/canvas 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Replayable 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,35 @@
+# @replayablejs/canvas
+
+Provide a shared canvas host for rendering integrations.
+
+Part of [Replayable](https://github.com/replayablejs/replayable) **0.1.0-alpha.0**.
+APIs may change during the alpha series.
+
+## Install
+
+```sh
+pnpm add @replayablejs/canvas@0.1.0-alpha.0
+```
+
+## Public surface
+
+`getCanvasHost`, `CanvasHost`, `SharedRenderingContext`.
+
+[Usage and reference](https://github.com/replayablejs/replayable/blob/main/docs/reference/canvas.md).
+The package manifest defines supported import paths; internal source files are not public APIs.
+
+## Development
+
+From the repository root, install with `pnpm install --frozen-lockfile` and build dependencies
+with `pnpm build`. Run `pnpm --filter @replayablejs/canvas test` for this package's tests.
+
+## Peer dependencies
+
+- `@replayablejs/runtime`: `workspace:*`
+
+Workspace ranges are converted to package versions when packed.
+
+## License
+
+Original code is [MIT licensed](https://github.com/replayablejs/replayable/blob/main/LICENSE). Bundled third-party resources retain
+their accompanying license terms.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+//#region src/types/canvas-host.d.ts
+interface CanvasHost {
+  /** Returns the canvas mounted inside Replayable's runtime container. */
+  getCanvas(): HTMLCanvasElement;
+  /** Returns the WebGL context registered by a renderer, or `null` before registration. */
+  getSharedContext(): SharedRenderingContext | null;
+  /** Registers the first renderer's context; rejects replacement or use after destruction. */
+  setSharedContext(context: SharedRenderingContext): void;
+  /** Removes the canvas once and lets the next access create a fresh shared host. */
+  destroy(): void;
+}
+type SharedRenderingContext = WebGLRenderingContext | WebGL2RenderingContext;
+//#endregion
+//#region src/host/get-canvas-host.d.ts
+/** Returns the canvas host shared by every renderer in the playable. */
+declare function getCanvasHost(): CanvasHost;
+//#endregion
+export { type CanvasHost, type SharedRenderingContext, getCanvasHost };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,72 @@
+import { playable } from "@replayablejs/runtime";
+import { registerWebglContext } from "#webgl-stats";
+//#region src/host/canvas-ids.ts
+/** ID of the generated runtime canvas element. */
+const REPLAYABLE_CANVAS_ID = "replayable-canvas";
+//#endregion
+//#region src/host/canvas.scss?inline
+var canvas_default = "#replayable-container #replayable-canvas{width:100%;height:100%;display:block;position:absolute;inset:0}\n";
+//#endregion
+//#region src/host/install-canvas-styles.ts
+const CANVAS_STYLE_ID = "replayable-canvas-styles";
+/** Installs canvas host base styles once per document. */
+function installCanvasStyles() {
+	if (document.getElementById(CANVAS_STYLE_ID) !== null) return;
+	const style = document.createElement("style");
+	style.id = CANVAS_STYLE_ID;
+	style.textContent = canvas_default.trim();
+	document.head.append(style);
+}
+//#endregion
+//#region src/host/get-canvas-host.ts
+let sharedCanvasHost;
+/** Returns the canvas host shared by every renderer in the playable. */
+function getCanvasHost() {
+	sharedCanvasHost ??= createCanvasHost();
+	return sharedCanvasHost;
+}
+/**
+* Creates a replayable canvas host and mounts it into the runtime container.
+*
+* The host only owns DOM placement and shared-context handoff; it never creates
+* or configures rendering contexts itself.
+*/
+function createCanvasHost() {
+	installCanvasStyles();
+	const canvas = document.createElement("canvas");
+	let destroyed = false;
+	let sharedContext = null;
+	let unregisterContext;
+	canvas.id = REPLAYABLE_CANVAS_ID;
+	playable.container.append(canvas);
+	const host = {
+		getCanvas: () => canvas,
+		getSharedContext: () => sharedContext,
+		setSharedContext,
+		destroy
+	};
+	return host;
+	/** Commits the renderer's context only after registration succeeds, allowing retries. */
+	function setSharedContext(context) {
+		if (destroyed) throw new Error("Cannot register a WebGL context on a destroyed Replayable canvas host.");
+		if (sharedContext === context) return;
+		if (sharedContext !== null) throw new Error("Replayable canvas already has a different WebGL context.");
+		unregisterContext = registerWebglContext(context);
+		sharedContext = context;
+	}
+	/** Releases local ownership before notifying observers, whose cleanup may throw. */
+	function destroy() {
+		if (destroyed) return;
+		destroyed = true;
+		const unregister = unregisterContext;
+		unregisterContext = void 0;
+		sharedContext = null;
+		canvas.remove();
+		if (sharedCanvasHost === host) sharedCanvasHost = void 0;
+		unregister?.();
+	}
+}
+//#endregion
+export { getCanvasHost };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["canvasStyles"],"sources":["../src/host/canvas-ids.ts","../src/host/canvas.scss?inline","../src/host/install-canvas-styles.ts","../src/host/get-canvas-host.ts"],"sourcesContent":["/** ID of the generated runtime canvas element. */\nexport const REPLAYABLE_CANVAS_ID = 'replayable-canvas';\n","#replayable-container #replayable-canvas {\n  position: absolute;\n  inset: 0;\n  display: block;\n  width: 100%;\n  height: 100%;\n}","import canvasStyles from './canvas.scss?inline';\n\nconst CANVAS_STYLE_ID = 'replayable-canvas-styles';\n\n/** Installs canvas host base styles once per document. */\nexport function installCanvasStyles(): void {\n  if (document.getElementById(CANVAS_STYLE_ID) !== null) {\n    return;\n  }\n\n  const style = document.createElement('style');\n  style.id = CANVAS_STYLE_ID;\n  style.textContent = canvasStyles.trim();\n  document.head.append(style);\n}\n","import { playable } from '@replayablejs/runtime';\n\nimport type { CanvasHost, SharedRenderingContext } from '#types/canvas-host.js';\nimport { registerWebglContext } from '#webgl-stats';\n\nimport { REPLAYABLE_CANVAS_ID } from './canvas-ids.js';\nimport { installCanvasStyles } from './install-canvas-styles.js';\n\nlet sharedCanvasHost: CanvasHost | undefined;\n\n/** Returns the canvas host shared by every renderer in the playable. */\nexport function getCanvasHost(): CanvasHost {\n  sharedCanvasHost ??= createCanvasHost();\n\n  return sharedCanvasHost;\n}\n\n/**\n * Creates a replayable canvas host and mounts it into the runtime container.\n *\n * The host only owns DOM placement and shared-context handoff; it never creates\n * or configures rendering contexts itself.\n */\nfunction createCanvasHost(): CanvasHost {\n  installCanvasStyles();\n\n  const canvas = document.createElement('canvas');\n  let destroyed = false;\n  let sharedContext: SharedRenderingContext | null = null;\n  let unregisterContext: (() => void) | undefined;\n\n  canvas.id = REPLAYABLE_CANVAS_ID;\n  playable.container.append(canvas);\n\n  const host: CanvasHost = {\n    getCanvas: () => canvas,\n    getSharedContext: (): SharedRenderingContext | null => sharedContext,\n    setSharedContext,\n    destroy,\n  };\n\n  return host;\n\n  /** Commits the renderer's context only after registration succeeds, allowing retries. */\n  function setSharedContext(context: SharedRenderingContext): void {\n    if (destroyed) {\n      throw new Error('Cannot register a WebGL context on a destroyed Replayable canvas host.');\n    }\n\n    // Both renderers may report the same shared context; register it only once.\n    if (sharedContext === context) {\n      return;\n    }\n    if (sharedContext !== null) {\n      throw new Error('Replayable canvas already has a different WebGL context.');\n    }\n\n    unregisterContext = registerWebglContext(context);\n    sharedContext = context;\n  }\n\n  /** Releases local ownership before notifying observers, whose cleanup may throw. */\n  function destroy(): void {\n    if (destroyed) {\n      return;\n    }\n    destroyed = true;\n\n    const unregister = unregisterContext;\n    unregisterContext = undefined;\n    sharedContext = null;\n    canvas.remove();\n\n    if (sharedCanvasHost === host) {\n      sharedCanvasHost = undefined;\n    }\n\n    // Errors still reach the caller, but cannot leave a mounted or reusable dead host.\n    unregister?.();\n  }\n}\n"],"mappings":";;;;AACA,MAAa,uBAAuB;;;ACDpC,IAAA,iBAAA;;;ACEA,MAAM,kBAAkB;;AAGxB,SAAgB,sBAA4B;CAC1C,IAAI,SAAS,eAAe,eAAe,MAAM,MAC/C;CAGF,MAAM,QAAQ,SAAS,cAAc,OAAO;CAC5C,MAAM,KAAK;CACX,MAAM,cAAcA,eAAa,KAAK;CACtC,SAAS,KAAK,OAAO,KAAK;AAC5B;;;ACNA,IAAI;;AAGJ,SAAgB,gBAA4B;CAC1C,qBAAqB,iBAAiB;CAEtC,OAAO;AACT;;;;;;;AAQA,SAAS,mBAA+B;CACtC,oBAAoB;CAEpB,MAAM,SAAS,SAAS,cAAc,QAAQ;CAC9C,IAAI,YAAY;CAChB,IAAI,gBAA+C;CACnD,IAAI;CAEJ,OAAO,KAAK;CACZ,SAAS,UAAU,OAAO,MAAM;CAEhC,MAAM,OAAmB;EACvB,iBAAiB;EACjB,wBAAuD;EACvD;EACA;CACF;CAEA,OAAO;;CAGP,SAAS,iBAAiB,SAAuC;EAC/D,IAAI,WACF,MAAM,IAAI,MAAM,wEAAwE;EAI1F,IAAI,kBAAkB,SACpB;EAEF,IAAI,kBAAkB,MACpB,MAAM,IAAI,MAAM,0DAA0D;EAG5E,oBAAoB,qBAAqB,OAAO;EAChD,gBAAgB;CAClB;;CAGA,SAAS,UAAgB;EACvB,IAAI,WACF;EAEF,YAAY;EAEZ,MAAM,aAAa;EACnB,oBAAoB,KAAA;EACpB,gBAAgB;EAChB,OAAO,OAAO;EAEd,IAAI,qBAAqB,MACvB,mBAAmB,KAAA;EAIrB,aAAa;CACf;AACF"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@replayablejs/canvas",
+  "version": "0.1.0-alpha.0",
+  "description": "Renderer-agnostic canvas host utilities for Replayable playables",
+  "homepage": "https://github.com/replayablejs/replayable#readme",
+  "bugs": {
+    "url": "https://github.com/replayablejs/replayable/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/replayablejs/replayable.git",
+    "directory": "packages/canvas"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#types/*": "./src/types/*"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@tsdown/css": "0.22.14",
+    "happy-dom": "20.13.2",
+    "sass-embedded": "1.103.1",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10",
+    "@replayablejs/runtime": "0.1.0-alpha.0"
+  },
+  "peerDependencies": {
+    "@replayablejs/runtime": "0.1.0-alpha.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "oxlint --type-aware --max-warnings 0 .",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}