Folio Docs

Class Reference

This is a practical map of the main JavaScript classes in Folio: what each class owns, what it should not own, and how the pieces cooperate at runtime.

Top-Level Wiring

Class / module Path Responsibility
index.html bootstrap folio/folio-web/index.html Creates the store, bus, parser, policy, registry, bridge, editor, and canvas; registers renderers; owns top-level menu and document loading logic.
DocumentStore folio/folio-web/src/core/DocumentStore.js Persistent multi-document text store with stable ids, history, snapshots, and mutation application.
SyncBus folio/folio-web/src/core/SyncBus.js Validates mutation events, applies them to the store, then notifies subscribers.
DirectiveParser folio/folio-web/src/core/DirectiveParser.js Parses plain text into directive descriptors. This is the structural read layer for the entire runtime.

Security And Capability Layer

Class Path Responsibility
DocumentSecurityPolicy folio/folio-web/src/core/DocumentSecurityPolicy.js Stores per-document trust state and explicit grants in local storage. Changing the current document swaps the active security state.
CapabilityRegistry folio/folio-web/src/core/CapabilityRegistry.js Registers renderer classes, instantiates them, normalizes manifests, and authorizes render/query operations based on trust domain and grants.
Important boundary: registry lookup alone is not authorization. Mirrored renderers and mirrored Python namespaces are supposed to pass through capability checks first.

Python Runtime Layer

Class Path Responsibility
NamespaceBridge folio/folio-web/src/python/NamespaceBridge.js Builds document-scoped globals from current text, computes mirrored namespace permissions, orchestrates evaluation, and caches per-block results.
PyodideWorker folio/folio-web/src/python/PyodideWorker.js Owns the isolated Python execution environment. Rebuilds a fresh shared namespace per evaluation and executes blocks in document order.
PyRenderer folio/folio-web/src/renderers/mock/PyRenderer.js UI wrapper for ::py blocks. Displays code, stdout, denied-capability controls, and manual run actions.

Simulation Layer

Class Path Responsibility
SimulationProfileStore folio/folio-web/src/simulation/SimulationProfileStore.js Persists authored simulation profiles in local storage: user identity, contacts, projects, channels, and organization context.
SimulationScenarioStore folio/folio-web/src/simulation/SimulationScenarioStore.js Persists generated scenario state, a richer generation ledger with surface and prompt/input summaries, and the last generated mirrored-backend snapshot per profile so simulated worlds can be inspected and restored independently of live backend memory.
SimulationSettingsStore folio/folio-web/src/simulation/SimulationSettingsStore.js Persists non-secret remote generation settings such as the OpenAI-compatible endpoint and model configuration.
SimulationSecretsStore folio/folio-web/src/simulation/SimulationSecretsStore.js Persists provider secrets separately from profiles and ordinary settings, such as the API key for a remote simulation provider.
SimulationPromptBuilder folio/folio-web/src/simulation/SimulationPromptBuilder.js Builds structured prompt objects from the current profile, scenario seed, and generation intent. It now covers day, inbox, chat, calendar, and day-plan surfaces as the handoff boundary for real LLM calls.
SimulationDocumentPromptBuilder folio/folio-web/src/simulation/SimulationDocumentPromptBuilder.js Builds structured prompts for full Folio document generation. It packages the profile, scenario summary, current date, and seed document example so the remote model can return a document spec instead of raw directive text.
SimulationNormalizer folio/folio-web/src/simulation/SimulationNormalizer.js Validates and normalizes generated output into backend-native email, chat, calendar, and scenario shapes.
SimulationDocumentNormalizer folio/folio-web/src/simulation/SimulationDocumentNormalizer.js Normalizes document-generation output into a stable document spec and compiles that spec into valid Folio text with owned-state and mirrored-state directives.
SimulationLLMClient folio/folio-web/src/simulation/SimulationLLMClient.js Abstraction for simulation generation providers. Concrete clients implement availability checks, metadata, status subscriptions, and generate(prompt).
OpenAICompatibleSimulationLLMClient folio/folio-web/src/simulation/OpenAICompatibleSimulationLLMClient.js Concrete remote provider client that calls an OpenAI-compatible chat-completions endpoint with a separately stored API key and returns structured JSON for the simulation pipeline.
SimulationCoordinator folio/folio-web/src/simulation/SimulationCoordinator.js Integration point for the simulation layer. Orchestrates profile/scenario lookup, prompt building, remote generation, normalization, backend application, timeline advancement, full document generation, snapshot persistence, and richer ledger recording via setLLMClient() and getClientStatus().

