@beyondwork/docx-react-component 1.0.0

package/services/react-word-editor/lib/harness-config.json

@@ -0,0 +1,30 @@
+{
+  "buildOrder": [
+    "Canonical contracts and runtime skeleton",
+    "Core Word text import/edit/export",
+    "Lists, tables, and inline media",
+    "Comments and anchor remapping",
+    "Tracked changes and accept/reject",
+    "Preservation and compatibility reporting",
+    "Railway harness and validator integration"
+  ],
+  "harnessPanels": [
+    {
+      "title": "Fixtures",
+      "description": "Browse the F01-F21 corpus and real-world scenario artifacts, upload new docs, and compare expected support classes."
+    },
+    {
+      "title": "Editor Session",
+      "description": "Mount WordReviewEditor with the selected source and collect runtime warnings, events, and exports."
+    },
+    {
+      "title": "Compatibility",
+      "description": "Inspect package checks, preserve-only warnings, and Word reopen risk summaries for each run."
+    },
+    {
+      "title": "Validator",
+      "description": "Send exported artifacts to the internal Open XML SDK validator and store the results with the run."
+    }
+  ],
+  "validatorEndpointExample": "http://openxml-validator.railway.internal:8080"
+}

package/services/react-word-editor/lib/harness-config.test.mjs

@@ -0,0 +1,31 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function readConfig() {
+  const raw = await readFile(path.join(__dirname, "harness-config.json"), "utf8");
+  return JSON.parse(raw);
+}
+
+test("harness scaffold inventory exposes the expected build stages", async () => {
+  const config = await readConfig();
+
+  assert.equal(config.buildOrder.length, 7);
+  assert.equal(config.buildOrder.at(0), "Canonical contracts and runtime skeleton");
+  assert.equal(config.buildOrder.at(-1), "Railway harness and validator integration");
+});
+
+test("harness scaffold inventory keeps validator and review surfaces visible", async () => {
+  const config = await readConfig();
+  const titles = config.harnessPanels.map((panel) => panel.title);
+  const fixturesPanel = config.harnessPanels.find((panel) => panel.title === "Fixtures");
+
+  assert.deepEqual(titles, ["Fixtures", "Editor Session", "Compatibility", "Validator"]);
+  assert.match(fixturesPanel.description, /scenario artifacts/i);
+  assert.match(config.validatorEndpointExample, /^http:\/\/openxml-validator/);
+});

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

@@ -0,0 +1,21 @@
+import scaffoldConfig from "./harness-config.json";
+
+type HarnessPanel = {
+  title: string;
+  description: string;
+};
+
+type HarnessScaffoldConfig = {
+  buildOrder: string[];
+  harnessPanels: HarnessPanel[];
+  validatorEndpointExample: string;
+};
+
+const config = scaffoldConfig as HarnessScaffoldConfig;
+
+export const buildOrder = config.buildOrder;
+
+export const harnessPanels = config.harnessPanels;
+
+export const validatorEndpointExample =
+  process.env.OPENXML_VALIDATOR_BASE_URL ?? config.validatorEndpointExample;

package/services/react-word-editor/lib/harness-editor-datastore.test.mjs

