@awacloud/pdf 0.0.0-stage → 1.0.0

package/docs/api/annot/fileAttach.md

@@ -0,0 +1,53 @@
+---
+module: pdfFileAttachAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFileAttachAnnot
+
+> File-attachment annotation — ISO 32000-2 §12.5.6.15.
+
+**Module** `pdfFileAttachAnnot` | **Source** `packages/front/office/pdf/src/annot/fileAttach.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfAnnot` | **Worker-safe** yes
+
+Subtype `/FileAttachment`. Key entries: `/FS` (file specification — see
+[`pdfFileSpec`](../embedded/fileSpec.md)) and `/Name` (icon — `Graph`,
+`PushPin`, `Paperclip`, `Tag`). The payload lives in the file spec's `/EF`
+stream. `/FS` is required and must be a reference or a dictionary.
+
+## Resolve
+
+```js
+const fa = runtime.resolve('pdfFileAttachAnnot');
+// Returns: { typeFileAttachAnnot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeFileAttachAnnot` | `(dict) => FileAttachAnnot` | Base record plus `fs` (raw typed `/FS` — ref or dict) and `iconName`. |
+
+## Examples
+
+```js
+const fa = runtime.resolve('pdfFileAttachAnnot').typeFileAttachAnnot(dict);
+const spec = runtime.resolve('pdfFileSpec').typeFileSpec(doc._raw.resolve(fa.fs));
+spec.f;             // filename (/F)
+spec.embedded?.F;   // /EF /F — the embedded-file stream reference
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/fileattach/bad-subtype` | `ParseError` | `/Subtype` present and not `/FileAttachment`. |
+| `pdf/annot/fileattach/bad-fs` | `ParseError` | `/FS` missing, or neither a reference nor a dictionary. |
+
+## See also
+
+- [`pdfAnnot`](./annot.md) · [`pdfMarkupAnnot`](./markup.md)
+- [`pdfFileSpec`](../embedded/fileSpec.md) · [`pdfEmbeddedFile`](../embedded/embeddedFile.md)

package/docs/api/annot/freeText.md

@@ -0,0 +1,68 @@
+---
+module: pdfFreeTextAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfFreeTextAnnot
+
+> Free text annotation — ISO 32000-2 §12.5.6.6.
+
+**Module** `pdfFreeTextAnnot` | **Source** `packages/front/office/pdf/src/annot/freeText.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfAnnot` | **Worker-safe** yes
+
+Subtype `/FreeText` — text painted directly on the page rather than in a pop-up.
+Subtype-specific entries: `/DA` (default appearance string — a sequence of `Tf`,
+`g`, `rg`, … operators), `/Q` (quadding 0/1/2), `/RC` (rich content), `/DS`
+(default style, CSS), `/CL` (callout line array), `/IT` (intent: `FreeText`,
+`FreeTextCallout`, `FreeTextTypeWriter`), `/RD` (rectangle differences) and
+`/LE` (line ending). `/BS` and `/BE` come from the base record.
+
+## Resolve
+
+```js
+const ft = runtime.resolve('pdfFreeTextAnnot');
+// Returns: { typeFreeTextAnnot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeFreeTextAnnot` | `(dict) => FreeTextAnnot` | Base record plus `da`, `q`, `rc`, `ds`, `cl`, `it`, `rd`, `le`. |
+
+`da`, `rc` and `ds` are the raw `Uint8Array` payloads of the PDF strings; `le` is
+a single name (not an array).
+
+## Examples
+
+### Plain free text
+
+```js
+const f = runtime.resolve('pdfFreeTextAnnot').typeFreeTextAnnot(dict);
+f.contents;    // body text
+f.da;          // Uint8Array — Tf + rg/g sequence
+f.q;           // 0=left, 1=center, 2=right
+```
+
+### Callout
+
+```js
+f.it === 'FreeTextCallout';
+f.cl;          // [x1, y1, x2, y2, x3, y3] — knee/elbow points
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/freetext/bad-subtype` | `ParseError` | `/Subtype` present and not `/FreeText`. |
+| `pdf/annot/freetext/bad-cl` | `ParseError` | `/CL` is not an array of numbers. |
+| `pdf/annot/freetext/bad-rd` | `ParseError` | `/RD` is not an array of numbers. |
+
+## See also
+
+- [`pdfAnnot`](./annot.md)
+- [`pdfAppearance`](../form/appearance.md) — `/AP` shares the same mechanics.

