Add a source-grounded 3D Model Atlas

CHANGELOG.md

@@ -6,6 +6,10 @@ All notable changes to `explorables` are documented here.
 
 ### Added
 
+- `@explorables/model-atlas`, a source-grounded 3D architecture and trace renderer with strict inert schemas, evidence labels, reviewed source references, semantic controls, exact tensor tables, WebGL fallback, comparison mode, and deterministic cleanup.
+- A learner-facing Transformer Model Atlas in `AI from First Principles` covering the exact tiny teaching model, published GPT-1/2/3 configurations, GPT-4's explicit disclosure boundary, and source-gated DeepSeek V4, Kimi K3, Qwen 3, MiniMax M1, and GLM 5.2 mechanism views.
+- Model Atlas descriptor validation, scene/bundle budgets, renderer and comparison tests, and first-party browser interaction/accessibility coverage.
+
 - Opt-in Guided Course Mode with ordered learner and explorable-event checkpoints.
 - Versioned browser-only progress, deep-link recovery, explicit lesson skipping, confirmed Explore mode, reset, and a local question parking lot.
 - Guided checkpoints and focus-aware tutor policy across all thirteen `AI from First Principles` lessons.
@@ -25,3 +29,4 @@ All notable changes to `explorables` are documented here.
 ### Security
 
 - Guided progress and course-session state remain in the main browser document. Sandboxed explorables retain their existing opaque origin, restrictive CSP, and no-network policy.
+- Model Atlas data cannot supply executable code, markup, styles, shaders, or runtime URLs. Three.js remains inside the existing opaque-origin, no-network iframe and does not require production weights or relaxed permissions.

SECURITY.md

@@ -12,6 +12,8 @@ This browser boundary does not make dependency installation or exercise executio
 
 The runtime has no accounts, secrets, analytics, backend, or remote learner state. The landing page is static and sets no cookies.
 
+3D model-atlas descriptors are inert data and cannot supply HTML, CSS, shader source, executable code, or runtime URLs. Counts, dimensions, graph references, evidence labels, source references, trace values, and scene budgets are validated before rendering. Renderer resources, observers, listeners, and animation frames are disposed when the explorable is destroyed. WebGL initialization failure or context loss must fall back to the synchronized semantic representation without weakening iframe permissions.
+
 ## Report a vulnerability
 
 Do not open a public issue for an exploitable vulnerability. Use GitHub's private vulnerability reporting for `Doppp/explorables` with reproduction, impact, affected commit/version, and any proposed mitigation. If private reporting is unavailable, contact the repository owner through their public GitHub profile and request a private channel.

docs/PRD.md

@@ -981,6 +981,16 @@ Each explorable should include:
 - An accessibility check
 - A browser screenshot or visual regression test for first-party courses
 
+## 10.7 Source-grounded 3D Model Atlas
+
+Courses may use `@explorables/model-atlas` when spatial structure materially helps a learner understand repeated blocks, routing, residual paths, caches, or differences between model families. The Atlas is an explorable module, not a new Markdown directive or lesson language.
+
+Every Atlas descriptor is inert versioned data. Each stage identifies its evidence as `executable`, `configuration-derived`, `report-derived`, `conceptual`, or `undisclosed` and references a reviewed source revision. Exact tensor traces are separate and may come only from tested teaching code or committed deterministic fixtures. A convincing scene must never turn a conceptual aggregation, candidate source, or proprietary gap into an architecture claim.
+
+The 3D canvas is progressive enhancement. The same learning task must remain available through native stage controls, a semantic outline, provenance text, comparison tables, and exact tensor tables where a trace exists. WebGL failure or context loss falls back to this representation. Large model counts are aggregated within validated scene budgets; production weights, runtime downloads, remote assets, analytics, and new iframe permissions are not required.
+
+The first reference Atlas covers the deterministic tiny Transformer, published GPT-1/2/3 configurations, GPT-4's explicit disclosure boundary, and source-gated candidate mechanism views for DeepSeek V4, Kimi K3, Qwen 3, MiniMax M1, and GLM 5.2. Candidate family views omit unfrozen numerical topology until their course-local source and licence gates are complete.
+
 ---
 
 # 11. Sandboxing and security
@@ -1313,6 +1323,8 @@ explorables/
 │   │   └── src/
 │   ├── explorable-sdk/
 │   │   └── src/
+│   ├── model-atlas/
+│   │   └── src/
 │   ├── sandbox/
 │   │   └── src/
 │   ├── validator/
