otherplane 0.1.0

package/engine/tailwind.config.js

@@ -0,0 +1,184 @@
+/** @type {import('tailwindcss').Config} */
+
+import colors from "tailwindcss/colors";
+import defaultTheme from "tailwindcss/defaultTheme";
+import plugin from "tailwindcss/plugin";
+
+module.exports = {
+  content: [
+    "./primitives/**/*.{js,ts,jsx,tsx,mdx}",
+    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
+    "./layouts/**/*.{js,ts,jsx,tsx,mdx}",
+    "./components/**/*.{js,ts,jsx,tsx,mdx}",
+    "./icons/**/*.{js,ts,jsx,tsx,mdx}",
+    "./app/**/*.{js,ts,jsx,tsx,mdx}",
+  ],
+  theme: {
+    extend: {
+      fontFamily: {
+        "sans-medium": ["Avenir-Medium", ...defaultTheme.fontFamily.sans],
+        "sans-heavy": ["Avenir-Heavy", ...defaultTheme.fontFamily.sans],
+        "sans-black": ["Avenir-Black", ...defaultTheme.fontFamily.sans],
+      },
+      fontSize: {
+        heading: ["24px", "36px"],
+      },
+      colors: {
+        gray: colors.neutral,
+      },
+      transitionProperty: {
+        "max-height": "max-height",
+        "padding": "padding"
+      },
+    },
+  },
+  plugins: [
+    plugin(function ({ addUtilities }) {
+      const actions = {
+        ".action-normal": {
+          "background-color": "var(--action-normal)",
+        },
+      };
+
+      const backgrounds = {
+        ".bg-root": {
+          "background-color": "var(--background-root)",
+        },
+        ".bg-root-inverted": {
+          "background-color": "var(--background-root-inverted)",
+        },
+        ".bg-elevated": {
+          "background-color": "var(--background-elevated)",
+        },
+        ".bg-action-primary": {
+          "background-color": "var(--background-action-primary)",
+        },
+        ".bg-action-primary-hover": {
+          "background-color": "var(--background-action-primary-hover)",
+        },
+        ".bg-action-primary-active": {
+          "background-color": "var(--background-action-primary-active)",
+        },
+        ".bg-action-transparent": {
+          "background-color": "var(--background-action-transparent)",
+        },
+        ".bg-action-primary-disabled": {
+          "background-color": "var(--background-action-primary-disabled)",
+        },
+        ".bg-action-hover": {
+          "background-color": "var(--background-action-hover)",
+        },
+        ".bg-action-active": {
+          "background-color": "var(--background-action-active)",
+        },
+        ".bg-transparent": {
+          "background-color": "transparent",
+        },
+      };
+
+      const text = {
+        ".text-primary": {
+          color: "var(--text-primary)",
+        },
+        ".text-secondary": {
+          color: "var(--text-secondary)",
+        },
+        ".text-tertiary": {
+          color: "var(--text-tertiary)",
+        },
+        ".text-inverted-primary": {
+          color: "var(--text-inverted-primary)",
+        },
+        ".text-inverted-secondary": {
+          color: "var(--text-inverted-secondary)",
+        },
+        ".text-sm": {
+          "font-size": "var(--size-sm)",
+        },
+        ".text-md": {
+          "font-size": "var(--size-md)",
+        },
+      };
+
+      const strokesAndFills = {
+        ".stroke-primary": {
+          stroke: "var(--stroke-primary)",
+        },
+        ".stroke-secondary": {
+          stroke: "var(--stroke-secondary)",
+        },
+        ".stroke-tertiary": {
+          stroke: "var(--stroke-tertiary)",
+        },
+        ".stroke-suggestion": {
+          stroke: "var(--stroke-suggestion)",
+        },
+        ".stroke-inverted-primary": {
+          stroke: "var(--stroke-inverted-primary)",
+        },
+        ".stroke-error-primary": {
+          stroke: "var(--stroke-error-primary)",
+        },
+        ".stroke-success-primary": {
+          stroke: "var(--stroke-success-primary)",
+        },
+        ".fill-root": {
+          fill: "var(--fill-root)",
+        },
+        ".fill-primary": {
+          fill: "var(--fill-primary)",
+        },
+        ".fill-secondary": {
+          fill: "var(--fill-secondary)",
+        },
+        ".fill-tertiary": {
+          fill: "var(--fill-tertiary)",
+        },
+        ".fill-switch-off": {
+          fill: "var(--fill-switch-off)",
+        },
+        ".fill-switch-on": {
+          fill: "var(--fill-switch-on)",
+        },
+        ".fill-inverted-primary": {
+          fill: "var(--fill-inverted-primary)",
+        },
+        ".fill-inverted-secondary": {
+          fill: "var(--fill-inverted-secondary)",
+        },
+        ".fill-error-primary": {
+          fill: "var(--fill-error-primary)",
+        },
+        ".fill-success-primary": {
+          fill: "var(--fill-success-primary)",
+        },
+      };
+
+      const bordersAndOutlines = {
+        ".border-normal": {
+          "border-color": "var(--border-normal)",
+        },
+        ".border-highlighted": {
+          "border-color": "var(--border-highlighted)",
+        },
+        ".border-action": {
+          "border-color": "var(--text-secondary)", 
+        },
+        ".border-error": {
+          "border-color": "var(--border-error)",
+        },
+        ".border-elevated": {
+          "border-color": "var(--border-elevated)",
+        }
+      };
+
+      addUtilities({
+        ...actions,
+        ...backgrounds,
+        ...text,
+        ...strokesAndFills,
+        ...bordersAndOutlines,
+      });
+    }),
+  ],
+}