package/docs/api/annot/ink.md

@@ -0,0 +1,69 @@
+---
+module: pdfInkAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfInkAnnot
+
+> Ink (freehand) annotation — ISO 32000-2 §12.5.6.13.
+
+**Module** `pdfInkAnnot` | **Source** `packages/front/office/pdf/src/annot/ink.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfAnnot` | **Worker-safe** yes
+
+Subtype `/Ink`. A freehand trace: `/InkList` is an array of strokes, each stroke
+itself an array of coordinates `[x0 y0 x1 y1 …]` (pairs). `/BS` — part of the
+base record — carries width and style. The typer validates the shape strictly:
+an array of arrays of numeric pairs. `/InkList` is the only subtype-specific
+entry; everything else lands in the base record or in `_extras`.
+
+## Resolve
+
+```js
+const ink = runtime.resolve('pdfInkAnnot');
+// Returns: { typeInkAnnot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeInkAnnot` | `(dict) => InkAnnot` | Base record plus `inkList: number[][]`. |
+
+Each sub-array of `inkList` is one stroke; an even length is guaranteed.
+
+## Examples
+
+### Reading the strokes
+
+```js
+const a = runtime.resolve('pdfInkAnnot').typeInkAnnot(dict);
+for (const stroke of a.inkList) {
+    for (let i = 0; i < stroke.length; i += 2) {
+        const [x, y] = [stroke[i], stroke[i + 1]];
+        // …
+    }
+}
+```
+
+### Line width
+
+```js
+a.bs?.entries.W?.value;   // line width, from the base record
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/ink/bad-subtype` | `ParseError` | `/Subtype` present and not `/Ink`. |
+| `pdf/annot/ink/bad-inklist` | `ParseError` | `/InkList` is not an array. |
+| `pdf/annot/ink/bad-stroke` | `ParseError` | A non-array element inside `/InkList`. |
+| `pdf/annot/ink/bad-coord` | `ParseError` | Stroke of odd length, or a non-numeric element. |
+
+## See also
+
+- [`pdfAnnot`](./annot.md)
+- [`pdfMarkupAnnot`](./markup.md) — shared markup entries land in `_extras` here too.

package/docs/api/annot/link.md

@@ -0,0 +1,74 @@
+---
+module: pdfLinkAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfLinkAnnot
+
+> Hyperlink — ISO 32000-2 §12.5.6.5.
+
+**Module** `pdfLinkAnnot` | **Source** `packages/front/office/pdf/src/annot/link.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfAnnot` | **Worker-safe** yes
+
+Subtype `/Link`. Subtype-specific entries: `/A` (action — see
+[`pdfAction`](../action/action.md)), `/Dest` (destination — see
+[`pdfDestination`](../destination/destination.md)), `/H` (highlight mode —
+`N`/`I`/`O`/`P`), `/PA` (legacy URI action) and `/QuadPoints` (clickable
+regions, multiples of 8 floats §12.5.6.10). `/BS` is part of the base record.
+Any other entry lands in `_extras`.
+
+## Resolve
+
+```js
+const link = runtime.resolve('pdfLinkAnnot');
+// Returns: { typeLinkAnnot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeLinkAnnot` | `(dict) => LinkAnnot` | Base record plus `dest`, `action`, `h`, `pa`, `quadPoints`. |
+
+`/A` is surfaced as `action` (and only when it is a dictionary, not an indirect
+reference); `dest` is the raw typed `/Dest` value, left unresolved. `action` and
+`dest` are mutually exclusive in practice; the typer does not arbitrate — the
+semantic resolver (catalog walker) prioritises `/A`.
+
+## Examples
+
+### Link to a URI
+
+```js
+const link = runtime.resolve('pdfLinkAnnot').typeLinkAnnot(dict);
+if (link.action) {
+    const act = runtime.resolve('pdfAction').typeAction(link.action, typers);
+    act.kind === 'URI';
+}
+```
+
+### Internal link (destination)
+
+```js
+if (link.dest) {
+    const d = runtime.resolve('pdfDestination')
+        .typeDestination(link.dest, catalog.names, resolveRef);
+    d.page;
+}
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/not-dict` | `ParseError` | Inherited from `typeBaseAnnot`. |
+| `pdf/annot/link/bad-subtype` | `ParseError` | `/Subtype` present and not `/Link`. |
+| `pdf/annot/link/bad-quadpoints` | `ParseError` | `/QuadPoints` is not an array of numbers. |
+
+## See also
+
+- [`pdfAnnot`](./annot.md)
+- [`pdfAction`](../action/action.md) · [`pdfDestination`](../destination/destination.md)