@@ -1391,6 +1403,14 @@ Zod schemas and TypeScript types for:
 - Test utilities
 - Optional adapters
 
+### `@explorables/model-atlas`
+
+- Inert architecture-descriptor and deterministic-trace schemas
+- Evidence and reviewed-source boundaries
+- Bounded Three.js rendering behind the explorable contract
+- Semantic stage, tensor, fallback, and comparison representations
+- Deterministic WebGL/resource lifecycle
+
 ### `@explorables/sandbox`
 
 - Bundling

docs/architecture.md

@@ -17,6 +17,7 @@ COURSE.md + lessons + modules + exercises
 - `@explorables/course-schema`: Zod schemas and shared data types. It knows no filesystem or UI details.
 - `@explorables/markdown`: parses frontmatter and plain Markdown, recognizes only `explorable` and `exercise`, sanitises HTML, and preserves source positions for diagnostics.
 - `@explorables/explorable`: the framework-neutral module/event/handle contract plus mount test helpers.
+- `@explorables/model-atlas`: inert model/trace schemas, evidence-aware comparison, semantic fallback, and bounded Three.js rendering behind the ordinary explorable contract.
 - `@explorables/sandbox`: controlled TypeScript bundling, iframe document/CSP, message validation, lifecycle, and cleanup.
 - `@explorables/validator`: filesystem and cross-file checks that produce actionable diagnostics.
 - `@explorables/runtime`: the React reading/navigation shell and directive UI.
