@quario/pdf 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-07
+
+### Added
+
+- **Styled runs reach the page.** A cell value written as a list of styled runs
+  draws each run in its own face, size and colour, underlines and strikes
+  through per run rather than across the line, and paints a run's `background`
+  as a highlight behind its text.
+
+### Changed
+
+- **A `format` inside a sentence now presents where the engine says it does.** A
+  cell mixing literal text and one interpolation under a `format` draws the
+  value plainly, as the spreadsheet and CSV targets already did; splitting the
+  value into styled runs is how a value inside a sentence is formatted.
+
+## [0.6.0] - 2026-09-07
+
+### Added
+
+- **A cell's own `currency` code is honoured**, ahead of the instance's
+  default, so a listing whose rows arrive in different currencies presents each
+  in its own. A code the engine could not accept leaves the cell as plain
+  display text rather than presenting it in the instance's currency.
+
+### Changed
+
+- **Numbers presented through `format` now show a fixed two fraction digits,
+  matching every other target.** `format: "number"` on `1000` renders
+  `1,000.00` where it rendered `1,000`, and `0.12345` renders `0.12` where it
+  rendered `0.123`; `format: "percent"` on `0.21` renders `21.00%` where it
+  rendered `21%`. `format: "currency"` follows the currency's own minor units,
+  so a JPY amount loses the two decimals it never had. `date` is unchanged, as
+  are grouping separators and symbol placement. The digits come from the
+  engine, so a cell reads the same here as it does in a workbook.
+
+### Fixed
+
+- **An image these bytes cannot embed now fails with the item's name on it.**
+  A PNG whose pixel data is corrupt past the size in its header used to reject
+  the render with `Invalid typed array length: 0` — the PDF writer's own words,
+  naming neither an image nor an item, so a report with two pictures gave no
+  way to tell which was at fault. The message now begins with the item's
+  `source` path and says the image could not be embedded, keeping the writer's
+  account after it and on `cause`. A JPEG is unchanged: its header is read but
+  its pixel data never is, so a corrupt one still embeds without complaint.
+
 ## [0.5.0] - 2026-09-05
 
 ### Added

package/README.md

