@assembly-js/app-foundation 0.0.46 → 0.0.47

package/CHANGELOG.md

@@ -14,6 +14,11 @@ A foundation update reads the sections between an app's version and the target:
 from every bullet except `[guidance]`, agent work from the `fixes.json` entries those `[action]`
 bullets name. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's owner.
 
+## 0.0.47
+- [new] Apps can read the text of uploaded PDFs with a built-in parser that keeps working after publishing.
+- [action: server-pdf-text-extraction] PDF uploads that parsed in the preview but failed after publishing now parse correctly; apps that read PDFs with their own parser switch to the built-in one.
+- [guidance] Tell the build agent why PDF and similar libraries break after deploy (they look up worker scripts and native bindings by their own path), to use the built-in PDF text helper, and to preview PDFs in a new tab or on a canvas rather than in an iframe.
+
 ## 0.0.46
 - [new] Pages, server actions, and routes can use an installer client that acts as the installing admin while a person is in the app.
 - [behavior] The action wrapper takes the actor from the verified bearer and ignores a userId query parameter.

package/CLAUDE.md

@@ -622,7 +622,7 @@ Server components, route handlers, and server actions run in **Node on Vercel**
 
 - **Visual work** (draw a chart, render on a canvas) is **client** work — load the library with `next/dynamic` + `ssr: false`, never in server code.
 - **Fuzzy extraction** (pull fields from a document, classify, summarize) is usually better done through the **AI proxy** (see `assembly-ai`) than a parsing lib — no native binding, no serverless hazard.
-- **Genuine server-side data work** (transform an image, parse bytes) must use a Node-native library: add native/CommonJS packages (e.g. `sharp`) to `serverExternalPackages` in `app.config.ts` (bundling breaks the binding), and give any dep that's loaded dynamically or transitively a static, string-literal import in server code — the deploy tracer can't follow dynamic requires, so such a package silently won't exist in the deployed function even though preview works.
+- **Genuine server-side data work** (transform an image, parse bytes) must use a Node-native library: add native/CommonJS packages (e.g. `sharp`) to `serverExternalPackages` in `app.config.ts` (bundling breaks the binding). A library that locates files at runtime — a worker script, a native binding, font data — by a path computed from its own location breaks after deploy: the bundler relocates its code and the deployed function only has the files reachable from literal imports, so the lookup fails even though preview has the full `node_modules`. Prefer a self-contained server build. **PDF text: `extractPdfText` from `@assembly-js/app-foundation/server`** — never `pdf-parse` or `pdfjs-dist` on the server; both look their worker and canvas up this way and fail on every deployed upload.
 - **Browser-only packages** (touch `window`/`document`/`DOMMatrix`/`HTMLCanvasElement` at import *or during operations*) can't run server-side at all — `serverExternalPackages` doesn't help and dynamic `import()` only defers the crash. Use a Node-native alternative or move the work client-side.
 
 ---
@@ -1464,6 +1464,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't add a manual close button (a `<DialogClose>` render or any X button) inside `DialogContent`. `DialogContent` already ships a built-in close button (`showCloseButton` defaults to `true`); adding another produces two overlapping X icons in the top-right corner. Only pass `showCloseButton={false}` when a custom affordance genuinely replaces the built-in one.
 - ❌ Don't edit `next.config.ts` — it's the platform-owned wrapper that keeps the preview working (cross-origin hydration, WebSocket-blocked networks), and `bun run build` fails if it's rewritten. Your Next configuration belongs in `app.config.ts`.
 - ❌ Don't import a native or browser-only library into server code without the serverless setup — `bun run build` passes but the deployed route crashes at request time. Decide the layer first per "Server runs in serverless Node" above.
+- ❌ Don't preview a PDF (or any file) in an `<iframe>`, `<embed>` or `<object>` — the portal frame is sandboxed and Chrome won't run its PDF viewer inside it, so the preview renders blank while the build passes. Open the pre-signed URL in a new tab (`assembly-storage` Pattern A) or render pages to a canvas client-side with `next/dynamic` + `ssr: false`.
 - ❌ Don't call a change verified, working, or safe to publish because `tsc --noEmit` and `bun run build` passed — name the checks that ran and the signed-in screens left unopened. See "What a passing build proves" above.
 - ❌ Don't pass a function — or an object that holds one, like a question/field config with `visibleWhen`, `validate`, `render`, or `format` callbacks — as a prop from a server component or page into a `'use client'` component. Props cross that boundary as serialized data, so the render throws `Functions cannot be passed directly to Client Components` and the page 500s for every visitor no matter what the record holds. `tsc --noEmit` and `bun run build` both pass. Keep such a config in a shared module the client component imports itself, or express the logic as data (`{ showWhen: { field: 'entityType', equals: 'llc' } }`) and interpret it client-side.
 - ❌ Don't use `Select` or `Combobox` to pick any Assembly person or organization record (clients, internal users, team members, staff, companies). Always use `UserCompanySelector` — in forms, filters, dropdowns, "assign to" controls, everywhere.

