@beyondwork/docx-react-component 1.0.0

package/services/react-word-editor/lib/editor-session-summary.test.mjs

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { countOpaqueFragmentsInSnapshot } from "./editor-session-summary.ts";
+
+function createSnapshot(documentId) {
+  return {
+    snapshotVersion: "persisted-editor-snapshot/1",
+    schemaVersion: "cds/1.0.0",
+    documentId,
+    docId: `${documentId}-doc`,
+    createdAt: "2026-03-27T00:00:00.000Z",
+    updatedAt: "2026-03-27T00:00:00.000Z",
+    savedAt: "2026-03-27T00:00:00.000Z",
+    editorBuild: "wave-9-editor-session-test",
+    canonicalDocument: {
+      schemaVersion: "cds/1.0.0",
+      docId: `${documentId}-doc`,
+      createdAt: "2026-03-27T00:00:00.000Z",
+      updatedAt: "2026-03-27T00:00:00.000Z",
+      metadata: {},
+      styles: {},
+      numbering: {},
+      media: {},
+      content: {
+        type: "doc",
+        children: [
+          {
+            type: "paragraph",
+            children: [{ type: "text", text: "Alpha" }],
+          },
+        ],
+      },
+      review: {
+        comments: {},
+        revisions: {},
+      },
+      preservation: {
+        opaqueFragments: {
+          "fragment:one": {
+            fragmentId: "fragment:one",
+          },
+          "fragment:two": {
+            fragmentId: "fragment:two",
+          },
+        },
+        packageParts: {},
+      },
+      diagnostics: {
+        warnings: [],
+        errors: [],
+      },
+    },
+    compatibility: {
+      reportVersion: "compatibility-report/1",
+      generatedAt: "2026-03-27T00:00:00.000Z",
+      blockExport: false,
+      featureEntries: [],
+      warnings: [],
+      errors: [],
+    },
+    warningLog: [],
+  };
+}
+
+test("opaque fragment summary counts keyed preserve-only fragments", () => {
+  assert.equal(countOpaqueFragmentsInSnapshot(createSnapshot("doc-editor-session")), 2);
+});

package/services/react-word-editor/lib/editor-session-summary.ts

@@ -0,0 +1,14 @@
+import type { PersistedEditorSnapshot } from "../../../src/api/public-types";
+
+export function countOpaqueFragmentsInSnapshot(
+  snapshot: PersistedEditorSnapshot,
+): number {
+  const opaqueFragments =
+    (
+      snapshot.canonicalDocument as {
+        preservation?: { opaqueFragments?: Record<string, unknown> };
+      }
+    ).preservation?.opaqueFragments ?? {};
+
+  return Object.keys(opaqueFragments).length;
+}

package/services/react-word-editor/lib/editor-session.ts

