Core DevPre-alpha

Sumeru Web Client (SWC)

SWC is Sumeru’s browser workspace client: a custom reactive component runtime (TypeScript 7) that replaces server-rendered workspace HTML and progressive JavaScript.

Folder layout (Sumeru-native)

core/swc/src/
├── main.ts                 # bootstrap, registerCore, SwcApp.start
├── runtime/                # framework kernel
│   ├── component.ts        # SwcComponent, updateProps, lifecycle
│   ├── component-host.ts   # nested components in templates
│   ├── app.ts              # SwcApp, mount, ErrorBoundary, rAF schedule
│   ├── hooks.ts            # useState, useEffect, useService
│   ├── reactivity.ts       # reactive proxy, markRaw, toRaw
│   ├── scheduler.ts        # rAF render queue
│   ├── lifecycle.ts        # onWillStart, onWillPatch, onPatched, …
│   └── patch/              # DOM update engine
│       ├── keyed.ts        # t-key / forEach reconciliation
│       └── blocks.ts       # static blocks + dynamic holes
├── template/               # templates
│   ├── html.ts             # html`` tagged literals
│   ├── helpers.ts          # forEach, when, fragment
│   └── sum/                # sum-template compiler (.sum.xml)
├── model/                  # client record layer
│   ├── record.ts           # SwcRecord, RecordStore, onchange
│   └── modifiers.ts        # invisible/readonly/required + domains
├── views/                  # workspace view types (by kind)
│   ├── workspace/          # WorkspaceRouter, workspace-chrome
│   ├── list/, form/, kanban/, graph/, pivot/, calendar/, chatter/, advanced/
├── widgets/                # field registry + field components
├── shell/                  # app chrome (layout, nav, launcher)
├── devtools/               # SWC Vision (__SWC_DEVTOOLS__)
├── i18n/                   # _t(), loadTranslations
├── services/               # rpc, action, router, bus, dialog, …
└── types/                  # bootstrap, workspace

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)
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:

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

Capability mapping (OWL-inspired, not OWL code)

Concept	SWC module
Component	`runtime/component.ts`
Registry	`runtime/registry.ts` — `fields`, `views`, `services`, `actions`, `systray`
Templates	`template/html.ts`, `template/sum/` (`.sum.xml`)
Keyed lists	`template/helpers.ts` + `runtime/patch/keyed.ts`
Reactivity	`runtime/reactivity.ts`
Services	`services/*` + `useService()` in `runtime/hooks.ts`
Relational model	`model/record.ts`
DevTools	`devtools/bridge.ts` — `window.__SWC_DEVTOOLS__`
Views	`views/list`, `views/form`, `views/kanban`, …

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