Skip to content

README.md

Latest commit

 

History

History
157 lines (128 loc) · 6.81 KB

README.md

File metadata and controls

157 lines (128 loc) · 6.81 KB
Raw

Readonly MoonBit Viewer

In the OpenSeek monorepo, the reusable Viewer has two deliberately different in-tree hosts:

  • viewer: the reusable MoonBit readonly viewer. It is Monaco-shaped in API and behavior where that helps embedders, but it stays MoonBit-owned and does not import Monaco, VS Code, or CodeMirror code.
  • internal/shell: the fast repository-only development, preview, and E2E host. It demonstrates one composition through public Viewer APIs; it is not an external import surface or the product host.
  • OpenSeek's desktop/frontend/fileeditor: the primary downstream, user-facing host in this monorepo. It owns its product policy and integrates the viewer through the same public APIs and ViewerServices capabilities available to other embedders.

The separate moonbitlang/editor-server module supplies the reference backend. OpenSeek supplies its own host integrations.

direction: down

embedder: another MoonBit app
openseek: OpenSeek desktop file editor — primary product host

repo: this repository {
  viewer: viewer — reusable workspace module {
    facade: Viewer facade
    common: viewer/common — DOM-free
    browser: browser runtime + contributions
  }
  reference: editor reference composition {
    workbench: internal/shell/workbench
    server: moonbitlang/editor-server
  }
}

embedder -> repo.viewer.facade: imports moonbitlang/editor in the workspace
openseek -> repo.viewer.facade: public Viewer API + ViewerServices
repo.reference.workbench -> repo.viewer.facade: embeds via public API
repo.reference.workbench <-> repo.reference.server: readonly remote protocol

Monaco/VS Code is the primary design reference. CodeMirror is a secondary reference when its simpler state/view split is useful. Both submodules are reference-only.

UI Development Workflow

Use internal/shell as the default UI development loop because it builds and previews much faster than the full OpenSeek desktop application. OpenSeek is still the primary real downstream host and must remain an active consumer of the editor's public surface.

  • A visual or behavioral improvement to existing Viewer UI should normally appear in OpenSeek through its existing integration with no or minimal host changes. Develop and visually verify it in internal/shell, then run the relevant targeted OpenSeek compile/tests and the repository integration gates.
  • A new UI capability may also be developed and previewed first in internal/shell. Unless explicitly scoped to editor-only exploration, treat new user-facing Viewer UI as intended for OpenSeek: the same implementation task must add the required public editor seam and the desktop/frontend/fileeditor adaptation. Do not defer known provider, service, lifecycle, theme, or asset wiring to an unspecified downstream follow-up.
  • Keep OpenSeek-specific RPC, storage, workspace, and product-shell policy in OpenSeek. The reference shell is a fast host and behavioral proof, not a place to make product-specific behavior part of the reusable Viewer.

A full OpenSeek package/build/preview is a final integration tool when OpenSeek-specific layout, effects, assets, or packaging are involved; it is not the routine editor UI inner loop. See docs/harness.md for the layered commands and docs/architecture.md for the host boundary.

Browser Runtime

Whole-line Markdown comments render exact lowercase d2/diago and uml/plantuml fences synchronously with the bundled Diago and kokic/uml compilers. Exact lowercase mermaid fences use Mermaid's official browser implementation. The web build downloads the pinned mermaid@11.16.0 npm archive, verifies its SHA-256 digest, and stages the minified ESM entry, relative chunks, and license under web/dist/mermaid/. Mermaid remains a lazy runtime import, but it is loaded from that same-origin directory rather than a public CDN.

Generated inline diagram SVG is not a sanitization boundary. Embedders must trust every viewer Markdown source that can contain d2, diago, uml, or plantuml fences, including workspace comments, hover-provider results, and agent-feedback bodies. Embedders that enable Mermaid rendering must stage the generated mermaid/ tree at the document resource base, allow same-origin module scripts in their CSP, and permit the inline styles used inside Mermaid SVG output. A clean build needs registry access once; the verified archive is cached under target/vendor-mermaid/cache/, so later builds can reuse it offline. If the local asset is missing or blocked, or if a diagram is invalid, the viewer keeps the safe tokenized source code visible.

Repository Development

In the OpenSeek monorepo this directory is a member of the root workspace, while the local moon.work keeps the commands below scoped to the editor and its server. From the repository root, the equivalent integration entry points are just editor-build, just editor-test, and just editor-test-browser.

just

Open http://127.0.0.1:5173/. The dev server is the internal host/backend shell: it serves web/dist and talks to the browser workbench over the readonly remote protocol WebSocket.

just builds the browser assets and server, then runs the server module on its default Wasm target and serves the current checkout. To opt into the native target, run just TARGET=native dev. Use just ROOT=<workspace> PORT=<port> dev to override the starting workspace or port, or just list to show every recipe.

ROOT selects only the starting workspace. The workbench's Open Repository… picker may switch the running server without a restart, with its reach controlled separately by BROWSE_ROOT and the listener bind:

  • on a loopback bind such as HOST=127.0.0.1, an empty BROWSE_ROOT permits browsing the host filesystem;
  • on a non-loopback bind, including plain just dev with its 0.0.0.0 default, an empty BROWSE_ROOT disables repository browsing; and
  • an explicit BROWSE_ROOT=<directory> permits only that realpathed directory and its descendants, on either kind of bind.

The reference server has no authentication and exposes the active workspace's source files. Use non-loopback binds only on a trusted network, and grant the smallest practical BROWSE_ROOT when repository switching is required.

The browser suites additionally require Node.js 18 or newer, the locked npm dependencies, and a Playwright-managed Chromium installation:

npm ci
npx playwright install chromium

On Linux, use npx playwright install --with-deps chromium when Chromium's system dependencies are not installed yet.

Validation

moon check --target all --warn-list +73 --deny-warn
moon fmt --check
just test
just build
just test-browser-smoke

Current architecture lives in docs/architecture.md. Browser harness behavior lives in docs/harness.md.