@quario/pdf 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,39 +1,51 @@
-# Changelog
+# @quario/pdf
 
-All notable changes to @quario/pdf are documented in this file.
+## 0.8.0
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+### Minor Changes
 
-## [Unreleased]
+- **An image's box is now as wide as the container it sits in.** A
+  `background` or `border*` on an image item hugged the picture and now spans
+  the content width, or the slot's share inside a split; the picture itself
+  does not move. See the `@quario/layout` changelog for the rule and for what
+  it costs a report that relied on a border hugging a logo.
 
-## [0.7.0] - 2026-09-07
+### Patch Changes
 
-### Added
+- **Every published README says where the documentation is.** Each package now
+  carries a Documentation section pointing at the reference, at the report schema
+  that normatively specifies what a report may declare, and at the package's own
+  API. The paragraphs that used to end on an unstated contract — the event
+  stream's field semantics, the style vocabulary, page columns, the Content
+  Security Policy a fragment with images needs, the formula mangling, and each
+  target's own contract — link the page that states it. Every link is an absolute
+  URL, so it resolves from the npm package page as readily as from an installed
+  copy.
+- Updated dependencies
+  - @quario/layout@0.5.0
+  - quario@0.8.0
+
+## 0.7.0
+
+### Minor Changes
 
 - **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
+## 0.6.0
 
-### Added
+### Minor Changes
 
 - **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
@@ -42,9 +54,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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,
@@ -54,9 +63,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
+## 0.5.0
 
-### Added
+### Minor Changes
 
 - **A spanning cell draws as one box** across the columns it covers, through
   `@quario/layout`. It takes no part in measuring them, and a spanning row that
@@ -64,16 +73,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   each slice lands in.
 - **`valign`** on table cells and split slots, through `@quario/layout`: middle
   and bottom place the content in the height its row or split leaves over it.
-
-### Changed
-
 - **A row's box is drawn by the row's cells**, through `@quario/layout`. A box
   declared on a table row used to be one rect across the columns; each covered
   cell now draws its own. A row's `borderBottom` still reads as one continuous
   edge, a row's `borderLeft` becomes an edge on every cell rather than one at
   the row's outer left, and a bordered row is taller by its border's width,
   since a border occupies height as a cell's always has.
-
 - **Embedding TrueType fonts now needs `fontkit`, not `@pdf-lib/fontkit`.**
   Install `fontkit` instead; nothing else about `options.fonts` changes. The
   old package's bundle crashed with a bare `ReferenceError` on any OpenType
@@ -81,28 +86,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Tamil, Khmer or Myanmar webfont in practice, and some fifty further scripts
   besides. Those faces now measure, embed and draw. Which scripts a face
   supports remains the font's and the parser's to answer, not this package's.
-
 - **`pdf-lib` is now `@cantoo/pdf-lib`.** A maintained fork, and what
   `fontkit`'s subsetting requires. Rendered documents are unchanged in what
   they draw: every drawn string is identical and every filled area lands in
   the same place, but the file's bytes differ, so a host comparing digests
   against stored output will see them move once.
 
-## [0.4.0] - 2026-09-03
+## 0.4.0
 
-### Changed
+### Minor Changes
 
 - **A split slot's box now fills the split's height.** A slot's background and
   border stopped at that slot's own content and now take the split's height,
   the way a table cell's take their row's. See the `@quario/layout` changelog
   for the rule and for what it costs a report that relied on the short box.
-
 - **A date string under `format: "date"` now presents as a date.** The
   drawn text comes from the engine's `format()` helper, which revives the two
   read forms. See the `quario` changelog for the forms and the timezone rule.
-
-### Changed
-
 - **The layout moved to `@quario/layout`; this target paints its list.**
   Measurement, wrapping, pagination, page furniture, the marking's geometry
   and the page-size table now live in the layout package, which this target
@@ -112,16 +112,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   options are the layout's own, so the same object configures `pdf()`, the
   viewer and the editor. The font mapping's shape is now refused at the
   factory call rather than at render.
-
-### Fixed
-
 - **A nested group's footer keeps the page columns.** Inside a page-column
   region, the first footer of a group nested in it ended the region: the
   strips collapsed and every band after it was laid out across the page, as
   if `columns` were absent. Only the node that declared `columns` closes its
   own region now — a nested group's header and footer are region content,
   laid out in the strips.
-
 - **A padded or bordered item or row that breaks across a page keeps its
   box.** Content too tall for one page is drawn as slices, and a slice now
   carries the box sides the break left it — the top on the first, the bottom
@@ -133,60 +129,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the horizontal padding they were wrapped for, rather than flush to the
   column. **This changes output** for reports where such content breaks.
 
-## [0.3.0] - 2026-09-02
+## 0.3.0
 
-### Added
+### Minor Changes
 
 - **`format` stringifies at the edge from the instance locale.** A PDF
   without a host locale still uses `en-US` / UTC, so the bytes stay
   reproducible.
-
 - **A height-declared report header pins from the page top.** Leftover sits
   under the items; the next band starts at the pin. The half-line group gap
   drops after it. `page.margin` on the document is the inset when the host
   omits it; both is a render error.
-
 - **`spaceBefore` / `spaceAfter` skip the cursor.** Adjacent gaps add.
   `spaceBefore` drops at a fresh body page or strip top; page-band items
   keep it.
-
 - **The box is honoured in layout.** Padding and border inset wrap width; a
   named padding `0` beats the cell omakase (`PADX` 6 / `PADY` 2) on that
   side. Incomplete sides draw nothing.
