# St Joseph's Curriculum Portal — Comprehensive LLM Architecture Dossier (llms-full.txt)

> Deterministic, privacy-first, on-device AI educational portal running via in-browser WebRTC loopback channels, Chrome Prompt API (Gemini Nano), WebLLM, and autonomous 60 FPS vector media engines. The AST player serves a dual-market architecture: perpetually free for schools, Catholic organisations, and developing nations (Track A Humanitarian Commons), and commercially licensed for enterprise Digital Signage (DOOH), Programmatic Display Advertising, and Interactive Kiosks (Track B).

---

## 1. System Vision & Foundational Tenets

1. **Education Should Be Free**: The portal is perpetually free and open-source under a dual-licensing humanitarian model (GNU AGPLv3 for public and humanitarian use, commercial dual-licence for proprietary deployments).
2. **Zero Cloud Leakage**: Student logs, responses, voice transcripts, and mastery progress remain strictly client-side in browser IndexedDB (`services/dbStore.ts`). No student data egresses to remote cloud servers.
3. **Multi-Modal Tuples Architecture**: Unifies vector graphics, synchronized video underlays/overlays, procedural audio synthesis, reactive S-Expression data bindings, sub-pixel pointer gestures, and formative assessment gates into a coherent, atomic tuple structure.
4. **Decoupled & Domain-Agnostic Engine**: The core vector engine is strictly **< 35 KB gzipped** (< 150 KB uncompressed) with zero external npm runtime dependencies. All domain-specific hardcoding has been eliminated; dynamic parameter HUDs discover variables, bounds, and interactive controls automatically for ANY domain (education, science, engineering, or digital signage).
5. **Bandwidth & Hardware Sovereignty**: Designed to operate flawlessly on $30 legacy hardware, Chromebooks, and metered mobile 2G/3G connections. Cold start is < 15 ms, with a memory footprint < 8 MB RAM.
6. **Air-Gap Classroom Readiness**: Standalone HTML cartridges and the full portal can be bundled as an air-gapped single file (`exportAirgapHtmlBundle.ts`), bootable directly from USB thumb drives in off-grid rural schools with zero internet connection.
7. **Classroom Smartboard First**: Built-in quadratic Bézier ink whiteboard layer (`#annotation-ink-root`) optimized for stylus pen interaction on Promethean, SMART, ViewSonic boards, and iPads.

---

## 2. Full Route & Resource Map

### User-Facing Routes
- `/` : Portal Home, Subject Hub, Quick Practice Starters, and System Diagnostics.
- `/media-player` : Full-featured AST Vector Media Player with interactive simulation stage, 3D camera controls, parameter sliders, teacher HUD, and audio sonification.
- `/player` : Alias to `/media-player`.
- `/player.html` : Lightweight zero-dependency embeddable vector stage, OBS studio broadcast controller, and developer inspection lathe.
- `/cartridges` : Decentralized Cartridge Vault, offline ROM repository, PhET/SWF transpiler bridge, and cartridge compressor.
- `/phonics` : EYFS & KS1 Phonics Sounds Suite, DfE Phases 2–5 soundboard, blending mat, Alien Words screening check & flashcards.
- `/languages` : MFL & Polyglot Languages Studio, Spanish, French & Latin comparative phonics, verb conjugation wheels, etymology bridges.
- `/bsl` : 3D British Sign Language (BSL) Studio, 360° rotatable 3D two-handed manual alphabet, vowel tap positions, Signer vs Receiver POV.
- `/shakespeare` : Shakespeare Globe Theatre Suite, 1599 Wooden O 3D stage geometry, 5-Act dramatic play-throughs, spoken blank verse & metronomes.
- `/practice-lab` : Formative assessment arena featuring interactive AST cartridges, AI hints (Professor Turing persona), and misconception diagnostics.
- `/learning-zone` : National curriculum lesson player aligned with Oak National Academy learning objectives.
- `/curriculum-studio` : Visual curriculum authoring workspace, S-Expression graph generator, and prompt hydrator.
- `/catholic-life` : Catholic life, 3D Sanctuary explorer, Holy Water & Thurifer altar server simulator, liturgical calendar, and sacramental catechesis.
- `/first-communion` : Catechetical module for First Holy Communion preparation.
- `/teacher-beacon` : Teacher broadcast console, real-time classroom sync, and Smartboard remote presenter.
- `/profile` : Learner mastery passport, streak history, diagnostic records, and achievement badges stored in IndexedDB.
- `/settings` : Neural hardware probe, WebGPU check, Gemini Nano Prompt API toggles, and audio settings.
- `/news` & `/blog` : Technical dispatches, pedagogical essays, and system release announcements.
- `/licensing` : Humanitarian Commons charter, GNU AGPLv3 terms, and educational covenant.
- `/privacy` : GDPR-compliant zero-cloud sovereign privacy guarantee.
- `/child-safety` : Safeguarding and on-device student safety standards.

