Skip to content

docs(adr): add ADR-0032, structured Workshop editor form factor and stack - #800

Merged
e54-bot merged 2 commits into
mainfrom
docs/adr-0032-structured-editor
Oct 19, 2026
Merged

e54-bot merged 2 commits into
mainfrom
docs/adr-0032-structured-editor

Conversation

@e54-bot

@e54-bot e54-bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Adds ADR-0032. It decides the form factor that ADR-0029 left open for a structured editing view: what the view is, where it lives, and how it is built.

  • Form factor: wright ui [INPUT] serves a local web UI on loopback and opens it in the browser. It is not a hosted service, an editor extension, or a desktop shell.
  • Scope: raw Workshop projects, the same scope as ADR-0029. Other inputs are refused with the owner named.
  • Adapter, like MCP (ADR-0020):
    • The page sends wright-agent/v1 bodies to one local endpoint and gets the results back unchanged.
    • The UI has no Workshop semantics of its own.
    • The endpoint is not a public transport.
  • Local endpoint security:
    • Binds 127.0.0.1 on an ephemeral port.
    • Every request needs a per-session token, passed to the page in the URL fragment.
    • Requests with a foreign Host or Origin are refused. No CORS headers.
  • Writes: wright ui applies the editStatements transaction after re-checking inputIdentity. The page never touches files.
  • Ownership: a top-level ui/ directory in wright, outside the Rust workspace.
  • Stack: Svelte 5 in project-wide runes mode, strict TypeScript, and Vite.
    • The only runtime dependency is svelte.
    • Every value that leaves the reactive tree goes through $state.snapshot.
    • React was rejected. Preact with signals was the close alternative.
  • Types: generated from schemas/wright-agent-v1.schema.json and workshop-rs's rule-content-v1.schema.json. A stale copy fails CI.
  • Build and distribution:
    • Assets are built in ui/, not committed, and embedded behind a ui Cargo feature that release builds enable.
    • Without the feature, wright ui reports that the build has no UI and exits 2. Rust-only builds need no Node.
    • Release channels are unchanged.
  • Verification:
    • A UI CI job runs svelte-check, unit tests, the build, and a 100 KB gzip size budget.
    • An end-to-end headless-browser test edits a fixture and checks the bytes on disk.
  • Delivery in layers: read-only first, then editing (editStatements), then full dropdowns (listEntries).

Why now

The prototype (practice-range, 139 rules) covers the interaction end to end. It also shows the limits of plain JavaScript: the whole form is rebuilt after every change, and untyped nodes caused real defects. Its only link to Wright is a Python bridge, because a browser cannot reach wright serve over stdio.

Review

Accepted by the owner. The four open points were accepted as drafted: the command name wright ui, the ui Cargo feature with exit 2 when it is absent, the 100 KB gzip size budget, and host-side writes in decision 5.

Documentation only; no code or behavior changes.

…tack

Proposes wright ui: a local web UI over ToolService for raw Workshop projects, built with Svelte 5, TypeScript, and Vite in a top-level ui/ directory and embedded behind a ui Cargo feature.
@e54-bot
e54-bot merged commit e414efc into main Oct 19, 2026
16 checks passed
@e54-bot
e54-bot deleted the docs/adr-0032-structured-editor branch October 19, 2026 14:57
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Make Workshop Great Again Oct 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Development

Successfully merging this pull request may close these issues.

2 participants