@@ -58,8 +58,9 @@ const paged = {
 ```
 
 `visible: "=page.number > 1"` on a band is the cover-page recipe. Gate band _visibility_ on
-`page.number` only. Band heights are reserved before the real page count is known, so
-`=page.total > 10` reserves nothing. `page.total` is fine in band _text_.
+`page.number` only. Band heights are reserved before the real page count is known, probed as a
+two-page document, so `=page.total > 10` reserves only the 8 pt gap a declared band always costs.
+`page.total` is fine in band _text_.
 
 ## API
 
@@ -85,7 +86,9 @@ host. Render-time failures reject with located errors.
 
 ### Options
 
-Page geometry is target configuration, never schema:
+Page size and fonts are target configuration. The margin is the target's unless the document
+declares `page.margin`, in which case the document's is used; a document and a target that both
+declare one reject the render.
 
 ```js
 {
@@ -96,7 +99,7 @@ Page geometry is target configuration, never schema:
 ```
 
 `size` defaults to `A4` (595.28 × 841.89 pt); an array is a custom `[width, height]` in points. An
-unknown size name is a definition error, thrown by the factory. `margin` applies to all four sides and defaults to 54
+unknown size name is an error the factory throws. `margin` applies to all four sides and defaults to 54
 (0.75 in). Text renders at 10pt when nothing declares a size: a document's type size is the
 document's own, so it is the report's `style.size`, not a host option. Line leading is 1.4× a line's
 largest font size.
@@ -105,12 +108,12 @@ largest font size.
 
 **Guaranteed** normative behavior a conforming target must produce:
 
-- Table header rows repeat after every page break, with a rule under the header and above the
-  total row.
+- Table header rows repeat after every page break. An unstyled table draws no rules; an
+  authored border on a header row or a total row is drawn at the width written.
 - A group header always travels with its first content unit: the first detail lines, or a table's
   header plus its first row. An instance's headers also repeat at the top of every page it
   continues onto (outermost first, then content) and stop when the instance ends.
-- The total row keeps the last data row with it.
+- The total rows keep the last data row with them.
 - A row that fits on a page is never split across one.
 - `break: "page"` on a group opens a fresh page per instance.
 - `reset: "page"` on a group does the same and restarts `page.number` / `page.total` for that instance's sequence.
@@ -119,17 +122,32 @@ largest font size.
   nothing is a definition error, so there is no over-commitment case.
 - Hidden cells keep their column slot.
 - Page bands render on every page, their heights reserved out of the body area.
+- A report header declaring `height` pins a box of that many points from the page top; its items
+  pack from the top and the next band starts where the box ends.
+- Every group instance opens with a half-line gap, dropped at a page top; authored `spaceBefore`
+  drops at a fresh page or strip top the same way.
+- An item or row a page cannot hold whole still carries its box: each slice draws the sides the
+  break left it, the top on the first and the bottom on the last.
+- A split lays out as one block at the height of its tallest slot; every slot's box is the split's
+  height, and a slot's `valign` places its content in that slack, as a table cell's does in its
+  row's.
+- Page columns are strips: the flow fills one to its foot, moves to the next, and turns the page
+  once the last is spent; a table restates its headings at a strip head, a group's headers only
+  at a page head.
+- The band-role defaults (a bold, larger report header; bold group headers) sit under the
+  author's own style, and `uppercase` capitalises the drawn string before it is measured.
 - An image draws at the size its `fit` dictates (`natural` at 96 dpi capped at the content
   width, `width` scaled to it, aspect ratio preserved) and is never split across a page break:
   one that does not fit the remaining height moves whole to a fresh page.
 
-**Best-effort** current implementation, pinned by no test and changeable
-without a breaking change: paragraph widow and orphan avoidance, slicing a row taller than the
+**Best-effort** current implementation, pinned only as a regression guard where the layout suite
+holds it, and changeable without a breaking change: paragraph widow and orphan avoidance, the
+gutter between page-column strips and whether a region balances, slicing a row taller than the
 page, downscaling an image taller than any page, embedding repeated image bytes once, and where
 an image's page break lands. Do not write definitions that depend on these.
 
 Bands flow vertically in walk order, matching the HTML target's divs. Group nesting adds no
-indentation, but every instance opens with a structural half-line gap so groups read as blocks
+indentation, but every instance that draws opens with a structural half-line gap so groups read as blocks
 without authored margins.
 
 ## Fonts and text
@@ -153,7 +171,9 @@ const target = pdf({
 
 Missing variants fall back to the family's regular. Embedded text uses the font's own metrics, is
 subset to the glyphs the document uses, and carries a ToUnicode map so extraction and
-copy see the original text. Fonts are trusted host assets, like registered functions.
+copy see the original text. Fonts are trusted host assets, like registered functions. A mapping
+without a `regular` is refused by the factory (`options.fonts.<name>.regular: required`); bytes
+the parser cannot read reject the render, located at the same option path.
 
 ## Outline
 
@@ -175,8 +195,8 @@ per-page presence is normative; exact geometry is best-effort. A licensed render
 
 ## Page furniture
 
-Paper size, margins, and fonts are options, not schema. Authored watermarks and finer break
-control stay out of scope. Keep-together and continuation headers are by construction, above.
+Paper size and fonts are options, not schema; the margin is an option a document may declare in
+its stead. Authored watermarks and finer break control stay out of scope. Keep-together and continuation headers are by construction, above.
 
 ## License
 

package/lib/index.d.ts

@@ -1,7 +1,7 @@
 import type { LayoutFontFamily, LayoutPage } from "@quario/layout";
 import type { Target } from "quario";
 
-/** Page geometry, in PostScript points: the layout's own, never schema. */
+/** Page geometry, in PostScript points: the layout's own, its margin one a document may declare instead. */
 export type PdfPage = LayoutPage;
 
 /** Optional document information; never includes dates, so output stays deterministic. */

package/lib/painter.js

@@ -9,7 +9,7 @@
  * and one logo on every page is embedded once, the marking after them so an
  * image can never cover it (LICENSE section 6).
  */
-import { breathe } from "quario";
+import { breathe, imageError } from "quario";
 import { degrees, drawImage, drawText, rgb } from "@cantoo/pdf-lib";
 import { fontFor } from "./embed.js";
 
@@ -122,11 +122,45 @@ let paintMark = ({ page, height, fonts, faceKey }, op) => {
 
 // Keyed by the array the source expression yielded, so one logo reused
 // across pages is embedded once and every placement references it.
+//
+// The embedders parse the bytes, and what they throw when those bytes are bad
+// says nothing an author could act on: a corrupt PNG used to reach a host as a
+// bare `RangeError: Invalid typed array length: 0`, naming no image and no
+// item (quario-e0bz). The engine vouched for the magic numbers and the layout
+// read the size out of the header, so a file corrupt past that point arrives
+// here looking like any other and this is the first place that knows. The
+// embedder's own class and words survive behind the path, which is the shape
+// SCHEMA.md documents for every render error.
+//
+// **What this cannot promise is symmetry between the two formats.** pdf-lib's
+// PNG embedder decompresses the pixel data, while its JPEG embedder reads
+// markers alone and never the scan data, so a JPEG corrupt past its frame
+// header embeds without complaint and arrives here as no failure at all.
+// Corrupt scan data cannot be told from good without decoding the image, which
+// is not a cost a render should pay to find out what it is about to write.
+//
+// Closing part of the gap was weighed and declined (`quario-dqt8`). A JPEG
+// carrying no `SOS` at all is structural, as cheap to read as the size, so the
+// marker walk in `@quario/layout`'s `image.js` could say so — but measuring
+// what that catches settled it: a JPEG's headers are roughly fixed while its
+// scan grows with the image, so the check covers truncation only up to the
+// point the scan starts. On the 882-byte `logo.jpg` fixture that is 85% of the
+// file; on a photograph it is a fraction of a percent, and every truncation
+// worth worrying about lands past it. What it would buy is the shape of a
+// hand-built repro; what it would cost an author is a rule whose seam falls in
+// an arbitrary place — a JPEG whose scan never starts fails, one whose scan is
+// cut does not — and the PNG/JPEG asymmetry survives either way. So the line
+// stays where the engine's own guarantee stops.
 /** @type {(painter: Painter, op: any) => Promise<any>} */
 let imageOf = async ({ doc, embedded }, op) => {
   let image = embedded.get(op.bytes);
   if (!image) {
-    image = await (op.format === "png" ? doc.embedPng(op.bytes) : doc.embedJpg(op.bytes));
+    try {
+      image = await (op.format === "png" ? doc.embedPng(op.bytes) : doc.embedJpg(op.bytes));
+    } catch (cause) {
+      let said = /** @type {Error} */ (cause).message;
+      throw imageError(op.path, "the image could not be embedded: " + said, cause);
+    }
     embedded.set(op.bytes, image);
   }
   return image;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/pdf",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "The browserless, paginated PDF render target for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -37,20 +37,20 @@
   },
   "dependencies": {
     "@cantoo/pdf-lib": "^2.9.1",
-    "@quario/layout": "^0.2.0"
+    "@quario/layout": "^0.4.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
     "@types/fontkit": "^2.0.9",
     "fontkit": "^2.0.4",
-    "quario": "^0.5.0",
+    "quario": "^0.7.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
     "fontkit": "^2.0.4",
-    "quario": "^0.5.0"
+    "quario": "^0.7.0"
   },
   "peerDependenciesMeta": {
     "fontkit": {