Add design folder and README

design/canvas.md

@@ -0,0 +1,26 @@
+# Canvas Feature
+
+**Purpose**: Infinite zoomable/pannable workspace where krates live. Starts empty.
+
+**Layout**:
+- Full‑viewport `position: fixed; inset: 0` with background `#0b0e13`.
+- Two CSS grid overlays (fine `34px` rgba(125,145,175,.04), coarse `170px` rgba(125,145,175,.075)).
+- World layer: `<div>` sized `12000×8000px`, transformed via `translate(camX, camY) scale(zoom)`; all krates/windows are absolutely positioned children.
+- Top bar (`height ~56px`, `z-index:10`).
+- Bottom hint bar (`right:18px; bottom:18px`).
+- Zoom pill (`left:18px; bottom:18px`).
+- Minimap (`right:18px; bottom:64px; width:180px; height:120px`).
+
+**Navigation**:
+- Scroll wheel → pan.
+- Ctrl/⌘ + scroll → zoom.
+- Space + drag → pan (global capture, works even when a shell has focus).
+- Click empty canvas → open Spotlight.
+- Typing any key (when no input focused) → open Spotlight pre‑seeded with that character.
+
+**LOD**:
+- `zoom > 0.5` normal view (krates expanded, windows visible).
+- `zoom < 0.4` collapsed view (krates become 230 px overview cards, windows hidden).
+- Hysteresis: collapse @0.4, expand @0.5.
+
+**Camera fly**: on programmatic open, animate to center krate with `zoom:0.92` using `transform .52s cubic‑bezier(.22,.8,.28,1)`.

design/collection_window.md

@@ -0,0 +1,45 @@
+# Collection Window Feature
+
+**Purpose**: Provide an overview list or tree of objects within a namespace or category (e.g., "All Pods", "ns/payments").
+
+**Size**: Default 540 × 480 px.
+
+**Header**:
+- Title (e.g., "pods · ns/payments") with status summary badges (✓ N / ⚠ N / ✗ N).
+- Filter input (auto‑focused on open) using `IBM Plex Mono` at 12 px.
+- Keyboard hint (`↑↓ ⌥L/S/D/Y`).
+- Buttons to toggle **List** vs **Tree** view.
+
+**List Mode**:
+- Row shows shape glyph, name, relation tag (muted), health metric, type badge, view shortcuts (⌥L/S/D/Y), status dot.
+- Selected row: `background: accentDim; border-left: 2px solid accent`.
+- Hover row: `background: rgba(255,255,255,.04)`.
+- Sorting: degraded/failed first, then pending, then ready; alphabetical within groups.
+
+**Tree Mode**:
+- Hierarchical view similar to k9s "xray".
+- Workloads expand to show their pods; pods expand to show ConfigMaps, Secrets, PVCs.
+- Services/Ingresses expand to show targets.
+- Relation tags: `pod`, `configMap`, `secret`, `volume`, `selects`, `routes`, `used by`.
+- Indentation `20 px × depth` with L‑shaped connector border.
+- Filtering retains matching nodes **and** all ancestors so hierarchy stays readable.
+
+**Interaction**:
+- Typing filters instantly (no mode switch).
+- `↑/↓` moves selection highlight.
+- `⌥L/S/D/Y` opens the respective view for the selected row (same shortcuts as Spotlight).
+- `Enter` opens the default view for the selected row.
+- `Escape` blurs the filter input.
+- Mouse‑over the collection window and start typing focuses the filter input.
+- Resizing follows the same rules as other Detail Windows (sibling windows resize proportionally).
+
+**State** (`CollectionState` interface in design docs):
+```typescript
+interface CollectionState {
+  [wid: string]: {
+    search: string;
+    view: 'list' | 'tree';
+    sel: number; // selected row index
+  }
+}
+```

design/detail_window.md

@@ -0,0 +1,26 @@
+# Detail Window Feature
+
+**Purpose**: Shows a single view (YAML, Describe, Logs, Shell) for a Kubernetes object.
+
+**Size**: Default 380×362 px, resizable via bottom‑right corner handle. Sibling windows in the same column/row resize proportionally.
+
+**Header (36 px)**:
+- Shape glyph (type‑specific colour) + view label (uppercase, accent colour).
+- Object name + status badge.
+- Close button (×).
+- `cursor: grab` – drag to reposition within the canvas.
+- Double‑click → maximize to fill available space (below top bar, above bottom bar, side margins 22 px). Press `z` or double‑click again to restore.
+
+**Tab Bar**: YAML · Describe · Logs · Shell. Shell tab disabled for non‑exec objects (opacity 0.45).
+
+**Content area**: `<pre>` with `overflow:auto; height:286px; font-family:'IBM Plex Mono'; font-size:12px; line-height:1.65`. Custom scrollbar (8 px, rgba(140,165,200,.18)).
+
+**Keyboard focus**:
+- Mouse‑over window + type → focuses that window’s content (shell input when a Shell view is active).
+- Global `keydown` capture routes keys to the hovered window if it is a shell.
+
+**Maximize (`z` key or double‑click header)**:
+- Resize to `width = viewport.width - 44px`, `height = viewport.height - topBarHeight(68px) - bottomBarHeight(66px)`.
+- Set camera so the window fills the viewport (`zoom = 1`).
+
+**Secret YAML auto‑decode**: When rendering a Secret, base64‑decode all `data` values and display plaintext with a banner `⊙ secret values auto‑decoded`.