package/engine/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/otherplane.config.example.json

@@ -0,0 +1,6 @@
+{
+  "landingRoom": "",
+  "basePath": "",
+  "siteTitle": "My Museum",
+  "moveSpeed": 14
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "otherplane",
+  "version": "0.1.0",
+  "description": "A static site generator for walkable Gaussian-splat museums. Generate a 3D room per section, link rooms with doorways, publish a static walkable site.",
+  "keywords": [
+    "gaussian-splatting",
+    "static-site-generator",
+    "3d",
+    "webgl",
+    "three-js",
+    "spark",
+    "worldlabs",
+    "marble",
+    "museum"
+  ],
+  "homepage": "https://github.com/Julian-Moncarz/otherplane#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Julian-Moncarz/otherplane.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Julian-Moncarz/otherplane/issues"
+  },
+  "author": "Julian Moncarz",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "otherplane": "bin/otherplane.mjs"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "schema",
+    "engine",
+    "skill.md",
+    "CLAUDE.md",
+    "otherplane.config.example.json"
+  ],
+  "scripts": {
+    "otherplane": "node bin/otherplane.mjs",
+    "prepublishOnly": "node bin/otherplane.mjs clean",
+    "setup": "node bin/otherplane.mjs setup",
+    "init": "node bin/otherplane.mjs init",
+    "new": "node bin/otherplane.mjs new",
+    "dev": "node bin/otherplane.mjs dev",
+    "edit": "node bin/otherplane.mjs edit",
+    "check": "node bin/otherplane.mjs check",
+    "build": "node bin/otherplane.mjs build",
+    "serve": "node bin/otherplane.mjs serve",
+    "preview": "node bin/otherplane.mjs preview",
+    "clean": "node bin/otherplane.mjs clean",
+    "lint": "npm --prefix engine run lint"
+  },
+  "license": "MIT"
+}

