@quario/xlsx 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,15 +1,74 @@
-# Changelog
+# @quario/xlsx
 
-All notable changes to @quario/xlsx 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]
+- **Every target factory now refuses an option it does not understand.** An unknown key, a key with
+  a value of the wrong type, or an `options` that is not an object throws a `TypeError` at the
+  factory call, naming the option path — `options.meta.title`, `options.page.size`. `@quario/docx`
+  already behaved this way. `@quario/pdf`, `@quario/html`, `@quario/xlsx` and `@quario/layout` read
+  the keys they knew and ignored the rest, so a typo cost you the option you meant to set with no
+  signal at any point. `csv()` takes no options, and it refuses an argument rather than discarding
+  one.
 
-## [0.7.0] - 2026-09-07
+  The check itself is one thing, so the engine now exports it: `hostOptions` closes a key set and
+  `hostMeta` validates the `{ title, author, subject }` contract the document targets share. A
+  fourth document property is one edit rather than three.
 
-### Added
+  **What this changes for you.** One options object spread across several targets stops working if
+  any target does not know one of its keys — `const o = { page, fonts, meta }` passed to `pdf(o)`,
+  `html(o)` and `xlsx(o)` is three different key sets. An object holding only what its consumers
+  share is unaffected, so `{ page, fonts }` into both `pdf()` and `layout()` still works.
+  TypeScript does not warn about this: excess-property checking fires on an object literal and not
+  on a variable, so a bag held in a `const` compiles clean and throws when you call the factory.
+
+  Nullish is absence everywhere, at both levels, so `{ meta: config.meta ?? null }` and
+  `{ meta: { title: config.title } }` over a config that carries neither are both fine.
+  `html({ paths })` now takes `true` or `false` rather than anything truthy, so `paths: "no"` throws
+  instead of turning path stamping on. A `fonts` mapping given as an array is refused by
+  `@quario/html` and `@quario/layout` rather than read as families named `0`, `1`, `2`.
+
+  Every host-option failure is now a `TypeError` rather than a plain `Error`. A `catch` that tests
+  `instanceof Error` is unaffected. One that compares the constructor is not.
+
+  `@quario/docx` is relaxed in three places, each of them now accepting what it refused: `meta: null`
+  and `page: null` are absence rather than errors, a property written as `meta: { title: undefined }`
+  is a property you did not write rather than one of the wrong type, and an inherited enumerable key
+  is no longer reported as an option you wrote.
+
+  `@quario/pdf`, `@quario/xlsx` and `@quario/docx` now copy `meta` at the factory call. Mutating the
+  object you passed no longer changes what a configured target writes.
+
+- **`meta` is now read once, at the factory call.** It was read inside the render, so a host that
+  mutated its options object between renders got a different workbook from the same configured
+  target. The documented behaviour was always the factory call. If you were mutating an options
+  object to change the document properties, build a new target instead.
+
+### Patch Changes
+
+- Updated dependencies
+  - quario@0.9.0
+
+## 0.7.1
+
+### Patch Changes
+
+- **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@0.8.0
+
+## 0.7.0
+
+### Minor Changes
 
 - **Styled runs become rich text.** A cell of more than one styled run is written
   as rich text, each run's font merged over the cell's — so bold, italic,
@@ -18,14 +77,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   only, and filling the cell would colour text nobody asked to colour. A cell of
   exactly one run stays a typed cell, so a single styled amount is still a
   number.
-
 - **A run inside a sentence presents its value.** A run holding one
   interpolation under a `format` shows the same decimals here as on the page,
   where a mixed cell used to show the bare value.
 
-## [0.6.0] - 2026-09-07
+## 0.6.0
 
-### Added
+### Minor Changes
 
 - **A date cell's number format follows the `form` its report declares.** The
   four forms map to `dd/mm/yy`, `dd mmm yyyy`, `dd mmmm yyyy` and
