quario 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # quario
 
+## 0.14.0
+
+### Minor Changes
+
+- **`quario(options)` now refuses an option it does not understand, like every target factory.** Before, the engine read the keys it knew and ignored the rest. A typo such as `quario({ licence })` therefore marked every render as unlicensed, and nothing said why. Now an unknown key, a value of the wrong type, or an `options` that is not an object throws a `TypeError` at the call. The message names the option path, such as `options.license`.
+
+  **`locale`, `timeZone` and `currency` are now checked at the call.** Before, a value that `Intl` refused did not fail. Every formatted cell showed its raw value instead. Now `quario({ locale: "en_US" })` and `quario({ timeZone: "Europe/Amsterdm" })` throw a `TypeError`. `currency` must be three upper-case letters, the same rule that a cell's own `currency` declaration follows. A cell's own `currency` still fails soft.
+
+  **The `query` budgets are now checked at the call.** Before, the engine checked them only when a report compiled its first query. A report with no query never reported a bad budget. The error still comes from padvinder, in its own words.
+
+  **`plan(schema, functions, options)` now refuses an unknown key in `options`.** Before, `{ target: [...] }` checked nothing and said nothing. A `targets` that is not an array also throws a `TypeError`.
+
+  **A bad `schemes` allowlist now throws a `TypeError`, not an `Error`.** The message starts with `options.schemes:`, not `schemes:`. A `null` allowlist still throws.
+
+  **What this changes for you.** An options object that carries keys for another consumer stops working when you pass it to `quario()`. Pass `quario()` only the six keys it takes: `query`, `license`, `locale`, `currency`, `timeZone` and `schemes`.
+
+- **A group can now order and cut its instances.** Declare `instances` beside `sort`, with an optional `sort` and an optional `take` inside it. They order and cut the group's instances, as the group's own `sort` and `take` order and cut the rows inside each instance. Each `instances.sort` key reads the group's own handle once per instance, so `instances: { sort: [{ by: "=region.subtotal", dir: "desc" }], take: 5 }` keeps the five regions with the largest subtotals, largest first. `@` and `run` are unbound there. A dropped instance never renders, and no running value steps over it. The totals around the group still count it, as they count a row that a group's `take` drops. A group without `instances` renders every instance in first-seen order, so existing reports render as before.
+- **An image item now accepts SVG bytes.** Before, `source` had to yield PNG or JPEG bytes, and SVG bytes were a render error. Now the engine also names UTF-8 text whose root element is `<svg` as an SVG, and the image event carries `format: "svg"`. The engine reads the size from the root's `width` and `height` when both are absolute lengths, and else from its `viewBox`. An SVG that states no size this way is the same render error as a PNG that is too short to state its size. The message for bytes that are not an image now says "PNG, JPEG or SVG".
+
+  The HTML target puts an SVG in an `<img>` under `data:image/svg+xml`, so the SVG never becomes markup in the fragment. The PDF target draws an SVG as vector paths. It draws no picture that the SVG names, and it fetches nothing. SVG `<text>` draws in the standard Helvetica. The viewer paints an SVG through a `data:` URI, so a page that shows one needs the Content Security Policy grant `img-src data:`. A PNG or a JPEG still needs no grant there. The XLSX and DOCX targets cannot draw an SVG, so an SVG image is a render error that names the item.
+
+### Patch Changes
+
+- **The package now carries edition 1.1 of the Quario License Agreement.** A license now covers one production deployment, not one developer. Each deployment needs one license key. Development, staging, CI and test environments need no key. A key covers every release dated up to one year after you buy it, and those releases stay licensed for good. A key is not a subscription, and it never renews automatically. A refunded or reversed payment voids the keys it bought. Software that your customers install or resell needs separate OEM terms.
+
 ## 0.13.0
 
 ### Minor Changes

package/LICENSE

@@ -1,179 +1,200 @@
 # Quario License Agreement
 
 > **In short:** Quario is commercial software with visible source.
-> Evaluate it free for as long as you like. Evaluation output is
-> watermarked. Anything else needs a per-developer license, after
-> which deployment is unlimited and royalty-free. This summary is not
-> the license; the full terms below govern.
+> You may evaluate it and develop with it free, for as long as you
+> like. The Software marks output that no license key covers. Each
+> production deployment needs one license key. A key covers one year
+> of releases, and those releases stay licensed for good. This summary
+> is not the license. The full terms below govern.
 
-Version 1.0, August 2026
+Version 1.1, October 2026
 
 This agreement is between you and Webstronauts, trading as Quario,
-established in the Netherlands ("we", "us"), and governs the Software
+established in the Netherlands ("we", "us"). It governs the Software
 defined below.
 
 Quario is commercial software. Its packages ship with readable source
-code, but it is not open source. No rights are granted beyond those in
-this agreement.
+code, but it is not open source. This agreement grants no rights
+beyond those it states.
 
 ## 1. Definitions
 
 - The **Software** is any software we publish under the Quario name,
   including the `quario` and `@quario/*` packages, except where a
   product states its own terms. Each release states the edition of this
-  agreement that governs it.
-- **You** means the individual exercising rights under this agreement
-  and, where that individual acts for a company or other organization,
-  that organization. In that case the organization is the licensee, and
-  the rights and limits in this agreement apply to it as a whole.
+  agreement that governs it. A license key bought under this edition
+  licenses every release it covers under this edition, including
+  releases that shipped with an earlier edition.
+- **You** means the individual who exercises rights under this
+  agreement. Where that individual acts for a company or other
+  organization, **you** also means that organization. In that case the
+  organization is the licensee, and the rights and limits in this
+  agreement apply to it as a whole.
 - An **Application** is software you create that incorporates the
-  Software and adds substantial functionality beyond it. A
-  licensee-operated service that embeds the Software and renders
-  reports for your End Users is an Application under this agreement,
-  even if it does little more than render.
-- A **Developer** is any individual (employee or contractor working on
-  your behalf) who writes or maintains code that uses the Software's
-  APIs, or who creates or maintains report definitions for use with the
-  Software. That includes people who never install or run the Software
-  themselves, when their definitions are rendered by a service that
-  embeds it.
-- A **Seat** is a paid license for one named Developer, purchased from
-  us or an authorized reseller.
+  Software and adds substantial functionality beyond it. A service you
+  operate that embeds the Software and renders reports for your End
+  Users is an Application, even if it does little more than render.
+- A **Deployment** is one production service, application, bot, worker
+  or MCP server that runs the Software under your control. All replicas
+  of it together are one Deployment. A service that only passes render
+  requests to another service does not run the Software, so it is not
+  a Deployment. A service that a host or contractor operates on your
+  behalf stays under your control. Development, staging, CI and test
+  environments are not Deployments. We never count the people, agents
+  or renders that a Deployment serves.
+- A **License Key** is the signed key that evidences the license of
+  one Deployment. You buy it from us or from an authorized reseller.
 - **End Users** are people who interact with the Software only through