package/docs/api/annot/markup.md

@@ -0,0 +1,83 @@
+---
+module: pdfMarkupAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfMarkupAnnot
+
+> Text-markup annotations — ISO 32000-2 §12.5.6.10.
+
+**Module** `pdfMarkupAnnot` | **Source** `packages/front/office/pdf/src/annot/markup.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfAnnot` | **Worker-safe** yes
+
+Covers the `Highlight`, `Underline`, `Squiggly`, `StrikeOut` and `Caret`
+subtypes. The typer consumes `/QuadPoints` (8 × n floats — the four corners of
+each region), `/IT` (intent) and, for `Caret` only (§12.5.6.11), `/RD`
+(rectangle differences) and `/Sy` (displayed symbol).
+
+The shared markup entries of §12.5.6.2 — `/T` (author), `/Subj`, `/RC` (rich
+content), `/CreationDate`, `/IRT` (in-reply-to ref), `/RT` (reply type), `/Popup`
+and `/ExData` — are **not** promoted to named fields: they are neither base keys
+nor subtype keys, so `captureExtras` puts them in `_extras` under their raw PDF
+names.
+
+## Resolve
+
+```js
+const markup = runtime.resolve('pdfMarkupAnnot');
+// Returns: { typeMarkupAnnot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeMarkupAnnot` | `(dict, expected: string) => MarkupAnnot` | Base record plus `quadPoints`, `it`, and — for `Caret` — `rd` and `sy`. |
+
+`expected` ∈ `'Highlight'`, `'Underline'`, `'Squiggly'`, `'StrikeOut'`,
+`'Caret'`. The multiple-of-8 check on `/QuadPoints` is applied to every subtype
+except `Caret`.
+
+## Examples
+
+### Typed highlight
+
+```js
+const m = runtime.resolve('pdfMarkupAnnot').typeMarkupAnnot(dict, 'Highlight');
+m.quadPoints;      // number[8 * n]
+m.it;              // /IT intent name or null
+m._extras.T;       // /T (author) — typed string object
+m._extras.Popup;   // /Popup — typed ref object
+```
+
+### Reply thread
+
+```js
+m._extras.IRT;     // ref to the parent annotation
+m._extras.RT;      // 'R' (reply) | 'Group' — typed name object
+```
+
+### Caret specifics
+
+```js
+const c = runtime.resolve('pdfMarkupAnnot').typeMarkupAnnot(dict, 'Caret');
+c.rd;              // rectangle differences
+c.sy;              // 'P' | 'None' | null
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/markup/bad-expected` | `ParseError` | `expected` is not one of the five supported subtypes. |
+| `pdf/annot/markup/bad-subtype` | `ParseError` | `/Subtype` differs from `expected`. |
+| `pdf/annot/markup/bad-quadpoints` | `ParseError` | `/QuadPoints` is not an array of numbers, or its length is not a multiple of 8. |
+| `pdf/annot/markup/bad-rd` | `ParseError` | `/RD` (Caret) is not an array of numbers. |
+
+## See also
+
+- [`pdfAnnot`](./annot.md)
+- [`pdfPopupAnnot`](./popup.md)