### Machine-Readable Endpoints & Manifests
- `/llms.txt` : Concise machine-readable context file following the llms.txt standard.
- `/llms-full.txt` : Comprehensive full-system briefing file for large-context models.
- `/robots.txt` : Web robot and AI bot discovery policy.
- `/sitemap.xml` : XML sitemap indexing all public curriculum portals and manifests.
- `/sitemap.ast` : S-Expression sitemap indexing self-mounting cartridges.
- `/manifests/catalog.json` : Master curriculum catalogue indexing subjects, units, and learning objectives.
- `/manifests/rag-index.json` : Pre-indexed semantic embeddings for offline retrieval-augmented generation.
- `/player/scenes.manifest.json` : Index of all 46 production vector simulation cartridges.
- `/player/scenes-config.json` : Timeline keyframes, multilingual subtitles (EN/ES/FR/LA/DE/IT), and pause checkpoints.
- `/player/grammar/ast-sexpr.gbnf` : GGML/GBNF grammar defining AST S-Expression syntax for constrained AI decoding.
- `/player/grammar/ast-scene.gbnf` : GGML/GBNF grammar defining full scene graph structure.
- `/nano-map.ast` : Compact curriculum domain schema parsed by `sexprParser.ts`.

---

## 3. The Multi-Modal Tuples Specification

The AST architecture treats media not as disparate layers or separate streams, but as an atomic, mathematically synchronized **Multi-Modal Tuple**:

$$\text{Tuple} = \Big\langle \mathbf{V}_{\text{vector}},\, \mathbf{V}_{\text{video}},\, \mathbf{A}_{\text{synth}},\, \mathbf{D}_{\text{reactive}},\, \mathbf{G}_{\text{gestures}},\, \mathbf{C}_{\text{checkpoints}} \Big\rangle$$

### 3.1. Vector & Video Synchrony
- **Hybrid Presentation Layer**: The engine supports simultaneous video underlays/overlays (`hasVideo: true`) with responsive vector elements layered directly on top in the same coordinate space (`viewBox="0 0 800 480"`).
- **`videoFit` Modes**: Configurable `:video-fit "contain"` (letterbox preservation) or `:video-fit "cover"` (full-bleed display signage), ensuring identical aspect ratio alignment between background video frames and interactive vector coordinate probes.
- **Master Clock Locking**: Both the native `<video>` element and the 60 FPS vector timeline derive from a single high-resolution master clock. Scrubbing the timeline scrubs the video frame instantly with zero drift; pausing the vector stage pauses the video stream; formative pause checkpoints freeze video playback automatically.
- **Dynamic HUD Over Video**: Vector annotations, pointers, data readouts, and bounding boxes react dynamically to video timestamps without burning overlays into the video file itself.

### 3.2. Procedural Audio Sonification
- **0 KB Asset Overhead**: Procedural Web Audio API synthesis replaces static WAV/MP3 files.
- **Waveform Synthesis**: Generates tactile switch clicks, ascending pentatonic success chimes (C5-E5-G5-C6), dissonant error tones, and continuous pitch-modulated frequencies (e.g. pressure hums, Doppler shifts, or musical intervals) strictly from mathematical oscillator functions.

### 3.3. S-Expression Reactive Data-Flow
- **Mathematical Binding Engine**: Real-time attribute binding via `:bindings (:target "#id" :attr "attrName" :expr "(formula)")`.
- **Dynamic Expression Evaluation**: Evaluates formulas at 60 FPS using sanitized arithmetic parsers supporting standard trigonometric, exponential, and algebraic functions without `eval()` security risks.

---

## 4. Decoupled, Domain-Agnostic Flash-Caliber Engine

The AST Vector Engine (`static/player/ast-engine.js` and `@stjosephs/ast-vector-player`) is fully decoupled from the React host portal and completely domain-agnostic:

### 4.1. Elimination of Domain-Specific Coupling
- **Universal 3D Detection**: `has3D()` dynamically detects `:3d-node`, `:camera`, `:mesh`, `:3d-line`, `:3d-ring`, or `:3d-polygon` tags rather than checking hardcoded scene IDs.
- **Generic Master Clock**: Simulations advance a universal time accumulator `vars._simClock` (with backwards compatibility for legacy `_solarClock`), enabling continuous or periodic animations across any subject without engine customization.
- **Universal State Machines**: Declarative `:state-machine` nodes govern state transitions, particle emissions, and conditional triggers across scientific models, industrial machines, and interactive games identically.

### 4.2. Dynamic Parameter & Selector HUD (`setupSimParametersHud`)
- **Automatic Parameter Discovery**: The engine inspects `:inputs` and `:vars` arrays declared in any cartridge.
- **Auto-Generated Controls**: Generates sliders, step buttons, toggle switches, and discrete selectors dynamically:
  - If a variable has `:min`, `:max`, and `:step`, a range slider with real-time value readout is mounted.
  - If a variable represents discrete states or enumerations, a segmented button selector is created.
  - Interactive parts across complex slides (such as DNA base-pair unzipping and nucleotide inspection, kinetic gas piston valves, calculus derivative sliders, or electric circuit switches) are discovered and rendered automatically without writing custom component code.
- **Bidirectional Variable Binding**: User adjustments in the parameter HUD update reactive `:vars` instantly, triggering 60 FPS DOM attribute re-projections and formula evaluations.

