Chore roadmap v010x shift (#76)

Co-authored-by: Jeffrey Smith <jasafpro@gmail.com>
Co-committed-by: Jeffrey Smith <jasafpro@gmail.com>

docs/DESIGN-panels.md

@@ -0,0 +1,743 @@
+# DESIGN: Panels — v0.10.x
+
+## Status: Proposed
+
+## Problem
+
+Packages export one rendering granularity today: a **surface** — a
+full-page application that owns `#extension-mount`. There is no way
+for a package to offer a lightweight, composable view of itself that
+another surface can pull in.
+
+Concrete example: the `notes` package provides a full note editor
+surface at `/s/notes`. When a user is in the `chat` surface and wants
+to reference their notes, the only option is to navigate away. There is
+no mechanism to embed a notes panel alongside chat, whether as a
+floating window, a docked sidebar, or a bottom strip.
+
+This forces users into one-thing-at-a-time workflows and prevents the
+"extensions extending extensions" composability story from reaching the
+UI layer. Slots and actions allow injection of buttons and menu items,
+but not entire companion views.
+
+Without kernel coordination, package authors who need this will roll
+their own floating containers, producing:
+
+- **Z-index wars** between packages and kernel overlays (Dialog at 1000,
+  debug at 9999, toast in between).
+- **Inconsistent drag/resize** behavior (touch support, bounds clamping,
+  accessibility).
+- **No position persistence** — panels reset on every navigation.
+- **No layout negotiation** — docked panels can't tell the host surface
+  to shrink.
+
+## Non-Goals
+
+- **Window management system.** This is not a tiling WM. The kernel
+  provides a small set of presentation modes (floating, docked). Complex
+  layouts are post-1.0 horizon.
+- **Cross-surface panel sharing at runtime.** A panel runs inside one
+  host surface's page context. It is not an iframe or a separate
+  browsing context.
+- **Panel-to-panel communication.** Panels communicate with their host
+  surface (and each other) via `sw.events`. No new IPC mechanism.
+- **Server-side panel rendering.** Panels are frontend-only. The kernel
+  resolves dependencies and serves JS; rendering happens in the browser.
+
+## What Already Exists
+
+**Three rendering tiers exist today; panels fill the gap between the
+first two:**
+
+| Tier | Scope | Example |
+|------|-------|---------|
+| **Surface** | Full-page app, owns `#extension-mount` | Notes editor, Chat, Admin |
+| *(gap)* | *Composable companion view* | *Notes reference panel in Chat* |
+| **Block renderer** | Inline content unit in markdown | Mermaid diagram, KaTeX formula |
+
+**Kernel primitives that panels build on:**
+
+- `sw.ui.Dialog` — centered modal with focus trap, backdrop, z-index 1000.
+- `sw.ui.Drawer` — slide-in side panel (left/right), backdrop, z-index 1000.
+- `sw.events` — pub/sub event bus, local and realtime. Already the
+  communication channel between surfaces and slot contributors.
+- `sw.storage` — per-user localStorage wrapper with namespaced keys.
+- `sw.slots` — named UI injection points with manifest declarations.
+- Manifest `depends` field — package dependency resolution at install time.
+
+**What panels add:** A second rendering granularity between surfaces and
+block renderers, with kernel-managed presentation modes and lifecycle.
+
+---
+
+## Architecture
+
+### 1. Three-Tier Rendering Hierarchy
+
+After this change, every package can export up to three things:
+
+```
+Surface   — full-page app, owns the mount, has shell topbar slots
+Panel     — composable view, kernel-managed container, presentation-agnostic
+Renderer  — inline content block (sw.renderers)
+```
+
+The key architectural property: **the panel component does not know its
+presentation mode.** It renders into whatever container the kernel
+provides. Floating, docked-right, docked-bottom — that is a shell/layout
+concern. The panel receives a mount element and a size. Nothing else.
+
+### 2. Manifest Schema
+
+#### Provider: `panels` field
+
+The package that provides a panel declares it in its manifest:
+
+```json
+{
+  "id": "notes",
+  "surfaces": ["/notes"],
+  "panels": {
+    "reference": {
+      "entry": "js/panels/reference.js",
+      "title": "Notes",
+      "icon": "📝",
+      "description": "Searchable note list with quick preview",
+      "min_width": 280,
+      "min_height": 200,
+      "default_width": 400,
+      "default_height": 350
+    }
+  }
+}
+```
+
+Panel IDs are namespaced: `<package_id>.<panel_key>`. The notes
+reference panel above is addressed as `notes.reference` everywhere
+in the SDK and in consumer manifests.
+
+A package may declare multiple panels:
+
+```json
+{
+  "id": "notes",
+  "panels": {
+    "reference": { "entry": "js/panels/reference.js", ... },
+    "graph":     { "entry": "js/panels/graph.js", ... }
+  }
+}
+```
+
+#### Consumer: `panels` dependency
+
+The consuming surface declares which panels it wants available:
+
+```json
+{
+  "id": "chat",
+  "surfaces": ["/chat"],
+  "panels": ["notes.reference"]
+}
+```
+
+This is a **soft dependency**: the panel is available if the providing
+package is installed and enabled. If not, `sw.panels.open()` returns
+`false` and the consuming surface can degrade gracefully (hide the
+button, show a tooltip explaining the missing package).
+
+This is distinct from `depends` (hard dependency — install fails without
+it). A consumer does not need the provider installed to function; the
+panel is an enhancement.
+
+### 3. Panel Entry Point Contract
+
+The panel JS module exports a single `mount` function. The kernel calls
+it with a DOM element and a context object. It returns a cleanup function.
+
+```js
+// notes/js/panels/reference.js
+const { html } = window;
+const { render } = preact;
+
+export function mount(el, ctx) {
+    // ctx.sw       — SDK instance
+    // ctx.params   — optional params from sw.panels.open()
+    // ctx.panelId  — 'notes.reference'
+    // ctx.close    — function to request close
+    // ctx.resize   — function(width, height) to request resize
+
+    render(html`<${NotesReference} sw=${ctx.sw} />`, el);
+
+    // Return cleanup
+    return () => render(null, el);
+}
+```
+
+**Rules:**
+
+- The panel must not assume any particular container size. Use CSS
+  `width: 100%; height: 100%` and let the kernel container control
+  dimensions.
+- The panel must not create its own overlay, backdrop, or drag handle.
+  The kernel wraps the panel in the appropriate chrome.
+- The panel must not set `z-index` on anything. The kernel manages
+  stacking.
+- The panel may use `ctx.close()` to request its own dismissal (e.g.
+  user clicks an "X" inside the panel content area).
+- The panel may use `ctx.resize(w, h)` to suggest a new size, but the
+  kernel may clamp or ignore the request.
+- Communication with the host surface is via `sw.events` — the same
+  bus surfaces and slot contributors already use.
+
+### 4. SDK API — `sw.panels`
+
+New SDK module: `src/js/sw/sdk/panels.js`
+
+```js
+export function createPanels(events, storage) {
+    const _registry = new Map();   // panelId → manifest entry
+    const _active   = new Map();   // panelId → { el, cleanup, mode, ... }
+
+    return {
+        /**
+         * Register a panel from manifest data. Called by the kernel
+         * during surface load — not by package code directly.
+         */
+        _register(panelId, manifest) { ... },
+
+        /**
+         * Open a panel. Lazy-loads the JS entry if not yet loaded.
+         *
+         * @param {string} panelId — e.g. 'notes.reference'
+         * @param {object} opts
+         * @param {string} opts.mode — 'floating' | 'docked-right' | 'docked-left' | 'docked-bottom'
+         * @param {object} opts.params — passed to mount(el, ctx)
+         * @param {number} opts.width — override default width
+         * @param {number} opts.height — override default height
+         * @returns {Promise<boolean>} — false if panel not available
+         */
+        async open(panelId, opts = {}) { ... },
+
+        /**
+         * Close a panel. Calls cleanup, removes container.
+         */
+        close(panelId) { ... },
+
+        /**
+         * Toggle open/close.
+         */
+        toggle(panelId, opts = {}) { ... },
+
+        /**
+         * Check if a panel is currently open.
+         */
+        isOpen(panelId) { ... },
+
+        /**
+         * Check if a panel is available (provider installed + enabled).
+         */
+        isAvailable(panelId) { ... },
+
+        /**
+         * List available panel IDs for the current surface.
+         */
+        list() { ... },
+
+        /**
+         * List currently open panel IDs.
+         */
+        active() { ... },
+    };
+}
+```
+
+**Exposed on `sw` as:**
+
+```js
+sw.panels.open('notes.reference', { mode: 'floating' });
+sw.panels.open('notes.reference', { mode: 'docked-right' });
+sw.panels.close('notes.reference');
+sw.panels.toggle('notes.reference');
+sw.panels.isOpen('notes.reference');    // boolean
+sw.panels.isAvailable('notes.reference'); // boolean
+sw.panels.list();     // ['notes.reference', 'notes.graph']
+sw.panels.active();   // ['notes.reference']
+```
+
+### 5. Presentation Modes
+
+#### Floating (v0.10.1)
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  ←  │ Chat                              │  🔔 │ 👤      │
+├──────────────────────────────────────────────────────────┤
+│                                                          │
+│         Host surface (interactive)                       │
+│                              ┌───────────────────┐       │
+│                              │ ≡ Notes       ─ ✕ │       │
+│                              │                   │       │
+│                              │  [panel content]  │       │
+│                              │                   │       │
+│                              │              ◢    │       │
+│                              └───────────────────┘       │
+│                                                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+- Draggable via title bar (pointer + touch events).
+- Resize via bottom-right handle.
+- Viewport bounds clamping — panel cannot be dragged fully offscreen
+  (at least 48px of title bar must remain visible).
+- No backdrop — host surface remains fully interactive.
+- Z-index above surfaces, below Dialog/Drawer overlays.
+- On focus or drag-start, panel gets next-z (multiple floating panels
+  stack correctly).
+- Escape key: configurable — close panel or do nothing (default: close).
+- Position and size persisted in `sw.storage` keyed by panel ID.
+
+**Title bar chrome (kernel-provided):**
+
+```
+┌────────────────────────────────────┐
+│ ≡  │ {icon} {title}        │ ─ ✕  │
+└────────────────────────────────────┘
+  │                             │  │
+  drag handle              minimize close
+```
+
+- **≡** Drag handle / grip indicator.
+- **─** Minimize: collapses to a small pill at the bottom of the viewport.
+  Click to restore. Minimized state persisted.
+- **✕** Close: calls cleanup, removes panel.
+- Title and icon from manifest.
+
+#### Docked (v0.10.2)
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  ←  │ Chat                              │  🔔 │ 👤      │
+├──────────────────────────────┬──┬────────────────────────┤
+│                              │▐▐│ 📝 Notes          ✕   │
+│    Host surface              │▐▐│                        │
+│    (shrinks to fit)          │▐▐│  [panel content]       │
+│                              │▐▐│                        │
+│                              │▐▐│                        │
+└──────────────────────────────┴──┴────────────────────────┘
+                              resize
+                              gutter
+```
+
+- Docked panels consume space from the host surface. The
+  `#extension-mount` area shrinks via CSS flex or grid.
+- Resize gutter between host and panel (drag to adjust split).
+- Three dock positions: right (default), left, bottom.
+- No z-index concerns — docked panels are in normal flow.
+- Split ratio persisted in `sw.storage` keyed by panel ID + mode.
+- Close button removes panel, host surface reclaims full width/height.
+
+#### Mode Transitions (v0.10.2)
+
+A floating panel can be dragged to a dock zone (edge highlight on
+hover). A docked panel's title bar can be dragged away to float.
+The panel component is never unmounted during a mode transition — only
+the wrapping container changes.
+
+The user controls presentation mode. Surfaces can suggest a default
+mode in `sw.panels.open()`, but the user's last-used mode (persisted)
+takes precedence.
+
+### 6. Z-Index Strategy
+
+Panels slot into the existing stacking context:
+
+| Layer | Z-Index | Contents |
+|-------|---------|----------|
+| Base | 0 | Surface content, docked panels (in flow) |
+| Floating panels | 100–199 | `sw.panels` floating mode (auto-incrementing) |
+| Shell overlays | 200–299 | Dropdowns, tooltips, menus |
+| Drawer | 1000 | `sw.ui.Drawer` |
+| Dialog | 1000 | `sw.ui.Dialog` + confirm/prompt |
+| Toast | 1100 | `sw.ui.toast` |
+| Debug | 9999 | Debug panel |
+
+Floating panels start at z-index 100. Each panel that receives focus
+or drag-start gets `max(current panel z-indexes) + 1`, capped at 199.
+If the cap is hit, all floating panels are renumbered starting from 100
+(maintaining relative order). This prevents unbounded z-index growth.
+
+When a Dialog or Drawer opens, floating panels remain visible beneath
+the overlay — they do not auto-hide. This preserves the "see while
+doing" property.
+
+### 7. Dependency Resolution + Loading
+
+**At install time:** The kernel validates that panel dependencies
+reference valid `<package>.<panel>` identifiers. Invalid references
+are warnings (soft deps), not errors.
+
+**At surface load time:**
+
+1. Kernel reads the surface's `panels` array from its manifest.
+2. For each declared panel, check if the providing package is installed
+   and enabled. Build the available panel list.
+3. Register available panels into `sw.panels._register()` with their
+   manifest metadata (entry path, title, icon, size constraints).
+4. Panel JS is **not** loaded yet — lazy loading on first
+   `sw.panels.open()`.
+
+**On `sw.panels.open(panelId)`:**
+
+1. If panel JS not yet loaded: `import()` the entry module from the
+   package's static asset path
+   (`/api/v1/ext/<package>/static/js/panels/<name>.js`).
+2. Call `module.mount(el, ctx)` where `el` is the content area of the
+   kernel-provided container (FloatingPanel or DockedPanel component).
+3. Store the cleanup function returned by `mount()`.
+4. Emit `panels.opened` event with `{ panelId, mode }`.
+
+**On `sw.panels.close(panelId)`:**
+
+1. Call stored cleanup function.
+2. Remove kernel container from DOM.
+3. Emit `panels.closed` event with `{ panelId }`.
+
+### 8. Panel Communication
+
+No new mechanism. Panels and their host surface share the same
+`sw.events` bus and `sw` SDK instance. Convention-based event
+namespacing:
+
+```js
+// Host surface requests the notes panel to show a specific note
+sw.emit('panel.notes.reference.show', { noteId: '...' });
+
+// Panel listens
+sw.on('panel.notes.reference.show', (data) => {
+    navigateToNote(data.noteId);
+});
+
+// Panel notifies the host that a note was selected
+sw.emit('panel.notes.reference.selected', { noteId: '...', title: '...' });
+
+// Host listens
+sw.on('panel.notes.reference.selected', (data) => {
+    insertNoteLink(data);
+});
+```
+
+The `params` object in `sw.panels.open()` provides initial state:
+
+```js
+sw.panels.open('notes.reference', {
+    mode: 'floating',
+    params: { folderId: 'inbox', highlight: noteId }
+});
+```
+
+Params are passed to `mount(el, ctx)` as `ctx.params`. This avoids
+the need for an event round-trip on first open.
+
+### 9. CSS
+
+New file: `src/css/panels.css`
+
+**Floating panel:**
+
+```css
+.sw-panel-floating {
+    position: fixed;
+    display: flex;
+    flex-direction: column;
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+    background: var(--bg-surface);
+    box-shadow: var(--shadow-lg);
+    overflow: hidden;
+    /* z-index set dynamically by JS */
+}
+
+.sw-panel-floating__titlebar {
+    display: flex;
+    align-items: center;
+    gap: var(--sp-2);
+    padding: var(--sp-2) var(--sp-3);
+    background: var(--bg-raised);
+    border-bottom: 1px solid var(--border);
+    cursor: grab;
+    user-select: none;
+    flex-shrink: 0;
+}
+
+.sw-panel-floating__titlebar:active {
+    cursor: grabbing;
+}
+
+.sw-panel-floating__title {
+    flex: 1;
+    font-size: 13px;
+    font-weight: 600;
+    color: var(--text);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.sw-panel-floating__actions {
+    display: flex;
+    gap: var(--sp-1);
+}
+
+.sw-panel-floating__action {
+    background: none;
+    border: none;
+    color: var(--text-3);
+    cursor: pointer;
+    padding: 2px 4px;
+    border-radius: var(--radius-sm);
+    font-size: 14px;
+    line-height: 1;
+}
+
+.sw-panel-floating__action:hover {
+    color: var(--text);
+    background: var(--bg-hover);
+}
+
+.sw-panel-floating__body {
+    flex: 1;
+    overflow: auto;
+}
+
+.sw-panel-floating__resize {
+    position: absolute;
+    bottom: 0;
+    right: 0;
+    width: 16px;
+    height: 16px;
+    cursor: nwse-resize;
+}
+
+/* Minimized pill */
+.sw-panel-pill {
+    position: fixed;
+    bottom: var(--sp-3);
+    display: flex;
+    align-items: center;
+    gap: var(--sp-2);
+    padding: var(--sp-2) var(--sp-3);
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    box-shadow: var(--shadow);
+    cursor: pointer;
+    font-size: 12px;
+    color: var(--text-2);
+    z-index: 100;
+}
+
+.sw-panel-pill:hover {
+    color: var(--text);
+    background: var(--bg-raised);
+}
+```
+
+**Docked panel:**
+
+```css
+.sw-panel-dock-container {
+    display: flex;
+    height: 100%;
+    overflow: hidden;
+}
+
+.sw-panel-dock-container--bottom {
+    flex-direction: column;
+}
+
+.sw-panel-dock-gutter {
+    flex-shrink: 0;
+    background: var(--bg-raised);
+    border: 1px solid var(--border);
+    cursor: col-resize;
+    width: 5px;
+}
+
+.sw-panel-dock-container--bottom .sw-panel-dock-gutter {
+    cursor: row-resize;
+    width: auto;
+    height: 5px;
+}
+
+.sw-panel-docked {
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    background: var(--bg-surface);
+}
+
+.sw-panel-docked__header {
+    display: flex;
+    align-items: center;
+    gap: var(--sp-2);
+    padding: var(--sp-2) var(--sp-3);
+    border-bottom: 1px solid var(--border);
+    background: var(--bg-raised);
+    flex-shrink: 0;
+}
+
+.sw-panel-docked__body {
+    flex: 1;
+    overflow: auto;
+}
+```
+
+**Touch targets (mobile):**
+
+```css
+@media (max-width: 768px) {
+    .sw-panel-floating__action {
+        min-width: 44px;
+        min-height: 44px;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+    }
+
+    .sw-panel-floating__titlebar {
+        padding: var(--sp-3) var(--sp-4);
+    }
+
+    .sw-panel-dock-gutter {
+        width: 10px;
+    }
+
+    .sw-panel-dock-container--bottom .sw-panel-dock-gutter {
+        height: 10px;
+    }
+}
+```
+
+### 10. Backend Changes
+
+**Minimal.** The kernel backend already serves extension static assets
+and reads manifests. Changes:
+
+1. **Manifest parsing** (`server/extensions/manifest.go`): Parse the
+   `panels` field from provider manifests (map of panel key → entry
+   metadata). Parse the `panels` field from consumer manifests (array
+   of panel ID strings). Store in the existing `PackageRecord` struct.
+
+2. **Surface load endpoint** (`/api/v1/surfaces/:id`): Include resolved
+   panel metadata in the response — for each panel declared by the
+   surface, include the provider's panel manifest entry (title, icon,
+   entry path, size constraints) if the provider is installed and
+   enabled. This lets the frontend `sw.panels._register()` at surface
+   boot without additional API calls.
+
+3. **Static asset serving**: Already works — panels are served from
+   the same package static path as surface JS
+   (`/api/v1/ext/<package>/static/...`).
+
+**No new tables.** No new migrations. Panel metadata lives in the
+existing manifest JSON stored in the packages table.
+
+### 11. Admin Visibility
+
+The admin packages page already shows package manifests. With panels:
+
+- The package detail view shows declared panels with their metadata.
+- The dependency view shows which surfaces consume which panels.
+- Panel availability warnings surface when a provider package is
+  disabled but consumers reference its panels.
+
+This falls out naturally from the existing manifest introspection —
+no new admin surfaces needed.
+
+---
+
+## Event Inventory
+
+| Event | Emitted by | Payload |
+|-------|-----------|---------|
+| `panels.opened` | Kernel (sw.panels) | `{ panelId, mode }` |
+| `panels.closed` | Kernel (sw.panels) | `{ panelId }` |
+| `panels.mode_changed` | Kernel (sw.panels) | `{ panelId, from, to }` |
+| `panels.focused` | Kernel (sw.panels) | `{ panelId }` |
+| `panel.<id>.*` | Convention (package code) | Package-defined |
+
+All panel events are `localOnly: true` — they do not broadcast over
+the WebSocket. Panels are a frontend-only concern.
+
+---
+
+## Persistence
+
+Panel state persisted in `sw.storage` (localStorage wrapper):
+
+| Key | Value | Scope |
+|-----|-------|-------|
+| `panel_pos_<panelId>` | `{ x, y, w, h }` | Floating position + size |
+| `panel_mode_<panelId>` | `'floating' \| 'docked-right' \| ...` | Last-used presentation mode |
+| `panel_split_<panelId>` | `{ ratio: 0.3 }` | Docked split ratio |
+| `panel_minimized_<panelId>` | `true` | Minimized state |
+
+Persisted per-user (sw.storage is already user-scoped). Cleared when
+the providing package is uninstalled.
+
+---
+
+## Version Plan
+
+| Version | Title | Scope |
+|---------|-------|-------|
+| v0.10.0 | Panel Manifest + Lifecycle | Manifest `panels` field (provider + consumer). Backend parsing. `sw.panels` SDK module (register, open, close, toggle, isOpen, isAvailable, list). Lazy JS loading pipeline. No presentation UI yet — panels render into a plain unstyled container for contract validation. |
+| v0.10.1 | FloatingPanel Primitive | `FloatingPanel` Preact component with drag, resize, minimize, z-index stacking, viewport bounds, position persistence. `panels.css` floating section. Touch support. |
+| v0.10.2 | Docked Panels + Mode Transitions | `DockedPanel` component. Layout negotiation (flex resize of `#extension-mount`). Resize gutter. Drag-to-dock / drag-to-float transitions. `panels.css` docked section. Split ratio persistence. |
+| v0.10.3 | Panel Communication Patterns | Event namespace conventions documented. `ctx.params` for initial state. SDK helper: `sw.panels.send(panelId, event, data)` as sugar over `sw.emit('panel.' + panelId + '.' + event, data)`. Panel communication section in extension developer guide. |
+| v0.10.4 | Reference Panel: Notes | Notes package ships `panels.reference` — searchable note list with quick preview. Chat declares it as a consumer. End-to-end proof: open notes panel in chat, select a note, insert link. Test runner coverage. |
+
+Each version independently CI-green. v0.10.0 is the foundation that
+all subsequent versions build on.
+
+---
+
+## Changeset Plan — v0.10.0
+
+| CS | Scope | Description |
+|----|-------|-------------|
+| CS-1 | Backend (Go) | Manifest parsing: `panels` field on provider + consumer manifests. `PackageRecord` struct update. Surface load endpoint includes resolved panel metadata. |
+| CS-2 | Frontend (JS) | `sw.panels` SDK module: `createPanels()`, register, open, close, toggle, isOpen, isAvailable, list, active. Lazy `import()` loader. Unstyled container mount. |
+| CS-3 | Frontend (JS) | SDK boot integration: wire `sw.panels` into SDK boot sequence. Register panels from `__MANIFEST__` surface data. |
+| CS-4 | Frontend (JS) | Panel lifecycle events: `panels.opened`, `panels.closed`, `panels.focused`. |
+| CS-5 | Tests | SDK test runner: panel registration, open/close lifecycle, lazy loading, availability checks, event emission. |
+
+---
+
+## Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Kernel primitive, not package-level | Z-index coordination, drag/resize consistency, layout negotiation, and position persistence are all kernel concerns. Multiple packages need this. |
+| Soft dependency (not `depends`) | Chat should work without notes installed. Panel availability is a runtime check, not an install-time requirement. |
+| Presentation-agnostic panel contract | `mount(el, ctx)` / cleanup is the entire API surface. Panels never know if they are floating or docked. This lets us add new modes without touching panel code. |
+| Lazy loading | Panel JS is not loaded until first `sw.panels.open()`. Surfaces that declare panels but the user never opens them pay zero cost. |
+| Event bus for communication | `sw.events` already exists and is the established pattern for cross-package communication. No new mechanism needed. |
+| No new backend tables | Panel metadata is manifest data stored in the existing packages table JSON. No schema changes. |
+| Z-index band 100–199 | Above surface content, below shell overlays and Dialog/Drawer. Renumber on cap to prevent unbounded growth. |
+| User controls mode, surface suggests | The surface can pass `mode: 'docked-right'` as a default, but the user's persisted mode preference wins. Users know their own workflow. |
+
+---
+
+## Future Considerations (post-v0.10.x)
+
+- **User-composable layouts.** Power users drag panels from different
+  packages into a persistent workspace layout. Requires a layout
+  persistence model beyond per-panel position.
+- **Panel marketplace metadata.** Panels become a discoverability
+  feature: "this package provides 2 surfaces and 3 panels."
+- **Multi-monitor.** Pop a floating panel into a separate browser
+  window via `window.open()` + `SharedWorker` for event bus. Very
+  post-1.0.
+- **Keyboard shortcuts.** `Ctrl+Shift+N` opens the notes panel.
+  Requires a keybinding registry (not yet a kernel primitive).