gnomonlearn

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

  1. 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.
  2. Studio MUST NOT execute .gnm source 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.
  3. 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.
  4. 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).
  5. The publish flow in Studio MUST be identical in outcome to running gnomon publish from the CLI; Studio MUST NOT bypass the semver lint gate (RFC-0019 §4.1).
  6. 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 .gnm source 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 publish via 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 postMessage bridge 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 lsp process 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 .gnm files and module.gnm are 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 entity declaration: renders field names, types, and any inferred or declared documentation, plus applicable facets.
  • For a flow declaration: renders the state machine as a diagram (states, transitions, guards).
  • For a facet declaration: renders the contributed fields and rules.
  • For an agent declaration: 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”:

  1. Studio runs the equivalent of gnomon publish against the active module.
  2. 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.
  3. If lint passes, Studio uploads the bundle to the configured registry.
  4. 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 lsp process (which has access to the platform credential store), or
  • Prompts the author for an GNOMON_REGISTRY_TOKEN value 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 binding declarations.
  • Studio MUST NOT apply install plans.
  • Studio MUST NOT invoke action declarations 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 eval and new Function.
  • Restricts connect-src to 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

ScenarioOutcomeDiagnostic
WebSocket LSP connection fails at startupStudio falls back to WASM mode, shows status banner— (status indicator, not a code)
WASM module fails to initializeStudio shows error state; editing is unavailableM23300
Semantic preview times out (>2s on a responsive system)Panel shows “Updating…” placeholderM23301 (warning)
Publish: semver lint gate blocksPublish aborted, lint codes displayed in panelL01401 (RFC-0014)
Publish: registry unreachablePublish aborted, error displayedM01911 (RFC-0019)
Session credential cleared after tab closeAuthor must re-enter token on next session— (expected behavior)
Author attempts to open a non-.gnm fileFile tree ignores it; no error—
LSP returns diagnostic for unknown codeProblems panel displays code with “unknown diagnostic” tooltipM23302 (warning)

9. Invariants

  1. No execution. Studio MUST NOT execute .gnm declarations against live state. Analysis (compilation, type inference, semantic preview) is permitted; execution is not.
  2. 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.
  3. Publish gate parity. The Studio publish flow MUST produce the same outcome as gnomon publish for the same module and credentials. Studio MUST NOT bypass any gate that the CLI enforces.
  4. Credential non-persistence. Session credentials MUST NOT be written to persistent storage. Loss of credentials on tab close is expected and correct behavior.
  5. Panel completeness. A Studio build that omits any normative panel (file tree, editor, semantic preview, problems) is non-conformant.
  6. 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.
  7. 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.

CodeSeveritySummary
M23300ErrorStudio WASM module failed to initialize; editing features unavailable.
M23301WarningSemantic preview panel update exceeded the 2-second latency budget.
M23302WarningLanguage server returned a diagnostic code not present in the allocated diagnostic table.