### Install quario with npm

Source: https://getquario.com/docs

Install the quario package via npm. The command is shown on the landing page as the quick start for evaluating the library.

```bash
$npm install quario
```

--------------------------------

### Install @quario/csv

Source: https://getquario.com/docs/diving-deeper/csv-target

Install the @quario/csv package. The csv() factory takes no options and refuses one rather than discarding it.

```bash
npm install @quario/csv
```

--------------------------------

### Install @quario/xlsx

Source: https://getquario.com/docs/diving-deeper/xlsx-target

Install the @quario/xlsx package to render reports to XLSX files.

```bash
npm install @quario/xlsx
```

--------------------------------

### Install quario engine and render targets

Source: https://getquario.com/docs/getting-started

Install the quario engine and the HTML and PDF render targets. The targets declare the engine as a peer dependency, so you can add another target later without touching existing definitions.

```bash
npm install quario @quario/html @quario/pdf
```

--------------------------------

### Report document with $schema pointing to quario/schema.json

Source: https://getquario.com/docs/diving-deeper/validating

Example report document that references the installed JSON Schema file. The engine only checks the top-level $schema string; anywhere else it is an unknown key.

```json
{
  "$schema": "./node_modules/quario/lib/schema.json",
  "data": "$.invoice.lines[*]",
  "detail": { "columns": [{ "header": "Item", "value": "{{ @.item }}" }] }
}

```

--------------------------------

### Typed and untyped columns side by side

Source: https://getquario.com/docs/diving-deeper/xlsx-target

Example configuration showing a typed column with a currency format and an untyped column that renders as text.

```json
{
  "columns": [
    { "header": { "value": "Amount" }, "value": "{{ @.amount }}",
      "style": { "format": "currency" } },
    { "header": { "value": "Label" }, "value": "Total: {{ @.amount }}" }
  ]
}
```

--------------------------------

### Activate quario with a license key

Source: https://getquario.com/docs/diving-deeper/licensing

Used to activate quario by providing a license key. The `q.license` promise settles with `{ licensed, licensee?, id? }` and never rejects; without a key it settles with `{ licensed: false }`. Verification starts once, and every report compiled by the instance shares the result.

```ts
import { quario } from 'quario'

const q = quario({ license: 'quario_...' })

const { licensed, licensee, id } = await q.license
```

--------------------------------

### Agent tool-call loop with validate_report and render_report

Source: https://getquario.com/docs

Example of the agent tool-call loop: validate_report returns problems, then a revised definition passes validation, and render_report produces a PDF. The output shows the exact error messages and the final file path.

```text
→ validate_report  { definition }
← 2 problems
    sort[0].dir: unknown sort direction "descending"
    detail.columns[1].value [{{ round(@.qty * @.unitPrice }}]: Unexpected end of expression
→ validate_report  { definition }  revised
← {"problems":[],"warnings":[]}
→ render_report  { definition, target: "pdf", dataPath: "invoices/1042.json", filename: "invoice-1042" }
← Wrote invoice-1042.pdf (1.8 kB): /srv/reports/invoice-1042.pdf
```

--------------------------------

### Inline reducer example

Source: https://getquario.com/docs/reference/functions-and-reducers

Shows an inline reducer that folds an array on the row itself, using the sum reducer with a lambda expression.

```json
{ "value": "{{ sum(@.lines, l => l.total) }}" }
```

--------------------------------

### xlsx(options)

Source: https://getquario.com/docs/diving-deeper/xlsx-target

Renders a compiled report to an XLSX workbook, returning a Uint8Array. Accepts options for metadata, print setup, and autofilter. Throws TypeError for unknown or incorrectly typed options.

```APIDOC
## xlsx(options)

### Description
Renders a compiled report to an XLSX workbook, returning a Uint8Array. Accepts options for metadata, print setup, and autofilter. Throws TypeError for unknown or incorrectly typed options.

### Method
Function

### Endpoint
xlsx(options)

### Parameters
#### Options
- **meta** (object) - Required - Metadata for the workbook. Contains `title`, `author`, `subject` (all strings, never a date).
- **page** (object) - Optional - Print setup options.
- **filter** (object) - Optional - Autofilter configuration.

### Request Example
```javascript
import { xlsx } from '@quario/xlsx';
const result = xlsx({
  meta: { title: 'Report', author: 'Author', subject: 'Subject' },
  page: { /* print setup */ },
  filter: { /* autofilter */ }
});
```

### Response
#### Success Response
- **Uint8Array** - The XLSX workbook bytes.

#### Response Example
```javascript
// result is a Uint8Array
```

### Error Handling
- Throws `TypeError` if an option is unknown or of the wrong type, naming the path it came from.
```

--------------------------------

### JSON-LD BreadcrumbList schema

Source: https://getquario.com/docs/getting-started

A JSON-LD structured data snippet for a breadcrumb list, used for SEO. It defines a BreadcrumbList with three items: Home, Docs, and Getting started.

```json
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://getquario.com/"},{"@type":"ListItem","position":2,"name":"Docs","item":"https://getquario.com/docs"},{"@type":"ListItem","position":3,"name":"Getting started","item":"https://getquario.com/docs/getting-started"}]}
```