design/krate.md

@@ -0,0 +1,39 @@
+# Krate Feature
+
+**Purpose**: Named group of windows for a single Kubernetes object (or a collection) placed on the canvas.
+
+**Visual Container**:
+- Dashed border frame around all its windows: `border: 1px dashed rgba(color, .3); border-radius: 18px; background: rgba(color, .04)`.
+- Frame auto‑fits to the bounding box of its windows plus 30 px padding.
+- Header bar above the frame shows object name, status badge, window count, a drag handle, and a close (×) button.
+
+**Layout of Windows**:
+- Tiled in a 2‑column grid.
+- Column 0 offset `dx:0`, column 1 offset `dx:412`.
+- Row height `416 px`.
+- When a window is resized, sibling windows resize proportionally within the same column/row.
+- Windows never overlap – on drag release the krate checks other krate bounding boxes and nudges to avoid overlap (gentle snap).
+
+**Interactions**:
+- **Drag header** → move entire krate.
+- **Double‑click header** → toggle collapse/expand.
+- **Minimize button (—)** → collapse to overview card (230 px wide) showing name, view‑letter badges, status dot, window count, namespace.
+- **Double‑click collapsed card** → re‑expand and fly camera to the krate.
+- **Non‑overlapping placement**: on mouse release after a drag, the krate adjusts position to avoid overlapping other krates.
+- **Camera fly‑to** after summon: animates to centre the krate at `zoom: 0.92`.
+
+**State** (`Krate` interface in design docs):
+```typescript
+interface Krate {
+  id: string;
+  objId: string | null;        // null for collection krates
+  collScope?: { kind: 'namespace' | 'category', value: string };
+  label: string;
+  status: string;
+  color: string;               // derived from namespace palette
+  wx: number; wy: number;      // world position
+  minimized: boolean;
+  windows: Window[];
+  seq: number;                 // for generating window IDs
+}
+```

design/logs_window.md

@@ -0,0 +1,17 @@
+# Logs Window Feature
+
+**Purpose**: Live‑tail container logs for a pod/deployment/statefulset.
+
+**Implementation**:
+- Backend streams `kubectl logs --follow` over a WebSocket.
+- Front‑end displays lines in the same `<pre>` area as Detail Window.
+- Auto‑scroll to bottom when new lines arrive unless the user has manually scrolled up (detect `scrollTop + clientHeight < scrollHeight`).
+- Color‑code log levels: `ERROR` → `#ef6f6f`, `WARN` → `#e8b54a`, `INFO` → `#b9c6d8`.
+- No input handling – all keypresses are routed to the canvas (unless the user focuses the filter in a collection window).
+
+**Interaction**:
+- Click on a result in Spotlight or Collection with **Alt+L** to open a Logs window inside a new or existing Krate.
+- Resize like any Detail Window; sibling windows resize proportionally.
+- Double‑click header or press `z` to maximize.
+
+**State** (`Window` type `logs`).

design/shell_window.md

