+ )
+}
diff --git a/src/client/view3d/puzlwerkOrientation.ts b/src/client/view3d/puzlwerkOrientation.ts
new file mode 100644
index 00000000..dd9cabe2
--- /dev/null
+++ b/src/client/view3d/puzlwerkOrientation.ts
@@ -0,0 +1,13 @@
+// Display orientation of the PuzlWerk viewer as a unit quaternion [x, y, z, w]: the XYZ Euler rotation
+// (pitch about x, then yaw about y) of the existing isometric view, written out so the app needs no direct
+// dependency on three.
+export function eulerPitchYaw(
+ pitch: number,
+ yaw: number,
+): [number, number, number, number] {
+ const c1 = Math.cos(pitch / 2)
+ const s1 = Math.sin(pitch / 2)
+ const c2 = Math.cos(yaw / 2)
+ const s2 = Math.sin(yaw / 2)
+ return [s1 * c2, c1 * s2, s1 * s2, c1 * c2]
+}
diff --git a/test/cubeView3DChoice.test.ts b/test/cubeView3DChoice.test.ts
new file mode 100644
index 00000000..f67d99f9
--- /dev/null
+++ b/test/cubeView3DChoice.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+import { puzlwerkViewerRequested } from '../src/client/view3d/cubeView3DChoice'
+
+describe('puzlwerkViewerRequested', () => {
+ it('selects the PuzlWerk viewer only for viewer=puzlwerk', () => {
+ expect(puzlwerkViewerRequested('?viewer=puzlwerk')).toBe(true)
+ expect(puzlwerkViewerRequested('?x=1&viewer=puzlwerk')).toBe(true)
+ })
+ it('keeps the existing view for everything else', () => {
+ for (const search of [
+ '',
+ '?',
+ '?viewer=',
+ '?viewer=old',
+ '?viewer=PuzlWerk',
+ '?viewers=puzlwerk',
+ '?puzlwerk',
+ ])
+ expect(puzlwerkViewerRequested(search), search).toBe(false)
+ })
+})
diff --git a/test/puzlwerkOrientation.test.ts b/test/puzlwerkOrientation.test.ts
new file mode 100644
index 00000000..7af5df80
--- /dev/null
+++ b/test/puzlwerkOrientation.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { eulerPitchYaw } from '../src/client/view3d/puzlwerkOrientation'
+
+const rotate = (q: number[], v: number[]) => {
+ // v' = q * v * q^-1 for a unit quaternion
+ const [x, y, z, w] = q
+ const [a, b, c] = v
+ const tx = 2 * (y * c - z * b)
+ const ty = 2 * (z * a - x * c)
+ const tz = 2 * (x * b - y * a)
+ return [
+ a + w * tx + (y * tz - z * ty),
+ b + w * ty + (z * tx - x * tz),
+ c + w * tz + (x * ty - y * tx),
+ ]
+}
+
+describe('eulerPitchYaw', () => {
+ it('is a unit quaternion', () => {
+ for (const [p, y] of [
+ [0.52, -0.74],
+ [0, 0],
+ [1, 2],
+ ])
+ expect(Math.hypot(...eulerPitchYaw(p, y))).toBeCloseTo(1, 12)
+ })
+ it('turns about x for pitch only and about y for yaw only', () => {
+ const half = Math.PI / 2
+ const pitched = rotate(eulerPitchYaw(half, 0), [0, 0, 1])
+ expect(pitched[1]).toBeCloseTo(-1, 12)
+ const yawed = rotate(eulerPitchYaw(0, half), [0, 0, 1])
+ expect(yawed[0]).toBeCloseTo(1, 12)
+ })
+ it('applies yaw first about the fixed y axis, then pitch (XYZ Euler order)', () => {
+ const v = rotate(eulerPitchYaw(Math.PI / 2, Math.PI / 2), [0, 0, 1])
+ // z -> x by yaw, x stays under pitch about x
+ expect(v[0]).toBeCloseTo(1, 12)
+ expect(v[1]).toBeCloseTo(0, 12)
+ expect(v[2]).toBeCloseTo(0, 12)
+ })
+})
diff --git a/vendor/README.md b/vendor/README.md
index e28988d9..498146ec 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -9,3 +9,19 @@ bindings, runtime modules, rebuildable ReScript sources, and source provenance.
Core is licensed EUPL-1.2. The included CubeAssembler-derived material retains its
MIT license and attribution. These notices do not relicense the package as MIT.
Production distribution requires the owner's separate license acceptance gate.
+
+# PuzlWerk viewer (spike)
+
+`puzlwerk-viewer-0.1.0-7e14cbd8.tgz` is the private `@puzlwerk/viewer` package packed from
+wstein/puzlwerk commit `7e14cbd8ba570bbafb02f2557e9c1b6e9ac09723` (`npm pack --workspace @puzlwerk/viewer`
+after `npm run build`). SHA-256 of the archive:
+`cfa25d8305954f210515dc99c038a44e123e218ff7226d2b0a0e573965fd2788`. `viewer.json` pins it and
+`npm run verify:viewer-vendor` checks the archive, the installed package, its `NOTICE` and the bridge. No
+registry publication, no gitlink.
+
+The package is AGPL-3.0-or-later (CubeAssembler is AGPL-3.0-or-later too). Its `NOTICE` and the license texts
+inside the archive (`LICENSE`, `CUBE_ASSEMBLER_LICENSE.txt`, `THREE_LICENSE.txt`, `CORE_EUPL_LICENSE.txt`) stay
+with it. `dist/bridge/core` holds compiled PuzlWerk Core modules under EUPL-1.2 OR AGPL-3.0-or-later (owner decision 2026-11-17; this project uses the AGPL choice); production distribution of that
+combination is an owner license gate. Three.js 0.187.0 (MIT) is a dependency of the viewer.
+
+Used only by the spike view selected with `?viewer=puzlwerk` (`src/client/view3d/puzlwerkCubeView.tsx`).
diff --git a/vendor/puzlwerk-viewer-0.1.0-7e14cbd8.tgz b/vendor/puzlwerk-viewer-0.1.0-7e14cbd8.tgz
new file mode 100644
index 00000000..5051c9a5
Binary files /dev/null and b/vendor/puzlwerk-viewer-0.1.0-7e14cbd8.tgz differ
diff --git a/vendor/viewer.json b/vendor/viewer.json
new file mode 100644
index 00000000..0774c566
--- /dev/null
+++ b/vendor/viewer.json
@@ -0,0 +1,9 @@
+{
+ "package": "@puzlwerk/viewer",
+ "version": "0.1.0",
+ "artifact": "puzlwerk-viewer-0.1.0-7e14cbd8.tgz",
+ "sha256": "cfa25d8305954f210515dc99c038a44e123e218ff7226d2b0a0e573965fd2788",
+ "sourceRevision": "7e14cbd8ba570bbafb02f2557e9c1b6e9ac09723",
+ "sourceRepository": "https://github.com/wstein/puzlwerk",
+ "license": "AGPL-3.0-or-later; compiled Core modules in dist/bridge/core are EUPL-1.2 OR AGPL-3.0-or-later, used here under the AGPL choice"
+}
diff --git a/web/cube3d.css b/web/cube3d.css
index a127474c..208f0799 100644
--- a/web/cube3d.css
+++ b/web/cube3d.css
@@ -210,3 +210,11 @@
text-align: center;
color: var(--color-text-secondary);
}
+
+/* PuzlWerk viewer spike: its canvas fills the same backdrop box as the existing canvas. */
+.cube-3d-puzlwerk canvas {
+ width: 100%;
+ height: 100%;
+ display: block;
+ touch-action: none;
+}