package/docs/api/annot/popup.md

@@ -0,0 +1,52 @@
+---
+module: pdfPopupAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfPopupAnnot
+
+> Pop-up annotation — ISO 32000-2 §12.5.6.14.
+
+**Module** `pdfPopupAnnot` | **Source** `packages/front/office/pdf/src/annot/popup.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfAnnot` | **Worker-safe** yes
+
+Subtype `/Popup`: the display window attached to a parent annotation (markup,
+sticky note). Subtype-specific entries: `/Parent` (reference to the carrying
+annotation) and `/Open` (initial state). A pop-up is never meaningful alone — it
+relies on its parent for `/Contents`, `/T` and `/M`.
+
+## Resolve
+
+```js
+const popup = runtime.resolve('pdfPopupAnnot');
+// Returns: { typePopupAnnot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typePopupAnnot` | `(dict) => PopupAnnot` | Base record plus `parent: {num,gen}\|null` and `open: boolean`. |
+
+## Examples
+
+```js
+const p = runtime.resolve('pdfPopupAnnot').typePopupAnnot(dict);
+p.parent;     // reference to the parent markup annotation
+p.open;       // false by default
+p.rect;       // window position (base record)
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/popup/bad-subtype` | `ParseError` | `/Subtype` present and not `/Popup`. |
+
+## See also
+
+- [`pdfAnnot`](./annot.md) · [`pdfMarkupAnnot`](./markup.md)
+- [`pdfTextAnnot`](./text.md)

package/docs/api/annot/projection.md

@@ -0,0 +1,56 @@
+---
+module: pdfProjectionAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfProjectionAnnot
+
+> Projection annotation (3D view) — ISO 32000-2 §13.6.6.2.
+
+**Module** `pdfProjectionAnnot` | **Source** `packages/front/office/pdf/src/annot/projection.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfAnnot` | **Worker-safe** yes
+
+Subtype `/Projection`: an annotation bound to a 3D view. Two subtype-specific
+entries are promoted — `/V` (the 3D view, a dictionary or a referenced view
+name) and `/B` (the 3D state dictionary: background and so on). Everything else,
+including the shared markup entries (`/T`, `/Subj`, `/CreationDate`, …) and 3D
+extras such as `/M3D`, is captured into `_extras` under its raw PDF name.
+
+The same source file also carries the legacy Movie/Sound handling (Annex H,
+deprecated in PDF 2.0) for completeness.
+
+## Resolve
+
+```js
+const proj = runtime.resolve('pdfProjectionAnnot');
+// Returns: { typeProjectionAnnot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeProjectionAnnot` | `(dict) => ProjectionAnnot` | Base record plus `v` (raw typed `/V`) and `b` (`/B` dictionary or `null`), with everything else in `_extras`. |
+
+## Examples
+
+```js
+const p = runtime.resolve('pdfProjectionAnnot').typeProjectionAnnot(dict);
+p.v;            // /V — 3D view dict or name
+p.b;            // /B — 3D state dict or null
+p._extras.T;    // /T (author) — typed string object
+p._extras.M3D;  // reference to the 3D measurement, when present
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/projection/bad-subtype` | `ParseError` | `/Subtype` present and not `/Projection`. |
+
+## See also
+
+- [`pdfAnnot`](./annot.md) · [`pdfMarkupAnnot`](./markup.md)

package/docs/api/annot/redact.md

