Merge pull request #194 from BjoernSchotte/codex/import-pdf-mvp

feat(import-pdf): semantic PDF import MVP

Author: BjoernSchotte

.gitignore

@@ -26,6 +26,10 @@ packages/pdf/.fonts/
 # packages/pdf-compiler-browser/scripts/vendor-typst.ts for why not committed).
 packages/pdf-compiler-browser/vendor/
 
+# Reproducible PDFium importer WASM/licenses/provenance. The exact-pinned
+# dependency is verified and copied by packages/import-pdf/scripts/vendor-pdfium.ts.
+packages/import-pdf/vendor/
+
 # SonarQube coverage artifact
 coverage/
 .scannerwork/

NOTICE

@@ -11,6 +11,12 @@ original attribution preserved.
 
 Third-party notices:
 
+- @embedpdf/pdfium (https://github.com/embedpdf/embed-pdf-viewer), version
+  2.15.0, licensed under the MIT License, distributing a PDFium WebAssembly
+  binary from https://github.com/embedpdf/pdfium. PDFium is licensed under a
+  BSD-style license and carries Apache-2.0-licensed components. Exact release,
+  fork, binary provenance, license texts, and the unresolved transitive-notice
+  inventory ship in packages/import-pdf/vendor/.
 - typst.ts web compiler (https://github.com/BjoernSchotte/typst.ts), forked
   from https://github.com/Myriad-Dreamin/typst.ts, distribution version
   0.8.0-rc3.typst0151.1 with embedded Typst 0.15.1, licensed under the Apache

apps/browser-export-harness/package.json

@@ -7,14 +7,14 @@
   "scripts": {
     "pretypecheck": "bun run --cwd ../.. fonts:ensure",
     "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.worker.json && tsc -p tsconfig.tools.json",
-    "prebuild": "bun run --cwd ../.. fonts:ensure && bun run --cwd ../.. vendor:typst && bun run --cwd ../.. clean:browser-export-harness-output",
+    "prebuild": "bun run --cwd ../.. fonts:ensure && bun run --cwd ../.. vendor:typst && bun run --cwd ../.. vendor:pdfium && bun run --cwd ../.. clean:browser-export-harness-output",
     "build": "vite build",
     "check:output": "bun --conditions=development scripts/check-output.ts",
     "assert:cases": "bun scripts/assert-case-manifest.ts",
-    "precheck:parity": "bun run --cwd ../.. fonts:ensure && bun run --cwd ../.. vendor:typst",
+    "precheck:parity": "bun run --cwd ../.. fonts:ensure && bun run --cwd ../.. vendor:typst && bun run --cwd ../.. vendor:pdfium",
     "check:parity": "bun --conditions=development scripts/check-parity.ts",
     "test:unit": "bun --conditions=development test tests/boundaries.test.ts tests/output-scan.test.ts tests/pdf-worker-client.test.ts tests/pdf-job-parity.test.ts tests/docx-job-parity.test.ts scripts/check-parity.test.ts",
-    "pretest:e2e": "bun run --cwd ../.. fonts:ensure && bun run --cwd ../.. vendor:typst",
+    "pretest:e2e": "bun run --cwd ../.. fonts:ensure && bun run --cwd ../.. vendor:typst && bun run --cwd ../.. vendor:pdfium",
     "test:e2e": "playwright test"
   },
   "dependencies": {
@@ -25,6 +25,7 @@
     "@atlcli/export-fixtures": "workspace:*",
     "@atlcli/export-jobs": "workspace:*",
     "@atlcli/export-wiring": "workspace:*",
+    "@atlcli/import-pdf": "workspace:*",
     "@atlcli/pdf": "workspace:*",
     "@atlcli/pdf-compiler-browser": "workspace:*",
     "@atlcli/pdf-template-authoring": "workspace:*",

apps/browser-export-harness/scripts/check-output.ts

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join, relative } from "node:path";
 import { PDF_RUNTIME_ASSETS } from "@atlcli/pdf/browser";
+import { PDFIUM_WASM_SHA256 } from "@atlcli/import-pdf/browser-worker";
 
 const NODE_SPECIFIER_RE = /["'`](?:node|bun):[A-Za-z0-9_./-]*["'`]/g;
 const NODE_RUNTIME_RE = /(?<![\w.])Buffer\.[A-Za-z_$]|\bprocess\.(?:env|versions)\b|\brequire\s*\(\s*["'`]|\b__dirname\b|\b__filename\b/g;
@@ -34,6 +35,11 @@ const AGGREGATE_SHIKI_RUNTIME_RES = [
   /\blangs-bundle-full\b/g,
   /["'`]shiki(?:\/(?:langs|themes))?["'`]/g,
 ];
+const IMPORT_ENGINE_BOUNDARY_RES = [
+  /pdfjs-dist/g,
+  /DEFAULT_PDFIUM_WASM_URL/g,
+  /cdn[.]jsdelivr[.]net\/npm\/@embedpdf\/pdfium/gi,
+];
 const DOCX_CODE_FONT_SHA256 =
   "a0bf60ef0f83c5ed4d7a75d45838548b1f6873372dfac88f71804491898d138f";
 
@@ -56,21 +62,34 @@ function matches(text: string, expressions: RegExp[]): string[] {
   return [...findings];
 }
 
+function withoutReviewedEmscriptenBrowserProbe(text: string): string {
+  // @embedpdf/pdfium's browser-only Emscripten wrapper retains one discarded
+  // environment probe even though the Node branch is compiled out. This exact
+  // expression does not import/call Node and evaluates safely in a Worker.
+  // Keep every other process.versions use subject to the Node-runtime ban.
+  return text.replace(
+    /typeof process\s*==\s*["'`]object["'`]\s*&&\s*typeof process[.]versions\s*==\s*["'`]object["'`]\s*&&\s*typeof process[.]versions[.]node\s*==\s*["'`]string["'`]\s*&&\s*process[.]type/gu,
+    "false",
+  );
+}
+
 export function scanHarnessText(text: string): string[] {
+  const reviewed = withoutReviewedEmscriptenBrowserProbe(text);
   const findings = [
-    ...matches(text, [NODE_SPECIFIER_RE, NODE_RUNTIME_RE]),
-    ...matches(text, DYNAMIC_CODE_RES),
-    ...matches(text, REMOTE_EXECUTABLE_RES),
-    ...matches(text, [EXTENSION_RUNTIME_RE]),
-    ...matches(text, ROOT_RELATIVE_RES),
-    ...matches(text, ONIGURUMA_RUNTIME_RES),
-    ...matches(text, AGGREGATE_SHIKI_RUNTIME_RES),
+    ...matches(reviewed, [NODE_SPECIFIER_RE, NODE_RUNTIME_RE]),
+    ...matches(reviewed, DYNAMIC_CODE_RES),
+    ...matches(reviewed, REMOTE_EXECUTABLE_RES),
+    ...matches(reviewed, [EXTENSION_RUNTIME_RE]),
+    ...matches(reviewed, ROOT_RELATIVE_RES),
+    ...matches(reviewed, ONIGURUMA_RUNTIME_RES),
+    ...matches(reviewed, AGGREGATE_SHIKI_RUNTIME_RES),
+    ...matches(reviewed, IMPORT_ENGINE_BOUNDARY_RES),
   ];
   // Shiki grammar chunks are inert JSON payloads. Some grammars list Node
   // globals as source-language keywords; those strings are not runtime use.
   if (
-    text.includes("Object.freeze(JSON.parse(`") &&
-    text.includes('"scopeName"')
+    reviewed.includes("Object.freeze(JSON.parse(`") &&
+    reviewed.includes('"scopeName"')
   ) {
     return findings.filter(
       (finding) => finding !== "__dirname" && finding !== "__filename",
@@ -170,6 +189,12 @@ export function validateHarnessInventory(artifacts: OutputArtifact[]): string[]
     "Typst compiler WASM",
     /(?:^|\/)assets\/typst_ts_web_compiler_bg-[^/]+\.wasm$/,
   ));
+  issues.push(...requireOne(
+    artifacts,
+    "PDFium importer WASM",
+    /(?:^|\/)assets\/pdfium-[^/]+\.wasm$/,
+    PDFIUM_WASM_SHA256,
+  ));
   issues.push(...requireOne(
     artifacts,
     "DOCX code font",

apps/browser-export-harness/src/conformance-manifest.ts

@@ -91,6 +91,14 @@ export const CONFORMANCE_MANIFEST: readonly ConformanceCaseMeta[] = [
     mediaPolicy: "none",
     emitsDigests: false,
   },
+  {
+    id: "import-pdf",
+    title: "PDFium import Worker contract",
+    folderTaskIds: ["import-pdf-mvp/PDF-10"],
+    engines: ["pdf"],
+    mediaPolicy: "none",
+    emitsDigests: false,
+  },
   {
     id: "pdf-settings",
     title: "PDF settings & watermark (007)",
@@ -222,6 +230,7 @@ export const EXPECTED_LANDED_CASE_IDS: readonly string[] = [
   "docx-job-parity",
   "pdf",
   "pdf-job-parity",
+  "import-pdf",
   "pdf-settings",
   "pdf-v5",
   "docx-template-intake",

apps/browser-export-harness/src/conformance-registry.ts

@@ -16,6 +16,7 @@ import { runDocxCase } from "./docx-case.js";
 import { runDocxJobParityCase } from "./docx-job-parity-case.js";
 import { runDocxQualityCase } from "./docx-quality-case.js";
 import { runDocxTemplateIntakeCase } from "./docx-template-intake-case.js";
+import { runImportPdfCase } from "./import-pdf-case.js";
 import { runM1Case } from "./m1-case.js";
 import { runMacroCase } from "./macro-case.js";
 import { runManuscriptCase } from "./manuscript-case.js";
@@ -40,6 +41,7 @@ const RUNNERS: Record<string, () => Promise<unknown>> = {
   "docx-job-parity": runDocxJobParityCase,
   pdf: runPdfCase,
   "pdf-job-parity": runPdfJobParityCase,
+  "import-pdf": runImportPdfCase,
   "pdf-settings": runPdfSettingsCase,
   "pdf-v5": runPdfV5Case,
   "docx-template-intake": runDocxTemplateIntakeCase,

apps/browser-export-harness/src/import-pdf-case.ts

@@ -0,0 +1,79 @@
+import fixtureUrl from "../../../specs/import-pdf-mvp/fixtures/simple-untagged.pdf?url&no-inline";
+import {
+  PDFIUM_ENGINE_VERSION,
+  PDFIUM_WASM_SHA256,
+} from "@atlcli/import-pdf/browser-worker";
+import {
+  isImportPdfWorkerResponse,
+  type ImportPdfWorkerResponse,
+} from "./import-pdf-worker-protocol.js";
+
+export interface ImportPdfCaseResult {
+  pageCount: number;
+  complete: boolean;
+  classification: string;
+  engine: string;
+  engineVersion: string;
+  wasmSha256: string;
+  factsDigest: string;
+  semanticDigest: string;
+  titleCandidate: string | null;
+  blockTypes: string[];
+  workerTerminated: boolean;
+}
+
+async function loadFixture(): Promise<Uint8Array<ArrayBuffer>> {
+  const resolved = new URL(fixtureUrl, location.href);
+  if (resolved.origin !== location.origin) {
+    throw new Error("The PDF import fixture must be loaded from the harness origin.");
+  }
+  const response = await fetch(resolved);
+  if (!response.ok) throw new Error(`The PDF import fixture failed to load (${response.status}).`);
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+function runWorker(bytes: Uint8Array<ArrayBuffer>): Promise<ImportPdfWorkerResponse> {
+  const worker = new Worker(new URL("./import-pdf-worker.ts", import.meta.url), {
+    type: "module",
+    name: "atlcli-browser-harness-import-pdf",
+  });
+  return new Promise((resolve, reject) => {
+    const timeout = window.setTimeout(() => {
+      worker.terminate();
+      reject(new Error("The PDF import Worker exceeded its 30 second harness deadline."));
+    }, 30_000);
+    worker.onmessage = (event: MessageEvent<unknown>) => {
+      if (!isImportPdfWorkerResponse(event.data) || event.data.requestId !== 1) return;
+      window.clearTimeout(timeout);
+      worker.terminate();
+      resolve(event.data);
+    };
+    worker.onerror = (event) => {
+      window.clearTimeout(timeout);
+      worker.terminate();
+      reject(new Error(event.message || "The PDF import Worker failed."));
+    };
+    worker.postMessage({ kind: "analyze", requestId: 1, bytes }, [bytes.buffer]);
+  });
+}
+
+export async function runImportPdfCase(): Promise<ImportPdfCaseResult> {
+  const response = await runWorker(await loadFixture());
+  if (!response.ok) throw new Error(response.error);
+  const result = response.result;
+  if (
+    result.pageCount !== 1
+    || !result.complete
+    || result.classification !== "digital-untagged"
+    || result.engine !== "pdfium"
+    || result.engineVersion !== PDFIUM_ENGINE_VERSION
+    || result.wasmSha256 !== PDFIUM_WASM_SHA256
+    || result.titleCandidate !== "Quarterly Garden Notes"
+    || result.blockTypes.join(",") !== "heading,paragraph,paragraph,paragraph,heading,list"
+    || !/^[a-f0-9]{64}$/u.test(result.factsDigest)
+    || !/^[a-f0-9]{64}$/u.test(result.semanticDigest)
+  ) {
+    throw new Error(`The browser PDF import facts drifted: ${JSON.stringify(result)}`);
+  }
+  return { ...result, workerTerminated: true };
+}

apps/browser-export-harness/src/import-pdf-worker-protocol.ts

@@ -0,0 +1,40 @@
+export interface ImportPdfWorkerRequest {
+  kind: "analyze";
+  requestId: number;
+  bytes: Uint8Array;
+}
+
+export interface ImportPdfWorkerSuccess {
+  kind: "result";
+  requestId: number;
+  ok: true;
+  result: {
+    pageCount: number;
+    complete: boolean;
+    classification: string;
+    engine: string;
+    engineVersion: string;
+    wasmSha256: string;
+    factsDigest: string;
+    semanticDigest: string;
+    titleCandidate: string | null;
+    blockTypes: string[];
+  };
+}
+
+export interface ImportPdfWorkerFailure {
+  kind: "result";
+  requestId: number;
+  ok: false;
+  error: string;
+}
+
+export type ImportPdfWorkerResponse = ImportPdfWorkerSuccess | ImportPdfWorkerFailure;
+
+export function isImportPdfWorkerResponse(value: unknown): value is ImportPdfWorkerResponse {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<ImportPdfWorkerResponse>;
+  return candidate.kind === "result"
+    && typeof candidate.requestId === "number"
+    && typeof candidate.ok === "boolean";
+}

apps/browser-export-harness/src/import-pdf-worker.ts

@@ -0,0 +1,67 @@
+/// <reference lib="webworker" />
+
+import pdfiumWasmUrl from "@atlcli/import-pdf/wasm?url&no-inline";
+import {
+  createBrowserPdfiumFactsAdapter,
+  normalizeUntaggedPdfFacts,
+} from "@atlcli/import-pdf/browser-worker";
+import type {
+  ImportPdfWorkerRequest,
+  ImportPdfWorkerResponse,
+} from "./import-pdf-worker-protocol.js";
+
+const scope = self as unknown as DedicatedWorkerGlobalScope;
+
+async function sameOriginBytes(url: string): Promise<Uint8Array<ArrayBuffer>> {
+  const resolved = new URL(url, scope.location.href);
+  if (resolved.origin !== scope.location.origin) {
+    throw new Error("The PDF importer runtime asset must be same-origin.");
+  }
+  const response = await fetch(resolved);
+  if (!response.ok) {
+    throw new Error(`The packaged PDFium asset failed to load (${response.status}).`);
+  }
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+async function analyze(request: ImportPdfWorkerRequest): Promise<void> {
+  try {
+    const wasmBinary = await sameOriginBytes(pdfiumWasmUrl);
+    const adapter = createBrowserPdfiumFactsAdapter({ wasmBinary });
+    const analyzed = await adapter.analyze(request.bytes);
+    const semantics = await normalizeUntaggedPdfFacts(
+      analyzed.facts,
+      analyzed.factsDigest,
+    );
+    const response: ImportPdfWorkerResponse = {
+      kind: "result",
+      requestId: request.requestId,
+      ok: true,
+      result: {
+        pageCount: analyzed.facts.pageCount,
+        complete: analyzed.facts.completeness.complete,
+        classification: analyzed.facts.classification,
+        engine: analyzed.facts.provenance.engine,
+        engineVersion: analyzed.facts.provenance.engineVersion,
+        wasmSha256: analyzed.facts.provenance.wasmSha256,
+        factsDigest: analyzed.factsDigest,
+        semanticDigest: semantics.semanticDigest,
+        titleCandidate: semantics.document.titleCandidate ?? null,
+        blockTypes: semantics.document.blocks.map((block) => block.type),
+      },
+    };
+    scope.postMessage(response);
+  } catch (error) {
+    const response: ImportPdfWorkerResponse = {
+      kind: "result",
+      requestId: request.requestId,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+    scope.postMessage(response);
+  }
+}
+
+scope.addEventListener("message", (event: MessageEvent<ImportPdfWorkerRequest>) => {
+  if (event.data?.kind === "analyze") void analyze(event.data);
+});

apps/browser-export-harness/tests/boundaries.test.ts

@@ -56,6 +56,21 @@ describe("browser harness boundaries", () => {
     expect(combined).toContain("new Worker(new URL");
   });
 
+  it("keeps PDFium in the isolated import Worker and PDF.js out of the importer graph", () => {
+    const worker = read("src/import-pdf-worker.ts");
+    const importerFiles = [
+      "src/import-pdf-case.ts",
+      "src/import-pdf-worker.ts",
+      "src/import-pdf-worker-protocol.ts",
+    ].map(read).join("\n");
+    expect(worker).toContain('@atlcli/import-pdf/wasm?url&no-inline');
+    expect(worker).toContain('@atlcli/import-pdf/browser-worker');
+    expect(worker).toContain("sameOriginBytes");
+    expect(importerFiles).not.toContain("pdfjs-dist");
+    expect(importerFiles).not.toContain("DEFAULT_PDFIUM_WASM_URL");
+    expect(importerFiles).not.toContain("@embedpdf/pdfium");
+  });
+
   it("keeps every font import static and checks it against the manifest", () => {
     const worker = read("src/pdf-worker.ts");
     const staticFontImports = [...worker.matchAll(/from\s+"@atlcli\/pdf\/fonts\/([^?]+)\?url"/g)]