@murumets-ee/pdf 0.0.0-preview-20261014110621

package/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0 (ELv2)
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license
+no later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your
+licenses to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or
+the power to direct the management and policies of an entity (for example, by
+voting right, contract, or otherwise). Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,104 @@
+# @murumets-ee/pdf
+
+A React element tree in, PDF bytes plus a SHA-256 digest out. Domain-free and server-only in
+intent: it knows nothing about contracts, invoices, entities, storage buckets or blocks.
+
+Engine rationale, flip conditions and the determinism policy are locked in
+[`plan/rent/decisions/D028-pdf-package-and-engine.md`](../../plan/rent/decisions/D028-pdf-package-and-engine.md);
+the legal background is [R06](../../plan/rent/research/R06-contract-legal-and-pdf.md).
+
+## Usage
+
+```tsx
+import { createReactPdfRenderer, DEFAULT_FONT_FAMILY } from '@murumets-ee/pdf'
+import { Document, Page, StyleSheet, Text, View } from '@murumets-ee/pdf/primitives'
+
+const styles = StyleSheet.create({
+  page: { fontFamily: DEFAULT_FONT_FAMILY, padding: 40, fontSize: 11 },
+  heading: { fontFamily: DEFAULT_FONT_FAMILY, fontWeight: 700, fontSize: 16 },
+})
+
+const renderer = createReactPdfRenderer()
+
+const { bytes, sha256, byteLength } = await renderer.render(
+  <Document>
+    <Page size="A4" style={styles.page}>
+      <View>
+        <Text style={styles.heading}>Üürileping</Text>
+        <Text>Договор аренды</Text>
+      </View>
+    </Page>
+  </Document>,
+  { creationDate: signedAt, producer: 'Lumi CMS', creator: 'Lumi CMS' },
+)
+```
+
+Build documents out of `@murumets-ee/pdf/primitives` — `Document`, `Page`, `View`, `Text`,
+`Image`, `StyleSheet`, `Font`, plus the `Style` / `Styles` types. Consumers should never add a
+direct `@react-pdf/renderer` dependency; the engine seam is this package.
+
+`creationDate` is **required**. There is no wall-clock default: an implicit `new Date()` is the
+single biggest source of gratuitous non-determinism, and a caller that wants "now" should say so.
+
+## The digest is not a reproducibility claim
+
+`sha256` identifies **the bytes it was returned with**. Re-rendering the same tree with the same
+options is *not* expected to reproduce it, so **re-render-and-compare is not a valid integrity
+check** — it will report a false mismatch on a document nobody touched.
+
+Two independent reasons, both inside the engine:
+
+1. `@react-pdf/renderer` vendors a pdfkit fork whose six-letter font-subset tag (`ABCDEF+NotoSans`)
+   comes from `Math.random()`. Upstream pdfkit derives it from the font's object id; the fork has
+   not picked that up. We deliberately do **not** patch or seed the global RNG — it is
+   process-wide and would corrupt any concurrent render in the same worker.
+2. pdfkit compresses each stream through an **async** `zlib.createDeflate()` and writes each object
+   when *its* deflate finishes, so two streams of different sizes can complete in either order.
+   The `FontFile2` and `ToUnicode` objects are observed swapping places between runs.
+
+What *is* pinned, and covered by tests: the Info dictionary (`/CreationDate`, `/ModificationDate`,
+`/Producer`, `/Creator`), the file `/ID` that pdfkit derives from `md5(info)`, the total byte
+length, and every indirect object's content.
+
+The policy, per [R06](../../plan/rent/research/R06-contract-legal-and-pdf.md) §2: **hash on write,
+persist the exact bytes, never re-render for comparison.** ISO 32000-1 §14.4 says outright that
+*"the calculation of the file identifier need not be reproducible"*, and no e-signature vendor
+re-renders from source to verify — they all hash the stored bytes.
+
+## Fonts
+
+**Noto Sans**, regular + bold, shipped inside the package. A render never fetches a font over the
+network.
+
+One file covers Latin, Latin Extended (Estonian `õäöüšž`), Greek and Cyrillic — these are the
+[`notofonts/latin-greek-cyrillic`](https://github.com/notofonts/latin-greek-cyrillic) static
+builds, and `src/fonts.test.ts` asserts glyph coverage per script rather than assuming it. That
+single-file property is load-bearing: `@react-pdf/renderer` has no `unicode-range` mechanism, so a
+per-script split would need a fallback chain it cannot express, and a missing glyph renders as
+`.notdef` **silently**.
+
+`loadDefaultFonts()` reads both weights off disk *before* the render rather than letting react-pdf
+load them lazily mid-layout — the lazy path changes pdfkit's object emission order, so the first
+render in a process would otherwise differ structurally from every later one.
+
+The fonts are licensed under the **SIL Open Font License 1.1**; the licence text ships with them at
+[`fonts/OFL.txt`](./fonts/OFL.txt). Copyright 2022 The Noto Project Authors. Install weight: ~1.2 MB
+of font files, plus `@react-pdf/renderer` (~33 MB, 67 transitive packages, no native build, no
+postinstall, no browser download).
+
+## Not `server-only`-tagged — deliberately
+
+The package is server-only in intent, but the entry does **not** `import 'server-only'`.
+
+Its consumers reach it from an admin route, which is reachable from a plugin's static entry — the
+exact chain `pnpm verify:plugin-loads` loads under plain Node, where `server-only` throws
+unconditionally. `@murumets-ee/rent`'s `plugin.ts` already dynamic-imports its server-only runtime
+deps to stay jiti-safe; tagging this package would force the same escape hatch on every consumer
+for no security gain, since nothing here reads a request, a session or the database.
+
+`@murumets-ee/storage` carries the tag on `./` precisely because it keeps a *separate*, clean
+`./plugin` entry for the CLI path. This package has no such split — the renderer is the whole
+surface.
+
+Keep it out of any `*-ui/src/pages/**` static-import path (or add it to that package's tsdown
+`neverBundle`) so it is never inlined into a server-pages bundle.

package/dist/index.d.mts

@@ -0,0 +1,143 @@
+import { ReactElement } from "react";
+
+//#region src/digest.d.ts
+/**
+ * Lowercase hex SHA-256 of exactly the bytes in `bytes`.
+ *
+ * Respects `byteOffset` / `byteLength`, so a `Buffer` that is a window into a
+ * larger pooled `ArrayBuffer` hashes its own contents and nothing else.
+ *
+ * See {@link PdfRenderResult.sha256} for what this digest does and does not
+ * attest to — it identifies a specific byte sequence, not a rendering input.
+ */
+declare function sha256Hex(bytes: Uint8Array): string;
+//#endregion
+//#region src/fonts.d.ts
+/**
+ * The one font family this package registers.
+ *
+ * **Noto Sans** (SIL Open Font License 1.1). A single file covers Latin,
+ * Latin Extended (Estonian `õäöüšž`), Greek and Cyrillic — these are the
+ * `notofonts/latin-greek-cyrillic` static builds, verified glyph-by-glyph in
+ * `fonts.test.ts`. That matters because `@react-pdf/renderer` has no
+ * `unicode-range` mechanism: a per-script split would need a fallback chain it
+ * cannot express, and missing glyphs render as `.notdef` **silently**.
+ */
+declare const DEFAULT_FONT_FAMILY = "Noto Sans";
+/**
+ * Absolute paths to the bundled font files. They ship **inside the package**;
+ * a render never fetches a font over the network.
+ */
+declare const NOTO_SANS_FILES: {
+  readonly regular: string;
+  readonly bold: string;
+};
+/** The SIL Open Font License 1.1 text that covers {@link NOTO_SANS_FILES}. */
+declare const NOTO_SANS_LICENSE_FILE: string;
+/**
+ * Register {@link DEFAULT_FONT_FAMILY} on react-pdf's font store.
+ *
+ * Idempotent: react-pdf's store is a module singleton, and `register` appends
+ * to a family's source list rather than replacing it, so a naive repeat call
+ * would stack duplicates. The guard reads the store instead of tracking local
+ * state, so it stays correct across a caller's `Font.reset()`.
+ */
+declare function registerDefaultFonts(): void;
+/**
+ * Register the default family AND read both weights off disk before returning.
+ *
+ * This is a determinism fix, not a performance one. react-pdf loads a font
+ * lazily, mid-layout, the first time a glyph needs it — and that extra `await`
+ * changes the order in which pdfkit emits objects, so the FIRST render in a
+ * process produces a different object numbering (and different xref offsets)
+ * than every render after it. Measured: renders 2/3/4 were byte-identical once
+ * the subset tag is normalised away, render 1 was not. Pre-loading collapses
+ * that difference.
+ *
+ * Bounded by construction: exactly the two weights this package registers, no
+ * fan-out over a caller-supplied list. A consumer that registers additional
+ * families is responsible for warming them the same way.
+ */
+declare function loadDefaultFonts(): Promise<void>;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Document-level metadata pinned onto every render.
+ *
+ * Everything here exists to remove *gratuitous* non-determinism from the
+ * output. It is deliberately small: this package renders a React tree, it does
+ * not model documents.
+ */
+interface PdfRenderOptions {
+  /**
+   * Pinned document timestamps. REQUIRED — callers must pass a deliberate value.
+   * There is no wall-clock default: an implicit `new Date()` is the single biggest
+   * source of gratuitous non-determinism, and a caller that wants "now" should say so.
+   */
+  readonly creationDate: Date;
+  readonly modificationDate?: Date;
+  readonly producer?: string;
+  readonly creator?: string;
+}
+interface PdfRenderResult {
+  readonly bytes: Uint8Array;
+  /**
+   * Lowercase hex SHA-256 of `bytes`, computed over exactly what is returned.
+   *
+   * ## This digest identifies THESE BYTES — it is not a reproducibility claim
+   *
+   * Re-rendering the same React tree with the same {@link PdfRenderOptions} is
+   * **not** expected to reproduce this digest, and **re-render-and-compare is
+   * therefore not a valid integrity check**. Doing so will report a false
+   * mismatch on a document that was never touched.
+   *
+   * The concrete reason: `@react-pdf/renderer` vendors a fork of pdfkit whose
+   * font-subset tag (the six-letter `ABCDEF+` prefix on `/BaseFont`) comes from
+   * `Math.random()`. Upstream pdfkit derives that tag from the font's object id;
+   * the fork has not picked the change up. We deliberately do **not** patch or
+   * seed the global RNG to work around it — see
+   * `plan/rent/decisions/D028-pdf-package-and-engine.md`.
+   *
+   * The policy, per `plan/rent/research/R06-contract-legal-and-pdf.md` §2:
+   * **hash on write, persist the exact bytes, never re-render for comparison.**
+   * That is also the legally correct model and matches universal industry
+   * practice — ISO 32000-1 §14.4 states outright that *"the calculation of the
+   * file identifier need not be reproducible"*, and no e-signature vendor
+   * re-renders from source to verify; they all hash the stored bytes.
+   *
+   * To verify a stored document: hash the stored bytes and compare against the
+   * digest recorded at write time. Never regenerate the document.
+   */
+  readonly sha256: string;
+  readonly byteLength: number;
+}
+/**
+ * The engine seam. One implementation ships today
+ * (`createReactPdfRenderer`); the interface exists so a swap costs one
+ * package rather than every consumer.
+ */
+interface PdfRenderer {
+  render(document: ReactElement, options: PdfRenderOptions): Promise<PdfRenderResult>;
+}
+//#endregion
+//#region src/react-pdf-renderer.d.ts
+/**
+ * The `@react-pdf/renderer` implementation of {@link PdfRenderer}.
+ *
+ * Stateless and cheap to construct — react-pdf's font store is a module
+ * singleton, so several renderers share one registration. Renders happen
+ * entirely in-process: no browser, no sidecar, no network (the fonts ship
+ * inside this package), and the document never executes script.
+ *
+ * @example
+ * ```ts
+ * const renderer = createReactPdfRenderer()
+ * const { bytes, sha256 } = await renderer.render(<Document>…</Document>, {
+ *   creationDate: signedAt, // a deliberate instant, never `new Date()` by default
+ * })
+ * ```
+ */
+declare function createReactPdfRenderer(): PdfRenderer;
+//#endregion
+export { DEFAULT_FONT_FAMILY, NOTO_SANS_FILES, NOTO_SANS_LICENSE_FILE, type PdfRenderOptions, type PdfRenderResult, type PdfRenderer, createReactPdfRenderer, loadDefaultFonts, registerDefaultFonts, sha256Hex };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/digest.ts","../src/fonts.ts","../src/types.ts","../src/react-pdf-renderer.ts"],"mappings":";;;;;;AAWA;;;;AAA2C;;iBAA3B,SAAA,CAAU,KAAiB,EAAV,UAAU;;;;;;AAA3C;;;;AAA2C;;;cCI9B,mBAAA;AAAb;;;;AAAA,cAiBa,eAAA;EAAA,SAGH,OAAA;EAAA,SAAA,IAAA;AAAA;;cAGG,sBAAA;AAAb;;;;AAA+D;AAU/D;;;AAVA,iBAUgB,oBAAA;AAAoB;AAuCpC;;;;AAAiD;;;;AC9EjD;;;;;;ADuCoC,iBAuCd,gBAAA,IAAoB,OAAO;;;;;AD5EjD;;;;AAA2C;UEF1B,gBAAA;;;ADMjB;;;WCAW,YAAA,EAAc,IAAA;EAAA,SACd,gBAAA,GAAmB,IAAI;EAAA,SACvB,QAAA;EAAA,SACA,OAAA;AAAA;AAAA,UAGM,eAAA;EAAA,SACN,KAAA,EAAO,UAAU;EDgBf;;;;AAAkD;AAU/D;;;;AAAoC;AAuCpC;;;;AAAiD;;;;AC9EjD;;;;;;;;;ED6Ba,SCYF,MAAA;EAAA,SACA,UAAA;AAAA;AA9BX;;;;;AAAA,UAsCiB,WAAA;EACf,MAAA,CAAO,QAAA,EAAU,YAAA,EAAc,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,eAAA;AAAA;;;;;AFjDrE;;;;AAA2C;;;;ACI3C;;;;AAAgC;AAiBhC;iBEwBgB,sBAAA,IAA0B,WAAW"}