package/schema/room.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://otherplane.dev/schema/room.schema.json",
+  "title": "Room",
+  "description": "A Otherplane room: one splat world you can walk, plus the entryways you arrive at, the exits you leave through, and the artifacts you open. A museum is just rooms linked by exits — there is no manifest. Asset URLs resolve relative to this file's URL.",
+  "type": "object",
+  "required": ["display_name", "splat_url", "collider_url", "calibration"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string", "description": "Path/URL to this schema (editor autocomplete only; ignored by the viewer)." },
+    "display_name": { "type": "string", "description": "Human name shown in the HUD, e.g. \"Library\"." },
+    "splat_url": { "type": "string", "description": "Gaussian-splat world (.spz/.ply). Resolved relative to this file." },
+    "collider_url": { "type": "string", "description": "GLB collider mesh for wall/floor physics. Resolved relative to this file." },
+    "music_url": { "type": ["string", "null"], "description": "Optional loopable background track." },
+    "pano_url": { "type": ["string", "null"], "description": "Optional equirectangular panorama." },
+    "thumbnail_url": { "type": ["string", "null"], "description": "Optional preview image." },
+    "calibration": {
+      "type": "object",
+      "description": "Marble reconstructs at an arbitrary scale; this brings the room to meters.",
+      "required": ["scale"],
+      "additionalProperties": false,
+      "properties": { "scale": { "type": "number", "exclusiveMinimum": 0 } }
+    },
+    "entryways": {
+      "type": "array",
+      "description": "Named spawn spots. One should be id \"default\" (the no-fragment spawn).",
+      "items": {
+        "type": "object",
+        "required": ["id", "pos", "yaw"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "description": "Stable id; URL fragments link to it (/library/#from-study). Renaming rots links." },
+          "pos": { "$ref": "#/$defs/vec3" },
+          "yaw": { "type": "number", "description": "Facing direction in degrees on arrival." }
+        }
+      }
+    },
+    "exits": {
+      "type": "array",
+      "description": "Walk up + press E to follow `to`. Dead links 404 by design.",
+      "items": {
+        "type": "object",
+        "required": ["pos", "to"],
+        "additionalProperties": false,
+        "properties": {
+          "pos": { "$ref": "#/$defs/vec3" },
+          "radius": { "type": "number", "exclusiveMinimum": 0, "default": 1.3, "description": "Trigger radius in meters." },
+          "to": { "type": "string", "description": "Destination URL + #entryway. Relative within a site (../study/#from-library), absolute across sites." }
+        }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "description": "Walk up + interact to open `url` in a fullscreen overlay (no travel).",
+      "items": {
+        "type": "object",
+        "required": ["pos", "radius", "url"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "pos": { "$ref": "#/$defs/vec3" },
+          "radius": { "type": "number", "exclusiveMinimum": 0 },
+          "url": { "type": "string", "description": "Web URL opened in the overlay." }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "vec3": {
+      "type": "array",
+      "description": "[x, y, z] in meters, world space.",
+      "items": { "type": "number" },
+      "minItems": 3,
+      "maxItems": 3
+    }
+  }
+}

package/scripts/gen_world.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Minimal one-off Marble room generator.
+
+Generates a single room from a TEXT prompt, polls the operation, downloads the
+splat (.spz), collider (.glb), pano and thumbnail into the repo-root worlds/,
+and writes a room.json skeleton to rooms/<slug>/room.json for the room primitive
+(engine/src/data/room.ts). Mark entryways/exits in edit mode after.
+
+The repo root holds the project's content (rooms/, worlds/, music/); the engine
+mirrors it into engine/public/ at dev/build time. `otherplane new` runs that sync
+for you; if you call this script directly, run `otherplane dev`/`edit` after.
+
+Usage:
+    otherplane new "<text prompt>" --slug library --name "Library"
+    # or directly:
+    uv run --with requests scripts/gen_world.py "<text prompt>" --slug library --name "Library"
+"""
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from urllib.parse import urlparse
+
+import requests
+
+BASE = "https://api.worldlabs.ai/marble/v1"
+# The content root. The CLI passes OTHERPLANE_PROJECT; default to this repo's root
+# so direct invocation (uv run scripts/gen_world.py) still works.
+ROOT = Path(os.environ.get("OTHERPLANE_PROJECT") or Path(__file__).resolve().parent.parent)
+OUT = ROOT / "worlds"
+
+
+def load_key() -> str:
+    env = ROOT / ".env"
+    for line in env.read_text().splitlines():
+        if line.strip().startswith("WORLD_LABS_KEY"):
+            return line.split("=", 1)[1].strip()
+    sys.exit("WORLD_LABS_KEY not found in .env")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("prompt")
+    ap.add_argument("--model", default="marble-1.0-draft")
+    ap.add_argument("--name", default="step-one-test-room")
+    ap.add_argument("--slug", default="room", help="basename for output files, e.g. 'library'")
+    args = ap.parse_args()
+
+    headers = {"WLT-Api-Key": load_key(), "Content-Type": "application/json"}
+
+    print(f"→ generating ({args.model}): {args.prompt!r}")
+    r = requests.post(
+        f"{BASE}/worlds:generate",
+        headers=headers,
+        json={
+            "display_name": args.name,
+            "model": args.model,
+            "world_prompt": {"type": "text", "text_prompt": args.prompt},
+        },
+    )
+    r.raise_for_status()
+    op = r.json()
+    op_id = op.get("operation_id") or op.get("name", "").split("/")[-1] or op.get("id")
+    print(f"  operation: {op_id}")
+
+    world_id = None
+    while True:
+        time.sleep(10)
+        s = requests.get(f"{BASE}/operations/{op_id}", headers=headers)
+        s.raise_for_status()
+        st = s.json()
+        if st.get("done"):
+            if st.get("error"):
+                print(json.dumps(st, indent=2))
+                sys.exit("generation failed")
+            resp = st.get("response", {})
+            world_id = resp.get("world_id") or resp.get("id")
+            print(f"  done. world_id: {world_id}")
+            break
+        print("  …still generating")
+
+    # fetch authoritative world object
+    w = requests.get(f"{BASE}/worlds/{world_id}", headers=headers)
+    w.raise_for_status()
+    world = w.json()
+    assets = world.get("assets", {})
+
+    OUT.mkdir(parents=True, exist_ok=True)
+    prov = ROOT / "generated" / args.slug
+    prov.mkdir(parents=True, exist_ok=True)
+    (prov / "world.json").write_text(json.dumps(world, indent=2))
+
+    slug = args.slug
+    spz = assets.get("splats", {}).get("spz_urls", {})
+    targets = {
+        f"{slug}.spz": spz.get("500k") or spz.get("full_res") or spz.get("100k"),
+        f"{slug}_collider.glb": assets.get("mesh", {}).get("collider_mesh_url"),
+        f"{slug}_pano.jpg": assets.get("imagery", {}).get("pano_url"),
+        f"{slug}_thumb.jpg": assets.get("thumbnail_url") or assets.get("imagery", {}).get("thumbnail_url"),
+    }
+    saved: dict[str, str] = {}  # role -> public path, e.g. "splat" -> "/worlds/library.spz"
+    for fname, url in targets.items():
+        if not url:
+            print(f"  ! no url for {fname}")
+            continue
+        ext = Path(urlparse(url).path).suffix
+        out = OUT / fname
+        if ext and ext != out.suffix:
+            out = out.with_suffix(ext)
+        print(f"  ↓ {fname} ← {url[:60]}…")
+        dl = requests.get(url)
+        dl.raise_for_status()
+        out.write_bytes(dl.content)
+        print(f"    saved {out.relative_to(ROOT)} ({len(dl.content)//1024} KB)")
+        role = fname.split(".")[0].replace(slug, "").strip("_") or "splat"
+        saved[role] = f"/worlds/{out.name}"
+
+    print(f"\n✓ assets in {OUT.relative_to(ROOT)}")
+
+    # Emit a room.json skeleton for the room primitive (src/data/room.ts). One
+    # room = one folder = one pretty URL (/<slug>/). Assets are filled in;
+    # entryways/exits/artifacts are left empty for marking with `otherplane edit`
+    # (fly with Z, copy floor-snapped spots with C). With no entryways the
+    # renderer best-effort searches for floor until you mark a "default" one.
+    room_dir = ROOT / "rooms" / slug
+    room_dir.mkdir(parents=True, exist_ok=True)
+    room = {
+        "$schema": "../../schema/room.schema.json",
+        "display_name": args.name,
+        "splat_url": saved.get("splat", f"/worlds/{slug}.spz"),
+        "collider_url": saved.get("collider", f"/worlds/{slug}_collider.glb"),
+        "thumbnail_url": saved.get("thumb"),
+        "music_url": None,
+        "calibration": {"scale": 1.0},
+        "entryways": [],
+        "exits": [],
+        "artifacts": [],
+    }
+    room_path = room_dir / "room.json"
+    room_path.write_text(json.dumps(room, indent=2) + "\n")
+    print(f"✓ room skeleton {room_path.relative_to(ROOT)} — run `otherplane edit`, open /{slug}/ to mark it")
+
+
+if __name__ == "__main__":
+    main()

package/skill.md

@@ -0,0 +1,94 @@
+# Skill — turn a personal website into a walkable splat museum
+
+Given someone's personal site, generate a 3D **room** per section, mark its
+spawn/doors/artifacts, link rooms together, and publish a **static walkable
+museum**. Generation is automated; curation and placement are human-in-the-loop.
+
+> The runtime/renderer is documented in `engine/` (its own README + CLAUDE.md).
+> This file is the *authoring* skill — how rooms get made, marked, linked, shipped.
+
+## Providers / stack
+
+| Need                     | Provider                                              | Notes                                                                                                                                                      |
+| :----------------------- | :---------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Room generation          | **World Labs Marble**                                 | `api.worldlabs.ai/marble/v1`; text/image → `.spz` splat + GLB collider. `marble-1.0-draft` for cheap iteration ($1.26). Key in `.env` as `WORLD_LABS_KEY`. |
+| Renderer                 | **WorldSplats** (`engine/`)                           | Spark (splats) + Three.js + Rapier (physics); static export. Content-free viewer.                                                                          |
+| Concept art *(optional)* | **FLUX.2 Pro via fal.ai**                             | photographic concept image for a consistent house style; Marble reconstructs photos best. Not yet scripted.                                                |
+| Room music *(optional)*  | **yt-dlp**                                            | a quiet, loopable track; no key/cost. Manual pull.                                                                                                         |
+| Asset storage            | **Cloudflare R2** (or any object storage / CDN)       | permanent hosting, zero egress. Marble's own URLs have no retention SLA — **self-host anything you want to keep**.                                         |
+| Hosting                  | **GitHub Pages / Cloudflare Pages / any static host** | the built `out/` is plain static files.                                                                                                                    |
+
+## The model (what a museum is)
+
+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.
+
+A room is `rooms/<slug>/room.json` (at the repo root; the CLI mirrors it into
+`engine/public/` at build):
+
+```jsonc
+{
+  "display_name": "Library",
+  "splat_url":    "library.spz",            // resolved RELATIVE to this file
+  "collider_url": "library_collider.glb",
+  "music_url":    "library.mp3",
+  "calibration":  { "scale": 1.0 },
+  "entryways": [ { "id": "default", "pos": [x,y,z], "yaw": deg } ],
+  "exits":     [ { "pos": [x,y,z], "radius": 1.3, "to": "../study/#from-library" } ],
+  "artifacts": [ { "pos": [x,y,z], "radius": 1.0, "url": "https://…" } ]
+}
+```
+
+* **One room = one URL:** `/<slug>/`, entryway via `#fragment` (`/library/#from-study`).
+
+* **entryway** — a named arrival spot (`id`/`pos`/`yaw`). `default` is used when there's no fragment.
+
+* **exit** — walk up + press **E** to follow `to` (a room URL + `#entryway`; relative within a site, absolute across). Dead links 404 by design.
+
+* **artifact** — walk up + interact to open a web URL in an overlay (no travel).
+
+* **assets are URL-agnostic** — resolved relative to the room.json's URL, so they can be colocated, on R2/S3, or on the Marble CDN.
+
+## Pipeline (per room) — ✋ = human checkpoint
+
+1. **Read the section/piece** (essay, repo README, video). Pick a vibe + the artifact object (desk / CRT / telescope / …).
+2. ✋ *(optional)* **Concept image** — FLUX, photographic, in the house style. Approve or regenerate.
+3. **Generate the room:**
+
+   ```bash
+   npm run new -- "<prompt>" --slug <slug> --name "<Name>"
+   ```
+
+   Downloads splat/collider into `worlds/` and writes a `rooms/<slug>/room.json`
+   skeleton (empty entryways/exits/artifacts). Use `--model marble-1.0-draft`
+   while iterating.
+4. ✋ **Mark & wire it** — `npm run edit`, open `/<slug>/`. An authoring panel
+   writes `room.json` for you (no clipboard, no hand-editing):
+
+   * **C** add / move an entryway (floor-snapped `pos`+`yaw`); **B** aim + add /
+     move an artifact; **F** select the orb under the crosshair; **Del** remove;
+     **Z** specter no-clip fly (↑/↓) to reach any spot.
+
+   * In the panel: name entryways, wire **exits** by menu (any room → entryway) or
+     paste an arbitrary URL, **promote** an entryway into a doorway, and click
+     **two-way** to auto-create the reciprocal door in the target room (it reuses
+     that room's existing entryway position — so mark the far side's arrival spot
+     first). Internal exits are relative `../<other>/#<entryway>`; a two-way link
+     is two exits + two entryways.
+6. ✋ *(optional)* **Music** — `yt-dlp` a quiet loopable track into `music/`; set
+   `music_url`.
+7. ✋ *(per artifact)* **Build the styled page** the artifact opens; set its `url`.
+8. **Publish** — mirror the big assets to R2 (durable) and rewrite the `room.json`
+   URLs to point there; then `npm run build` and deploy `engine/out/`
+   to the static host. (Keep big binaries out of git — R2 holds blobs, git holds
+   the tiny `room.json` + the shared bundle.)
+
+## Conventions / gotchas
+
+* **Stable slugs + entryway ids** — other rooms (and other people's museums) link to them; renaming rots links.
+
+* **Self-host keeper assets** — Marble CDN URLs are unsigned/stable today but undocumented, so don't depend on them for anything permanent.
+
+* **`default`** **entryway** is the no-fragment spawn; mark one for every room.
+
+* Marble splats use quaternion `[1,0,0,0]` + `calibration.scale` — handled by the viewer; you only mark coordinates.