@telorun/pdf 0.3.0 → 0.8.0

package/README.md

@@ -23,9 +23,9 @@ Built to be language-agnostic and infinitely extensible.
 
 ```bash
 # Reconcile your manifest into a running backend
-$ telo ./examples/hello-api
+$ telo ./examples/todo-app
 
-{"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8844"}
+{"level":30,"time":1771610393008,"pid":1310178,"hostname":"dev","msg":"Server listening at http://127.0.0.1:8077"}
 ```
 
 ## Why use Telo?
@@ -48,7 +48,9 @@ See [examples/](./examples/) for a list of working applications.
 
 ## Status
 
-Telo is under **active development**. The core runtime, module system, and standard library are functional, but the API surface — including YAML shapes — may change without notice. Not yet recommended for production use.
+Telo is under heavy development. While it is pre-1.0, breaking changes ship in **minor** releases — manifest shapes, kind schemas, and APIs can change between versions. Pin your imports and expect to update manifests when you upgrade. The core runtime, module system, and standard library are functional, but Telo is not yet recommended for production use.
+
+**1.0 lands when the Rust kernel reaches feature parity with the Node.js implementation** — that is the milestone that freezes the manifest contract across runtimes.
 
 ## The Meaning of Telo
 

package/dist/text-controller.d.ts

@@ -0,0 +1,39 @@
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+interface TextResource {
+    metadata: {
+        name: string;
+        module?: string;
+    };
+}
+interface TextInputs {
+    data: Uint8Array;
+    page?: number;
+}
+interface TextOutputs {
+    text: string;
+    pages: string[];
+    pageCount: number;
+}
+/**
+ * Reads the text a PDF actually renders.
+ *
+ * The counterpart to `Pdf.Rasterizer`: rasterizing answers *what does this page
+ * look like*, which is a question about pixels and moves with the platform's
+ * font rasterization. This answers *what does it say*, which is what an
+ * assertion about a generated document needs — a rendered page image cannot
+ * tell a correct table from an empty one.
+ *
+ * Items are joined in the order pdf.js reports them, with a line break at each
+ * end-of-line marker. That is reading order for ordinary flowed content; it is
+ * not a layout reconstruction, and a multi-column page reads column by column
+ * the way the producer wrote it.
+ */
+declare class PdfText implements ResourceInstance<TextInputs, TextOutputs> {
+    private readonly resource;
+    constructor(resource: TextResource);
+    invoke(inputs: TextInputs): Promise<TextOutputs>;
+    snapshot(): Record<string, unknown>;
+}
+export declare function register(): void;
+export declare function create(resource: TextResource, _ctx: ResourceContext): Promise<PdfText>;
+export {};

package/dist/text-controller.js