--------------------------------

### Create a quario instance with locale and currency

Source: https://getquario.com/docs/getting-started

Create a quario instance that holds host configuration such as locale, currency, and timezone. The instance verifies the license key once, offline, and should be built at startup and kept for the service's lifetime.

```ts
import { quario } from 'quario'

const q = quario({ locale: 'en-IE', currency: 'EUR', timeZone: 'UTC' })
```

--------------------------------

### quario(options?)

Source: https://getquario.com/docs/reference/quario

Creates a configured quario instance with host-level options.

```APIDOC
## quario(options?)

### Description
Creates a configured instance of the quario engine. Host-level configuration only.

### Method
function

### Endpoint
quario(options?)

### Parameters
#### Options
- **license** (string) - Optional - License key, verified offline once at creation. The engine marks output when the key ends before this version's release date.
- **locale** (string) - Optional - Locale for `format`. Defaults to `"en-US"`.
- **currency** (string) - Optional - Default ISO 4217 code for `format: "currency"`.
- **timeZone** (string) - Optional - Timezone for `format: "date"`. Defaults to `"UTC"`.
- **query** (QueryOptions) - Optional - Budgets for the JSONPath selection.
- **schemes** (readonly string[]) - Optional - The URL schemes an `href` may use, lower-case and colon-terminated. Defaults to `https:` and `mailto:`. A value the engine can't read throws at construction.

### Returns
- **Quario** - A configured instance.

### Example
```ts
const engine = quario({
  license: 'your-license-key',
  locale: 'en-US',
  currency: 'USD',
  timeZone: 'UTC',
  schemes: ['https:', 'mailto:']
});
```
```

--------------------------------

### q.plan(schema, funcs?)

Source: https://getquario.com/docs/diving-deeper/validating

Compiles a report definition and returns a detailed plan object with report, problems, anchors, warnings, and params. Use this to check a definition before rendering and to inspect anchors and warnings.

```APIDOC
## q.plan(schema, funcs?)

### Description
Compiles a report definition and returns a detailed plan object. Use this to check a definition before rendering and to inspect anchors and warnings.

### Method
Function

### Endpoint
q.plan(schema, funcs?)

### Parameters
#### Parameters
- **schema** (object) - Required - The report definition to compile.
- **funcs** (object) - Optional - Additional functions or configuration.

### Returns
- **report** (object|null) - The compiled report, or null if the document has problems.
- **problems** (array) - List of problems found during compilation.
- **anchors** (object) - Maps each compiled source's schema path to the anchors and handles it reads.
- **warnings** (array) - List of warnings, each with `path` and `message`.
- **params** (array) - List of parameters the document declares.

### Example
```ts
const { report, problems, anchors, warnings, params } = q.plan(definition)
```
```

--------------------------------

### pdf(options?)

Source: https://getquario.com/docs/reference/pdf

Creates a PDF render target. Validates options at the factory call and returns a target that resolves to a Uint8Array containing the PDF bytes.

```APIDOC
## pdf(options?)

### Description
Returns the PDF render target. It validates options at the factory call, and takes three: `page`, `meta` and `fonts`. Any other key, or one of the wrong type, throws a `TypeError` naming the path. The factory copies `meta` as it reads it, so mutating that object afterwards changes nothing the target writes.

### Signature
```ts
function pdf(options?: PdfOptions): Target<'pdf', Promise<Uint8Array>>
```

### Parameters
- **options** (PdfOptions) - Optional - Configuration object with `page`, `meta`, and `fonts` fields.

### Returns
- **Target<'pdf', Promise<Uint8Array>>** - The PDF render target that resolves to the document bytes.

### Errors
- **TypeError** - Thrown if options contain an invalid key or a field of the wrong type.
```

--------------------------------

### QuarioDiagnostic interface

Source: https://getquario.com/docs/reference/quario

An error interface representing a diagnostic raised by a delegated engine, with optional code, start, end, limit, actual, and blocks.

```APIDOC
## QuarioDiagnostic interface

### Description
An error interface representing a diagnostic raised by a delegated engine, with optional code, start, end, limit, actual, and blocks.

### Signature
```ts
interface QuarioDiagnostic extends Error {
  readonly code?: QuarioErrorCode
  readonly start?: number
  readonly end?: number
  readonly limit?: number
  readonly actual?: number
  readonly blocks?: readonly SjabloonBlock[]
}
```

### Properties
- **code** (QuarioErrorCode) - Optional - The error code, absent on option and target-definition faults.
- **start** (number) - Optional - The start position.
- **end** (number) - Optional - The end position.
- **limit** (number) - Optional - The limit on a budget failure.
- **actual** (number) - Optional - The actual value on a budget failure.
- **blocks** (readonly SjabloonBlock[]) - Optional - The blocks involved.
```

--------------------------------

### Render a PDF with page size and margin

Source: https://getquario.com/docs/diving-deeper/pdf-target

Sets up a PDF page with A4 size and a 54-point margin, then renders the report to bytes. The page geometry is validated at the factory call, so a bad option throws before the engine walks any data.

```ts
import { pdf } from '@quario/pdf'

const bytes = await report.render(pdf({ page: { size: 'A4', margin: 54 } }), data)
```

