di.iiii

di.iiii hosts 3D spaces on the web

You sign in, get an address, build a scene in the browser, mark one project live, and hand out the link — it opens on a phone, a laptop or a headset with nothing to install, and exports as a file when it ends. The editor runs in the browser; the backend owns persistence, auth, and publish state; spaces are the public unit. No native installs, no engine lock-in, creator-owned data.

Start Here

• main editor: Studio
• node editor: /<space>/raw (src/raw/)
• compatibility lane: V1
• backend authority: serverXR
• public unit: space
• editable document inside a space: project
• live public route for a space: publishedProjectId
• where things run — two lanes, four names, one rule:
  • dev branch → dev.diiii.xyz, the dev tier (rehearsal — work and verify here)
  • main branch → diiii.xyz, prod (live — promote dev -> main only after the dev tier is verified)
• runtime baseline: Node 22.x, npm 10.x

Project links:

• live site: di-studio.xyz
• primary public repo: dob-0/di.iiii
• latest checkpoint: Checkpoint 2026-04-09
• AI quick context: AGENTS.md
• AI knowledge base: docs/ai/index.md
• public-context materials: docs/deck
• repo visibility and mirror status: Private Dev And Public Showcase Workflow
• deploy runbook: Live Deploy Runbook

Current Truth

This is the shipped, working reality of the repo today.

• Studio is the stable main editor.
• the node editor at /<space>/raw (src/raw/) is where recursive node-first work happens.
• V1 remains for compatibility, fallback behavior, and migration-sensitive work.
• serverXR is authoritative for spaces, projects, assets, ops, SSE, presence, and edit enforcement.
• public routes use /<space> for the live published view, with /<space>/studio, /<space>/raw, and /admin?space=<space> for editing and ops
• any project link opens for editing by appending the tool: /<space>/<project>/studio, or /<space>/<project>/raw. A shortcut, not a second address — it redirects to the editor's canonical path, so nothing new has to be kept alive forever
• the lists live at the level they list: /spaces for your spaces, /<space>/projects for what a space shows its visitors. The tool-named forms (/<space>/studio, /<space>/raw/projects) are the one working list a space's makers use — drafts, shelves and the trash — the same list at both, a card opening in Studio or in Nodes
• persistence is still single-host filesystem storage
• writes are protected by session/token-based auth, not a full multi-user identity and audit model yet

Direction

This is where the project is going, but not all of it is fully shipped yet.

• move toward recursive node-first project documents and node ops
• prefer shared project logic over expanding older one-off editor paths
• keep the web as the universal authoring and runtime substrate
• support spaces that reach into the physical world and linked hardware over time

Space + Project Workflow

Use this as the default path for new work in a space:

1. Create or open a space from the admin surface or the spaces panel. Space creation provisions the server record and a blank scene.
2. Open /<space>/studio for the main editor. Create new projects there, import legacy scenes, and keep the long-term working copy.
3. Use /<space>/raw for node-first work when the project needs research-style iteration.
4. Publish the chosen project to the public route by setting publishedProjectId for the space; /<space> then shows the live project viewer.

Important distinction:

• Current Truth = what is real in the repo now
• Direction = where new work should lean
• bridge code = necessary, active, but not always canonical

Mental Model

• space
  • the public and management unit
  • owns routes like /<space>, /<space>/studio, and /<space>/raw
• project
  • the editable document inside a space
  • stored independently from the public route
• publishedProjectId
  • the project currently shown on the public route for that space
• long-term document shape
  • rootNodeId
  • nodes[]
  • edges[]
  • assets[]
  • templates[]
  • workspaceState

Repo Map

Path	Role	Use It For
src/studio/	stable main editor	main user-facing product work
src/raw/	the node editor	research and recursive-node work
src/project/	shared project logic center	document state, sync, presence, asset flow, shared editor/viewer logic
src/shared/ and shared/	cross-runtime schema and contracts	canonical schema/runtime definitions
serverXR/	backend runtime	auth, persistence, assets, presence, SSE, publish state
docs/architecture/	deeper architecture docs	repo intent, direction, and system explanations
src/components/ and src/hooks/	older orchestration surfaces that still matter	active behavior, but not always best home for new permanent logic

For Humans And AI Agents

Use these defaults unless the task clearly says otherwise.

• default to Studio for main product work
• default to src/project/ for shared document or collaboration logic
• use the node editor (src/raw/) only when the task is intentionally node-first
• prefer node-first behavior over growing legacy object/window systems
• treat worldState, windowLayout, and older entity structures as compatibility bridges
• treat V1 work as compatibility work unless the task is explicitly about migration or legacy support

Common mistakes to avoid:

• do not describe the node editor as the main shipped editor — that is Studio
• do not describe physical sync or hardware-linked workflows as fully productized repo capability
• do not assume older orchestration files are the right long-term home for new canonical behavior
• do not push private ops material, raw dev-tier details, .env files, or host-specific deployment secrets into the public repo

