+ This is the literal graph Echo maintains. Derived artifacts (proxies, pairs, contacts, events) are not hidden engine buffers —
+ they are nodes that tools can query, branch, replay, and merge deterministically. The same initial facts and policies yield the
+ same subgraph and the same snapshot hash on every peer.
+
+
+
+
+
+
+
How Things Move (time-aware proxies)
+
+
BuildTemporalProxy (pre_update)
+
+
+
+ Step 1 — LHS: Collider + Transform (+ Velocity) at Tick n
+
+
+ We gather the collider’s Transform (and optional Velocity) at tick n. In Echo this input is
+ explicit graph state, not a transient engine struct. Chronos gives us a fixed dt, so the motion window
+ for the upcoming tick is well-defined and reproducible.
+
+
+
Different: many engines pull from mutable component state ad‑hoc; here we read typed nodes bound to a specific tick.
+
Determinism: same dt and same components ⇒ same inputs on every peer/branch.
+
+
+
+
+
+ Step 2 — Interface K
+
+
+ The DPO Interface K shows what is preserved between LHS and RHS: collider + transform + tick.
+ This is how we say “the world keeps these facts while we add the proxy.”
+
+
+
Different: Echo makes the preserved context explicit; typical engines merge implicit state in-place.
+
+
+
+
+
+ Step 3 — RHS: TemporalProxy(e,n) added
+
+
+ We add a TemporalProxy with a fat AABB that encloses motion over [start,end]. Padding is derived from
+ velocity and quantized policy, so two peers derive the same box. The proxy links back to the entity and Tick n.
+
+
+
Different: broad‑phase caches become first‑class graph nodes with stable IDs.
+ This rule deterministically derives a TemporalProxy for each collider at tick n.
+ The proxy’s “fat AABB” encloses the body over the whole tick window [start,end], so fast movers can’t tunnel between broad‑phase sweeps.
+ The proxy is a typed node in the graph (not an opaque engine cache) and is linked back to the entity and the producing tick.
+
+
+
Different from typical engines: broad‑phase buffers are usually internal and mutation‑ordered; in Echo they are explicit graph nodes, created by a rewrite with a stable scope and ID.
+
Determinism: proxy size and padding are computed from quantized policy values; insert order is sorted by ID, so peers/branches build identical proxy sets.
+
+
+
+
+
How Collision Works (broad → narrow → events)
+
+
BroadPhasePairing (update)
+
+ Step 1 — LHS: overlapping proxies
We test fat AABB overlap on proxies built for the full tick window. Overlap means the pair is a candidate for narrow phase.
Different: the candidate condition is a graph fact, not an opaque boolean.
The proxies themselves are preserved (K). This makes the rule commute with other rules that may also read them this tick.
+ Step 3 — RHS: PotentialPair added
We mint a PotentialPair with canonical PairId = H(min(A,B)||max(A,B)||branch) and back‑refs to proxies.
Different: pair lists are reproducible data, not engine iteration order.
Determinism: output list is sorted strictly; peers/branches match.
+
+
+
+ The broad phase converts overlapping proxies into PotentialPair nodes. Each pair gets a canonical
+ PairId = H(min(A,B) || max(A,B) || branch) and edges back to the proxies. The emitted list is
+ sorted deterministically, which makes network replication and timeline diffs trivial.
+
+
+
Different: most engines keep an internal unsorted array of candidate pairs; Echo materializes pairs as graph facts, with stable IDs and ordering.
+
Determinism: ties in AABB endpoints break on IDs; output is strictly sorted, so two peers converge on identical pair order.
+
+
+
+
+
+
NarrowPhaseDiscrete (update)
+
+ Step 1 — LHS: discrete overlap @ end pose
For low‑speed pairs, we evaluate shapes at the end pose of tick n. If they overlap, we proceed to build a manifold.
Different: thresholding policy is data; no hidden time‑step heuristics.
+ Step 2 — K: pair preserved
We keep the PotentialPair (K). The narrow phase acts as a pure derivation from pair+poses.
+ Step 3 — RHS: Contact with Manifold added
We create a Contact with a reduced Manifold (2–4 points). Points are canonicalized by feature IDs to ensure reproducible ordering.
Different: engine doesn’t call your code mid‑narrow; it records facts you can read consistently.
Determinism: centralized tolerances + ordering.
+
+
+
+ For low‑speed pairs, we evaluate shapes at end‑of‑tick poses and, if intersecting, create a Contact with a
+ deterministically ordered Manifold (2–4 clipped points). The contact attaches to the pair and to the producing tick.
+ Manifold point ordering and feature IDs are canonicalized to remove platform drift.
+
+
+
Different: instead of imperative callbacks that mutate scripts, Echo records contacts as first‑class nodes; scripts read them after rules run.
+
Determinism: manifold reduction, feature selection, and floating‑point tolerances are centralized and quantized.
+
+
+
+
+
+
NarrowPhaseCCD (update)
+
+ Step 1 — LHS: CCD policy triggers
Policy flags fast motion/small features (or material‑required CCD). We will compute a Toi in [0,1] before creating a contact.
+ Step 2 — K: pair preserved
We keep the pair (K) and run conservative advancement or a swept primitive test to find the impact time.
+ Step 3 — RHS: Toi + Contact added
We emit a Toi node with quantized s and a Contact at the impact pose. Quantization and iteration caps are recorded to make this stable.
+
+
+
+ When a policy indicates high motion or small features, we run CCD: conservative advancement for general convex
+ shapes or closed‑form sweeps for spheres/capsules. We emit a Toi node with quantized s ∈ [0,1] and a Contact
+ at the impact pose. Because s is quantized and the rule scopes are stable, peers compute the same TOI and contact set.
+
+
+
Different: CCD outputs are persisted as graph data (Toi + Contact), not transient solver state; branches and replays see identical values.
+
Determinism: iteration caps, policy thresholds, and s quantization are recorded; identical inputs yield identical s.
+
+
+
+
+
+
ContactEvents (post_update)
+
+ Step 1 — LHS: contact states n-1 vs n
We stage previous and current Contact facts for the pair to compute Begin/Persist/End.
+ Step 2 — K: contacts preserved
K keeps both contact nodes in scope so event construction is a pure comparison, not in‑place mutation.
+ Step 3 — RHS: ContactEvent added
We create a ContactEvent (Begin/Persist/End) sorted by (toi_s, ContactId). Events are nodes that tools and scripts can consume deterministically.
+
+
+
+ We diff previous vs current Contact nodes and create a ContactEvent (Begin/Persist/End) ordered by
+ (toi_s, ContactId). Events are regular nodes and flow through the Temporal Bridge to tools, replay, or networking.
+
+
+
Different: engines typically invoke user callbacks in engine order; Echo records events as data first, then tooling/scripts consume them deterministically.
+
Determinism: strict sort order; event payloads are value objects that hash the same on every peer.
+
+
+
+
+
How We Keep It Clean (deterministic GC)
+
+
GC Ephemeral (timeline_flush)
+
+ Step 1 — LHS: ephemeral nodes
Before flush, the frame has proxies, pairs, TOIs and optional per‑tick contacts. They’re marked ephemeral.
+ Step 2 — Selection
We deterministically select unreferenced, older artifacts for deletion. The retention policy is configured and recorded.
+ Step 3 — RHS: nodes deleted
We remove the selected nodes in a stable ID order. Snapshots after flush are identical across peers/branches.
+
+
+
+ Broad‑phase proxies, potential pairs, transient TOIs and, optionally, per‑tick contacts are ephemeral. At
+ timeline_flush we delete them in a deterministic order. We keep only the high‑value artifacts (Aion‑tagged events, metrics) for tools and audits.
+
+
+
Different: many engines leak implicit caches across frames; Echo models and cleans them explicitly as graph data.
+
Determinism: GC order is sorted by ID; post‑flush snapshots are identical across branches and peers.
+
+
+
+
+
+
+
diff --git a/docs/decision-log.md b/docs/decision-log.md
index e0763c33..8ec05e45 100644
--- a/docs/decision-log.md
+++ b/docs/decision-log.md
@@ -54,3 +54,9 @@
- Decision: Raise the workspace floor (MSRV) to Rust 1.71.1. All crates and CI jobs target 1.71.1.
- Implementation: Updated `rust-toolchain.toml` to 1.71.1; bumped `rust-version` in crate manifests; CI jobs pin 1.71.1; devcontainer installs only 1.71.1.
+## 2025-10-29 — Docs E2E carousel init (PR #10)
+
+- Context: Playwright tour test clicks Next to enter carousel from "all" mode.
+- Decision: Do not disable Prev/Next in "all" mode; allow navigation buttons to toggle into carousel.
+- Change: docs/assets/collision/animate.js leaves Prev/Next enabled in 'all'; boundary disabling still applies in single-slide mode.
+- Consequence: Users can initiate the carousel via navigation controls; E2E tour test passes deterministically.
diff --git a/docs/execution-plan.md b/docs/execution-plan.md
index 76bec188..13e0a0f3 100644
--- a/docs/execution-plan.md
+++ b/docs/execution-plan.md
@@ -33,6 +33,12 @@ This is Codex’s working map for building Echo. Update it relentlessly—each s
## Today’s Intent
+> 2025-10-29 — Docs E2E (PR #10)
+
+- Collision DPO tour carousel: keep Prev/Next enabled in "all" mode so users and tests can enter carousel via navigation. Fixes Playwright tour test.
+- Updated Makefile by merging hooks target with docs targets.
+- CI Docs Guard satisfied with this entry; Decision Log updated.
+
> 2025-10-29 — rmg-core snapshot header + tx/rules hardening (PR #9 base)
- Adopt Snapshot v1 header shape in `rmg-core` with `parents: Vec`, and canonical digests:
diff --git a/docs/guide/collision-tour.md b/docs/guide/collision-tour.md
new file mode 100644
index 00000000..5bb3c340
--- /dev/null
+++ b/docs/guide/collision-tour.md
@@ -0,0 +1,13 @@
+---
+title: Collision DPO Tour
+---
+
+# Collision DPO Tour
+
+The interactive tour illustrates how Echo models collision and CCD as DPO graph rewrites.
+
+- Launch the tour: [docs/collision-dpo-tour.html](../collision-dpo-tour.html)
+- Assets live under `docs/assets/collision/`.
+
+Tip: Toggle the World/Graph tabs in the picture-in-picture panel and use the Prev/Next buttons to step through each rule.
+
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..9a3709db
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,11 @@
+---
+title: Echo Docs
+---
+
+# Echo
+
+Deterministic, multiverse-aware ECS.
+
+- See the Collision DPO Tour: [Open the interactive HTML](./collision-dpo-tour.html).
+- Read the spec: [Geometry & Collision](./spec-geom-collision.md).
+
diff --git a/e2e/collision-dpo-tour.spec.ts b/e2e/collision-dpo-tour.spec.ts
new file mode 100644
index 00000000..14aee96f
--- /dev/null
+++ b/e2e/collision-dpo-tour.spec.ts
@@ -0,0 +1,51 @@
+import { test, expect } from '@playwright/test'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+function fileUrl(rel: string) {
+ return pathToFileURL(resolve(rel)).href
+}
+
+test.describe('Collision DPO Tour (static HTML)', () => {
+ test('loads and renders', async ({ page }) => {
+ await page.goto(fileUrl('docs/collision-dpo-tour.html'))
+ await expect(page.locator('h1')).toHaveText(/Collision/i)
+ // Animate script attaches pagers; ensure at least one exists
+ await expect(page.locator('.pager').first()).toBeVisible()
+ })
+
+ test('tabs toggle World/Graph views', async ({ page }) => {
+ await page.goto(fileUrl('docs/collision-dpo-tour.html'))
+ // Find a figure with pip tabs
+ const tabs = page.locator('.pip-tabs').first()
+ await expect(tabs).toBeVisible()
+ const graphTab = tabs.locator('.tab', { hasText: 'Graph' })
+ const worldTab = tabs.locator('.tab', { hasText: 'World' })
+ await graphTab.click()
+ // Graph image should be visible, world hidden within the same figure
+ const fig = tabs.locator('..') // pip
+ const pip = fig
+ await expect(pip.locator('img[alt="Graph view"]')).toBeVisible()
+ await expect(pip.locator('img[alt="World view"]')).toBeHidden()
+ await worldTab.click()
+ await expect(pip.locator('img[alt="World view"]')).toBeVisible()
+ })
+
+ test('prev/next navigation toggles carousel mode', async ({ page }) => {
+ await page.goto(fileUrl('docs/collision-dpo-tour.html'))
+ const firstRule = page.locator('.rule').first()
+ const nextBtn = firstRule.locator('.pager .btn', { hasText: 'Next' })
+ await expect(nextBtn).toBeVisible()
+ // Initially all slides are visible
+ const figs = firstRule.locator('.step-grid figure')
+ const total = await figs.count()
+ expect(total).toBeGreaterThan(1)
+ // Click next -> enter carousel mode (only one visible)
+ await nextBtn.click()
+ // Wait a tick for layout updates
+ await page.waitForTimeout(50)
+ const hiddenCount = await firstRule.locator('.step-grid figure.hidden').count()
+ expect(hiddenCount).toBeGreaterThan(0)
+ })
+})
+
diff --git a/e2e/playwright.config.ts b/e2e/playwright.config.ts
new file mode 100644
index 00000000..11509fc4
--- /dev/null
+++ b/e2e/playwright.config.ts
@@ -0,0 +1,12 @@
+import { defineConfig } from '@playwright/test'
+
+export default defineConfig({
+ testDir: './e2e',
+ retries: 0,
+ use: {
+ headless: true,
+ viewport: { width: 1280, height: 800 },
+ ignoreHTTPSErrors: true,
+ },
+})
+
diff --git a/package.json b/package.json
new file mode 100644
index 00000000..e040490d
--- /dev/null
+++ b/package.json
@@ -0,0 +1,14 @@
+{
+ "name": "echo-docs-and-tests",
+ "private": true,
+ "scripts": {
+ "docs:dev": "vitepress dev docs",
+ "docs:build": "vitepress build docs",
+ "test:e2e": "playwright test"
+ },
+ "devDependencies": {
+ "@playwright/test": "^1.48.0",
+ "vitepress": "^1.3.3"
+ }
+}
+
diff --git a/scripts/docs-open.sh b/scripts/docs-open.sh
new file mode 100755
index 00000000..3365a020
--- /dev/null
+++ b/scripts/docs-open.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+URL="${1:-http://localhost:5173/}"
+case "${OSTYPE:-}" in
+ darwin*) open "$URL" ;;
+ linux*) xdg-open "$URL" >/dev/null 2>&1 || echo "Open: $URL" ;;
+ msys*|cygwin*|win32*) cmd.exe /c start "" "$URL" ;;
+ *) echo "Open: $URL" ;;
+esac
+
+ 
+ 
+ 
+ 