### 4.3. Direct Canvas Manipulation (`ast-gestures.js`)
- **Sub-Pixel Coordinate Translation**: Applies inverse Current Transformation Matrix ($\mathbf{CTM}^{-1}$) to convert pointer coordinates into exact SVG stage coordinates regardless of CSS scaling, letterboxing, or display DPI.
- **PointerCapture Robustness**: Seamlessly captures high-speed drags across viewport boundaries, touchscreens, and mouse devices without dropping drag focus.
- **Constrained Axis Motion**: Supports 1D horizontal (`:axis "x"`), 1D vertical (`:axis "y"`), rotational (`:axis "angle"`), or unconstrained 2D planar movement.

### 4.4. Classroom Smartboard Whiteboard Layer
- **Native Ink Root (`#annotation-ink-root`)**: Renders high-fidelity drawing strokes directly inside the SVG document.
- **Quadratic Bézier Smoothing**: Interpolates raw pointer events using quadratic Bézier curves to eliminate jitter and produce smooth calligraphic handwriting from interactive styluses (Promethean, SMART, ViewSonic, iPad Pencil).
- **Teacher Toolbar**: Provides pen colors, highlighter transparency, stroke widths, eraser modes, and instant canvas clearing without altering underlying simulation elements.

### 4.5. Formative Assessment & Checkpoint Control Subsystem
- **Runtime Fisher-Yates Shuffling**: Every formative checkpoint dynamically randomizes answer choice order at runtime, decoupling correct answers from index 0/Option A while tracking the true answer key transparently.
- **Floating Question Pill**: Questions can be dismissed or minimized into a non-intrusive floating pill (`🎯 Show Question`) to prevent obscuring visual phenomena during demonstrations.
- **Presenter Mode Toggle (`Q`)**: Allows educators to disable mandatory pause checkpoints during lectures or re-engage formative gates during independent student study.

---

## 5. High-Performance AST Binary Bytecode (.astb)

To achieve instantaneous cold start times and ultra-low bandwidth consumption, the AST language compiles into an optimized binary bytecode format (`.astb`):

### 5.1. Binary Bytecode Opcode Specification
```
Magic Bytes:   0x41 0x53 0x54 0x42  ("ASTB")
Version:       0x01

Opcode Table:
0x01: OP_SCENE          (id, title, duration, loop)
0x02: OP_STAGE          (viewBox, background)
0x03: OP_VAR            (key, numeric value)
0x04: OP_INPUT          (key, label, min, max, step, default)
0x05: OP_COMPUTED       (key, formula expression)
0x10: OP_KEYFRAME       (time, properties)
0x20: OP_BIND           (target, attr, expr)
0x30: OP_CHECKPOINT     (time, question, options, answerIndex, explanation)
0x40: OP_CAMERA         (fov, near, far, initial position)
0x41: OP_3D_NODE        (id, geometry type, vertices, transforms)
0x50: OP_STATE_MACHINE  (id, initial state, states, transitions)
0x51: OP_EMITTER        (id, rate, lifespan, speed, spread)
0x60: OP_GESTURE        (target, axis, min, max)
```

### 5.2. Performance Benchmarks
- **Cold Boot Time**: < 15 ms from disk fetch to first interactive frame.
- **Memory Allocation**: Zero-allocation streaming reader decodes directly into typed arrays without garbage-collection pressure.
- **Payload Compression**: 99.8% size reduction compared to legacy PhET or Three.js bundles:

| Technology | Bundle Size | Cold Boot Time | RAM Usage | 24/7 Stability |
| :--- | :--- | :--- | :--- | :--- |
| **Legacy PhET Simulation** | 2,000 – 5,000 KB | 1,200 – 2,500 ms | 45 – 90 MB | Frequent GC crashes on ARM |
| **Adobe/Lottie Player** | 150 – 350 KB | 400 – 800 ms | 25 – 40 MB | High CPU usage on complex paths |
| **Three.js WebGL Engine** | 600 – 1,200 KB | 800 – 1,600 ms | 60 – 150 MB | GPU context loss on kiosks |
| **St Joseph's AST Engine** | **< 35 KB gzipped** | **< 15 ms** | **< 8 MB** | **Zero crashes (365 days continuous)** |

---

## 6. On-Device Edge AI & Gemini Nano (Chrome Prompt API)

The portal integrates on-device AI through the W3C Chrome Prompt API (`window.LanguageModel`) and local WebLLM:

### 6.1. Why the AST + On-Device AI Pairing is Structurally Unique
1. **The LLM Code Generation Dilemma**: Large and small language models frequently hallucinate or introduce syntax errors when asked to output 500–2,000 lines of imperative JavaScript, React components, or complex canvas physics logic.
2. **Declarative S-Expression Compactness**: AST S-Expressions represent complete, functioning, multi-modal simulations in just 1–4 KB of text (typically 200–600 tokens).
3. **GBNF Grammar Enforcement**: Decoding can be constrained at the logit level via GGML/GBNF grammars (`ast-sexpr.gbnf` and `ast-scene.gbnf`). This guarantees that 100% of generated tokens conform to valid AST language syntax, producing zero syntax errors.
4. **Sub-Second Generation Speed**: An on-device Small Language Model (SLM) such as Gemini Nano generates a complete interactive science lab or calculus curve in ~500 ms.
5. **Zero Cloud Egress**: Student inquiries, dialogue, and diagnostic hints execute locally on the user's NPU/GPU/CPU without network requests, satisfying GDPR, COPPA, and safeguarding mandates.

