@qrcommunication/gigapdf-lib 0.1.0 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,219 @@ All notable changes to `@qrcommunication/gigapdf-lib` are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/) and the
 project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.8.0] - 2026-06-16
+
+### Added
+
+- **AES PDF encryption** (`doc.saveEncrypted`). The Standard Security Handler can
+  now *write* **AES-128 (V4/R4)** and **AES-256 (V5/R6)** in addition to RC4, with
+  **separate user and owner passwords**:
+  - `saveEncrypted(password, fileId, { algorithm: "aes256" | "aes128" | "rc4",
+    ownerPassword, permissions, keySeed })` — defaults to **AES-256**.
+  - AES-256 needs a **secret 32-byte file key** (the engine has no RNG): the SDK
+    generates it with Web Crypto, or you pass `keySeed`. The decryption side
+    already read AESV2/AESV3; `openEncrypted` now also accepts the **owner**
+    password for R6 (Algorithm 2.A).
+  - ABI `gp_save_encrypted` gains `owner`, `key` and an `algorithm` selector.
+
+### Changed
+
+- **Breaking (SDK):** `saveEncrypted(password, fileId, permissions?)` →
+  `saveEncrypted(password, fileId, opts?)`. Pass `{ permissions }` (and
+  `{ algorithm: "rc4" }` to keep the previous RC4 behaviour).
+
+## [0.7.0] - 2026-06-15
+
+### Added
+
+- **Complete viewer zoom controls** (`@qrcommunication/gigapdf-lib/viewer`):
+  `fitWidth()`, `fitPage()`, `actualSize()`, `setZoom()` / `setZoomPercent()` and a
+  `zoom` getter; a toolbar **preset drop-down** (Fit width · Fit page · 50–400 %)
+  with a live `%` readout; `Ctrl`/`⌘` + mouse-wheel zoom; and a `0` keyboard
+  shortcut. A chosen **fit mode is sticky** — it re-applies when the viewport
+  resizes (via `ResizeObserver`) and when paging to a page of a different
+  orientation.
+- **Editor rulers & margins** (`@qrcommunication/gigapdf-lib/editor`): every page
+  shows graduated **millimetre rulers** (top + left) and four **margin guides**
+  dragged **live** from handles in the ruler bands — or set via the palette's
+  `T R B L` mm fields and the `setMargins()` / `getMargins()` / `showRulers()`
+  API. Guides are drawn in page-point coordinates (on a second SVG layer) and kept
+  a constant on-screen size at any zoom.
+
+## [0.6.0] - 2026-06-15
+
+### Added
+
+- **Full page control for HTML→PDF** via `htmlRenderWith(html, fonts, options)`:
+  - **named paper sizes** — `pageSize: "A4" | "a3-landscape" | "letter" | …`
+    (ISO A0–A6, ISO B4/B5, US Letter/Legal/Tabloid/Executive; `-landscape`
+    suffix swaps the axes). `giga.pageSize(name)` resolves one to `{ w, h }`
+    points.
+  - **per-side margins** — `margin: number | { top, right, bottom, left }`.
+  - **running header & footer** — `header` / `footer` are full HTML+CSS
+    snippets painted in the page margins on every page, with `{{page}}` /
+    `{{pages}}` substitution and configurable `startPageNumber`,
+    `headerOffset` / `footerOffset`.
+- **`htmlNeededFontsWith(html, header, footer)`** — phase-1 font discovery that
+  also scans the header/footer HTML so their Google fonts are fetched.
+- New ABI exports: `gp_html_render_opts`, `gp_html_needed_fonts_ex`,
+  `gp_page_size`.
+
+### Images & SVG
+
+- **SVG → native PDF vector** via `doc.addSvg(page, src, x, y, w, h)` (ABI
+  `gp_add_svg`): shapes (`rect`/`circle`/`ellipse`/`line`/`polyline`/`polygon`),
+  `<path>` (full `d` grammar with **exact `A` arc→Bézier conversion**), `<g>`
+  groups, `transform`, `viewBox`, `fill`/`stroke`/`stroke-width`/`opacity`, and
+  **gradients** (`<linearGradient>`/`<radialGradient>` → native PDF axial/radial
+  shadings, with stops, `gradientUnits`, `gradientTransform` and `href`
+  inheritance) — crisp at any zoom, not rasterized. In the HTML renderer, inline
+  `<svg>` and `data:image/svg+xml` `<img>` sources render as native vector.
+- **PNG transparency in the rasterizer**: `renderPage`/thumbnails now honour an
+  image's `/SMask` (soft mask) as per-pixel alpha instead of treating it as
+  opaque, so transparent PNGs composite correctly in every conversion (not just
+  HTML→PDF).
+- **Colour emoji** (COLR v0 + CPAL): when a text run uses a colour font (e.g.
+  `font-family: "Noto Color Emoji"`), emoji are drawn as native vector colour
+  layers in the HTML renderer — crisp, and rasterized for free. **Apple `sbix`
+  bitmap emoji** are placed as PNG glyph bitmaps. Non-colour characters in the
+  run still render as text. (COLRv1 gradient glyphs and `CBDT/CBLC` strikes are
+  not yet drawn.)
+
+### Viewer
+
+- **`@qrcommunication/gigapdf-lib/viewer`** — a new zero-dependency browser
+  document viewer (`GigaPdfViewer`) built on the engine (no pdf.js): opens PDF,
+  Office (docx/xlsx/pptx, legacy, ODF) and HTML (auto-detected, converted
+  in-engine), renders pages with `renderPage`, **detects per-page orientation**
+  and adapts, with navigation, zoom, a thumbnail rail, keyboard control and a
+  **fullscreen presentation mode**.
+- **`@qrcommunication/gigapdf-lib/editor`** — an interactive **editing canvas**
+  (`GigaPdfEditor`) extending the viewer: an SVG overlay per page with tools
+  (text, rectangle, ellipse, line, freehand ink, image, highlight, redaction),
+  select·move·delete, and `applyEdits()` that **bakes edits into the real PDF**
+  through the engine (then re-renders); `save()` returns the result.
+
+### CSS
+
+- HTML→PDF renderer gained `min-width` / `max-width`, `height` / `min-height`,
+  `box-sizing`, `text-indent` (first-line indent), `visibility: hidden`,
+  `opacity` (backgrounds/borders/text rules), and `text-decoration: line-through`
+  / `overline`. See [`docs/HTML-CSS.md`](../docs/HTML-CSS.md).
+
+## [0.5.0] - 2026-06-15
+
+### Changed
+
+- **Suspendable JavaScript VM** for `<script>` execution (`htmlRender` /
+  `runInlineScripts`). `function*` and `async` bodies now compile to a
+  resumable bytecode machine, so:
+  - **generators are truly lazy** — an infinite `while (true) { yield … }` is
+    fine, `.next(v)` feeds a value back into the suspended `yield`, and `yield*`
+    delegates lazily;
+  - **`await` yields to the event loop** with spec microtask ordering (the
+    synchronous tail runs before a deferred continuation), instead of draining
+    the queue synchronously;
+  - **full control flow** can span a `yield`/`await` — `try`/`catch`/`finally`
+    (the handler survives suspension; a rejected `await` in a `try` is caught),
+    `for…of`/`for…in`, `switch`, labelled `break`/`continue`, destructuring,
+    compound assignment, and `...spread`.
+
+  No API change — existing `htmlRender`/`runInlineScripts` calls simply behave
+  correctly for script-driven, generator/async-heavy templates. A body the VM
+  can't compile (e.g. `try`/`catch` around a `yield`/`await`) transparently
+  falls back to the previous eager/synchronous model.
+
+## [0.4.0] - 2026-06-15
+
+### Added
+
+- **AcroForm field creation.** Build interactive forms from scratch — no
+  `pdf-lib`. New `GigaPdfDoc` methods, each taking a `[x0,y0,x1,y1]` rectangle
+  and an optional [`FieldStyle`](src/index.ts) (font size, text/border/background
+  colour, border width):
+  - `addTextField(page, name, rect, value?, { maxLen, multiline, password, style })`
+  - `addCheckbox(page, name, rect, checked?, { export, style })`
+  - `addRadioGroup(page, name, options: RadioOption[], { selected, style })`
+  - `addComboBox(page, name, rect, options, { selected, editable, style })`
+  - `addListBox(page, name, rect, options, { selected, multi, style })`
+
+  Every widget is given a real `/AP` appearance stream (text baseline, a vector
+  tick for checkboxes, a filled dot for radios) **and** the form is flagged
+  `NeedAppearances`, so fields display immediately and stay faithful when edited.
+- **Advanced flexbox + real grid** in the HTML renderer:
+  - `flex-direction: column`, `justify-content` (start/center/end/space-between/
+    space-around) and per-item `flex-grow` (proportional column widths);
+  - `display: grid` with `grid-template-columns` (fixed column count; children
+    wrap into rows). `float` still maps to inline-block.
+- **ES module syntax** is now parsed transparently by the JS engine (`import` is
+  elided, `export` declarations run as normal statements).
+
+## [0.3.0] - 2026-06-15
+
+### Added
+
+- **JavaScript engine** (zero-dependency, pure Rust → WASM). A document's inline
+  `<script>`s now execute **before layout** inside `htmlRender` /
+  `htmlNeededFonts` — no Chromium/Playwright — so script-driven content renders.
+  The engine covers:
+  - Language: classes + `super`, closures, destructuring, spread, optional
+    chaining, template literals, `for…of`, generators (`function*`/`yield`,
+    eager), `async`/`await` + `Promise` (deterministic synchronous microtask
+    model), `try/catch/finally`, labelled loops, `arguments`.
+  - Built-ins: `Object`/`Array`/`String`/`Number`/`Boolean`/`Math`/`JSON`/
+    `console`/`Map`/`Set`/`RegExp` (a from-scratch backtracking regex engine)/
+    `Error`, plus `parseInt`/`parseFloat`/`setTimeout`/`queueMicrotask`.
+  - DOM bindings: `document.getElementById`/`getElementsByTagName`/
+    `querySelector(All)` (combinators `>`/`+`/`~`, attribute selectors), and on
+    elements `textContent`/`innerHTML`/`getAttribute`/`setAttribute`/
+    `appendChild`/`removeChild`/`classList`/`style`/`children`.
+- **Page breaks** in the HTML renderer: CSS `page-break-before|after: always`,
+  `break-before|after: page`, a `<pagebreak>` element, or `class="page-break"`
+  start the following content on a new page.
+- **CSS flexbox** (`display: flex` / `inline-flex`) — a basic equal-column row;
+  `grid` falls back to block flow and `float` to inline-block.
+
+### Notes
+
+- `htmlRender` / `htmlNeededFonts` are unchanged in signature — they simply run
+  the document's scripts first. No new SDK call is required.
+
+## [0.2.0] - 2026-06-15
+
+### Added
+
+- Vector drawing primitives on `GigaPdfDoc`: `drawLine`, `addEllipse`,
+  `addPolygon`, and `addPath` — the latter accepts arbitrary SVG path data
+  (`M`/`L`/`H`/`V`/`C`/`S`/`Q`/`T`/`A`/`Z`, absolute & relative), converting
+  quadratic Béziers to cubics and flipping the Y axis like `pdf-lib`'s
+  `drawSvgPath`. Covers freeform/polygon/triangle shapes.
+- `addImage`: embed PNG or JPEG rasters as image XObjects. JPEG is stored
+  losslessly via `/DCTDecode`; PNG is decoded in-engine (zero-dependency) with
+  its alpha channel honoured through a `/SMask` soft mask.
+- `opacity` (fill + stroke alpha through a transient `/ExtGState`) on every
+  shape and image (`addRectangle`, `drawLine`, `addEllipse`, `addPolygon`,
+  `addPath`, `addImage`).
+- `toOdp`: convert a PDF to an editable OpenDocument Presentation (`.odp`) —
+  one slide per page with positioned text boxes, pictures and shapes. This
+  completes **bidirectional ODF** (`.odt` / `.ods` / `.odp` both ways, the
+  reverse via `officeToPdf`), round-trip validated through LibreOffice Impress.
+- **HTML → PDF rendering engine** (`htmlNeededFonts` + `htmlRender`): a
+  zero-dependency in-engine pipeline — HTML parser → CSS cascade (selectors,
+  specificity, inheritance, UA defaults) → block / inline / table layout with
+  pagination → paint — that renders HTML + CSS to PDF **without a headless
+  browser**. Text is set in **embedded Google fonts** resolved against the full
+  catalogue (real glyphs + metrics → identical or nearest match). Validated
+  end-to-end: Roboto downloaded, embedded (`emb=yes`, Identity-H) and the output
+  opens in LibreOffice. JavaScript execution is not included (a separate engine).
+
+### Changed
+
+- `addRectangle` gains a trailing optional `opacity` argument — backward
+  compatible (defaults to `1`).
+
+[0.2.0]: https://github.com/qrcommunication/gigapdf-lib/releases/tag/v0.2.0
+
 ## [0.1.0] - 2026-06-14
 
 ### Added

