From 3bf3aa1989403fdd6c1c7106c98b3af5fce0d078 Mon Sep 17 00:00:00 2001
From: hzhang <hzhang@hangman-lab.top>
Date: Fri, 22 May 2026 23:00:02 +0100
Subject: [PATCH] chore: P0 skeleton

Bootstrap the Dashward repo per arch/UBUNTU-DASHBOARD-SPACE.md:

- pnpm-workspaces monorepo (sdk, extension, container, widgets-builtin/*)
- GNOME extension stub (metadata.json, src/*.ts placeholders for warden,
  guard, supervisor, entry UX, DBus service)
- WebKit container stub (GJS main + page-side runtime + dashboard.html)
- TypeScript widget SDK (defineWidget + types)
- Builtin clock widget as the first SDK consumer example
- DBus interface XML (proto/shell.iface.xml) and shared types
- esbuild configs for extension and container; tsc for SDK
- Design doc copied in at repo root for discoverability

No functional logic yet -- all components are placeholders that compose
in extension.ts so the build chain can be exercised. P1 (workspace
warden) starts next.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .editorconfig                                |  15 +
 .gitignore                                   |  29 +
 README.md                                    |  60 ++
 UBUNTU-DASHBOARD-SPACE.md                    | 683 +++++++++++++++++++
 container/esbuild.config.js                  |  34 +
 container/package.json                       |  16 +
 container/runtime/dashboard.html             |  12 +
 container/runtime/runtime.ts                 |  15 +
 container/runtime/styles.css                 |  22 +
 container/src/bridge.ts                      |   4 +
 container/src/dbus-client.ts                 |   3 +
 container/src/main.ts                        |  10 +
 container/src/window.ts                      |   4 +
 container/tsconfig.json                      |  10 +
 extension/esbuild.config.js                  |  28 +
 extension/metadata.json                      |   9 +
 extension/package.json                       |  16 +
 extension/src/container-supervisor.ts        |   9 +
 extension/src/dbus-service.ts                |   8 +
 extension/src/entry-ux.ts                    |   9 +
 extension/src/extension.ts                   |  40 ++
 extension/src/window-guard.ts                |   9 +
 extension/src/workspace-warden.ts            |   9 +
 extension/tsconfig.json                      |  10 +
 extension/widgets-builtin/clock/package.json |  13 +
 extension/widgets-builtin/clock/src/index.ts |  41 ++
 extension/widgets-builtin/clock/widget.json  |  10 +
 package.json                                 |  20 +
 pnpm-workspace.yaml                          |   6 +
 proto/shell.iface.xml                        |  38 ++
 proto/types.ts                               |  42 ++
 scripts/dev-vm.sh                            |  10 +
 scripts/lint.sh                              |   4 +
 scripts/package.sh                           |   9 +
 sdk/package.json                             |  22 +
 sdk/src/define-widget.ts                     |   5 +
 sdk/src/index.ts                             |  11 +
 sdk/src/types.ts                             |  41 ++
 sdk/tsconfig.json                            |   8 +
 tsconfig.base.json                           |  17 +
 widgets/.gitkeep                             |   0
 41 files changed, 1361 insertions(+)
 create mode 100644 .editorconfig
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 UBUNTU-DASHBOARD-SPACE.md
 create mode 100644 container/esbuild.config.js
 create mode 100644 container/package.json
 create mode 100644 container/runtime/dashboard.html
 create mode 100644 container/runtime/runtime.ts
 create mode 100644 container/runtime/styles.css
 create mode 100644 container/src/bridge.ts
 create mode 100644 container/src/dbus-client.ts
 create mode 100644 container/src/main.ts
 create mode 100644 container/src/window.ts
 create mode 100644 container/tsconfig.json
 create mode 100644 extension/esbuild.config.js
 create mode 100644 extension/metadata.json
 create mode 100644 extension/package.json
 create mode 100644 extension/src/container-supervisor.ts
 create mode 100644 extension/src/dbus-service.ts
 create mode 100644 extension/src/entry-ux.ts
 create mode 100644 extension/src/extension.ts
 create mode 100644 extension/src/window-guard.ts
 create mode 100644 extension/src/workspace-warden.ts
 create mode 100644 extension/tsconfig.json
 create mode 100644 extension/widgets-builtin/clock/package.json
 create mode 100644 extension/widgets-builtin/clock/src/index.ts
 create mode 100644 extension/widgets-builtin/clock/widget.json
 create mode 100644 package.json
 create mode 100644 pnpm-workspace.yaml
 create mode 100644 proto/shell.iface.xml
 create mode 100644 proto/types.ts
 create mode 100755 scripts/dev-vm.sh
 create mode 100755 scripts/lint.sh
 create mode 100755 scripts/package.sh
 create mode 100644 sdk/package.json
 create mode 100644 sdk/src/define-widget.ts
 create mode 100644 sdk/src/index.ts
 create mode 100644 sdk/src/types.ts
 create mode 100644 sdk/tsconfig.json
 create mode 100644 tsconfig.base.json
 create mode 100644 widgets/.gitkeep

diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..4250a32
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..4c39223
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,29 @@
+# Build outputs
+**/dist/
+**/build/
+*.tsbuildinfo
+
+# Node
+node_modules/
+.pnpm-store/
+npm-debug.log*
+pnpm-debug.log*
+
+# Editor
+.idea/
+.vscode/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Packaged extension
+*.shell-extension.zip
+
+# Local env / state
+.env
+.env.local
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8006028
--- /dev/null
+++ b/README.md
@@ -0,0 +1,60 @@
+# Dashward
+
+A dedicated rightmost workspace for custom widgets on Ubuntu/GNOME, in the
+spirit of macOS Dashboard.
+
+- **GNOME Shell extension** (GJS) creates the dashboard workspace, defends
+  it from regular window incursions, and supervises the container.
+- **WebKitGTK container** (separate process) renders an HTML page on that
+  workspace.
+- **Widget SDK** (TypeScript) lets you write widgets as web components.
+
+Status: P0 skeleton. Design lives in
+[`UBUNTU-DASHBOARD-SPACE.md`](https://git.hangman-lab.top/hzhang/Dashward/src/branch/main/UBUNTU-DASHBOARD-SPACE.md)
+(see also `~/arch/UBUNTU-DASHBOARD-SPACE.md` locally).
+
+## Target
+
+- Ubuntu 25.04 / GNOME Shell 48 / Wayland.
+- Other distros & versions: post-v1.
+
+## Repo layout
+
+```
+sdk/                      TS widget SDK, published as @dashward/widget-sdk
+extension/                GNOME Shell extension (GJS, TS-authored)
+  src/                    Extension source
+  widgets-builtin/        Builtin widgets shipped with the extension
+container/                WebKit kiosk process
+  src/                    GJS bootstrap
+  runtime/                Page-side runtime (host grid, edit mode, widget loader)
+widgets/                  Example / 3rd-party widget dev tree
+proto/                    Shared DBus XML + TS types
+scripts/                  Build & dev helpers
+```
+
+## Dev setup
+
+Requires Node ≥ 20 and pnpm ≥ 9. To install pnpm:
+
+```bash
+npm install -g pnpm
+```
+
+Then:
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Testing discipline
+
+All Shell-side iteration happens inside the
+`ubuntu2504-test` libvirt VM, **never on the host GNOME session** — a
+buggy extension can lock you out of the Wayland session. See the design
+doc §17 for the dev loop.
+
+## License
+
+TBD.
diff --git a/UBUNTU-DASHBOARD-SPACE.md b/UBUNTU-DASHBOARD-SPACE.md
new file mode 100644
index 0000000..ec7130d
--- /dev/null
+++ b/UBUNTU-DASHBOARD-SPACE.md
@@ -0,0 +1,683 @@
+# Ubuntu Dashboard Space — Design
+
+Status: design. Goal: a macOS-Dashboard-style **dedicated rightmost workspace**
+on GNOME/Ubuntu that hosts user-defined widgets. Widgets are written against
+a TypeScript SDK and rendered as web components inside an embedded WebKit
+view; the GNOME Shell extension is the workspace warden and the IPC bridge,
+nothing heavier.
+
+Codename: **Dashward** (decided 2026-05-22; see §19).
+
+---
+
+## 1. Goals & non-goals
+
+### Goals
+
+- A workspace that is **created by the extension** at enable time, lives at
+  the rightmost position, and is **destroyed** at disable time. It is not
+  one of the user's existing workspaces, even temporarily.
+- **Regular windows cannot enter it** — neither by overview drag, by
+  `super+shift+arrow`, by `wmctrl`/`xdotool`, nor by being newly mapped
+  there. Attempts get bounced to the prior workspace immediately.
+- Widgets are **web components in TS**. A buggy widget cannot take down
+  GNOME Shell.
+- Hot-reload during widget development.
+- Light/dark theme follows the system.
+- Zero hand-edits to user dotfiles outside `~/.local/share/dashward/` and
+  the extension install dir.
+
+### Non-goals (v1)
+
+- Cross-distro support beyond Ubuntu 25.04 / GNOME 48. KDE, XFCE, Cinnamon
+  are out of scope until v1 lands and stabilizes.
+- A widget marketplace, signing, or sandboxing beyond what WebKit's process
+  model already provides. Widgets are trusted code at v1.
+- macOS-style "ripple in" widget add animation. Edit mode is utilitarian.
+- Multi-monitor span: dashboard appears on the **primary** monitor only;
+  other monitors get the regular last-workspace view.
+- Replacing the regular workspace switcher UX. The dashboard is reached by a
+  dedicated gesture/shortcut, not by being workspace N+1 in the existing
+  switcher.
+
+---
+
+## 2. Hard constraints (carried from chat)
+
+| C# | Constraint | Resolution |
+|---|---|---|
+| C1 | Dashboard does **not** reuse any existing workspace | §5: append a new workspace at enable, mark it, remove at disable |
+| C2 | Dashboard is **always rightmost** | §5: position invariant maintained on every workspace mutation |
+| C3 | Regular windows cannot be **dragged into** dashboard | §6: layered defense on `window-added`, overview drop target, gesture handlers |
+| C4 | Widgets in **TypeScript** | §9: SDK is a TS package; widgets are TS modules bundled to ESM |
+| C5 | Avoid the GridSpaces lockout failure mode | §17: VM-only iteration loop; extension never touches `gnome-extensions enable` on host until VM-green |
+
+---
+
+## 3. Reality check (probed 2026-05-22 on ubuntu2504-test)
+
+| Component | Version | Note |
+|---|---|---|
+| Ubuntu | 25.04 (Plucky) | |
+| GNOME Shell | 48.0-1ubuntu1 | ESM extension format |
+| Mutter | 48.1 (`libmutter-16-0`) | API gen 16, `Meta.WorkspaceManager` stable |
+| gjs | 1.82.1 | SpiderMonkey 128 era — ESM, top-level await OK |
+| WebKit2GTK 4.1 (GTK3) | 2.50.4 + `gir1.2-webkit2-4.1` pre-installed | **Chosen** for the container — zero new GIR deps |
+| WebKitGTK 6.0 (GTK4) | 2.50.4 lib present, GIR not installed | Migration target post-v1 |
+| Session | Wayland (gdm `Ubuntu on Wayland` default) | |
+| Pre-existing ext | `ding`, `tiling-assistant`, `ubuntu-appindicators`, `ubuntu-dock` | tiling-assistant is the relevant precedent for window manipulation |
+
+Implication: we can build v1 with only what's already on disk — no new apt
+packages required. (Build chain is in dev only; not shipped onto the VM at
+runtime.)
+
+---
+
+## 4. Architecture
+
+Three processes, two IPC channels:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                     gnome-shell  (GJS, in-process)                       │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │  Dashward extension                                              │   │
+│  │   • WorkspaceWarden  (create/destroy + position invariant)        │   │
+│  │   • WindowGuard      (block window-added on dashboard ws)         │   │
+│  │   • EntryUX          (gesture, shortcut, panel indicator)         │   │
+│  │   • ContainerSupervisor (spawn/respawn web container, pin window) │   │
+│  │   • DBusService      "top.hangmanlab.Dashward.Shell"             │   │
+│  └─────────┬────────────────────────────────────────────────────────┘   │
+└────────────┼────────────────────────────────────────────────────────────┘
+             │ DBus session bus
+             ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│        dashward-container  (GJS + WebKit2 4.1, separate process)       │
+│   • One GtkWindow, fullscreen, undecorated, app_id = container          │
+│   • WebKitWebView loads file://…/dashboard.html                          │
+│   • DBus client: pushes shell events into the page via                  │
+│     UserContentManager.evaluate_javascript()                            │
+│   • UserContentManager script-message handlers receive page→shell calls │
+└─────────────────────────────────────────────────────────────────────────┘
+             │ WebKit user-content-manager bridge
+             ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│        dashboard.html  (WebKit content process, sandboxed by WebKit)     │
+│   • Runtime: dashboard-runtime.js (host shell, layout grid, edit mode)   │
+│   • SDK: @dashward/widget-sdk (TS, bundled in)                        │
+│   • Widgets: each loaded into its own <iframe> for crash isolation      │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**Why the container is its own process**: GJS code crashing inside
+`gnome-shell` kills the session. Container is forked under `Gio.Subprocess`;
+when it crashes, supervisor sees the exit, hides the dashboard slot's
+content, and respawns with backoff. Shell stays up.
+
+**Why widgets are in `<iframe>`s and not just `<div>`s**: a widget that
+loops, throws unhandled, or leaks memory only affects its iframe — the host
+page and other widgets keep running. Iframes also give us a clean origin
+boundary for widget asset paths.
+
+---
+
+## 5. Workspace lifecycle
+
+### Enable
+
+1. Snapshot user state:
+   - `org.gnome.mutter dynamic-workspaces` → save under
+     `~/.local/state/dashward/saved-settings.json`.
+   - `org.gnome.desktop.wm.preferences num-workspaces` → save.
+   - Current workspace count `N` (from `Meta.WorkspaceManager`).
+2. Set `dynamic-workspaces = false` (we need a fixed slot at the end that
+   doesn't get GC'd when empty).
+3. Set `num-workspaces = N + 1`.
+4. Take the new last workspace (index `N`) as **the dashboard slot**. Tag
+   it: stash its `Meta.Workspace` reference under `wm._dashSpaceWs` and
+   record the workspace's index in `WorkspaceWarden.index`.
+5. Spawn the container; pin its window to `wm._dashSpaceWs` (see §7).
+6. Install signal handlers (§6).
+
+### Steady state — invariants
+
+After **every** workspace mutation (workspace appended/removed/reordered)
+the warden re-checks:
+
+- `WorkspaceWarden.ws` still exists in `WorkspaceManager.get_workspaces()`.
+  If not (something forcibly removed it), recreate at the end. Log.
+- Its index equals `WorkspaceManager.get_n_workspaces() - 1`. If not, move
+  it to the end via `reorder_workspace(ws, N-1)`.
+
+### Disable
+
+1. Kill container.
+2. Remove the dashboard workspace via
+   `WorkspaceManager.remove_workspace(ws, current_time)`.
+3. Restore `num-workspaces` and `dynamic-workspaces` to snapshotted values.
+4. Disconnect all signals; clear `wm._dashSpaceWs`.
+
+### Edge cases
+
+- **User changes `num-workspaces` externally** while extension is enabled:
+  warden treats this as the new "N", appends dashboard at N (effectively
+  `num-workspaces = newN + 1`). Saved setting is updated.
+- **User logs out / shell restart (Wayland: only logout; X11: alt-F2 `r`)**:
+  `disable()` is called by Shell. If we somehow miss it (crash), a
+  best-effort cleanup runs on next `enable()`: detect workspace tagged with
+  our marker (`Meta.Workspace.get_work_area_all_monitors` is not enough;
+  we tag via a sticky window — see §7) and remove.
+- **Other extensions also manage workspaces** (e.g. tiling-assistant
+  adjusts but doesn't add/remove; should be compatible. WorkspaceMatrix
+  would conflict — flag in README as incompatible).
+
+---
+
+## 6. Window-defense rules
+
+### Layer 1: `window-added` bounce-back
+
+```js
+ws.connectObject('window-added', (_, window) => {
+  if (window === containerWindow) return;          // whitelist
+  if (window.is_override_redirect()) return;        // tooltip, menu, etc.
+  const fallback = priorWorkspaceFor(window);
+  window.change_workspace(fallback);
+}, this);
+```
+
+`priorWorkspaceFor` heuristic: the window's `get_user_time()` workspace if
+known, else workspace `N-1` (dashboard index minus 1), else workspace 0.
+
+This single hook catches:
+- new windows mapped to dashboard (`window-created` race: even if the
+  window initially picks dashboard via `_NET_WM_DESKTOP`, `window-added`
+  fires immediately when it joins);
+- programmatic moves via `wmctrl -r ... -t N`, `xdotool windowmove`,
+  `Meta.Window.change_workspace`;
+- keyboard `super+shift+→` on the rightmost workspace.
+
+### Layer 2: overview drop refusal
+
+In the activities overview, workspace thumbnails are drop targets via
+`WorkspaceThumbnail` + `_acceptDrop`. We monkey-patch the dashboard
+thumbnail's `acceptDrop` to return `false` (and the visual to show "no
+drop" cursor). Cleaner than letting Layer 1 bounce it back after the visual
+drop completed.
+
+### Layer 3: hide from regular switcher
+
+The dashboard workspace renders specially in the overview: instead of the
+normal thumbnail, we draw a placeholder card with the Dashward icon and
+"Dashboard" label. This is purely cosmetic (Layers 1+2 already enforce);
+the goal is **user clarity** — they don't try to drag, because the slot
+visibly isn't a regular workspace.
+
+Implementation: override `WorkspaceThumbnail` for the specific workspace
+via `WorkspacesView._workspaces[N-1]` patching, or simpler: hide it from
+the thumbnail strip entirely. The dashboard is accessed via gesture /
+shortcut (§14), not by clicking its thumbnail. **Default: hide from strip.**
+
+### Layer 4: workspace switcher (Super+Page_Up/Down)
+
+By default this cycles through `0..N`. We want Super+Page_Down on the last
+real workspace to **not** land on dashboard. Implementation: hook
+`Meta.KeyBindingAction.WORKSPACE_DOWN` and clamp target to `N-1`. (User
+still gets to dashboard via dedicated gesture/shortcut.)
+
+---
+
+## 7. Web container process
+
+### Window properties
+
+- Wayland app_id: `top.hangmanlab.dashward.container` (set via
+  `GLib.set_prgname` + `Gtk.Window.set_default_icon_name` — for Wayland
+  app_id detection on the Shell side, we identify by
+  `Meta.Window.get_gtk_application_id()`).
+- Title: `Dashward`.
+- Decorations: none (`set_decorated(false)`).
+- Fullscreen on the primary monitor.
+- Type hint: `NORMAL` (not `DOCK`, since dock windows skip workspaces).
+- Stickiness: **NOT sticky**; it must belong to the dashboard workspace
+  only.
+
+### Lifetime managed by `ContainerSupervisor`
+
+```
+spawn() → wait for window-created signal → match by app_id →
+move to dashboardWs (Layer 1 whitelist needed!) → record windowId →
+WebKit ready → first eval: bootstrap dashboard-runtime.js
+```
+
+Crash recovery: restart with exponential backoff (1s, 2s, 5s, 10s, then
+give up and surface error in panel indicator). The container's stderr
+streams to `~/.local/state/dashward/container.log`.
+
+### Visibility model
+
+The container window **always exists** on the dashboard workspace; user
+"opens dashboard" = switching to that workspace; "closes" = switching
+away. No need to map/unmap the window per visit — Mutter culls it from
+rendering when its workspace isn't active. This is the same model the
+overview uses for inactive workspace windows.
+
+**Exception**: on disable / shell-shutdown, container is gracefully asked
+to quit via DBus, then SIGTERM after 2s.
+
+---
+
+## 8. IPC layers
+
+### 8.1  Shell ↔ Container (DBus)
+
+Bus name: `top.hangmanlab.Dashward.Shell` (owned by the extension).
+Object path: `/top/hangmanlab/Dashward`. Interface methods:
+
+| Method | Direction | Purpose |
+|---|---|---|
+| `Ready()` | container → shell | container finished bootstrap; safe to enter edit mode |
+| `RequestEnterDashboard()` | container → shell | "switch to dashboard workspace" (used by `<a href>` clicks etc.) |
+| `RequestExitDashboard()` | container → shell | "switch to previous workspace" |
+| `GetSystemInfo() → a{sv}` | container → shell | brightness, battery, network, theme |
+| `WidgetIPC(widgetId, method, args)` | container → shell | namespaced widget-to-shell calls; routed by SDK |
+
+Signals (shell → container):
+
+| Signal | Payload | Purpose |
+|---|---|---|
+| `ThemeChanged` | `s` (`"light"`/`"dark"`) | system theme toggle |
+| `EditModeRequested` | `b` (enter/exit) | extension's panel button or keybind |
+| `SystemInfoChanged` | `a{sv}` (partial) | battery/network/etc updates |
+
+### 8.2  Container GJS ↔ WebKit page (UserContentManager)
+
+GJS-side container exposes script-message handlers:
+
+```js
+ucm.register_script_message_handler('shellCall');   // page → GJS
+ucm.register_script_message_handler('log');         // widget logs to GJS stderr
+```
+
+Page-side bridge:
+
+```js
+window.__dashShell__ = {
+  call(method, args) {
+    return new Promise((resolve, reject) => {
+      const id = nextId();
+      pending.set(id, { resolve, reject });
+      webkit.messageHandlers.shellCall.postMessage({ id, method, args });
+    });
+  }
+};
+```
+
+Reverse (GJS → page): `webView.evaluate_javascript(...)`.
+
+### 8.3  Page ↔ widget iframe
+
+`window.postMessage` with the SDK's wrapper. SDK injects into each iframe a
+preload script that exposes:
+
+```ts
+const dashboard = {
+  config: { get(): T, set(T): Promise<void>, onChange(cb) },
+  system: { onThemeChange(cb), getTheme(): 'light'|'dark', /* … */ },
+  lifecycle: { onMount(cb), onUnmount(cb), onVisibilityChange(cb) },
+  shell: { call(method, args): Promise<any> },  // gated by manifest permissions
+};
+```
+
+---
+
+## 9. Widget SDK
+
+Package: `@dashward/widget-sdk` (TypeScript, ESM, distributed as both
+source-for-bundle and as a CDN-style local file the runtime can load).
+
+### Authoring API
+
+```ts
+import { defineWidget } from '@dashward/widget-sdk';
+
+interface ClockConfig { hour12: boolean; showSeconds: boolean }
+
+export default defineWidget<ClockConfig>({
+  id: 'clock',
+  defaultConfig: { hour12: false, showSeconds: true },
+
+  mount(host, { config, system, lifecycle }) {
+    const root = host.attachShadow({ mode: 'open' });
+    root.innerHTML = `<div class="clock"></div>`;
+    const tick = () => { /* render */ };
+
+    const timer = setInterval(tick, 1000);
+    lifecycle.onUnmount(() => clearInterval(timer));
+
+    config.onChange(() => tick());
+    system.onThemeChange(t => root.host.dataset.theme = t);
+  },
+
+  configUI(host, { config }) {
+    // optional: render a settings panel for edit mode
+  },
+});
+```
+
+Surfaces:
+
+| API | Capability |
+|---|---|
+| `config.get/set/onChange` | persistent JSON config; auto-saved to `~/.local/share/dashward/widgets/<id>/config.json` |
+| `system.getTheme/onThemeChange` | follow Shell theme |
+| `system.getBattery/getNetwork/getBrightness` | shell DBus relay (requires manifest permission) |
+| `lifecycle.onMount/onUnmount/onVisibilityChange` | called by host when widget appears/disappears |
+| `shell.call(method, args)` | escape hatch to namespaced shell DBus calls (requires permission) |
+
+What's **not** exposed: file system, network sockets, arbitrary
+`Gio`/`Meta` access. Widgets that need that file an upstream issue.
+
+---
+
+## 10. Widget manifest
+
+`widget.json` at the widget root:
+
+```json
+{
+  "id": "clock",
+  "name": "Clock",
+  "version": "0.1.0",
+  "entry": "dist/index.js",
+  "icon": "icon.svg",
+  "size": { "w": 2, "h": 2, "minW": 1, "minH": 1, "maxW": 4, "maxH": 4 },
+  "permissions": ["timer"],
+  "configSchema": { "hour12": "boolean", "showSeconds": "boolean" }
+}
+```
+
+Permissions vocabulary v1: `timer`, `battery`, `network`, `brightness`,
+`notifications`. Permission grant is currently implicit (manifest declares
+it, runtime allows it); a user-visible grant UI is v2.
+
+Widget directory layout:
+
+```
+widgets/clock/
+├── widget.json
+├── src/
+│   └── index.ts
+├── dist/
+│   └── index.js          # esbuild-bundled, ESM, references SDK as bare import
+└── icon.svg
+```
+
+Install location at runtime:
+
+```
+~/.local/share/dashward/widgets/
+├── clock/                  # user's widgets (drop a dir here, runtime sees it)
+├── weather/
+└── …
+```
+
+Plus a built-in pack shipped with the extension at
+`extension/widgets-builtin/` (clock, calendar, system-stats, notes).
+
+---
+
+## 11. Layout & edit mode
+
+### Grid
+
+- 12 columns wide; rows grow vertically as needed.
+- Cell aspect ratio: 1:1 at the canonical size of `floor(viewportWidth /
+  12)` px. So a widget with `size: { w: 3, h: 2 }` occupies 3 cols × 2
+  rows = 3w × 2h grid cells, naturally responsive.
+- Widgets snap to grid; no free positioning in v1.
+
+### Storage
+
+User layout in `~/.local/share/dashward/layout.json`:
+
+```json
+{
+  "widgets": [
+    { "instanceId": "clock-1", "widgetId": "clock", "x": 0, "y": 0, "w": 2, "h": 2 },
+    { "instanceId": "weather-1", "widgetId": "weather", "x": 2, "y": 0, "w": 3, "h": 2 }
+  ]
+}
+```
+
+Multiple instances of the same widget are allowed (hence `instanceId` vs
+`widgetId`); each has its own config file scoped by `instanceId`.
+
+### Edit mode
+
+Triggered by:
+- Top-edge floating button (visible only when dashboard is active).
+- Keyboard `e` while on dashboard.
+- Long-press on any widget.
+
+In edit mode: widgets show resize handles + delete X; a "+" tray slides
+in from the right with available widgets; drag to add. Exit on `Esc` or
+clicking outside.
+
+Out of edit mode: widgets are passive; no drag/resize.
+
+---
+
+## 12. Theming
+
+- Container reads `org.gnome.desktop.interface color-scheme` at startup.
+- Shell subscribes to GSettings changes; pushes `ThemeChanged` DBus
+  signal to container; container does `document.documentElement.dataset.
+  theme = 'dark' | 'light'`.
+- SDK exposes `system.onThemeChange(cb)`; widgets style via CSS
+  `[data-theme="dark"]` attribute selectors (no JS theming, CSS does it).
+- Background is a configurable color + optional wallpaper image (defaults
+  to a desaturated copy of the user's desktop wallpaper).
+
+---
+
+## 13. Entry / exit UX
+
+Three ways in:
+
+| Path | Default binding | Implementation |
+|---|---|---|
+| Gesture | 4-finger swipe right past last workspace | hook `Shell.WorkspacesView._swipeTracker`; on `end` with target > N-1, jump to dashboard |
+| Keyboard | `Super+Grave` | `Meta.KeyBinding` via Shell.ActionMode.NORMAL |
+| Panel button | left-click Dashward indicator | `PanelMenu.Button` with custom icon |
+
+All three call the same `EntryUX.openDashboard()` which animates the
+workspace switch via existing Shell APIs.
+
+Exit: same gesture/shortcut/button toggles. Plus `Esc` while on dashboard
+(but only if no widget has focus capturing it).
+
+---
+
+## 14. Persistence & permissions
+
+Filesystem layout (all under `XDG_*` standards):
+
+```
+~/.local/share/dashward/
+├── layout.json                          # grid layout
+├── widgets/<instanceId>/config.json     # per-instance config
+└── widgets-installed/<widgetId>/        # user-installed widget bundles
+~/.local/state/dashward/
+├── saved-settings.json                  # gsettings snapshot for restore
+├── container.log
+└── extension.log
+~/.cache/dashward/                     # WebKit cache, regenerable
+```
+
+Nothing else outside the extension's install directory is touched.
+
+Permissions today: declared in manifest, allowed by runtime. v2: a
+first-run prompt per widget; revocable from edit mode.
+
+---
+
+## 15. Directory layout (the repo)
+
+```
+Dashward/
+├── extension/                            # GNOME Shell extension
+│   ├── metadata.json                     # GNOME-mandated, shell-version: ["48"]
+│   ├── src/
+│   │   ├── extension.ts                  # entry, exports default class
+│   │   ├── workspace-warden.ts
+│   │   ├── window-guard.ts
+│   │   ├── container-supervisor.ts
+│   │   ├── entry-ux.ts
+│   │   ├── dbus-service.ts
+│   │   └── prefs.ts                      # GNOME Extension prefs window
+│   ├── dist/                             # esbuild output, single extension.js
+│   ├── widgets-builtin/                  # ships with extension
+│   │   ├── clock/
+│   │   ├── calendar/
+│   │   ├── system-stats/
+│   │   └── notes/
+│   └── tsconfig.json
+│
+├── container/                            # WebKit kiosk process
+│   ├── src/
+│   │   ├── main.ts                       # GJS bootstrap
+│   │   ├── window.ts                     # GtkWindow + WebKitWebView
+│   │   ├── dbus-client.ts
+│   │   └── bridge.ts                     # UserContentManager wiring
+│   ├── runtime/                          # injected into the page
+│   │   ├── runtime.ts                    # grid host, edit mode, widget loader
+│   │   ├── dashboard.html
+│   │   └── styles.css
+│   └── dist/
+│
+├── sdk/                                  # @dashward/widget-sdk
+│   ├── src/
+│   │   ├── index.ts
+│   │   ├── define-widget.ts
+│   │   ├── config.ts
+│   │   ├── system.ts
+│   │   └── types.ts
+│   ├── package.json
+│   └── tsconfig.json
+│
+├── widgets/                              # example/3rd-party widgets dev tree
+│   └── …                                 # each is a self-contained TS project
+│
+├── proto/                                # DBus xml + shared TS types
+│   ├── shell.iface.xml
+│   └── types.ts
+│
+├── scripts/
+│   ├── dev-vm.sh                         # rsync to VM + reload extension
+│   ├── package.sh                        # produces .shell-extension.zip
+│   └── lint.sh
+│
+└── README.md
+```
+
+---
+
+## 16. Build chain
+
+Single root `package.json` + pnpm workspaces (`sdk`, `extension`,
+`container`, `widgets/*`).
+
+| Subproject | Bundler | Output |
+|---|---|---|
+| `sdk` | tsc | ESM, types, published as workspace dep |
+| `extension` | esbuild | single `dist/extension.js` (GNOME loads one file) |
+| `container` | esbuild | single `dist/main.js` (GJS-friendly ESM) |
+| each widget | esbuild | `dist/index.js`, SDK marked external (loaded by runtime) |
+
+GJS specifics (carried from your [[project_fabric_esm]] habit):
+- `"module": "NodeNext"` in tsconfig; explicit `.js` import suffixes; default-import any CJS dep.
+- `Gio` / `Meta` etc. imported via `gi://` URLs.
+- Type stubs: `@girs/gnome-shell`, `@girs/meta-16`, `@girs/gtk-3.0`,
+  `@girs/webkit2-4.1`.
+
+Dev cycle:
+
+```bash
+pnpm dev                # watches src/, rebuilds extension+container+widgets
+pnpm vm:sync            # rsync dist → VM, restart shell (or just kill container)
+```
+
+Inside the VM, a small helper script (`~/dashward-dev/reload.sh`):
+- Wayland: re-enable extension via `gnome-extensions disable && enable`
+  (a full Shell restart on Wayland requires logout — see §17).
+- Container-only changes: `pkill dashward-container`; supervisor
+  respawns.
+
+---
+
+## 17. Implementation phases
+
+| Phase | Deliverable | Acceptance |
+|---|---|---|
+| P0 | Repo skeleton, build chain, hello-world extension that logs on enable | extension shows in `gnome-extensions list` on VM |
+| P1 | WorkspaceWarden in isolation: appends/removes ws, position invariant | manual: enable → see N+1 workspaces; disable → back to N; mutations preserved |
+| P2 | WindowGuard | manual: try `wmctrl -r foo -t <dashboard>`, `super+shift+→`, overview drag — all bounce |
+| P3 | Container spawn + WebKit window + pin to dashboard | container window appears on dashboard ws only |
+| P4 | DBus + WebKit bridge round-trip | `dashboard.system.getTheme()` returns shell-side value |
+| P5 | Runtime: grid host, layout.json load/save, one builtin widget (clock) | clock renders, persists across enable cycles |
+| P6 | SDK + 3 more builtins (calendar, system-stats, notes) | each widget works in isolation; iframe crash containment verified |
+| P7 | Edit mode (add/remove/resize/rearrange) | layout edits persist; instances scoped configs |
+| P8 | Entry UX (gesture, shortcut, panel button) | all three paths open dashboard |
+| P9 | Polish: theming, animations, error surfaces | passes a manual checklist |
+| P10 | Stretch: WebKit 6.0 migration, multi-monitor, widget marketplace stub | post-v1 |
+
+**Critical**: P1, P2, P3 all run **only on the VM** ([[project_gridspaces_test_vm]]). The host's GNOME Shell never sees the extension until P9 and only via `gnome-extensions install` from a packaged zip — never via a `~/.local/share/gnome-shell/extensions/` symlink, which would survive logout and lock us out as in [[project_gridspaces_lockout]].
+
+---
+
+## 18. Risks & open questions
+
+### Risks
+
+| R# | Risk | Mitigation |
+|---|---|---|
+| R1 | Wayland shell restart requires logout — slow iteration | Container hot-reload covers 80%; for extension changes, accept the logout cost; consider a nested Wayland session (`mutter --nested`) for ultra-fast iteration in P5+ |
+| R2 | `dynamic-workspaces = false` is intrusive — user may rely on dynamic behavior | Restore on disable; document in README; consider an "advanced mode" later that keeps dynamic mode and races the GC, but **not v1** |
+| R3 | Overview shows the dashboard slot oddly when hidden from strip | Spend a P9 day on the cosmetic; if upstream `WorkspacesView` proves fragile across GNOME minor versions, fall back to "show the slot with a placeholder thumbnail" |
+| R4 | WebKitGTK 4.1 (GTK3) is older — long-term deprecation risk | Migration path: swap container to GTK4 + WebKitGTK 6.0 (install `gir1.2-webkit-6.0`). API surface is similar; isolated to `container/`, won't touch SDK or widgets |
+| R5 | Widget IPC permissions are honor-system in v1 | Acceptable for personal-use v1; v2 adds first-run prompt |
+| R6 | tiling-assistant or other extensions interact with workspace count | Document incompatibility list in README; test against default Ubuntu 25.04 extension set on VM during P1 |
+| R7 | A misbehaving extension load could crash shell on enable | Wrap entire `enable()` in try/catch; on first-throw, write error to `~/.local/state/dashward/extension.log` and bail rather than partial-init |
+
+### Open questions
+
+| Q# | Question | Status |
+|---|---|---|
+| Q1 | Project name | **Decided 2026-05-22: `Dashward`** |
+| Q2 | Where does the repo live? | **Decided 2026-05-22: local `~/dev/Dashward/`; remote = `https://git.hangman-lab.top/hzhang/Dashward.git` (Gitea on server.t0)** |
+| Q3 | Should widgets be able to span the entire dashboard (full-bleed)? | Open — no in v1; revisit |
+| Q4 | Multi-monitor: dashboard on primary only, or per-monitor? | Open — primary only in v1 |
+| Q5 | Should `Super+Grave` clash check happen at install or runtime? | Open — runtime check on `enable()`; if taken, fall back to no shortcut and warn |
+| Q6 | Widget config schema validation (Zod? JSON Schema? none?) | Open — none in v1; SDK trusts the widget's TS types |
+| Q7 | Do we ship a widget devtools page (live reload of widget under dev)? | Open — P10 stretch |
+
+---
+
+## 19. Naming, hosting & next actions
+
+**Codename:** Dashward (decided 2026-05-22).
+
+**Local working tree:** `~/dev/Dashward/`. Not under HangmanLab — Dashward is a personal tool, orthogonal to the lab estate.
+
+**Remote:** Gitea on `server.t0` at `https://git.hangman-lab.top/hzhang/Dashward.git`. Created when the P0 skeleton is ready to push. Per [[project-server-topology]] t0 hosts Git + auth; per [[project-local-sim-env]] the local-sim hijack of `*.hangman-lab.top` is **opt-in** (set up by `setup-sim.sh`) — when the hijack is off (default state), `git.hangman-lab.top` resolves to prod, which is what we want for pushing Dashward.
+
+Next concrete step:
+
+1. ✅ Q1, Q2 decided.
+2. Create the repo skeleton on disk (§15) — empty files, working `pnpm install`, no logic.
+3. Create the Gitea repo (via Gitea API or web UI) and `git push -u origin main`.
+4. P0 hello-world extension on the VM, prove the dev loop end-to-end.
+5. Begin P1.
+
+See [[project-gridspaces-lockout]] and [[project-gridspaces-test-vm]] for the testing discipline this project inherits.
diff --git a/container/esbuild.config.js b/container/esbuild.config.js
new file mode 100644
index 0000000..8d7cb54
--- /dev/null
+++ b/container/esbuild.config.js
@@ -0,0 +1,34 @@
+import esbuild from 'esbuild';
+
+const watch = process.argv.includes('--watch');
+
+const gjsOpts = {
+  entryPoints: ['src/main.ts'],
+  bundle: true,
+  outfile: 'dist/main.js',
+  format: 'esm',
+  target: 'firefox128',
+  platform: 'neutral',
+  external: ['gi://*', 'system', 'cairo', 'gettext'],
+  sourcemap: 'inline',
+  logLevel: 'info',
+};
+
+const runtimeOpts = {
+  entryPoints: ['runtime/runtime.ts'],
+  bundle: true,
+  outfile: 'dist/runtime.js',
+  format: 'esm',
+  target: 'es2022',
+  platform: 'browser',
+  sourcemap: 'inline',
+  logLevel: 'info',
+};
+
+if (watch) {
+  const c1 = await esbuild.context(gjsOpts);
+  const c2 = await esbuild.context(runtimeOpts);
+  await Promise.all([c1.watch(), c2.watch()]);
+} else {
+  await Promise.all([esbuild.build(gjsOpts), esbuild.build(runtimeOpts)]);
+}
diff --git a/container/package.json b/container/package.json
new file mode 100644
index 0000000..4bfa65e
--- /dev/null
+++ b/container/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "@dashward/container",
+  "version": "0.0.0",
+  "private": true,
+  "description": "WebKitGTK kiosk that hosts the Dashward dashboard page.",
+  "type": "module",
+  "scripts": {
+    "build": "node esbuild.config.js",
+    "dev": "node esbuild.config.js --watch"
+  },
+  "devDependencies": {
+    "@girs/gjs": "4.0.0-next.1",
+    "@girs/gtk-3.0": "3.24.0-next.1",
+    "@girs/webkit2-4.1": "4.1.0-next.1"
+  }
+}
diff --git a/container/runtime/dashboard.html b/container/runtime/dashboard.html
new file mode 100644
index 0000000..a5ef98a
--- /dev/null
+++ b/container/runtime/dashboard.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="utf-8" />
+  <title>Dashward</title>
+  <link rel="stylesheet" href="styles.css" />
+</head>
+<body>
+  <main id="grid"></main>
+  <script type="module" src="runtime.js"></script>
+</body>
+</html>
diff --git a/container/runtime/runtime.ts b/container/runtime/runtime.ts
new file mode 100644
index 0000000..771b3d1
--- /dev/null
+++ b/container/runtime/runtime.ts
@@ -0,0 +1,15 @@
+// Stub: page-side runtime (design §11).
+// Loads layout.json, instantiates widgets in iframes on the 12-column grid,
+// handles edit mode, persists changes via the shell bridge.
+
+declare global {
+  interface Window {
+    __dashShell__?: {
+      call(method: string, args?: unknown): Promise<unknown>;
+    };
+  }
+}
+
+console.info('[dashward-runtime] P0 stub loaded');
+
+export {};
diff --git a/container/runtime/styles.css b/container/runtime/styles.css
new file mode 100644
index 0000000..0cca405
--- /dev/null
+++ b/container/runtime/styles.css
@@ -0,0 +1,22 @@
+:root {
+  --bg: #f5f5f7;
+  --fg: #1c1c1e;
+  --grid-gap: 16px;
+}
+
+[data-theme="dark"] {
+  --bg: #0f0f12;
+  --fg: #f0f0f5;
+}
+
+html, body { margin: 0; padding: 0; height: 100%; background: var(--bg); color: var(--fg); }
+body { font-family: ui-sans-serif, system-ui, -apple-system, sans-serif; }
+
+#grid {
+  display: grid;
+  grid-template-columns: repeat(12, 1fr);
+  gap: var(--grid-gap);
+  padding: var(--grid-gap);
+  min-height: 100%;
+  box-sizing: border-box;
+}
diff --git a/container/src/bridge.ts b/container/src/bridge.ts
new file mode 100644
index 0000000..fcaac35
--- /dev/null
+++ b/container/src/bridge.ts
@@ -0,0 +1,4 @@
+// Stub: WebKit UserContentManager wiring (design §8.2).
+// Registers script-message handlers; evaluates JS into the page for shell→page push.
+
+export {};
diff --git a/container/src/dbus-client.ts b/container/src/dbus-client.ts
new file mode 100644
index 0000000..c52df18
--- /dev/null
+++ b/container/src/dbus-client.ts
@@ -0,0 +1,3 @@
+// Stub: DBus client for top.hangmanlab.Dashward.Shell (design §8.1).
+
+export {};
diff --git a/container/src/main.ts b/container/src/main.ts
new file mode 100644
index 0000000..84d091c
--- /dev/null
+++ b/container/src/main.ts
@@ -0,0 +1,10 @@
+// Stub: see design §7 — WebKit kiosk bootstrap.
+// Creates a GtkWindow, attaches a WebKitWebView, loads dashboard.html,
+// connects to the Shell DBus service.
+
+import GLib from 'gi://GLib';
+
+GLib.set_prgname('dashward-container');
+log('[dashward-container] P0 stub started');
+
+declare function log(msg: string): void;
diff --git a/container/src/window.ts b/container/src/window.ts
new file mode 100644
index 0000000..a57e664
--- /dev/null
+++ b/container/src/window.ts
@@ -0,0 +1,4 @@
+// Stub: GtkWindow + WebKitWebView setup (design §7).
+// Properties: undecorated, fullscreen on primary, app_id = top.hangmanlab.dashward.container.
+
+export {};
diff --git a/container/tsconfig.json b/container/tsconfig.json
new file mode 100644
index 0000000..d904f80
--- /dev/null
+++ b/container/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": ".",
+    "noEmit": true,
+    "types": []
+  },
+  "include": ["src/**/*", "runtime/**/*"]
+}
diff --git a/extension/esbuild.config.js b/extension/esbuild.config.js
new file mode 100644
index 0000000..a3a1de8
--- /dev/null
+++ b/extension/esbuild.config.js
@@ -0,0 +1,28 @@
+import esbuild from 'esbuild';
+
+const watch = process.argv.includes('--watch');
+
+const opts = {
+  entryPoints: ['src/extension.ts'],
+  bundle: true,
+  outfile: 'dist/extension.js',
+  format: 'esm',
+  target: 'firefox128',
+  platform: 'neutral',
+  external: [
+    'gi://*',
+    'resource:///*',
+    'system',
+    'cairo',
+    'gettext',
+  ],
+  sourcemap: 'inline',
+  logLevel: 'info',
+};
+
+if (watch) {
+  const ctx = await esbuild.context(opts);
+  await ctx.watch();
+} else {
+  await esbuild.build(opts);
+}
diff --git a/extension/metadata.json b/extension/metadata.json
new file mode 100644
index 0000000..a23e9f4
--- /dev/null
+++ b/extension/metadata.json
@@ -0,0 +1,9 @@
+{
+  "uuid": "dashward@hangman-lab.top",
+  "name": "Dashward",
+  "description": "A dedicated rightmost workspace for custom widgets, in the spirit of macOS Dashboard.",
+  "shell-version": ["48"],
+  "url": "https://git.hangman-lab.top/hzhang/Dashward",
+  "version": 1,
+  "settings-schema": "org.gnome.shell.extensions.dashward"
+}
diff --git a/extension/package.json b/extension/package.json
new file mode 100644
index 0000000..a163cb5
--- /dev/null
+++ b/extension/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "@dashward/extension",
+  "version": "0.0.0",
+  "private": true,
+  "description": "GNOME Shell extension that creates and guards the Dashward workspace.",
+  "type": "module",
+  "scripts": {
+    "build": "node esbuild.config.js",
+    "dev": "node esbuild.config.js --watch"
+  },
+  "devDependencies": {
+    "@girs/gnome-shell": "48.0.0-next.1",
+    "@girs/meta-16": "16.0.0-next.1",
+    "@girs/gtk-3.0": "3.24.0-next.1"
+  }
+}
diff --git a/extension/src/container-supervisor.ts b/extension/src/container-supervisor.ts
new file mode 100644
index 0000000..64968f2
--- /dev/null
+++ b/extension/src/container-supervisor.ts
@@ -0,0 +1,9 @@
+// Stub: see design §7 — web container process.
+// Spawn container via Gio.Subprocess; match its window by Wayland app_id;
+// pin to dashboard workspace; restart with exponential backoff on crash.
+
+export class ContainerSupervisor {
+  dispose(): void {
+    // graceful shutdown via DBus, then SIGTERM after 2s
+  }
+}
diff --git a/extension/src/dbus-service.ts b/extension/src/dbus-service.ts
new file mode 100644
index 0000000..86bdd35
--- /dev/null
+++ b/extension/src/dbus-service.ts
@@ -0,0 +1,8 @@
+// Stub: see design §8.1 — Shell ↔ Container DBus.
+// Bus: top.hangmanlab.Dashward.Shell, path /top/hangmanlab/Dashward.
+
+export class DBusService {
+  dispose(): void {
+    // unown bus name, disconnect handlers
+  }
+}
diff --git a/extension/src/entry-ux.ts b/extension/src/entry-ux.ts
new file mode 100644
index 0000000..aa7d13d
--- /dev/null
+++ b/extension/src/entry-ux.ts
@@ -0,0 +1,9 @@
+// Stub: see design §13 — entry/exit UX.
+// Three paths in: 4-finger swipe right past last workspace, Super+Grave,
+// panel button. All converge on openDashboard().
+
+export class EntryUX {
+  dispose(): void {
+    // remove gesture hook, keybinding, panel indicator
+  }
+}
diff --git a/extension/src/extension.ts b/extension/src/extension.ts
new file mode 100644
index 0000000..d9b90d5
--- /dev/null
+++ b/extension/src/extension.ts
@@ -0,0 +1,40 @@
+import { Extension } from 'resource:///org/gnome/shell/extensions/extension.js';
+
+import { WorkspaceWarden } from './workspace-warden.js';
+import { WindowGuard } from './window-guard.js';
+import { ContainerSupervisor } from './container-supervisor.js';
+import { EntryUX } from './entry-ux.js';
+import { DBusService } from './dbus-service.js';
+
+export default class DashwardExtension extends Extension {
+  private warden?: WorkspaceWarden;
+  private guard?: WindowGuard;
+  private container?: ContainerSupervisor;
+  private entry?: EntryUX;
+  private dbus?: DBusService;
+
+  enable(): void {
+    log('[Dashward] enable: P0 skeleton — components not wired yet');
+    this.warden = new WorkspaceWarden();
+    this.guard = new WindowGuard();
+    this.container = new ContainerSupervisor();
+    this.entry = new EntryUX();
+    this.dbus = new DBusService();
+  }
+
+  disable(): void {
+    log('[Dashward] disable');
+    this.dbus?.dispose();
+    this.entry?.dispose();
+    this.container?.dispose();
+    this.guard?.dispose();
+    this.warden?.dispose();
+    this.dbus = undefined;
+    this.entry = undefined;
+    this.container = undefined;
+    this.guard = undefined;
+    this.warden = undefined;
+  }
+}
+
+declare function log(msg: string): void;
diff --git a/extension/src/window-guard.ts b/extension/src/window-guard.ts
new file mode 100644
index 0000000..33b3f1c
--- /dev/null
+++ b/extension/src/window-guard.ts
@@ -0,0 +1,9 @@
+// Stub: see design §6 — window-defense rules.
+// Layer 1: window-added bounce-back. Layer 2: overview drop refusal.
+// Layer 3: hide from switcher strip. Layer 4: workspace switcher clamp.
+
+export class WindowGuard {
+  dispose(): void {
+    // disconnect all signals and restore patched prototypes
+  }
+}
diff --git a/extension/src/workspace-warden.ts b/extension/src/workspace-warden.ts
new file mode 100644
index 0000000..ab5572c
--- /dev/null
+++ b/extension/src/workspace-warden.ts
@@ -0,0 +1,9 @@
+// Stub: see design §5 — workspace lifecycle.
+// Responsibilities: snapshot gsettings, append the dashboard workspace, hold
+// position invariant on every workspace mutation, restore on disable.
+
+export class WorkspaceWarden {
+  dispose(): void {
+    // restore snapshotted settings, remove dashboard workspace
+  }
+}
diff --git a/extension/tsconfig.json b/extension/tsconfig.json
new file mode 100644
index 0000000..11fb0e8
--- /dev/null
+++ b/extension/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "noEmit": true,
+    "types": []
+  },
+  "include": ["src/**/*"]
+}
diff --git a/extension/widgets-builtin/clock/package.json b/extension/widgets-builtin/clock/package.json
new file mode 100644
index 0000000..a76b41d
--- /dev/null
+++ b/extension/widgets-builtin/clock/package.json
@@ -0,0 +1,13 @@
+{
+  "name": "@dashward/widget-clock",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --format=esm --outfile=dist/index.js --external:@dashward/widget-sdk",
+    "dev": "esbuild src/index.ts --bundle --format=esm --outfile=dist/index.js --external:@dashward/widget-sdk --watch"
+  },
+  "dependencies": {
+    "@dashward/widget-sdk": "workspace:*"
+  }
+}
diff --git a/extension/widgets-builtin/clock/src/index.ts b/extension/widgets-builtin/clock/src/index.ts
new file mode 100644
index 0000000..0e7af97
--- /dev/null
+++ b/extension/widgets-builtin/clock/src/index.ts
@@ -0,0 +1,41 @@
+import { defineWidget } from '@dashward/widget-sdk';
+
+interface ClockConfig {
+  hour12: boolean;
+  showSeconds: boolean;
+}
+
+export default defineWidget<ClockConfig>({
+  id: 'clock',
+  defaultConfig: { hour12: false, showSeconds: true },
+
+  mount(host, { config, lifecycle, system }) {
+    const root = host.element.attachShadow({ mode: 'open' });
+    root.innerHTML = `
+      <style>
+        :host { display: grid; place-items: center; }
+        .time { font: 600 clamp(2rem, 8vw, 5rem) ui-sans-serif, system-ui; }
+        :host([data-theme="dark"]) .time { color: #f0f0f0; }
+      </style>
+      <div class="time"></div>
+    `;
+    const el = root.querySelector('.time') as HTMLDivElement;
+
+    const render = () => {
+      const cfg = config.get();
+      el.textContent = new Date().toLocaleTimeString(undefined, {
+        hour12: cfg.hour12,
+        hour: '2-digit',
+        minute: '2-digit',
+        second: cfg.showSeconds ? '2-digit' : undefined,
+      });
+    };
+
+    const timer = setInterval(render, 1000);
+    render();
+    lifecycle.onUnmount(() => clearInterval(timer));
+
+    config.onChange(render);
+    system.onThemeChange(t => (host.element.dataset.theme = t));
+  },
+});
diff --git a/extension/widgets-builtin/clock/widget.json b/extension/widgets-builtin/clock/widget.json
new file mode 100644
index 0000000..9266a3e
--- /dev/null
+++ b/extension/widgets-builtin/clock/widget.json
@@ -0,0 +1,10 @@
+{
+  "id": "clock",
+  "name": "Clock",
+  "version": "0.0.0",
+  "entry": "dist/index.js",
+  "icon": "icon.svg",
+  "size": { "w": 2, "h": 2, "minW": 1, "minH": 1, "maxW": 4, "maxH": 4 },
+  "permissions": ["timer"],
+  "configSchema": { "hour12": "boolean", "showSeconds": "boolean" }
+}
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..ce12147
--- /dev/null
+++ b/package.json
@@ -0,0 +1,20 @@
+{
+  "name": "dashward",
+  "version": "0.0.0",
+  "private": true,
+  "description": "A dedicated rightmost workspace for custom widgets on Ubuntu/GNOME.",
+  "type": "module",
+  "scripts": {
+    "build": "pnpm -r build",
+    "dev": "pnpm -r --parallel dev",
+    "lint": "bash scripts/lint.sh",
+    "package": "bash scripts/package.sh"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "esbuild": "^0.24.0"
+  }
+}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
new file mode 100644
index 0000000..19f4cef
--- /dev/null
+++ b/pnpm-workspace.yaml
@@ -0,0 +1,6 @@
+packages:
+  - 'sdk'
+  - 'extension'
+  - 'container'
+  - 'widgets/*'
+  - 'extension/widgets-builtin/*'
diff --git a/proto/shell.iface.xml b/proto/shell.iface.xml
new file mode 100644
index 0000000..ee02f5b
--- /dev/null
+++ b/proto/shell.iface.xml
@@ -0,0 +1,38 @@
+<!-- DBus interface for the Dashward Shell extension.
+     Bus name: top.hangmanlab.Dashward.Shell
+     Object path: /top/hangmanlab/Dashward
+     See design §8.1. -->
+<node>
+  <interface name="top.hangmanlab.Dashward.Shell">
+
+    <method name="Ready"/>
+
+    <method name="RequestEnterDashboard"/>
+
+    <method name="RequestExitDashboard"/>
+
+    <method name="GetSystemInfo">
+      <arg type="a{sv}" direction="out" name="info"/>
+    </method>
+
+    <method name="WidgetIPC">
+      <arg type="s" direction="in" name="widgetId"/>
+      <arg type="s" direction="in" name="method"/>
+      <arg type="v" direction="in" name="args"/>
+      <arg type="v" direction="out" name="result"/>
+    </method>
+
+    <signal name="ThemeChanged">
+      <arg type="s" name="theme"/>
+    </signal>
+
+    <signal name="EditModeRequested">
+      <arg type="b" name="enter"/>
+    </signal>
+
+    <signal name="SystemInfoChanged">
+      <arg type="a{sv}" name="changed"/>
+    </signal>
+
+  </interface>
+</node>
diff --git a/proto/types.ts b/proto/types.ts
new file mode 100644
index 0000000..33875c1
--- /dev/null
+++ b/proto/types.ts
@@ -0,0 +1,42 @@
+// Shared types between extension, container, and SDK. Keep in sync with
+// shell.iface.xml. See design §8.
+
+export type Theme = 'light' | 'dark';
+
+export interface SystemInfo {
+  theme: Theme;
+  battery?: { level: number; charging: boolean };
+  network?: { connected: boolean; type: 'wifi' | 'ethernet' | 'cellular' | 'none' };
+  brightness?: number;
+}
+
+export interface LayoutEntry {
+  instanceId: string;
+  widgetId: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface LayoutFile {
+  widgets: LayoutEntry[];
+}
+
+export interface WidgetManifest {
+  id: string;
+  name: string;
+  version: string;
+  entry: string;
+  icon?: string;
+  size: { w: number; h: number; minW?: number; minH?: number; maxW?: number; maxH?: number };
+  permissions: WidgetPermission[];
+  configSchema?: Record<string, string>;
+}
+
+export type WidgetPermission =
+  | 'timer'
+  | 'battery'
+  | 'network'
+  | 'brightness'
+  | 'notifications';
diff --git a/scripts/dev-vm.sh b/scripts/dev-vm.sh
new file mode 100755
index 0000000..693f390
--- /dev/null
+++ b/scripts/dev-vm.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Stub: sync built extension + container to the ubuntu2504-test VM
+# (libvirt qemu:///session) and reload. See design §16.
+#
+# Usage: scripts/dev-vm.sh [--extension-only|--container-only]
+
+set -euo pipefail
+
+echo "TODO: implement after P0 ships."
+exit 1
diff --git a/scripts/lint.sh b/scripts/lint.sh
new file mode 100755
index 0000000..fc27a95
--- /dev/null
+++ b/scripts/lint.sh
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Stub: tsc --noEmit across all workspaces.
+set -euo pipefail
+exec pnpm -r exec tsc --noEmit
diff --git a/scripts/package.sh b/scripts/package.sh
new file mode 100755
index 0000000..7b69940
--- /dev/null
+++ b/scripts/package.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Stub: produce dashward@hangman-lab.top.shell-extension.zip suitable for
+# `gnome-extensions install`. Bundles extension/dist + metadata.json +
+# widgets-builtin + container/dist + container/runtime.
+
+set -euo pipefail
+
+echo "TODO: implement after P9 ships."
+exit 1
diff --git a/sdk/package.json b/sdk/package.json
new file mode 100644
index 0000000..b37e7cf
--- /dev/null
+++ b/sdk/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@dashward/widget-sdk",
+  "version": "0.0.0",
+  "description": "TypeScript SDK for authoring Dashward widgets.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch"
+  }
+}
diff --git a/sdk/src/define-widget.ts b/sdk/src/define-widget.ts
new file mode 100644
index 0000000..5b380f5
--- /dev/null
+++ b/sdk/src/define-widget.ts
@@ -0,0 +1,5 @@
+import type { WidgetDefinition } from './types.js';
+
+export function defineWidget<T>(def: WidgetDefinition<T>): WidgetDefinition<T> {
+  return def;
+}
diff --git a/sdk/src/index.ts b/sdk/src/index.ts
new file mode 100644
index 0000000..666988f
--- /dev/null
+++ b/sdk/src/index.ts
@@ -0,0 +1,11 @@
+export { defineWidget } from './define-widget.js';
+export type {
+  Theme,
+  WidgetHost,
+  WidgetContext,
+  WidgetDefinition,
+  ConfigApi,
+  SystemApi,
+  LifecycleApi,
+  ShellApi,
+} from './types.js';
diff --git a/sdk/src/types.ts b/sdk/src/types.ts
new file mode 100644
index 0000000..f74f99c
--- /dev/null
+++ b/sdk/src/types.ts
@@ -0,0 +1,41 @@
+export type Theme = 'light' | 'dark';
+
+export interface WidgetHost {
+  readonly element: HTMLElement;
+  readonly instanceId: string;
+}
+
+export interface ConfigApi<T> {
+  get(): T;
+  set(value: Partial<T>): Promise<void>;
+  onChange(handler: (value: T) => void): () => void;
+}
+
+export interface SystemApi {
+  getTheme(): Theme;
+  onThemeChange(handler: (theme: Theme) => void): () => void;
+}
+
+export interface LifecycleApi {
+  onMount(handler: () => void): void;
+  onUnmount(handler: () => void): void;
+  onVisibilityChange(handler: (visible: boolean) => void): () => void;
+}
+
+export interface ShellApi {
+  call<T = unknown>(method: string, args?: unknown): Promise<T>;
+}
+
+export interface WidgetContext<T> {
+  config: ConfigApi<T>;
+  system: SystemApi;
+  lifecycle: LifecycleApi;
+  shell: ShellApi;
+}
+
+export interface WidgetDefinition<T> {
+  id: string;
+  defaultConfig: T;
+  mount(host: WidgetHost, ctx: WidgetContext<T>): void;
+  configUI?(host: WidgetHost, ctx: WidgetContext<T>): void;
+}
diff --git a/sdk/tsconfig.json b/sdk/tsconfig.json
new file mode 100644
index 0000000..03ce790
--- /dev/null
+++ b/sdk/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}
diff --git a/tsconfig.base.json b/tsconfig.base.json
new file mode 100644
index 0000000..ad3e985
--- /dev/null
+++ b/tsconfig.base.json
@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noImplicitOverride": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "declaration": true,
+    "sourceMap": true
+  }
+}
diff --git a/widgets/.gitkeep b/widgets/.gitkeep
new file mode 100644
index 0000000..e69de29