---

## 7. Universal Translator & Multilingual Subtitles/Audio

The portal features a built-in multilingual synthesis engine:
- **Languages Supported**: English (EN), Spanish (ES), French (FR), Latin (LA), German (DE), and Italian (IT).
- **Synchronized Subtitles**: Subtitle cues are indexed by timestamp in `scenes-config.json` and rendered with high-contrast typography.
- **Procedural Speech Synthesis**: Leverages the browser's native `SpeechSynthesis` API with automatic voice matching, rate optimization, and boundary event dispatching for the BSL signing interpreter.

---

## 8. British Sign Language (BSL) In-Vision Vector Interpreter

The player incorporates a world-first zero-video procedural 3D British Sign Language (BSL) "In-Vision" Vector Interpreter (`BslInterpreterOverlay.tsx` & `/lexicons/bsl-signs.ast`):
- **Full 68-Sign Primary Curriculum Corpus**: Unlike legacy digital tools that rely on pre-recorded video files (15–50 MB/min) or flat fingerspelling cards, the interpreter runs an extensive 68-sign procedural 3D lexicon covering primary Religious Education (`JESUS`, `PRAY`, `CHURCH`, `ALTAR`, `GOD`, `CROSS`, `BIBLE`, `PEACE`), STEM (`SCIENCE`, `MATHS`, `TIME`, `ENERGY`, `FORCE`, `GRAVITY`, `EARTH`, `SUN`, `MOON`, `PLANET`, `ORBIT`), and Classroom Core (`WHAT`, `WHERE`, `WHO`, `WHY`, `WHEN`, `HOW`, `START`, `STOP`, `HELLO`, `GOODBYE`, `THANK YOU`, `SORRY`, `HAPPY`, `SAD`, `MORE`, `AGAIN`, `CORRECT`, `WRONG`).
- **99.99% Compression Invariant**: The complete 68-sign lexicon is encoded as declarative AST S-Expressions in `static/lexicons/bsl-signs.ast`. Total payload size is **11.33 KB gzipped** (~170 bytes per sign) and parses in **< 8 ms** (< 0.4 ms/sign), eliminating the video bandwidth bottleneck for rural or low-bandwidth schools.
- **Procedural 3D Kinematics & Coordinate Tuples**: Hand trajectories and finger joint poses are codified using 3D coordinate tuples `(:xyz [x y z])` with continuous 60 FPS cubic Hermite spline interpolation.
- **Dual-Hand Coordinated Modes**:
  - `:vowel-board`: Non-dominant "Paper" hand acts as an anatomical reference palette while the dominant "Pen" pointer hand executes precision taps on the A-E-I-O-U fingertips.
  - `:mirror`: Bilateral symmetric joint articulation for signs like *CHURCH*, *FAMILY*, *PEACE*, or *COMMUNITY*.
  - `:base-shift`: Base hand forms a stationary spatial anchor (representing an altar, table, or book) while dominant hand executes arbitrary directional motion.
- **Grammatical Non-Manual Features (NMF) Facial Rig**: Synthesizes procedural facial expressions tied directly to linguistic interrogatives: raised eyebrows for polar yes/no questions, furrowed eyebrows for wh-questions, mouth morphemes, and head tilts without neural video hallucination.
- **Interactive 360° Drag-to-Orbit Camera**: Learners and teachers can freely click and drag to orbit the 3D camera 360°, zoom in on knuckles, or toggle between first-person Signer POV (looking down from chest) and conversational Receiver POV (facing partner across table).
- **Universal Site-Wide Integration (`bslGlobalStore`)**: BSL can be toggled anywhere across the portal via the persistent top header `UniversalTranslatorBar`, inside every embedded or full-screen `AstVectorMediaPlayer` toolbar, or using the global keyboard shortcut **`Shift + B`**. When active, the floating avatar automatically listens to speech boundary events (`SPEECH_BOUNDARY`) dispatched by any playing simulation cartridge.
- **281 Verified Invariant Tests**: The BSL engine and AST codec are validated against a 281-assertion invariant test suite (`npm run test:bsl`), guaranteeing round-trip serialization fidelity, bounds checking, and sub-15 KB bundle constraints.

---

## 9. PhET Simulation Ingestion & Transpiler Bridge

