@laminapdf/sdk 0.2.0-alpha.2 → 0.2.0-alpha.4

package/docs/pages/start/first-pdf.md

@@ -0,0 +1,81 @@
+---
+title: "Your first PDF"
+description: "Write hello.pdf from Node in five minutes."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/start/first-pdf/"
+---
+
+# Your first PDF
+
+Write hello.pdf from Node in five minutes.
+
+You'll write `hello.pdf`, one A4 page that says "Hello, world!", from a short Node script. It takes about five minutes.
+
+## Make a project
+
+You need Node 24.2 or newer, which runs `.ts` files directly. Create a folder and install `@laminapdf/sdk` from npm:
+
+```sh
+mkdir hello-pdf && cd hello-pdf
+npm init -y && npm pkg set type=module
+npm install @laminapdf/sdk@0.2.0-alpha.4
+```
+
+Lamina PDF is in alpha, so the install names the version these docs describe. `@laminapdf/sdk` brings its WebAssembly modules, `@laminapdf/wasm`, with it. [Install](../../pages/install.md) covers other package managers and Rust.
+
+## Write the page
+
+Save this app as `hello.ts`. It loads Lamina PDF, builds the page and writes it to `hello.pdf`:
+
+**TypeScript**
+
+`packages/sdk/examples/quick-start/node.ts`:
+
+```ts
+// Builds a one-page PDF that says "Hello, world!" and writes it to hello.pdf, in Node.
+import { writeFile } from "node:fs/promises";
+import { Builder, type BuilderOptions, Font, init } from "@laminapdf/sdk";
+
+/** The space between the page's edge and the text, in points (72 points = 1 inch). */
+const MARGIN = 72;
+/** The text's size in points; its baseline sits this far below the margin. */
+const FONT_SIZE = 24;
+
+/** Builds the page and hands its bytes to `save`, which writes hello.pdf unless you pass another `save` function. */
+export async function hello(
+  save: (pdf: Uint8Array) => void | Promise<void> = (pdf) => writeFile("hello.pdf", pdf),
+  options: BuilderOptions = {},
+): Promise<void> {
+  await init({ text: true });
+  using builder = new Builder(options);
+  const page = builder.page("A4");
+  // Points from the page's top-left corner, y down; the text's baseline sits FONT_SIZE points below the margin.
+  page.surface().text("Hello, world!", {
+    font: Font.standard("Helvetica"),
+    size: FONT_SIZE,
+    at: [MARGIN, MARGIN + FONT_SIZE],
+  });
+  page.finish();
+  using doc = builder.finish();
+  await save(doc.save());
+}
+
+// `node hello.ts` runs it (Node 24.2 or newer); imported, it only exports `hello`.
+if (import.meta.main) await hello();
+```
+
+**Result:** [hello.pdf](https://docs.laminapdf.com/examples/pdf/hello.pdf)
+
+## Run it
+
+```sh
+node hello.ts
+```
+
+Node runs the TypeScript file as it is. Open `hello.pdf` in any PDF viewer: one page, with "Hello, world!" near its top-left corner.
+
+## What happened
+
+`init({ text: true })` loaded Lamina PDF's text module, the one that draws fonts; after it, every call is synchronous. The builder made an A4 page, drew the text on it and finished into a document, `doc.save()` turned that document into bytes, and `save` wrote them to `hello.pdf`. `using` freed the builder and the document as soon as the function ended.
+
+Next, see [how Lamina PDF thinks about a PDF](../../pages/concepts/how-lamina-thinks.md) and [where things go on a page](../../pages/concepts/pages-and-coordinates.md). To use laminapdf somewhere other than Node, pick [your runtime](../../pages/quick-start/browser.md).

package/docs/pages/troubleshooting.md

@@ -0,0 +1,74 @@
+---
+title: "Troubleshooting"
+description: "The problems people hit with Lamina PDF, from a missing init() to a signed file that won't save, with the cause and the fix of each."
+version: "0.2.0-alpha.4"
+url: "https://docs.laminapdf.com/troubleshooting/"
+---
+
+# Troubleshooting
+
+The problems people hit with Lamina PDF, from a missing init() to a signed file that won't save, with the cause and the fix of each.
+
+Each entry starts from what you see, then gives the cause and the fix. Errors carry a `code`, and every code has a page that says what to do: search the [error and warning codes](../errors/README.md) for one that isn't here.
+
+## Every call throws `not-initialized`
+
+**Cause:** a function of `@laminapdf/sdk` ran before `init()` finished loading the WebAssembly.
+
+**Fix:** `await init()` once, before anything else. After it, every call is synchronous. See [`not-initialized`](../errors/not-initialized.md).
+
+## Drawing text throws `text-module-not-loaded`
+
+**Cause:** the builder lives in the base module, which has no fonts or text. Lamina PDF loads only the modules you ask for, so a page downloads only what it uses.
+
+**Fix:** load the text module before you create the builder: `init({ text: true })`, or `loadText()` after `init()`. See [`text-module-not-loaded`](../errors/text-module-not-loaded.md) and [Text and fonts](../pages/guides/fonts-and-text.md).
+
+## Reading text throws `extract-module-not-loaded`
+
+**Cause:** the document was opened in the base module, which can't extract text.
+
+**Fix:** load the extract module, with `init({ extract: true })` or `loadExtract()`, or the text module, before you open the document. A Cloudflare Worker can't fetch it, so import it and pass it: `import extract from "@laminapdf/wasm/lamina_pdf_extract.wasm"`, then `await loadExtract(extract)`. See [`extract-module-not-loaded`](../errors/extract-module-not-loaded.md).
+
+## The browser blocks the WebAssembly
+
+**Cause:** the page's Content Security Policy doesn't allow compiling WebAssembly.
+
+**Fix:** add `'wasm-unsafe-eval'` to its `script-src`. Lamina PDF needs nothing else from the policy. See [Browser and bundlers](../pages/quick-start/browser.md).
+
+## `init()` fails in a Vite app
+
+**Cause:** Vite pre-bundles dependencies into its own cache, and the `.wasm` files don't move with the JavaScript that loads them.
+
+**Fix:** exclude the package from pre-bundling: `optimizeDeps: { exclude: ["@laminapdf/sdk"] }` in `vite.config.ts`. A Web Worker that uses `@laminapdf/sdk/worker` needs the same setting. See [Browser and bundlers](../pages/quick-start/browser.md).
+
+## `init()` fails in a Cloudflare Worker
+
+**Cause:** Cloudflare Workers can't compile WebAssembly at run time, so `init()` can't build the modules from bytes or a URL.
+
+**Fix:** let Wrangler bundle the package, and call `init()` without a URL or bytes. Wrangler picks the package's entry for Cloudflare Workers, which imports the `.wasm` files as compiled modules. See [Cloudflare Workers](../pages/quick-start/workers.md).
+
+## Opening a file fails with `password-required` or `wrong-password`
+
+**Cause:** the file is encrypted. `password-required` means you passed no password, and `wrong-password` means the one you passed matches neither of the file's passwords.
+
+**Fix:** ask your user for the password and open the file again with it. Nothing else has changed. See [Open password-protected files](../pages/guides/password-protected-files.md).
+
+## A signed file won't save
+
+**Cause:** saving would break a signature, so the save fails with `would-invalidate-signatures`. A signed file saves only incrementally, and only with the edits its signatures allow.
+
+**Fix:** keep the default save mode and make only edits the signatures allow. To save anyway, ask your user first, then pass `invalidateSignatures: true`. See [Save a PDF](../pages/guides/save-a-pdf.md) and [`would-invalidate-signatures`](../errors/would-invalidate-signatures.md).
+
+## Memory keeps growing
+
+**Cause:** documents and builders live in WebAssembly memory, and the garbage collector frees them late: too late for a long-running page or server. WebAssembly memory also never shrinks, so one large file leaves it large.
+
+**Fix:** free each one when you're done: `using doc = …` frees it at the end of the block, and `doc.free()` at once. A call on a freed one throws `disposed`. To give grown memory back, call `reset()` while no document is in use: every module starts afresh, and handles from before throw `instance-reset`. See [You free what you create](../pages/concepts/how-lamina-thinks.md#you-free-what-you-create).
+
+## A call throws `out-of-memory` or `wasm-trap`
+
+**Cause:** the WebAssembly module ran out of memory (it may grow to 2 GiB), or it trapped on a bug in Lamina PDF. Either leaves the module's memory half-written, so Lamina PDF replaces the module's instance before the next call.
+
+**Fix:** open the document again from its bytes: documents, pages and builders from the old instance throw `instance-reset`. For `out-of-memory`, keep fewer documents open at once and lower the open limits for files you don't trust. Report a `wasm-trap` with the file that causes it. See [`out-of-memory`](../errors/out-of-memory.md) and [`wasm-trap`](../errors/wasm-trap.md).
+
+Next: the [error and warning codes](../errors/README.md), with what each one means and what to do.

package/docs/renames.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "./renames.schema.json",
+  "schema": "laminapdf.renames/1",
+  "renames": [
+    {
+      "from": "laminapdf::extract::TextRun",
+      "to": "laminapdf::extract::PageTextRun",
+      "surface": "rust",
+      "kind": "type",
+      "since": "0.2.0",
+      "note": "An extracted run; TextRun now means only drawn text."
+    },
+    {
+      "from": "laminapdf_text::extract::TextRun",
+      "to": "laminapdf_text::PageTextRun",
+      "surface": "rust",
+      "kind": "type",
+      "since": "0.2.0",
+      "note": "laminapdf-text's extract module is private; its items are at the crate root."
+    },
+    {
+      "from": "laminapdf_text::agl::to_unicode",
+      "to": "laminapdf_text::glyph_name_to_unicode",
+      "surface": "rust",
+      "kind": "function",
+      "since": "0.2.0",
+      "note": "laminapdf-text's agl module is private."
+    },
+    {
+      "from": "laminapdf_text::Tag",
+      "to": "laminapdf_text::OpenTypeTag",
+      "surface": "rust",
+      "kind": "type",
+      "since": "0.2.0",
+      "note": "The façade exports it as laminapdf::OpenTypeTag, for Font::instance."
+    },
+    {
+      "from": "laminapdf_build::Font",
+      "to": "laminapdf_build::FontHandle",
+      "surface": "rust",
+      "kind": "type",
+      "since": "0.2.0",
+      "note": "A font registered with a builder; laminapdf::Font is the font program."
+    },
+    {
+      "from": "laminapdf_content::Color",
+      "to": "laminapdf_content::CurrentColor",
+      "surface": "rust",
+      "kind": "type",
+      "since": "0.2.0",
+      "note": "The content reader's current colour: a colour space, its components and a pattern."
+    },
+    {
+      "from": "laminapdf_content::Matrix::multiply",
+      "to": "laminapdf_model::Matrix::then",
+      "surface": "rust",
+      "kind": "method",
+      "since": "0.2.0",
+      "note": "One Matrix for building and reading; then applies the receiver first."
+    },
+    {
+      "from": "laminapdf_content::Matrix::transform_point",
+      "to": "laminapdf_model::Matrix::apply",
+      "surface": "rust",
+      "kind": "method",
+      "since": "0.2.0",
+      "note": ""
+    },
+    {
+      "from": "laminapdf::CosError",
+      "to": "laminapdf::Error::error_code",
+      "surface": "rust",
+      "kind": "type",
+      "since": "0.2.0",
+      "note": "The crates' errors are opaque behind Error::Core: match on error_code() instead."
+    },
+    {
+      "from": "laminapdf_source::pending_ranges",
+      "to": "laminapdf::Error::pending_ranges",
+      "surface": "rust",
+      "kind": "function",
+      "since": "0.2.0",
+      "note": ""
+    }
+  ]
+}