--------------------------------

### quario.license

Source: https://getquario.com/docs/diving-deeper/licensing

Activates the license and returns the license status. Settles with { licensed, licensee?, id? } and never rejects. Without a key it settles { licensed: false }.

```APIDOC
## quario.license

### Description
Activates the license and returns the license status. Settles with { licensed, licensee?, id? } and never rejects. Without a key it settles { licensed: false }.

### Method
Property access (async)

### Endpoint
q.license

### Parameters
None

### Request Example
```ts
import { quario } from 'quario'

const q = quario({ license: 'quario_...' })

const { licensed, licensee, id } = await q.license
```

### Response
#### Success Response (200)
- **licensed** (boolean) - Whether the license is valid.
- **licensee** (string, optional) - The licensee name, if licensed.
- **id** (string, optional) - The license ID, if licensed.

#### Response Example
```json
{
  "licensed": true,
  "licensee": "Acme Corp",
  "id": "quario_..."
}
```
```

--------------------------------

### Pinned header configuration

Source: https://getquario.com/docs/diving-deeper/bands

Defines a report header band with a fixed height and a text item that uses a template expression. Requires page.margin on the document because the pin starts at the physical page edge.

```json
{
  "header": {
    "height": 120,
    "items": [
      { "type": "text", "value": "{{ $.input.company }}", "style": { "size": 14, "bold": true } }
    ]
  }
}
```

--------------------------------

### q.report(schema, funcs?)

Source: https://getquario.com/docs/diving-deeper/validating

Compiles a report definition and throws on the first problem encountered. Use this when you want to fail fast on invalid definitions.

```APIDOC
## q.report(schema, funcs?)

### Description
Compiles a report definition and throws on the first problem encountered. Use this when you want to fail fast on invalid definitions.

### Method
Function

### Endpoint
q.report(schema, funcs?)

### Parameters
#### Parameters
- **schema** (object) - Required - The report definition to compile.
- **funcs** (object) - Optional - Additional functions or configuration.

### Throws
Throws an error on the first problem found during compilation.

### Example
```ts
q.report(definition)
```
```

--------------------------------

### Compile and render a report with q.report

Source: https://getquario.com/docs/getting-started

Compile the report definition once and render it per dataset. The report object is held by the service and reused for each render, avoiding repeated parsing costs.

```ts
import { html } from '@quario/html'

const report = q.report(definition)

const invoice = await getInvoice()
const fragment = await report.render(html(), { invoice })
```

--------------------------------

### Await q.license before streaming a report

Source: https://getquario.com/docs/diving-deeper/licensing

Shows how to explicitly await the license promise before draining `report.stream(data)` directly. This prevents a race where the stream could outrun the license check; `render` already awaits settlement, but direct stream consumers must await `q.license` first.

```ts
await q.license

for (const event of report.stream(data)) {
  if (event.type === 'report-start' && event.marking) console.log(event.marking)
}
```

--------------------------------

### Fetch row data with an async registered function

Source: https://getquario.com/docs/diving-deeper/host-functions

Fetches data the report's own data doesn't carry by registering an `async` function and calling it as the whole value of a detail cell. The engine calls the function once per rendered row, starts all calls together, and waits for all before the first event reaches a target. The call must be the whole cell value and its arguments must come from the row; `render()` settles the calls, while `stream()` cannot.

```json
{ “type”: “text”, “value”: ”{{ customerName(@.customerId) }}” }
```

```ts
const funcs = {
  customerName: async (id: string) => (await getCustomer(id)).name,
}

const report = q.report(definition, funcs)
const output = await report.render(target, data)
```

--------------------------------

### q.report(definition, funcs)

Source: https://getquario.com/docs/diving-deeper/formatting

Creates a report with a definition and registered functions.

```APIDOC
## `q.report(definition, funcs)`

### Description
Creates a report using a definition and a set of registered functions. Registered functions are configuration you trust, the same standing as the definition itself. A function of the same name as a built-in shadows it.

### Parameters
- **definition** (object) - Required - The report definition.
- **funcs** (object) - Required - An object mapping function names to implementations.

### Example
```ts
const funcs = {
  period: (ym: string) => {
    const [year, month] = ym.split('-').map(Number)
    return new Intl.DateTimeFormat('en-GB', { month: 'long', year: 'numeric' })
      .format(new Date(year, month - 1, 1))
  },
}
const report = q.report(definition, funcs)
```
```

--------------------------------

### Import the HTML target stylesheet

Source: https://getquario.com/docs/diving-deeper/html-target

Imports the reference stylesheet for the HTML target. Two rules in this sheet affect fragment behavior: .q-item has min-height: 1lh and white-space: pre-line, and table cells carry pre-line but no min-height. The classes are yours to restyle, overriding on source order like any vendor sheet.

```css
@import '@quario/html/style.css';
```

--------------------------------

### paint(ctx, page, options?)

Source: https://getquario.com/docs/reference/layout

Draws one page to a canvas, filling white over the whole canvas first. The canvas must be sized to the paper before calling, as page ops are in page coordinates.