-
-### Changed
-
 - **The last data row keeps the whole emitted total block.** A stack taller
   than a page degrades like a tall row.
-
 - **An unstyled table has no rules.** This target used to draw two 0.5 pt
   rules, under the header and above the total, that no declaration could
   ask for or refuse. Those strokes are gone. The strokes an author wants
   are the box they declared. Cell padding omakase stays on undeclared cell
   sides.
-
 - **A visible text item occupies a line at its own `size`, empty or not.** An
   empty or whitespace-only value used to sit at the report's base leading
   (~14 pt at the 10 pt baseline). It now occupies `1.4 ×` the item's size, the
   same as a glyph line. A literal newline is a line break; the blank line
   among `"a\n\nb"` is that size too. A table cell that is empty or only
   horizontal whitespace still has no content height.
-
-### Fixed
-
 - **A missing TrueType glyph draws as `?`, not `.notdef`.** Characters
   outside WinAnsi already substituted `?`; an embedded face's cmap holes
   drew a box instead, and text extraction hid it. Same rule for every
   face: a character the face cannot draw becomes `?`.
-
 - **CR, LF, and CRLF are one hard line break.** Cell text already broke
   on LF; a CRLF left a CR on the previous line, and a lone CR did not
   break. All three are now one break, matching `SCHEMA.md` Cell values.
   Wrapping still applies within each line.
 
-## [0.2.0] - 2026-09-01
+## 0.2.0
 
-### Added
+### Minor Changes
 
 - **The report default sets the document's face and base size.** A report's
   top-level `style` replaces this target's own baseline, so its `size` scales
@@ -194,12 +178,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   nothing is set in. It is the layer _under_ the band-role defaults: a report
   declaring `size: 12` still renders its report header at 14, and an item's own
   style wins over both.
-
 - **`uppercase` draws capitals.** With no text-transform to defer to, this
   target capitalises the string before measuring it, so wrapping and column
   widths are those of the text actually drawn. The mapping is Unicode default
   case, never the host's locale, so output stays byte-reproducible.
-
 - **Splits lay out across the content width.** Each slot is measured and
   wrapped inside its own share, all slots draw from a common top, and the
   split takes the height of its tallest slot so the band below clears them
@@ -208,27 +190,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   any page renders in full past the bottom margin. The split's own style is
   the layer under each slot's, and its `background` fills the whole split
   behind them.
-
-### Changed
-
 - **A bare `Date` draws as ISO 8601 UTC, the same on every machine.** Cell
   text and outline bookmark titles for `Date` values used `String(date)`,
   which bakes the host's timezone and locale into the document — at odds with
   this target's byte-reproducibility guarantee. Both now render through the
   engine's shared display rule, so a `Date` group key titles its bookmark
   with the same ISO text its cells draw.
-
-### Removed
-
 - **`options.baseSize`.** A document's type size is the document's own, so it
   is the report's `style.size` — portable, travelling with the definition to
   every target — rather than a host option one target honoured. Text with
   nothing declared still renders at 10 points. Replace `pdf({ baseSize: 11 })`
   with `"style": { "size": 11 }` on the report.
 
-## [0.1.0] - 2026-08-27
+## 0.1.0
 
-### Added
+### Minor Changes
 
 - **Paginated PDFs from the same compiled report.** The band flow places
   headers, groups, and tables; pdf-lib writes the file. Page furniture and an

package/README.md

@@ -198,6 +198,17 @@ per-page presence is normative; exact geometry is best-effort. A licensed render
 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.
 
+The full contract is [The PDF target](https://getquario.com/docs/diving-deeper/pdf-target/),
+with each declaration's fate in the
+[support matrix](https://getquario.com/docs/reference/support-matrix/).
+
+## Documentation
+
+[The quario documentation](https://getquario.com/docs/) is the reference.
+The [report schema](https://getquario.com/docs/reference/report-schema/) is the normative
+specification of what a report may declare, and
+[`@quario/pdf`](https://getquario.com/docs/reference/pdf/) is this package's own API.
+
 ## License
 
 Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer

package/lib/painter.js

@@ -80,6 +80,7 @@ let paintLine = ({ page, height }, op) =>
   });
 
 /** @type {(painter: Painter, op: any) => void} */
+// fallow-ignore-next-line code-duplication -- one operator path, so a face is embedded once per page; ink, baseline, rotation and opacity all differ, and the marking's draw stays its own
 let paintText = ({ page, height, fonts, faceKey }, op) => {
   let font = fontFor(fonts, op.font);
   page.pushOperators(
@@ -100,6 +101,7 @@ let paintText = ({ page, height, fonts, faceKey }, op) => {
 // face reuses the page's `faceKey` resource instead of growing the dictionary
 // per draw.
 /** @type {(painter: Painter, op: any) => void} */
+// fallow-ignore-next-line code-duplication -- one operator path, so a face is embedded once per page; ink, baseline, rotation and opacity all differ, and the marking's draw stays its own
 let paintMark = ({ page, height, fonts, faceKey }, op) => {
   let font = fontFor(fonts, op.font);
   page.pushOperators(
@@ -126,7 +128,7 @@ let paintMark = ({ page, height, fonts, faceKey }, op) => {
 // 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
+// item (quario-e0bz). The engine vouched for the magic numbers and
 // 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/pdf",
-  "version": "0.7.0",
+  "version": "0.8.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.4.0"
+    "@quario/layout": "^0.5.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.7.0",
+    "quario": "^0.8.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
     "fontkit": "^2.0.4",
-    "quario": "^0.7.0"
+    "quario": "^0.8.0"
   },
   "peerDependenciesMeta": {
     "fontkit": {