package/docs/schemas/error.schema.json

@@ -0,0 +1,322 @@
+{
+  "$defs": {
+    "error": {
+      "properties": {
+        "code": {
+          "description": "The stable kebab-case code (fixtures/codes.json).",
+          "enum": [
+            "not-pdf",
+            "missing-root",
+            "reference-cycle",
+            "limit-exceeded",
+            "strict",
+            "data-pending",
+            "source",
+            "type",
+            "invalid-structure",
+            "unset-object",
+            "repaired-base",
+            "encrypted-base",
+            "password-required",
+            "wrong-password",
+            "unsupported-security-handler",
+            "unexpected-eof",
+            "syntax",
+            "unsupported-filter",
+            "decompress",
+            "nested-transaction",
+            "no-transaction",
+            "unknown-page",
+            "direct-page",
+            "unsupported-version",
+            "invalid-op-log",
+            "saved-not-rebased",
+            "no-pending-save",
+            "sink",
+            "not-rebased",
+            "sink-not-empty",
+            "would-invalidate-signatures",
+            "requires-rewrite",
+            "invalid-font",
+            "collection-index",
+            "unknown-axis",
+            "font-not-embeddable",
+            "missing-glyph",
+            "glyph-out-of-range",
+            "unknown-font",
+            "subset-failed",
+            "invalid-axis-value",
+            "wrong-document",
+            "invalid-feature",
+            "invalid-text-range",
+            "invalid-spans",
+            "unsupported-layout-option",
+            "font-mismatch",
+            "encoding-full",
+            "font-not-shapable",
+            "invalid-image",
+            "unsupported-image",
+            "image-too-large",
+            "image-data-length",
+            "invalid-icc-profile",
+            "color-components",
+            "invalid-color",
+            "invalid-geometry",
+            "text-overflow",
+            "page-index-out-of-range",
+            "unknown-destination",
+            "invalid-page-labels",
+            "tag-element-not-open",
+            "tag-element-unclosed",
+            "profile-version-conflict",
+            "missing-title",
+            "missing-lang",
+            "missing-alt-text",
+            "untagged-content",
+            "heading-level-skipped",
+            "unnumbered-heading-misused",
+            "invalid-structure-nesting",
+            "link-without-structure",
+            "link-without-contents",
+            "font-not-embedded",
+            "glyph-without-unicode",
+            "device-color-without-output-intent",
+            "embedded-file-forbidden",
+            "embedded-file-without-mime-type",
+            "flow-content-too-large",
+            "flow-layout-unstable",
+            "render-too-large",
+            "render-failed",
+            "render-backend-unavailable",
+            "model-failed",
+            "model-result-unexpected",
+            "model-needs-host",
+            "cancelled",
+            "job-finished",
+            "document-changed",
+            "revision-index-out-of-range",
+            "builder-finished",
+            "disposed",
+            "invalid-argument",
+            "source-budget-exceeded",
+            "unknown-option",
+            "already-initialized",
+            "extract-module-not-loaded",
+            "fetch-failed",
+            "not-initialized",
+            "source-changed",
+            "text-module-not-loaded",
+            "worker-version-mismatch",
+            "worker-crashed",
+            "worker-failed",
+            "wasm-trap",
+            "out-of-memory",
+            "instance-reset",
+            "invalid-command-line",
+            "invalid-page-range",
+            "binary-output-to-terminal",
+            "unknown-code",
+            "overwrite-refused",
+            "input-unreadable",
+            "output-unwritable",
+            "path-outside-roots"
+          ]
+        },
+        "data": {
+          "description": "Code-specific fields, listed on the code's page; the only place document-derived strings appear (untrusted).",
+          "type": "object"
+        },
+        "didYouMean": {
+          "description": "For usage errors: the closest names from lamina's own vocabulary.",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "type": "array"
+        },
+        "docsUrl": {
+          "description": "The code's explain page: base + code + suffix (ADR 0026 §6).",
+          "pattern": "^https:\\/\\/github\\.com\\/laudebugs\\/laminapdf\\/blob\\/main\\/docs\\/errors\\/[a-z0-9-]+\\.md$",
+          "type": "string"
+        },
+        "hint": {
+          "description": "One actionable sentence for this code. Never document text.",
+          "minLength": 1,
+          "type": "string"
+        },
+        "kind": {
+          "$ref": "#/$defs/kind"
+        },
+        "location": {
+          "$ref": "#/$defs/location"
+        },
+        "message": {
+          "description": "One lowercase sentence. Never document text (ADR 0026 §4).",
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "code",
+        "kind",
+        "message",
+        "docsUrl"
+      ],
+      "type": "object"
+    },
+    "kind": {
+      "description": "The nine kinds of ADR 0026 §2.",
+      "enum": [
+        "input",
+        "io",
+        "unsupported",
+        "limit",
+        "security",
+        "usage",
+        "state",
+        "cancelled",
+        "internal"
+      ]
+    },
+    "location": {
+      "additionalProperties": false,
+      "dependentRequired": {
+        "streamOffset": [
+          "object"
+        ]
+      },
+      "description": "Where the problem is (ADR 0026 §1.1); every value is lamina-made.",
+      "properties": {
+        "id": {
+          "description": "A LaminaPdfId (p12.0).",
+          "type": "string"
+        },
+        "object": {
+          "description": "Object number of the indirect object the problem is in or at.",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "offset": {
+          "description": "Byte offset in the input file.",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "pageIndex": {
+          "description": "0-based page index (ADR 0027 §6).",
+          "minimum": 0,
+          "type": "integer"
+        },
+        "streamOffset": {
+          "description": "Byte offset in the decoded data of `object`.",
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "type": "object"
+    },
+    "warning": {
+      "properties": {
+        "code": {
+          "description": "The stable kebab-case code (fixtures/codes.json).",
+          "enum": [
+            "missing-header",
+            "xref-repaired",
+            "xrefstm-ignored",
+            "stream-length-recovered",
+            "stale-generation",
+            "page-tree-node-skipped",
+            "page-count-mismatch",
+            "flate-truncated",
+            "objstm-index-mismatch",
+            "object-number-out-of-range",
+            "aes-padding-invalid",
+            "perms-mismatch",
+            "warnings-truncated",
+            "invalid-box",
+            "invalid-rotate",
+            "name-tree-node-skipped",
+            "outline-cycle",
+            "outline-item-skipped",
+            "invalid-date",
+            "invalid-page-label",
+            "invalid-entry",
+            "content-unknown-operator",
+            "content-bad-operands",
+            "content-unbalanced-q",
+            "content-unbalanced-bt",
+            "content-unbalanced-marked",
+            "content-syntax",
+            "content-resource-missing",
+            "inline-image-unterminated",
+            "xobject-cycle",
+            "content-path-unpainted",
+            "font-invalid",
+            "cmap-invalid",
+            "unmapped-glyph",
+            "extract-limit-blocks",
+            "extract-reading-order-ambiguous",
+            "extract-table-ambiguous",
+            "extract-table-limit",
+            "extract-struct-tree-ignored",
+            "extract-untagged-content",
+            "extract-needs-ocr",
+            "extract-column-order-uncertain",
+            "tounicode-conflict",
+            "whole-font-rebuilt",
+            "flow-keep-broken",
+            "markdown-html-ignored",
+            "markdown-image-missing",
+            "covered-text",
+            "redaction-not-applied",
+            "text-in-earlier-revision"
+          ]
+        },
+        "data": {
+          "description": "Code-specific fields, listed on the code's page; the only place document-derived strings appear (untrusted).",
+          "type": "object"
+        },
+        "didYouMean": false,
+        "docsUrl": {
+          "description": "The code's explain page: base + code + suffix (ADR 0026 §6).",
+          "pattern": "^https:\\/\\/github\\.com\\/laudebugs\\/laminapdf\\/blob\\/main\\/docs\\/errors\\/[a-z0-9-]+\\.md$",
+          "type": "string"
+        },
+        "hint": {
+          "description": "One actionable sentence for this code. Never document text.",
+          "minLength": 1,
+          "type": "string"
+        },
+        "kind": {
+          "$ref": "#/$defs/kind"
+        },
+        "location": {
+          "$ref": "#/$defs/location"
+        },
+        "message": {
+          "description": "One lowercase sentence. Never document text (ADR 0026 §4).",
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "code",
+        "kind",
+        "message",
+        "docsUrl"
+      ],
+      "type": "object"
+    }
+  },
+  "$id": "https://github.com/laudebugs/laminapdf/blob/main/packages/sdk/schemas/error.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "description": "An error or warning of every lamina surface (ADR 0026 §1): camelCase keys, optional keys omitted (never null). Generated from fixtures/codes.json by `cargo xtask gen codes`; do not edit. New optional keys may appear within version 1; consumers ignore unknown keys.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/error"
+    },
+    {
+      "$ref": "#/$defs/warning"
+    }
+  ],
+  "title": "laminapdf.error/1"
+}

package/docs/schemas/renames.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.laminapdf.com/schemas/renames-1.json",
+  "title": "laminapdf.renames/1",
+  "description": "What old names in Lamina PDF's APIs became: one entry per renamed, moved or deprecated item, so a coding agent can map old code to the current names.",
+  "type": "object",
+  "required": ["schema", "renames"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "schema": { "const": "laminapdf.renames/1" },
+    "renames": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "surface", "kind", "since", "note"],
+        "additionalProperties": false,
+        "properties": {
+          "from": { "type": "string", "minLength": 1, "description": "The old name, as a path (laminapdf::extract::TextRun) or a TypeScript export (Document.save)." },
+          "to": { "type": "string", "minLength": 1, "description": "The name to use now." },
+          "surface": { "enum": ["rust", "ts", "cli"] },
+          "kind": { "enum": ["type", "function", "method", "field", "module", "option", "command", "flag", "code"] },
+          "since": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[0-9A-Za-z.-]+)?$", "description": "The first version with the new name." },
+          "note": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laminapdf/sdk",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.0-alpha.4",
   "description": "Create, read, edit and save PDFs from TypeScript: Lamina PDF's Rust core as WebAssembly, synchronous after init(), in browsers, Node, Deno, Bun and Cloudflare Workers.",
   "license": "MIT OR Apache-2.0",
   "homepage": "https://laminapdf.com",
@@ -23,6 +23,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "schemas"
   ],
   "exports": {
@@ -64,10 +65,11 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@laminapdf/wasm": "0.2.0-alpha.2"
+    "@laminapdf/wasm": "0.2.0-alpha.4"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
+    "@microsoft/api-extractor": "7.59.4",
     "@types/node": "26.6.5",
     "@vitest/browser-playwright": "5.0.5",
     "ajv": "8.20.0",
@@ -80,6 +82,8 @@
     "vite": "8.3.5",
     "vitest": "5.0.5",
     "wrangler": "4.152.0",
+    "@laminapdf/render-hayro": "0.2.0-alpha.4",
+    "@laminapdf/render": "0.2.0-alpha.4",
     "@laminapdf/test-utils": "0.0.0"
   },
   "publishConfig": {
@@ -88,7 +92,7 @@
   "scripts": {
     "build:wasm": "tsc -p tsconfig.build.json",
     "typecheck:wasm": "tsc --noEmit -p tsconfig.json",
-    "test:wasm": "pnpm run build:wasm && tsc --noEmit -p tsconfig.json && vitest run -c vitest.node.config.ts --project node",
+    "test:wasm": "pnpm run build:wasm && tsc --noEmit -p tsconfig.json && vitest run -c vitest.node.config.ts --project node --project small-memory",
     "lint:package": "publint --strict && attw --pack . --profile esm-only"
   }
 }