```APIDOC
## paint(ctx, page, options?)

### Description
Draws one page to a canvas, filling white over the whole canvas first. The canvas must be sized to the paper before calling, as page ops are in page coordinates.

### Method
paint

### Signature
```ts
function paint(
  ctx: CanvasRenderingContext2D,
  page: Page,
  options?: { scale?: number; fonts?: LayoutFonts },
): Promise<void>
```

### Parameters
- **ctx** (CanvasRenderingContext2D) - Required - The canvas rendering context to draw on.
- **page** (Page) - Required - The page to draw.
- **options** (object) - Optional - Options for painting.
  - **scale** (number) - Optional - Scale factor for drawing.
  - **fonts** (LayoutFonts) - Optional - Fonts to use for text rendering.

### Example
```ts
import { layout, paint } from '@quario/layout'

const list = await report.render(layout({ page: { size: 'A4' } }), data)

canvas.width = list.width * 2        // the paper's, never a page's
canvas.height = list.height * 2
await paint(ctx, list.pages[0], { scale: 2 })
```

### Returns
Promise<void> - Resolves when painting is complete.
```

--------------------------------

### Admit URL schemes with quario({ schemes })

Source: https://getquario.com/docs/diving-deeper/security

Configures the URL scheme allowlist for a render. Defaults to https: and mailto:; each entry is lower-case and ends in a colon. Refused URLs drop out (text renders, link doesn't), and an unreadable schemes value throws at construction rather than falling back to the default.

```ts
import { quario } from 'quario'

const q = quario({ locale: 'en-IE', schemes: ['https:'] })
```

--------------------------------

### Configure quario MCP server in Claude Desktop

Source: https://getquario.com/docs/diving-deeper/mcp

Add this configuration to your claude_desktop_config.json file to enable the quario MCP server in Claude Desktop.

```json
{
  "mcpServers": {
    "quario": {
      "command": "npx",
      "args": ["-y", "@quario/mcp"],
      "env": { "QUARIO_LICENSE": "quario_..." }
    }
  }
}
```

--------------------------------

### html(options?)

Source: https://getquario.com/docs/reference/html

The html() factory function that creates the HTML render target.

```APIDOC
## `html(options?)`

### Description
Returns the HTML render target. `report.render(html(), data)` resolves the fragment.

### Method
Function call

### Endpoint
`html(options?)`

### Parameters
#### Options
- **fonts** (Record<string, string>) - Optional - A declared `family` name mapped to a CSS `font-family` value. Names match case-insensitively, and a mapping may cover the generics `sans` / `serif` / `mono` like any other.
- **paths** (boolean) - Optional - Emit `data-q-path` on each element whose event carries a schema `path`. Off by default.

### Return Value
`Target<'html', Promise<string>>`

### Errors
- Throws a `TypeError` if any option key is not `fonts` or `paths`, or if a value is of the wrong type.
- Throws from `html()` if a `fonts` value contains `;` or `}`.
- Throws if `fonts` is an array instead of a record.
- Throws if `paths` is not `true` or `false`.
```

--------------------------------

### Mark your own target with report-start.marking

Source: https://getquario.com/docs/diving-deeper/licensing

For custom targets that need to mark output when unlicensed. Reads `report-start.marking` and draws it; do not restate the wording or derive it from the document.

```ts
import { walk } from 'quario'

await walk(report.stream(data), {
  'report-start': (e) => {
    if (e.marking) console.log(e.marking)
  },
})
```

--------------------------------

### xlsx(options?)

Source: https://getquario.com/docs/reference/xlsx

The xlsx() factory function that creates the spreadsheet render target.

```APIDOC
## `xlsx(options?)`

### Description
Returns the spreadsheet render target. It takes three options, `meta`, `page` and `filter`. Any other key, or one of the wrong type, throws a `TypeError` naming the path. The factory reads `meta` once and copies it, so mutating that object between renders no longer changes the workbook.

### Signature
```ts
function xlsx(options?: XlsxOptions): Target<'xlsx', Promise<Uint8Array>>
```

### Parameters
#### Options
- **`meta`** (`XlsxMeta`) - Optional document information.
- **`page`** (`XlsxPage`) - Print setup, written to every worksheet.
- **`filter`** (`boolean`) - Put an autofilter over a worksheet’s one table. Off unless asked.

### Returns
- **`Target<'xlsx', Promise<Uint8Array>>`** - The target that resolves workbook bytes with typed cells.

### Errors
- Throws a `TypeError` if any option key is not one of `meta`, `page`, `filter`, or if the value is of the wrong type.
```

--------------------------------

### Painting a page to canvas

Source: https://getquario.com/docs/reference/layout

Shows how to render a page to a canvas, sizing the canvas to the paper dimensions and scaling by 2. The canvas must be sized to the paper, not the page, or content will be clipped.

```typescript
import { layout, paint } from '@quario/layout'

const list = await report.render(layout({ page: { size: 'A4' } }), data)

canvas.width = list.width * 2        // the paper's, never a page's
canvas.height = list.height * 2
await paint(ctx, list.pages[0], { scale: 2 })
```

--------------------------------

### Check definition with q.plan

Source: https://getquario.com/docs/getting-started