-  an Application: running it, viewing the reports it produces, or
-  supplying parameters or other input to existing report definitions
-  the Application provides. Creating or maintaining report definitions
-  makes someone a Developer. End Users do not purchase a license; their
-  rights come from section 5.
+  an Application that runs in a Deployment. They run it, view the
+  reports it produces, or supply parameters, input or report
+  definitions to it. End Users do not buy a license. Their rights come
+  from section 5.
 
 ## 2. Acceptance
 
-This file is our standing offer. Anyone who exercises the evaluation
-rights in section 3 accepts them, subject to their conditions. All
-other rights arise when Seats are purchased. Where a purchase is made
-for an organization, the person completing it confirms that they are
-authorized to accept this agreement on the organization's behalf, and
-acceptance covers the whole organization. If you do not accept this
+This file is our standing offer. Anyone who exercises the rights in
+section 3 accepts them, subject to their conditions. All other rights
+start when you buy a License Key. Where a person buys for an
+organization, that person states that they have the authority to
+accept this agreement on the organization's behalf. The acceptance
+then covers the whole organization. If you do not accept this
 agreement, do not use the Software.
 
-## 3. Evaluation
-
-You may download, install, and use the Software free of charge to
-evaluate it: assessing whether it suits your purposes, and building
-prototypes or proofs of concept. Evaluation covers the full feature
-set, needs no key, and has no fixed time limit. The Software marks
-evaluation output as described in section 6.
-
-Evaluation is limited to assessment: you may not distribute any
-Application containing the Software, use the Software in live business
-operations, or expose it in services offered to third parties. The
-moment your use goes beyond evaluating the Software, it requires Seats
-under section 4.
-
-## 4. Developer licenses
-
-Any use of the Software beyond section 3 requires a Seat for every
-Developer, whether or not an Application has shipped. With those Seats
-in place:
-
-- Each licensed Developer may install and use the Software on any number
-  of machines for developing Applications.
-- Automated build, test, and CI systems do not consume Seats.
-- Seats are per named individual. They may be reassigned when a
-  Developer stops working with the Software, but not shared or pooled
-  between concurrently active Developers. Contractors' work for you is
-  covered by your Seats; work they do for other clients is not.
-
-## 5. Distribution and runtime
-
-With Seats under section 4 in place, you may deploy and operate your
-Applications yourself, and distribute the Software as an embedded part
-of them, **royalty-free**: no additional fees or per-deployment
-licenses are required for any number of servers, copies, or End Users.
-You may embed your license key in an Application and ship it at no
-charge, so section 6 does not mark that Application's output.
-
-For that purpose, we grant you the right to pass through to each End
-User, and to anyone who distributes or operates your Application on your
-behalf, a limited, non-exclusive, non-transferable right to execute the
-Software only as embedded in the Application. You must not permit them
-to extract the Software from the Application or use it to develop
-software of their own.
-
-If you operate a service that embeds the Software and renders reports
-for your End Users, that service is an Application under section 1. You
-may run it royalty-free under this section, and you may put your license
-key in it as in any Application. Calling applications that only request
-renders from it need not incorporate the Software. People who use those
-applications only as End Users under section 1 get the pass-through
-rights above.
+## 3. Evaluation and development
 
-You may not:
+You may download, install and use the Software free of charge in any
+environment that is not a Deployment. That includes evaluation,
+prototypes, proofs of concept, and the development, staging, CI and
+test environments of an Application. This right covers the full
+feature set, needs no key, and has no time limit. The Software marks
+output that no License Key covers, as section 6 describes.
 
-- distribute the Software on its own, or as part of a product whose
-  primary purpose is to provide report-engine, report-design, or
-  document-generation capability to third-party developers;
-- expose the Software's APIs to third parties as a development tool or
-  service that substitutes for those parties buying their own Seats. A
-  licensee-operated service that embeds the Software and renders for
-  your own End Users falls outside that ban;
-- fork, mirror, repackage, rename, or wrap the Software, or republish
-  it on any package registry or code-hosting platform, other than as
-  embedded in an Application.
+This right does not let you use the Software in live business
+operations, or expose it in services that third parties use. Each
+Deployment needs a License Key under section 4.
+
+## 4. Deployment licenses
 
-For as long as this agreement is in force, you may not create any tool,
-library, product, or service that competes with the Software or any
-other Quario product, whether the competition is direct or indirect;
-this restriction does not survive termination. You may not remove or
-alter copyright or license notices in the Software. If your Application
-is itself a closed development product for third-party developers (OEM
-redistribution), contact us for separate terms.
+Each Deployment needs its own License Key, from the first day it runs
+in production. With that key in place:
 
-## 6. License keys and output marking
+- You may set the key in that Deployment and in the development,
+  staging, CI and test copies of that Deployment. The key then removes
+  the marking there too.
+- One key never covers two Deployments at the same time.
+- You may move a key to a new Deployment after the old Deployment no longer
+  runs the Software in production.
+- Contractors who work for you may use your keys for that work. They
+  may not use your keys for work they do for other clients.
 
-The Software accepts a license key that evidences your Seats under
-section 4. Key checks run offline.
+## 5. Use and pass-through
 
-Without a valid key, or with a key whose validity period does not cover
-the installed version's release date, the Software runs with its full
-feature set but marks its output as unlicensed. Using a key you are not
-entitled to is a material breach of this agreement.
+With a License Key under section 4 in place, you may operate the
+Application in its Deployment **royalty-free**. We charge no fees for
+servers, replicas, requests, renders, agents or End Users. You may
+embed your License Key in the Application.
 
-You may not remove, disable, or circumvent the key check or the output
+We grant you the right to pass through to each End User a limited,
+non-exclusive, non-transferable right to use the Software only as
+embedded in the Application that runs in your Deployment. You must not
+let End Users extract the Software from the Application or use it to
+develop software of their own.
+
+Calling applications that only request renders from your Deployment do
+not need to incorporate the Software. People who use those applications
+only as End Users get the pass-through rights above.
+
+You may not:
+
+- Distribute the Software on its own, or as part of a product whose
+  primary purpose is to give report-engine, report-design or
+  document-generation capability to third-party developers.
+- Expose the Software's APIs to third parties as a development tool or
+  service that replaces their own License Keys. A service you operate
+  that embeds the Software and renders for your own End Users is not
+  such a tool.
+- Fork, mirror, repackage, rename or wrap the Software, or republish it
+  on any package registry or code-hosting platform, other than as
+  embedded in an Application.
+
+**OEM distribution.** An Application that your customers install,
+embed or resell, and that runs the Software outside your control, is
+OEM distribution. A License Key does not cover OEM distribution, for
+any number of copies. Contact us for separate terms. When you render
+documents for your customers from a product that you host yourself,
+that product is a Deployment, not OEM distribution.
+
+While this agreement is in force, you may not create any tool,
+library, product or service that competes with the Software or with
+any other Quario product, directly or indirectly. This restriction
+ends when this agreement terminates. You may not remove or change
+copyright or license notices in the Software.
+
+## 6. License Keys and output marking
+
+The Software accepts a License Key as evidence of a Deployment's
+license under section 4. Key checks run offline.
+
+Each License Key states an end date. A key covers every release of the
+Software dated on or before that end date. Without a valid key, or with
+a key that does not cover the installed release, the Software runs with
+its full feature set but marks its output as unlicensed. A key that is
+void under section 7 licenses nothing, even where the installed
+release still accepts it. Use of a key that you have no right to use
+is a material breach of this agreement.
+
+A later release may refuse a key that we revoked. We revoke a key when
+we refund its payment, or when a chargeback or similar process
+reverses its payment. We also revoke a key that
+someone publishes for reuse by others. In that case, we give the
+licensee a free replacement key with the same end date. When you embed a
+key in your Application under section 5, that embedding alone does not
+publish the key for reuse.
+
+You may not remove, disable or bypass the key check or the output
 marking, or distribute anything that does.
 