@@ -0,0 +1,220 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  createHarnessEditorDatastore,
+  readHarnessEditorSessionState,
+} from "./harness-editor-datastore.ts";
+
+function createSnapshot(documentId) {
+  return {
+    snapshotVersion: "persisted-editor-snapshot/1",
+    schemaVersion: "cds/1.0.0",
+    documentId,
+    docId: `${documentId}-doc`,
+    createdAt: "2026-03-28T00:00:00.000Z",
+    updatedAt: "2026-03-28T00:00:00.000Z",
+    savedAt: "2026-03-28T00:00:00.000Z",
+    editorBuild: "harness-editor-datastore-test",
+    canonicalDocument: {
+      schemaVersion: "cds/1.0.0",
+      docId: `${documentId}-doc`,
+      createdAt: "2026-03-28T00:00:00.000Z",
+      updatedAt: "2026-03-28T00:00:00.000Z",
+      metadata: {},
+      styles: {},
+      numbering: {},
+      media: {},
+      content: {
+        type: "doc",
+        children: [
+          {
+            type: "paragraph",
+            children: [{ type: "text", text: "Alpha" }],
+          },
+        ],
+      },
+      review: {
+        comments: {},
+        revisions: {},
+      },
+      preservation: {
+        opaqueFragments: {},
+        packageParts: {},
+      },
+      diagnostics: {
+        warnings: [],
+        errors: [],
+      },
+    },
+    compatibility: {
+      reportVersion: "compatibility-report/1",
+      generatedAt: "2026-03-28T00:00:00.000Z",
+      blockExport: false,
+      featureEntries: [],
+      warnings: [],
+      errors: [],
+    },
+    warningLog: [],
+  };
+}
+
+function createSessionState(overrides = {}) {
+  return {
+    source: {
+      sourceLabel: "Fixture F11",
+    },
+    sourceDownloadPath: "/api/sessions/session-123/source",
+    latestExport: null,
+    latestValidation: null,
+    snapshot: null,
+    ...overrides,
+  };
+}
+
+test("readHarnessEditorSessionState reads the mounted session record", async (t) => {
+  const originalFetch = globalThis.fetch;
+  t.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  globalThis.fetch = async () =>
+    Response.json(createSessionState(), {
+      headers: { "cache-control": "no-store" },
+    });
+
+  const state = await readHarnessEditorSessionState("session-123");
+  assert.equal(state.source.sourceLabel, "Fixture F11");
+  assert.equal(state.sourceDownloadPath, "/api/sessions/session-123/source");
+});
+
+test("datastore load prefers the saved snapshot when one exists", async (t) => {
+  const originalFetch = globalThis.fetch;
+  t.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  const calls = [];
+  globalThis.fetch = async (url) => {
+    calls.push(String(url));
+    return Response.json(
+      createSessionState({
+        snapshot: {
+          isAutosave: true,
+          savedAt: "2026-03-28T00:00:00.000Z",
+          snapshot: createSnapshot("doc-123"),
+        },
+      }),
+      {
+        headers: { "cache-control": "no-store" },
+      },
+    );
+  };
+
+  const datastore = createHarnessEditorDatastore("session-123");
+  const result = await datastore.load({ documentId: "doc-123" });
+
+  assert.deepEqual(calls, ["/api/sessions/session-123"]);
+  assert.equal(result.source.kind, "snapshot");
+  assert.equal(result.source.snapshot.documentId, "doc-123");
+  assert.equal(result.source.sourceLabel, "Fixture F11");
+});
+
+test("datastore load falls back to the source package when no snapshot exists", async (t) => {
+  const originalFetch = globalThis.fetch;
+  t.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  const calls = [];
+  globalThis.fetch = async (url) => {
+    calls.push(String(url));
+    if (String(url) === "/api/sessions/session-123") {
+      return Response.json(createSessionState(), {
+        headers: { "cache-control": "no-store" },
+      });
+    }
+
+    return new Response(new Uint8Array([1, 2, 3]).buffer, {
+      status: 200,
+      headers: {
+        "content-type":
+          "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      },
+    });
+  };
+
+  const datastore = createHarnessEditorDatastore("session-123");
+  const result = await datastore.load({ documentId: "doc-123" });
+
+  assert.deepEqual(calls, ["/api/sessions/session-123", "/api/sessions/session-123/source"]);
+  assert.equal(result.source.kind, "docx");
+  assert.deepEqual(Array.from(new Uint8Array(result.source.bytes)), [1, 2, 3]);
+});
+
+test("datastore saveSnapshot persists through the session route", async (t) => {
+  const originalFetch = globalThis.fetch;
+  t.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  const requests = [];
+  globalThis.fetch = async (url, init) => {
+    requests.push({
+      url: String(url),
+      method: init?.method,
+      body: init?.body ? JSON.parse(String(init.body)) : null,
+    });
+
+    return Response.json({ savedAt: "2026-03-28T00:05:00.000Z" });
+  };
+
+  const datastore = createHarnessEditorDatastore("session-123");
+  const result = await datastore.saveSnapshot({
+    documentId: "doc-123",
+    isAutosave: true,
+    snapshot: createSnapshot("doc-123"),
+  });
+
+  assert.equal(result.savedAt, "2026-03-28T00:05:00.000Z");
+  assert.equal(requests[0].url, "/api/sessions/session-123");
+  assert.equal(requests[0].method, "PUT");
+  assert.equal(requests[0].body.isAutosave, true);
+  assert.equal(requests[0].body.snapshot.documentId, "doc-123");
+});
+
+test("datastore saveExport persists bytes through the session route", async (t) => {
+  const originalFetch = globalThis.fetch;
+  t.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  const requests = [];
+  globalThis.fetch = async (url, init) => {
+    requests.push({
+      url: String(url),
+      method: init?.method,
+      body: init?.body ? JSON.parse(String(init.body)) : null,
+    });
+
+    return Response.json({ savedAt: "2026-03-28T00:06:00.000Z" });
+  };
+
+  const datastore = createHarnessEditorDatastore("session-123");
+  const result = await datastore.saveExport({
+    documentId: "doc-123",
+    result: {
+      bytes: new Uint8Array([65, 66, 67]),
+      fileName: "doc-123.docx",
+      mimeType:
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    },
+  });
+
+  assert.equal(result.savedAt, "2026-03-28T00:06:00.000Z");
+  assert.equal(requests[0].url, "/api/sessions/session-123");
+  assert.equal(requests[0].method, "POST");
+  assert.equal(requests[0].body.bytesBase64, "QUJD");
+  assert.equal(requests[0].body.fileName, "doc-123.docx");
+  assert.equal(requests[0].body.reason, "harness-mounted-export");
+});

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

@@ -0,0 +1,161 @@
+import type {
+  EditorDatastoreAdapter,
+  LoadResult,
+  PersistedEditorSnapshot,
+  SaveExportParams,
+  SaveExportResult,
+  SaveSnapshotParams,
+  SaveSnapshotResult,
+} from "../../../src/api/public-types";
+
+type HarnessSessionExportRecord = {
+  exportId: string;
+  fileName: string;
+};
+
+type HarnessSessionValidationRecord = {
+  exportId?: string;
+  runId: string;
+  summary: {
+    isValid: boolean;
+    packageFindingCount: number;
+    sdkFindingCount: number;
+  };
+};
+
+type HarnessSessionStateResponse = {
+  source: {
+    sourceLabel: string;
+  };
+  sourceDownloadPath: string;
+  latestExport: HarnessSessionExportRecord | null;
+  latestValidation: HarnessSessionValidationRecord | null;
+  snapshot: {
+    isAutosave: boolean;
+    savedAt: string;
+    snapshot: PersistedEditorSnapshot;
+  } | null;
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function assertSessionStateResponse(value: unknown): asserts value is HarnessSessionStateResponse {
+  if (!isObject(value) || !isObject(value.source) || typeof value.sourceDownloadPath !== "string") {
+    throw new Error("Session state response is malformed.");
+  }
+}
+
+async function fetchJson(url: string, init?: RequestInit): Promise<unknown> {
+  const response = await fetch(url, {
+    cache: "no-store",
+    ...init,
+  });
+
+  if (!response.ok) {
+    throw new Error(await response.text());
+  }
+
+  return response.json();
+}
+
+function encodeBytesBase64(bytes: Uint8Array): string {
+  let binary = "";
+  const chunkSize = 0x8000;
+
+  for (let index = 0; index < bytes.length; index += chunkSize) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + chunkSize));
+  }
+
+  return btoa(binary);
+}
+
+export async function readHarnessEditorSessionState(
+  sessionId: string,
+): Promise<HarnessSessionStateResponse> {
+  const payload = await fetchJson(`/api/sessions/${sessionId}`);
+  assertSessionStateResponse(payload);
+  return payload;
+}
+
+async function loadSessionSource(state: HarnessSessionStateResponse): Promise<LoadResult> {
+  if (state.snapshot?.snapshot) {
+    return {
+      source: {
+        kind: "snapshot",
+        snapshot: state.snapshot.snapshot,
+        sourceLabel: state.source.sourceLabel,
+      },
+    };
+  }
+
+  const response = await fetch(state.sourceDownloadPath, {
+    cache: "no-store",
+  });
+
+  if (!response.ok) {
+    throw new Error(await response.text());
+  }
+
+  const arrayBuffer = await response.arrayBuffer();
+
+  return {
+    source: {
+      kind: "docx",
+      bytes: new Uint8Array(arrayBuffer),
+      sourceLabel: state.source.sourceLabel,
+    },
+  };
+}
+
+export function createHarnessEditorDatastore(sessionId: string): EditorDatastoreAdapter {
+  return {
+    async load() {
+      const state = await readHarnessEditorSessionState(sessionId);
+      return loadSessionSource(state);
+    },
+    async saveSnapshot(params: SaveSnapshotParams): Promise<SaveSnapshotResult> {
+      const payload = await fetchJson(`/api/sessions/${sessionId}`, {
+        body: JSON.stringify({
+          isAutosave: params.isAutosave,
+          snapshot: params.snapshot,
+        }),
+        headers: {
+          "content-type": "application/json",
+        },
+        method: "PUT",
+      });
+
+      if (!isObject(payload) || typeof payload.savedAt !== "string") {
+        throw new Error("Snapshot save response is malformed.");
+      }
+
+      return {
+        savedAt: payload.savedAt,
+      };
+    },
+    async saveExport(params: SaveExportParams): Promise<SaveExportResult> {
+      const payload = await fetchJson(`/api/sessions/${sessionId}`, {
+        body: JSON.stringify({
+          bytesBase64: encodeBytesBase64(params.result.bytes),
+          fileName: params.result.fileName,
+          mimeType: params.result.mimeType,
+          reason: "harness-mounted-export",
+        }),
+        headers: {
+          "content-type": "application/json",
+        },
+        method: "POST",
+      });
+
+      if (!isObject(payload) || typeof payload.savedAt !== "string") {
+        throw new Error("Export save response is malformed.");
+      }
+
+      return {
+        savedAt: payload.savedAt,
+      };
+    },
+  };
+}

