@beyondwork/docx-react-component 1.0.0

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

@@ -0,0 +1,677 @@
+# Harness Control Bar 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 root route with a live `WordReviewEditor` backed by real DOCX fixtures, with a harness control bar for source picking, upload, validation, certification, export, and theme controls.
+
+**Architecture:** Server component loads the dashboard model and creates a default session. Client component renders a `HarnessControlBar` above a `WordReviewEditor`. The control bar manages session lifecycle via API calls; the editor renders from `externalDocSource` props with zero harness knowledge.
+
+**Tech Stack:** Next.js 16 (App Router), React 19, Tailwind CSS 4, Radix UI (Select, Tooltip), Lucide React, existing harness API routes.
+
+---
+
+### Task 1: Create HarnessControlBar component
+
+**Files:**
+- Create: `services/react-word-editor/components/harness-control-bar.tsx`
+
+- [ ] **Step 1: Create the component file with source picker and upload**
+
+```tsx
+"use client";
+
+import { useId, useRef, useState, type ChangeEvent } from "react";
+import * as Select from "@radix-ui/react-select";
+import * as Tooltip from "@radix-ui/react-tooltip";
+import {
+  ChevronDown,
+  Download,
+  FileCheck2,
+  FileText,
+  Moon,
+  Sun,
+  Upload,
+} from "lucide-react";
+
+import type { WordReviewEditorRef } from "../../../src/api/public-types";
+
+export interface HarnessSourceOption {
+  sourceId: string;
+  sourceKind: "fixture" | "scenario" | "upload";
+  name: string;
+  sourceLabel: string;
+  available: boolean;
+  kindLabel: string;
+  primaryBadge?: string;
+}
+
+export interface HarnessSessionInfo {
+  sessionId: string;
+  documentId: string;
+  sourceId: string;
+  sourceLabel: string;
+}
+
+export interface HarnessControlBarProps {
+  sources: HarnessSourceOption[];
+  currentSession: HarnessSessionInfo;
+  editorRef: React.RefObject<WordReviewEditorRef | null>;
+  isDirty: boolean;
+  darkMode: boolean;
+  reducedMotion: boolean;
+  onSourceSelect: (sourceId: string) => void;
+  onUpload: (file: File) => void;
+  onDarkModeChange: (dark: boolean) => void;
+  onReducedMotionChange: (reduced: boolean) => void;
+}
+
+const focusRing =
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1 focus-visible:ring-offset-canvas";
+
+const kindColors: Record<string, string> = {
+  fixture: "text-insert bg-insert-soft",
+  scenario: "text-accent bg-accent-soft",
+  upload: "text-secondary bg-subtle",
+};
+
+export function HarnessControlBar(props: HarnessControlBarProps) {
+  const uploadId = useId();
+  const [validationResult, setValidationResult] = useState<string | null>(null);
+  const [isValidating, setIsValidating] = useState(false);
+  const [isExporting, setIsExporting] = useState(false);
+
+  const fixtures = props.sources.filter((s) => s.sourceKind === "fixture");
+  const scenarios = props.sources.filter((s) => s.sourceKind === "scenario");
+  const uploads = props.sources.filter((s) => s.sourceKind === "upload");
+
+  function handleUploadChange(event: ChangeEvent<HTMLInputElement>) {
+    const file = event.target.files?.[0];
+    if (file) props.onUpload(file);
+    event.target.value = "";
+  }
+
+  async function handleValidate() {
+    if (!props.editorRef.current || isValidating) return;
+    setIsValidating(true);
+    setValidationResult(null);
+    try {
+      const result = await props.editorRef.current.exportDocx();
+      const formData = new FormData();
+      formData.append("file", new Blob([result.bytes]), result.fileName);
+      formData.append("sessionId", props.currentSession.sessionId);
+      const response = await fetch("/api/validate", {
+        method: "POST",
+        body: formData,
+      });
+      const data = await response.json();
+      if (data.isValid) {
+        setValidationResult("Valid");
+      } else {
+        const count = (data.packageFindingCount ?? 0) + (data.sdkFindingCount ?? 0);
+        setValidationResult(`${count} finding${count !== 1 ? "s" : ""}`);
+      }
+    } catch {
+      setValidationResult("Error");
+    } finally {
+      setIsValidating(false);
+    }
+  }
+
+  async function handleExport() {
+    if (!props.editorRef.current || isExporting) return;
+    setIsExporting(true);
+    try {
+      const result = await props.editorRef.current.exportDocx();
+      const blob = new Blob([result.bytes], { type: result.mimeType });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = result.fileName;
+      a.click();
+      URL.revokeObjectURL(url);
+    } catch {
+      // Export failed — editor onError handles this
+    } finally {
+      setIsExporting(false);
+    }
+  }
+
+  return (
+    <div className="flex h-9 shrink-0 items-center gap-3 border-b border-border bg-surface px-3 text-xs">
+      {/* Source picker */}
+      <Select.Root
+        value={props.currentSession.sourceId}
+        onValueChange={props.onSourceSelect}
+      >
+        <Select.Trigger
+          className={`inline-flex items-center gap-1 rounded-md px-2 py-1 text-xs text-primary transition-colors hover:bg-surface-hover outline-none max-w-[240px] ${focusRing}`}
+        >
+          <FileText className="h-3 w-3 text-tertiary shrink-0" />
+          <Select.Value />
+          <Select.Icon>
+            <ChevronDown className="h-3 w-3 text-tertiary" />
+          </Select.Icon>
+        </Select.Trigger>
+        <Select.Portal>
+          <Select.Content
+            className="overflow-hidden rounded-lg bg-canvas shadow-lg ring-1 ring-border z-50 max-h-[400px]"
+            position="popper"
+            sideOffset={4}
+          >
+            <Select.Viewport className="p-1">
+              {fixtures.length > 0 && (
+                <Select.Group>
+                  <Select.Label className="px-2 py-1 text-[10px] font-semibold uppercase tracking-wider text-tertiary">
+                    Fixtures
+                  </Select.Label>
+                  {fixtures.map((s) => (
+                    <SourceItem key={s.sourceId} source={s} />
+                  ))}
+                </Select.Group>
+              )}
+              {scenarios.length > 0 && (
+                <Select.Group>
+                  <Select.Label className="px-2 py-1 text-[10px] font-semibold uppercase tracking-wider text-tertiary mt-1">
+                    Scenarios
+                  </Select.Label>
+                  {scenarios.map((s) => (
+                    <SourceItem key={s.sourceId} source={s} />
+                  ))}
+                </Select.Group>
+              )}
+              {uploads.length > 0 && (
+                <Select.Group>
+                  <Select.Label className="px-2 py-1 text-[10px] font-semibold uppercase tracking-wider text-tertiary mt-1">
+                    Uploads
+                  </Select.Label>
+                  {uploads.map((s) => (
+                    <SourceItem key={s.sourceId} source={s} />
+                  ))}
+                </Select.Group>
+              )}
+            </Select.Viewport>
+          </Select.Content>
+        </Select.Portal>
+      </Select.Root>
+
+      {/* Upload */}
+      <Tooltip.Provider delayDuration={400}>
+        <Tooltip.Root>
+          <Tooltip.Trigger asChild>
+            <label
+              className={`inline-flex items-center gap-1 rounded-md px-2 py-1 text-tertiary cursor-pointer hover:bg-surface-hover hover:text-primary transition-colors ${focusRing}`}
+            >
+              <Upload className="h-3 w-3" />
+              <span>Upload</span>
+              <input
+                accept=".docx"
+                className="sr-only"
+                id={uploadId}
+                type="file"
+                onChange={handleUploadChange}
+              />
+            </label>
+          </Tooltip.Trigger>
+          <Tooltip.Portal>
+            <Tooltip.Content
+              className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50"
+              sideOffset={6}
+            >
+              Upload a .docx file
+            </Tooltip.Content>
+          </Tooltip.Portal>
+        </Tooltip.Root>
+      </Tooltip.Provider>
+
+      {/* Divider */}
+      <div className="h-3 w-px bg-border" />
+
+      {/* Session info */}
+      <span className="text-tertiary truncate max-w-[180px]">
+        {props.currentSession.sourceLabel}
+      </span>
+      <span className="flex items-center gap-1.5">
+        <span
+          className={`inline-block h-1.5 w-1.5 rounded-full ${
+            props.isDirty ? "bg-comment" : "bg-insert"
+          }`}
+        />
+        <span className="text-tertiary">
+          {props.isDirty ? "Unsaved" : "Ready"}
+        </span>
+      </span>
+
+      {/* Spacer */}
+      <div className="flex-1" />
+
+      {/* Validate */}
+      <Tooltip.Provider delayDuration={400}>
+        <Tooltip.Root>
+          <Tooltip.Trigger asChild>
+            <button
+              type="button"
+              onClick={handleValidate}
+              disabled={isValidating}
+              className={`inline-flex items-center gap-1 rounded-md px-2 py-1 text-secondary hover:bg-surface-hover hover:text-primary transition-colors disabled:opacity-40 ${focusRing}`}
+            >
+              <FileCheck2 className="h-3 w-3" />
+              {isValidating
+                ? "Validating..."
+                : validationResult
+                  ? validationResult
+                  : "Validate"}
+            </button>
+          </Tooltip.Trigger>
+          <Tooltip.Portal>
+            <Tooltip.Content
+              className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50"
+              sideOffset={6}
+            >
+              Export and validate against OpenXML SDK
+            </Tooltip.Content>
+          </Tooltip.Portal>
+        </Tooltip.Root>
+
+        {/* Export */}
+        <Tooltip.Root>
+          <Tooltip.Trigger asChild>
+            <button
+              type="button"
+              onClick={handleExport}
+              disabled={isExporting}
+              className={`inline-flex items-center gap-1 rounded-md px-2 py-1 text-secondary hover:bg-surface-hover hover:text-primary transition-colors disabled:opacity-40 ${focusRing}`}
+            >
+              <Download className="h-3 w-3" />
+              Export
+            </button>
+          </Tooltip.Trigger>
+          <Tooltip.Portal>
+            <Tooltip.Content
+              className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50"
+              sideOffset={6}
+            >
+              Download edited .docx
+            </Tooltip.Content>
+          </Tooltip.Portal>
+        </Tooltip.Root>
+      </Tooltip.Provider>
+
+      {/* Divider */}
+      <div className="h-3 w-px bg-border" />
+
+      {/* Dark mode */}
+      <button
+        type="button"
+        onClick={() => props.onDarkModeChange(!props.darkMode)}
+        className={`inline-flex h-6 w-6 items-center justify-center rounded-md text-tertiary hover:bg-surface-hover transition-colors ${focusRing}`}
+        aria-label={props.darkMode ? "Light mode" : "Dark mode"}
+      >
+        {props.darkMode ? (
+          <Sun className="h-3.5 w-3.5" />
+        ) : (
+          <Moon className="h-3.5 w-3.5" />
+        )}
+      </button>
+
+      {/* Reduced motion */}
+      <label className="flex items-center gap-1.5 text-tertiary cursor-pointer select-none">
+        <input
+          checked={props.reducedMotion}
+          type="checkbox"
+          className="h-3 w-3 accent-accent"
+          onChange={(e) => props.onReducedMotionChange(e.target.checked)}
+        />
+        <span className="hidden sm:inline">Reduced motion</span>
+      </label>
+    </div>
+  );
+}
+
+function SourceItem(props: { source: HarnessSourceOption }) {
+  const { source } = props;
+  return (
+    <Select.Item
+      value={source.sourceId}
+      disabled={!source.available}
+      className={`flex cursor-pointer items-center gap-2 rounded-md px-2 py-1.5 text-xs text-primary outline-none data-[highlighted]:bg-surface data-[disabled]:opacity-40 data-[disabled]:cursor-not-allowed ${focusRing}`}
+    >
+      <Select.ItemText>{source.name}</Select.ItemText>
+      {source.primaryBadge && (
+        <span className="shrink-0 rounded px-1 py-px text-[10px] font-medium bg-primary text-white">
+          {source.primaryBadge}
+        </span>
+      )}
+      <span
+        className={`shrink-0 rounded px-1 py-px text-[10px] font-medium ${kindColors[source.sourceKind] ?? "text-secondary bg-subtle"}`}
+      >
+        {source.kindLabel}
+      </span>
+    </Select.Item>
+  );
+}
+```
+
+- [ ] **Step 2: Verify the component compiles**
+
+Run: `cd services/react-word-editor && ./node_modules/.bin/tsc --noEmit --pretty 2>&1 | grep harness-control-bar`
+Expected: No errors
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add services/react-word-editor/components/harness-control-bar.tsx
+git commit -m "feat(harness): add HarnessControlBar component"
+```
+
+---
+
+### Task 2: Create HarnessEditorPage client component
+
+**Files:**
+- Create: `services/react-word-editor/components/harness-editor-page.tsx`
+
+- [ ] **Step 1: Create the client component that composes control bar + editor**
+
+```tsx
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { WordReviewEditorRef, WordReviewEditorEvent } from "../../../src/api/public-types";
+import { WordReviewEditor } from "../../../src/ui/WordReviewEditor";
+import {
+  HarnessControlBar,
+  type HarnessSourceOption,
+  type HarnessSessionInfo,
+} from "./harness-control-bar";
+
+export interface HarnessEditorPageProps {
+  sources: HarnessSourceOption[];
+  initialSession: HarnessSessionInfo;
+  initialSourceBytes: number[];
+}
+
+export function HarnessEditorPage(props: HarnessEditorPageProps) {
+  const editorRef = useRef<WordReviewEditorRef>(null);
+  const [session, setSession] = useState<HarnessSessionInfo>(props.initialSession);
+  const [sourceBytes, setSourceBytes] = useState<Uint8Array>(
+    new Uint8Array(props.initialSourceBytes),
+  );
+  const [sourceRevision, setSourceRevision] = useState(0);
+  const [isDirty, setIsDirty] = useState(false);
+  const [darkMode, setDarkMode] = useState(false);
+  const [reducedMotion, setReducedMotion] = useState(false);
+
+  useEffect(() => {
+    document.documentElement.classList.toggle("dark", darkMode);
+  }, [darkMode]);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const sync = () => setReducedMotion(mq.matches);
+    sync();
+    mq.addEventListener?.("change", sync);
+    return () => mq.removeEventListener?.("change", sync);
+  }, []);
+
+  const switchToSource = useCallback(async (sourceId: string) => {
+    const response = await fetch("/api/demo-sessions", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ sourceId }),
+    });
+    if (!response.ok) return;
+    const data = await response.json();
+    const newSession: HarnessSessionInfo = {
+      sessionId: data.session.sessionId,
+      documentId: data.session.documentId,
+      sourceId: data.session.sourceId,
+      sourceLabel: data.session.sourceLabel,
+    };
+    const bytesResponse = await fetch(
+      `/api/sessions/${newSession.sessionId}/source`,
+    );
+    if (!bytesResponse.ok) return;
+    const bytes = new Uint8Array(await bytesResponse.arrayBuffer());
+    setSession(newSession);
+    setSourceBytes(bytes);
+    setSourceRevision((r) => r + 1);
+    setIsDirty(false);
+  }, []);
+
+  const handleUpload = useCallback(async (file: File) => {
+    const formData = new FormData();
+    formData.append("file", file);
+    const response = await fetch("/api/demo-sessions", {
+      method: "POST",
+      body: formData,
+    });
+    if (!response.ok) return;
+    const data = await response.json();
+    const newSession: HarnessSessionInfo = {
+      sessionId: data.session.sessionId,
+      documentId: data.session.documentId,
+      sourceId: data.session.sourceId,
+      sourceLabel: data.session.sourceLabel,
+    };
+    const bytesResponse = await fetch(
+      `/api/sessions/${newSession.sessionId}/source`,
+    );
+    if (!bytesResponse.ok) return;
+    const bytes = new Uint8Array(await bytesResponse.arrayBuffer());
+    setSession(newSession);
+    setSourceBytes(bytes);
+    setSourceRevision((r) => r + 1);
+    setIsDirty(false);
+  }, []);
+
+  const handleEditorEvent = useCallback((event: WordReviewEditorEvent) => {
+    if (event.type === "dirty_changed") {
+      setIsDirty(event.isDirty);
+    }
+  }, []);
+
+  return (
+    <div
+      className="flex h-screen flex-col bg-canvas text-primary"
+      data-reduced-motion={reducedMotion ? "true" : "false"}
+    >
+      <HarnessControlBar
+        sources={props.sources}
+        currentSession={session}
+        editorRef={editorRef}
+        isDirty={isDirty}
+        darkMode={darkMode}
+        reducedMotion={reducedMotion}
+        onSourceSelect={switchToSource}
+        onUpload={handleUpload}
+        onDarkModeChange={setDarkMode}
+        onReducedMotionChange={setReducedMotion}
+      />
+      <div className="flex-1 min-h-0">
+        <WordReviewEditor
+          ref={editorRef}
+          key={`${session.sessionId}-${sourceRevision}`}
+          documentId={session.documentId}
+          currentUser={{ userId: "operator", displayName: "Operator" }}
+          externalDocSource={{
+            kind: "docx",
+            bytes: sourceBytes,
+            sourceLabel: session.sourceLabel,
+          }}
+          externalDocumentRevision={`${sourceRevision}`}
+          reviewMode="review"
+          onEvent={handleEditorEvent}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 2: Verify the component compiles**
+
+Run: `cd services/react-word-editor && ./node_modules/.bin/tsc --noEmit --pretty 2>&1 | grep harness-editor-page`
+Expected: No errors
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add services/react-word-editor/components/harness-editor-page.tsx
+git commit -m "feat(harness): add HarnessEditorPage client component"
+```
+
+---
+
+### Task 3: Rewrite root route and redirect /demo
+
+**Files:**
+- Modify: `services/react-word-editor/app/page.tsx`
+- Modify: `services/react-word-editor/app/demo/page.tsx`
+
+- [ ] **Step 1: Rewrite app/page.tsx as server component that loads default session**
+
+```tsx
+import type { Metadata } from "next";
+
+import { getHarnessDashboardModel } from "../lib/harness-client";
+import {
+  createHarnessSession,
+  readHarnessSourceBytes,
+} from "../lib/storage";
+import { HarnessEditorPage } from "../components/harness-editor-page";
+
+export const dynamic = "force-dynamic";
+export const metadata: Metadata = {
+  title: "Word Review Editor",
+  description: "Live runtime editor with harness controls for fixtures, upload, validation, and certification.",
+};
+
+export default async function MainPage() {
+  const model = await getHarnessDashboardModel();
+
+  const sources = model.browseableSources.map(({ source, descriptor }) => ({
+    sourceId: source.sourceId,
+    sourceKind: source.sourceKind as "fixture" | "scenario" | "upload",
+    name: source.name,
+    sourceLabel: source.sourceLabel,
+    available: source.available,
+    kindLabel: descriptor.kindLabel,
+    primaryBadge: descriptor.primaryBadge,
+  }));
+
+  const defaultSource =
+    sources.find(
+      (s) => s.available && s.sourceKind === "fixture" && s.primaryBadge === "F01",
+    ) ||
+    sources.find((s) => s.available && s.sourceKind === "fixture") ||
+    sources.find((s) => s.available);
+
+  if (!defaultSource) {
+    return (
+      <main className="flex h-screen items-center justify-center bg-canvas text-primary">
+        <p className="text-secondary">No available sources found. Check fixture artifacts.</p>
+      </main>
+    );
+  }
+
+  const session = await createHarnessSession(defaultSource.sourceId);
+  const sourceBytes = await readHarnessSourceBytes(defaultSource.sourceId);
+
+  return (
+    <HarnessEditorPage
+      sources={sources}
+      initialSession={{
+        sessionId: session.sessionId,
+        documentId: session.documentId,
+        sourceId: session.sourceId,
+        sourceLabel: session.sourceLabel,
+      }}
+      initialSourceBytes={Array.from(sourceBytes)}
+    />
+  );
+}
+```
+
+- [ ] **Step 2: Update app/demo/page.tsx to redirect to /**
+
+```tsx
+import { redirect } from "next/navigation";
+
+export default function DemoPage() {
+  redirect("/");
+}
+```
+
+- [ ] **Step 3: Verify type-check passes**
+
+Run: `cd services/react-word-editor && ./node_modules/.bin/tsc --noEmit --pretty 2>&1 | grep -E "page\.tsx|harness-" | head -10`
+Expected: No errors (or only pre-existing ones)
+
+- [ ] **Step 4: Run tests to confirm no regressions**
+
+Run: `pnpm test 2>&1 | grep -E "^ℹ (pass|fail)"`
+Expected: Same pass/fail counts as before (no new failures)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add services/react-word-editor/app/page.tsx services/react-word-editor/app/demo/page.tsx
+git commit -m "feat(harness): wire root route to live runtime editor with control bar
+
+/ now loads the real WordReviewEditor with F01 fixture by default.
+Harness control bar provides source picker, upload, validate, export,
+dark mode, and reduced motion controls.
+/demo redirects to /."
+```
+
+---
+
+### Task 4: Clean up old prototype client reference
+
+**Files:**
+- Modify: `services/react-word-editor/app/demo/prototype-client.tsx` (keep file but it's no longer imported)
+
+- [ ] **Step 1: Verify prototype-client.tsx is no longer imported anywhere**
+
+Run: `grep -r "prototype-client\|DemoPrototypeClient" services/react-word-editor/app/ --include="*.tsx" --include="*.ts"`
+Expected: Only the file itself appears, no imports from page.tsx
+
+- [ ] **Step 2: Add deprecation comment to prototype-client.tsx**
+
+Add at the top of the file (line 1, before "use client"):
+```tsx
+/**
+ * @deprecated This prototype demo client is no longer rendered.
+ * The root route (/) now uses HarnessEditorPage with the real WordReviewEditor.
+ * This file is kept for reference only.
+ */
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add services/react-word-editor/app/demo/prototype-client.tsx
+git commit -m "chore: mark prototype-client.tsx as deprecated"
+```
+
+---
+
+### Task 5: Final verification
+
+- [ ] **Step 1: Full type-check**
+
+Run: `cd services/react-word-editor && ./node_modules/.bin/tsc --noEmit --pretty 2>&1 | grep -E "harness-control|harness-editor|page\.tsx" | head -10`
+Expected: No errors
+
+- [ ] **Step 2: Full test suite**
+
+Run: `pnpm test 2>&1 | grep -E "^ℹ (pass|fail)"`
+Expected: No new failures
+
+- [ ] **Step 3: Push**
+
+```bash
+git push
+```