Use `q.plan(definition)` to compile a definition without rendering. It returns `report`, `problems`, and `warnings`. Problems are errors that prevent compilation; warnings are non-blocking. The snippet logs each problem and warning, and sets the process exit code to 1 if the report is null.

```ts
const { report, problems, warnings } = q.plan(definition)

for (const problem of problems) console.error(`${problem.path}: ${problem.message}`)
for (const warning of warnings) console.warn(`${warning.path}: ${warning.message}`)

if (!report) process.exitCode = 1
```

--------------------------------

### Quario.plan(schema, functions?, options?)

Source: https://getquario.com/docs/reference/quario

Plans a schema traversal, optionally validating required declarations against target capabilities.

```APIDOC
## Quario.plan(schema, functions?, options?)

### Description
Returns everything one traversal produced. Can validate required declarations against target capabilities.

### Method
function

### Endpoint
plan(schema: unknown, functions?: FunctionRegistry, options?: PlanOptions): Plan

### Parameters
- **schema** (unknown) - Required - The schema to plan.
- **functions** (FunctionRegistry) - Optional - A registry of custom functions.
- **options** (PlanOptions) - Optional - Planning options.
  - **targets** (readonly TargetCapabilities[]) - Optional - Capability descriptors from published targets. Every declaration the document marks `required` that one of them withdraws or leaves unread becomes a problem at `required.<name>`. An approximated declaration isn't one, and passing no descriptors checks nothing.

### Returns
- **Plan** - The result of the traversal.

### Example
```ts
const plan = engine.plan(schema, undefined, { targets: [{ target: 'pdf', declarations: { 'required': 'true' } }] });
```
```

--------------------------------

### docx()

Source: https://getquario.com/docs/reference/docx

The docx() factory function for creating a Word render target.

```APIDOC
## `docx()`

### Description
Creates a Word render target that resolves the bytes of a `.docx` file as a `Uint8Array`. It accepts optional `page` and `meta` options to control page size, margins, and document metadata.

### Signature
```ts
function docx(options?: DocxOptions): Target<'docx', Promise<Uint8Array>>
```

### Parameters
#### Options
- **page** (object) - Optional - Page configuration. `size` can be `'A4'`, `'letter'`, or a `[width, height]` array in points (default `'A4'`). `margin` can be a number (points on all sides) or an object with `top`, `right`, `bottom`, `left` (default 54 when document declares none).
- **meta** (object) - Optional - Document metadata. `title`, `author`, `subject` are strings only. The object is copied, so later mutations have no effect.

### Errors
- Throws a `TypeError` if any option key is unknown or of the wrong type, naming the path.
- A render error occurs if a document declares a key and the host declares the same one.

### Returns
- `Target<'docx', Promise<Uint8Array>>` - A target that resolves to the `.docx` bytes.
```

--------------------------------

### Registering the element

Source: https://getquario.com/docs/reference/viewer

How to register the quario-viewer custom element.

```APIDOC
## Registering the element

```ts
import '@quario/viewer/register';
```

or

```ts
import { QuarioViewer } from '@quario/viewer';
// define it yourself
```
```

--------------------------------

### hostOptions(value, keys, at) and hostMeta(value, at)

Source: https://getquario.com/docs/reference/quario

Functions to validate option objects for custom targets, ensuring only allowed keys and the shared metadata contract.

```APIDOC
## `hostOptions(value, keys, at)` and `hostMeta(value, at)`

### Description
Validates option objects for custom targets. `hostOptions` throws a `TypeError` prefixed with `at` when the value carries a key outside `keys`. `hostMeta` validates the `{ title, author, subject }` contract shared by document targets, each a string and nothing else. Both return the value passed in.

### Signature
```ts
interface QuarioMeta {
  title?: string
  author?: string
  subject?: string
}

function hostOptions<T>(value: T, keys: readonly string[], at: string): T
function hostMeta<T extends QuarioMeta | null | undefined>(value: T, at: string): T
```

### Parameters
- `value` (T) - Required - The object to validate.
- `keys` (readonly string[]) - Required (for `hostOptions`) - The allowed key set.
- `at` (string) - Required - Prefix for error messages.

### Returns
- The original `value` unchanged.

### Errors
- `TypeError` - Thrown when `value` has a key outside `keys` (for `hostOptions`) or when `value` does not conform to the `QuarioMeta` contract (for `hostMeta`).
```

--------------------------------

### Read problems and warnings from a plan

Source: https://getquario.com/docs/diving-deeper/validating

Iterates over problems and warnings from q.plan, logging their paths and messages. Optionally logs the source for problems that have one. Sets exit code 1 if no report is produced.

```typescript
const { report, problems, warnings } = q.plan(definition, {})

for (const problem of problems) {
  console.error(`${problem.path}: ${problem.message}`)
  if (problem.source) console.error(`  in ${problem.source}`)
}
for (const warning of warnings) console.warn(`${warning.path}: ${warning.message}`)

if (!report) process.exitCode = 1
```

--------------------------------

### Enable schema paths with html({ paths: true })

Source: https://getquario.com/docs/diving-deeper/html-target

Enables data-q-path attributes on elements whose event carries a schema path. This is off by default and is the selection seam the editor builds on.

```ts
import { html } from '@quario/html'

const target = html({ paths: true })
```