package/services/react-word-editor/lib/private-mode.test.mjs

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  getHarnessPrivateModeHint,
+  isHarnessPrivateModeEnabled,
+  shouldBypassHarnessPrivateMode,
+} from "./private-mode.ts";
+
+test("private mode stays disabled until explicitly enabled", (t) => {
+  const originalValue = process.env.HARNESS_PRIVATE_MODE;
+  t.after(() => {
+    if (originalValue === undefined) {
+      delete process.env.HARNESS_PRIVATE_MODE;
+      return;
+    }
+
+    process.env.HARNESS_PRIVATE_MODE = originalValue;
+  });
+
+  delete process.env.HARNESS_PRIVATE_MODE;
+  assert.equal(isHarnessPrivateModeEnabled(), false);
+
+  process.env.HARNESS_PRIVATE_MODE = " enabled ";
+  assert.equal(isHarnessPrivateModeEnabled(), true);
+});
+
+test("private mode hint keeps the deployment instruction explicit", () => {
+  assert.equal(
+    getHarnessPrivateModeHint(),
+    "Set HARNESS_PRIVATE_MODE=enabled on a private deployment.",
+  );
+});
+
+test("only framework assets and deploy health bypass the private mode gate", () => {
+  assert.equal(shouldBypassHarnessPrivateMode("/_next/static/chunks/app.js"), true);
+  assert.equal(shouldBypassHarnessPrivateMode("/favicon.ico"), true);
+  assert.equal(shouldBypassHarnessPrivateMode("/api/deploy-health"), true);
+  assert.equal(shouldBypassHarnessPrivateMode("/"), false);
+  assert.equal(shouldBypassHarnessPrivateMode("/api/health"), false);
+  assert.equal(shouldBypassHarnessPrivateMode("/api/uploads"), false);
+});

