---
path: /studio/hathor/simulation-physics
surface: studio
domain: hathor
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/hathor/simulation-physics/page.tsx
status: walked
last_walked:
  '2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data
  (2xx), console/page-errors, expected content, screenshot verified; live
  screen-reader, touch, offline, and telemetry-delivery checks pending a manual
  AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body
  re-derived 2026-06-03 from current source (lane-console architecture)'
---

# Studio Hathor · Simulation Physics

## Purpose

Admin lane console for the physics sibling under the Hathor simulation cluster:
a deterministic point-mass integrator. The operator picks a gravity preset, sets
mass and step count, and the lane runs the real solver and returns the integrated
trajectory (position, velocity, speed per step). It is a sibling lane under the
canonical `/studio/hathor/simulation` aggregator.

## Entry points

- **Quick-action link from `/studio/hathor/simulation`** — "Open Hathor
  Simulation Physics workspace"
- **Quick-action link from `/studio/hathor/npc-behavior-trees`** (verify against
  that page's source)
- **Direct URL / bookmark** — yes; `alternates.canonical` set to
  `/studio/hathor/simulation-physics`
- **Studio overview** — see
  [`../../studio-overview.md`](../../studio-overview.md)

## Layout regions

`page.tsx` renders inside `<ShellLayout active="studio">`:

- **Breadcrumb panel** (`data-hathor-simulation-physics-breadcrumbs`) — `<nav>`
  ol: Studio / Hathor / Simulation (link) / Simulation Physics (sibling lane)
- **Workspace** `<StudioHathorSimulationPhysicsWorkspace />`
  (`data-hathor-simulation-physics-workspace`):
  - `WorkspaceHeading` `<h1>` — "Hathor Simulation Physics Workspace"
  - Summary `<p data-hathor-simulation-physics-summary>`
  - The simulation form lane (loading / unauthorized / error / form / result)
- **Route Map panel** `data-hathor-simulation-physics-route-map` — `<h2>` "Hathor
  Simulation cluster — IA contract"; a role-tagged list built from
  `STUDIO_HATHOR_SIMULATION_PHYSICS_ROUTE_MAP` (7 entries): the
  `parent-aggregator` (`/studio/hathor/simulation`), `self`
  (`/studio/hathor/simulation-physics`), and 5 `peer-lane` siblings
  (simulation-worker, simulation-state-persistence, economy-simulation,
  politics-simulation, culture-evolution-simulation)
- **Quick-action lane** — three `Link.quickAction` anchors: Back to Hathor
  Simulation aggregator, NPC Behavior Trees, Back to Studio workspace index

## States

- [ ] **Loading** — `data-hathor-simphys-loading` "Loading physics engine…"
- [ ] **Unauthorized (admin-scope 401/403)** — `data-hathor-simphys-unauthorized`
      "Access restricted."
- [ ] **Error** — `data-hathor-simphys-error` "Could not load the physics engine."
- [ ] **Ready (form)** — gravity select + mass/steps inputs + submit
- [ ] **Result** — `data-hathor-simphys-result` with per-step
      `data-hathor-simphys-field` rows (`data-hathor-simphys-position`,
      `data-hathor-simphys-velocity`, `data-hathor-simphys-speed`)
- [ ] **Validation error** — `data-hathor-simphys-simulate-error`

## Interactions

### Simulation lane

- [ ] **Gravity** — `<select data-hathor-simphys-gravity>` populated from
      `catalog.gravityPresets`
- [ ] **Mass** — `<input data-hathor-simphys-mass>` (aria-label "mass")
- [ ] **Steps** — `<input data-hathor-simphys-steps>` (aria-label "steps")
- [ ] **Submit** — `<button data-hathor-simphys-simulate-submit>` "Run simulation"
      → POST `SIMULATE_ENDPOINT`

### Route Map panel

- [ ] **Role-tagged entries** — verify parent-aggregator / self / peer-lane roles
      against `STUDIO_HATHOR_SIMULATION_PHYSICS_ROUTE_MAP` (7 entries)

### Quick-action lane

- [ ] **"Back to Hathor Simulation aggregator"** → `/studio/hathor/simulation`
- [ ] **"Open Hathor NPC Behavior Trees workspace"** → `/studio/hathor/npc-behavior-trees`
- [ ] **"Back to Studio workspace index"** → `/studio`

## Data & contracts

- **Reads**: `GET /v1/admin/hathor/simulation-physics` (`SP_ENDPOINT`) — the
  physics catalog (gravity presets, defaults)
- **Writes**: `POST /v1/admin/hathor/simulation-physics/simulate`
  (`SIMULATE_ENDPOINT`) with gravity/mass/steps
- **Realtime**: none
- **Caching**: client `fetch` on mount, `cache: 'no-store'`, `buildBffAuthHeaders()`
- **Auth/role check**: admin-scoped, fail-closed on 401/403; route additionally
  gated signed-in + studio by the BFF proxy

## Cross-references

- Parent aggregator:
  [`./studio-hathor-simulation.md`](./studio-hathor-simulation.md)
- Studio overview: [`../../studio-overview.md`](../../studio-overview.md)
- Shell:
  [`../../../shell/04-auth-session.md`](../../../shell/04-auth-session.md)
- Sibling lanes:
  [`./studio-hathor-simulation-worker.md`](./studio-hathor-simulation-worker.md),
  [`./studio-hathor-simulation-state-persistence.md`](./studio-hathor-simulation-state-persistence.md),
  [`./studio-hathor-economy-simulation.md`](./studio-hathor-economy-simulation.md),
  [`./studio-hathor-politics-simulation.md`](./studio-hathor-politics-simulation.md),
  [`./studio-hathor-culture-evolution-simulation.md`](./studio-hathor-culture-evolution-simulation.md)
- Component sources:
  - `apps/oshun/web/src/components/studio/StudioHathorSimulationPhysicsWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioHathorSimulationPhysicsRouteMap.ts`

## Open questions / known gaps

- [ ] Hathor is `unconfirmed-v1` per `WALKTHROUGH/matrix/routes.csv`. Confirm
      whether the dedicated `/studio/hathor/` lane consoles ship at V1 or are
      internal-only.