@@ -0,0 +1,228 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type {
+  PersistedEditorSnapshot,
+  SaveExportResult,
+  SaveSnapshotResult,
+} from "../../../src/api/public-types";
+import {
+  DOCX_MIME_TYPE,
+  getHarnessSession,
+  getHarnessSource,
+  getHarnessStorageAssumptions,
+  listHarnessExportsForSession,
+  listHarnessValidationRuns,
+  readHarnessSourceBytes,
+  saveHarnessExport,
+  type HarnessExportRecord,
+  type HarnessSessionRecord,
+  type HarnessSourceRecord,
+  type HarnessValidationRunRecord,
+} from "./storage.ts";
+import { countOpaqueFragmentsInSnapshot } from "./editor-session-summary.ts";
+
+const HARNESS_EDITOR_SESSION_STATE_VERSION = "harness-editor-session-state/1";
+
+type StoredHarnessEditorSnapshot = {
+  version: typeof HARNESS_EDITOR_SESSION_STATE_VERSION;
+  sessionId: string;
+  documentId: string;
+  sourceId: string;
+  savedAt: string;
+  isAutosave: boolean;
+  snapshot: PersistedEditorSnapshot;
+};
+
+export type HarnessEditorSessionSnapshotSummary = {
+  savedAt: string;
+  isAutosave: boolean;
+  warningCount: number;
+  errorCount: number;
+  featureEntryCount: number;
+  opaqueFragmentCount: number;
+  snapshot: PersistedEditorSnapshot;
+};
+
+export type HarnessEditorSessionState = {
+  session: HarnessSessionRecord;
+  source: HarnessSourceRecord;
+  sourceDownloadPath: string;
+  storage: ReturnType<typeof getHarnessStorageAssumptions>;
+  latestExport: HarnessExportRecord | null;
+  latestValidation: HarnessValidationRunRecord | null;
+  snapshot: HarnessEditorSessionSnapshotSummary | null;
+  controls: {
+    supportsSourceReload: true;
+    supportsSnapshotSave: true;
+    supportsExportPersist: true;
+    notes: string[];
+  };
+};
+
+function getEditorSessionStatePath(sessionId: string): string {
+  return path.join(
+    getHarnessStorageAssumptions().activeStorageDir,
+    "editor-sessions",
+    `${sessionId}.json`,
+  );
+}
+
+async function writeJsonAtomically(filePath: string, value: unknown): Promise<void> {
+  const directory = path.dirname(filePath);
+  await mkdir(directory, { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.tmp`;
+  await writeFile(tempPath, JSON.stringify(value, null, 2));
+  await rename(tempPath, filePath);
+}
+
+function toSnapshotSummary(
+  record: StoredHarnessEditorSnapshot,
+): HarnessEditorSessionSnapshotSummary {
+  return {
+    savedAt: record.savedAt,
+    isAutosave: record.isAutosave,
+    warningCount: record.snapshot.warningLog.length,
+    errorCount: record.snapshot.compatibility.errors.length,
+    featureEntryCount: record.snapshot.compatibility.featureEntries.length,
+    opaqueFragmentCount: countOpaqueFragmentsInSnapshot(record.snapshot),
+    snapshot: record.snapshot,
+  };
+}
+
+export async function readHarnessEditorSessionSnapshot(
+  sessionId: string,
+): Promise<HarnessEditorSessionSnapshotSummary | null> {
+  try {
+    const raw = await readFile(getEditorSessionStatePath(sessionId), "utf8");
+    const parsed = JSON.parse(raw) as StoredHarnessEditorSnapshot;
+
+    if (parsed.version !== HARNESS_EDITOR_SESSION_STATE_VERSION) {
+      return null;
+    }
+
+    return toSnapshotSummary(parsed);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+export async function loadHarnessEditorSessionState(
+  sessionId: string,
+): Promise<HarnessEditorSessionState | null> {
+  const session = await getHarnessSession(sessionId);
+
+  if (!session) {
+    return null;
+  }
+
+  const [source, exports, validationRuns, snapshot] = await Promise.all([
+    getHarnessSource(session.sourceId),
+    listHarnessExportsForSession(sessionId),
+    listHarnessValidationRuns({ sessionId, limit: 1 }),
+    readHarnessEditorSessionSnapshot(sessionId),
+  ]);
+
+  if (!source) {
+    return null;
+  }
+
+  return {
+    session,
+    source,
+    sourceDownloadPath: `/api/sessions/${sessionId}/source`,
+    storage: getHarnessStorageAssumptions(),
+    latestExport: exports[0] ?? null,
+    latestValidation: validationRuns[0] ?? null,
+    snapshot,
+    controls: {
+      supportsSourceReload: true,
+      supportsSnapshotSave: true,
+      supportsExportPersist: true,
+      notes: [
+        "This route reports internal pilot controls only. Manual Word reopen evidence still lives outside the mounted editor.",
+        "The mounted editor runtime remains package-backed and schema-driven, so later table and font work can grow without changing the session contract shape.",
+      ],
+    },
+  };
+}
+
+export async function saveHarnessEditorSessionSnapshot(input: {
+  sessionId: string;
+  snapshot: PersistedEditorSnapshot;
+  isAutosave?: boolean;
+}): Promise<SaveSnapshotResult & { snapshot: HarnessEditorSessionSnapshotSummary }> {
+  const session = await getHarnessSession(input.sessionId);
+
+  if (!session) {
+    throw new Error(`Harness session ${input.sessionId} does not exist.`);
+  }
+
+  const savedAt = input.snapshot.savedAt || new Date().toISOString();
+  const record: StoredHarnessEditorSnapshot = {
+    version: HARNESS_EDITOR_SESSION_STATE_VERSION,
+    sessionId: session.sessionId,
+    documentId: session.documentId,
+    sourceId: session.sourceId,
+    savedAt,
+    isAutosave: input.isAutosave ?? false,
+    snapshot: {
+      ...input.snapshot,
+      savedAt,
+    },
+  };
+
+  await writeJsonAtomically(getEditorSessionStatePath(session.sessionId), record);
+
+  return {
+    savedAt,
+    snapshot: toSnapshotSummary(record),
+  };
+}
+
+export async function persistHarnessEditorSessionExport(input: {
+  sessionId: string;
+  fileName: string;
+  mimeType?: string;
+  bytes: Uint8Array;
+  reason?: string;
+}): Promise<SaveExportResult & { exportRecord: HarnessExportRecord }> {
+  const exportRecord = await saveHarnessExport({
+    sessionId: input.sessionId,
+    fileName: input.fileName,
+    mimeType: input.mimeType || DOCX_MIME_TYPE,
+    bytes: input.bytes,
+    reason: input.reason,
+  });
+
+  return {
+    savedAt: exportRecord.createdAt,
+    exportRecord,
+  };
+}
+
+export async function readHarnessEditorSessionSource(
+  sessionId: string,
+): Promise<{ session: HarnessSessionRecord; source: HarnessSourceRecord; bytes: Uint8Array } | null> {
+  const session = await getHarnessSession(sessionId);
+
+  if (!session) {
+    return null;
+  }
+
+  const source = await getHarnessSource(session.sourceId);
+
+  if (!source) {
+    return null;
+  }
+
+  return {
+    session,
+    source,
+    bytes: await readHarnessSourceBytes(source.sourceId),
+  };
+}

package/services/react-word-editor/lib/exports-route.test.mjs

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { POST } from "../app/api/exports/route.ts";
+import {
+  HARNESS_MAX_UPLOAD_BYTES,
+  getHarnessStorageAssumptions,
+} from "./storage.ts";
+
+test("exports route rejects oversized multipart requests before parsing the body", async () => {
+  const response = await POST(
+    new Request("http://localhost/api/exports", {
+      method: "POST",
+      headers: {
+        "content-type": "multipart/form-data; boundary=----cursor-boundary",
+        "content-length": String(HARNESS_MAX_UPLOAD_BYTES + 1),
+      },
+      body: "",
+    }),
+  );
+
+  assert.equal(response.status, 413);
+  assert.equal(response.headers.get("cache-control"), "no-store");
+
+  const payload = await response.json();
+  const expectedStorage = JSON.parse(JSON.stringify(getHarnessStorageAssumptions()));
+  assert.deepEqual(payload, {
+    error: "file_too_large",
+    detail: `Requests larger than ${Math.round(HARNESS_MAX_UPLOAD_BYTES / (1024 * 1024))} MiB are rejected before upload parsing.`,
+    storage: expectedStorage,
+  });
+});

package/services/react-word-editor/lib/harness-client.ts

@@ -0,0 +1,347 @@
+import {
+  getHarnessExport,
+  getHarnessHealthSnapshot,
+  getHarnessSession,
+  getHarnessSource,
+  getHarnessValidationRun,
+  listHarnessExportsForSession,
+  listHarnessSessions,
+  listHarnessSources,
+  listHarnessValidationRuns,
+  readHarnessValidationReport,
+  type HarnessExportRecord,
+  type HarnessSessionRecord,
+  type HarnessSourceRecord,
+  type HarnessValidationReport,
+  type HarnessValidationRunRecord,
+} from "./storage.ts";
+
+type ReviewStatusTone = "neutral" | "success" | "warning";
+
+export type HarnessSourceDescriptor = {
+  id: string;
+  kind: HarnessSourceRecord["sourceKind"];
+  kindLabel: string;
+  releaseLabel: string;
+  releaseTone: ReviewStatusTone;
+  primaryBadge?: string;
+  secondaryBadge?: string;
+  note?: string;
+};
+
+export type HarnessValidationSnapshotSummary = {
+  runId?: string;
+  label: string;
+  detail: string;
+  tone: ReviewStatusTone;
+  findingCount: number;
+};
+
+export type HarnessExportSnapshotSummary = {
+  exportId?: string;
+  label: string;
+  detail: string;
+};
+
+export type HarnessActivitySummary = {
+  exports: number;
+  validationRuns: number;
+  latestExport: HarnessExportSnapshotSummary;
+  latestValidation: HarnessValidationSnapshotSummary;
+};
+
+export type HarnessDashboardModel = {
+  health: Awaited<ReturnType<typeof getHarnessHealthSnapshot>>;
+  fixtures: HarnessSourceRecord[];
+  scenarios: HarnessSourceRecord[];
+  uploads: HarnessSourceRecord[];
+  browseableSources: Array<{
+    source: HarnessSourceRecord;
+    descriptor: HarnessSourceDescriptor;
+  }>;
+  recentUploads: HarnessSourceRecord[];
+  recentSessions: Array<{
+    session: HarnessSessionRecord;
+    source?: HarnessSourceRecord;
+    latestExport?: HarnessExportRecord;
+    latestValidationRun?: HarnessValidationRunRecord;
+    descriptor: HarnessSourceDescriptor;
+    activity: HarnessActivitySummary;
+  }>;
+  recentValidationRuns: Array<{
+    run: HarnessValidationRunRecord;
+    session?: HarnessSessionRecord;
+    source?: HarnessSourceRecord;
+    exportRecord?: HarnessExportRecord;
+    descriptor?: HarnessSourceDescriptor;
+    validation: HarnessValidationSnapshotSummary;
+  }>;
+};
+
+export type HarnessEditorSessionModel = {
+  session: HarnessSessionRecord;
+  source: HarnessSourceRecord;
+  exports: HarnessExportRecord[];
+  validationRuns: HarnessValidationRunRecord[];
+  relatedSessions: HarnessSessionRecord[];
+  descriptor: HarnessSourceDescriptor;
+  activity: HarnessActivitySummary;
+};
+
+export type HarnessValidationRunModel = {
+  run: HarnessValidationRunRecord;
+  report: HarnessValidationReport;
+  session?: HarnessSessionRecord;
+  source?: HarnessSourceRecord;
+  exportRecord?: HarnessExportRecord;
+  relatedRuns: HarnessValidationRunRecord[];
+  descriptor?: HarnessSourceDescriptor;
+  validation: HarnessValidationSnapshotSummary;
+};
+
+function getSourceDescriptor(source: HarnessSourceRecord): HarnessSourceDescriptor {
+  if (source.sourceKind === "fixture") {
+    return {
+      id: source.fixtureId || source.sourceId,
+      kind: source.sourceKind,
+      kindLabel: "Release-gate fixture",
+      releaseLabel: "release-gate corpus",
+      releaseTone: "success",
+      primaryBadge: source.fixtureId,
+      secondaryBadge: source.featureClassFocus,
+      note: source.primaryFocus,
+    };
+  }
+
+  if (source.sourceKind === "scenario") {
+    return {
+      id: source.scenarioId || source.sourceId,
+      kind: source.sourceKind,
+      kindLabel: "Representative scenario",
+      releaseLabel: "non-release-gate",
+      releaseTone: "warning",
+      primaryBadge: source.scenarioId,
+      secondaryBadge: source.validatorPolicy
+        ? `${source.validatorPolicy.mode} validator policy`
+        : undefined,
+      note: source.wordExpectation || source.primaryFocus,
+    };
+  }
+
+  return {
+    id: source.sourceId,
+    kind: source.sourceKind,
+    kindLabel: "Operator upload",
+    releaseLabel: "operator-upload",
+    releaseTone: "neutral",
+    primaryBadge: "upload",
+    note: "Durable internal upload source",
+  };
+}
+
+function summarizeExport(exportRecord?: HarnessExportRecord): HarnessExportSnapshotSummary {
+  if (!exportRecord) {
+    return {
+      label: "Pending export",
+      detail: "No durable export artifact stored yet.",
+    };
+  }
+
+  return {
+    exportId: exportRecord.exportId,
+    label: `Export ${exportRecord.exportId.slice(0, 8)}`,
+    detail: `${exportRecord.byteLength.toLocaleString()} bytes saved at ${exportRecord.createdAt}`,
+  };
+}
+
+function summarizeValidation(
+  run?: HarnessValidationRunRecord,
+): HarnessValidationSnapshotSummary {
+  if (!run) {
+    return {
+      label: "Pending validation",
+      detail: "No validator snapshot stored yet.",
+      tone: "neutral",
+      findingCount: 0,
+    };
+  }
+
+  const findingCount = run.summary.packageFindingCount + run.summary.sdkFindingCount;
+
+  return {
+    runId: run.runId,
+    label: run.summary.isValid ? "Clean snapshot" : "Findings recorded",
+    detail: run.summary.isValid
+      ? "No stored package or SDK findings in this run."
+      : `${findingCount} stored finding${findingCount === 1 ? "" : "s"} across package and SDK checks.`,
+    tone: run.summary.isValid ? "success" : "warning",
+    findingCount,
+  };
+}
+
+function buildActivitySummary(input: {
+  exports: HarnessExportRecord[];
+  validationRuns: HarnessValidationRunRecord[];
+  latestExport?: HarnessExportRecord;
+  latestValidationRun?: HarnessValidationRunRecord;
+}): HarnessActivitySummary {
+  return {
+    exports: input.exports.length,
+    validationRuns: input.validationRuns.length,
+    latestExport: summarizeExport(input.latestExport || input.exports[0]),
+    latestValidation: summarizeValidation(
+      input.latestValidationRun || input.validationRuns[0],
+    ),
+  };
+}
+
+export async function getHarnessDashboardModel(): Promise<HarnessDashboardModel> {
+  const [health, sources, sessions, runs] = await Promise.all([
+    getHarnessHealthSnapshot(),
+    listHarnessSources(),
+    listHarnessSessions(),
+    listHarnessValidationRuns({ limit: 10 }),
+  ]);
+
+  const recentValidationRuns = await Promise.all(
+    runs.map(async (run) => ({
+      run,
+      session: run.sessionId ? await getHarnessSession(run.sessionId) : undefined,
+      source: run.sourceId ? await getHarnessSource(run.sourceId) : undefined,
+      exportRecord: run.exportId ? await getHarnessExport(run.exportId) : undefined,
+      descriptor: run.sourceId
+        ? await getHarnessSource(run.sourceId).then((source) =>
+            source ? getSourceDescriptor(source) : undefined,
+          )
+        : undefined,
+      validation: summarizeValidation(run),
+    })),
+  );
+  const recentSessions = await Promise.all(
+    sessions.slice(0, 10).map(async (session) => {
+      const [source, latestExport, latestValidationRun, exports, validationRuns] =
+        await Promise.all([
+          getHarnessSource(session.sourceId),
+          session.latestExportId ? getHarnessExport(session.latestExportId) : undefined,
+          session.latestValidationRunId
+            ? getHarnessValidationRun(session.latestValidationRunId)
+            : undefined,
+          listHarnessExportsForSession(session.sessionId),
+          listHarnessValidationRuns({ sessionId: session.sessionId }),
+        ]);
+
+      return {
+        session,
+        source,
+        latestExport,
+        latestValidationRun,
+        descriptor: source
+          ? getSourceDescriptor(source)
+          : {
+              id: session.sourceId,
+              kind: session.sourceKind,
+              kindLabel: session.sourceKind,
+              releaseLabel: "source record missing",
+              releaseTone: "warning",
+            },
+        activity: buildActivitySummary({
+          exports,
+          validationRuns,
+          latestExport,
+          latestValidationRun,
+        }),
+      };
+    }),
+  );
+  const uploads = sources.filter((source) => source.sourceKind === "upload");
+
+  return {
+    health,
+    fixtures: sources.filter((source) => source.sourceKind === "fixture"),
+    scenarios: sources.filter((source) => source.sourceKind === "scenario"),
+    uploads,
+    browseableSources: sources.map((source) => ({
+      source,
+      descriptor: getSourceDescriptor(source),
+    })),
+    recentUploads: uploads.slice(0, 8),
+    recentSessions,
+    recentValidationRuns,
+  };
+}
+
+export async function getHarnessEditorSessionModel(
+  sessionId: string,
+): Promise<HarnessEditorSessionModel | undefined> {
+  const session = await getHarnessSession(sessionId);
+
+  if (!session) {
+    return undefined;
+  }
+
+  const [source, exports, validationRuns] = await Promise.all([
+    getHarnessSource(session.sourceId),
+    listHarnessExportsForSession(sessionId),
+    listHarnessValidationRuns({ sessionId }),
+  ]);
+
+  if (!source) {
+    return undefined;
+  }
+
+  return {
+    session,
+    source,
+    exports,
+    validationRuns,
+    descriptor: getSourceDescriptor(source),
+    activity: buildActivitySummary({
+      exports,
+      validationRuns,
+      latestExport: exports[0],
+      latestValidationRun: validationRuns[0],
+    }),
+    relatedSessions: (await listHarnessSessions())
+      .filter(
+        (candidate) =>
+          candidate.sessionId !== sessionId && candidate.sourceId === session.sourceId,
+      )
+      .slice(0, 8),
+  };
+}
+
+export async function getHarnessValidationRunModel(
+  runId: string,
+): Promise<HarnessValidationRunModel | undefined> {
+  const run = await getHarnessValidationRun(runId);
+
+  if (!run) {
+    return undefined;
+  }
+
+  const [report, session, source, exportRecord] = await Promise.all([
+    readHarnessValidationReport(runId),
+    run.sessionId ? getHarnessSession(run.sessionId) : Promise.resolve(undefined),
+    run.sourceId ? getHarnessSource(run.sourceId) : Promise.resolve(undefined),
+    run.exportId ? getHarnessExport(run.exportId) : Promise.resolve(undefined),
+  ]);
+  const relatedRuns = run.sessionId
+    ? (
+        await listHarnessValidationRuns({
+          sessionId: run.sessionId,
+          limit: 8,
+        })
+      ).filter((candidate) => candidate.runId !== runId)
+    : [];
+
+  return {
+    run,
+    report,
+    session,
+    source,
+    exportRecord,
+    relatedRuns,
+    descriptor: source ? getSourceDescriptor(source) : undefined,
+    validation: summarizeValidation(run),
+  };
+}