--------------------------------

### Add quario MCP server to Claude Code

Source: https://getquario.com/docs/diving-deeper/mcp

Use this command to register the quario MCP server in Claude Code, providing the required license key via environment variables.

```bash
claude mcp add quario -e QUARIO_LICENSE=quario_... -- npx -y @quario/mcp
```

--------------------------------

### report.ts instance configuration

Source: https://getquario.com/docs/diving-deeper/formatting

Configures the Quario instance with specific locale, currency, and time zone settings.

```ts
import { quario } from 'quario'

const q = quario({ locale: 'en-IE', currency: 'EUR', timeZone: 'Europe/Dublin' })
```

--------------------------------

### Target.compile

Source: https://getquario.com/docs/reference/quario

Compiles a renderer for the target. Called once per render call, so it must be cheap and stateless.

```APIDOC
## [FUNCTION] Target.compile

### Description
Compiles a renderer for the target. Called once per render call, so it must be cheap and stateless.

### Method
FUNCTION

### Endpoint
Target.compile

### Parameters
#### Request Body
- **stream** (ReportEventStream) - Required - The event stream to compile against.

### Response
#### Success Response (200)
- **(data?: unknown) => Out** - The renderer function.

#### Response Example
```typescript
(stream: ReportEventStream) => (data?: unknown) => Out
```
```

--------------------------------

### layout(options?)

Source: https://getquario.com/docs/reference/layout

A render target that resolves the display list instead of bytes. Accepts optional LayoutOptions to configure page and fonts.

```APIDOC
## `layout(options?)`

### Description
A render target like any other, resolving the display list instead of bytes.

### Signature
```ts
function layout(options?: LayoutOptions): Target<'layout', Promise<Layout>>
```

### Parameters
#### Options
- **options** (LayoutOptions) - Optional - Configuration for the layout target.

### Returns
- **Target<'layout', Promise<Layout>>** - A render target that resolves to a Layout display list.

### Example
```ts
const layoutTarget = layout({ page: { size: 'A4', margin: 20 }, fonts: fontRecord });
```
```

--------------------------------

### loadFontkit()

Source: https://getquario.com/docs/reference/layout

Loads the optional font parser once and hands the same module to every caller, which is how @quario/pdf embeds with the parser this package measured with.

```APIDOC
## loadFontkit()

### Description
Loads the optional font parser once and hands the same module to every caller, which is how @quario/pdf embeds with the parser this package measured with.

### Method
loadFontkit

### Signature
```ts
function loadFontkit(): Promise<unknown>
```

### Returns
Promise<unknown> - The loaded font parser module.
```

--------------------------------

### pdf({ page, meta, fonts })

Source: https://getquario.com/docs/diving-deeper/pdf-target

Creates a PDF target configuration. Validates the provided options, throwing a TypeError for invalid keys or types. Accepts page geometry, metadata, and font mappings.

```APIDOC
## pdf({ page, meta, fonts })

### Description
Creates a PDF target configuration. Validates the provided options, throwing a TypeError for invalid keys or types. Accepts page geometry, metadata, and font mappings.

### Method
Factory function

### Parameters
#### Options Object
- **page** (object) - Required - Page geometry configuration.
- **meta** (object) - Optional - Document metadata.
- **fonts** (object) - Optional - Font family mappings.

### Request Example
```ts
import { pdf } from '@quario/pdf'

const bytes = await report.render(pdf({ page: { size: 'A4', margin: 54 } }), data)
```

### Response
Returns a PDF target configuration object.

### Errors
- **TypeError** - Thrown when an invalid key or type is provided.
```

--------------------------------

### capabilities

Source: https://getquario.com/docs/reference/pdf

Provides the target's capabilities for each declaration in the support matrix, keyed by schema name. Use with plan(schema, functions, { targets }) to check a document's required marking before rendering.

```APIDOC
## capabilities

### Description
What this target makes of each declaration the support matrix names, keyed by the schema name an author writes. Hand it to `plan(schema, functions, { targets })` to check a document’s `required` marking before you render. It carries no version of its own. The package that ships it sets the version.

### Signature
```ts
const capabilities: {
  readonly target: 'pdf'
  readonly declarations: Readonly<Record<string, Fate>>
}

type Fate = 'resolved' | 'approximated' | 'withdrawn' | 'unread'
```
```

--------------------------------

### walk(events, handlers)

Source: https://getquario.com/docs/reference/quario

Dispatches events to handlers in stream order.

```APIDOC
## `walk(events, handlers)`

### Description
Dispatches one render's events to per-event handlers in stream order and once each, pulling lazily and handing the loop back between batches. Handlers are synchronous, and a promise one returns isn't awaited.

### Signature
```ts
function walk(events: Iterable<ReportEvent>, handlers: WalkHandlers): Promise<void>
```

### Parameters
- **events** (Iterable<ReportEvent>) - Required - The iterable of report events to process.
- **handlers** (WalkHandlers) - Required - An object mapping event types to synchronous handler functions.

### Returns
- **Promise<void>** - Resolves when all events have been dispatched.
```

--------------------------------

### render.ts — render report to PDF with pdf()