@@ -33,26 +91,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   weekday name is spelled in stays the reader's, because that is what a
   spreadsheet application supplies and pinning it would stop the file reading
   naturally for whoever opens it.
-
 - **A declared digit count builds the pattern.** A `number` cell asking for
   three digits writes `#,##0.000`, and a `currency` cell asking for none writes
   `"EUR"#,##0` — the same count the page presents, taken off the declaration
   the engine resolved rather than computed here.
-
 - **A cell's own `currency` code picks the number format**, ahead of the
   instance's default: `"JPY"#,##0` where the row says `JPY`, since the code
   decides the digits too. The cell stays a number either way. A code the engine
   could not accept writes no number format at all, rather than labelling the
   cell in the instance's currency.
-
-### Changed
-
 - **A `date` cell with no declared form now writes `dd mmm yyyy`, not
   `yyyy-mm-dd`.** A bare `date` means the `medium` form throughout, so the grid
   agrees with the page. A report that wants the ISO shape has no form for it;
   the nearest is `{ "kind": "date", "form": "short" }`, which writes
   `dd/mm/yy`. The cell is still a real typed date either way.
-
 - **A cell's number format now comes from the engine's fraction-digit count
   rather than from four patterns this target held of its own.** The visible
   change is `currency`: the pattern followed the currency's own minor units,
@@ -61,7 +113,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   (`#,##0.00`), `percent` (`0.00%`) and `date` (`yyyy-mm-dd`) are unchanged in
   a worksheet; what changed for those is that HTML and PDF now show the same
   decimals the grid always did, instead of their own.
-
 - A `currency` code that is not a readable currency no longer produces a number
   format at all. The cell keeps its value; before, the code was pasted straight
   into a pattern while every other target fell back to the unformatted value.
@@ -70,39 +121,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   position still come from the application that opens the file, which is what
   lets one workbook read naturally wherever it is opened.
 
-### Fixed
-
 - A `format` kind reaching this target from an `=` expression is now looked up
   as an own key. Before, a kind resolving to the name of a built-in object
   member threw out of the render (`valueOf`, `hasOwnProperty`) or wrote
   `[object Undefined]` into the cell's number format (`toString`). A literal
   was never affected: it is checked against the four kinds.
-
-### Fixed
-
 - **An image whose size cannot be read now names the item that asked for it.**
   The failure said only that the size could not be read from the bytes, so a
   report with two pictures gave no way to tell which one was bad. The message
   now begins with the item's `source` path, as every other render error does
   and as it does from every other target.
 
-## [0.5.0] - 2026-09-05
+## 0.5.0
 
-### Added
+### Minor Changes
 
 - **Chrome merges, data does not.** A cell spanning several columns in the
   header row or a total row is written into the first column it covers, the
   rest of the range is written empty, and the range is merged. Nothing in the
   data region merges, so sort, filter and column selection keep working over
   it.
-
 - **`valign`** writes the cell's vertical alignment for table cells and split
   slots. Undeclared writes nothing, so the spreadsheet application keeps its
   own default.
 
-## [0.4.0] - 2026-09-03
+## 0.4.0
 
-### Changed
+### Minor Changes
 
 - **A date string under `format: "date"` now reaches the grid as a date.**
   The cell carries a real date value under the `yyyy-mm-dd` number format
@@ -110,83 +155,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   cell declaring the kind is affected; a string in a form the engine does not
   read stays text. See the `quario` changelog for the forms.
 
-## [0.3.0] - 2026-09-02
+## 0.3.0
 
-### Added
+### Minor Changes
 
 - **`format` maps to a number format; the cell stays typed.** `number` is
   `#,##0.00`, `percent` `0.00%`, `date` `yyyy-mm-dd`, `currency` the
   instance currency code as `"USD"#,##0.00`. A kind on the wrong type
   contributes nothing.
-
 - **Cell borders map; padding and flow spacing do not.** `solid` is exceljs
   `thin`; `dashed` and `dotted` keep their names. A header-row, row, or
   total-row box fans onto that row's cells; a cell that named any of a
   side's three keys owns that side whole. Padding is unread: a worksheet
   cell has no inset. Flow spacing is unread: a grid has no flow.
