# ZoneGaze Code Plugin Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Replace the dummy ZoneGaze Code tab with an embedded Matrix plugin surface that connects to the local Code-OSS/code-server workspace while keeping native launch as fallback.

**Architecture:** Keep the VS Code OSS snapshot under `extensions/code/upstreams/vscode` as upstream source provenance. Add a focused `MatrixCodePluginPanel` implementation in `flow/web/src/components/extensions/` that renders ZoneGaze-owned branding, builds a local `127.0.0.1:3500` code-server iframe URL from the active workspace path, and preserves the existing native bridge open action.

**Tech Stack:** React 18, TypeScript, Tailwind CSS v4 utilities, Lucide React, Vitest/jsdom.

---

### Task 1: Red Test For Embedded Code Surface

**Files:**
- Modify: `flow/web/src/components/extensions/matrix-plugin-surfaces.test.tsx`

- [x] **Step 1: Write the failing test**

Add a `MatrixCodePluginPanel` import and a test that renders the Code panel with `workspacePath="/Users/example/project"`. Assert that the panel shows ZoneGaze Code, renders an iframe named `ZoneGaze Code workspace`, points at `http://127.0.0.1:3500`, includes the encoded workspace folder, shows upstream source provenance, and keeps an `Open ZoneGaze Code` fallback button.

- [x] **Step 2: Run test to verify it fails**

Run: `npm --prefix flow/web run test -- src/components/extensions/matrix-plugin-surfaces.test.tsx`

Expected: fail because the current `MatrixCodePluginPanel` has no iframe or upstream source provenance.

### Task 2: Implement Focused Code Plugin Panel

**Files:**
- Create: `flow/web/src/components/extensions/matrix-code-plugin-panel.tsx`
- Modify: `flow/web/src/components/extensions/matrix-plugin-surfaces.tsx`
- Modify: `flow/web/src/App.tsx`

- [x] **Step 1: Move Code panel into a focused file**

Create `matrix-code-plugin-panel.tsx` with a `MatrixCodePluginPanel` that accepts `workspacePath?: string | null`.

- [x] **Step 2: Build local IDE URL**

Use `new URL("http://127.0.0.1:3500/")`; when `workspacePath` is present, append `folder=<workspacePath>`. Do not use dynamic imports or Microsoft branding.

- [x] **Step 3: Render embedded plugin experience**

Render a ZoneGaze-branded header, a compact toolbar with an `Open ZoneGaze Code` fallback button, an iframe titled `ZoneGaze Code workspace`, and a small source card that references `extensions/code/upstreams/vscode` and Code-OSS as technical provenance.

- [x] **Step 4: Wire active workspace path**

In `App.tsx`, render `<MatrixCodePluginPanel workspacePath={workspacePath ?? navigationProjectPath ?? null} />`.

- [x] **Step 5: Run test to verify it passes**

Run: `npm --prefix flow/web run test -- src/components/extensions/matrix-plugin-surfaces.test.tsx`

Expected: pass.

### Task 3: Validation And Closeout

**Files:**
- Validate changed web files and docs only.

- [x] **Step 1: Run focused checks**

Run:
- `npm --prefix flow/web run test -- src/components/extensions/matrix-plugin-surfaces.test.tsx`
- `npm --prefix flow/web run typecheck`
- `npm --prefix flow/web run build`

- [ ] **Step 2: Browser QA**

Start/refresh the app at `http://127.0.0.1:4217/demo-website` from `development` after merge. Verify the Code plugin tab shows the embedded ZoneGaze Code surface without console errors or layout overlap.

- [ ] **Step 3: Git closeout**

Commit the task branch, merge back to `development`, push `origin/development`, remove the task worktree and branch if safe, and report any residual local worktrees or unmerged branches.
