@t4h.framework/pdf 0.4.6 → 0.4.7

package/.ai/skills/framework-pdf/SKILL.md

@@ -1,355 +1,117 @@
 ---
 name: framework-pdf
 description: >-
-  Guides correct use of @t4h.framework/pdf in T4H Framework workflows: the
-  `render()` helper, PDF marker components (Document, Page, View, Text, Link,
-  Image, PageNumber), custom fonts, Binary image sources, styling,
-  password-protected PDFs via the `encrypt` option, and the FileSystemClaim
-  the render activity requires. Use when generating PDFs in workflows,
-  building PDF templates with JSX, registering fonts, encrypting PDFs, or
-  working in packages/pdf.
+  Guides the use of @t4h.framework/pdf to generate PDF files in T4H Framework
+  workflows: the render() function, the JSX marker components (Document, Page,
+  View, Text, Link, Image, PageNumber), styles, custom fonts, Binary image
+  sources, password protection with the encrypt option (ProtectionFlags,
+  ProtectionPresets), the FileSystemClaim that render needs, and tests with
+  TestWorkflowEnvironment and mockClaim. Use when a workflow must produce a
+  PDF, an invoice, a report or a statement, when building a PDF template in
+  JSX, or when someone mentions @react-pdf/renderer in a workflow.
 ---
 
 # @t4h.framework/pdf
 
-Declarative PDF rendering for workflows, backed by `@react-pdf/renderer`.
-Package path: `framework/packages/pdf`. Peer dependencies:
-`@t4h.framework/core`, `@t4h.framework/fs`. Regular dependencies: `react`,
-`@react-pdf/renderer`.
+## Render a PDF in a workflow
 
