otherplane 0.1.0

package/engine/src/data/editApi.ts

@@ -0,0 +1,73 @@
+// src/data/editApi.ts
+// Client for the edit-mode writer — the tiny local HTTP sidecar the `otherplane
+// edit` CLI runs alongside `next dev` (see bin/otherplane.mjs). It is the ONLY
+// thing that writes room.json: edit mode POSTs marked coordinates here and the
+// CLI merges them into the PROJECT source (never the mirror) and re-syncs.
+//
+// This exists only in edit mode. A published static export has no writer and no
+// edit UI, so none of this is ever reachable there.
+
+import type { Entryway, Exit, Artifact, Vec3 } from '@/data/room';
+
+// The CLI passes its port through NEXT_PUBLIC_EDIT_API; fall back to the default.
+const API = process.env.NEXT_PUBLIC_EDIT_API || 'http://localhost:4400';
+
+/** One room as the writer reports it for the exit-target dropdown. */
+export type RoomSummary = {
+  slug: string;
+  display_name: string;
+  entryways: { id: string; pos: Vec3; yaw: number }[];
+};
+
+/** The coordinate data the editor owns and writes back (never asset URLs). */
+export type Marks = {
+  entryways: Entryway[];
+  exits: Exit[];
+  artifacts: Artifact[];
+};
+
+async function req<T>(path: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(`${API}${path}`, {
+    ...init,
+    headers: { 'Content-Type': 'application/json', ...(init?.headers ?? {}) },
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(body?.error || `${res.status} ${res.statusText}`);
+  return body as T;
+}
+
+/** List every room + its entryways, for wiring exits by menu. */
+export async function fetchRooms(): Promise<RoomSummary[]> {
+  const { rooms } = await req<{ rooms: RoomSummary[] }>('/rooms');
+  return rooms;
+}
+
+/**
+ * Persist a room's marks (and optionally its calibration.scale). Asset URLs are
+ * untouched — the CLI merges only the keys we send.
+ */
+export async function saveMarks(
+  slug: string,
+  marks: Marks,
+  calibration?: { scale: number },
+): Promise<void> {
+  const body = calibration ? { ...marks, calibration } : marks;
+  await req(`/rooms/${slug}`, { method: 'PUT', body: JSON.stringify(body) });
+}
+
+/** Merge fields into otherplane.config.json (e.g. the per-museum walk speed). */
+export async function saveConfig(patch: Record<string, unknown>): Promise<void> {
+  await req('/config', { method: 'PUT', body: JSON.stringify(patch) });
+}
+
+/**
+ * Wire a two-way door by reusing each side's existing entryway position. Both
+ * entryways must already exist — the reciprocal exit sits at the entryway you
+ * point it at (you can't conjure the far room's coordinates from this one).
+ */
+export async function linkDoor(
+  a: { slug: string; entryId: string },
+  b: { slug: string; entryId: string },
+): Promise<void> {
+  await req('/doors/link', { method: 'POST', body: JSON.stringify({ a, b }) });
+}

package/engine/src/data/presets.ts

@@ -0,0 +1,34 @@
+// src/data/presets.ts
+import type { Room } from '@/data/room';
+
+// WorldDef is the viewer's internal per-room render shape, built from a Room
+// (roomToWorldDef below). There is no hardcoded world library — the renderer is
+// given one room at a time.
+export type WorldDef = {
+  id: string;
+  name: string;
+  url: string;             // .spz or .ply (Spark auto-detects)
+  colliderUrl?: string;    // GLB collider mesh (Marble) for real wall collision
+  musicUrl: string;
+  position?: [number, number, number];
+  quaternion?: [number, number, number, number]; // x,y,z,w
+  scale?: number;
+};
+
+// All Marble splats share the same canonical transform: identity position, the
+// Spark 180°-about-X flip, and the room's calibrated scale. Per-room
+// rotation/offset is never needed since rooms never share space.
+export function roomToWorldDef(id: string, room: Room, scaleOverride?: number): WorldDef {
+  return {
+    id,
+    name: room.display_name,
+    url: room.splat_url,
+    colliderUrl: room.collider_url,
+    musicUrl: room.music_url ?? '',
+    position: [0, 0, 0],
+    quaternion: [1, 0, 0, 0], // Spark convention: 180° about X
+    // Edit mode drives scale live off the room-scale slider; published builds use
+    // the room's saved calibration.
+    scale: scaleOverride ?? room.calibration.scale,
+  };
+}

package/engine/src/data/room.ts

@@ -0,0 +1,100 @@
+// src/data/room.ts
+// The viewer's ONE primitive: a room. There is no "museum" object — a museum is
+// just rooms linked by exits, exactly like the web is pages linked by hrefs.
+//
+// Each room lives at its own URL (the /r/[id] route, or any remote URL). The
+// renderer is a deep module: "here is one room — its splat, its collider, its
+// music, its entryways, its exits, its artifacts — render it and let me walk."
+//
+// Two distinct concepts that an old "door" used to conflate:
+//   • entryway — a named, addressable spot you ARRIVE at: { id, pos, yaw }. You
+//     spawn at an entryway, facing into the room. It's what a URL fragment points
+//     at (…/library#from-study). One entryway is the "default" (used when the URL
+//     has no fragment).
+//   • exit — a spot you walk up to and INTERACT with (gaze + E) to leave:
+//     { pos, radius, to }. `to` is a URL, normally "<room-url>#<entryway-id>"
+//     (relative within a museum, absolute across museums). Dead exits 404 quietly.
+//
+// artifacts are a third, separate thing: walk up, interact, open a web URL in an
+// overlay — content in place, no transport.
+
+export type Vec3 = [number, number, number];
+
+/** A named spawn point: a position + the yaw you face when you arrive there. */
+export type Entryway = { id: string; pos: Vec3; yaw: number };
+
+/** A walk-up interactive link to another room (or any URL). */
+export type Exit = { pos: Vec3; radius?: number; to: string };
+
+/** Walk up + interact to open `url` in a fullscreen overlay. */
+export type Artifact = { id?: string; pos: Vec3; radius: number; url: string };
+
+export type Room = {
+  display_name: string;
+  splat_url: string;
+  collider_url: string;
+  music_url?: string | null;
+  pano_url?: string | null;
+  thumbnail_url?: string | null;
+  /** Marble reconstructs at arbitrary scale; this brings the room to meters. */
+  calibration: { scale: number };
+  entryways: Entryway[];
+  exits: Exit[];
+  artifacts: Artifact[];
+};
+
+/** The default entryway is the one named "default", else the first listed. */
+export const DEFAULT_ENTRYWAY_ID = 'default';
+
+/**
+ * Resolve which entryway to spawn at. `id` comes from the URL fragment
+ * (…/library#from-study → "from-study"); empty/unknown falls back to the
+ * default. Returns null only if the room declares no entryways at all (a
+ * freshly generated, not-yet-marked room — the renderer then best-effort
+ * searches for floor).
+ */
+export function resolveEntryway(room: Room, id?: string | null): Entryway | null {
+  if (id) {
+    const match = room.entryways.find((e) => e.id === id);
+    if (match) return match;
+  }
+  return (
+    room.entryways.find((e) => e.id === DEFAULT_ENTRYWAY_ID) ??
+    room.entryways[0] ??
+    null
+  );
+}
+
+/** Read the entryway id from a URL hash like "#from-study" → "from-study". */
+export function entrywayIdFromHash(hash: string): string | null {
+  const h = hash.replace(/^#/, '').trim();
+  return h.length ? h : null;
+}
+
+/**
+ * Load a room from its room.json URL. Asset URLs inside are resolved RELATIVE TO
+ * the room.json's own URL — so a room is a portable unit: assets can sit next to
+ * it (`./study.spz`), live on object storage (`https://r2.../study.spz`), or point
+ * at the World Labs CDN. The viewer never cares where the bytes are.
+ */
+export async function loadRoom(url: string): Promise<Room> {
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Failed to load room "${url}": ${res.status} ${res.statusText}`);
+  }
+  const room = (await res.json()) as Room;
+  if (!room.splat_url || !room.collider_url) {
+    throw new Error(`room "${url}" is missing splat_url/collider_url`);
+  }
+  const base = new URL(url, window.location.href);
+  const abs = (u: string | null | undefined) => (u ? new URL(u, base).href : u ?? null);
+  room.splat_url = abs(room.splat_url) as string;
+  room.collider_url = abs(room.collider_url) as string;
+  room.music_url = abs(room.music_url);
+  room.pano_url = abs(room.pano_url);
+  room.thumbnail_url = abs(room.thumbnail_url);
+  room.entryways ??= [];
+  room.exits ??= [];
+  room.artifacts ??= [];
+  return room;
+}

package/engine/src/data/site.ts

@@ -0,0 +1,50 @@
+// Deploy-level config, read from `otherplane.config.json` at the repo root.
+//
+// A museum is just rooms linked by exits — there is no global "museum" object and
+// no start_room baked into the room model. But a single *deploy* still has to
+// answer a few per-deploy questions: which room does the site root (/) land on,
+// what is the page titled, is it served under a sub-path. Those choices belong to
+// the project, NOT to the renderer source — so they live in the project's
+// otherplane.config.json and the engine reads them here.
+//
+// Read at BUILD time and SERVER-SIDE only (it touches fs). Never import this from
+// a 'use client' component, or the build will try to bundle fs for the browser.
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+export type SiteConfig = {
+  /** Slug the site root (/) redirects to. Empty = no redirect. */
+  landingRoom: string;
+  /** Sub-path prefix for project-page hosting ("" = served at domain root). */
+  basePath: string;
+  /** Document <title> / metadata. */
+  siteTitle: string;
+  /** Per-museum walk speed (ships to every viewer). Editable in edit mode. */
+  moveSpeed: number;
+};
+
+const DEFAULTS: SiteConfig = { landingRoom: '', basePath: '', siteTitle: 'Otherplane', moveSpeed: 14 };
+
+function projectDir(): string {
+  // The CLI passes the project root via OTHERPLANE_PROJECT. Falling back to the
+  // engine's parent keeps this repo's sibling layout working when run directly.
+  return process.env.OTHERPLANE_PROJECT || join(process.cwd(), '..');
+}
+
+function load(): SiteConfig {
+  let cfg = DEFAULTS;
+  try {
+    const raw = readFileSync(join(projectDir(), 'otherplane.config.json'), 'utf8');
+    cfg = { ...DEFAULTS, ...JSON.parse(raw) };
+  } catch {
+    cfg = DEFAULTS;
+  }
+  // `otherplane build --base /museum` overrides basePath for a one-off deploy.
+  if (typeof process.env.OTHERPLANE_BASE_PATH === 'string') {
+    cfg = { ...cfg, basePath: process.env.OTHERPLANE_BASE_PATH };
+  }
+  return cfg;
+}
+
+export const SITE: SiteConfig = load();
+export const LANDING_ROOM = SITE.landingRoom;

package/engine/src/data/universeconfig.ts

@@ -0,0 +1,19 @@
+export const CONFIG = {
+  // Physics
+  GRAVITY: { x: 0, y: -9.81, z: 0 },
+  ENVIRONMENT_RESTITUTION: 0.0,
+
+  // Player
+  PLAYER: {
+    RADIUS: 0.33,
+    HALF_HEIGHT: 0.55,
+    START: [0, 1.4, 0] as [number, number, number],
+    FRICTION: 0.9,
+    RESTI: 0.0,
+    // Low, so gravity actually accelerates a fall (real quadratic drop) instead
+    // of capping it at a floaty ~2.5 m/s terminal velocity. Horizontal velocity
+    // is set explicitly every frame in PlayerController, so it doesn't rely on
+    // damping to stop — walking stays snappy.
+    LINEAR_DAMPING: 0.1,
+  },
+}

package/engine/src/icons/ArrowLeft.tsx

@@ -0,0 +1,20 @@
+import React from "react";
+import { IconProps, defaultClassName } from "./icons.interface";
+
+export function ArrowLeftLine({ className }: IconProps) {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      className={className || defaultClassName}
+    >
+      <path d="M19 12H5M5 12L12 19M5 12L12 5"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"/>
+    </svg>
+  );
+}

package/engine/src/icons/ChevronDown.tsx

@@ -0,0 +1,23 @@
+import React from "react";
+import { IconProps, defaultClassName } from "./icons.interface";
+
+export function ChevronDownLine({ className }: IconProps) {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      className={className || defaultClassName}
+    >
+      <path
+        d="M6 9L12 15L18 9"
+        // stroke="black"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}

package/engine/src/icons/ChevronLeft.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { IconProps, defaultStrokeClassName } from "./icons.interface"
+
+export function ChevronLeftLine({ className }: IconProps) {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      className={className || defaultStrokeClassName}
+    >
+      <path
+        d="M15 18L9 12L15 6"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}

package/engine/src/icons/Home.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { IconProps, defaultStrokeClassName } from "./icons.interface";
+
+export function HomeLine({ className }: IconProps) {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      className={className || defaultStrokeClassName}
+    >
+      <path d="M9 21V13.6C9 13.0399 9 12.7599 9.10899 12.546C9.20487 12.3578 9.35785 12.2049 9.54601 12.109C9.75992 12 10.0399 12 10.6 12H13.4C13.9601 12 14.2401 12 14.454 12.109C14.6422 12.2049 14.7951 12.3578 14.891 12.546C15 12.7599 15 13.0399 15 13.6V21M11.0177 2.764L4.23539 8.03912C3.78202 8.39175 3.55534 8.56806 3.39203 8.78886C3.24737 8.98444 3.1396 9.20478 3.07403 9.43905C3 9.70352 3 9.9907 3 10.5651V17.8C3 18.9201 3 19.4801 3.21799 19.908C3.40973 20.2843 3.71569 20.5903 4.09202 20.782C4.51984 21 5.07989 21 6.2 21H17.8C18.9201 21 19.4802 21 19.908 20.782C20.2843 20.5903 20.5903 20.2843 20.782 19.908C21 19.4801 21 18.9201 21 17.8V10.5651C21 9.9907 21 9.70352 20.926 9.43905C20.8604 9.20478 20.7526 8.98444 20.608 8.78886C20.4447 8.56806 20.218 8.39175 19.7646 8.03913L12.9823 2.764C12.631 2.49075 12.4553 2.35412 12.2613 2.3016C12.0902 2.25526 11.9098 2.25526 11.7387 2.3016C11.5447 2.35412 11.369 2.49075 11.0177 2.764Z"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+

package/engine/src/icons/Spinner.module.css

@@ -0,0 +1,13 @@
+@keyframes spin {
+  0% {
+    transform: rotate(0deg);
+  }
+
+  100% {
+    transform: rotate(360deg);
+  }
+}
+
+.spinner {
+  animation: spin 1s linear infinite;
+}

package/engine/src/icons/Spinner.tsx

@@ -0,0 +1,28 @@
+import clsx from "clsx";
+import { ComponentProps } from "react";
+import styles from "./Spinner.module.css";
+
+export interface Props extends ComponentProps<"svg"> {
+  size?: number;
+}
+
+export function Spinner({ size = 16, className, ...props }: Props) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 16 16"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      className={clsx(className, styles.spinner)}
+      {...props}
+    >
+      <path
+        d="M14 8a6 6 0 1 1-6-6"
+        stroke="currentColor"
+        strokeWidth="2"
+        vectorEffect="non-scaling-stroke"
+      />
+    </svg>
+  );
+}

package/engine/src/icons/VolumeMax.tsx

@@ -0,0 +1,21 @@
+import React from "react";
+import { IconProps, defaultStrokeClassName } from "./icons.interface";
+
+export function VolumeMaxLine({ className }: IconProps) {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      className={className || defaultStrokeClassName}
+    >
+      <path d="M19.7479 5.00005C21.1652 6.97029 22 9.38768 22 12C22 14.6124 21.1652 17.0298 19.7479 19M15.7453 8.00005C16.5362 9.13388 17 10.5128 17 12C17 13.4873 16.5362 14.8662 15.7453 16M9.63432 4.36573L6.46863 7.53142C6.29568 7.70437 6.2092 7.79085 6.10828 7.85269C6.01881 7.90752 5.92127 7.94792 5.81923 7.97242C5.70414 8.00005 5.58185 8.00005 5.33726 8.00005H3.6C3.03995 8.00005 2.75992 8.00005 2.54601 8.10904C2.35785 8.20492 2.20487 8.3579 2.10899 8.54606C2 8.75997 2 9.04 2 9.60005V14.4C2 14.9601 2 15.2401 2.10899 15.454C2.20487 15.6422 2.35785 15.7952 2.54601 15.8911C2.75992 16 3.03995 16 3.6 16H5.33726C5.58185 16 5.70414 16 5.81923 16.0277C5.92127 16.0522 6.01881 16.0926 6.10828 16.1474C6.2092 16.2093 6.29568 16.2957 6.46863 16.4687L9.63431 19.6344C10.0627 20.0627 10.2769 20.2769 10.4608 20.2914C10.6203 20.304 10.7763 20.2394 10.8802 20.1177C11 19.9774 11 19.6745 11 19.0687V4.93142C11 4.3256 11 4.0227 10.8802 3.88243C10.7763 3.76073 10.6203 3.69614 10.4608 3.7087C10.2769 3.72317 10.0627 3.93736 9.63432 4.36573Z"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}

package/engine/src/icons/VolumeX.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { IconProps, defaultStrokeClassName } from "./icons.interface";
+
+export function VolumeXLine({ className }: IconProps) {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      className={className || defaultStrokeClassName}
+    >
+      <path
+        d="M22 9.00005L16 15M16 9.00005L22 15M9.63432 4.36573L6.46863 7.53142C6.29568 7.70437 6.2092 7.79085 6.10828 7.85269C6.01881 7.90752 5.92127 7.94792 5.81923 7.97242C5.70414 8.00005 5.58185 8.00005 5.33726 8.00005H3.6C3.03995 8.00005 2.75992 8.00005 2.54601 8.10904C2.35785 8.20492 2.20487 8.3579 2.10899 8.54606C2 8.75997 2 9.04 2 9.60005V14.4C2 14.9601 2 15.2401 2.10899 15.454C2.20487 15.6422 2.35785 15.7952 2.54601 15.8911C2.75992 16 3.03995 16 3.6 16H5.33726C5.58185 16 5.70414 16 5.81923 16.0277C5.92127 16.0522 6.01881 16.0926 6.10828 16.1474C6.2092 16.2093 6.29568 16.2957 6.46863 16.4687L9.63431 19.6344C10.0627 20.0627 10.2769 20.2769 10.4608 20.2914C10.6203 20.304 10.7763 20.2394 10.8802 20.1177C11 19.9774 11 19.6745 11 19.0687V4.93142C11 4.3256 11 4.0227 10.8802 3.88243C10.7763 3.76073 10.6203 3.69614 10.4608 3.7087C10.2769 3.72317 10.0627 3.93736 9.63432 4.36573Z"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}

package/engine/src/icons/icons.interface.ts

@@ -0,0 +1,7 @@
+export type IconProps = {
+  className?: string;
+};
+
+export const defaultStrokeClassName = "stroke-primary";
+export const defaultFillClassName = "fill-primary";
+export const defaultClassName = `${defaultStrokeClassName} ${defaultFillClassName}`;

package/engine/src/icons/index.ts

@@ -0,0 +1,27 @@
+export * from "./ChevronLeft";
+export * from "./ChevronDown";
+export * from "./ArrowLeft";
+export * from "./Spinner"
+export * from "./VolumeMax"
+export * from "./VolumeX"
+export * from "./Home"
+
+export enum IconColor {
+  Primary = "primary",
+  Secondary = "secondary",
+  Tertiary = "tertiary",
+  InvertedPrimary = "inverted-primary"
+}
+
+export type IconProps = {
+  className?: string;
+  color?: IconColor;
+};
+
+export const defaultFillClass = "fill-primary";
+export const defaultStrokeClass = "stroke-primary";
+
+export const fillClass = (color: IconColor | undefined) =>
+  `fill-${color ? color : "primary"}`;
+export const strokeClass = (color: IconColor | undefined) =>
+  `stroke-${color ? color : "primary"}`;