Source: https://getquario.com/docs/getting-started

Renders the same compiled report to PDF using the @quario/pdf factory. The call differs only in the factory handed to render; the definition and data stay unchanged. The PDF target writes the document without a browser, typesetting pages itself and writing the file directly. The render resolves a Uint8Array that is deterministic for one definition and one dataset.

```ts
import { pdf } from '@quario/pdf'

const bytes = await report.render(
  pdf({ page: { size: 'A4', margin: 54 }, meta: { title: 'Invoice INV-2043' } }),
  { invoice }
)
```

--------------------------------

### report.stream(data) - Await license before streaming

Source: https://getquario.com/docs/diving-deeper/licensing

When consuming report.stream(data) directly, await the license promise first to avoid racing the license check. The stream emits events including 'report-start' with a marking property when unlicensed.

```APIDOC
## report.stream(data)

### Description
Streams report events. When consuming directly, await the license promise first to avoid racing the license check. The stream emits events including 'report-start' with a marking property when unlicensed.

### Method
Stream (async iterable)

### Endpoint
report.stream(data)

### Parameters
- **data** (any) - The data to render.

### Request Example
```ts
await q.license

for (const event of report.stream(data)) {
  if (event.type === 'report-start' && event.marking) console.log(event.marking)
}
```

### Response
#### Success Response (200)
- **event.type** (string) - The event type, e.g., 'report-start'.
- **event.marking** (string, optional) - The marking wording, present only when unlicensed.

#### Response Example
```json
{
  "type": "report-start",
  "marking": "Unlicensed"
}
```
```

--------------------------------

### Use quario/schema.json as a tool input schema

Source: https://getquario.com/docs/diving-deeper/validating

Use this to feed the JSON Schema to a model tool. The schema works with Gemini and ordinary editors, but not with OpenAI or Anthropic strict structured-output modes.

```ts
import schema from 'quario/schema.json' with { type: 'json' }

const tool = { name: 'draft_report', input_schema: schema }

// What the model sends back is still untrusted.
const { report, problems } = q.plan(definition)

```

--------------------------------

### Declare parameters with params

Source: https://getquario.com/docs/diving-deeper/supplying-data

Declares parameters on the document. A bare value is a constant; a plain object is a declaration. A declaration without a default makes the parameter required.

```json
{
  "data": "$.orders[*]",
  "params": {
    "threshold": 1000,
    "region": { "type": "string", "label": "Region" }
  }
}
```

--------------------------------

### renderComplete

Source: https://getquario.com/docs/diving-deeper/editor

Resolves once the pages within reach have painted. Use it before reading pixels from a page.

```APIDOC
## [METHOD] renderComplete

### Description
Resolves once the pages within reach have painted. Use it before reading pixels from a page.

### Method
METHOD

### Endpoint
quario-editor element

### Parameters
None.

### Response
#### Success Response
A promise that resolves when rendering is complete.
```

--------------------------------

### boxes(path)

Source: https://getquario.com/docs/diving-deeper/editor

Returns every rectangle the render drew for a schema node, in document order, as client rectangles. Use it to anchor custom UI to a node.

```APIDOC
## [METHOD] boxes(path)

### Description
Returns every rectangle the render drew for a schema node, in document order, as client rectangles. Use it to anchor custom UI to a node.

### Method
METHOD

### Endpoint
quario-editor element

### Parameters
#### Path Parameters
- **path** (string) - Required - The schema node path.

### Response
#### Success Response
An array of client rectangles for the node. Returns an empty array for nodes that draw nothing, groups, or invalid paths.
```

--------------------------------

### walk(events, handlers)

Source: https://getquario.com/docs/diving-deeper/custom-target

Dispatches one render's events to per-event handlers in stream order and exactly once each. Pulls lazily and hands the event loop back between batches.

```APIDOC
## walk(events, handlers)

### Description
Dispatches one render's events to per-event handlers in stream order and exactly once each. It pulls lazily and hands the event loop back between batches, so a long report doesn't block the host. Handlers are synchronous; a promise one returns isn't awaited, so accumulate into a closure and resolve after the walk. The stream's first event reaches its handler before anything pulls a second.

### Signature
```ts
walk(events, handlers)
```

### Parameters
- **events** - The event stream to walk.
- **handlers** - Object mapping event types to synchronous handler functions.
```

--------------------------------

### LayoutOptions

Source: https://getquario.com/docs/reference/layout

Options for the layout() function, including page configuration and font families.

```APIDOC
## `LayoutOptions`

### Description
Options for the layout() function, including page configuration and font families.

### Interface
```ts
interface LayoutOptions {
  page?: LayoutPage
  fonts?: LayoutFonts
}

interface LayoutPage {
  size?: 'A4' | 'letter' | [number, number]
  margin?: number | { top: number; right: number; bottom: number; left: number }
}

interface LayoutFontFamily {
  regular: Uint8Array | ArrayBuffer
  bold?: Uint8Array | ArrayBuffer
  italic?: Uint8Array | ArrayBuffer
  boldItalic?: Uint8Array | ArrayBuffer
}