The portal includes an automated transpiler bridge (`ast-phet-bridge.js` & `src/utils/phetBridge.ts`):
- **Input Formats**: Ingests monolithic PhET HTML5 bundles (`.html`, `.json`), PhET-iO models, and legacy Macromedia/Adobe Flash SWF files.
- **AST Distillation**: Strips out megabytes of redundant Scenery/Kite/Dot wrapper code, distilling complex physical simulations down to clean < 4 KB AST S-Expressions (99.8% payload reduction).
- **Conservation Law Preservation**: Automatically identifies state variables and compiles them into reactive `:bindings` and `:state-machine` nodes, guaranteeing that physical conservation laws (momentum, mass, energy, charge) remain mathematically intact.

---

## 10. Complete Production Curriculum Cartridge Catalog (46 Cartridges)

### 10.1. Mathematics & Quantitative Reasoning
1. **Calculus: Tangent Slopes & Integrals (`calculus-curves`)**: GCSE/A-Level. Tangent slope $dy/dx$, stationary turning points, and Simpson's 1/3 numerical integrals with interactive curve selection.
2. **Algebra Balance Scale Lab (`algebra-balance`)**: KS2/KS3. Two-pan balance scale, algebraic equation balancing ($2x + 5 = 15$), and zero-pair cancelations.
3. **Pythagoras' Geometric Proof (`pythagoras`)**: KS3. Euclidean shear proof, dynamic square slicing, area conservation, and algebraic $a^2 + b^2 = c^2$ verification.
4. **BODMAS / BIDMAS Forcefield Clamping (`bodmas`)**: KS2/KS3. Visual operation precedence clamps, bracket forcefields, and step-by-step arithmetic evaluations.
5. **Fraction Wall & Slicing (`fractions`)**: KS2. Visual fraction wall, dynamic denominator slicing, equivalent fractions, and common denominator arithmetic.
6. **Times Tables 2D Multiplication Array (`times-tables`)**: KS1/KS2. 2× to 12× multiplication arrays, distributive property slicing, and commutative proofs.
7. **Maths Fishing: Number Bonds to 10/20 (`math-fishing`)**: KS1. Gamified number bond rods, hook physics, and complementary addition calculations.

### 10.2. Physics, Chemistry & Space Sciences
8. **Kinetic Gas Theory & Boyle's Law (`kinetic-gas`)**: KS3/KS4. Kinetic molecular theory, Boyle's Law ($PV = \text{constant}$), Gay-Lussac's Law, wall impulse pressure gauge, and phase changes.
9. **Electrical Circuits Lab & Ohm's Law (`electric-circuits`)**: KS3. Interactive knife switches, Ohm's law ($V = IR$), series/parallel branches, and live ammeter/voltmeter readouts.
10. **Bohr Atomic Structure & Electron Shells (`atom`)**: KS3. 2,8,8 orbital electron configurations, atomic number vs mass, and 3D shell inclination tilt.
11. **Kinematics: Velocity & Distance-Time Vectors (`velocity`)**: KS3. Distance-time and velocity-time graphs with synchronized vector sprites and acceleration vectors.
12. **Solar System 3D Heliocentric Orbits (`solar-system`)**: KS3. Heliocentric planetary orbits, Keplerian velocities, axial tilts, and 3D inclination angles.

### 10.3. Biology & Earth Sciences
13. **DNA Watson-Crick Double Helix & Transcription (`dna-helix`)**: KS3/KS4. Hydrogen-bonded base pairing (A-T, C-G) in 3D projected helical twist with interactive unzipping and transcription controls.
14. **Photosynthesis Solar Engine (`photosynthesis`)**: KS3. Chloroplast inner thylakoids, light-dependent reactions, Calvin cycle, and carbon dioxide absorption.
15. **Water Cycle Continuous Earth Engine (`water-cycle`)**: KS2. Evaporation, transpiration, condensation, precipitation, and percolation cycle.
16. **Mountain Elevation & Atmospheric Science (`mountain-elevation`)**: KS2/KS3. Altitude hypotenuse, clinometer elevation angles, and atmospheric boiling point shifts.
17. **Aquarium Living Ecosystem Stress Benchmark (`fish-tank`)**: All Stages. Vector stress benchmark, multi-species aquatic food web, nitrogen cycle, and water chemistry parameters.

### 10.4. Early Literacy, Phonics & English Language Arts
18. **Early Phonics Laboratory (`phonics-lab`)**: EYFS/KS1. Grapheme-phoneme sound buttons, blending mat, and procedural speech synthesis.
19. **Year 1 Phonics Screening Check (`phonics-screening`)**: EYFS/KS1. DfE official 40-word screening check simulator with alien pseudo-words, sound button dots & dashes, and diagnostics.
20. **Spelling Bee Championship Arena (`spelling-bee`)**: KS1/KS2/KS3. Interactive phonetic spelling arena, tiered national curriculum word lists, and sound-button synthesis.
21. **Shakespeare Globe Theatre 1599 Anatomy (`shakespeare`)**: KS3/KS4. 1599 Wooden O 3D stage geometry, Heaven/Hell/Earth trapdoors, and iambic pentameter metronomes.
22. **Macbeth: 5-Act Dramatic Soliloquy (`shakespeare-macbeth`)**: KS3/KS4. 5-Act interactive play-through on Bankside Globe stage, spoken blank verse audio, and canon vs what-if branches.

