SWiM — Sigil Window Morph

What every SWiM window is

• 3D-accelerated — a GPU surface, composited through one rendering abstraction that maps to Metal (macOS), Vulkan (Linux), D3D12 (Windows), WebGPU (web), and V3D (sigilOS), with a software-raster floor so it always works.
• Themeable — content is a declarative, retained Scene styled by a theme-token system, so the same app restyles wholesale without touching a line of logic.
• Dual-faced — one app core drives a GUI face and a CLI face, and the window flips between them. GUI on the front, terminal on the back.

The flip — one window, two faces

sigilOS mandates that every subsystem ship a GUI and a CLI. SWiM makes that the window itself: one artifact, two faces, a flip as the seam. The CLI face is a first-class client of the app's command grammar — not a log dump — bound to the same live state. Flip mid-task and the other face reflects the same model. Trigger it by hotkey, gesture, menu, or API.

The Scene & theming

Window content is a Scene: a retained tree of nodes (containers, text, vectors, images, surfaces, custom GPU nodes) whose properties resolve against a theme token table — colors, spacing, a type ramp, motion curves, the light source. Re-theming is data, not code. SWiM ships with the Lumen theme (NeXTSTEP-dark, the #a78bfa accent, geographic-sun shadows and night-mode lighting — the Lumen look) and a neutral default; designers author their own, and switching is live and animatable. It's the same Scene, render, and theme model Lumen already uses — SWiM is its portable, documented form.

One core, many front doors

The engine is 100% Sigil, compiled by cc0 to a native library per platform (libswim.dylib / .so / .dll / .wasm) exposing one stable C ABI. Over that ABI sit thin, idiomatic per-language shims, so you call SWiM from your language and author the app without learning Sigil:

Language	Shim	Feels like
C / C++	header + the C ABI directly	swim_run(app)
Rust	swim crate	swim::run(app)
Python	wheel	swim.run(app)
JS / TS	N-API module + WASM build	import { run } from 'swim'
Swift	SwiftPM package	SWiM.run(app)
Go / C#	cgo / P-Invoke	idiomatic wrappers

Shims are thin marshalling layers with no logic forks — the Sigil core is the single source of behavior — and new bindings are mostly generated from cc0's ABI metadata, not hand-written.

Architecture — portable core, thin PAL

A single portable Sigil Core (Scene graph, theme engine, the AppCore model + command grammar, the dual-face controller + flip animator, and the swim.gpu abstraction) sits above a deliberately thin per-OS PAL (Platform Abstraction Layer): surface creation, input, a GPU device handle, a PTY, and the capability bridge. No per-OS forks live above the PAL line — one behavior everywhere; the host differences live only in the PAL. cc0 compiles it native for each target (macho, PE, ELF, WASM, and the sigilOS V3D path), reproducibly. It's the exact structural template proven by the Forge cross-platform effort and the SRDX macOS client.

Platform	GPU backend	Surface
macOS	Metal	Cocoa
Windows	D3D12 (Vulkan fallback)	Win32
Linux	Vulkan	Wayland / X
Web	WebGPU (WASM)	canvas
sigilOS	V3D / native GPU-first path	native Lumen host

The API, in one glance

// An app = one core, two faces.
app Notes {
  state notes: List<Note>

  scene gui(theme) {              // GUI face — a declarative Scene
    Column(pad: theme.space.md) {
      Text(notes.title, style: theme.type.h1)
      List(notes) { n => Card(n.body, tap: open(n)) }
    }
  }

  cli grammar {                   // CLI face — same core, a command grammar
    "ls"          => notes.map(n => n.title)
    "open <id>"   => open(id)
    "new <title>" => notes.add(title)
  }
}

swim.run(Notes, platform: auto, theme: lumen,
  flip: { axis: Y, curve: theme.motion.snap, key: "⌘\\" })

Two hard bars @grio set

1 · Developer experience ≥ Qt / Electron / Tauri

Embedding SWiM must be as easy or easier than Qt or any website-to-app wrapper, on every OS. Zero-to-window in one command (swim new app && swim run); embedding into an existing project is a single dependency and one swim.run(...) call — no per-OS project files, no bundler config, no native build step to understand. One small native artifact, not a bundled browser engine — megabytes, not the ~100 MB Electron floor. A "hello, window" must be measurably fewer steps than the equivalent in Qt, Electron, and Tauri — if it isn't, it's treated as a bug.

2 · All-Sigil core, language-specific shims

The engine is one Sigil codebase; the bindings are idiomatic per language (above). You get Sigil's reproducible, single-behavior core, and you call it from whatever you already build in.

Capability-honest, everywhere

On sigilOS a SWiM window binds real Cap<T> scopes (display, input, fs, net) — no ambient authority, the same discipline as the OS. On other systems the PAL maps requested capabilities to the host's own model (macOS entitlements, Windows AppContainer, Linux portals, browser permissions) and surfaces what it cannot enforce — SWiM never pretends to a guarantee the host can't keep. The CLI face is cap-scoped identically to the GUI face: no privilege back-door through the terminal.

---

The plan — Forge first, then the framework

Phasing is deliberately re-centered on the funded near-term deliverable (Forge cross-platform), with the general framework deferred:

Phase	Deliverable
P0	RFC ratified (✅ name = Morph, greenlit). Freeze the PAL contract, the swim.gpu interface, and the C ABI. Prove the DX bar with a 5-line "hello, window" measured against Qt / Electron / Tauri.
P1	Forge's UI running on SWiM on macOS (Metal), looking exactly how it will on Linux and Windows — the uniform cross-platform Forge look. Validates the Scene, theming, and the DX bar on a real app.
P2	Forge uniform on Linux (Vulkan) + Windows (D3D12) — same look, same code, native each OS. First language shims (Rust + C).
P3	Broaden shims (Python / JS-TS / Swift); the Web (WebGPU) PAL; the GUI⟺CLI flip as a general primitive; the swim CLI and scaffolds.
P4	The general framework: swim.host(lumen) — the real Lumen on a foreign desktop, optionally over SRDX; the sigilOS V3D PAL folds back so sigilOS Lumen is a SWiM host.

SWiM reuses, rather than reinvents: the Lumen Scene / theming / lighting, the Forge portable-core + thin-PAL template, SRDX for remote surfaces, and the GPU-first-with-software-floor rendering rule. Tracked as the fleet epic grioghar/sigil#190; near-term deliverable ties the Forge cross-platform epic grioghar/sigil#116.