15. Frontend: The Altar

Requirements

• Server-Side Verification: Mandatory logic unification; all validation, state management, and routing must reside on the server to prevent architectural bifurcation.
• Hypermedia-Driven Scrying: Adoption of the HATEOAS pattern, where the server returns HTML fragments representing distilled outcomes rather than raw data.
• Generative UI Protocol: Capability to dynamically render interactive components (forms, diff-views, checklists) based on the schema of an Agent's tool call, allowing the interface to evolve with the machine's capabilities.
• Predictive State Streaming: Support for Server-Sent Events (SSE) to animate the machine’s internal states and "Predictive" drafts in real-time, sharing state between the Python kernel and the DOM.
• Extension Template Discovery: Provision of a formal mechanism for Extensions to register Jinja2 templates and visual components that are automatically assimilated into the interface at boot time.
• Island Architecture: Support for optional "Islands of Interactivity" (Alpine.js) to allow specialized, high-fidelity tools to be mounted as non-critical extension components.
• Hermetic Asset Strategy: Prioritization of local, self-contained asset compilation (Vite) to ensure the interface remains functional in air-gapped or isolated environments.

Considered Options

Decision Outcome

The Altar is implemented as a Server-Rendered Hypermedia interface. Its primary role is observation and the Rite of Consecration, with control surfaces expressed through typed ritual forms rather than a generic cockpit model.

1. The Scrying Stack

The Altar utilizes a "Thin Client" stack designed for maximum substrate integration:

• HTMX: The primary engine for state transitions. It swaps HTML fragments into the DOM, allowing the Magus to "zoom" into specific cognitive processes without a page reload.
• Alpine.js: Used for ephemeral, local UI state (e.g., toggling a sidebar) and managing "Islands of Interactivity."
• Jinja2: The templating engine that renders fragments, utilizing the directory structure defined in the Layout (13).
• Vite: The supported asset pipeline and dev/build contract for the Altar. Package manager or runtime substitutions are acceptable only when they preserve Vite compatibility and the Litestar integration surface.
• Tailwind CSS: A utility-first styling engine. The final CSS is synthesized by scanning the templates of both the Core and all active Extensions.

2. Generative UI Patterns (The AG-UI Protocol)

The Altar adopts the Agentic Generative UI (AG-UI) philosophy but implements it via Server-Side Rendering (HTMX) to maintain substrate purity.

• Dynamic Component Rendering: When an Agent utilizes a tool (e.g., create_plan), the Vessel does not return raw JSON state to a client-side framework. Instead, it renders a specialized Jinja2 fragment (e.g., <div id="plan">...</div>) that is swapped directly into the chat stream via HTMX.
• Predictive State: The Altar subscribes to the Agent's thought stream via Server-Sent Events (SSE). If the Agent is "drafting" a document, the UI updates a live preview window in real-time, utilizing shared state between the Python kernel and the DOM.
• Tool-Based Interaction: Approvals use dynamically generated forms based on the Pydantic schema of the pending tool call, allowing precise parameter editing before execution.

3. The Ritual of Consent

The Altar is the primary coordinate for high-level deliberation.

• Visions: The backend does not present raw log streams. Instead, it sends HTML fragments containing Agent-distilled summaries of speculative processes.
• Consecration: The Magus interacts with "Decision Fragments"—simple, server-validated forms that trigger the system's internal reflex arcs, merging speculative logic into the primary reality.

4. The Extension Lens & Islands

To maintain the Federation (05), the Altar functions as a discovery engine:

• Discovery: During the registration hook, extensions provide the coordinates for their visual templates.
• Grafting: The Vessel scans these directories, allowing extensions to inject new scrying fragments into the Altar's layout without core modifications.
• Islands: If an extension requires complex client-side logic (e.g., a real-time data visualization or an interactive node-map), it may mount an "Island"—a small, isolated JavaScript bundle—into an HTMX-driven page. TypeScript is optional and encouraged for these richer islands, but it is not required for the baseline HTMX/Alpine surface.

5. The Scales of the Whims

The Altar provides a real-time scrying view of the Orchestrator’s Intent Queues.

• The Scales: Visualization of current "Inertia" weights and "Whim" multipliers. This allows the Magus to see exactly why the Orchestrator is maintaining a specific Coven or why a swap is pending.
• Queue Scrying: A live stream of the Ghoul (14) labor force, showing which tasks are active, which are in "Stasis," and which are awaiting a hardware transition.
• Manual Flip: A privileged interface component to manually trigger a Coven Swap, providing the Override required to break logical loops or prioritize specific work.

Consequences