RFC-0023 · Gnomon Studio — In-Browser Authoring Environment
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.
1. Scope
This RFC defines Gnomon Studio: a browser-based IDE for authoring .gnm modules. Studio is a domain-specific authoring environment, not a general-purpose code editor.
This RFC covers:
- What Studio is and explicitly is not
- The relationship between Studio and the Gnomon language server (RFC-0017)
- Panel layout contract: the normative UI panels and their responsibilities
- The semantic preview panel: domain summary rendering powered by RFC-0018 compiler services
- Module publish flow from within Studio
- Registry integration: browsing dependencies via RFC-0019
- Security constraints: Studio’s execution boundary
This RFC does not cover:
- The language server protocol implementation — that is defined in RFC-0017
- Compiler services internals — those are defined in RFC-0018
- Registry protocol details — those are defined in RFC-0019
- Mobile or native desktop Studio builds (Studio is browser-only in this RFC; native packaging is deferred)
- Multi-user collaborative editing (deferred; Studio in this RFC is single-user per session)
- Studio hosting, deployment topology, or SaaS distribution model
2. Goals
- Studio MUST provide an authoring experience functionally equivalent to VS Code with the Gnomon extension, powered by the same language server, so that authors are not penalized for using the browser over a local editor.
- Studio MUST NOT execute
.gnmsource code. It is a read-and-analyze tool: it may compile, type-check, and render semantic previews, but it MUST NOT invoke agent bindings or apply install plans. - The semantic preview panel MUST update reactively as the author types, within a latency budget of 2 seconds from keystroke to updated preview in normal conditions.
- Studio MUST work in two modes: embedded WASM language server (fully offline-capable) and remote LSP over WebSocket (for power users who want full system resources).
- The publish flow in Studio MUST be identical in outcome to running
gnomon publishfrom the CLI; Studio MUST NOT bypass the semver lint gate (RFC-0019 §4.1). - Studio MUST be implementable as a static single-page application with no server-side rendering requirement. All computation occurs in the browser or via the connected language server.
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.
3. What Studio Is and Is Not
3.1 Studio IS
- A browser-based IDE for authoring
.gnmsource files - A semantic preview surface that renders entity, flow, and facet declarations as human-readable domain summaries
- A module browser for exploring imported dependencies from a configured registry
- A publish surface that runs
gnomon publishvia subprocess or remote API
3.2 Studio IS NOT
- A general-purpose code editor (no support for
.ts,.py,.go, or other languages) - A runtime or execution environment; it MUST NOT invoke agent bindings or apply install plans
- A replacement for the CLI; Studio is a UI layer over the same compiler and registry toolchain
- A collaboration platform; multi-user real-time editing is out of scope for this RFC
- A debugger; runtime debugging is an implementation concern outside this specification
4. Language Server Integration
Studio integrates with the Gnomon language server (RFC-0017) in one of two modes.
4.1 Embedded WASM Mode
The Gnomon compiler and language server are compiled to WebAssembly and bundled with the Studio application. The WASM module runs in a Web Worker (off the main thread) to avoid blocking the editor UI.
In this mode:
- No network connectivity is required for language features (completions, diagnostics, hover).
- The WASM module is initialized with the module source files loaded from the browser’s in-memory file system.
- The module resolve step for dependencies reads from a local cache (IndexedDB) seeded by prior registry fetches.
- Compiler service calls (RFC-0018 CompilerSession) are dispatched via a
postMessagebridge to the Web Worker.
4.2 Remote LSP Mode (WebSocket)
Studio connects to a locally running gnomon lsp process via a WebSocket transport. This mode is recommended when:
- The project uses a large dependency graph that strains WASM memory limits.
- The author wants full incremental compilation performance.
- The project is stored on the local filesystem and Studio is launched from a local server.
In remote mode:
- Studio acts as an LSP client over WebSocket; the
gnomon lspprocess acts as the server. - RFC-0017’s full protocol surface is available.
- The semantic preview panel still renders in the browser; it receives structured JSON from the language server rather than running the compiler locally.
4.3 Mode Selection
Mode is determined by Studio’s startup configuration:
{
"lsp": {
"mode": "wasm", // or "websocket"
"websocket": {
"url": "ws://localhost:5007"
}
}
}
If mode is not specified, Studio defaults to wasm. If the WebSocket connection fails or is not configured, Studio MUST fall back to wasm and display a status indicator. It MUST NOT silently degrade without notifying the author.
5. Panel Layout Contract
Studio’s panel layout is normative. Implementations MUST provide the following panels. Layout (left/right/bottom split ratios) is implementation-defined, but all panels MUST be present and reachable.
5.1 File Tree Panel
- Displays the module’s file tree rooted at
module.gnm. - Only
.gnmfiles andmodule.gnmare shown. Other file types are not displayed (Studio is not a general file browser). - Clicking a file opens it in the editor panel.
- Context menu MUST support: new file, rename file, delete file. These operations MUST be reflected in the language server’s incremental model (RFC-0018 §5).
5.2 Editor Panel
- A code editor with full Gnomon language support: syntax highlighting, completions, hover documentation, inline diagnostics, and go-to-definition.
- All language features are backed by the language server (RFC-0017) in whichever mode is active.
- The editor MUST display diagnostic codes (e.g.,
M01402,M08770) inline, with hover detail including the diagnostic message and a link to the relevant RFC section where defined. - The editor MUST NOT allow arbitrary script execution (see §7).
5.3 Semantic Preview Panel
The semantic preview panel renders entity, flow, and facet declarations as human-readable domain summaries. It is powered by the RFC-0018 CompilerSession.
Behavior:
- The panel is keyed to the current cursor position in the editor. It shows the semantic summary of the declaration at or enclosing the cursor.
- For an
entitydeclaration: renders field names, types, and any inferred or declared documentation, plus applicable facets. - For a
flowdeclaration: renders the state machine as a diagram (states, transitions, guards). - For a
facetdeclaration: renders the contributed fields and rules. - For an
agentdeclaration: renders the capability contract (protocols, inputs, outputs, permissions) in a readable format. - The panel updates within the latency budget specified in §2.3.
The semantic preview MUST NOT render synthetic data or execute any rules. It is a structural display of the compiled declaration, not a live runtime preview.
5.4 Problems Panel
Lists all active diagnostics across all open files, mirroring the RFC-0017 textDocument/publishDiagnostics output. Diagnostics are grouped by file. Clicking a diagnostic navigates the editor to the relevant source location.
6. Module Publish Flow
Studio provides a publish panel that wraps the gnomon publish workflow (RFC-0019 §4).
6.1 Publish Panel
The publish panel displays:
- Current module ID and version from
module.gnm - Pre-publish validation status (semver lint result, lockfile freshness)
- Configured registry URL
- A “Publish” button
6.2 Publish Execution
When the author clicks “Publish”:
- Studio runs the equivalent of
gnomon publishagainst the active module. - The semver lint gate (RFC-0019 §4.1) MUST run. If it blocks, the publish panel displays the blocking lint codes and does not proceed.
- If lint passes, Studio uploads the bundle to the configured registry.
- The publish panel displays the outcome (success, error with diagnostic codes).
Studio MUST NOT provide a “skip lint” toggle in the publish UI. That option is CLI-only and intentionally not surfaced in Studio to reduce the risk of accidental semver gate bypass.
6.3 Credential Handling
Registry credentials are not stored in Studio’s browser state. Studio either:
- Reads credentials from the connected
gnomon lspprocess (which has access to the platform credential store), or - Prompts the author for an
GNOMON_REGISTRY_TOKENvalue for the session (in-memory only, never persisted to localStorage or IndexedDB).
7. Security Constraints
Security is a hard constraint for Studio, not a best-effort concern.
7.1 No Source Code Execution
Studio MUST NOT execute .gnm source code in the browser. Specifically:
- Studio MUST NOT invoke any agent
bindingdeclarations. - Studio MUST NOT apply install plans.
- Studio MUST NOT invoke
actiondeclarations against live data. - The compiler WASM module may evaluate rule expressions for type-checking and semantic preview purposes, but only within the compiler’s sandboxed evaluation context. This is analysis, not execution.
If a future Studio feature requires live data interaction, it MUST be defined in a separate RFC with explicit security review.
7.2 Content Security Policy
Studio’s HTML shell MUST be served with a strict Content Security Policy (CSP) that:
- Prohibits inline scripts (
script-src 'self'). - Prohibits
evalandnew Function. - Restricts
connect-srcto the configured registry URL and LSP WebSocket URL only.
The WASM module is loaded via script-src 'wasm-unsafe-eval' (required by browsers for WASM instantiation). This is the only relaxation permitted.
7.3 Credential Isolation
Session credentials (§6.3) MUST be held in JS heap memory only. They MUST NOT be written to localStorage, sessionStorage, IndexedDB, cookies, or any persistent storage mechanism. They are cleared when the Studio tab is closed.
7.4 File System Access
In WASM mode, Studio uses an in-memory virtual file system scoped to the active module. It MUST NOT request broad filesystem access (e.g., via the File System Access API) beyond the module root. If the File System Access API is used to mount a local directory, the mount MUST be scoped to the directory the author selects and MUST NOT traverse parent directories.
8. Failure Modes
| Scenario | Outcome | Diagnostic |
|---|---|---|
| WebSocket LSP connection fails at startup | Studio falls back to WASM mode, shows status banner | — (status indicator, not a code) |
| WASM module fails to initialize | Studio shows error state; editing is unavailable | M23300 |
| Semantic preview times out (>2s on a responsive system) | Panel shows “Updating…” placeholder | M23301 (warning) |
| Publish: semver lint gate blocks | Publish aborted, lint codes displayed in panel | L01401 (RFC-0014) |
| Publish: registry unreachable | Publish aborted, error displayed | M01911 (RFC-0019) |
| Session credential cleared after tab close | Author must re-enter token on next session | — (expected behavior) |
| Author attempts to open a non-.gnm file | File tree ignores it; no error | — |
| LSP returns diagnostic for unknown code | Problems panel displays code with “unknown diagnostic” tooltip | M23302 (warning) |
9. Invariants
- No execution. Studio MUST NOT execute
.gnmdeclarations against live state. Analysis (compilation, type inference, semantic preview) is permitted; execution is not. - LSP parity. All language features in Studio (completions, diagnostics, hover, go-to-definition) MUST be backed by the same RFC-0017 protocol surface as the VS Code extension. Studio MUST NOT implement language features independently.
- Publish gate parity. The Studio publish flow MUST produce the same outcome as
gnomon publishfor the same module and credentials. Studio MUST NOT bypass any gate that the CLI enforces. - Credential non-persistence. Session credentials MUST NOT be written to persistent storage. Loss of credentials on tab close is expected and correct behavior.
- Panel completeness. A Studio build that omits any normative panel (file tree, editor, semantic preview, problems) is non-conformant.
- Mode fallback. If the configured LSP mode is unavailable, Studio MUST fall back to WASM mode rather than failing to open. The fallback MUST be visibly indicated to the author.
- CSP compliance. A Studio deployment that does not serve a conformant Content Security Policy (§7.2) is non-conformant, regardless of runtime behavior.
10. Diagnostic Codes (M23xxx)
All diagnostics introduced by this RFC occupy the M23300–M23399 range.
| Code | Severity | Summary |
|---|---|---|
| M23300 | Error | Studio WASM module failed to initialize; editing features unavailable. |
| M23301 | Warning | Semantic preview panel update exceeded the 2-second latency budget. |
| M23302 | Warning | Language server returned a diagnostic code not present in the allocated diagnostic table. |