@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

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