tosijs-floorplan 0.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,202 @@
+# tosijs-floorplan
+
+Render an **agent-surface map** — plain records describing a UI's wired
+elements — as a floorplan SVG: one shape per element at its true geometry,
+wearing an explicit **affordance grammar** so "can I act here?" never needs
+guessing. Like a floorplan of a building, it documents a *real, live*
+structure — where the doors are, which ones open.
+
+It is a **pure function over plain data**. No DOM, no framework, no
+dependencies. The map travels as JSON, so the renderer runs in the page, in
+a headless embodiment, in a test harness, or on the far side of a wire from
+an app nobody is viewing.
+
+> **Formerly `tosijs-schematic`** (deprecated on npm at 0.2.0; renamed
+> before its first external consumer shipped). The old name near-collided
+> with [tosijs-schema](https://github.com/tonioloewald/tosijs-schema), the
+> JSON-schema validation library, and confused readers in practice — an
+> honest hazard of real cross-fertilization: schemas become *contracts*,
+> contracts ride the *map*, and the map is what this package draws. The
+> **exported API keeps its names** (`schematic()`, `SchematicRecord`, …):
+> the drawing is still a schematic in the common-noun sense, and the record
+> format is a multi-producer contract mid-adoption.
+
+## Install
+
+```
+npm add tosijs-floorplan
+```
+
+## Quick start
+
+With [tosijs](https://tosijs.net), the map draws itself — `describe()`
+output is already the record format:
+
+```js
+import { enableAgentInterface } from 'tosijs'
+import { schematicSVG } from 'tosijs-floorplan'
+
+const agent = enableAgentInterface()
+const svg = schematicSVG(agent.describe({ styles: true }))
+```
+
+Without tosijs, emit records yourself — anything that produces them gets
+the renderer and the grammar:
+
+```js
+import { schematicSVG } from 'tosijs-floorplan'
+
+const svg = schematicSVG({
+  wiring: [
+    {
+      tag: 'input',
+      label: 'quantity',
+      value: '3 ⟷ app.qty',
+      bounds: { x: 10, y: 10, width: 160, height: 24 },
+    },
+    {
+      tag: 'button',
+      text: 'submit',
+      on: { click: 'app.submit' },
+      bounds: { x: 180, y: 10, width: 80, height: 24 },
+    },
+  ],
+})
+```
+
+## The record format (the contract)
+
+One flat record per wired element. Producers may add fields beyond these —
+**bound props ride under their own keys** as `"value ⟷ path"` strings.
+
+| field | type | meaning |
+| --- | --- | --- |
+| `tag` | `string` | lowercase tag name (required) |
+| `ref` | `string` | a durable, actionable handle from the producer (survives re-renders — an agent can *act* on it, where an index only *looks up*) |
+| `flags` | `{kind, label, severity?}[]` | computed verdicts about the element (contrast ratios, target sizes, …) |
+| `image` | `string` | data-URL snapshot of inline media, drawn in place — pixels a pure renderer can't obtain |
+| `bounds` | `{x, y, width, height}` | page-coordinate geometry — layout is part of the semantics; zero-size or absent = not drawn |
+| `label` | `string` | the accessible **name** (aria-label, resolved labelledby, `<label>` association, title, alt) |
+| `placeholder` | `string` | the hint — deliberately distinct from `label`: an empty input must never read as content |
+| `text` | `string` | textContent, static (`"foo"`) or bound (`"foo ⟵ path"`) |
+| `href` | `string` | a link's destination — distinct from `text` ("the link *says* X" is not "the link *goes to* Y"). Captions fall back to it only when nothing else names the element; it always rides the **legend** |
+| `value` | `string` | a filled control's value, distinct from `label`/`placeholder` — static (`"3"`) or bound (`"3 ⟷ app.qty"`); the fact that distinguishes an empty form from a filled one |
+| `type` | `string` | input kind when not plain text (`checkbox`, `radio`, `range`, `email`, …) |
+| `checked` | `boolean` | live toggle state |
+| `focused` | `boolean` | holds keyboard focus right now |
+| `invalid` | `boolean` | live ValidityState (or aria-invalid) says invalid |
+| `required` | `boolean` | the field is required |
+| `disabled` | `boolean` | disabled right now |
+| `contentEditable` | `boolean` | an editable region — treated as an input field |
+| `on` | `Record<string, string \| string[]>` | handlers by event type — a path when nameable, `ƒ` (or `ƒ name`) when not |
+| `list` | `{path, idPath?}` | this element renders a collection (drawn as *ground*, not figure) |
+| `structural` | `boolean` | structure, not affordance (headings, landmarks, containers) |
+| `viewportFixed` | `boolean` | rides the viewport (fixed/sticky) — bounds are screen coordinates |
+| `style` | `{background, borderColor, color}` | computed colors, worn when present |
+| `id`, `part`, `role`, `description` | `string` | identity and explanation, passed through to consumers |
+
+**Provenance tokens** (exported as `BOUND_TO_DOM` / `BOUND_TWO_WAY`): a bound
+value reads `"<shown> <arrow> <path>"` — `⟵` means state flows to the DOM
+(display), `⟷` means two-way (a user-writable affordance). A plain string
+with no arrow is a live-but-unbound value.
+
+**The picture is not the whole payload.** The renderer is *allowed to omit*:
+captions and badges below legibility thresholds move to the legend, keyed by
+the stamped index/ref, and facts that never draw well (`href` above all)
+live there always. A consumer of the raster is expected to hold
+`schematic().legend` alongside it — the image says *where* and *which*; the
+legend says *what*.
+
+## The grammar
+
+Every rule is **geometry or ASCII** — hard-won: a single exotic glyph can
+tofu an entire caption run under a rasterizer, and text glyphs are mush at
+checkbox sizes.
+
+| you see | it means |
+| --- | --- |
+| **bold outline** | wired to act (has handlers) |
+| `↔` badge, bottom-right | editable here (two-way binding, or contenteditable) |
+| caption ending `*` | required |
+| **red corner flag**, top-left | invalid *right now* — live ValidityState, the same truth `:invalid` styles |
+| `✕` filling a box / dot in a circle | checkbox / radio state, live |
+| *italic caption* | placeholder hint — **not** content |
+| faded | disabled right now (beats bold: a disabled button is not an affordance) |
+| double outline | keyboard focus — where the user is |
+| faint dotted | structure — including list *containers* (their items are the affordances) |
+| number, top-right, on a white backdrop | the record's index (`index: true`) — the raster form of `data-record`: read it off the image, look up `wiring[n]` |
+| a `ref` (e.g. `@42`), top-right | the producer's **durable, actionable handle** — takes the index slot when present, survives re-renders, rides the group as `data-ref` |
+| colored bars, left edge | computed **verdicts** (`flags`): WCAG contrast failures and friends — error red, warn amber, info gray, first flag's label shown |
+| pixels inside a box | embedded media (`image`: a data URL) — the producer's snapshot of inline `<svg>`/`<canvas>`, drawn in place |
+| a bare box wearing only a stamped number | too small to label legibly — its caption, badges and flags live in the **legend**, matched by that number |
+| single amber bar, left edge | an interactive element below `targetSize` (default 24×24, WCAG 2.5.8; set 44/48 for the touch-target bar) — a usability defect in its own right; the measurement is in the legend |
+| footer strip: "N elements with details in legend" | the image's confession that it isn't the whole map — fetch `schematic().legend` (a machine-readable `<desc>` says the same) |
+
+The target-size audit honours WCAG 2.5.8's **inline exception** as far as
+pure geometry can: a link *with text* is presumed sized by its text and is
+exempt (flagging prose links would fire on every paragraph — a check that
+cries wolf gets ignored, taking the real findings with it). An icon link —
+an `<a>` wrapping an `<svg>`, no text — stays flagged. A producer with DOM
+access can compute the exception *properly* (computed display + parent text
+nodes) and ship the finding via `flags`; a producer flag whose `kind`
+mentions `target` **supersedes** the built-in audit, so the two never
+double-mark.
+
+Captions tell the truth in priority order: a held **value** wins (as
+`label: value` when both are known), an empty control falls back to its
+*hint*, then label, then text. Containers holding other drawn boxes get no
+text-derived caption — their children speak. Captions **wrap** when the box
+affords more than one line — a paragraph that wraps on the real page has
+the same vertical room here — and only truncate (with `…`) when the
+geometry genuinely runs out.
+
+## API
+
+| export | what |
+| --- | --- |
+| `schematic(description, options?)` | the renderer's primary form — returns `{ svg, legend }`: the drawing plus the metadata it could not legibly carry (cramped/truncated/undersized records), keyed by index/ref. **Pair every raster with its legend.** |
+| `schematicSVG(description, options?)` | `schematic().svg` — the string-only form; each `<g>` carries `data-record="<i>"` linking back to `description.wiring[i]` (the image as index) |
+| `rasterizeSVG(svg, {scale})` | SVG → PNG Blob for vision encoders (browser canvas; under bun/node use `@resvg/resvg-js` — rasterize at 2× so labels OCR cleanly) |
+| `boundsOf(element)` | an element's page-coordinate bounds — the natural `within` argument |
+| `BOUND_TO_DOM`, `BOUND_TWO_WAY` | the provenance tokens |
+
+**Options**: `pad`, `minLabelHeight`, `maxCaption`, `fontSize`; `within`
+(a page-coordinate rect — spatial scoping: the viewBox *is* the region);
+`index: true` (stamp record indexes); `targetSize` (the undersized-audit
+floor: 24 default, 44/48 for touch, 0 off); `legendNote: false` (suppress
+the footer strip); `decorate` (below).
+
+## Plugins (EXPERIMENTAL)
+
+`decorate` is the extension seam: called once per drawn record, just before
+its `<g>` closes, with the record, its resolved geometry, and an `emit`
+function. The corner slots already spoken for: **top-left** invalid flag,
+**top-right** index, **bottom-right** `↔` badge, **outline** focus/emphasis.
+Claim empty real estate:
+
+```js
+schematicSVG(map, {
+  decorate({ record, x, y, width, emit }) {
+    if (record.style && contrastRatio(record.style) < 4.5) {
+      emit(`<text x="${x + width / 2}" y="${y - 2}" font-size="6"
+        text-anchor="middle">contrast!</text>`)
+    }
+  },
+})
+```
+
+The first real plugins will shape the successor API — if you build one,
+open an issue.
+
+## Provenance
+
+Extracted from the [tosijs](https://tosijs.net) *one user interface* work:
+one source of truth for state, UI, and AI, where the agent's map derives
+from what the framework already knows. The grammar here was debugged
+against real rasterizers and real assistive-tech semantics — see the tosijs
+docs for the living demos (a todo list whose map redraws itself, and a
+kitchen-sink truth page).
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+/**
+ * tosijs-floorplan — render an agent-surface map as a floorplan SVG.
+ *
+ * (Formerly tosijs-schematic — renamed to stop near-colliding with
+ * tosijs-schema. Exported API names are unchanged.)
+ *
+ * A PURE FUNCTION over plain data: one record per wired element, drawn at
+ * its true geometry, wearing the affordance grammar. No DOM, no framework,
+ * no dependencies — the map travels as JSON, so this runs in the page, in
+ * a headless embodiment, or on the far side of a wire from an app nobody
+ * is viewing.
+ *
+ * The RECORD FORMAT is the contract (see README): tosijs's describe()
+ * produces it, but anything that emits records gets the renderer — and
+ * every consumer inherits the grammar's hard-won rules (geometry over
+ * glyphs, hints are not content, ground is not figure).
+ */
+/** provenance tokens for bound values: "shown ⟵ path" (display-only) and
+ * "shown ⟷ path" (two-way — user-writable). Part of the record format. */
+export declare const BOUND_TO_DOM = "\u27F5";
+export declare const BOUND_TWO_WAY = "\u27F7";
+/**
+ * One wired element, flat. Producers may include fields beyond these —
+ * bound props ride as "value ⟷ path" strings under their own keys.
+ */
+export interface SchematicRecord {
+    tag: string;
+    id?: string;
+    part?: string;
+    role?: string;
+    label?: string;
+    placeholder?: string;
+    type?: string;
+    checked?: boolean;
+    focused?: boolean;
+    invalid?: boolean;
+    required?: boolean;
+    disabled?: boolean;
+    contentEditable?: boolean;
+    description?: string;
+    text?: string;
+    on?: Record<string, string | string[]>;
+    list?: {
+        path: string;
+        idPath?: string;
+    };
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    viewportFixed?: boolean;
+    structural?: boolean;
+    style?: {
+        background: string;
+        borderColor: string;
+        color: string;
+    };
+    /** a DURABLE, actionable handle from the producer (haltija's `@42`) —
+     * survives re-renders where a wiring index doesn't; rendered in the
+     * index slot in preference to the index, and emitted as data-ref */
+    ref?: string;
+    /** computed verdicts about this element (WCAG contrast failures, etc.) —
+     * drawn as severity-colored bars on the LEFT edge (the unclaimed slot),
+     * with the first flag's label */
+    flags?: Array<{
+        kind: string;
+        label: string;
+        severity?: 'info' | 'warn' | 'error';
+    }>;
+    /** pixels a pure renderer can't obtain: a data-URL snapshot of inline
+     * media (serialized <svg>, <canvas>.toDataURL()) drawn IN PLACE — on an
+     * illustration-led page the picture IS the content */
+    image?: string;
+    /** a link's destination — the most actionable fact about a link, and
+     * deliberately distinct from `text` ("the link says X" is not "the link
+     * goes to Y"). Captions fall back to it only when nothing else names the
+     * element; it ALWAYS rides the legend — URLs are the facts most often
+     * too long to draw */
+    href?: string;
+    /** a filled control's value, distinct from label/placeholder — static
+     * ("3") or bound ("3 ⟷ app.qty"). tosijs emits it as a bound prop; the
+     * declared field gives plain-DOM producers the same home */
+    value?: string;
+    [boundProp: string]: unknown;
+}
+/** the map: only `wiring` is read. The named optional fields are the
+ * known producer extras (tosijs's describe() shape) — deliberately NOT an
+ * index signature, which would stop interface-typed producers (TS gives
+ * implicit index signatures to literals, never to interfaces) from
+ * assigning without casts. */
+export interface SchematicDescription {
+    wiring: SchematicRecord[];
+    roots?: unknown;
+    actions?: unknown;
+    exposure?: unknown;
+    contract?: unknown;
+}
+export interface SchematicBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface SchematicOptions {
+    /** padding around the drawn region, px (default 8) */
+    pad?: number;
+    /** boxes shorter than this get no caption (default 14) */
+    minLabelHeight?: number;
+    /** caption length limit (default 36) */
+    maxCaption?: number;
+    /** caption font size, px (default 11) */
+    fontSize?: number;
+    /**
+     * Scope the map SPATIALLY: only records whose bounds intersect this
+     * page-coordinate rect are drawn, and the viewBox IS the rect — the
+     * schematic becomes "this region of the page". Use `boundsOf(element)`
+     * to scope to an element's region; omit for the whole map.
+     */
+    within?: SchematicBounds;
+    /**
+     * Stamp each box with its wiring index (top-right corner) — the raster
+     * form of `data-record`: a vision consumer reads the number off the image
+     * and looks the record up in `description.wiring[n]` — image as legend.
+     */
+    index?: boolean;
+    /**
+     * Interactive elements (handlers or editable, toggles exempt as
+     * user-agent-sized) smaller than this on either axis are flagged
+     * undersized — amber bar + legend fact. Default 24 (WCAG 2.5.8 AA);
+     * raise to 44/48 for the AAA / platform touch-target bar. 0 disables.
+     */
+    targetSize?: number;
+    /** draw the footer strip advertising the legend when it's non-empty
+     * (default true) — the raster must confess what it couldn't carry */
+    legendNote?: boolean;
+    /**
+     * EXPERIMENTAL plugin seam: called once per drawn record, just before
+     * its <g> closes — emit extra SVG into the record's group. The corner
+     * slots already spoken for: top-left = invalid flag, top-right = index,
+     * bottom-right = ↔ badge, outline = focus ring / emphasis. Claim empty
+     * real estate; the first real plugins will shape the successor API.
+     */
+    decorate?: (ctx: {
+        record: SchematicRecord;
+        index: number;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        structural: boolean;
+        emit: (svg: string) => void;
+    }) => void;
+}
+/** what the drawing could not legibly carry, keyed back by index/ref —
+ * the image's companion JSON. Pair every raster with this. */
+export interface SchematicLegendEntry {
+    index: number;
+    ref?: string;
+    tag: string;
+    /** the caption that would have been drawn (or its untruncated form) */
+    caption?: string;
+    editable?: boolean;
+    required?: boolean;
+    invalid?: boolean;
+    disabled?: boolean;
+    flags?: Array<{
+        kind: string;
+        label: string;
+        severity?: 'info' | 'warn' | 'error';
+    }>;
+    /** the link's destination — carried whenever the record has one */
+    href?: string;
+    /** the control's held value (provenance stripped), when the drawing
+     * elided or truncated it */
+    value?: string;
+    /** interactive element below the target-size floor, e.g.
+     * "18×13 — below 24×24 (WCAG 2.5.8)" */
+    undersized?: string;
+}
+export interface SchematicResult {
+    svg: string;
+    legend: SchematicLegendEntry[];
+}
+/**
+ * An element's page-coordinate bounds (the same space describe() records) —
+ * the natural `within` argument for a region-scoped schematic.
+ */
+export declare const boundsOf: (element: Element) => SchematicBounds;
+export declare const schematic: (description: SchematicDescription, options?: SchematicOptions) => SchematicResult;
+/** the string-only form — schematic().svg, kept for drop-in compatibility */
+export declare const schematicSVG: (description: SchematicDescription, options?: SchematicOptions) => string;
+/**
+ * Rasterize an SVG string to a PNG Blob — the vision-encoder form of the map
+ * (rasterize at 2× so labels land large enough to OCR near-losslessly).
+ *
+ * Browser-only by design: it uses Image + canvas, which keeps tosijs at zero
+ * dependencies. Under bun/node, use `@resvg/resvg-js` directly instead:
+ *
+ *     const { Resvg } = await import('@resvg/resvg-js')
+ *     const png = new Resvg(svg, { fitTo: { mode: 'zoom', value: 2 } })
+ *       .render().asPng()
+ */
+export declare const rasterizeSVG: (svg: string, options?: {
+    scale?: number;
+}) => Promise<Blob>;