@beyondwork/docx-react-component 1.0.0

package/docs/superpowers/specs/2026-03-28-harness-control-bar-design.md

@@ -0,0 +1,274 @@
+# Harness Control Bar + Live Runtime Editor
+
+## Problem
+
+The `/demo` route renders a mock prototype with fixture data — no real editing, no real DOCX loading. The real runtime editor lives at `/editor/[sessionId]` behind a complex workspace wrapper. Users must navigate between disconnected routes to access harness features (upload, validation, certification) and the actual editor.
+
+## Solution
+
+Replace the root route (`/`) with a single page that renders:
+1. A **harness control bar** at the top — source picker, upload, validation, certification, session controls
+2. The **real `WordReviewEditor`** below — actual DOCX loading, editing, comments, revisions, export
+
+The prototype demo client (`prototype-client.tsx`) is retired. The mock fixture catalog (`demo-fixtures.ts`) remains available for unit tests but is no longer rendered.
+
+---
+
+## Architecture
+
+### Separation of Concerns
+
+```
+┌─────────────────────────────────────────────────────┐
+│  HarnessControlBar (harness-owned)                  │
+│  Source picker, upload, validate, export, cert,     │
+│  dark mode, reduced motion, session info            │
+├─────────────────────────────────────────────────────┤
+│  WordReviewEditor (runtime-owned)                   │
+│  Toolbar, document surface, review rail, status bar │
+│  No harness awareness — receives data via props     │
+└─────────────────────────────────────────────────────┘
+```
+
+The control bar and editor communicate through:
+- **Props down**: `externalDocSource` (DOCX bytes or snapshot), `currentUser`, `documentId`
+- **Ref up**: `WordReviewEditorRef` for imperative actions (exportDocx, getSnapshot)
+- **Events**: `onEvent` callback for dirty/save/export state changes
+
+The editor has zero knowledge of the harness. The harness has zero knowledge of document content.
+
+### Routes
+
+| Route | Behavior |
+|-------|----------|
+| `/` | Harness control bar + live `WordReviewEditor`. Default source: F01. |
+| `/editor/[sessionId]` | Same layout, locked to a specific session ID. |
+| `/demo` | Redirects to `/`. |
+| `/fixtures`, `/dashboard`, `/certification` | Redirect to `/?panel=<name>`. |
+| `/runs/[runId]` | Validation run detail (unchanged). |
+
+### Source Resolution
+
+On initial load, the page:
+1. Calls `getHarnessDashboardModel()` server-side
+2. Finds the default source (F01 if available, else first available fixture)
+3. Creates a session via `createHarnessSession(sourceId)`
+4. Passes the session's DOCX bytes to `WordReviewEditor` via `externalDocSource`
+
+When the user picks a different source from the control bar:
+1. Control bar calls `POST /api/demo-sessions` with `sourceId` or uploaded file
+2. Response includes new session record with source bytes
+3. Control bar updates the `externalDocSource` prop → editor reloads
+
+---
+
+## Harness Control Bar Component
+
+### File
+`services/react-word-editor/components/harness-control-bar.tsx`
+
+### Props
+```typescript
+interface HarnessControlBarProps {
+  sources: BrowseableSource[];
+  currentSession: HarnessSessionRecord;
+  currentSource: HarnessSourceRecord;
+  editorRef: React.RefObject<WordReviewEditorRef>;
+  onSessionChange: (session: HarnessSessionRecord, source: HarnessSourceRecord) => void;
+  onDarkModeChange: (dark: boolean) => void;
+  onReducedMotionChange: (reduced: boolean) => void;
+}
+```
+
+### Layout
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│ [📄 F01-basic-contract ▼]  [📤 Upload .docx]  │  Session: abc-123     │
+│ [✓ Validate] [↓ Export] [📋 Runs ▼] [🏅 Cert ▼] │  ☀/🌙  □ Reduced   │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### Left Cluster: Source Selection
+
+**Fixture/Scenario/Upload Picker** (Radix Select):
+- Groups: "Fixtures" (F01-F20), "Scenarios" (S01-S02), "Recent Uploads"
+- Each item shows: name, source kind badge, availability status
+- Selecting a source → creates new session → reloads editor
+- Unavailable sources (missing artifact files) shown as disabled
+
+**Upload Button**:
+- Hidden file input accepting `.docx`
+- On selection: POST FormData to `/api/demo-sessions`
+- Creates upload source + session in one step
+- Shows upload filename briefly, then switches to new session
+
+### Center: Session Info
+
+- Current session ID (truncated, monospace)
+- Source label (e.g., "F01-basic-contract.docx")
+- Dirty indicator dot (green=saved, amber=unsaved, red=error)
+
+### Right Cluster: Operator Controls
+
+**Validate Button**:
+- Calls `editorRef.current.exportDocx()` first to get current bytes
+- POSTs bytes to `/api/validate`
+- Shows inline result: "✓ Valid" or "✗ 3 findings"
+- Links to full validation run detail at `/runs/[runId]`
+
+**Export Button**:
+- Calls `editorRef.current.exportDocx()`
+- Triggers browser download of the `.docx` file
+- Shows brief "Exported" confirmation
+
+**Runs Dropdown** (Radix Select):
+- Lists recent validation runs for current session
+- Each entry: timestamp, valid/invalid badge, finding count
+- Selecting opens `/runs/[runId]` in new tab
+
+**Certification Dropdown** (Radix Select):
+- Options: "Word Desktop", "Word Web"
+- Each shows last certification status
+- Selecting opens inline certification form (pass/issues-found/notes)
+- Submits to `POST /api/certification`
+
+**Dark Mode Toggle**: Sun/Moon icon button, scopes `.dark` class to page root
+
+**Reduced Motion Toggle**: Checkbox, sets `data-reduced-motion` attribute
+
+### Styling
+
+Tailwind classes matching the editor theme. The control bar uses:
+- `h-9 bg-surface border-b border-border text-xs` — compact, consistent with editor chrome
+- Same CSS custom properties as the editor theme
+- Focus ring pattern: `focus-visible:ring-2 focus-visible:ring-accent`
+- Dark mode: inherits from the `.dark` class on the page root
+
+---
+
+## Page Component
+
+### File
+`services/react-word-editor/app/page.tsx`
+
+### Server Component
+```typescript
+export default async function MainPage({ searchParams }) {
+  const model = await getHarnessDashboardModel();
+  const defaultSource = findDefaultSource(model.browseableSources);
+  const session = await createHarnessSession(defaultSource.sourceId);
+  const sourceBytes = await readSourceBytes(defaultSource);
+
+  return (
+    <HarnessEditorPage
+      sources={model.browseableSources}
+      initialSession={session}
+      initialSource={defaultSource}
+      initialSourceBytes={sourceBytes}
+    />
+  );
+}
+```
+
+### Client Component (`HarnessEditorPage`)
+```typescript
+function HarnessEditorPage(props) {
+  const editorRef = useRef<WordReviewEditorRef>(null);
+  const [session, setSession] = useState(props.initialSession);
+  const [source, setSource] = useState(props.initialSource);
+  const [sourceBytes, setSourceBytes] = useState(props.initialSourceBytes);
+  const [darkMode, setDarkMode] = useState(false);
+  const [reducedMotion, setReducedMotion] = useState(false);
+
+  return (
+    <div className={darkMode ? "dark" : ""} data-reduced-motion={reducedMotion}>
+      <HarnessControlBar
+        sources={props.sources}
+        currentSession={session}
+        currentSource={source}
+        editorRef={editorRef}
+        onSessionChange={(newSession, newSource) => {
+          setSession(newSession);
+          setSource(newSource);
+          // fetch new source bytes, update sourceBytes state
+        }}
+        onDarkModeChange={setDarkMode}
+        onReducedMotionChange={setReducedMotion}
+      />
+      <WordReviewEditor
+        ref={editorRef}
+        documentId={session.documentId}
+        currentUser={{ userId: "operator", displayName: "Operator" }}
+        externalDocSource={{ kind: "docx", bytes: sourceBytes, sourceLabel: source.name }}
+        reviewMode="review"
+        onEvent={handleEditorEvent}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## Fixture Test Cases
+
+All 20+ fixtures from `test/fixtures/docx/` and 2 scenarios from `test/fixtures/scenarios/docx/` are exposed in the source picker dropdown:
+
+| ID | Name | Focus |
+|----|------|-------|
+| F01 | Basic Contract | supported-roundtrip baseline |
+| F02 | Headings & Styles | style preservation |
+| F03 | Legal Outline Numbering | numbering restart |
+| F04 | Restart Numbering Schedules | numbering restart edge cases |
+| F05 | Table-Heavy Agreement | preserve-only tables |
+| F06 | Merged Cells Signature Table | preserve-only table edge cases |
+| F07 | Inline Images Exhibit | image relationship handling |
+| F08 | Hyperlinks | hyperlink preservation |
+| F09 | Comments Single Paragraph | basic comment roundtrip |
+| F10 | Threaded Comments | threaded comments with resolution |
+| F11 | Redlines Basic | tracked change roundtrip |
+| F12 | Paragraph Joins/Splits | complex revision boundaries |
+| F13 | Comments on Deleted Text | anchor detachment |
+| F14 | Revisions in Tables/Lists | structural revisions |
+| F15 | Sections/Headers/Footers | preserve-only sections |
+| F16 | Footnotes/Endnotes | preserve-only notes |
+| F17 | Fields and TOC | preserve-only fields |
+| F20 | Unknown OOXML | alternate content preservation |
+| S01 | SOW Template | real-world scenario |
+| S02 | Licence Agreement Redlines | real-world redline scenario |
+
+Each fixture shows availability status (artifact exists on disk or not).
+
+---
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `app/page.tsx` | Rewrite: server component loading default session + client page |
+| `app/demo/page.tsx` | Redirect to `/` |
+| `components/harness-control-bar.tsx` | New: full operator control bar |
+| `components/harness-editor-page.tsx` | New: client component composing control bar + editor |
+
+## Files Unchanged
+
+- `WordReviewEditor.tsx` — no changes, receives data via props
+- `src/ui-tailwind/` — no changes, renders from RuntimeRenderSnapshot
+- All API routes — no changes, called by control bar
+- `lib/storage.ts`, `lib/harness-client.ts` — no changes, used by page server component
+
+---
+
+## Verification
+
+1. `/` loads with F01 fixture in the real editor
+2. Fixture picker dropdown shows all 20+ fixtures grouped by kind
+3. Selecting a different fixture reloads the editor with new document
+4. Upload button accepts `.docx` and opens it in the editor
+5. Validate button exports and validates, shows inline result
+6. Export button downloads the current document
+7. Dark mode toggle inverts the entire page (control bar + editor)
+8. Reduced motion toggle disables all animations
+9. All existing API routes continue to work
+10. `/editor/[sessionId]` route continues to work independently

package/docs/xlsx-react/README.md

@@ -0,0 +1,38 @@
+# XLSX Research Intake
+
+This directory is the research intake area for the future `xlsx` runtime.
+
+It is not the canonical source for shipped repo contracts. The repo now separates xlsx docs into two groups:
+
+- canonical planned docs under `docs/architecture/xlsx/`, `docs/reference/xlsx/`, and `docs/plans/xlsx/`
+- retained research papers in this folder when the source material is still useful but not yet the repo's final contract language
+
+## Promoted Into Canonical Planned Docs
+
+These research papers now have repo-aligned canonical destinations:
+
+| Research source | Canonical planned doc |
+| --- | --- |
+| [`shared-openxml-editor-platform-docx-xlsx.md`](./shared-openxml-editor-platform-docx-xlsx.md) | `docs/architecture/platform/shared-openxml-editor-platform.md` |
+| [`spreadsheet-editor-frontend-architecture.md`](./spreadsheet-editor-frontend-architecture.md) | `docs/architecture/xlsx/spreadsheet-editor-frontend-architecture.md` |
+| [`canonical-workbook-model-and-commands.md`](./canonical-workbook-model-and-commands.md) | `docs/architecture/xlsx/canonical-workbook-model-and-commands.md` |
+| [`xlsx-ooxml-compliance.md`](./xlsx-ooxml-compliance.md) | `docs/reference/xlsx/xlsx-ooxml-compliance.md` |
+| [`xlsx-fixture-corpus-and-certification-plan.md`](./xlsx-fixture-corpus-and-certification-plan.md) | `docs/plans/xlsx/xlsx-fixture-corpus-and-certification-plan.md` |
+
+## Retained Research Docs
+
+These papers remain useful research inputs, but they are not yet the repo's canonical planned contracts:
+
+| File | Current role |
+| --- | --- |
+| [`spreadsheet-editor-component-architecture.md`](./spreadsheet-editor-component-architecture.md) | Additional xlsx shell and source-layout exploration that still informs the planned architecture docs |
+| [`spreadsheet-editor-ux-guide.md`](./spreadsheet-editor-ux-guide.md) | Spreadsheet UX research and future product guidance |
+| [`agent-llm-interaction-layer-docx-xlsx.md`](./agent-llm-interaction-layer-docx-xlsx.md) | Future cross-vertical agent layer input; not part of the shipped docx API or first xlsx runtime contract |
+| [`xlsx-editor-research-pack.md`](./xlsx-editor-research-pack.md) | Umbrella source pack and rationale archive |
+
+## Cleanup Policy
+
+- Keep descriptive kebab-case filenames for retained research docs.
+- Promote only the papers that have been rewritten into repo-aligned canonical docs.
+- If a newly added raw imported report duplicates an already-cleaned paper, keep the cleaned paper and remove the raw duplicate.
+- Treat this folder as research intake, not as the source of shipped or guaranteed runtime behavior.