### 10.5. Languages, Polyglot & Accessibility
23. **MFL & Polyglot Languages Studio (`languages`)**: KS2/KS3. Spanish, French & Latin comparative phonics, conversational speech synthesis, and regular verb conjugation wheels.
24. **3D British Sign Language (BSL) Fingerspelling (`bsl-fingerspelling`)**: Inclusion. 360° rotatable 3D two-handed manual alphabet rig, A-E-I-O-U vowel tap positions, and Signer POV vs Receiver POV orbits.

### 10.6. Catholic Life, Liturgy & Sacraments
25. **Solemn Eucharistic Procession Film (`eucharistic-procession-film`)**: Liturgical film and vector HUD overlay, Blessed Sacrament canopy, thurible incensation streams, Tantum Ergo hymns, and humeral veil benediction.
26. **Sacred Altar Anatomy & Types (`altar-anatomy`)**: Consecrated Mensa, Altar Stone with Five Wounds, sealed martyrs' relics, 2/6/7 beeswax candle rules (GIRM 117), seasonal Antependium, Tabernacle, and Credence table.
27. **Sacred Church Tour & Architecture (`church-tour`)**: 3D Sanctuary, Tabernacle, High Altar, Lectern (Ambo), Baptismal Font, Stained Glass Windows, and Pedagogical X-Ray discovery exploration.
28. **The Stations of the Cross (Via Crucis) (`stations-of-the-cross`)**: The 14 sacred stations of the Via Dolorosa, Golgotha Calvary hill, Roman praetorium, Holy Sepulchre tomb, and Easter Resurrection.
29. **Holy Oils & Sacred Ambry (Olea Sancta) (`holy-oils`)**: Liturgical oils reservoir, Oleum Infirmorum (OI), Oleum Catechumenorum (OC), Sanctum Chrisma (SC), ambry cabinet, and sacramental anointing rites.
30. **Holy Water & The Thurible (Asperges & Incense) (`holy-water-thurifer`)**: Holy Water fonts, Aspergillum & Aspersorium, Thurible censing swings, charcoal boat, and sacramental purification rites.
31. **The Holy Rosary: 3D Beads & 20 Mysteries (`rosary-mysteries`)**: Contemplative 3D chaplet ring with Our Father and Hail Mary beads, depth-fog lighting, 4 scriptural mystery cycles (Joyful, Luminous, Sorrowful, Glorious), and Latin prayers.
32. **First Holy Communion & Eucharistic Adoration (`first-communion`)**: Catechetical preparation for First Holy Communion, Real Presence, Transubstantiation, and Eucharistic Adoration in the Monstrance.
33. **The Seven Holy Sacraments (`seven-sacraments`)**: Sacraments of Initiation (Baptism, Confirmation, Eucharist), Healing (Reconciliation, Anointing), and Service (Holy Orders, Matrimony).
34. **The Order of the Holy Mass (`order-of-the-mass`)**: Introductory Rites, Liturgy of the Word, Liturgy of the Eucharist, and Concluding Rites with Latin & English dialogs.
35. **The Sacred Paschal Triduum & Easter (`triduum-easter`)**: Holy Thursday Mass of the Lord's Supper, Good Friday Passion, Easter Vigil Lucernarium (Lumen Christi), and Easter Sunday Resurrection.
36. **The Catholic Liturgical Year & Seasons (`liturgical-calendar`)**: Seasonal cycle of Advent, Christmas, Lent, Triduum, Easter, and Ordinary Time with liturgical color symbolism.
37. **Sacred Postures & Gestures in Prayer (`liturgical-postures`)**: Genuflection, bowing, kneeling, standing, Sign of the Cross, and Orans posture with theological meanings.
38. **The Liturgy of the Hours (Divine Office) (`liturgy-of-the-hours`)**: Sanctification of daily time through Matins, Lauds, Terce, Sext, None, Vespers, and Compline.
39. **The Nicene & Apostles' Creed (`nicene-creed`)**: Systematic exploration of the Credo in Unum Deum, Trinitarian theology, Christology, and Four Marks of the Church.
40. **The Ten Commandments & Moral Law (`ten-commandments`)**: The Decalogue on the Two Tablets of Sinai, love of God and neighbor, and Catholic moral theology.
41. **Sacred Vessels, Linens & Vestments (`sacred-objects`)**: Chalice, Ciborium, Paten, Monstrance, Corporal, Purificator, Alb, Cincture, Stole, Chasuble, and Humeral Veil.
42. **Latin Prayers & Gregorian Chant (`latin-mass-prayers`)**: Pater Noster, Ave Maria, Gloria Patri, Salve Regina, and Gregorian neume notation.
43. **The 24 Catholic Rites & Churches (`catholic-rites`)**: Universal communion across Western Latin Rite and Eastern Catholic Rites (Byzantine, Alexandrian, Antiochene, Armenian, Chaldean).
44. **Catholic Social Teaching & Gospel Virtues (`cst-virtues`)**: Seven principles of CST (Human Dignity, Subsidiarity, Common Good, Option for the Poor, Solidarity) and theological/cardinal virtues.
45. **Sample Physics Knowledge Pipeline (`pipeline-sample`)**: Algorithmic physics pipeline and kinetic energy vector calculation testbed.
46. **Portal Welcome & Simulator Onboarding (`welcome`)**: Guided onboarding tour of the AST vector canvas, camera orbit controls, and smartboard stylus whiteboard tools.