For AI task assignments, use the task request template in AGENTS.md.

Quick Start

Local setup:

nvm use
npm install
npm --prefix serverXR install

Normal start-of-session flow:

git switch dev
git pull --ff-only origin dev
npm run dev

Core commands:

npm run dev
npm run lint
npm run build
npm run test
npm run test:server-contracts

Useful local routes:

• http://localhost:5173/main
• http://localhost:5173/main/studio
• http://localhost:5173/main/raw
• http://localhost:5173/admin?space=main
• http://localhost:4000/serverXR/api/health

Contributing

There are two doors, and most people only need the first:

• Collaborating on a space — you were invited to build, not to run di.iiii. Nothing to install: di-studio.xyz/wiki#joining-a-space is the whole path, from the invite link to your first saved edit.
• Working on the code — clone, run, and change di.iiii itself. Start with ONBOARDING.md: prerequisites, fork + clone, local env setup, npm run dev, and setting up Claude Code with the project's checked-in AI workflow (don't start a fresh one — see ONBOARDING §8).

The code path is fork-based:

1. Fork dob-0/di.iiii, clone your fork, work there freely
2. Validate before sharing: npm run lint && npm run build && npm run test
3. Push to your fork and open a PR against this repo's dev branch (or let docs/templates/fork-auto-pr.yml open it for you automatically on push, once set up)
4. We review and merge into dev from the upstream side

An AI agent working in your own fork can validate, commit, and push on its own once a task is done — pushing only ever updates your fork, never dob-0/di.iiii directly, so this is safe to leave unattended. Merging into dev/main always stays an explicit, human-requested action.

For running more than one agent/contributor at once without anyone's edits colliding (git worktrees, role-scoped file ownership, fork isolation), see docs/ai/parallel-agents.md.

Release Flow

Normal promotion path:

1. work on dev
2. validate locally
3. push dev — it deploys the dev tier (dev.diiii.xyz)
4. verify on the dev tier
5. promote to main

Deploys are driven by pushes, via GitHub Actions (GHCR build + SSH to the Hetzner VPS):

git push origin dev    # deploys the dev tier (dev.diiii.xyz) — see .github/workflows/deploy-vps-dev.yml
git push origin main   # deploys to VPS production — see .github/workflows/deploy-vps.yml

Both wired up and verified end-to-end (2026-07-16): GitHub secrets/variables are set, both workflows sync tracked config from git and reload Caddy as needed. See docs/deploy/VPS_DOCKER_DEPLOY.md for the full setup this relies on.

npm run deploy:* (scripts/deploy.mjs) is the older cPanel-era path, kept only as a documented fallback (see docs/deploy/legacy/) — it is not how di-studio.xyz is deployed today.

Rules:

• normal work starts on dev
• do not start routine feature work on main
• use main directly only for emergency production hotfixes

Publishing Content to a Space

For pushing teaser pages, multi-file experiences, or project packages to a live /<space> route, see the Publish Workflow. Options: in-app update, branch-hosted URL, ZIP import, full code deploy.

Repo And Hosting Topology

flowchart LR
    work["Daily work"] --> dev["dob-0/di.iiii<br/>primary public repo"]
    dev --> branchDev["dev branch"]
    dev --> branchMain["main branch"]
    branchDev --> ghcrDev["GHCR build<br/>deploy-vps-dev.yml"]
    branchMain --> ghcrProd["GHCR build<br/>deploy-vps.yml"]
    ghcrDev --> vpsDev["Hetzner VPS<br/>dev tier Compose project<br/>→ dev.diiii.xyz"]
    ghcrProd --> vpsProd["Hetzner VPS<br/>production Compose project<br/>→ di-studio.xyz"]
    branchMain -.disabled fallback.-> release["cpanel-* release branches"]
    release -.-> hosting["cPanel hosting<br/>(legacy, workflow_dispatch-only)"]

Read Next

By task:

• AI knowledge base: docs/ai/index.md
• user-facing help (in-app /wiki + landing teaser, single source of truth): src/wiki/wikiContent.js
• documentation sync system (how the surfaces stay in lockstep): docs/ops/doc-sync-system.md
• new contributor setup: ONBOARDING.md
• self-hosting a space (portable bundle export/import): docs/deploy/SELF_HOST.md
• running multiple agents/contributors at once: docs/ai/parallel-agents.md
• shared project logic: src/project/AGENTS.md
• backend/runtime: serverXR README
• project architecture: Project Surfaces
• node model direction: Recursive Node Core
• audit and growth plan: Project Audit And Growth Plan
• latest checkpoint: Checkpoint 2026-04-09
• development framework: Project Development And Optimization Framework

Evergreen Rule

Keep this README focused on durable repo truth:

• what the project is
• how the repo is structured
• what is shipped now
• where new work should go

Put dated milestones, application-specific notes, and time-sensitive movement into supporting docs instead of this root entrypoint.