@@ -44,6 +45,12 @@ The iframe CSP defaults to no capabilities: `default-src 'none'` and `connect-sr
 
 This protects the course document context and blocks browser networking. It does not make installing an arbitrary dependency safe; external courses remain unreviewed code and the CLI must display that trust boundary before any future remote-install feature.
 
+### Model Atlas boundary
+
+Model Atlas descriptors are JSON-compatible data with strict keys, IDs, source references, evidence labels, stage-reference integrity, and scene budgets. They cannot contain HTML, CSS, shaders, executable callbacks, or runtime asset URLs. Deterministic tensor traces use a separate schema and must match a descriptor and its stage IDs.
+
+Three.js is an internal renderer dependency. It is bundled by the same controlled pipeline, runs in the same opaque-origin `allow-scripts` iframe, and retains `connect-src 'none'`. The renderer creates no remote requests and loads no model weights. Its canvas is `aria-hidden`; native stage buttons, provenance, comparison rows, and tensor tables are the complete semantic representation. WebGL initialization failure or context loss replaces only the canvas. Destroy disconnects observers, removes listeners, cancels pending frames, and disposes geometries, materials, and the renderer.
+
 ## Exercise boundary
 
 Opening a lesson never runs an exercise. The `exercise` directive links to an existing repository directory and shows its declared test command. Execution is an explicit learner or host action. Tutor policy protects central and solution paths; tests enforce outcomes without progress tracking.

docs/course-authoring.md

@@ -210,6 +210,14 @@ export default module;
 
 For a discovery explorable, provide a baseline/reset, learner-created inputs, visible assumptions and intermediate calculations, a meaningful broken case, and a save-evidence action. Do not call `recordExperiment` during initial render. The authoring review should be able to answer: what new question can a learner investigate that the lesson did not prescribe exactly?
 
+### Source-grounded 3D model views
+
+Use `@explorables/model-atlas` only when spatial structure clarifies a relationship that prose, a matrix, or a small 2D diagram does not. Keep lesson narration in Markdown and mount the Atlas through the ordinary `explorable` directive. Do not add a 3D-specific directive.
+
+Author descriptors as inert data and validate them with `parseModelAtlasDescriptor`. Every stage needs a reviewed source and one evidence label: `executable`, `configuration-derived`, `report-derived`, `conceptual`, or `undisclosed`. Keep exact tensor traces separate and derive them from tested teaching code. If a model card or report does not publish a count, width, schedule, or internal topology, omit it and add an explicit undisclosed stage. Product names and benchmark behavior are not architecture evidence.
+
+The shared renderer supplies keyboard-operable stage controls, a semantic outline, evidence/source text, tensor tables, comparison tables, WebGL fallback, and resource cleanup. Authors still provide a useful Markdown fallback, a prediction or comparison task, descriptor/trace unit tests, narrow-layout browser coverage, and a source/licence freeze before promoting a candidate family descriptor to exact configuration-derived content. Never load production weights, remote textures, fonts, shaders, or data from an Atlas explorable.
+
 Every interaction must work with a keyboard, use labels/native controls where practical, expose important updates through `aria-live`, avoid colour-only meaning, respect reduced motion, and fit a narrow desktop pane.
 
 The CLI bundles the entry. Course-owned Vite configuration, external runtime CDNs, and browser network access are not allowed. Each artifact runs in an opaque-origin iframe with scripts only and `connect-src 'none'`.

docs/course-roadmap.md

@@ -2,6 +2,8 @@
 
 Status: accepted; foundation complete, frontier family planned, DeepSeek V4 and GLM 5.2 refresh complete Planning date: 17 August 2026
 
+The foundation course now includes a source-grounded 3D Model Atlas for comparing the executable tiny Transformer with published GPT configurations and candidate mechanism views of the planned frontier families. This shared view does not make the planned model-family courses runnable or complete their source/licence freezes; unfrozen numerical topology remains explicitly undisclosed.
+
 ## Purpose
 
 `AI from First Principles` is the common foundation for a family of advanced courses about open-weight frontier-model research:

docs/decisions/0009-3d-model-atlas.md

@@ -0,0 +1,55 @@
+# ADR 0009: source-grounded 3D Model Atlas
+
+Status: accepted
+
+Date: 18 August 2026
+
+## Context
+
+The foundation course already exposes exact Transformer calculations through accessible tables and controls. Planned model-family courses need an additional representation for model depth, repeated blocks, routed experts, residual paths, cache state, and architectural comparison. Separate bespoke 3D applications would duplicate interaction code and make visual meaning inconsistent across courses.
+
+Architecture diagrams also create an evidence risk. Public configurations, reports, executable teaching models, and proprietary disclosures provide different levels of certainty. A visually convincing scene must not turn a teaching simplification or undisclosed region into an apparent fact.
+
+## Decision
+
+Add a reusable `@explorables/model-atlas` package after validating the interaction through a course-local tiny-Transformer pilot. The atlas uses Three.js behind an internal renderer boundary and continues to mount through the existing framework-neutral `ExplorableModule` contract.
+
+The atlas has three coordinated modes:
+
+- architecture mode for aggregated model structure;
+- trace mode for exact values from a deterministic teaching model;
+- comparison mode for source-grounded structural differences.
+
+Architecture descriptors are inert, versioned data. Every material stage identifies its evidence as executable, configuration-derived, report-derived, conceptual, or undisclosed and links to a pinned source record. Exact numerical traces remain separate and may only come from tested teaching-model code or committed deterministic fixtures.
+
+The 3D canvas is a progressive enhancement. A synchronized semantic outline, component inspector, exact tensor tables, native controls, reduced-motion behavior, and a WebGL-unavailable fallback expose the same learning task without relying on spatial navigation, color, or motion.
+
+All renderer code, shaders, descriptors, fonts, and teaching data are bundled by the existing controlled pipeline. The iframe remains `sandbox="allow-scripts"` without `allow-same-origin`; `connect-src 'none'` remains unchanged. The atlas does not require WebGPU, WASM, remote model assets, production weights, analytics, or a new Markdown directive.
+
+## Consequences
+
+- Courses share a stable visual grammar while retaining their own prose, source interpretation, exercises, descriptors, and conclusions.
+- Three.js becomes a reviewed browser dependency, but React Three Fiber and a second application framework are avoided.
+- Large layer, head, expert, and cache counts require aggregation and instancing rather than literal scene objects.
+- Model source freezes and licence review precede model-family descriptors.
+- Proprietary GPT lineage views preserve undisclosed regions rather than filling them with inference or rumor.
+- A descriptor schema, renderer lifecycle, semantic mirror, context-loss behavior, performance budgets, and provenance validation become tested public responsibilities.
+- Existing 2D representations remain primary wherever they communicate matrices, distributions, code, or exact values more clearly.
+
+## Rejected alternatives
+
+### Build one custom 3D application per model family
+
+Rejected because it duplicates rendering and accessibility work, fragments visual meaning, and makes comparison unreliable.
+
+### Run full browser models for every architecture
+
+Rejected because production weights, tokenizer downloads, WASM assets, startup time, and network requirements conflict with the local-first sandbox and are unnecessary for structural learning.
+
+### Put all model narration in a scene or tour format
+
+Rejected because plain Markdown remains the readable, portable teaching source. Atlas viewpoints can focus a scene but do not create a second lesson language.
+
+### Require WebGPU
+
+Rejected for the initial implementation because WebGL through Three.js is sufficient, more broadly available, and can be hidden behind a renderer boundary if a future implementation justifies WebGPU.