Shell Layer

Class Path Responsibility
RenderCanvas folio/folio-web/src/shell/RenderCanvas.js Primary reading and interaction surface. Segments prose vs directives, mounts text fallbacks, lazily activates widgets, supports global text mode, and preserves exact prose/fallback text on edits.
DocumentEditor folio/folio-web/src/shell/DocumentEditor.js Hidden textarea-based editor wrapper used for full-text editing and synchronization. It is currently a lightweight placeholder for a richer editor.

Transclusion And Lifecycle

Class Path Responsibility
TransclusionResolver folio/folio-web/src/core/TransclusionResolver.js Resolves ::note sources, supports cross-document references, detects cycles, and builds writeback patches into the source block.
MetaRenderer folio/folio-web/src/renderers/MetaRenderer.js UI for document lifecycle status. Mutates the underlying ::meta[status] line in text.
SpawnRenderer folio/folio-web/src/renderers/SpawnRenderer.js Creates next documents and roll-up documents, compacts completed tasks, and carries open tasks forward by reference.

Directive Renderer Base

Class Path Responsibility
RendererBase folio/folio-web/src/renderers/RendererBase.js Common widget shell helpers used by concrete renderers. Concrete subclasses provide manifest, render(), and optionally query().

Owned-State Renderers

Renderer Path Responsibility
TaskRenderer folio/folio-web/src/renderers/TaskRenderer.js Checkbox UI for text-native tasks. Rewrites the directive line on toggle and resolves simple blocked-by dependencies.
TableRenderer folio/folio-web/src/renderers/TableRenderer.js Editable table widget with derived-source linking to Python blocks, divergence tracking, re-sync, and detach behavior.
NoteRenderer folio/folio-web/src/renderers/NoteRenderer.js Transclusion UI for ::note, including writeback to local or cross-document source blocks and freeze-to-literal behavior.
ContactRenderer folio/folio-web/src/renderers/ContactRenderer.js Structured contact block editor with action logging.
FileRenderer folio/folio-web/src/renderers/FileRenderer.js Reference card for local files and simple preview hints.

Mirrored-State Renderers

Renderer Path Responsibility
CalRenderer folio/folio-web/src/renderers/CalRenderer.js Renders projected calendar state from the mock backend and journals RSVP actions into text.
EmailRenderer folio/folio-web/src/renderers/EmailRenderer.js Inbox, thread, and draft UIs over the mock mail backend. The document owns local logs and draft text, not canonical messages.
ChatRenderer folio/folio-web/src/renderers/ChatRenderer.js Projected chat slice with send and promote actions. Backend messages remain canonical.
WebRenderer folio/folio-web/src/renderers/WebRenderer.js URL reference plus local annotations. Treated as mirrored read state with user-owned notes.

Mock Backends

Module Path Responsibility
MockCalBackend folio/folio-web/src/backends/MockCalBackend.js In-memory event source and RSVP mutation surface for calendar widgets, now with import/export/reset support for simulation seeding.
MockEmailBackend folio/folio-web/src/backends/MockEmailBackend.js In-memory inbox, threads, send, and file actions used by email widgets, now with import/export/reset support for simulation seeding.
MockChatBackend folio/folio-web/src/backends/MockChatBackend.js In-memory chat history and post actions used by chat widgets, now with import/export/reset support for simulation seeding.

Design Boundaries