package/services/react-word-editor/lib/private-mode.ts

@@ -0,0 +1,61 @@
+const ENABLED_VALUE = "enabled";
+const UNGUARDED_PATHS = new Set(["/api/deploy-health", "/favicon.ico"]);
+
+export class HarnessRouteError extends Error {
+  readonly code: string;
+  readonly status: number;
+
+  constructor(code: string, status: number, message: string) {
+    super(message);
+    this.name = "HarnessRouteError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export function isHarnessRouteError(error: unknown): error is HarnessRouteError {
+  return error instanceof HarnessRouteError;
+}
+
+export function isHarnessPrivateModeEnabled(): boolean {
+  return process.env.HARNESS_PRIVATE_MODE?.trim().toLowerCase() === ENABLED_VALUE;
+}
+
+export function getHarnessPrivateModeHint(): string {
+  return "Set HARNESS_PRIVATE_MODE=enabled on a private deployment.";
+}
+
+export function shouldBypassHarnessPrivateMode(pathname: string): boolean {
+  return pathname.startsWith("/_next/") || UNGUARDED_PATHS.has(pathname);
+}
+
+export function assertHarnessPrivateModeEnabled(): void {
+  if (!isHarnessPrivateModeEnabled()) {
+    throw new HarnessRouteError(
+      "private_mode_required",
+      503,
+      "The harness is disabled until private-only mode is explicitly enabled.",
+    );
+  }
+}
+
+export function assertContentLengthWithinLimit(
+  request: Request,
+  maxBytes: number,
+): void {
+  const rawContentLength = request.headers.get("content-length");
+  if (!rawContentLength) {
+    return;
+  }
+
+  const contentLength = Number.parseInt(rawContentLength, 10);
+  if (!Number.isFinite(contentLength) || contentLength <= maxBytes) {
+    return;
+  }
+
+  throw new HarnessRouteError(
+    "file_too_large",
+    413,
+    `Requests larger than ${Math.round(maxBytes / (1024 * 1024))} MiB are rejected before upload parsing.`,
+  );
+}