type LayoutFonts = Record<string, LayoutFontFamily>
```

### Fields
- **page** (LayoutPage) - Optional - Page size and margin configuration.
- **fonts** (LayoutFonts) - Optional - Record of font family names to font files.

### LayoutPage Fields
- **size** ('A4' | 'letter' | [number, number]) - Optional - Page size.
- **margin** (number | { top: number; right: number; bottom: number; left: number }) - Optional - Page margins.

### LayoutFontFamily Fields
- **regular** (Uint8Array | ArrayBuffer) - Required - Regular font file.
- **bold** (Uint8Array | ArrayBuffer) - Optional - Bold font file.
- **italic** (Uint8Array | ArrayBuffer) - Optional - Italic font file.
- **boldItalic** (Uint8Array | ArrayBuffer) - Optional - Bold italic font file.

### Notes
- Pass the same `fonts` record here and to `pdf({ fonts })` so a preview and the document break their lines in the same places.
- Hold the record and its buffers across renders, since they’re the identity the layout remembers a face by.
- Any other key, or one of the wrong type, throws a `TypeError` naming the path.
- An array in place of the `fonts` record throws too, rather than reading as families named `0`, `1` and `2`.
```

--------------------------------

### splits(events)

Source: https://getquario.com/docs/diving-deeper/custom-target

Folds a split bracket into one event before the walk sees it. Read walk(splits(events), handlers) and register a split handler.

```APIDOC
## splits(events)

### Description
Folds a split bracket into one event before the walk sees it. Read `walk(splits(events), handlers)` and register a `split` handler, which receives the opening event's `role`, `path`, `slots` and `style` plus the slot events in order under `items`. Every other event passes through unchanged, and lazily. The stream itself doesn't change. A consumer that doesn't reach for `splits` still gets `split-start`, the slots, and `split-end`.

### Signature
```ts
splits(events)
```

### Parameters
- **events** - The event stream to transform.

### Returns
A transformed stream where split brackets are folded into a single event.
```

--------------------------------

### Render DOCX bytes with quario and @quario/docx

Source: https://getquario.com/docs/diving-deeper/docx-target

Creates a Quario report with locale 'en-IE' and currency 'EUR', then renders it to DOCX bytes using the docx target with an A4 page and title 'Sales 2026'. The page option is validated identically to the PDF target; size defaults to 'A4' and margin defaults to 54 points when not declared.

```ts
import { quario } from 'quario'
import { docx } from '@quario/docx'

const report = quario({ locale: 'en-IE', currency: 'EUR' }).report(definition)

const bytes = await report.render(
  docx({ page: { size: 'A4' }, meta: { title: 'Sales 2026' } }),
  data,
)
```

--------------------------------

### meta.title, meta.author, meta.subject

Source: https://getquario.com/docs/diving-deeper/pdf-target

Write an optional /Info dictionary. They are strings only, never dates, which keeps the output reproducible.

```APIDOC
## meta.title, meta.author, meta.subject

### Description
Write an optional /Info dictionary. They are strings only, never dates, which keeps the output reproducible.

### Type
string

### Usage
- **meta.title** - Document title.
- **meta.author** - Document author.
- **meta.subject** - Document subject.
```

--------------------------------

### Mount Quario editor element

Source: https://getquario.com/docs/diving-deeper/editor

Imports the editor registration and creates a quario-editor element, setting its properties including schema, instance, functions, data, and page. The instance is a quario() instance, functions is the registry the definition may call, and data is sample data for preview that never leaves the browser.

```TypeScript
import '@quario/editor/register'
import type { EditorPage } from '@quario/editor'

const el = document.createElement('quario-editor')

const page: EditorPage = { size: 'A4', margin: 54 }

el.schema = definition
el.instance = q
el.functions = {}
el.data = data
el.page = page

document.body.append(el)
```

--------------------------------

### floor(x, n?)

Source: https://getquario.com/docs/diving-deeper/formatting

Rounds a number down towards negative infinity.

```APIDOC
## `floor(x, n?)`

### Description
Rounds a number down towards negative infinity to `n` decimal places. `n` defaults to 0.

### Parameters
- **x** (number) - Required - The number to floor.
- **n** (number) - Optional - Number of decimal places (default 0). Must be between 0 and 100.

### Errors
- An `n` outside 0 to 100, or not a number, is an error naming the cell and the call.
- Non-finite `x` passes through untouched.

### Example
```
floor(2.675, 2) // 2.67
```
```

--------------------------------

### Lay out cells across the width with a grid (JSON)

Source: https://getquario.com/docs/diving-deeper/images-and-splits

Use this JSON object as a grid to lay out multiple rows of text cells across the content width. Columns define width shares and styles, rows define slots with optional styles. A row may name fewer slots than columns, leaving the rest empty. Grids cannot nest and cannot appear in table or total cells.

```json
{
  "type": "grid",
  "columns": [{ "width": 70 }, { "width": 30, "style": { "align": "right", "format": "currency" } }],
  "rows": [
    { "slots": [{ "type": "text", "value": "Opening" }, { "type": "text", "value": "{{ $.input.opening }}" }] },
    {},
    { "style": { "bold": true },
      "slots": [{ "type": "text", "value": "Closing" }, { "type": "text", "value": "{{ $.input.closing }}" }] }
  ]
}
```