@@ -0,0 +1,67 @@
+---
+module: pdfRedactAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfRedactAnnot
+
+> Redact annotation (ISO 32000-2 §12.5.6.21) — read-side typing only; applying a redaction (content removal) is not implemented.
+
+**Module** `pdfRedactAnnot` | **Source** `packages/front/office/pdf/src/annot/redact.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfAnnot` | **Worker-safe** yes
+
+Subtype `/Redact`: a visual marker for an area to be redacted. Actually applying
+the redaction (removing the underlying content) is *not* performed by this
+module. Subtype-specific entries: `/QuadPoints` (regions, multiples of 8
+floats), `/IC` (interior colour after redaction), `/RO` (override appearance),
+`/OverlayText` (replacement text), `/Repeat` (boolean — repeat the overlay
+pattern), `/DA` and `/Q`.
+
+## Resolve
+
+```js
+const redact = runtime.resolve('pdfRedactAnnot');
+// Returns: { typeRedactAnnot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeRedactAnnot` | `(dict) => RedactAnnot` | Base record plus `quadPoints`, `ic`, `ro`, `overlayText`, `repeat`, `da`, `q`. |
+
+`overlayText` and `da` are the raw `Uint8Array` payloads of the PDF strings;
+`q` defaults to `0` and `repeat` to `false`.
+
+## Examples
+
+### Marking
+
+```js
+const r = runtime.resolve('pdfRedactAnnot').typeRedactAnnot(dict);
+r.quadPoints;    // regions to redact
+r.overlayText;   // Uint8Array — e.g. 'REDACTED'
+r.ic;            // [0, 0, 0] = solid black
+```
+
+### Applying
+
+Application must happen out of band (content removal, image re-encoding,
+deletion of covered annotations). See
+[`pdfRedactionIso32005`](../extra/redaction-iso32005.md).
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/redact/bad-subtype` | `ParseError` | `/Subtype` present and not `/Redact`. |
+| `pdf/annot/redact/bad-quadpoints` | `ParseError` | `/QuadPoints` is not an array of numbers, or its length is not a multiple of 8. |
+| `pdf/annot/redact/bad-ic` | `ParseError` | `/IC` is not an array of numbers. |
+
+## See also
+
+- [`pdfAnnot`](./annot.md) · [`pdfMarkupAnnot`](./markup.md)
+- [`pdfRedactionIso32005`](../extra/redaction-iso32005.md)

package/docs/api/annot/square.md

@@ -0,0 +1,87 @@
+---
+module: pdfShapeAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfShapeAnnot
+
+> Shape annotations — Line/Square/Circle/Polygon/PolyLine — ISO 32000-2 §12.5.6.7–§12.5.6.9.
+
+**Module** `pdfShapeAnnot` | **Source** `packages/front/office/pdf/src/annot/square.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfAnnot` | **Worker-safe** yes
+
+Generic typer for the geometric annotations. `/IC` (interior colour) is read for
+every subtype; the remaining entries are gated on `expected`:
+
+| `expected` | Fields set |
+|------------|------------|
+| `Square`, `Circle` | `ic`, `rd` (`/RD`) |
+| `Line` | `ic`, `l` (`/L`), `le` (`/LE`), `ll` (`/LL`), `lle` (`/LLE`), `cap` (`/Cap`), `cp` (`/CP`), `it` (`/IT`), `measure` (`/Measure`) |
+| `Polygon`, `PolyLine` | `ic`, `vertices` (`/Vertices`), `le`, `it`, `measure`, `path` (`/Path`) |
+
+Every other entry — including `/BE`, handled by the base typer, and the shared
+markup entries `/T`, `/Subj`, `/Popup`, … — is either part of the base record or
+captured into `_extras`.
+
+## Resolve
+
+```js
+const shape = runtime.resolve('pdfShapeAnnot');
+// Returns: { typeShapeAnnot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeShapeAnnot` | `(dict, expected: string) => ShapeAnnot` | Base record plus the geometry fields listed above. |
+
+`expected` ∈ `'Line'`, `'Square'`, `'Circle'`, `'Polygon'`, `'PolyLine'`.
+
+## Examples
+
+### Square / Circle
+
+```js
+const s = runtime.resolve('pdfShapeAnnot').typeShapeAnnot(dict, 'Square');
+s.ic;        // [r, g, b] interior colour
+s.rd;        // rectangle differences
+s.bs;        // border style dict (base record)
+```
+
+### Line with endings
+
+```js
+const l = runtime.resolve('pdfShapeAnnot').typeShapeAnnot(dict, 'Line');
+l.l;         // [x1, y1, x2, y2]
+l.le;        // ['OpenArrow', 'None']
+l.cap;       // false unless /Cap true
+```
+
+### Polygon vertices
+
+```js
+const p = runtime.resolve('pdfShapeAnnot').typeShapeAnnot(dict, 'Polygon');
+p.vertices;  // [x0, y0, x1, y1, …]
+p.path;      // typed /Path array or null
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/shape/bad-expected` | `ParseError` | `expected` outside the allowed set. |
+| `pdf/annot/shape/bad-subtype` | `ParseError` | `/Subtype` differs from `expected`. |
+| `pdf/annot/shape/bad-ic` | `ParseError` | `/IC` is not an array of numbers. |
+| `pdf/annot/shape/bad-rd` | `ParseError` | `/RD` is not an array of numbers. |
+| `pdf/annot/shape/bad-l` | `ParseError` | `/L` is not an array of numbers. |
+| `pdf/annot/shape/bad-le` | `ParseError` | `/LE` is not an array of names. |
+| `pdf/annot/shape/bad-vertices` | `ParseError` | `/Vertices` is not an array of numbers. |
+
+## See also
+
+- [`pdfAnnot`](./annot.md) — dispatcher.
+- [`pdfMarkupAnnot`](./markup.md) — text-markup subtypes.

