Core DevPre-alpha

Sumeru Web Client (SWC)

SWC is Sumeru’s browser workspace client: a TypeScript 7 component runtime that renders workspace views from JSON arch and records.

Folder layout

text

core/swc/src/
├── main.ts                 # bootstrap, register views/widgets, SwcApp.start
├── runtime/                # component kernel
│   ├── component.ts        # SwcComponent, callSetup, patch, destroy
│   ├── component-host.ts   # nested components + slots
│   ├── app.ts              # SwcApp, mount, ErrorBoundary
│   ├── hooks.ts            # useState, useService, useTemplateRef, mount effects
│   ├── scheduler.ts        # rAF scheduleRender / flushScheduledRenders
│   ├── lifecycle.ts        # onWillStart, onWillPatch, onPatched (per instance)
│   ├── portals.ts          # data-portal move/restore
│   └── patch/
│       └── keyed.ts        # keyed sibling reconciliation
├── template/
│   ├── html.ts             # html`` tagged literals (render + patch)
│   ├── helpers.ts          # forEach, when
│   └── sum/                # .sum.xml compiler (parser + codegen)
├── model/                  # SwcRecord, modifiers
├── views/                  # list, form, kanban, graph, pivot, calendar, gantt, map, cohort, chatter
├── widgets/                # field registry + FieldHost
├── shell/                  # layout, nav, launcher
├── devtools/               # SWC Vision
├── i18n/
├── services/               # rpc, action, router, bus, dialog, …
└── types/

Tests mirror this layout under core/swc/tests/{runtime,template,model,views,devtools}/.

Architecture

Layer	Location	Role
SWC bundle	`core/swc/` → `core/engine/assets/swc/swc.js`	Components, views, services
Go shell	`core/engine/templates/base.html`	Login/setup stay server HTML; workspace mounts `#swc-workspace`
Workspace JSON	`GET /web/swc/workspace`	View arch, records, toolbar metadata
Data plane	`POST /api/rpc`	CRUD, `read_group`, `call`, `onchange`
Serializer	`core/engine/swcmeta/`	Parse `sys.view` arch → JSON (ACL redaction)

TypeScript 7 toolchain

Direct devDependencies in core/swc/package.json track latest stable releases (pinned in package-lock.json):

Compiler: typescript@^7
Bundler: esbuild@^0.28 (.sum.xml plugin loads TypeScript codegen)
Tests: vitest@^4 with jsdom@^30 (environment: "jsdom")
Build: make swc (esbuild IIFE bundle)
Typecheck: make swc-check (tsc --noEmit)
Tests: make swc-test (Vitest)

Bootstrap

Authenticated workspace pages inject:

javascript

window.__SWC_BOOTSTRAP__ = { csrfToken, rpcUrl, user, menus, apps, workspace, … };

SWC reads bootstrap on DOMContentLoaded, mounts ShellLayout + WorkspaceRouter, and initializes shell chrome (sidebar, app launcher, view-tab SPA navigation).

Shell features

Feature	Module	Behaviour
Global app launcher	`shell/app-launcher.ts`	Cmd/Ctrl+K fuzzy search across menus and apps
SPA router	`services/router.ts`, `views/workspace/WorkspaceRouter.ts`	URL-driven view switching without full page reload
View tab sync	`shell/view-tab-sync.ts`	Breadcrumb Kanban/List/Form tabs stay active after record open
List/kanban search	`views/list/ListView.ts`, `views/kanban/KanbanView.ts`	Toolbar search via `?q=` query param
Addon loader	`addon/loader.ts`	Loads `window.__SWC_ADDON_ENTRIES__` before bootstrap

Runtime capabilities

Concept	SWC module
Component	`runtime/component.ts` — `callSetup()`, `scheduleRender`, `template().patch()`
Local state	`useState` in `runtime/hooks.ts` (batched with `runtime/scheduler.ts`)
Services	`useService` + `services/*`
Lifecycle	Per-instance `onWillStart` / `onWillPatch` / `onPatched` in `runtime/lifecycle.ts`
Registry	`runtime/registry.ts` — `fields`, `views`, `services`, `main_components`
Templates	`template/html.ts` (`render` + incremental `patch`), optional `template/sum/`
Keyed lists	`template/helpers.ts` `forEach` + `runtime/patch/keyed.ts`
Refs / slots / portals	`useTemplateRef`, `ComponentHost` slots, `runtime/portals.ts`
Relational model	`model/record.ts`
DevTools	`devtools/bridge.ts` — `window.__SWC_DEVTOOLS__`
Views	`views/list`, `views/form`, `views/kanban`, `views/gantt`, `views/map`, `views/cohort`, …

SWC Vision

Enable with ?debug=1 on workspace URLs. Exposes component tree via window.__SWC_DEVTOOLS__. Optional browser extension in core/swc/devtools-extension/.

Cutover

Legacy assets/js/* and HTML workspace render (*_render.go) were removed in the SWC release. Workspace UI is SWC-only; Home/Apps/Settings support SPA shell routes via ?shell=home|apps|settings.

Addon extension

Manifest key "swc_entry": "static/swc/main.js" registers widgets/views on registry (see SWC widgets and Build a module with SWC).

Developer docs

Topic	Page
End-to-end module	Build a module with SWC
XML → JSON pipeline	Arch JSON pipeline
Field attributes	Field attributes
Widget catalog	SWC widget catalog
View types	View types
Sum template	Sum template
Devtools	SWC Vision devtools