---

## 11. Decoupled Headless Player Architecture & 4-Way Distribution

The AST Vector Player engine is 100% decoupled from the React host portal. It carries zero framework dependencies, runs in under 35 KB gzipped, and distributes across four universal models:

1. **Autonomous NPM Package (`@stjosephs/ast-vector-player`)**:
   - Ships with its own `package.json` (`static/player/package.json`).
   - Headless runtime: `import { AstEngine } from '@stjosephs/ast-vector-player'`.
   - Allows developers to drive custom UIs, Three.js canvases, or programmatic headless workers with complete AST keyframe, variable, and gesture execution.

2. **Native Web Component (`<micro-vector-player>`)**:
   - Packaged in `static/player/micro-vector-player.js` (< 25 KB uncompressed).
   - Zero-dependency Shadow DOM element that drops into any HTML page, WordPress, Webflow, or Shopify site:
     ```html
     <script src="micro-vector-player.js"></script>
     <micro-vector-player preset="kinetic-gas" autoplay voice lang="en"></micro-vector-player>
     ```

3. **Embeddable Responsive LMS Iframe**:
   - Embedded into Canvas, Moodle, Blackboard, Google Classroom, and web intranets via standard `<iframe>` (`/player/index.html?preset=...`).
   - Provides bidirectional `window.postMessage` telemetry protocol for gradebook reporting, remote teacher play/pause, speed control, and checkpoint scoring.

4. **Single-File Air-Gapped HTML Capsule (`exportAirgapHtmlBundle.ts`)**:
   - Compiles simulation, vector stage, procedural Web Audio, and assessment gates into a single `.html` file (< 45 KB).
   - Runs directly from `file://` or USB drives with zero internet connection, zero server, and zero dependencies.

---

## 12. Dual-Market Industrial Architecture: Digital Signage (DOOH) & Programmatic Advertising

While forged for rigorous educational simulations, `@stjosephs/ast-vector-player` is an industrial-grade, zero-bloat vector animation engine solving critical commercial pain points in advertising and digital display markets:

### 12.1. Programmatic Rich-Media & IAB Display Advertising
- **IAB 150 KB Size Cap Mastery**: Strict IAB (Interactive Advertising Bureau) and Google Display Network specs cap initial ad payloads at 150 KB gzipped. Standard animation engines (Lottie ~150 KB, GSAP, Three.js >600 KB) blow through budgets before graphics are loaded. The entire AST runtime is **< 35 KB gzipped**, allowing an entire interactive 3D/physics ad banner to load in **under 45 KB total**.
- **Dynamic Creative Optimization (DCO)**: Ad networks can personalize copy, local store addresses, live countdown clocks, or weather-triggered product variants in real-time by updating reactive `:vars` over `postMessage` or URL params with a 30-byte JSON message, without needing server-side video re-rendering.
- **High Viewability & Zero CPU Throttling**: Operates on native hardware-accelerated SVG DOM transforms, consuming <1% CPU and dropping to 0% when scrolled off-screen, preventing browser tab battery drain.

### 12.2. Digital Out-of-Home (DOOH) & Commercial Digital Signage
- **Extreme Tolerance for Low-Spec Hardware**: Fast-food digital menu boards, airport transit displays, supermarket shelf-edge screens, and bus-stop displays run on cheap quad-core ARM chips (Raspberry Pi CM4, Rockchip, Android 11 sticks, LG webOS, Samsung Tizen) with 1–2 GB RAM. Standard Chromium kiosk loops crash every 48–72 hours from memory leaks. AST runs with **< 8 MB RAM and 0 GC thrashing**, operating continuously for 365 days without crashing or thermal throttling.
- **Infinite DPI Resolution Independence**: Pure mathematical vector projection scales identically from a 2-inch electronic shelf label to a 100-foot 8K Times Square LED billboard with **zero pixelation** and **zero bandwidth cost**.
- **Interactive Retail Kiosks & Wayfinding**: Sub-pixel `PointerCapture` dragging (`ast-gestures.js`) and quadratic Bézier smoothing provide instant, lag-free touch and stylus interaction for mall directories and retail product configurators.
- **Procedural 0 KB Audio Feedback**: Native Web Audio API synthesizes UI feedback, chimes, and scanner clicks without downloading external audio files.
- **Air-Gapped Reliability**: Displays function continuously offline with zero remote CDN dependencies.

### 12.3. Dual-Track Licensing Strategy (Track A vs Track B)
- **Track A (Humanitarian Commons - AGPLv3)**: State schools, educational charities, and pupils enjoy free, perpetual access with copyleft reciprocity.
- **Track B (Enterprise Commercial License)**: Commercial DOOH operators, ad-tech platforms, and kiosk OEMs license closed-source proprietary distribution rights, with 100% of license revenues directly funding free hardware and solar-powered devices for disadvantaged schools.