-
 - **`page.margin` and report-header `height` are unread.** A grid has no
   page top to pin from.
-
-### Changed
-
 - **A table total emits N rows.** Each `total-row` is one worksheet row, as
   each data row is.
-
 - **A cell whose display contains a newline wraps.** `wrapText` is this
   target's mapping of a literal newline as a line break, so `"one\ntwo"` is
   two lines in the grid. Single-line cells are unchanged.
 
-## [0.2.0] - 2026-09-01
+## 0.2.0
 
-### Added
+### Minor Changes
 
 - **The report default reaches every cell.** A report's top-level `style`
   replaces this target's baseline, so a document declaring a face and size gets
   them in cells that declare nothing of their own. It is the layer under the
   band-role defaults — a report declaring `size: 12` still writes its report
   header at 14 — and under each cell's own style.
-
 - **`uppercase` is accepted and deliberately not read.** A spreadsheet font
   has no text-transform, and writing capitals into the cell instead would turn
   presentation into data — the cell would stop round-tripping and would sort
   differently. The cell keeps the text you wrote; every other declaration on
   it still applies. Same posture as the column widths this target withdrew.
-
 - **A split is one row, its slots the cells across it.** The grid's own
   reading of values placed beside each other. Slot `width` shares go unread,
   on exactly the ground the table's column widths do — a worksheet's columns
   are global to the sheet. The split's own style is what its slots sit under,
   layering the way a table row's does, and a slot that renders nothing writes
   an empty cell so the cells either side keep their columns.
-
-### Changed
-
 - **Every cell is written at 10 points unless something declares otherwise.**
   The size was previously left to the writer's own default of 11. Now that a
   report can declare its own size, this target and the PDF carrying different
   numbers for one declaration is exactly what the targets' agreement rule
   forbids. A worksheet's row height follows its font size, so existing unstyled
   sheets come out slightly tighter.
-
 - **Display-text `Date`s join as ISO 8601 UTC.** A `Date` inside a mixed
   cell (literal text plus interpolation) joined through `String(date)`, which
   bakes the host's timezone and locale into the worksheet. It now joins
   through the engine's shared display rule as `toISOString()` text. Typed
   cells are untouched: a cell that is one bare `Date` interpolation still
   writes a native date.
-
-### Fixed
-
 - **Cells carry their font face explicitly.** Text declaring no `family` used
   to inherit whatever the workbook writer defaulted to, which agreed with the
   other targets only by coincidence. It now writes the same face that
   `family: "sans"` resolves to, so the baseline is a rule rather than a
   property of the library underneath.
 
-## [0.1.0] - 2026-08-27
+## 0.1.0
 
-### Added
+### Minor Changes
 
 - **A workbook from the same compiled report.** Bands become rows; a bare
   interpolation that is a number, boolean, or Date stays that type. The first

package/README.md

@@ -13,12 +13,12 @@ can keep working in, not a grid of strings.
 npm install quario @quario/xlsx
 ```
 
-[exceljs](https://github.com/exceljs/exceljs) comes along as a dependency; the engine is a peer, installed beside it. ESM-only,
+[exceljs](https://github.com/exceljs/exceljs) arrives as a dependency. The engine is a peer, installed beside it. ESM-only,
 Node 22+, and browser-ready through any standards-based ESM bundler. The renderer returns bytes,
 so you decide where they go.
 
-> The writer is an implementation detail: exceljs is confined to a single internal module, so it
-> can be swapped behind this exact API without a breaking change.
+> The writer is an implementation detail. This package confines exceljs to a single internal
+> module, so a later version can swap it behind this exact API without a breaking change.
 
 ## Quick start
 
@@ -33,11 +33,11 @@ const bytes = await report.render(xlsx({ meta: { title: "Sales 2026" } }), data)
 writeFileSync("sales.xlsx", bytes);
 ```
 