-## 7. Term, updates, and perpetual fallback
+## 7. Term, updates and refunds
+
+**No subscription.** You pay once for each License Key. The key covers
+every release dated up to one year after you bought it, and you get
+support until that end date. We give support through our issue tracker
+and by email, with commercially reasonable effort. We do not guarantee
+response times.
+
+**Perpetual license.** Your license to the releases that a key covers
+is **perpetual**. The Deployment may keep using those releases, and
+the Application may keep running them, forever, at no further cost.
+Releases dated after the key's end date need a new key.
 
-Seats are sold as an annual subscription. While the subscription is
-active, licensed Developers receive all Software versions we release,
-and support for the Software through our issue tracker and by email. We
-provide support with commercially reasonable effort; we do not guarantee
-specific response times.
+**Renewal.** Renewal is a new purchase of a new key. It never occurs
+automatically, and we never charge you without a new order.
 
-If the subscription lapses, your license to the versions released during
-your subscription is **perpetual, for the number of Seats held at the
-lapse**: up to that many Developers may keep using those versions, and
-your Applications may keep shipping them, forever, at no further cost.
-Versions released after the lapse require renewal. We encode this rule
-in purchased keys: a key remains valid for every version released
-during its validity period, with no end date.
+**Refunds and reversals.** If we refund a payment, or a chargeback or
+similar process reverses a payment, each key that the payment
+bought is void. A partial refund states the keys that it voids. A void
+key gives you no rights, including no perpetual license. You keep the
+rights of section 3, and this agreement continues. Use of a void key in
+a Deployment is a material breach of this agreement. Keys that the
+refund or reversal does not void stay valid. If a payment dispute is
+decided in our favour, we restore the license with a reissued key.
 
 ## 8. Source availability
 
-The Software's packages ship with readable source code so that you can
+The Software's packages ship with readable source code, so you can
 review and debug what you run. Readable source does not grant extra
-rights: this agreement governs all use of the source, and you may
-publish the Software (modified or not) only as part of an Application
-under section 5.
+rights. This agreement governs all use of the source. You may publish
+the Software, modified or not, only as part of an Application under
+section 5.
 
-## 9. Ownership, trademarks, and feedback
+## 9. Ownership, trademarks and feedback
 
-We license the Software; we retain all intellectual property rights in
-it. Report definitions, data, and output you create with the Software
-are yours. "Quario" and the Quario logo are our trademarks; this
-agreement grants no rights to use them beyond identifying the Software.
-If you send us feedback or suggestions, we may use them without
-obligation.
+We license the Software. We keep all intellectual property rights in
+it. The report definitions, data and output that you create with the
+Software are yours. "Quario" and the Quario logo are our trademarks.
+This agreement grants no rights to use them, except to identify the
+Software. If you send us feedback or suggestions, we may use them
+without obligation.
 
 ## 10. Warranty and liability
 
@@ -181,11 +202,11 @@ We provide the Software as is. To the fullest extent the law allows, we
 disclaim all warranties and conditions, express or implied, including
 merchantability, fitness for a particular purpose, and non-infringement.
 
-To the fullest extent the law allows: we are not liable for indirect or
+To the fullest extent the law allows, we are not liable for indirect or
 consequential damages, loss of profits, loss of data, or business
-interruption; and our total aggregate liability under this agreement is
+interruption. Our total aggregate liability under this agreement is
 limited to the greater of EUR 100 and the fees you paid us in the
-twelve months preceding the event giving rise to the claim. These
+twelve months before the event that gave rise to the claim. These
 limitations do not apply where the damage results from the intent or
 deliberate recklessness (opzet of bewuste roekeloosheid) of us or our
 management, or where mandatory law does not permit them.
@@ -193,23 +214,24 @@ management, or where mandatory law does not permit them.
 ## 11. Termination and survival
 
 If you materially breach this agreement, we may terminate it by notice.
-If the breach can be remedied, we will first allow 30 days from that
-notice to remedy it, and termination takes effect only if the breach
-remains. On termination, the licenses granted here end.
-Perpetual-fallback rights under section 7 survive termination only if
-they arose from a lapse that predates the breach, and section 5
-survives with them to the extent needed to keep exercising them.
-Sections 8 through 12 survive any termination.
+If you can remedy the breach, we first give you 30 days from that
+notice to remedy it. Termination then occurs only if the breach
+continues. On termination, the licenses that this agreement grants end.
+The perpetual license to the releases that a key covers survives
+termination only if the end date of that key passed before the breach.
+Section 5 survives with it, as far as you need section 5 to use that
+license. Sections 8 through 12 survive any termination.
 
 ## 12. General
 
-Dutch law governs this agreement. Disputes go to the competent court for
-our registered office. You may not assign this agreement without our
-consent, except to a successor of your whole business; we may assign it
-to a successor of ours. If a provision is unenforceable, the remainder
-stays in force. Failure to enforce a provision does not waive it. This
-agreement, together with your order for Seats, is the entire agreement
-about the Software, unless we agree otherwise in writing.
+Dutch law governs this agreement. The competent court for our
+registered office decides disputes. You may not assign this agreement
+without our consent, except to a successor of your whole business. We
+may assign it to a successor of ours. If a provision is unenforceable,
+the remainder stays in force. If we do not enforce a provision, we do
+not waive it. This agreement, together with your order for License
+Keys, is the entire agreement about the Software, unless we agree
+otherwise in writing.
 
 ---
 

package/lib/format.js

