From f5bf7cba813c9c9345727597f3d8ae48bd76c71b Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Feb 2026 17:40:16 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20Phase=204=20design=20=E2=80=94=20CoreDe?= =?UTF-8?q?no=20+=20Web=20Components?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Approved architecture for the JavaScript runtime layer: - CoreDeno (Deno sidecar) as module loader, I/O fortress, and dev toolchain - go-html as Web Component factory (manifest → custom elements) - .core/view.yml convention for declarative app definitions - Signed application loading with ed25519 verification - gRPC/Unix socket bridge between Deno and Go - Gradual Angular migration to vanilla Web Components - HLCRF slot composition with Shadow DOM isolation Open sections (polyfills, object store, config generators, marketplace) pending dAppServer heritage code review. Co-Authored-By: Claude Opus 4.6 --- ...17-phase4-coredeno-webcomponents-design.md | 245 ++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 docs/plans/2026-02-17-phase4-coredeno-webcomponents-design.md diff --git a/docs/plans/2026-02-17-phase4-coredeno-webcomponents-design.md b/docs/plans/2026-02-17-phase4-coredeno-webcomponents-design.md new file mode 100644 index 0000000..a701cde --- /dev/null +++ b/docs/plans/2026-02-17-phase4-coredeno-webcomponents-design.md @@ -0,0 +1,245 @@ +# Phase 4: CoreDeno + Web Components + +**Date:** 2026-02-17 +**Status:** Approved (open sections pending dAppServer code review) +**Heritage:** dAppServer prototype (20 repos), Chandler/Dreaming in Code + +## Vision + +A universal application framework where `.core/view.yml` defines what an app IS. +Run `core` in any directory — it discovers the manifest, verifies its signature, +and boots the application. Like `docker-compose.yml` but for applications. + +Philosophical lineage: Mitch Kapor's Chandler (universal configurable app), +rebuilt with Web Components, Deno sandboxing, WASM rendering, and LEM ethics. + +## Architecture + +``` +┌─────────────────────────────────────────────┐ +│ WebView2 (Browser) │ +│ ┌───────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Angular │ │ Web Comp │ │ go-html │ │ +│ │ (shell) │ │ (modules)│ │ WASM │ │ +│ └─────┬─────┘ └────┬─────┘ └────┬─────┘ │ +│ └──────┬───────┘ │ │ +│ │ fetch/WS │ │ +└───────────────┼─────────────────────┼───────┘ + │ │ +┌───────────────┼─────────────────────┼───────┐ +│ CoreDeno (Deno sidecar) │ │ +│ ┌────────────┴──────────┐ ┌─────┴─────┐ │ +│ │ Module Loader │ │ ITW3→WC │ │ +│ │ + Permission Gates │ │ Codegen │ │ +│ │ + Dev Server (HMR) │ │ │ │ +│ └────────────┬──────────┘ └───────────┘ │ +│ │ gRPC / Unix socket │ +└───────────────┼─────────────────────────────┘ + │ +┌───────────────┼─────────────────────────────┐ +│ Go Backend (CoreGO) │ +│ ┌────────┐ ┌┴───────┐ ┌─────────────────┐ │ +│ │ Module │ │ gRPC │ │ MCPBridge │ │ +│ │Registry│ │ Server │ │ (WebView tools) │ │ +│ └────────┘ └────────┘ └─────────────────┘ │ +└─────────────────────────────────────────────┘ +``` + +Three processes: +- **WebView2**: Angular shell (gradual migration) + Web Components + go-html WASM +- **CoreDeno**: Deno sidecar — module sandbox, I/O fortress, TypeScript toolchain +- **CoreGO**: Framework backbone — lifecycle, services, I/O (core/pkg/io), gRPC server + +## Responsibility Split + +| Layer | Role | +|-------|------| +| **CoreGO** | Framework (lifecycle, services, I/O via core/pkg/io, module registry, gRPC server) | +| **go-html** | Web Component factory (layout → Shadow DOM, manifest → custom element, WASM client-side registration) | +| **CoreDeno** | Sandbox + toolchain (Deno permissions, TypeScript compilation, dev server, asset serving) | +| **MCPBridge** | Retained for direct WebView tools (window control, display, clipboard, dialogs) | + +## CoreDeno Sidecar + +### Lifecycle +Go spawns Deno as a managed child process at app startup. Auto-restart on crash. +SIGTERM on app shutdown. + +### Communication +- **Channel**: Unix domain socket at `$XDG_RUNTIME_DIR/core/deno.sock` +- **Protocol**: gRPC (proto definitions in `pkg/coredeno/proto/`) +- **Direction**: Bidirectional + - Deno → Go: I/O requests (file, network, process) gated by permissions + - Go → Deno: Module lifecycle events, HLCRF re-render triggers + +### Deno's Three Roles + +**1. Module loader + sandbox**: Reads ITW3 manifests, loads modules with +per-module `--allow-*` permission flags. Modules run in Deno's isolate. + +**2. I/O fortress gateway**: All file/network/process I/O routed through Deno's +permission gates before reaching Go via gRPC. A module requesting access outside +its declared paths is denied before Go ever sees the request. + +**3. Build/dev toolchain**: TypeScript compilation, module resolution, dev server +with HMR. Replaces Node/npm entirely. In production, pre-compiled bundles +embedded in binary. + +### Permission Model +Each module declares required permissions in its manifest: + +```yaml +permissions: + read: ["/data/mining/"] + write: ["/data/mining/config.json"] + net: ["pool.lthn.io:3333"] + run: ["xmrig"] +``` + +CoreDeno enforces these at the gRPC boundary. + +## The .core/ Convention + +### Auto-Discovery +Run `core` in any directory. If `.core/view.yml` exists, CoreGO reads it, +validates the ed25519 signature, and boots the application context. + +### view.yml Format (successor to .itw3.json) + +```yaml +code: photo-browser +name: Photo Browser +version: 0.1.0 +sign: + +layout: HLCRF +slots: + H: nav-breadcrumb + L: folder-tree + C: photo-grid + R: metadata-panel + F: status-bar + +permissions: + read: ["./photos/"] + net: [] + run: [] + +modules: + - core/media + - core/fs +``` + +### Signed Application Loading +The `sign` field contains an ed25519 signature. CoreGO verifies before loading. +Unsigned or tampered manifests are rejected. The I/O fortress operates at the +application boundary — the entire app load chain is authenticated. + +## Web Component Lifecycle + +1. **Discovery** → `core` reads `.core/view.yml`, verifies signature +2. **Resolve** → CoreGO checks module registry for declared components +3. **Codegen** → go-html generates Web Component class definitions from manifest +4. **Permission binding** → CoreDeno wraps component I/O calls with per-module gates +5. **Composition** → HLCRF layout assembles slots, each a custom element with Shadow DOM +6. **Hot reload** → Dev mode: Deno watches files, WASM re-renders affected slots only + +### HLCRF Slot Composition + +``` +┌──────────────────────────────────┐ +│ (H - shadow) │ +├────────┬───────────────┬─────────┤ +│ │ │ (C-shadow) │ -panel> │ +│(L-shad)│ │(R-shad) │ +├────────┴───────────────┴─────────┤ +│ (F - shadow) │ +└──────────────────────────────────┘ +``` + +Each slot is a custom element with closed Shadow DOM. Isolation by design — +one module cannot reach into another's shadow tree. + +### go-html WASM Integration +- **Server-side (Go)**: go-html reads manifests, generates WC class definitions +- **Client-side (WASM)**: go-html WASM in browser dynamically registers custom + elements at runtime via `customElements.define()` +- Same code, two targets. Server pre-renders for initial load, client handles + dynamic re-renders when slots change. + +## Angular Migration Path + +**Phase 4a** (current): Web Components load inside Angular's ``. +Angular sees custom elements via `CUSTOM_ELEMENTS_SCHEMA`. No Angular code needed +for new modules. + +**Phase 4b**: ApplicationFrame becomes a go-html Web Component (HLCRF outer frame). +Angular router replaced by lightweight hash-based router mapping URLs to +`.core/view.yml` slot configurations. + +**Phase 4c**: Angular removed. WebView2 loads: +1. go-html WASM (layout engine + WC factory) +2. Thin router (~50 lines) +3. CoreDeno-served module bundles +4. Web Awesome (design system — already vanilla custom elements) + +## dAppServer Heritage + +20 repos at `github.com/dAppServer/` — the original client-side server concept +and browser↔Go communications bridge. Extract and port, not copy. + +| dAppServer repo | CoreDeno equivalent | Action | +|---|---|---| +| `server` | CoreDeno sidecar architecture | Extract | +| `dappui` | Web Component framework | Extract | +| `auth-server` + `mod-auth` | Signed manifest verification | Extract | +| `mod-docker` | Process management (core/pkg/process) | Port | +| `mod-io-process` | I/O fortress gRPC bridge | Extract | +| `server-sdk-typescript-angular` | Deno TypeScript bindings | Port | +| `app-marketplace` | Module registry/discovery | Extract | +| `app-directory-browser` | File browser Web Component | Port | +| `devops` | CI/deployment patterns | Reference | +| `app-utils-cyberchef` | Utility module example | Reference | +| `app-mining` | Mining module (already in ITW3) | Reference | +| `server-sdk-python` | Not needed (Go replaces) | Skip | + +## Open Sections (Pending dAppServer Code Review) + +These sections will be refined after studying the dAppServer codebase: + +### Polyfills +What browser APIs did dAppServer polyfill? Which are still needed in WebView2? +WebView2 is Chromium-based so most modern APIs are available natively. + +### Object Store +dAppServer's data persistence model. How does it map to CoreDeno? Options include +IndexedDB in WebView2, SQLite via Deno, or Go-managed storage via gRPC. + +### Templated Config Generators +The pattern for generating configs from templates. Informs `.core/view.yml` +codegen pipeline and how complex configurations are composed from simpler parts. + +### Git-Based Plugin Marketplace +Module discovery, versioning, and distribution via Git repositories. To be +designed after dAppServer `app-marketplace` code review. + +## Deliverables + +| Component | Location | Language | +|---|---|---| +| CoreDeno sidecar manager | `core/pkg/coredeno/` | Go | +| gRPC proto definitions | `core/pkg/coredeno/proto/` | Protobuf | +| gRPC server (Go side) | `core/pkg/coredeno/server.go` | Go | +| Deno client runtime | `core-deno/` (new repo) | TypeScript | +| ITW3 → WC codegen | `go-html/codegen/` | Go | +| .core/view.yml loader | `core/pkg/manifest/` | Go | +| Manifest signing/verify | `core/pkg/manifest/sign.go` | Go | +| WASM WC registration | `go-html/cmd/wasm/` (extend) | Go | + +## Not In Scope (Future Phases) + +- LEM auto-loading from signed manifests +- Module marketplace server infrastructure +- Offline-first sync / object store +- Full Angular removal (Phase 4c)