@@ -0,0 +1,18 @@
+# Shell Window Feature
+
+**Purpose**: Interactive pseudo‑terminal session inside a krate.
+
+**Implementation**:
+- Front‑end component uses **xterm.js** (or equivalent) for terminal UI.
+- Backend opens a WebSocket that proxies to `kubectl exec -it <pod> -n <ns> -- sh` (or the container's default shell).
+- Input handling: when the mouse is over the shell window, all keypresses are forwarded to the terminal; space does not trigger Spotlight.
+- Scroll wheel over the terminal scrolls its content; `Ctrl/⌘+scroll` still zooms the canvas.
+- No PTY needed on the server side beyond the exec stream; the WebSocket carries stdin/stdout/stderr.
+
+**Interaction**:
+- Click a result in Spotlight or Collection and press **Alt+S** to open a Shell window in a new/existing Krate.
+- Resize like any Detail Window; sibling windows resize proportionally.
+- Double‑click header or press `z` to maximize to the viewport.
+- The shell window obeys the global pan/zoom shortcuts (Space‑drag pans, Ctrl‑scroll zooms) when the cursor is inside it.
+
+**State** (`Window` type `shell`).

design/spotlight.md

@@ -0,0 +1,49 @@
+# Spotlight Feature
+
+**Purpose**: Global search overlay that lets users find any Kubernetes object, existing krates, namespaces, or collection categories, and open specific views.
+
+**Trigger**:
+- Click on empty canvas.
+- Type any printable key when no input is focused (pre‑seeds query).
+- `/` key opens an empty spotlight.
+
+**Layout**:
+- Full‑screen dark backdrop `rgba(7,9,13,.55)` with `backdrop‑filter: blur(2px)`.
+- Centered panel (max 660 px, 93 % viewport width) with background `rgba(16,20,28,.97)`, border `1px solid rgba(140,165,200,.26)`, border‑radius `14px`.
+- Input row (≈ 52 px high) containing:
+  - Search glyph `⌕` (accent color).
+  - Optional type‑filter pill.
+  - Text input (font‑size 18 px, IBM Plex Sans).
+  - Optional Tab‑ghost hint.
+- Horizontal **type chips** row (scrollable on narrow screens) for all object kinds (`pods`, `svc`, `deploy`, `secret`, `cm`, `sts`, …).
+- Results list (max‑height 48 vh, overflow‑auto) – each row shows:
+  - Shape glyph (type‑specific).
+  - Name.
+  - Subtext `type · ns/namespace`.
+  - CRD badge if applicable.
+  - Type badge.
+- **View chips** appear on the selected result only: `⌥L logs · ⌥S shell · ⌥D describe · ⌥Y yaml`. Views are limited to object capabilities (e.g., logs & shell only for pods, deployments, daemonsets, statefulsets).
+- Footer hint line.
+
+**Fuzzy Search Algorithm** (used in the prototype):
+- Score = character‑match score × 10 + type boost.
+- Type boost values: crd 60, deployment 50, statefulset 48, service 46, daemonset 44, ingress 42, secret 24, configmap 22, pvc 18, pod 16.
+- Character match: sequential chars, +3 for consecutive, +5 for word‑boundary start.
+- Top 8 results displayed.
+
+**Tab Quick‑Filter**:
+- Typing a type alias (`pod`, `svc`, `deploy`, etc.) shows a ghost hint `⇥ Pods`.
+- Press **Tab** to lock filter as a pill; Backspace removes it.
+- Tab also cycles through recently used type filters (most‑recent first).
+
+**Keyboard Shortcuts** (Alt/Option required):
+- `Alt+L` = open **Logs** view for selected result.
+- `Alt+S` = open **Shell** view.
+- `Alt+D` = open **Describe** view.
+- `Alt+Y` = open **YAML** view.
+- `Enter` = open default view (logs for pods, describe for workloads, yaml for config resources) and close spotlight.
+- `Esc` = close spotlight; if a krate was summoned it is placed on canvas.
+- `↑/↓` = navigate results.
+- `Tab` = apply/cycle type filter.
+
+**Auto‑Close**: after 500 ms of keyboard idle the spotlight auto‑closes and the camera flies to the newly created krate.

design/top_bar.md

@@ -0,0 +1,19 @@
+# Top Bar Feature
+
+**Purpose**: Persistent UI overlay providing cluster status, krate count, sync indicator, admin controls, and user roster.
+
+**Layout**:
+- `display: flex; align-items: center; padding: 13px 18px;` transparent over canvas.
+- **Left side**:
+  - **Logo pill** (`krates / yard`): background `rgba(14,18,25,.82)`, border `1px solid rgba(140,165,200,.18)`, border‑radius `9px`, padding `7px 12px`, backdrop‑filter `blur(6px)`. Diamond glyph with `clip-path: polygon(50% 0,100% 50%,50% 100%,0 50%)` in accent color.
+  - **Cluster pill**: shows cluster name, green health dot (`#4ad07a`) with `box-shadow: 0 0 8px #4ad07a`.
+  - **Krate count pill**: visible when krates exist.
+- **Right side**:
+  - **Synced pill**: pulsing accent dot + text "synced".
+  - **Admin button**: `◉ admin` – outlined when active, muted otherwise.
+  - **Roster avatars**: overlapping circles (`margin-left: -7px`), 30×30 px, colored per user, initials (★ for self).
+
+**Behavior**:
+- Stays fixed at top; does not scroll with canvas.
+- Clicking **Admin button** toggles the Admin Drawer.
+- Avatars show presence via Yjs awareness; hovering shows tooltip with username.