@@ -94,7 +94,7 @@ let asMoney = (value, locale, decl, options, style) => {
 //
 // The form is Intl's own `dateStyle`, and it is always present: a declaration
 // that named none resolved to `medium` (docs/adr/0056). This is the half that
-// does not converge — the worksheet approximates it (CONTEXT.md, "Form").
+// does not converge — the worksheet approximates it (GLOSSARY.md, "Form").
 // `date` leads for the same reason the number kinds do, so the two key shapes
 // live beside each other and "one piece at a time" is auditable in one place.
 /** @type {(locale: string, decl: any, zone: string) => string} */

package/lib/host.js

@@ -6,10 +6,15 @@
  *
  * Here rather than in a target for the reason `imageError` carries beside it:
  * every target needs it, no two of them may depend on each other, and the
- * engine is what they all already have. Nothing an author writes reaches this
- * module -- these are host API, and no located diagnostic is involved.
+ * engine is what they all already have. The engine's own two option bags,
+ * `quario()`'s and `plan()`'s, are checked here too, by the same rule. Nothing
+ * an author writes reaches this module -- these are host API, and no located
+ * diagnostic is involved.
  */
 
+import { query } from "padvinder";
+import { isCode } from "./style.js";
+
 /** @type {(msg: string) => never} */
 let fail = (msg) => {
   throw TypeError(msg);
@@ -23,6 +28,12 @@ let fail = (msg) => {
  */
 let plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 
+// Nullish is absence; anything else must be a string.
+/** @type {(value: unknown, at: string) => void} */
+let string = (value, at) => {
+  if (value != null && typeof value !== "string") fail(at + ": expected a string");
+};
+
 // Own keys only: an inherited enumerable property is the prototype's business,
 // and naming it back at the host would name something they never wrote.
 /** @type {(value: object, keys: readonly string[], at: string) => void} */
@@ -58,9 +69,7 @@ let PROPERTIES = ["title", "author", "subject"];
 // was never written.
 /** @type {(value: any, at: string) => void} */
 let everyString = (value, at) => {
-  for (let key of Object.keys(value))
-    if (value[key] != null && typeof value[key] !== "string")
-      fail(at + "." + key + ": expected a string");
+  for (let key of Object.keys(value)) string(value[key], at + "." + key);
 };
 
 /**
@@ -87,3 +96,73 @@ export let hostMeta = (value, at) => {
   everyString(value, at);
   return { ...value };
 };
+
+/**
+ * Every key `quario()` takes. The factory closes its set against this list,
+ * and the conformance fixture in quario's suite is held to it, so the list and
+ * `QuarioOptions` cannot drift apart unnoticed (`docs/adr/0072`, amended).
+ */
+export let INSTANCE_KEYS = ["query", "license", "locale", "currency", "timeZone", "schemes"];
+
+// `Intl` owns which locales and zones exist, so it is asked rather than
+// copied. What it refuses is a RangeError, which here is the host's mistake
+// and wears the host-mistake class.
+/** @type {(value: unknown, at: string, probe: (value: any) => unknown) => void} */
+let intl = (value, at, probe) => {
+  if (value == null) return;
+  try {
+    probe(value);
+  } catch {
+    fail(at + ": " + JSON.stringify(value) + " is not one Intl accepts");
+  }
+};
+
+/**
+ * The engine factory's own options, refused at the call like a target's. The
+ * three names that present `format` are checked for validity and not just
+ * type, because a typo there does not fail: every formatted cell prints its
+ * raw value instead. A cell's own `style.currency` keeps failing soft -- that
+ * is the authoring surface, and this is the host's.
+ *
+ * `currency` takes the author's gate, three upper-case letters, because the
+ * xlsx target splices the code into a number format and an engine default the
+ * gate never saw would be the one code that skipped it (`docs/adr/0041`).
+ *
+ * `schemes` keeps its own null posture: a `null` allowlist is a host saying
+ * something, and reading it as the default would widen what they restricted
+ * (`docs/adr/0085`).
+ *
+ * `query` is padvinder's, and so is the list of what it may carry: compiling
+ * one trivial query here raises padvinder's own refusal at the call, where it
+ * would otherwise wait for the first query a document compiles.
+ *
+ * @param {any} options The `quario()` argument.
+ */
+export let instanceOptions = (options) => {
+  let o = hostOptions(options, INSTANCE_KEYS, "options") ?? {};
+  query("$", undefined, o.query);
+  for (let key of ["license", "locale", "currency", "timeZone"]) string(o[key], "options." + key);
+  intl(o.locale, "options.locale", (v) => Intl.getCanonicalLocales(v));
+  intl(o.timeZone, "options.timeZone", (v) => Intl.DateTimeFormat("en", { timeZone: v }));
+  if (o.currency != null && !isCode(o.currency))
+    fail("options.currency: expected a three-letter ISO 4217 code");
+  let schemes = o.schemes;
+  if (schemes === undefined) return;
+  let listed =
+    Array.isArray(schemes) &&
+    schemes.every((scheme) => typeof scheme === "string" && /^[a-z][a-z0-9+.-]*:$/.test(scheme));
+  if (!listed)
+    fail("options.schemes: expected an array of lower-case URL schemes, each ending in a colon");
+};
+
+/**
+ * The third argument of an instance's `plan()`, closed like the factory's, so
+ * a misspelt `targets` is a throw rather than a plan that checked nothing and
+ * said so by saying nothing.
+ *
+ * @param {any} options The `plan()` options.
+ */
+export let planOptions = (options) => {
+  let targets = hostOptions(options, ["targets"], "options")?.targets;
+  if (targets != null && !Array.isArray(targets)) fail("options.targets: expected an array");
+};

package/lib/image.js

@@ -1,7 +1,8 @@
 /**
  * What the engine reads out of an image item's bytes: which format they are,
  * and how big the picture is. Read, never decoded -- a magic number, a PNG's
- * IHDR and a JPEG's frame header, and nothing here looks at a pixel.
+ * IHDR, a JPEG's frame header and an SVG's root tag, and nothing here looks at
+ * a pixel or draws a shape.
  *
  * Both answers ride on the image event, so no target reads these headers
  * again. That is the whole of `docs/adr/0067`: two targets used to keep a
@@ -16,6 +17,45 @@
 let PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
 let JPEG = [0xff, 0xd8, 0xff];
 
+// SVG has no magic number: it is text, named by its root element. Fatal, so
+// bytes that are not UTF-8 are not text at all. The decoder drops a leading
+// BOM on its own.
+let UTF8 = new TextDecoder("utf-8", { fatal: true });
+
+// What may stand before the root, one at a time: whitespace, then a
+// processing instruction (the XML declaration is one), a comment or a
+// doctype with its optional internal subset. Sticky, so each match starts
+// where the last one ended and nothing is skipped over.
+let PROLOG = /\s*(?:<\?[\s\S]*?\?>|<!--[\s\S]*?-->|<!DOCTYPE[^[>]*(?:\[[\s\S]*?\])?\s*>)/y;
+
+// The root's start tag, whose attributes are the group. A quoted value may
+// hold a `>`, so the tag ends at the first one outside quotes. `<svgx` and a
+// prefixed `<s:svg` are other elements.
+let ROOT = /\s*<svg(?=[\s/>])((?:[^>"']|"[^"]*"|'[^']*')*)>/y;
+
+/**
+ * The text inside the root's start tag, when the bytes are UTF-8 whose first
+ * element after the prolog is `<svg`, else null. An HTML page holding an SVG
+ * further in is not one: the root decides (SCHEMA.md, "Image item").
+ *
+ * @type {(bytes: Uint8Array) => string | null}
+ */
+let svgRoot = (bytes) => {
+  let text;
+  try {
+    text = UTF8.decode(bytes);
+  } catch {
+    return null;
+  }
+  // A sticky test that fails resets `lastIndex` to zero, so the end of the
+  // last prolog part is kept apart from it.
+  let at = 0;
+  PROLOG.lastIndex = 0;
+  while (PROLOG.test(text)) at = PROLOG.lastIndex;
+  ROOT.lastIndex = at;
+  return ROOT.exec(text)?.[1] ?? null;
+};
+
 /**
  * The image seam: name the format a `source` expression's bytes hold, or null
  * when they are not image bytes at all -- including when they are not bytes.
@@ -23,12 +63,13 @@ let JPEG = [0xff, 0xd8, 0xff];
  * so no consumer repeats it.
  *
  * @param {any} bytes The value a `source` expression yielded.
- * @returns {"png" | "jpeg" | null} The format, or null when unreadable.
+ * @returns {"png" | "jpeg" | "svg" | null} The format, or null when unreadable.
  */
 export function sniff(bytes) {
   if (!(bytes instanceof Uint8Array)) return null;
   if (PNG.every((byte, i) => bytes[i] === byte)) return "png";
   if (JPEG.every((byte, i) => bytes[i] === byte)) return "jpeg";
+  if (svgRoot(bytes) != null) return "svg";
   return null;
 }
 
@@ -62,15 +103,67 @@ let jpegSize = (bytes) => {
   return { width: 0, height: 0 };
 };
 
+// A plain decimal, as XML's attribute grammar writes one. Stricter than
+// `Number`, which would also read hex, `Infinity` and the empty string.
+let NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+/** @type {(text: string) => number} */
+let number = (text) => (NUMBER.test(text) ? Number(text) : NaN);
+
+// The absolute units, as how many of each make an inch. Pixels are the
+// unit the event carries, so a unitless length and `px` pass as they are,
+// and the rest convert at the 96 dpi the size is read at everywhere else.
+let PER_INCH = new Map([
+  ["pt", 72],
+  ["in", 1],
+  ["cm", 2.54],
+  ["mm", 25.4],
+]);
+
+/** @type {(value: string | undefined) => number | null} */
+let length = (value) => {
+  let [, amount = "", unit = ""] = value?.trim().match(/^(.*?)(px|pt|in|cm|mm)?$/) ?? [];
+  let pixels = number(amount);
+  if (Number.isNaN(pixels)) return null;
+  let perInch = PER_INCH.get(unit);
+  return perInch ? (pixels / perInch) * 96 : pixels;
+};
+
+// One attribute of the root's start tag, double- or single-quoted.
+let ATTRIBUTE = /([^\s=/]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+
+// An SVG's size is the root's `width` and `height` when both are absolute
+// lengths, else its `viewBox`'s last two numbers. A percentage or a font-
+// relative length is no size: it depends on a container the file never sees.
+/** @type {(bytes: Uint8Array) => { width: number, height: number }} */
+let svgSize = (bytes) => {
+  // `sniff` named these bytes SVG, so the root is there to read.
+  let root = /** @type {string} */ (svgRoot(bytes));
+  let attributes = new Map(
+    [...root.matchAll(ATTRIBUTE)].map(([, name, double, single]) => [name, double ?? single]),
+  );
+  let width = length(attributes.get("width"));
+  let height = length(attributes.get("height"));
+  if (width != null && height != null) return { width, height };
+  let box =
+    attributes
+      .get("viewBox")
+      ?.trim()
+      .split(/[\s,]+/)
+      .map(number) ?? [];
+  return box.length === 4 ? { width: box[2], height: box[3] } : { width: 0, height: 0 };
+};
+
 // One reader per format `sniff` names.
 /** @type {Record<string, (bytes: Uint8Array) => { width: number, height: number }>} */
-let READERS = { png: pngSize, jpeg: jpegSize };
+let READERS = { png: pngSize, jpeg: jpegSize, svg: svgSize };
 
 /**
  * The image's own size in pixels, or null when the header does not carry one
  * -- bytes whose magic numbers `sniff` vouched for, truncated before the
- * dimensions. Read, never decoded: a PNG's IHDR and a JPEG's frame header
- * carry the two numbers, and nothing here looks at a pixel.
+ * dimensions, or an SVG whose root states no usable size. Read, never
+ * decoded: a PNG's IHDR, a JPEG's frame header and an SVG's root tag carry
+ * the two numbers, and nothing here looks at a pixel.
  *
  * The size rides on the image event beside the format, so every target places
  * a picture from a field rather than parsing the same two headers again, and a
@@ -78,7 +171,7 @@ let READERS = { png: pngSize, jpeg: jpegSize };
  * alike (`docs/adr/0067`).
  *
  * @param {Uint8Array} bytes The image file.
- * @param {"png" | "jpeg"} format The format `sniff` named.
+ * @param {"png" | "jpeg" | "svg"} format The format `sniff` named.
  * @returns {{ width: number, height: number } | null} The size, if readable.
  */
 export function dimensions(bytes, format) {
@@ -86,7 +179,10 @@ export function dimensions(bytes, format) {
   // format `sniff` learns later and this table does not would throw here
   // rather than be read silently as the one on the ternary's else branch.
   let size = READERS[format](bytes);
-  // A zero is how either reader says "the header stopped before this" -- an
-  // absent byte reads as zero, and no image is zero wide.
-  return size.width > 0 && size.height > 0 ? size : null;
+  // A zero is how a raster reader says "the header stopped before this" -- an
+  // absent byte reads as zero, and no image is zero wide. The SVG reader
+  // hands back whatever the root said, so a negative, a NaN and an infinity
+  // fail here too.
+  let placeable = (/** @type {number} */ n) => n > 0 && n < Infinity;
+  return placeable(size.width) && placeable(size.height) ? size : null;
 }

package/lib/index.d.ts

@@ -161,6 +161,21 @@ export interface StyleDeclarations extends BoxDeclarations {
   spaceAfter?: ExpressionValue<Points>;
 }
 
+/** How a group orders and cuts its instances. */
+export interface Instances {
+  /**
+   * Order the instances. Each key reads the group's own handle once per
+   * instance, with `@` and `run` unbound.
+   */
+  sort?: SortKey[];
+  /**
+   * Keep this many instances after `sort`. Integer >= 1. A dropped instance
+   * never renders, so no runner steps over it, but the enclosing aggregates
+   * still count it.
+   */
+  take?: Count;
+}
+
 export interface SortKey {
   by: Expression;
   dir?: "asc" | "desc";
@@ -349,9 +364,9 @@ export type ImageStyleDeclarations = Pick<
 export type ReportStyleDeclarations = Pick<StyleDeclarations, "family" | "size">;
 
 /**
- * A host-supplied raster graphic in the band flow. `source` is an expression
+ * A host-supplied graphic in the band flow. `source` is an expression
  * (never a literal — JSON has no way to write bytes) yielding the complete
- * image file as a `Uint8Array` of PNG or JPEG bytes; nullish skips the item
+ * image file as a `Uint8Array` of PNG, JPEG or SVG bytes; nullish skips the item
  * silently, anything else invalid is a located render error.
  */
 export interface ImageItem {
@@ -594,6 +609,12 @@ export interface Group {
    */
   columns?: ColumnCount;
   sort?: SortKey[];
+  /**
+   * Order and cut this group's instances, as the group's own `sort` and
+   * `take` order and cut the rows inside each. Absent, every instance renders
+   * in first-seen order.
+   */
+  instances?: Instances;
   /**
    * Keep this many rows after this group's `sort`. Integer >= 1. Rows past
    * the count are dropped from aggregates and runners, unlike `visible`.
@@ -931,7 +952,7 @@ export interface ItemEvent {
 }
 
 /** The format the engine sniffed from an image's bytes. */
-export type ImageFormat = "png" | "jpeg";
+export type ImageFormat = "png" | "jpeg" | "svg";
 
 export interface ImageEvent {
   type: "image";
@@ -940,7 +961,10 @@ export interface ImageEvent {
   path: string;
   /** The bytes exactly as the `source` expression yielded them. */
   bytes: Uint8Array;
-  /** Sniffed from the bytes' magic numbers, so no consumer repeats it. */
+  /**
+   * Sniffed from the bytes — a PNG's or a JPEG's magic number, an SVG's root
+   * element — so no consumer repeats it.
+   */
   format: ImageFormat;
   /**
    * The image's own width in pixels, read from the same header. Bytes too
@@ -1262,13 +1286,21 @@ export interface Quario {
    * The one traversal, whole: compiled report (null on problems), structured
    * problems, advisory warnings, and per-node anchor sets — one descent per
    * edit for a host that validates and renders in a loop.
+   *
+   * @throws {TypeError} For an unknown `options` key, or a `targets` that is
+   * not an array — closed like the factory's own options.
    */
   plan(schema: unknown, functions?: FunctionRegistry, options?: PlanOptions): Plan;
 }
 
 /**
  * Create a configured instance: host-level options (license key, query
- * budgets).
+ * budgets, presentation, the `href` allowlist).
+ *
+ * @throws {TypeError} At the call, for an unknown option key, a value of the
+ * wrong type, a `locale` or `timeZone` that `Intl` refuses, or a `currency`
+ * that is not three upper-case letters. Nullish is absence, except for
+ * `schemes`. The `query` budgets are refused by padvinder, in its own words.
  */
 export function quario(options?: QuarioOptions): Quario;
 

package/lib/index.js

@@ -14,7 +14,8 @@
  */
 import { relocate as relocateQuery } from "padvinder";
 import { LEAD_REFUSED, isLead, leadPath } from "./band-height.js";
-import { MARKING, verify } from "./license.js";
+import { instanceOptions, planOptions } from "./host.js";
+import { MARKING, TRUST, verify } from "./license.js";
 import { err, fault, locate } from "./locate.js";
 import { BLOCKED, NAME, record } from "./names.js";
 import { checkParamType, jsonCopy, plan } from "./plan.js";
@@ -152,7 +153,7 @@ let calling = (target) => (typeof target?.target === "string" ? target.target :
 /** @type {readonly any[]} */
 let NO_TARGETS = Object.freeze([]);
 /** @type {(opts: any) => readonly any[]} */
-let named = (opts) => (Array.isArray(opts?.targets) ? opts.targets : NO_TARGETS);
+let named = (opts) => opts?.targets ?? NO_TARGETS;
 
 // What a caller asked to check beyond the document: the required declarations
 // its targets lose.
@@ -175,7 +176,7 @@ let loss = (target, name) => {
 let unmet = (required, targets) =>
   required.flatMap((name) => targets.map((target) => loss(target, name)).filter(Boolean));
 
-// The per-node anchor sets, as frozen host data (CONTEXT.md, "Freeze"): which
+// The per-node anchor sets, as frozen host data (GLOSSARY.md, "Freeze"): which
 // anchors and group handles each compiled source reads, keyed by schema path.
 /** @type {(anchors: Map<string, Set<string>>) => any} */
 let freezeAnchors = (anchors) =>
@@ -484,21 +485,6 @@ function assemble(planned, schema, marking, options) {
 
 /** @typedef {import("./license.js").LicenseInfo} LicenseInfo */
 
-// The `href` allowlist, checked once at construction rather than per cell.
-// It **throws** where every other host option is lenient: an allowlist is a
-// security control, and one the engine quietly replaced with its own default
-// would be a host believing it had restricted something it had not
-// (docs/adr/0085).
-/** @type {(schemes: unknown) => void} */
-let checkSchemes = (schemes) => {
-  if (schemes === undefined) return;
-  let listed =
-    Array.isArray(schemes) &&
-    schemes.every((scheme) => typeof scheme === "string" && /^[a-z][a-z0-9+.-]*:$/.test(scheme));
-  if (!listed)
-    throw Error("schemes: expected an array of lower-case URL schemes, each ending in a colon");
-};
-
 /**
  * Create a configured quario instance: the host-level options — license key,
  * query budgets. The key is verified once, here, and `license` settles with
@@ -507,19 +493,18 @@ let checkSchemes = (schemes) => {
  * ("Instances and targets").
  *
  * @param {{query?: {maxNodes?: number, maxDepth?: number, maxResults?: number},
- *   license?: string, trust?: {publicKey?: string, release?: string},
- *   locale?: string, currency?: string, timeZone?: string,
+ *   license?: string, locale?: string, currency?: string, timeZone?: string,
  *   schemes?: readonly string[]}} [options]
- *   Host configuration. `trust` is internal, not API — see ./license.js.
- *   `locale` / `currency` / `timeZone` present `format` (docs/adr/0041), and
+ *   Host configuration, its key set closed (docs/adr/0072). `locale` / `currency` / `timeZone` present `format` (docs/adr/0041), and
  *   `schemes` is the `href` allowlist (docs/adr/0085).
  * @returns {{license: Promise<LicenseInfo>,
  *   report: (schema: any, funcs?: Record<string, Function>) => any,
- *   plan: (schema: any, funcs?: Record<string, Function>) => any}} The instance.
+ *   plan: (schema: any, funcs?: Record<string, Function>, opts?: any) => any}}
+ *   The instance.
  */
 export function quario(options) {
-  checkSchemes(options?.schemes);
-  let { licensed, settled } = verify(options?.license, options?.trust);
+  instanceOptions(options);
+  let { licensed, settled } = verify(options?.license, /** @type {any} */ (options)?.[TRUST]);
   // The wording is the instance's, where the key is; the stream is what
   // states it, so nothing wraps a compiled stream to reach its first event.
   /** @type {() => string | false} */
@@ -571,7 +556,7 @@ export function quario(options) {
     report(schema, funcs) {
       return wrap(events(schema, funcs, options, marking));
     },
-    // The plan (CONTEXT.md): both readings of the one descent, kept.
+    // The plan (GLOSSARY.md): both readings of the one descent, kept.
     // `report()` and `validate()` name what a caller wanted from it; this
     // hands over the whole thing — the compiled report (null while the
     // document has problems), every problem structurally, and the per-node
@@ -586,6 +571,7 @@ export function quario(options) {
     // makes the whole marking additive.
     /** @type {(schema: any, funcs?: Record<string, Function>, opts?: any) => any} */
     plan(schema, funcs, opts) {
+      planOptions(opts);
       let planned = plan(schema, funcs, options);
       // After the document's own, so a problem list still opens with what is
       // wrong with the report rather than with where it is going.

package/lib/license.js

@@ -11,7 +11,7 @@
 // though nothing reassigns them. A key is valid for every version released on
 // or before its `to` (LICENSE section 7), so validity compares ISO date
 // strings and never reads a clock — accepted output stays accepted.
-let RELEASE = "2026-10-01"; // release-date
+let RELEASE = "2026-10-08"; // release-date
 // The verifying half of the signing pair: the 65-byte uncompressed P-256
 // point, base64url. The private half never enters the repo;
 // scripts/license/sign.mjs mints keys against it.
@@ -24,6 +24,18 @@ let PUBKEY =
 // draws it through a base-14 face, and the em dash is the one character here
 // that had to be checked. The assertion that would catch a bad one lives in
 // that target's suite (`packages/pdf/test/pdf.test.js`), not this package's.
+/**
+ * The key a test suite writes its keypair under, in place of the shipped one.
+ * A symbol rather than an option name: the production private key never
+ * enters the repo, so the suites verify against freshly generated pairs, and
+ * a named option would hand every host the same seam -- sign your own key,
+ * pass your own public key. The closed option check reads string keys only,
+ * and nothing the package exports reaches this module, so a host has no
+ * spelling for it. The suites import it through the repository's `#license`
+ * specifier, which resolves to this file and not a copy of it.
+ */
+export let TRUST = Symbol("quario.trust");
+
 export let MARKING = "Unlicensed evaluation — getquario.com";
 
 let ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
@@ -107,8 +119,7 @@ let failMsg = (error) => (error instanceof Error ? error.message : String(error)
  * @param {string | undefined} key The instance's `license` option.
  * @param {{publicKey?: string, release?: string}} [trust] What this instance
  *   verifies against, defaulting to the shipped key and release date. Internal
- *   — a test seam, not API: the production private key never enters the repo,
- *   so suites verify against freshly generated pairs.
+ *   — the `TRUST` seam above, never an option a host can name.
  * @returns {{licensed: () => boolean, settled: Promise<LicenseInfo>}}
  */
 export let verify = (key, trust) => {

package/lib/plan.js

@@ -10,7 +10,7 @@
  * constructs, so they must not appear even in a comment.)
  *
  * It is a traversal, never a walk: that word belongs to the event stream and
- * its driver (CONTEXT.md). Six layers hold it, each a factory named for what it
+ * its driver (GLOSSARY.md). Six layers hold it, each a factory named for what it
  * returns and taking the layers it builds on, composed by `plan()` at the foot
  * of the file:
  *
@@ -192,6 +192,7 @@ export let KEY_SETS = Object.freeze({
     "reset",
     "columns",
     "sort",
+    "instances",
     "take",
     "aggregates",
     "run",
@@ -199,6 +200,7 @@ export let KEY_SETS = Object.freeze({
     "footer",
   ],
   sortKey: ["by", "dir"],
+  instances: ["sort", "take"],
   param: ["default", "type", "label"],
   text: TEXT,
   textSlot: [...TEXT, "width"],
@@ -644,7 +646,7 @@ let runProp = (expression, path, source) => (scope) => {
   // have a text form, and that is the token seam.
   return refuseThenable(out, path, source, ONLY_A_CELL);
 };
-// The [live field](../../../CONTEXT.md#live-field): which page value a token
+// The [live field](../../../GLOSSARY.md#live-field): which page value a token
 // *is*, for a target whose own format numbers pages. sjabloon offers each
 // interpolation's expression source once while compiling, the only place the
 // author's words still exist. Reading the source here instead is what hard
@@ -1269,9 +1271,14 @@ let readers = ({ bad, warn, attempt }, { prop, cell, parseFold }, /** @type {any
     checkDir(spec.dir, keyPath + ".dir");
     return [{ by, sign: spec.dir === "desc" ? -1 : 1 }];
   };
-  // A sort spec (array of { by, dir }) becomes a comparator over rows.
-  /** @type {(value: any, path: string) => ((rows: any[], scope: Scope) => any[]) | null} */
-  let sortOf = (value, path) => {
+  // A sort spec (array of { by, dir }) becomes a comparator over rows, or over
+  // whatever `bind` turns into the scope its keys read: a group's `instances`
+  // binds each instance's own group scope, where no row is current.
+  /**
+   * @type {(value: any, path: string, bind?: (scope: Scope, item: any) => Scope)
+   *   => ((items: any[], scope: Scope) => any[]) | null}
+   */
+  let sortOf = (value, path, bind = withRow) => {
     let specs = arr(value, path);
     if (!specs || !specs.length) return null;
     let sortKeys = specs.flatMap((spec, i) => sortKey(spec, i, path));
@@ -1287,7 +1294,7 @@ let readers = ({ bad, warn, attempt }, { prop, cell, parseFold }, /** @type {any
       let resolved = [];
       for (let row of rows) {
         // One scope child per row: every key of that row reads the same one.
-        let bound = withRow(scope, row);
+        let bound = bind(scope, row);
         for (let key of sortKeys) resolved.push(key.by(bound));
       }
       // `sort` is stable, so a full tie leaves the indices — and with them
@@ -1603,7 +1610,7 @@ let nodes = (
     // into a string -- and both answers ride on the event so no target reads
     // the same header a second time.
     let format = sniff(bytes);
-    if (!format) badImage(fields, "expected a Uint8Array of PNG or JPEG bytes");
+    if (!format) badImage(fields, "expected a Uint8Array of PNG, JPEG or SVG bytes");
     let size = dimensions(bytes, format);
     // The one thing the engine reads past the magic numbers, and so the one
     // header failure every target shares: a file that cannot state its size
@@ -2196,6 +2203,27 @@ let bands = (
       rows,
     };
   };
+  /** @type {(items: any[], fn: (item: any) => any) => Generator<any>} */
+  let lazily = function* (items, fn) {
+    for (let item of items) yield fn(item);
+  };
+  // A partition's instances, opened, in the order they render, and how many
+  // render. Without `instances.sort` that is first-seen order, opened one at a
+  // time as the walk reaches each. With it every instance opens first,
+  // because its key reads the handles, and the group scopes are then what it
+  // orders. `instances.take` cuts either order the way a row `take` cuts rows,
+  // so an instance it drops never opens a band.
+  /** @type {(ctx: any, parts: Map<any, any[]>, scope: Scope) => { count: number, each: Iterable<any> }} */
+  let instancesOf = (ctx, parts, scope) => {
+    let { sort, take } = ctx.instances;
+    /** @type {(part: [any, any[]]) => any} */
+    let open = ([key, groupRows]) => ({ key, ...openInstance(ctx, key, groupRows, scope) });
+    let kept = (sort ? sort(Array.from(parts, open), scope) : [...parts]).slice(
+      0,
+      take ?? undefined,
+    );
+    return { count: kept.length, each: sort ? kept : lazily(kept, open) };
+  };
   // One instance's bands, in order, as the events they yield.
   /** @type {(ctx: any, groupScope: any, ordered: any[], runners: any) => Generator<any>} */
   let instanceBands = function* (ctx, groupScope, ordered, runners) {
@@ -2232,11 +2260,11 @@ let bands = (
       // run's own two edges fall on its first and its last. The run is this
       // call's partition, so a nested group's edges belong to the parent
       // instance holding it rather than to the document.
-      let last = parts.size - 1;
+      let { count, each } = instancesOf(ctx, parts, scope);
+      let last = count - 1;
       let index = 0;
-      for (let [key, groupRows] of parts) {
-        // A group band has no current row, so `@` stays unbound here.
-        let { groupScope, aggregates, rows: ordered } = openInstance(ctx, key, groupRows, scope);
+      // A group band has no current row, so `@` stays unbound here.
+      for (let { key, groupScope, aggregates, rows: ordered } of each) {
         yield opt(
           {
             type: "group-start",
@@ -2262,6 +2290,19 @@ let bands = (
         index++;
       }
     };
+  /** @type {(scope: Scope, instance: any) => Scope} */
+  let instanceScope = (_, instance) => instance.groupScope;
+  // `instances` is the group's own `sort` and `take`, one level up: the same
+  // two words, over its instances rather than its rows (docs/adr/0103).
+  /** @type {(value: any, path: string) => { sort: any, take: number | null }} */
+  let instancesSpec = (value, path) => {
+    if (value == null || !obj(value, path)) return { sort: null, take: null };
+    keys(value, KEY_SETS.instances, path);
+    return {
+      sort: sortOf(value.sort, path + ".sort", instanceScope),
+      take: takeOf(value.take, path + ".take"),
+    };
+  };
   /** @type {(def: any, path: string, defs: any[], index: number, detail: any, columned?: boolean) => Band} */
   let compileGroup = (def, path, defs, index, detail, columned) => {
     keys(def, KEY_SETS.group, path);
@@ -2279,6 +2320,7 @@ let bands = (
       // styling a fragment of one would mean nothing anywhere it is spent.
       label: def.label == null ? null : textValue(def.label, path + ".label"),
       sort: sortOf(def.sort, path + ".sort"),
+      instances: instancesSpec(def.instances, path + ".instances"),
       take: takeOf(def.take, path + ".take"),
       aggs: foldsOf(def.aggregates, path + ".aggregates", "aggregate", new Set(["key"])),
       running: foldsOf(def.run, path + ".run", "run", null, runNames),

package/lib/schema.json

@@ -427,7 +427,7 @@
       },
       "required": ["type", "source"],
       "additionalProperties": false,
-      "description": "A host-supplied raster graphic in the band flow. `source` is an expression (never a literal — JSON has no way to write bytes) yielding the complete image file as a `Uint8Array` of PNG or JPEG bytes; nullish skips the item silently, anything else invalid is a located render error."
+      "description": "A host-supplied graphic in the band flow. `source` is an expression (never a literal — JSON has no way to write bytes) yielding the complete image file as a `Uint8Array` of PNG, JPEG or SVG bytes; nullish skips the item silently, anything else invalid is a located render error."
     },
     "ImageFit": {
       "type": "string",
@@ -930,6 +930,10 @@
           "description": "Flow each instance's content in this many page columns (integer >= 2). Columned regions cannot nest."
         },
         "sort": { "type": "array", "items": { "$ref": "#/$defs/SortKey" } },
+        "instances": {
+          "anyOf": [{ "$ref": "#/$defs/Instances" }],
+          "description": "Order and cut this group's instances, as the group's own `sort` and `take` order and cut the rows inside each. Absent, every instance renders in first-seen order."
+        },
         "take": {
           "anyOf": [{ "$ref": "#/$defs/Count" }],
           "description": "Keep this many rows after this group's `sort`. Integer >= 1. Rows past the count are dropped from aggregates and runners, unlike `visible`."
@@ -949,6 +953,22 @@
       "required": ["name", "by"],
       "additionalProperties": false
     },
+    "Instances": {
+      "type": "object",
+      "properties": {
+        "sort": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/SortKey" },
+          "description": "Order the instances. Each key reads the group's own handle once per instance, with `@` and `run` unbound."
+        },
+        "take": {
+          "anyOf": [{ "$ref": "#/$defs/Count" }],
+          "description": "Keep this many instances after `sort`. Integer >= 1. A dropped instance never renders, so no runner steps over it, but the enclosing aggregates still count it."
+        }
+      },
+      "additionalProperties": false,
+      "description": "How a group orders and cuts its instances."
+    },
     "TableDetail": {
       "type": "object",
       "properties": {

package/lib/stream.js

@@ -6,7 +6,7 @@
  *
  * `breathe` sits here because the driver batches on it, not because handing the
  * loop back is a stream rule — the two are independent, and a target breathes
- * while stamping finished pages, which is no walk at all (CONTEXT.md).
+ * while stamping finished pages, which is no walk at all (GLOSSARY.md).
  */
 // The token-join sjabloon renders with — literals verbatim, values through
 // the scalar `display()` rule — re-exported together so event consumers
@@ -174,7 +174,7 @@ export function styledRuns(tokens) {
   return out;
 }
 
-// The report's own bands, by the role their items wear (CONTEXT.md, "Band").
+// The report's own bands, by the role their items wear (GLOSSARY.md, "Band").
 // The page ones are in it although no walk emits them: the question is whose
 // band a role names, not what a walk hands over (ADR 0028).
 let REPORT_BANDS = new Set([

package/lib/style.js

@@ -33,7 +33,7 @@ let isHex = (value) => typeof value === "string" && HEX.test(value);
 // diagnostic at the price of a data file that goes stale (docs/adr/0041).
 let CODE = /^[A-Z]{3}$/;
 /** @type {(value: any) => boolean} */
-let isCode = (value) => typeof value === "string" && CODE.test(value);
+export let isCode = (value) => typeof value === "string" && CODE.test(value);
 // A declaration checks to a message or to null, and `spec` is the sugar for
 // the ordinary case: one predicate, one wording. `format` is the one entry
 // written out longhand, because a value with structure of its own has four
@@ -96,7 +96,7 @@ let FORMATS = ["number", "currency", "percent", "date"];
 // whole rule, and the two halves below -- the check and the resolution -- are
 // the only places it is spelled out.
 
-// The four names are Intl's `dateStyle`, and CONTEXT.md's "Form" is the term.
+// The four names are Intl's `dateStyle`, and GLOSSARY.md's "Form" is the term.
 // A bare `date` means `medium`: the fifth shape Intl's no-option default used
 // to produce was nameable by nothing, so an author held one behaviour more
 // than the vocabulary described (docs/adr/0056).
@@ -427,7 +427,7 @@ export let isRunName = (name) => RUN.has(name);
 export let checkRunStyle = narrowed(RUN_STYLES, "a styled run");
 export let checkSlotStyle = withoutFlow(checkStyle, "a split slot");
 // `valign` is legal exactly where a box has height it did not ask for
-// (CONTEXT.md "Box": slack). A slot's box is the split's height, so a slot --
+// (GLOSSARY.md "Box": slack). A slot's box is the split's height, so a slot --
 // text or image -- reads it; a band image's box is exactly its picture's
 // height, so it does not.
 // That is the one name an image accepts in a slot and nowhere else, the same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quario",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Tiny, CSP-safe report engine for JavaScript. One JSON document renders to HTML, PDF, XLSX, CSV and Word.",
   "keywords": [
     "csp",
@@ -62,7 +62,7 @@
         "sjabloon",
         "padvinder"
       ],
-      "limit": "17.5 kB"
+      "limit": "18 kB"
     }
   ],
   "engines": {