-Any schema the other targets render works here unchanged. A spreadsheet has no pages, so page bands
-are ignored.
+Any schema the other targets render works here unchanged. A spreadsheet has no pages, so this
+target ignores page bands.
 
 One tip that changes the output a lot: **interpolate the bare value, not a formatter.** A cell
-written `{{ @.amount }}` becomes a real numeric cell; `{{ currency(@.amount) }}` becomes text,
+written `{{ @.amount }}` becomes a real numeric cell. `{{ currency(@.amount) }}` becomes text,
 because the formatter already turned the number into a string. Let the spreadsheet do the
 formatting it is good at.
 
@@ -45,8 +45,9 @@ formatting it is good at.
 
 ### `xlsx(options?)`
 
-The target factory: it takes this target's host options and returns the target you pass to
-`render`. `report()` compiles once and `report.render(xlsx(options), data)` resolves the
+The target factory takes this target's host options, validates them at the call, and returns the
+target you pass to `render`. The factory refuses an option it does not know. It throws a `TypeError` at the call for an unknown key. It throws one also for a key with a value of the wrong type. It also reads `meta` at the call. One configured target
+therefore always writes the same document. `report()` compiles once and `report.render(xlsx(options), data)` resolves the
 workbook bytes. Compile at startup, render per request. Definition problems throw at
 `report()`, at compile time.
 
@@ -59,7 +60,7 @@ The compiled report carries `stream` (the raw event generator), `names`, `functi
 `paths`, like every quario report. Engine-level options (`query` budgets, the license key)
 live on the instance, and `q.license` settles with the verification result.
 
-Rendering is asynchronous and hands the loop back between batches, so a large report never blocks the
+Rendering is asynchronous and returns the loop between batches, so a large report never blocks the
 host. Render-time failures reject with located errors.
 
 ### Options
@@ -74,12 +75,12 @@ host. Render-time failures reject with located errors.
 
 One worksheet, named `Report`, with the banded walk flattened onto it as rows in render order:
 report-header items, then per group instance its header items, nested content, and footer items,
-then the table's header row, data rows, and total rows, then report-footer items. Grouping shows up
-as that order alone. Group boundaries add no rows of their own, and `break: "page"` and
-`reset: "page"` are ignored, as are `page.margin` and a report header's `height`.
+then the table's header row, data rows, and total rows, then report-footer items. Grouping exists
+as that order alone. Group boundaries add no rows of their own. This target ignores `break: "page"`,
+`reset: "page"`, `page.margin`, and a report header's `height`.
 
-Each item takes one row with its cell in the first column, unmerged; a split takes one row with its
-slots as the cells across it (slot widths withdrawn, a slot rendering nothing an empty cell), and a
+Each item takes one row with its cell in the first column, unmerged. A split takes one row with its
+slots as the cells across it (slot widths withdrawn, a slot rendering nothing an empty cell). A
 spanning header or total cell is a merged range. Two band roles carry an
 omakase default that the author's own style always overrides: report-header items render bold at
 size 14, group-header items render bold.
@@ -99,9 +100,9 @@ A hidden cell keeps its column slot as an empty cell that retains its style.
 
 `format` writes a number format so the grid presents what the other targets do. `date` builds
 its pattern from the cell's `form` (`dd mmm yyyy` undeclared), with month and weekday names
-spelled by the reader's application; the number kinds build theirs from the declaration's
-fraction-digit count — an undeclared `number` is `#,##0.00`, `percent` is `0.00%`,
-`{ "kind": "number", "digits": 3 }` is `#,##0.000` — and `currency` is the code the cell wears
+spelled by the reader's application. The number kinds build theirs from the declaration's
+fraction-digit count: an undeclared `number` is `#,##0.00`, `percent` is `0.00%`, and
+`{ "kind": "number", "digits": 3 }` is `#,##0.000`. `currency` is the code the cell wears
 — its own `currency` when it declares one, else the instance's — over that currency's minor
 units unless `digits` says otherwise: `"USD"#,##0.00`, `"JPY"#,##0`, `"BHD"#,##0.000`. A kind
 on the wrong type, or a code the engine cannot read, writes no format.