package/dist/pdf.d.ts

@@ -0,0 +1,6 @@
+export interface PdfText {
+    /** Every page's text, pages separated by a newline. Empty when the PDF has no text layer (a scan). */
+    text: string;
+    pages: number;
+}
+export declare function extractPdfText(data: ArrayBuffer | Uint8Array): Promise<PdfText>;

package/dist/pdf.js

@@ -0,0 +1,15 @@
+// unpdf ships a self-contained serverless build of pdf.js: the worker is inlined
+// and it never loads @napi-rs/canvas. pdf-parse and pdfjs-dist locate both at
+// runtime by paths computed from their own location, which the deploy tracer
+// can't follow, so they pass in the sandbox and 500 once published. Loaded
+// lazily so routes that never parse a PDF don't carry the bundle.
+export async function extractPdfText(data) {
+    const { getDocumentProxy, extractText } = await import('unpdf');
+    // pdf.js rejects a Node Buffer outright, so hand it a plain Uint8Array view.
+    const bytes = data instanceof ArrayBuffer
+        ? new Uint8Array(data)
+        : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    const pdf = await getDocumentProxy(bytes);
+    const { text, totalPages } = await extractText(pdf, { mergePages: true });
+    return { text, pages: totalPages };
+}

package/dist/server.d.ts

@@ -14,6 +14,7 @@ export * from './notifications.js';
 export * from './cron.js';
 export * from './replace-rows.js';
 export * from './proxy.js';
+export * from './pdf.js';
 export * from './api-errors.js';
 export * from './params.js';
 export * from './client.js';

package/dist/server.js

@@ -18,6 +18,8 @@ export * from './notifications.js';
 export * from './cron.js';
 export * from './replace-rows.js';
 export * from './proxy.js';
+// Lazy-loads its parser, so importing the barrel costs a route nothing until it parses a PDF.
+export * from './pdf.js';
 // Returns NextResponse, so route handlers only — but nothing here reads a
 // secret, which is why a client file may still `import type` from them.
 export * from './api-errors.js';

package/fixes.json

@@ -60,5 +60,19 @@
       "dependencies": ["@assembly-js/app-foundation"],
       "checks": [{ "of": "@assembly-js/app-foundation", "script": "check-proxy-csrf.mjs" }]
     }
+  },
+  {
+    "id": "server-pdf-text-extraction",
+    "version": "0.0.47",
+    "title": "PDF uploads that parsed in the preview but failed after publishing now parse correctly.",
+    "check": "Your app reads PDF text on the server with pdf-parse or pdfjs-dist. Those libraries locate their worker script and the optional canvas binding at runtime by paths computed from their own location; the preview has the full node_modules so it works there, but the deployed function only ships the files reachable from literal imports, so every PDF parse fails after publishing with \"DOMMatrix is not defined\" or \"Setting up fake worker failed\".\n\nReplace each server-side use with the foundation's helper: `import { extractPdfText } from '@assembly-js/app-foundation/server';` then `const { text, pages } = await extractPdfText(bytes);` where `bytes` is the Buffer, Uint8Array or ArrayBuffer the code already has (read back from S3 or from the request). `text` is the whole document with pages separated by newlines and is empty for a scanned PDF with no text layer, so keep whatever fallback the app had for that case. Keep what the app does with the text unchanged.\n\nThen remove what only existed to support the old parser: the pdf-parse, pdfjs-dist and @napi-rs/canvas dependencies, any GlobalWorkerOptions.workerSrc setup, any static `import '@napi-rs/canvas'` or worker import, and their entries in serverExternalPackages in app.config.ts. Do not touch client-side PDF rendering code.",
+    "detector": {
+      "forbidden": [
+        {
+          "id": "server-pdf-parser-import",
+          "pattern": "(from|import\\()\\s*['\"](pdf-parse|pdfjs-dist/legacy/build/pdf(\\.mjs)?)['\"]"
+        }
+      ]
+    }
   }
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.46",
+  "version": "0.0.47",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -65,5 +65,8 @@
     "helpers"
   ],
   "author": "Assembly",
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "unpdf": "^1.9.1"
+  }
 }

package/skills/assembly-storage/SKILL.md

@@ -151,6 +151,7 @@ export async function POST(request: NextRequest) {
     if (!res.ok) throw new Error('S3 fetch failed: ' + res.status);
     const buffer = Buffer.from(await res.arrayBuffer());
     // ...process the buffer here; the file is already stored, no second upload.
+    // PDF text: const { text } = await extractPdfText(buffer) from '@assembly-js/app-foundation/server' (empty text = scanned PDF, no text layer).
     return NextResponse.json({ ok: true });
   } catch (err) {
     return handleRouteError(err, 'Processing failed');