-Import surface:
-
-```typescript
-import {
-  render,
-  Document,
-  Page,
-  View,
-  Text,
-  Link,
-  Image,
-  PageNumber,
-  RenderPDFActivity,
-  ProtectionFlags,
-  ProtectionPresets,
-  type RenderPDFOptions,
-  type RenderPDFInput,
-  type EncryptPDFOptions,
-  type DocumentProps,
-  type PageProps,
-  type ViewProps,
-  type TextProps,
-  type LinkProps,
-  type ImageProps,
-  type PageNumberProps,
-  type DocumentNode,
-  type PDFNode,
-  type PDFStyle,
-} from '@t4h.framework/pdf'
-```
-
-> Workflows use **`render()`** — for everything, including encryption.
-> `@t4h.framework/core/no-framework-activity-in-app` rejects `new` and
-> `extends` on `RenderPDFActivity`.
-
-## Architecture
-
-`Workflow` → `render(<Document>…</Document>, options?)`
-(`History.reconciler(RenderPDFActivity)`) →
-
-1. **`toInput`** (workflow side): the JSX tree is serialized into a plain
-   `DocumentNode` JSON tree that is stored in the workflow history. User
-   function components, fragments, arrays, and conditionals are flattened
-   here; only marker components and strings remain.
-2. **`run`** (activity side): `Binary` image and font sources are read through
-   their claims and inlined as `data:` URIs on the calling thread, then the
-   resolved tree is handed to a **worker thread** (pool size
-   `PDF_RENDER_CONCURRENCY`, default `1`, created on first render, idle workers
-   unrefed) that registers fonts once per process, converts the `DocumentNode`
-   tree back into real `@react-pdf/renderer` elements and renders it to a
-   buffer. The buffer is written through **`FileSystemClaim`** at
-   `pdf/${activityId}.pdf`. With the `encrypt` option, a password-protected
-   copy (AES-128, `%PDF-1.6`) is written from the same layout at
-   `pdf/${activityId}-encrypted.pdf` — no second layout pass, no re-encryption
-   of the finished file. A render therefore blocks the event loop of the
-   calling process for milliseconds, not for the whole document.
-3. The activity returns the **`Binary`** the claim produced — a reference to
-   the stored file, not in-memory bytes. Replay-safe by construction. With
-   `encrypt`, it returns the `[original, encrypted]` pair instead, and the
-   `render` return type narrows automatically based on the options.
-
----
-
-## Claims
-
-### FileSystemClaim (required)
-
-The render activity persists the PDF through `fs`. Any workflow that calls
-`render()` needs a `FileSystemClaim` provider:
-
-```typescript
-{ provide: FileSystemClaim, value: new MyFileSystemClaimImpl() }
-```
-
-Tests mock its `write` to return a `Binary` (see **Testing**).
-
----
-
-## Marker components
-
-The components exported by this package are **markers**: they exist only as
-type-safe JSX tags inside a tree passed to `render()`. JSX never invokes
-them — the serializer recognizes them by reference. A marker called as a
-function (`Image({ src })`) throws.
-
-| Component | Props (beyond `NodeProps`) | Notes |
-|-----------|---------------------------|-------|
-| `Document` | `title? author? subject? creator? producer? language?` | Root. Children must be `Page` elements |
-| `Page` | `size? orientation? style? wrap? dpi?` | `size` defaults to A4. Overflowing content paginates automatically |
-| `View` | — | Flex container, analogous to a `<div>` |
-| `Text` | — | All raw strings must live inside a `Text` |
-| `Link` | `href` (required) | Hyperlink; serialized `href` becomes react-pdf's `src` internally |
-| `Image` | `src: string \| Binary` (required) | URL, `data:` URI, or `Binary` with an image `contentType` |
-| `PageNumber` | `format?` | Resolves at layout time. Tokens: `{pageNumber}`, `{totalPages}`. Default `'{pageNumber}'`. Combine with `fixed` for running footers |
-
-`NodeProps` (shared by every node inside a page): `style`, `fixed` (repeat on
-every page — headers/footers), `break` (force page break before the node),
-`wrap` (allow splitting across pages, default `true`), `minPresenceAhead`
-(move to next page unless this many points remain — avoids orphaned headings).
-
-**Valid tree.** `render()` throws a `TypeError` for a tree that breaks one
-of these rules:
-
-- One `Document` root, with only `Page` children.
-- Raw text only inside `Text` or `Link`.
-- Inside `Text`: only text, `Text`, `Link` and `PageNumber`.
-- Inside `Page` and `View`: only the marker components of this package.
-
-User function components, `.map()` arrays, fragments, and conditional
-rendering (`null` / `false` / `undefined`) work exactly like normal React —
-they are evaluated and flattened during serialization.
-
----
-
-## Styling
-
-`PDFStyle` is a loose camelCase record (`fontSize`, `flexDirection`,
-`marginTop`, …). Layout is the CSS **flex model only** — no grid, no float.
-Values: numbers are points; strings accept units (`'2cm'`, `'5mm'`, `'50%'`).
-`style` also accepts an array of styles.
-
-Text styles (`color`, `fontSize`, `fontFamily`, …) **inherit** through the
-tree, so defaults belong on `Page`:
+1. Build the tree with the markers of `@t4h.framework/pdf`.
+2. Call `render` and `await` it. It returns a `Binary`, not bytes.
+3. Pass the `Binary` to the next activity (upload, e-mail, return value).
 
 ```tsx
-<Page size='A4' style={{ padding: '2cm', fontSize: 12, color: '#00513a' }}>
+import { Document, Page, Text, View, render } from '@t4h.framework/pdf'
+
+const pdf = await render(
+  <Document title='Invoice'>
+    <Page size='A4' style={{ padding: '2cm', fontSize: 12 }}>
+      {items.map(item => (
+        <View key={item.id} style={{ flexDirection: 'row' }}>
+          <Text>{item.label}</Text>
+        </View>
+      ))}
+    </Page>
+  </Document>,
+)
 ```
 
