otherplane 0.1.0

package/CLAUDE.md

@@ -0,0 +1,130 @@
+# CLAUDE.md
+
+Guidance for Claude Code working in the **Otherplane** repo.
+
+## What this is
+
+A static site generator for walkable Gaussian-splat museums. This repo ships the
+**engine/tool** only; a user's museum content is theirs and is gitignored. Two
+layers:
+
+- **the project** — a user's content root: `otherplane.config.json` (deploy config:
+  landing room, base path, site title, walk speed) plus `rooms/<slug>/room.json`,
+  `worlds/` (splats + colliders), `music/`. Gitignored here; it's the source of
+  truth for a given site. `otherplane init` scaffolds it.
+- **`engine/`** — the renderer: a content-free Next.js viewer (Spark + R3F +
+  Rapier) that statically exports (`output: 'export'` — no server, any static
+  host). Its only input is a `room.json` by URL; it knows nothing about museums,
+  hosting, or how assets were made. Keep it content-free — no rooms baked in.
+
+Plus the tooling: `bin/otherplane.mjs` (the CLI), `schema/` (room.json JSON
+Schema), `scripts/gen_world.py` (Marble room generation), and [`skill.md`](skill.md)
+(the authoring pipeline: generate → mark → wire → publish).
+
+The CLI mirrors the project's `rooms/`, `worlds/`, `music/` into `engine/public/`
+(gitignored build artifact) before dev/build, so Next's `generateStaticParams`
+can enumerate `public/rooms/*`. Author at the project root, never in the mirror.
+The project root defaults to the cwd, overridable via `$OTHERPLANE_PROJECT`.
+
+## Commands (run from the project root)
+
+One CLI, aliased by the npm scripts: `npm run init` (scaffold a project) ·
+`npm run new` (generate a room) · `npm run dev` · `npm run edit` (author in the
+viewer) · `npm run check` (validate rooms) · `npm run build` (→ `engine/out`;
+`-- --base /museum` to mount under a sub-path) · `npm run serve` · `npm run clean`.
+Each aliases `otherplane <verb>` (`bin/otherplane.mjs`), which drives `engine/` and
+`gen_world.py`.
+
+## The room primitive (`engine/src/data/room.ts`)
+
+A room is `rooms/<slug>/room.json`. Types:
+
+- `Entryway { id, pos, yaw }` — a named, addressable spawn spot. The URL fragment
+  (`/library/#from-study`) selects it; `id: "default"` is the no-fragment spawn.
+- `Exit { pos, radius?, to }` — walk up + press **E** to follow `to` (a room URL +
+  `#entryway`; relative within a site, absolute across). Dead links 404 by design.
+- `Artifact { id?, pos, radius, url }` — walk up + interact to open a web URL
+  overlay (no travel).
+- `loadRoom(url)` resolves every asset URL **relative to the room.json's URL**, so
+  assets can be colocated, on object storage (R2/S3), or on the World Labs CDN.
+
+A museum is just rooms linked by exits (like web pages linked by hrefs) — there is
+no manifest and no global "museum" object; the graph is emergent.
+
+## Routing (`engine/src/app`)
+
+- `app/[room]/page.tsx` — server wrapper; `generateStaticParams` enumerates
+  `public/rooms/*` so each room pre-renders to `/<slug>/index.html` in the export.
+  (generateStaticParams can't live in a `'use client'` file — hence the wrapper.)
+- `app/[room]/RoomViewer.tsx` — the client viewer: loads the room, resolves the
+  spawn entryway from `location.hash`, renders the scene, handles exits (client
+  nav same-origin, full nav cross-origin).
+- `app/page.tsx` — server component that bakes in `LANDING_ROOM` (`src/data/site.ts`,
+  read from `otherplane.config.json`) and renders `LandingRedirect.tsx`, a tiny
+  client redirect (static export has no server).
+- `app/providers.tsx` — PointerLock / Audio / Edit providers (in the root layout).
+
+## Rendering & physics
+
+- `components/scene/WorldScene.tsx` — the R3F `<Canvas>` and scene graph.
+- `components/spark/SplatWorld.tsx` — loads the `.spz` via Spark. All Marble splats
+  use quaternion `[1,0,0,0]` (180° about X) + the room's `calibration.scale` (see
+  `roomToWorldDef` in `presets.ts`); the collider is baked with the same transform
+  so walls line up with what you see.
+- `physics/RapierProvider.tsx` — builds a trimesh env collider from the room's
+  collider GLB; spawns the player (fixed-size dynamic capsule) at the entryway
+  `pos` (body-center) facing `yaw`. Falls back to a floor raycast (`findValidSpawn`)
+  only when a room declares no entryways. Rapier is `@dimforge/rapier3d-compat`
+  **v0.12** — ray hits use `.toi` (not `.timeOfImpact`).
+- `components/controls/PlayerController.tsx` — WASD + mouse. The player capsule is
+  a **fixed real-world size**; `calibration.scale` sizes the *room* to fit it, so a
+  too-small scale leaves the player wedged (that's the room-scale footgun). No
+  jumping/sprinting; edit-mode specter (Z + arrows) is the only vertical movement.
+
+## Edit mode (`engine/src/providers/edit.tsx`)
+
+A property of the running **instance** (`NEXT_PUBLIC_EDIT_MODE`, via `npm run
+edit`), not a URL — so published builds have no edit mode and never mount any of
+it. Edit mode **writes** `room.json`: `otherplane edit` runs a tiny local HTTP
+writer alongside `next dev`, and `src/data/editApi.ts` POSTs marks to it; the CLI
+merges only the coordinate arrays into the PROJECT source (never asset URLs, never
+the mirror) and re-syncs. Pieces:
+
+- `providers/edit.tsx` — owns the room's draft + mutators (each persists) + undo.
+- `components/edit/EditCapture.tsx` — keys: **C** add/move entryway (floor-snapped),
+  **B** add/move artifact (beamed), **F** gaze-select, **Del** remove, **X**
+  deselect, **Z** specter fly (↑/↓).
+- `components/edit/Markers.tsx` — labeled orbs in the scene (green entryway / cyan
+  exit / amber artifact), edit-only.
+- `components/edit/EditorPanel.tsx` — the single DOM panel: help legend, undo/⌘Z,
+  name/wire/delete, exit dropdown-or-arbitrary-URL, promote-to-doorway, two-way
+  (reciprocal exit reusing the target's entryway), and two sliders that write
+  **shippable** data — room scale → `calibration.scale` in room.json (rescales the
+  markers with it), walk speed → `moveSpeed` in `otherplane.config.json` (per-museum,
+  ships to every viewer).
+
+## Controls (published viewer)
+
+Desktop: WASD move, mouse look, **E** to use an exit, mute (top-right), Esc to
+release the mouse. The first click or keypress engages look + audio (browsers
+require a gesture). Mobile: virtual joystick + touch-drag to look.
+
+## Conventions
+
+- TypeScript, functional components, hooks. Providers live OUTSIDE the R3F Canvas.
+- Keep the renderer content-free: no specific rooms/assets baked in.
+- Memoize the `WorldDef` passed to the scene (stable `position`/`quaternion`
+  references) or SplatWorld's load effect re-fires every render.
+- Stable slugs + entryway ids: other rooms link to them; renaming rots links.
+- Big binaries (`.spz`/`.glb`) belong in object storage referenced by URL from
+  `room.json`; keep git small.
+- `.env` holds `WORLD_LABS_KEY` and is gitignored — never commit it (`.env.example`
+  is the template). Build output (`engine/.next`, `engine/out`, `node_modules`) and
+  content (`rooms/`, `worlds/`, `music/`, `generated/`) are gitignored too.
+
+## Tech stack
+
+Next.js 15 (static export) · React 19 · TypeScript · three.js + @react-three/fiber ·
+@sparkjsdev/spark (splat rendering) · @dimforge/rapier3d-compat (physics) ·
+Tailwind CSS. Built on [WorldSplats](https://github.com/philchacko/worldsplats),
+[Spark.js](https://sparkjs.dev), and [World Labs Marble](https://marble.worldlabs.ai).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Phil Chacko
+
+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,146 @@
+# Otherplane
+
+A **static site generator for walkable Gaussian-splat museums.** Point it at the
+sections of a personal site and it generates a 3D **room** for each one, lets you
+mark spawn points / doorways / artifacts, links the rooms together, and publishes
+a plain **static walkable site** — host it on GitHub Pages, Cloudflare R2/Pages,
+S3, or any folder behind any web server.
+
+A museum is just **rooms linked by exits** — like web pages linked by `href`s.
+There is no manifest and no central "museum" object; the graph is emergent.
+
+## This repo is the engine
+
+Otherplane ships the **tool**, not a museum. You build your own site on top: your
+rooms, splats, colliders, music, and per-site config are **your content** and are
+gitignored by default — clone the engine, then create a museum inside it (or in
+any folder) and track that content in your own repo. `engine/` is the content-free
+renderer; the rest is the CLI, schema, and authoring pipeline.
+
+```
+otherplane/
+├── engine/              the renderer — a content-free Next.js viewer (Spark + R3F + Rapier)
+├── bin/otherplane.mjs    the CLI (the npm scripts alias it)
+├── schema/              room.json JSON Schema (editor autocomplete + `otherplane check`)
+├── scripts/             gen_world.py — generate a room from a prompt (World Labs Marble)
+├── skill.md             the authoring guide — how rooms get made, marked, linked, shipped
+└── otherplane.config.example.json
+
+# created by `otherplane init` / your content — GITIGNORED, build your own site here:
+├── otherplane.config.json   deploy config (landing room, base path, title, walk speed)
+├── rooms/<slug>/room.json  the rooms — one folder, one URL (/<slug>/)
+├── worlds/                 splats + colliders (.spz / .glb) — host big blobs on R2/S3
+└── music/                  per-room loopable tracks
+```
+
+The CLI mirrors your content into `engine/public/` (a gitignored build artifact)
+so Next can serve and enumerate it; you never edit there. The renderer is a **deep
+module**: its only input is a `room.json` (by URL) — it knows nothing about
+museums, hosting, or how assets were made. See [`CLAUDE.md`](CLAUDE.md) for
+renderer internals and [`skill.md`](skill.md) for the authoring pipeline.
+
+## Quick start
+
+Use it as an installed CLI in any folder (the engine's deps install themselves on
+first run):
+
+```bash
+npx otherplane init       # scaffold otherplane.config.json + rooms/ worlds/ music/
+npx otherplane edit       # open http://localhost:3000 — walk, mark, and wire rooms
+npx otherplane build      # → ./out (deploy anywhere) · -- --base /museum to sub-path
+```
+
+…or clone the repo and use the `npm run` aliases (`npm run init` / `edit` /
+`build`). Either way, `build` emits a plain static `out/` in your project — host
+it on GitHub Pages, Cloudflare, S3, or any static host.
+
+Add rooms one of two ways: **generate** them with `otherplane new` (World Labs
+Marble — needs a key + `uv`, see below), or **bring your own** `.spz` splat +
+`.glb` collider, drop them in `worlds/`, and point a `rooms/<slug>/room.json` at
+them. Then `otherplane edit` to place spawns/doors/artifacts (it writes `room.json`
+for you). No key or Python is needed for the bring-your-own path.
+
+> **Publishing (maintainers):** `npm publish` ships the CLI + the engine source
+> (`files` allowlist; build artifacts and `node_modules` are excluded). The engine
+> is heavy (Next + Three.js + Rapier); its deps install on the user's first
+> `dev`/`edit`/`build`, not at install time. Bump the version and `npm publish`.
+
+## CLI
+
+Like other static site generators (Hugo, Astro, Eleventy), Otherplane exposes a
+small set of verbs through one CLI (`bin/otherplane.mjs`). Run them as
+`otherplane <verb>` or via the `npm run` aliases below:
+
+| Command            | What it does                                                                 |
+| :----------------- | :-------------------------------------------------------------------------- |
+| `npm run setup`    | Install the engine's dependencies (one-time).                               |
+| `npm run init`     | Scaffold a fresh project (config, `rooms/`, `.env.example`) in this folder. |
+| `npm run new`      | Generate a room from a prompt (World Labs Marble). See below.               |
+| `npm run dev`      | Dev server with the viewer (http://localhost:3000).                         |
+| `npm run edit`     | Dev server with **edit mode** on — mark/wire rooms in the viewer; writes `room.json` for you. |
+| `npm run check`    | Validate every `rooms/*/room.json` against the schema.                      |
+| `npm run build`    | Static export to `engine/out` — deploy this folder anywhere. `-- --base /museum` to mount under a sub-path. |
+| `npm run serve`    | Serve the built `engine/out` at http://localhost:8000.                      |
+| `npm run preview`  | `build` then `serve`.                                                       |
+| `npm run clean`    | Remove build output + the synced mirror.                                    |
+
+### Generating a room
+
+```bash
+cp .env.example .env          # then paste your WORLD_LABS_KEY
+npm run setup
+npm run new -- "a cozy wood-paneled library, warm lamplight" --slug library --name "Library"
+```
+
+This calls World Labs Marble, downloads the splat (`.spz`) + collider (`.glb`)
+into `worlds/`, saves the raw world object under `generated/<slug>/`, and writes a
+`room.json` skeleton to `rooms/<slug>/`. Use `--model marble-1.0-draft` (the
+default) while iterating — it's cheap (~$1.26).
+
+Then mark coordinates and wire the room up in the viewer — see below.
+
+### Marking & wiring (edit mode)
+
+`npm run edit` opens the viewer with an authoring panel and writes `room.json`
+for you (no clipboard, no hand-editing). Walk into a room, then:
+
+- **C** — drop (or move the selected) **entryway** at your floor-snapped spot.
+- **B** — aim and drop (or move the selected) **artifact** at what you're looking at.
+- **F** select the marker under your crosshair · **Del** remove it · **Z** fly.
+
+Every marker shows as a labeled orb (green entryway, cyan exit, amber artifact).
+In the panel you name entryways, wire **exits** by menu (any room → entryway) or
+paste an arbitrary URL (link into someone else's museum), promote an entryway
+into a doorway, and click **two-way** to auto-create the return door in the target
+room. Changes save to `rooms/<slug>/room.json` as you go.
+
+## Hosting & repo size
+
+Keep **text in git** (`room.json` + the shared bundle) and **blobs in object
+storage**. A `.spz` is ~5 MB and a collider ~5 MB; for anything you want to keep,
+mirror those to R2 (cheap, zero egress, CDN-backed) and point each `room.json`
+URL there. Adding a room then costs the repo a few KB, not 10 MB. (Marble's own
+CDN URLs have no documented retention SLA — self-host keepers.)
+
+### Mounting on an existing site (e.g. `/museum`)
+
+To hang the museum off a personal site — an "Enter my museum" button that goes to
+`example.com/museum/` — build it under that sub-path and drop the output into your
+site's tree:
+
+```bash
+npm run build -- --base /museum   # or set "basePath": "/museum" in otherplane.config.json
+# then copy engine/out/* into your site's /museum/ directory (or point the host at it)
+```
+
+The link on your homepage is just `<a href="/museum/">`. The museum is plain
+static files, so it coexists with any host; the two builds stay separate (the
+viewer carries a WebGL toolchain your main site shouldn't inherit) and integrate
+at the deploy layer.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). Built on
+[WorldSplats](https://github.com/philchacko/worldsplats) (the viewer),
+[Spark.js](https://sparkjs.dev) (splat rendering), and
+[World Labs Marble](https://marble.worldlabs.ai) (generation).