package/README.md

@@ -36,7 +36,7 @@ doc.redact(1, 72, 700, 180, 14); // physically remove content in a region
 doc.addHighlight(1, 72, 690, 252, 704, 0xffff00);
 
 // Convert
-const docx = doc.toDocx(); // also: toPptx/toOdt/toXlsx/toOds/toHtml/toText/toRtf/toPdfA
+const docx = doc.toDocx(); // also: toPptx/toOdp/toOdt/toXlsx/toOds/toHtml/toText/toRtf/toPdfA
 const png = doc.renderPage(1, 2); // rasterize a page
 
 // Save
@@ -52,6 +52,27 @@ const fromHtml = giga.htmlToPdf("<h1>Hello</h1>");
 const fromRtf = giga.rtfToPdf(rtfString);
 ```
 
+### Build an interactive form (no `pdf-lib`)
+
+```ts
+// Coordinates are PDF user space (origin bottom-left): [x0, y0, x1, y1].
+doc.addTextField(1, "fullname", [50, 700, 300, 720], "", { maxLen: 60 });
+doc.addCheckbox(1, "subscribe", [50, 670, 64, 684], true, { export: "Yes" });
+doc.addRadioGroup(1, "plan", [
+  { export: "Basic", rect: [50, 640, 64, 654] },
+  { export: "Pro", rect: [80, 640, 94, 654] },
+], { selected: "Pro" });
+doc.addComboBox(1, "country", [50, 610, 200, 626], ["FR", "US", "DE"], { selected: "FR" });
+doc.addListBox(1, "langs", [50, 540, 200, 600], ["en", "fr", "de"], { multi: true });
+
+// Optional per-field styling.
+doc.addTextField(1, "vat", [50, 510, 200, 528], "", {
+  style: { fontSize: 11, color: 0x102030, border: 0x888888, background: 0xf5f5f5 },
+});
+
+const filled = doc.fields(); // read them straight back: kind + value + options
+```
+
 ### Fonts (host performs the network fetch)
 
 ```ts