-Built-in fonts (no registration needed): Helvetica, Courier, Times-Roman —
-with `fontWeight: 'bold'` / `fontStyle: 'italic'` variants.
-
----
-
-## Rendering in a workflow
+Your own function components, fragments, `.map()` and conditionals work as in
+React.
+
+## Traps
+
+- Import `Document`, `Page`, `Text` and the other markers from
+  `@t4h.framework/pdf`, never from `@react-pdf/renderer`. A react-pdf component
+  in the tree throws a `TypeError`. Never call a marker as a function.
+- One `Document` root with only `Page` children. Raw text only in `Text` or
+  `Link`. Only text, `Text`, `Link` and `PageNumber` inside `Text`.
+- Never use `new RenderPDFActivity()` or extend it. The lint rule
+  `no-framework-activity-in-app` reports it. Use `render` for everything,
+  encryption included.
+- The runtime must provide a `FileSystemClaim` (from `@t4h.framework/fs`).
+  With no provider, `render` throws `ClaimProviderNotFoundException`.
+- Styles use the flex model only: no grid, no float. Numbers are points;
+  strings take units (`'2cm'`, `'50%'`). Put text defaults on `Page`: they
+  inherit.
+- Use a `Binary` as `Image src` or font source for private files and for
+  stable replays. A URL is fetched at each render and cannot authenticate.
+  Images: PNG or JPEG.
+- Fonts: TTF or WOFF, never WOFF2 (Google Fonts links often point to WOFF2).
+- With `encrypt`, `render` returns `[original, encrypted]`. When `protection`
+  is omitted, only `ProtectionFlags.Print` is granted. Viewers honor the
+  permission flags, but they are not cryptographic: only the password
+  protects.
+
+## Fonts and encryption
 
 ```tsx
-import { Workflow } from '@t4h.framework/core'
-import { Document, Page, PageNumber, Text, View, render } from '@t4h.framework/pdf'
-
-function Header({ title }: { title: string }) {
-  return (
-    <View style={{ borderBottom: '1 solid #333', marginBottom: 16 }}>
-      <Text style={{ fontSize: 18 }}>{title}</Text>
-    </View>
-  )
-}
-
-export const invoice = new Workflow({ id: 'invoice' }, async () => {
-  const pdf = await render(
-    <Document title='Invoice'>
-      <Page size='A4' style={{ padding: '2cm', fontSize: 12 }}>
-        <Header title='Invoice #42' />
-        {items.map(item => (
-          <View key={item.id} style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
-            <Text>{item.label}</Text>
-            <Text>{item.total}</Text>
-          </View>
-        ))}
-        <PageNumber
-          fixed
-          format='{pageNumber}/{totalPages}'
-          style={{ position: 'absolute', bottom: 24, right: '2cm' }}
-        />
-      </Page>
-    </Document>,
-  )
-
-  // pdf is a Binary — pass it to other activities, e.g. an http form upload:
-  // await http.post(url, { form: { file: pdf } })
-})
-```
-
-The returned `Binary` exposes `contentType` (`application/pdf`),
-`contentLength`, and `stream()`.
-
----
-
-## Images
-
-`Image src` accepts three shapes:
-
-- **URL string** — fetched by react-pdf at layout time. Simple, but the fetch
-  happens on every render/replay and cannot authenticate.
-- **`data:` URI string** — for small assets bundled with the app.
-- **`Binary`** — the replay-safe choice for anything private or that must stay
-  byte-identical across replays. The bytes are inlined as a `data:` URI on the
-  activity side. Typical source: an `http` response body
-  (`response.body.binary`) or any other claim-produced `Binary`.
-
-Supported formats: PNG and JPEG.
+import { ProtectionPresets, render } from '@t4h.framework/pdf'
 