---

## 13. W3C WebMCP (Web Model Context Protocol) Native Agent Tool Registry

In accordance with the emerging W3C Web Machine Learning Community Group standard incubated by Google Chrome and Microsoft (`github.com/webmachinelearning/webmcp-types`), St Joseph's Curriculum Portal registers client-side tool schemas directly on `document.modelContext.registerTool(...)`:

### Available In-Browser WebMCP Tools:
1. `catholic_catechism_search` (Read-Only): Query Roman Rite liturgical definitions, Holy Water (Aqua Benedicta) and Asperges, Thurifer (Thuriferarius) & Incensations, High Altar mensa and relics, Holy Oils, and Sanctuary pilgrim stations.
2. `navigate_portal` (Consequential): Seamless client-side viewport navigation (`/catholic-life`, `/practice-lab`, `/cartridges`, `/curriculum`, `/jotter`) and tab selection via React Router.
3. `launch_simulation` (Consequential): Programmatically open and render any interactive AST vector cartridge or synchronized educational film on the stage with autoPlay.
4. `list_ast_simulations` (Read-Only): Enumerate all vector cartridges across the four archetypes (`Sim`, `Slide`, `App`, `Film`) with learning invariants, subjects, video backdrops, and runtimes.
5. `get_learner_status` (Read-Only): Anonymously inspect local on-device pupil mastery (stars earned, active key stage) strictly without cloud egress.

---

## 14. Decentralized Virtual Console & Self-Mounting Cartridge Architecture

The portal is designed around a radical, zero-bloat inversion of traditional database-driven web architecture:
1. **Zero Central Data Storage**: The site holds 0 student or user data on servers. The portal acts as an air-gapped, stateless execution console (`#ast-persistent-viewport`).
2. **Autonomous Self-Mounting Cartridges**: Each curriculum cartridge (`.ast` and `.svg`) declares where it lives and what slots it occupies via metadata tags:
   - `:mount "/curriculum/..."` - Canonical route where the cartridge mounts itself in the site viewport.
   - `:section "Maths" | "Science" | "English" | "Faith"` - Curriculum category for automatic directory aggregation.
   - `:tier "core" | "extended"` - Core curriculum cartridges are protected, foundational ROMs; extended cartridges provide specialized labs.
3. **Dynamic Site Synthesis**: Rather than hardcoded pages, the portal dynamically queries `SceneRegistry.list()` and `getAllCartridges()` to construct routes, navigation grids, and interactive stages.
4. **Offline Air-Gap Portability**: Cartridges are 2.5 KB to 25 KB living vector files that can be copied to a USB drive or saved in client-side IndexedDB, running completely offline with sub-15 ms cold starts and zero cloud dependencies.

---

## 15. S-Expression Grammar & Generation Guide for AI Models

When generating AST cartridges, models must adhere strictly to the following syntax rules:

```lisp
(:scene
  :id "scene-identifier"
  :title "Human Readable Title"
  :type "Sim" ; Archetypes: "Sim", "Slide", "App", "Film"
  :mount "/curriculum/subject/topic"
  :section "Science"
  :tier "core"
  :duration 60
  :loop true
  :stage (:viewBox "0 0 800 480" :background "#0f172a")
  
  :vars (
    (:key "temperature" :default 300 :min 100 :max 800 :step 10 :label "Temperature (K)")
    (:key "pressure" :default 1.0 :min 0.2 :max 5.0 :step 0.1 :label "Pressure (atm)")
  )

  :inputs (
    (:key "temperature" :type "slider" :min 100 :max 800 :step 10 :label "Heat")
    (:key "phase" :type "select" :options ["Solid" "Liquid" "Gas"] :default "Gas")
  )

  :computed (
    (:key "volume" :expr "(8.314 * temperature) / (pressure * 100)")
  )

  :bindings (
    (:target "#piston-head" :attr "cy" :expr "400 - (volume * 1.5)")
    (:target "#temp-readout" :attr "text" :expr "temperature + ' K'")
  )

  :gestures (
    (:draggable "#piston-handle" :axis "y" :min 120 :max 380 :bindVar "pressure")
  )

  :keyframes (
    (:time 0 :action "init" :subtitle "System initialized to standard temperature and pressure.")
    (:time 15 :action "heat" :subtitle "Thermal energy increases particle collision velocity.")
  )

  :interactive (
    (:checkpoint
      :time 30
      :prompt "What happens to gas pressure when volume is halved at constant temperature?"
      :options ["Pressure doubles" "Pressure is halved" "Pressure stays constant" "Pressure drops to zero"]
      :answer 0
      :explanation "According to Boyle's Law (P1V1 = P2V2), pressure is inversely proportional to volume."
    )
  )
)
```

- **Output Validation**: Always validate output against `/player/grammar/ast-sexpr.gbnf`.
- **Coordinate System**: Always target `<svg viewBox="0 0 800 480">`.
- **Pure Vector Declarations**: Never embed raster images (PNG/JPEG) or external CSS stylesheets; all styling is declared directly on vector nodes or reactive bindings.