@@ -110,25 +111,27 @@ on the wrong type, or a code the engine cannot read, writes no format.
 
 An image item is not a cell: it takes one worksheet row as its anchor and floats over the sheet as a
 drawing at its natural pixel size. Placement here is best-effort. `fit`, `alt`, and `style` are
-unused, and all of it may change without a breaking change. Bytes too short to carry a size reject
-the render rather than vanish.
+unused, and all of it may change without a breaking change (see the
+[support matrix](https://getquario.com/docs/reference/support-matrix/#output)). Bytes too short to
+carry a size never reach this target: the engine reads every image's size and rejects them for
+every target alike.
 
 ### Styles
 
 | Declaration                                            | Maps to                                                                                                                              |
 | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `family`                                               | `sans` → Calibri, `serif` → Times New Roman, `mono` → Courier New; any other name passes through for the host application to resolve |
+| `family`                                               | `sans` → Calibri, `serif` → Times New Roman, `mono` → Courier New. Any other name passes through for the host application to resolve |
 | `size`, `bold`, `italic`, `underline`, `strikethrough` | Font (`strikethrough` → writer's `strike`)                                                                                           |
 | `color`, `background`                                  | Font colour, solid fill                                                                                                              |
 | `align`                                                | Horizontal alignment                                                                                                                 |
-| `valign`                                               | Vertical alignment; undeclared writes nothing, so the spreadsheet application keeps its own default                                  |
-| `border*`                                              | Cell borders (`solid` → `thin`, `dashed`, `dotted`; width approximated); a row's borders arrive on its cells already                 |
+| `valign`                                               | Vertical alignment. Undeclared writes nothing, so the spreadsheet application keeps its own default                                  |
+| `border*`                                              | Cell borders (`solid` → `thin`, `dashed`, `dotted`, with width approximated). A row's borders arrive on its cells already            |
 | `format`, `currency`                                   | A number format — see [Number formats](#number-formats)                                                                              |
 | `uppercase`, `padding*`, `spaceBefore`, `spaceAfter`   | Not read: a grid has no text-transform, no cell inset of its own, and no flow                                                        |
 
 Style blocks layer row under cell, as everywhere in quario, with the report default outermost.
-Every cell is written at 10 points unless something declares otherwise, and a cell whose display
-contains a newline wraps.
+This target writes every cell at 10 points unless something declares otherwise, and a cell whose
+display contains a newline wraps.
 
 ### Freeze
 
@@ -145,28 +148,40 @@ table for a share to be a share of.
 
 ### Page columns are withdrawn
 
-A page column count sizes and splits nothing here, and will not change, as `break: "page"` is
-ignored. Page columns are strips of a page, and this target has no page to strip.
+A [page column](https://getquario.com/docs/reference/support-matrix/#page-and-pagination) count
+sizes and splits nothing here, and will not change, as this target ignores `break: "page"`. Page columns
+are strips of a page, and this target has no page to strip.
 
 ## Unlicensed marking
 
 An unlicensed render writes the wording from `report-start.marking` twice: as a styled banner in
 row 1 (so the whole report, frozen view included, sits one row lower than a licensed render), and
-as the workbook's description property. Both are normative; banner styling is best-effort. A
+as the workbook's description property. Both are normative. Banner styling is best-effort. A
 licensed render has no banner and no description marking.
 
 ## Determinism
 
-The document model is deterministic: the workbook's dates are pinned rather than stamped, and
-`meta` is opt-in. The **bytes** are not. The writer stamps archive entries with the packing time.
+The document model is deterministic. This target pins the workbook's dates rather than stamping
+them, and `meta` is opt-in. The **bytes** are not. The writer stamps archive entries with the packing time.
 Compare extracted content, not digests.
 
+The full contract is [The XLSX target](https://getquario.com/docs/diving-deeper/xlsx-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/xlsx`](https://getquario.com/docs/reference/xlsx/) is this package's own API.
+
 ## License
 
-Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
-licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+Commercial software with readable source. Evaluation is free, unlimited, and watermarked.
+Per-developer licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
 
-Pass your license key once, on the instance; it is verified offline:
+Pass your license key once, on the instance. quario verifies it offline:
 
 ```js
 const q = quario({ license: "quario_..." });

package/lib/index.d.ts

@@ -7,7 +7,12 @@ export interface XlsxMeta {
   subject?: string;
 }
 
-/** Host controls, taken at the factory call. */
+/**
+ * Host controls, taken and validated at the factory call: an option this
+ * target does not understand, or one of the wrong type, throws a `TypeError`
+ * there rather than costing the host the option in silence. `meta` is read
+ * there too, so one configured target always writes the same document.
+ */
 export interface XlsxOptions {
   meta?: XlsxMeta;
 }

package/lib/index.js

@@ -15,10 +15,9 @@
  * the packing time. Byte-for-byte output is a goal for the writer that will
  * replace `workbook.js`.
  */
-import { imageError, walk } from "quario";
+import { hostMeta, hostOptions, walk } from "quario";
 import { field } from "./cell.js";
 import { merge as under } from "./style.js";
-import { pixels } from "./image.js";
 import { append, create, embed, freeze, mark, place, save, sheet, span } from "./workbook.js";
 
 // The options are described once, in the hand-written public declarations, and
@@ -67,14 +66,22 @@ let BANNER = { bold: true, background: "#fff2cc" };
  * runs the engine's `walk` driver over the handlers below, so large reports
  * stay cooperative.
  *
+ * Host controls are taken and validated here, at the factory call: an option
+ * this target does not understand, or one of the wrong type, throws where the
+ * host wrote it rather than costing them the option in silence
+ * (`docs/adr/0072`). `meta` is also *read* here, so a render is reproducible
+ * from the call that configured it.
+ *
  * @param {XlsxOptions} [options] Host controls (see SCHEMA.md, "The XLSX target").
  * @returns {{name: "xlsx", compile: (stream: any) => (data?: any) => Promise<Uint8Array>}}
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function xlsx(options) {
+  hostOptions(options, ["meta"], "options");
+  let meta = hostMeta(options?.meta, "options.meta");
   /** @type {(stream: any) => (data?: any) => Promise<Uint8Array>} */
   let compile = (stream) => async (data) => {
-    let workbook = create(options?.meta);
+    let workbook = create(meta);
     let worksheet = sheet(workbook);
     // The first table anchors the frozen header row. It is global to the
     // sheet, so later tables never move it.
@@ -197,15 +204,14 @@ export function xlsx(options) {
       image: (event) => {
         let known = images.get(event.bytes);
         if (!known) {
-          let size = pixels(event.bytes, event.format);
-          // The engine vouched for the magic numbers, not for the rest of the
-          // file. A header too short to carry a size leaves nothing to place a
-          // drawing at, and failing beats dropping the picture in silence
-          // (SCHEMA.md, "Image item"). Named on the item through the engine's
-          // own mint, so this failure reads the same from here as it does from
-          // a target that paints or embeds.
-          if (!size) throw imageError(event.path, "could not read the image's size from its bytes");
-          known = { ...size, id: embed(workbook, event.bytes, event.format) };
+          // The event states the size in pixels, which is the unit a floating
+          // drawing is placed in, so this target has nothing to work out: the
+          // engine read the header once for every target (`docs/adr/0067`).
+          known = {
+            width: event.width,
+            height: event.height,
+            id: embed(workbook, event.bytes, event.format),
+          };
           images.set(event.bytes, known);
         }
         if (split) {

package/lib/style.js

@@ -22,6 +22,7 @@ let FAMILY = { sans: "Calibri", serif: "Times New Roman", mono: "Courier New" };
 
 // A declared colour as an ARGB string, or null when the value is not one.
 /** @type {(value: any) => string | null} */
+// fallow-ignore-next-line code-duplication -- each target reads a declared hex into its own type; neither may import a sibling, and the engine's stream is all they share
 let argb = (value) => {
   let match = typeof value === "string" && HEX.exec(value);
   if (!match) return null;

package/lib/workbook.js

@@ -10,12 +10,16 @@
 import ExcelJS from "exceljs";
 
 // Host metadata keys as the workbook properties they become -- `author` is the
-// only one exceljs names differently.
+// only one exceljs names differently, and this mapping is all this target owns
+// of `meta`. The contract itself (which properties, each a string, never a
+// date) is the engine's `hostMeta`, checked at the factory call, so nothing
+// here restates it: a present property is a string, and a nullish one is a
+// property the host did not write.
 /** @type {(workbook: any, meta: any) => void} */
 let describe = (workbook, meta) => {
-  if (typeof meta.title === "string") workbook.title = meta.title;
-  if (typeof meta.author === "string") workbook.creator = meta.author;
-  if (typeof meta.subject === "string") workbook.subject = meta.subject;
+  if (meta.title != null) workbook.title = meta.title;
+  if (meta.author != null) workbook.creator = meta.author;
+  if (meta.subject != null) workbook.subject = meta.subject;
 };
 
 // A fresh workbook. Never the current time: a timestamp would make the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/xlsx",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The spreadsheet render target for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -42,12 +42,12 @@
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
     "@types/node": "^22.20.1",
-    "quario": "^0.7.0",
+    "quario": "^0.9.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.7.0"
+    "quario": "^0.9.0"
   },
   "size-limit": [
     {

package/lib/image.js

@@ -1,45 +0,0 @@
-/**
- * An image's own size, read from its header. A floating drawing is placed in
- * pixels, and the event carries the bytes and the format the engine sniffed
- * but no dimensions, so the one thing this target needs to place a picture is
- * worked out here — from the header alone, never by decoding the image.
- *
- * The PDF target reads the same two headers for its own placement, in points.
- * Restated per target rather than shared, like every other coercion at a
- * target's edge: neither package imports the other, and the engine's stream is
- * all they have in common.
- */
-
-/** @type {(bytes: Uint8Array, at: number) => number} */
-let word = (bytes, at) => (bytes[at] << 8) | bytes[at + 1];
-
-// The dimensions live in the frame header, the first SOFn marker: every
-// code in C0..CF except the three in that range that are not frames --
-// DHT, the JPG extension, and DAC.
-/** @type {Record<number, number>} */
-let SKIP = { 0xc4: 1, 0xc8: 1, 0xcc: 1 };
-/** @type {(code: number) => any} */
-let sof = (code) => code >= 0xc0 && code <= 0xcf && !SKIP[code];
-
-/** @type {(bytes: Uint8Array) => { width: number, height: number }} */
-let jpeg = (bytes) => {
-  for (let at = 2; at + 9 < bytes.length; at += 2 + word(bytes, at + 2)) {
-    if (bytes[at] !== 0xff) break;
-    if (sof(bytes[at + 1])) return { width: word(bytes, at + 7), height: word(bytes, at + 5) };
-  }
-  return { width: 0, height: 0 };
-};
-
-/**
- * The image's size in pixels, or null when the header does not carry one —
- * bytes the engine vouched the magic numbers of, truncated before the size.
- *
- * @param {Uint8Array} bytes The image file.
- * @param {string} format The engine's sniff: `"png"` or `"jpeg"`.
- * @returns {{ width: number, height: number } | null} The size, if readable.
- */
-export let pixels = (bytes, format) => {
-  // A PNG carries the two numbers in its IHDR at a fixed offset.
-  let size = format === "png" ? { width: word(bytes, 18), height: word(bytes, 22) } : jpeg(bytes);
-  return size.width > 0 && size.height > 0 ? size : null;
-};