----
-
-## Fonts
-
-`render(element, { fonts })` — an object keyed by **family name**. The value
-is either a bare source (registers the regular 400/normal variant) or an
-array of variants:
-
-```tsx
-const pdf = await render(<Doc />, {
+const [original, encrypted] = await render(<Invoice />, {
   fonts: {
-    // bare source: string URL or Binary
-    Inter: 'https://cdn.example.com/Inter-Regular.ttf',
-    Geometric: fontResponse.body.binary,
-
-    // multiple weights/styles under one family
-    Roboto: [
-      { src: robotoRegular.body.binary },
-      { src: robotoBold.body.binary, weight: 700 },
-      { src: robotoItalic.body.binary, style: 'italic' },
-    ],
+    Roboto: [{ src: robotoRegular }, { src: robotoBold, weight: 700 }],
   },
+  encrypt: { password: '1234', protection: ProtectionPresets.ReadOnly },
 })
 ```
 
-Select variants in styles with `fontFamily` + `fontWeight` + `fontStyle`.
-Weights are `100–900`; styles `'normal' | 'italic'`.
-
-Rules of thumb:
-
-- **TTF and WOFF only** — react-pdf cannot parse WOFF2 (Google Fonts links
-  often point to WOFF2; pick the TTF URL).
-- Prefer `Binary` for private/licensed fonts and replay stability; a URL is a
-  mutable external reference fetched at layout time.
-- Fonts registered per render; same-family re-registration is safe.
-
----
-
-## Encryption
-
-`render(element, { encrypt })` also persists a password-protected copy and
-resolves with an `[original, encrypted]` tuple — the return type narrows
-automatically:
+## Running footer
 
 ```tsx
-const [original, encrypted] = await render(<Invoice />, {
-  encrypt: {
-    password: customer.documentNumber,
-    protection: ProtectionPresets.ReadOnly,
-  },
-})
+<PageNumber
+  fixed
+  format='{pageNumber}/{totalPages}'
+  style={{ position: 'absolute', bottom: 24, right: '2cm' }}
+/>
 ```
 
-- `password`: a bare string (same password opens and owns the file) or
-  `{ user, owner }` for a distinct owner password that bypasses permission
-  restrictions.
-- `protection`: a `ProtectionFlags` bitmask granted to whoever opens with the
-  user password. Combine flags with `|` (`Print`, `Modify`, `CopyAndExtract`,
-  `AnnotateAndFill`, `FillForms`, `ExtractForAccessibility`, `Assemble`,
-  `PrintHighResolution`) or use a preset: `ProtectionPresets.ReadOnly`
-  (view + print only — invoices, statements) or `ProtectionPresets.All`.
-- Permission flags are honored by PDF viewers, **not enforced
-  cryptographically** — the open password is the only real protection.
-- Encryption is available only through `render`'s `encrypt` option.
-
----
-
-## Testing
+## Test
 
-Test the **workflow** with `TestWorkflowEnvironment` from
-`@t4h.framework/core/testing`, mocking the single claim the render activity
-uses: `FileSystemClaim`. See the **framework-workflow-testing** skill for the
-harness API. The render runs in a worker in tests too, so the first render in a
-test file pays for the thread starting up (around 400 ms).
+Mock `FileSystemClaim.write`. It receives the path (`pdf/<id>.pdf`) and the
+rendered `Buffer`; return any `Binary` stub. A class that extends `Binary` is
+allowed in test files only.
 
 ```typescript
-import { Readable } from 'node:stream'
-import { Binary } from '@t4h.framework/core'
 import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
 import { FileSystemClaim } from '@t4h.framework/fs'
 
-class MockBinary extends Binary {
-  public readonly contentType = 'application/pdf'
-  public readonly contentLength: number
-
-  constructor(private readonly data: Buffer) {
-    super()
-    this.contentLength = data.byteLength
-  }
-
-  public stream() {
-    return Readable.from(this.data)
-  }
-}
-
-const mockWrite = vi.fn().mockImplementation(async (_path, pdf: Buffer) => {
-  return new MockBinary(pdf)
-})
-
+const write = vi.fn(async (path: string, pdf: Buffer) => storedBinary)
 const env = TestWorkflowEnvironment.create({ now: 0 })
 
-await env.execute(workflow, input, {
-  claims: [mockClaim(FileSystemClaim, { write: mockWrite, read: vi.fn() })],
+await env.execute(invoice, undefined, {
+  claims: [mockClaim(FileSystemClaim, { write })],
 })
 
-// The activity hands the rendered buffer to fs.write — assert on it:
-const [path, pdf] = mockWrite.mock.calls[0]
-expect(path).toMatch(/^pdf\/.+\.pdf$/)
+const [, pdf] = write.mock.calls[0]
 expect(pdf.subarray(0, 5).toString()).toBe('%PDF-')
 ```
 