@@ -84,16 +105,43 @@ Or call `GigaPdfEngine.load(bytes)` with bytes you read yourself.
   `txtToPdf`/`htmlToPdf`/`rtfToPdf`/`officeToPdf`, `fontCatalog`/`fontRequestUrl`/`parseCssFontUrl`.
 - **`GigaPdfDoc`** — text intelligence (`textRuns`, `structuredText`, `search`,
   `ocr`, `ocrText`, `elements`, `elementAt`), editing (`replaceText`,
-  `removeElement`, `moveElement`, `duplicateElement`, `addRectangle`, `redact`),
-  pages (`rotatePage`, `deletePage`, `movePage`, `appendPages`, `extractPages`),
+  `removeElement`, `moveElement`, `duplicateElement`, `redact`), vector drawing
+  (`addRectangle`, `drawLine`, `addEllipse`, `addPolygon`, `addPath` (SVG path),
+  `addImage` (PNG/JPEG, alpha + opacity)), pages (`rotatePage`, `deletePage`,
+  `movePage`, `appendPages`, `extractPages`, `resizePage`, `addPage`, `copyPage`,
+  `pageInfo`),
   `renderPage`, fonts (`embedFont`, `addText`, `neededFonts`), conversions
-  (`toText/Html/Docx/Pptx/Odt/Xlsx/Ods/Rtf/PdfA`), security (`saveEncrypted`,
+  (`toText/Html/Docx/Pptx/Odp/Odt/Xlsx/Ods/Rtf/PdfA`), security (`saveEncrypted`,
   `sign`), metadata (`getMetadata`, `setMetadata`), annotations (`addSquare`,
   `addHighlight`, `addLineAnnotation`, `addFreeText`, `addUnderline`,
   `addStrikeOut`, `addInk`, `addStamp`, `annotations`, `removeAnnotation`,
   `flattenAnnotations`), links (`links`, `addUriLink`, `addGotoLink`), outline
-  (`outline`, `setOutline`), and forms (`fields`, `setTextField`, `setCheckbox`,
-  `setRadio`, `setChoice`).
+  (`outline`, `setOutline`), forms — read/fill (`fields`, `setTextField`,
+  `setCheckbox`, `setRadio`, `setChoice`) **and create**
+  (`addTextField`, `addCheckbox`, `addRadioGroup`, `addComboBox`, `addListBox`,
+  each with an optional `FieldStyle`), and optional-content layers (`layers`,
+  `addLayer`, `setLayerVisibility`, `setLayerLocked`, `removeLayer`).
+- **HTML rendering engine** (on `GigaPdfEngine`) — `htmlNeededFonts(html)`
+  returns the Google fonts to download (phase 1); `htmlRender(html, fonts,
+  pageW?, pageH?, margin?)` renders HTML + CSS to PDF with those fonts embedded
+  (phase 2). **No headless browser.** Block / inline / table / **flex**
+  (`flex-direction`, `justify-content`, `flex-grow`) / **grid**
+  (`grid-template-columns`) layout, selector cascade, pagination, and forced page
+  breaks via CSS `page-break-before|after: always` / `break-*: page` or a
+  `<pagebreak>` tag. **See the exhaustive list of supported HTML elements, CSS
+  properties, units, colours and selectors in
+  [`docs/HTML-CSS.md`](https://github.com/QrCommunication/gigapdf-lib/blob/main/docs/HTML-CSS.md).**
+- **JavaScript** — a document's inline `<script>`s run **before layout** through
+  a built-in zero-dependency JS engine (no Chromium/Playwright), so script-driven
+  content is rendered. It covers classes + `super`, closures, destructuring,
+  `RegExp`, `Map`/`Set`, `Symbol`, `eval`/`Function`, and DOM bindings
+  (`document.getElementById`, `querySelector(All)` with `>`/`+`/`~`/`[attr]`,
+  `textContent`, `innerHTML`, `createElement`/`appendChild`, `classList`,
+  `style`). `function*`/`async` bodies compile to a **suspendable bytecode VM**,
+  so generators are **truly lazy** (infinite generators, bidirectional
+  `.next(v)`, `yield*`) and `await` **yields** with spec microtask ordering. This
+  happens automatically inside `htmlRender`/`htmlNeededFonts` — no extra call
+  needed.
 
 Every method is fully typed. Always `close()` a document when done to free the
 WASM handle.