VISUALMODE LEARNING CONTRACT

Questions first. Docs second.

This route is for steering the project by understanding it together. Each session starts with one question, reads a small source set, and ends with a concrete artifact we can challenge or promote into current docs.

01

One question at a time

A session starts from a concrete question, not a broad tour. Stop when the answer is clear enough to restate.

02

Evidence before vocabulary

New terms matter only after we tie them to a file, test, runtime behavior, or decision in this repo.

03

Architecture waits for shared understanding

We can study tradeoffs now, but we do not change boundaries until the current behavior and proof are understood.

04

Docs stay small

Learning notes should create better questions and sharper decisions. They should not become a second project wiki.

WORKING LOOP

How we dig without making another pile

Orient

Question
What are we trying to understand right now?
Method
Pick one route, crate, renderer path, or validation gate.
Output
A one-sentence question and the files that can answer it.

Inspect

Question
What does the code or test actually say?
Method
Read the smallest source set and separate facts from inference.
Output
Three to five facts with file references.

Explain back

Question
Can you restate the behavior in your own words?
Method
I challenge vague terms and fill in missing background only where needed.
Output
A short mental model plus the parts still unclear.

Record

Question
Does this change project truth or only our understanding?
Method
Promote only durable facts to `.claude/*`; keep session-only notes out of canonical docs.
Output
Either a current-doc update, an explicit deferral, or no docs change.

START HERE

Five guided sessions

01

Repo Control Surface

Which files decide what contributors should touch first?

This sets the project steering map before touching Rust, WebGPU, Solid, or renderer details.

Read

README.mdAGENTS.md.claude/README.md

Inspect

.claude/planning/work-queue.mdpackage.json

Ask

  • What is active, frozen, archived, and generated?
  • Which command proves a docs-only change?
  • Where should a new architecture fact be recorded?

Session output

A four-bucket map: active app, root engine, generated packages, archive/reference.

02

Route And Renderer Entry

What happens when a user opens `/canvas/$canvasId` or `/world/$worldId`?

The route layer is where product intent, browser capability, and renderer fallback first meet.

Read

.claude/engineering/architecture.md.claude/vision/capabilities.md

Inspect

src/routes/canvas.$canvasId.tsxsrc/routes/world.$worldId.tsxsrc/app/canvas/CanvasEntryProductResourceRoute.tsx

Ask

  • Which renderer is default?
  • Why is the editor surface mounted in `__root.tsx` instead of the route component?
  • What belongs to TypeScript, and what belongs to Rust/WASM?

Session output

A route flow diagram in words, including every fallback path.

03

v3 Crate Boundaries

Why is v3 split into foundation, core, renderer, WASM, and CLI crates?

Crate boundaries are the main architecture lever for keeping renderer math, browser APIs, and editor state separate.

Read

.claude/engineering/architecture.md.claude/engineering/porting.md

Inspect

engine/Cargo.tomlengine/crates/*/Cargo.toml

Ask

  • Which crates should stay pure Rust?
  • Which crates are browser-facing?
  • Which crate proves pixels without a browser?

Session output

A dependency-direction sketch and a list of boundaries we should protect.

04

Proof, Not Confidence

Which gate proves which claim?

Most wrong project decisions here come from treating source presence, diagnostics, or one green test as full proof.

Read

.claude/engineering/validation.md.claude/vision/capabilities.md

Inspect

tests/e2e/canvas-radial-insert.spec.tstests/visual/v3-3d/engine/crates/cli/src/

Ask

  • When do CLI snapshots matter more than Playwright?
  • When do browser visual tests matter more than CLI snapshots?
  • What cannot be proven by DOM attributes?

Session output

A claim-to-gate table for the current task.

05

Archive As Oracle

When is it useful to read v1 or old v2, and when is it dangerous?

Archives should explain required behavior, not silently become dependencies or stale truth.

Read

.claude/engineering/archive-policy.md.claude/engineering/porting.md

Inspect

archive/source/v1-engine/pre-v3:archive/source/v2-engine/ (git tag)

Ask

  • What behavior are we borrowing?
  • Where will that behavior live in v3?
  • Which test or deferral closes the loop?

Session output

A porting handoff: source, destination, proof, and non-goal.

TECH LENSES

Learn each tool through its job here

SolidJS + TanStack Router

Owns routes, editor shell composition, signals, panels, and browser lifecycle.

src/routes/*.tsxsrc/app/canvas/CanvasEntryProductResourceRoute.tsxsrc/app/canvas/CanvasEntrySurface.tsx
  • Where does route state stop and editor state begin?
  • Which state is shown in panels versus owned by the canvas?

Rust + WASM

Owns engine contracts, renderer-facing data, interaction semantics, and browser-callable APIs.

engine/crates/core-3d/engine/crates/wasm-3d/src/app/engine-pkg/
  • What crosses the JS/WASM boundary?
  • Which behavior must not be reimplemented in TypeScript?

WebGPU + WGPU

Owns production renderer surfaces, GPU resources, readback, and visual proof.

engine/crates/renderer-3d/engine/crates/renderer-2d/tests/visual/
  • What is rendered on the GPU surface?
  • Which readback proves picking or pixels?

CLI Snapshots + Playwright

Separates exact renderer-pixel proof from browser integration, input behavior, and visual presentation.

engine/crates/cli/tests/e2e/tests/visual/
  • What claim does this test actually prove?
  • Which gate should fail before we call a feature done?

REUSABLE PROMPT

The shape of a good digging session

Question:
What exactly are we trying to understand?

Read:
- only the current docs and files needed for this question

Tell me:
- facts with file references
- inferences clearly labeled
- terms I need to understand
- what remains unclear
- which architectural decision this affects

Do not change architecture.
Do not expand the scope until I can explain this slice back.

PLAIN LANGUAGE

Starter glossary

Current docs

The small canonical docs under `.claude/*`, plus top-level `README.md` and `AGENTS.md`.

Source of truth

For behavior, code and tests win. For project policy, current docs win until code/tests contradict them.

v2

The frozen Rust/WASM engine workspace under `engine/crates/*`; fixes only, no new features.

v3

The active recovery workspace under `engine/*`, rebuilding Rust/WGPU rendering into the current app split.

WASM boundary

The API layer where browser TypeScript calls into Rust-compiled WebAssembly.

CLI snapshot

A headless renderer test that turns a JSON scene script into pixels and compares it to a baseline image.

Browser visual gate

A Playwright visual test that proves the app presents real browser-rendered pixels, not just diagnostics.

Archive oracle

Historical source or docs used to understand intended behavior, never as active product code or unverified truth.

VISUALMODEAI