-For helper-level tests (serialization, element mapping, fonts), see
-`src/helpers/__tests__/` — they assert on the `DocumentNode` JSON shape and on
-react-pdf element trees without rendering.
-
----
-
-## Checklist for agents
+The render runs in a worker thread, so the first render in a test file takes
+about 400 ms.
 
-1. In workflows, **always** use **`render()`**.
-2. Build templates with the **marker components from this package**.
-   `render()` throws a `TypeError` for a `@react-pdf/renderer` component, a
-   marker called as a function throws, and the **Valid tree** rules above
-   apply.
-3. Provide **`FileSystemClaim`** in the runtime (or mock it in tests). A
-   missing provider throws `ClaimProviderNotFoundException`.
-4. Prefer **`Binary`** sources for images and fonts that must be private or
-   replay-stable; URLs are fetched at layout time on every render.
-5. Fonts: object keyed by family, **TTF/WOFF only**, select variants via
-   `fontFamily`/`fontWeight`/`fontStyle`.
-6. Style with the **flex model** (`PDFStyle`, camelCase, points or unit
-   strings); put inheritable text defaults on `Page`.
-7. Use `fixed` + absolute positioning for running headers/footers and
-   `PageNumber` for pagination stamps.
-8. Password-protect PDFs via `render`'s `encrypt` option — it returns
-   `[original, encrypted]`. Permission flags are viewer-honored, not
-   cryptographic.
-9. Test workflows with **`TestWorkflowEnvironment`** + **`mockClaim`**,
-   asserting the `%PDF-` magic bytes on the `fs.write` call.
-10. The package exports only its entry, so a deep import into `helpers/` or
-    `tools/` fails in `tsc`.
+## Reference
 
-See also: **framework-workflow-testing** for the test harness;
-**framework-fs** for `FileSystemClaim`; **framework-http** for fetching
-`Binary` assets (images, fonts) used in templates.
+- Guide: https://tech4humans-brasil.github.io/framework/pdf/
+- `FileSystemClaim`: https://tech4humans-brasil.github.io/framework/fs/
+- Workflow testing: https://tech4humans-brasil.github.io/framework/core/testing
+- Types: `node_modules/@t4h.framework/pdf/dist/pdf.d.ts`

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @t4h.framework/pdf
 
