@beyondwork/docx-react-component 1.0.0 → 1.0.1

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

@@ -1,274 +0,0 @@
-# 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

@@ -1,38 +0,0 @@
-# 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.