@@ -0,0 +1,86 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+// The legacy build is pdf.js's Node target — the same one the rasterizer loads.
+import { getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
+import { InvokeError } from "@telorun/sdk";
+const PDFJS_ROOT = dirname(createRequire(import.meta.url).resolve("pdfjs-dist/package.json"));
+const ASSET_OPTIONS = {
+    standardFontDataUrl: join(PDFJS_ROOT, "standard_fonts") + "/",
+    cMapUrl: join(PDFJS_ROOT, "cmaps") + "/",
+    cMapPacked: true,
+    wasmUrl: join(PDFJS_ROOT, "wasm") + "/",
+};
+/**
+ * Reads the text a PDF actually renders.
+ *
+ * The counterpart to `Pdf.Rasterizer`: rasterizing answers *what does this page
+ * look like*, which is a question about pixels and moves with the platform's
+ * font rasterization. This answers *what does it say*, which is what an
+ * assertion about a generated document needs — a rendered page image cannot
+ * tell a correct table from an empty one.
+ *
+ * Items are joined in the order pdf.js reports them, with a line break at each
+ * end-of-line marker. That is reading order for ordinary flowed content; it is
+ * not a layout reconstruction, and a multi-column page reads column by column
+ * the way the producer wrote it.
+ */
+class PdfText {
+    resource;
+    constructor(resource) {
+        this.resource = resource;
+    }
+    async invoke(inputs) {
+        const name = this.resource.metadata.name;
+        const data = inputs?.data;
+        if (!(data instanceof Uint8Array)) {
+            throw new InvokeError("ERR_INVALID_INPUT", `Pdf.Text "${name}": 'data' must be a Uint8Array of PDF bytes; got ${typeof data}.`);
+        }
+        // pdf.js transfers the buffer it is given — hand it a copy so the caller's
+        // bytes survive a second read.
+        const task = getDocument({ data: new Uint8Array(data), ...ASSET_OPTIONS });
+        try {
+            const doc = await task.promise.catch((err) => {
+                throw new InvokeError("ERR_INVALID_INPUT", `Pdf.Text "${name}": failed to parse PDF — ${err instanceof Error ? err.message : String(err)}`);
+            });
+            const requested = inputs.page;
+            if (requested !== undefined && requested > doc.numPages) {
+                throw new InvokeError("ERR_INVALID_INPUT", `Pdf.Text "${name}": page ${requested} is out of range; document has ${doc.numPages} page(s).`);
+            }
+            const first = requested ?? 1;
+            const last = requested ?? doc.numPages;
+            const pages = [];
+            for (let n = first; n <= last; n++) {
+                const page = await doc.getPage(n);
+                try {
+                    pages.push(renderTextContent(await page.getTextContent()));
+                }
+                finally {
+                    page.cleanup();
+                }
+            }
+            return { text: pages.join("\n"), pages, pageCount: doc.numPages };
+        }
+        finally {
+            await task.destroy();
+        }
+    }
+    snapshot() {
+        return {};
+    }
+}
+function renderTextContent(content) {
+    let out = "";
+    for (const raw of content.items) {
+        const item = raw;
+        if (typeof item.str !== "string")
+            continue;
+        out += item.str;
+        if (item.hasEOL)
+            out += "\n";
+    }
+    return out;
+}
+export function register() { }
+export async function create(resource, _ctx) {
+    return new PdfText(resource);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@telorun/pdf",
-  "version": "0.3.0",
-  "description": "PDF primitives — rasterize pages to PNG images and author editable AcroForm fields.",
+  "version": "0.8.0",
+  "description": "PDF primitives — rasterize pages to PNG images, read the text a document renders, and author editable AcroForm fields.",
   "keywords": [
     "telo",
     "pdf",
@@ -38,6 +38,11 @@
       "types": "./dist/form-fields-controller.d.ts",
       "bun": "./src/form-fields-controller.ts",
       "import": "./dist/form-fields-controller.js"
+    },
+    "./text": {
+      "types": "./dist/text-controller.d.ts",
+      "bun": "./src/text-controller.ts",
+      "import": "./dist/text-controller.js"
     }
   },
   "files": [
@@ -47,7 +52,7 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
-    "@telorun/sdk": "0.61.0"
+    "@telorun/sdk": "0.82.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/text-controller.ts

@@ -0,0 +1,117 @@
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+// The legacy build is pdf.js's Node target — the same one the rasterizer loads.
+import { getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
+import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
+import { InvokeError } from "@telorun/sdk";
+
+const PDFJS_ROOT = dirname(createRequire(import.meta.url).resolve("pdfjs-dist/package.json"));
+const ASSET_OPTIONS = {
+  standardFontDataUrl: join(PDFJS_ROOT, "standard_fonts") + "/",
+  cMapUrl: join(PDFJS_ROOT, "cmaps") + "/",
+  cMapPacked: true,
+  wasmUrl: join(PDFJS_ROOT, "wasm") + "/",
+};
+
+interface TextResource {
+  metadata: { name: string; module?: string };
+}
+
+interface TextInputs {
+  data: Uint8Array;
+  page?: number;
+}
+
+interface TextOutputs {
+  text: string;
+  pages: string[];
+  pageCount: number;
+}
+
+/**
+ * Reads the text a PDF actually renders.
+ *
+ * The counterpart to `Pdf.Rasterizer`: rasterizing answers *what does this page
+ * look like*, which is a question about pixels and moves with the platform's
+ * font rasterization. This answers *what does it say*, which is what an
+ * assertion about a generated document needs — a rendered page image cannot
+ * tell a correct table from an empty one.
+ *
+ * Items are joined in the order pdf.js reports them, with a line break at each
+ * end-of-line marker. That is reading order for ordinary flowed content; it is
+ * not a layout reconstruction, and a multi-column page reads column by column
+ * the way the producer wrote it.
+ */
+class PdfText implements ResourceInstance<TextInputs, TextOutputs> {
+  constructor(private readonly resource: TextResource) {}
+
+  async invoke(inputs: TextInputs): Promise<TextOutputs> {
+    const name = this.resource.metadata.name;
+    const data = inputs?.data;
+    if (!(data instanceof Uint8Array)) {
+      throw new InvokeError(
+        "ERR_INVALID_INPUT",
+        `Pdf.Text "${name}": 'data' must be a Uint8Array of PDF bytes; got ${typeof data}.`,
+      );
+    }
+
+    // pdf.js transfers the buffer it is given — hand it a copy so the caller's
+    // bytes survive a second read.
+    const task = getDocument({ data: new Uint8Array(data), ...ASSET_OPTIONS });
+    try {
+      const doc = await task.promise.catch((err: unknown) => {
+        throw new InvokeError(
+          "ERR_INVALID_INPUT",
+          `Pdf.Text "${name}": failed to parse PDF — ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+      const requested = inputs.page;
+      if (requested !== undefined && requested > doc.numPages) {
+        throw new InvokeError(
+          "ERR_INVALID_INPUT",
+          `Pdf.Text "${name}": page ${requested} is out of range; document has ${doc.numPages} page(s).`,
+        );
+      }
+      const first = requested ?? 1;
+      const last = requested ?? doc.numPages;
+      const pages: string[] = [];
+      for (let n = first; n <= last; n++) {
+        const page = await doc.getPage(n);
+        try {
+          pages.push(renderTextContent(await page.getTextContent()));
+        } finally {
+          page.cleanup();
+        }
+      }
+      return { text: pages.join("\n"), pages, pageCount: doc.numPages };
+    } finally {
+      await task.destroy();
+    }
+  }
+
+  snapshot(): Record<string, unknown> {
+    return {};
+  }
+}
+
+interface TextItem {
+  str?: string;
+  hasEOL?: boolean;
+}
+
+function renderTextContent(content: { items: unknown[] }): string {
+  let out = "";
+  for (const raw of content.items) {
+    const item = raw as TextItem;
+    if (typeof item.str !== "string") continue;
+    out += item.str;
+    if (item.hasEOL) out += "\n";
+  }
+  return out;
+}
+
+export function register(): void {}
+
+export async function create(resource: TextResource, _ctx: ResourceContext): Promise<PdfText> {
+  return new PdfText(resource);
+}