+## 0.4.7
+
+### Patch Changes
+
+- [#257](https://github.com/tech4humans-brasil/framework/pull/257) [`586bfb4`](https://github.com/tech4humans-brasil/framework/commit/586bfb4663f4a478527ee0c8db360603f034d615) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The pdf README is now short and links to the site, and the skill keeps only the traps and the default steps. The docs no longer describe a `PDF_RENDER_CONCURRENCY` variable, and they give the default `protection` of `encrypt`.
+
 ## 0.4.6
 
 ### Patch Changes

package/README.md

@@ -1,25 +1,18 @@
 # @t4h.framework/pdf
 
-Declarative PDF rendering for workflows. Build documents with JSX components, render them replay-safely through the workflow history, and get back a `Binary` persisted via the filesystem claim. Backed by [`@react-pdf/renderer`](https://react-pdf.org).
+Declarative PDF rendering for T4H Framework workflows. You write the document
+as JSX with the marker components of this package, and `render` gives back a
+`Binary` that it stores through the `FileSystemClaim` of `@t4h.framework/fs`.
 
-## Claim
+## Install
 
-### FileSystemClaim
-
-The render activity persists the generated PDF through `FileSystemClaim` (from `@t4h.framework/fs`) and returns the resulting `Binary`. The runtime must provide a concrete implementation.
-
-```typescript
-import { FileSystemClaim } from '@t4h.framework/fs'
-
-// the runtime provides this:
-// { provide: FileSystemClaim, value: new MyFileSystemClaimImpl() }
+```bash
+npm install @t4h.framework/pdf
 ```
 
-## Rendering
-
-### render
+Peer dependencies: `@t4h.framework/core` and `@t4h.framework/fs`.
 
-Renders a JSX tree to a PDF `Binary` through the workflow history. The tree is serialized into the history on the workflow side and rendered on the activity side, so the step is replay-safe.
+## Usage
 
 ```tsx
 import { Workflow } from '@t4h.framework/core'
@@ -34,146 +27,10 @@ export const invoice = new Workflow({ id: 'invoice' }, async () => {
     </Document>,
   )
 
-  // pdf is a Binary — hand it to other activities, e.g. an upload:
-  // await http.post(url, { form: { file: pdf } })
+  return pdf
 })
 ```
 
-The returned `Binary` exposes `contentType` (`application/pdf`), `contentLength`, and `stream()`.
-
-## Components
-
-The components exported by this package are **markers**: type-safe JSX tags that only exist inside a tree passed to `render()`. They are never invoked as functions — calling one directly or rendering it with another renderer throws.
-
-| Component | Key props | Description |
-|-----------|-----------|-------------|
-| `Document` | `title`, `author`, `subject`, `language` | Root of the PDF. Children must be `Page` elements |
-| `Page` | `size` (default `A4`), `orientation`, `style`, `dpi` | A page. Overflowing content paginates automatically |
-| `View` | — | Flex container, analogous to a `<div>` |
-| `Text` | — | Text content. All raw strings must live inside a `Text` |
-| `Link` | `href` | Hyperlink |
-| `Image` | `src` | Image from a URL, `data:` URI, or `Binary` |
-| `PageNumber` | `format` | Text resolved to the current page number at layout time |
-
-Every node inside a page also accepts: `style`, `fixed` (repeat on every page), `break` (force a page break), `wrap` (allow splitting across pages, default `true`), and `minPresenceAhead`.
-
-User function components, `.map()` arrays, fragments, and conditional rendering work exactly like normal React:
-
-```tsx
-function LineItem({ label, value }: { label: string; value: string }) {
-  return (
-    <View style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
-      <Text>{label}</Text>
-      <Text>{value}</Text>
-    </View>
-  )
-}
-
-const pdf = await render(
-  <Document>
-    <Page size='A4'>
-      {items.map(item => (
-        <LineItem key={item.id} {...item} />
-      ))}
-      {showFooter && <Text>Footer</Text>}
-    </Page>
-  </Document>,
-)
-```
-
-Tree rules enforced at serialization (violations throw):
-
-- The tree must resolve to a single `Document` root, and `Document` children must be `Page` elements.
-- Raw text must be wrapped in `Text`.
-- Only `Text`, `Link`, and `PageNumber` are allowed inside `Text`.
-
-## Styling
-
-Styles are camelCase records following the CSS **flex model** (no grid, no float). Numbers are points; strings accept units (`'2cm'`, `'5mm'`, `'50%'`). Text styles inherit through the tree, so defaults belong on `Page`.
-
-```tsx
-<Page size='A4' style={{ padding: '2cm', fontSize: 12, color: '#00513a' }}>
-  <View style={{ flexDirection: 'row', gap: 8 }}>
-    <Text style={{ fontWeight: 'bold' }}>Bold</Text>
-    <Text style={[{ fontSize: 10 }, { color: '#666' }]}>Small and gray</Text>
-  </View>
-</Page>
-```
-
-The standard PDF fonts (Helvetica, Courier, Times-Roman) are available with no registration, including `bold` and `italic` variants.
-
-## Images
-
-`Image src` accepts a URL, a `data:` URI, or a `Binary` whose `contentType` is an image type (PNG or JPEG). Prefer `Binary` for anything private or that must stay byte-identical across replays — URLs are fetched at layout time on every render.
-
-```tsx
-const logo = await http.get('https://cdn.example.com/logo.png')
-
-<Image src={logo.body.binary} style={{ width: 120 }} />
-```
-
-## Fonts
+## Documentation
 
-Register custom fonts per render with an object keyed by family name. Values are a bare source — a URL string or a `Binary` — for the regular variant, or an array of variants with `weight` / `style`. TTF and WOFF only (no WOFF2).
-
-```tsx
-const pdf = await render(<Doc />, {
-  fonts: {
-    Inter: 'https://cdn.example.com/Inter-Regular.ttf',
-    Roboto: [
-      { src: robotoRegular.body.binary },
-      { src: robotoBold.body.binary, weight: 700 },
-      { src: robotoItalic.body.binary, style: 'italic' },
-    ],
-  },
-})
-```
-
-Select variants in styles with `fontFamily`, `fontWeight` (`100–900`), and `fontStyle` (`'normal' | 'italic'`).
-
-Each variant reaches the process-wide font store once, keyed by family, weight, style and the file's digest, so passing `fonts` on every render costs nothing after the first.
-
-## Encryption
-
-Pass `encrypt` to also persist a password-protected copy — `render` then resolves with an `[original, encrypted]` pair (the return type narrows automatically). `password` is a bare string or `{ user, owner }`; `protection` is a `ProtectionFlags` bitmask (defaults follow the viewer; use `ProtectionPresets.ReadOnly` for view-and-print documents). Permission flags are honored by viewers, not enforced cryptographically.
-
-The encrypted copy is written with pdfkit's own encryption (AES-128, PDF 1.6) from the layout the first render already produced, so neither a re-encryption pass over the finished file nor a second layout is paid for.
-
-```tsx
-import { ProtectionPresets, render } from '@t4h.framework/pdf'
-
-const [original, encrypted] = await render(<Invoice />, {
-  encrypt: { password: '12345678900', protection: ProtectionPresets.ReadOnly },
-})
-```
-
-## Page numbers
-
-`PageNumber` resolves at layout time. The `format` string may reference `{pageNumber}` and `{totalPages}`; combine with `fixed` and absolute positioning for running footers.
-
-```tsx
-<PageNumber
-  fixed
-  format='{pageNumber}/{totalPages}'
-  style={{ position: 'absolute', bottom: 24, right: '2cm' }}
-/>
-```
-
-## Testing
-
-Test workflows with `TestWorkflowEnvironment` from `@t4h.framework/core/testing`, mocking `FileSystemClaim` — the rendered buffer is handed to `fs.write`, so assert on the `%PDF-` magic bytes there:
-
-```typescript
-import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
-import { FileSystemClaim } from '@t4h.framework/fs'
-
-const mockWrite = vi.fn().mockImplementation(async (_path, pdf) => new MockBinary(pdf))
-
-const env = TestWorkflowEnvironment.create({ now: 0 })
-
-await env.execute(workflow, input, {
-  claims: [mockClaim(FileSystemClaim, { write: mockWrite, read: vi.fn() })],
-})
-
-expect(mockWrite.mock.calls[0][1].subarray(0, 5).toString()).toBe('%PDF-')
-```
+https://tech4humans-brasil.github.io/framework/pdf/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/pdf",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Declarative PDF rendering module for the T4H Framework",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/pdf",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -33,8 +33,8 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.20.0",
-    "@t4h.framework/fs": "^0.13.1",
+    "@t4h.framework/core": "^0.21.0",
+    "@t4h.framework/fs": "^0.14.0",
     "@types/react": "^19.2.17",
     "muhammara": "^6.0.5",
     "typescript": "^5.9.3",