package/docs/api/annot/stamp.md

@@ -0,0 +1,54 @@
+---
+module: pdfStampAnnot
+category: pdf/annot
+dependencies: [pdfErrors, pdfParser, pdfAnnot]
+returns: object
+worker-safe: true
+status: complete
+---
+
+# pdfStampAnnot
+
+> Rubber-stamp annotation — ISO 32000-2 §12.5.6.12.
+
+**Module** `pdfStampAnnot` | **Source** `packages/front/office/pdf/src/annot/stamp.js` | **Deps** `pdfErrors`, `pdfParser`, `pdfAnnot` | **Worker-safe** yes
+
+Subtype `/Stamp`. The only subtype-specific entry is `/Name` — the icon
+(`Approved`, `Experimental`, `NotApproved`, `AsIs`, `Expired`,
+`NotForPublicRelease`, `Confidential`, `Final`, `Sold`, `Departmental`,
+`ForComment`, `TopSecret`, `Draft`, `ForPublicRelease`). The actual rendering
+lives in `/AP` (base record); `/Name` is only a hint. The shared markup entries
+(`/T`, `/Subj`, `/CreationDate`, `/Popup`, …) are captured into `_extras`.
+
+## Resolve
+
+```js
+const stamp = runtime.resolve('pdfStampAnnot');
+// Returns: { typeStampAnnot }
+```
+
+## API
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `typeStampAnnot` | `(dict) => StampAnnot` | Base record plus `iconName`. |
+
+## Examples
+
+```js
+const s = runtime.resolve('pdfStampAnnot').typeStampAnnot(dict);
+s.iconName;     // 'Approved'
+s.ap;           // appearance-stream dictionary (base record)
+s._extras.T;    // /T (author) — typed string object
+```
+
+## Errors
+
+| Code | Class | When |
+|------|-------|------|
+| `pdf/annot/stamp/bad-subtype` | `ParseError` | `/Subtype` present and not `/Stamp`. |
+
+## See also
+
+- [`pdfAnnot`](./annot.md) · [`pdfMarkupAnnot`](./markup.md)
+- [`pdfAppearance`](../form/appearance.md)