Reference Workload: 3D Tarot & Gemini Live Multimodal Guidance

Experimental source tour

The package passes its current TypeScript and test suites. It remains a showcase because browser 3D rendering and a real Gemini Live connection are outside the unit-test boundary.

The Tarot 3D & Gemini Live reference workload demonstrates pure spatial scene projection, deterministic seeded domain logic, and typed multi-channel delivery across 3D WebGL interfaces and real-time voice channels.

                  Durable Session Snapshot
         { spread: "celtic_cross", deckSeed: "abc", drawnCards: [...] }
                                  │
               ┌──────────────────┴──────────────────┐
               ▼                                     ▼
     tarot3dProjector                      tarotVoiceProjector
• Card 3D coords (x, y, z)            • Mystic guide persona prompt
• Rotations (rx, ry, rz)              • Spoken narrative guidance
• Face-up / glow aura                 • Typed runtime actions:
• Altar ambience & camera target        - submit_input (reveal)
                                        - start_spread
               │                                     │
               ▼                                     ▼
      3D Web Table View                    Gemini Live Voice Audio
      (CSS3D / WebGL)                     (via @invariant/live-gemini)

---

Architectural Thesis: Presentation Truth is Derived

1. Separation of Execution Truth vs. Presentation Truth

Durable session state contains only business and inquiry facts:

• Selected spread layout (past_present_future, celtic_cross, love, daily, yes_no)
• Explicit deck seed for reproducible draws
• Drawn cards, upright/reversed posture, and reveal sequence
• Archetype reflections and seeker Q&A

Presentation properties (x/y/z, camera angles, glowing particle density) are 100% derived by Tarot3DSceneProjection:

export interface Card3DState {
  id: string;
  name: string;
  arcana: string;
  element: string;
  slotName: string;
  positionIndex: number;
  position: { x: number; y: number; z: number };
  rotation: { x: number; y: number; z: number };
  faceUp: boolean;
  isReversed: boolean;
  glowColor: string;
  isHighlighted: boolean;
}

The Invariant Law of Projection: "Presentation state remains derived. Presentation does not become execution truth."

2. Pure Deterministic Domain Logic with Explicit Seeds

Card shuffling and reversals use a seeded 32-bit PRNG (Mulberry32). By passing an explicit deckSeed, readings are 100% reproducible and replayable:

$$\text{Same Deck} + \text{Same Seed} \implies \text{Identical Shuffle & Card Draw}$$

const drawn1 = drawSpreadCards('past_present_future', 'reading_abc123');
const drawn2 = drawSpreadCards('past_present_future', 'reading_abc123');
// drawn1 is deeply equal to drawn2

3. Bounded Gemini Live Tools with Generic Typing

Voice tools exposed to Gemini Live directly reflect canonical runtime wait boundaries (wait-reveal-${index} $\to$ submit_input({ action: 'reveal' })).

Tool execution responses return typed 3D scene projections without type erasure:

const response = liveAdapter.formatToolResultResponse<Tarot3DSceneProjection>(
  'accepted',
  tarot3dProjector.project(session.snapshot())
);

// Types are preserved end-to-end:
response.next?.camera.fov; // number
response.next?.cards;      // Card3DState[]

---

Available Tarot Spreads

Spread	Cards	Metaphysical Focus
Past / Present / Future	3	Roots, current active energies, and emerging horizon
Celtic Cross	10	Complete inquiry architecture (Cross, Root, Crown, Environment, Outcome)
Love & Dynamics	4	Seeker truth, partner perspective, dynamic alchemy, higher guidance
Daily Meditation	1	Single-card archetype pull and mindful daily affirmation
Yes / No Oracle	1	Elemental polarity and upright/reversed balance determination

---

Running the Example

# Start the Fastify server with 3D Web UI on port 8082
pnpm --filter example-tarot-live-3d start

# Open in browser
open http://localhost:8082

# Run unit, projection determinism, and typed live tests
pnpm --filter example-tarot-live-3d test

---

Next Steps

• Projections & Derived Views — Learn how spatial 3D and voice projections derive pure representations from state.
• Boulevard Booking Example — Explore enterprise multi-channel workflows across voice, SMS, and SSE.
• Examples Hub — View the complete catalog of showcases.