@knowvah/dot-engine 0.1.0

package/src/gvc/viewport.ts

@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: EPL-2.0
+//
+// Drawing-scale (viewport fit) for the `size=` graph attribute. Ports the parse
+// (getdoubles2ptf) and the zoom factor Z (init_job_viewport) so SVG output is
+// fitted to the requested size, exactly as native `dot` does. The zoom is
+// carried by the SVG group transform, never by the coordinates (decisions D4).
+//
+// Also ports the `pad=` graph-attribute parse (init_gvc's attr read +
+// init_job_pad's fallback), threaded into the fit computation exactly as C's
+// init_job_viewport does (job->bb = graph bb expanded by job->pad on every
+// side before the size= fit is computed).
+//
+// Also ports the `margin=` graph-attribute parse (init_gvc's attr read +
+// init_job_margin's fallback). Unlike pad, margin does NOT feed the size=
+// fit; it only affects job.width/job.height and the page group translate
+// (device.ts render() / svg-graph.ts emitSvgTag+svgBeginPage), applied AFTER
+// the size= zoom Z (matching C's init_job_margin -> ... -> init_job_pagination
+// call order, emit.c:4290-4294).
+//
+// @see lib/common/input.c:476 getdoubles2ptf
+// @see lib/common/emit.c:3356 init_job_viewport
+// @see lib/common/emit.c:3230-3251 init_gvc (pad attr read)
+// @see lib/common/emit.c:3290-3304 init_job_pad
+// @see lib/common/emit.c:3229-3239 init_gvc (margin attr read)
+// @see lib/common/emit.c:3309-3331 init_job_margin
+
+import type { Box, Point } from '../model/geom.js';
+import { POINTS_PER_INCH } from '../model/geom.js';
+import { SVG_PAD, SVG_MARGIN } from '../render/svg-helpers.js';
+import type { Graph } from '../model/graph.js';
+import { cround } from '../common/arith.js';
+
+/** Parsed `size=` drawing size in points, plus the *filled* flag. */
+export interface DrawingSize {
+  x: number;
+  y: number;
+  filled: boolean;
+}
+
+/** A C-`sscanf("%lf")`-style float token (sign, digits, optional exponent). */
+const FLOAT = '[-+]?[0-9.]+(?:[eE][-+]?[0-9]+)?';
+/** sscanf("%lf,%lf%c"): two floats (whitespace-tolerant) then the next char. */
+const SIZE_XY_RE = new RegExp(`^\\s*(${FLOAT})\\s*,\\s*(${FLOAT})(.?)`);
+/** sscanf("%lf%c"): a lone float (square box) then the next char. */
+const SIZE_X_RE = new RegExp(`^\\s*(${FLOAT})(.?)`);
+/** sscanf("%lf,%lf") without the trailing-char capture used by `pad=`. */
+const PAD_XY_RE = new RegExp(`^\\s*(${FLOAT})\\s*,\\s*(${FLOAT})`);
+/** sscanf("%lf") without the trailing-char capture used by `pad=`. */
+const PAD_X_RE = new RegExp(`^\\s*(${FLOAT})`);
+
+/** Inches→points exactly as C's POINTS macro: ROUND(in * 72). @see geom.h:62 */
+function toPoints(inches: number): number {
+  return cround(inches * POINTS_PER_INCH);
+}
+
+/**
+ * Port of getdoubles2ptf(g, "size", …) for the `size=` attribute: parse
+ * `"x,y"` (or a lone `"x"` meaning square), convert inches→points, and treat a
+ * trailing `!` as the *filled* flag. Returns null when `size` is absent or
+ * non-positive (Z stays 1 — D5).
+ * @see lib/common/input.c:476 getdoubles2ptf
+ */
+export function parseDrawingSize(raw: string | undefined): DrawingSize | null {
+  if (raw === undefined) return null;
+  const xy = SIZE_XY_RE.exec(raw);
+  if (xy) {
+    const xf = Number(xy[1]);
+    const yf = Number(xy[2]);
+    if (xf > 0 && yf > 0) return { x: toPoints(xf), y: toPoints(yf), filled: xy[3] === '!' };
+  }
+  const x = SIZE_X_RE.exec(raw);
+  if (x) {
+    const xf = Number(x[1]);
+    if (xf > 0) return { x: toPoints(xf), y: toPoints(xf), filled: x[2] === '!' };
+  }
+  return null;
+}
+
+/**
+ * Port of the `pad=` graph-attribute parse: init_gvc reads it via
+ * `sscanf(p, "%lf,%lf", &xf, &yf)` (2 values matched → both axes
+ * independently; 1 value → y = x; 0 matched — attr absent or unparsable —
+ * leaves `graph_sets_pad` false) and init_job_pad falls back to the SVG
+ * plugin's `default_pad` (this port's only renderer) when unset, which is
+ * numerically identical to `DEFAULT_GRAPH_PAD` (4pt) — so the two C fallback
+ * branches collapse to the same constant here (`SVG_PAD`).
+ *
+ * Unlike `size=`, pad values are NOT rounded (`xf * POINTS_PER_INCH`
+ * directly — no `POINTS()` macro) and are not required to be positive.
+ *
+ * @see lib/common/emit.c:3241-3251 init_gvc (pad attr read)
+ * @see lib/common/emit.c:3290-3304 init_job_pad (fallback)
+ */
+export function parseGraphPad(raw: string | undefined): Point {
+  if (raw !== undefined) {
+    const xy = PAD_XY_RE.exec(raw);
+    if (xy) {
+      return { x: Number(xy[1]) * POINTS_PER_INCH, y: Number(xy[2]) * POINTS_PER_INCH };
+    }
+    const x = PAD_X_RE.exec(raw);
+    if (x) {
+      const v = Number(x[1]) * POINTS_PER_INCH;
+      return { x: v, y: v };
+    }
+  }
+  return { x: SVG_PAD, y: SVG_PAD };
+}
+
+/**
+ * Port of the `margin=` graph-attribute parse: init_gvc reads it via the same
+ * `sscanf(p, "%lf,%lf", &xf, &yf)` shape as `pad=` (2 values matched → both
+ * axes independently; 1 value → y = x; 0 matched leaves `graph_sets_margin`
+ * false) and init_job_margin falls back to the SVG plugin's
+ * `device_features_svg.default_margin` ({0,0}) when unset — the
+ * `GVRENDER_PLUGIN` branch of init_job_margin's fallback switch (the
+ * PCL/MIF/etc. print-margin and generic embed-margin branches never apply to
+ * this port's only renderer).
+ *
+ * This is a distinct attribute/mechanism from the already-ported per-node and
+ * per-cluster `margin=` (shape internal label margin) — do not conflate.
+ * Unlike `size=`, margin values are NOT rounded (`xf * POINTS_PER_INCH`
+ * directly) and are not required to be positive, matching `pad=`.
+ *
+ * @see lib/common/emit.c:3229-3239 init_gvc (margin attr read)
+ * @see lib/common/emit.c:3309-3331 init_job_margin (fallback)
+ */
+export function parseGraphMargin(raw: string | undefined): Point {
+  if (raw !== undefined) {
+    const xy = PAD_XY_RE.exec(raw);
+    if (xy) {
+      return { x: Number(xy[1]) * POINTS_PER_INCH, y: Number(xy[2]) * POINTS_PER_INCH };
+    }
+    const x = PAD_X_RE.exec(raw);
+    if (x) {
+      const v = Number(x[1]) * POINTS_PER_INCH;
+      return { x: v, y: v };
+    }
+  }
+  return { x: SVG_MARGIN, y: SVG_MARGIN };
+}
+
+/**
+ * Port of `mapbool` for the `landscape=` branch only: falsy spellings →
+ * false, truthy spellings → true, else `atoi(s) != 0`. Kept local (not imported
+ * from layout/dot) to avoid pulling the layout engine into this leaf module.
+ * @see lib/common/utils.c:mapbool
+ */
+function landscapeMapbool(s: string): boolean {
+  const v = s.toLowerCase();
+  if (v === '' || v === 'false' || v === 'no') return false;
+  if (v === 'true' || v === 'yes') return true;
+  return Number.parseInt(s, 10) !== 0;
+}
+
+/**
+ * Port of the landscape detection in `input.c`: `rotate=90`, or
+ * `orientation` starting with `l`/`L`, or a truthy `landscape`. Each branch is
+ * mutually exclusive in the same precedence as C (rotate wins over orientation
+ * wins over landscape). Returns false when no rotation attribute is present.
+ * This flag is **emit-only** — it drives `job.rotation`, never layout (ADR-1).
+ * @see lib/common/input.c:699-704
+ */
+export function parseLandscape(g: Graph): boolean {
+  const rotate = g.attrs.get('rotate');
+  if (rotate !== undefined) return Number.parseInt(rotate, 10) === 90;
+  const orientation = g.attrs.get('orientation');
+  if (orientation !== undefined) {
+    return orientation[0] === 'l' || orientation[0] === 'L';
+  }
+  const landscape = g.attrs.get('landscape');
+  if (landscape !== undefined) return landscapeMapbool(landscape);
+  return false;
+}
+
+/**
+ * Whether the drawing needs scaling to fit `size`: too big in either axis, or
+ * (when *filled*) too small in both. @see lib/common/emit.c:3380-3382
+ */
+function drawingNeedsFit(size: DrawingSize, szx: number, szy: number): boolean {
+  const tooBig = size.x < szx || size.y < szy;
+  const fillsUp = size.filled && size.x > szx && size.y > szy;
+  return tooBig || fillsUp;
+}
+
+/**
+ * Port of init_job_viewport's zoom factor Z (emit.c:3375-3384). When the user
+ * gave a `size=`, fit the drawing (size `sz` = bb plus pad, in points) into it.
+ * Z stays 1.0 otherwise, leaving every non-`size` byte unchanged (D5). SVG
+ * carries Z via the group transform, not the coordinates (D4). `pad` is the
+ * resolved `job.pad` (parseGraphPad), matching C's `job->bb = bb ± job->pad`
+ * before `sz = job->bb.UR - job->bb.LL` (emit.c:3363-3368).
+ * @see lib/common/emit.c:3356 init_job_viewport
+ */
+export function initJobViewportZoom(bb: Box, size: DrawingSize | null, pad: Point): number {
+  if (size === null || size.x <= 0.001 || size.y <= 0.001) return 1.0;
+  // sz = bb extent including the pad the SVG emit adds on every side.
+  let szx = bb.ur.x - bb.ll.x + 2 * pad.x;
+  let szy = bb.ur.y - bb.ll.y + 2 * pad.y;
+  if (szx <= 0.001) szx = size.x;
+  if (szy <= 0.001) szy = size.y;
+  if (drawingNeedsFit(size, szx, szy)) return Math.min(size.x / szx, size.y / szy);
+  return 1.0;
+}

package/src/index.ts

@@ -0,0 +1,165 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Public entry point for the graphviz-ts library.
+ *
+ * Wires together the parser, layout engines, SVG renderer, and GVC
+ * orchestration layer into a single renderSvg function.
+ *
+ * @see lib/gvc/gvc.h
+ */
+
+import { parse } from './parser/index.js';
+import { RenderError } from './errors.js';
+import type { GvError, RenderResult } from './errors.js';
+import type { EngineName } from './gvc/context.js';
+import { render as deviceRender } from './gvc/device.js';
+import { createDefaultContext } from './gvc/default-context.js';
+
+/**
+ * Duck-type a thrown value as a {@link GvError}: an object carrying a string
+ * `type` and a string `code`. Covers `ParseError`, `HtmlParseError`, and
+ * `RenderError` without per-subclass `instanceof`.
+ */
+function isGvErrorLike(err: unknown): err is GvError {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    typeof (err as { type?: unknown }).type === 'string' &&
+    typeof (err as { code?: unknown }).code === 'string'
+  );
+}
+
+/* v8 ignore start -- defensive normalizers for non-Error / genuinely-unknown
+   throws. Unreachable via the public API (renderSvg normalizes every throw to
+   GvError-like; parse only throws ParseError) but mandated by ADR-3 and the
+   render wrap. */
+function messageOf(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+function renderErrorFromUnknown(err: unknown): RenderError {
+  return new RenderError(messageOf(err), 'GENERIC_ERROR');
+}
+/* v8 ignore stop */
+
+/**
+ * Normalize any thrown value to a plain, JSON-serializable {@link GvError}
+ * (no stack). Structured throws are copied; unknown throws → `GENERIC_ERROR`.
+ */
+function classifyError(err: unknown): GvError {
+  /* v8 ignore next -- the unknown-throw fallback is unreachable via the public
+     API (see helpers above); ADR-3 still mandates it. */
+  const gv: GvError = isGvErrorLike(err) ? err : renderErrorFromUnknown(err);
+  const out: GvError = {
+    type: gv.type, code: gv.code, message: gv.message, friendlyMessage: gv.friendlyMessage,
+  };
+  if (gv.location !== undefined) out.location = gv.location;
+  if (gv.expected !== undefined) out.expected = gv.expected;
+  return out;
+}
+
+/**
+ * Render a DOT-language string to SVG using the specified layout engine.
+ *
+ * Always throws a value implementing {@link GvError}: parse failures throw
+ * `ParseError`; layout/render failures surface as `RenderError`
+ * (`RENDER_ERROR`).
+ *
+ * @remarks
+ * Security: when `dotSource` is untrusted, treat the returned SVG as
+ * attacker-controlled markup. Attribute values are XML-escaped (no element or
+ * attribute breakout), but URL schemes and resource origins in `href`/`URL`/
+ * `image`/`stylesheet` are passed through unfiltered, matching native Graphviz.
+ * Embedding pages should apply a Content-Security-Policy (or sanitize the
+ * markup) — see the "Security" section of the README.
+ *
+ * @param dotSource - DOT-language graph source
+ * @param engine    - layout engine name ({@link EngineName}): a built-in
+ *                    ('dot', 'neato', 'fdp', 'sfdp', 'circo', 'twopi',
+ *                    'osage', 'patchwork') or any custom-registered name
+ * @returns SVG string
+ * @throws ParseError if dotSource is not valid DOT
+ * @throws RenderError if layout or rendering fails
+ */
+export function renderSvg(dotSource: string, engine: EngineName): string {
+  const ctx = createDefaultContext();
+  try {
+    // parse() is inside the try so any non-ParseError throw (e.g. a raw
+    // RangeError from stack exhaustion) is still normalized to a GvError,
+    // honoring the "always throws a value implementing GvError" contract.
+    const g = parse(dotSource);
+    ctx.layout(g, engine);
+    const svg = deviceRender(ctx, g, 'svg');
+    // C: gvFreeLayout runs after gvRenderJobs; cleanup is destructive.
+    ctx.freeLayout(g, engine);
+    return svg;
+  } catch (err: unknown) {
+    // A render-stage throw already implementing GvError (e.g. HtmlParseError)
+    // is re-surfaced unchanged; only genuinely-unknown throws become RENDER_ERROR.
+    /* v8 ignore next -- current engines don't throw a GvError-like value here */
+    if (isGvErrorLike(err)) throw err;
+    throw new RenderError(messageOf(err), 'RENDER_ERROR');
+  }
+}
+
+/**
+ * Result-style render: returns `{ svg }` on success or `{ errors: [one] }` on
+ * the first failure (svg XOR errors). Errors are plain JSON-serializable
+ * {@link GvError} data objects.
+ *
+ * @remarks
+ * Security: same untrusted-input caveat as {@link renderSvg} — the returned
+ * `svg` is attacker-controlled markup for untrusted `dotSource`; apply a CSP or
+ * sanitize before embedding. See the README "Security" section.
+ */
+export function tryRenderSvg(dotSource: string, engine: EngineName): RenderResult {
+  try {
+    return { svg: renderSvg(dotSource, engine) };
+  } catch (err: unknown) {
+    return { errors: [classifyError(err)] };
+  }
+}
+
+export { parse } from './parser/index.js';
+export { ParseError } from './parser/index.js';
+export { RenderError } from './errors.js';
+export type {
+  GvError,
+  GvErrorType,
+  GvErrorCode,
+  GvExpectation,
+  RenderResult,
+} from './errors.js';
+export { setImageSizer } from './gvc/usershape.js';
+export type { ImageSizer } from './common/htmltable-types.js';
+export { setImageResolver } from './gvc/image-resolver.js';
+export type { ImageResolver } from './gvc/image-resolver.js';
+
+// Text measurement: install a custom measurer (deterministic tests, or a
+// host-faithful Node measurer wired from node-canvas). The library auto-resolves
+// browser canvas → Node LUT by default and never imports `canvas` itself (zero
+// runtime deps). @see plans/fix-xcoord-position/DESIGN.md
+export { setTextMeasurer, getTextMeasurer } from './common/textmeasure-factory.js';
+export {
+  CanvasTextMeasurer, EstimateTextMeasurer, LutTextMeasurer,
+} from './common/textmeasure.js';
+export type { TextMeasurer, TextSize, TextVariantFlags } from './common/textmeasure.js';
+export { GvcContext } from './gvc/context.js';
+export type { BuiltinEngine, EngineName } from './gvc/context.js';
+
+// Lower-level renderer-pipeline primitive: render a graph against a
+// caller-built `GvcContext`. The root `render` name is taken by the new
+// public `render(g, format, opts?)` (collision resolution below), so this
+// is namespaced as `renderWithContext` to preserve the GvcContext workflow.
+export { render as renderWithContext } from './gvc/device.js';
+
+// Discoverable root re-exports of the api + render surfaces (ADR-2): root
+// `graphviz-ts` exposes everything from `graphviz-ts/api` and
+// `graphviz-ts/render` for one-import discoverability.
+//
+// Collision resolution: the root `render` is the new public
+// `render(g, format, opts?)` from `./render`. The low-level
+// `render(ctx, g, format)` is re-exported as `renderWithContext` (above)
+// rather than `render`. See decisions.md ADR-5 and the decision journal.
+export * from './api/index.js';
+export * from './render/index.js';

package/src/label/index.ts

@@ -0,0 +1,302 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * R-tree public API: open/close/insert/search.
+ * @see label/index.h
+ * @see label/index.c
+ */
+
+import { type Rect, overlap, combineRect, NUMDIMS } from './rectangle.js';
+import {
+  NODECARD,
+  type Branch,
+  type Node,
+  type SplitQ,
+  rTreeNewNode,
+  nodeCover,
+  pickBranch,
+  addBranch,
+  disconnectBranch,
+  makeSplitQ,
+} from './node.js';
+
+// Import split-q.ts for its side-effect: registerSplitNode().
+// Without this import addBranch will throw when a split is needed.
+import './split-q.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * An R-tree leaf: the bounding rect and the caller-supplied data pointer.
+ *
+ * In C this is `Leaf_t { Rect_t rect; void *data; }` and a leaf branch is
+ * cast directly to Leaf_t* — `branch[i].child` holds the data pointer while
+ * `branch[i].rect` is the bounding rectangle.  We replicate that layout here.
+ *
+ * @see label/index.h:Leaf_t
+ */
+export interface Leaf {
+  rect: Rect;
+  /** Caller-supplied opaque data (C: void *). */
+  data: unknown;
+}
+
+/**
+ * R-tree: root node plus the SplitQ scratchpad.
+ * @see label/index.h:struct RTree
+ */
+export interface RTree {
+  root: Node | null;
+  split: SplitQ;
+}
+
+// ---------------------------------------------------------------------------
+// Internal leaf-list helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Leaf list node — a singly-linked cons cell.
+ *
+ * C iterates with `for (LeafList_t *ilp = llp; ilp; ilp = ilp->next)`.
+ * Each new hit is prepended (list-cons), so within a leaf node the order
+ * is REVERSED relative to branch-slot scan order (slot 0 is last in list).
+ * Between subtrees of an internal node, child results are appended to the
+ * tail in child-slot order.
+ *
+ * rTreeSearch returns a plain Leaf[] that reproduces this exact iteration
+ * sequence: within each leaf, hits appear in reverse slot order; across
+ * internal-node children, results are in forward slot order.
+ *
+ * @see label/index.c:LeafList_t
+ */
+interface LeafListNode {
+  leaf: Leaf;
+  next: LeafListNode | null;
+}
+
+/** Prepend a new hit to the list — mirrors RTreeLeafListAdd. */
+function leafListAdd(head: LeafListNode | null, leaf: Leaf): LeafListNode {
+  return { leaf, next: head };
+}
+
+/** Append list `tail` to the end of `head`; returns the new head. */
+function leafListAppend(
+  head: LeafListNode | null,
+  tail: LeafListNode | null,
+): LeafListNode | null {
+  if (!head) return tail;
+  if (!tail) return head;
+  let cur: LeafListNode = head;
+  while (cur.next) cur = cur.next;
+  cur.next = tail;
+  return head;
+}
+
+/** Convert a linked list to an array, preserving iteration order. */
+function leafListToArray(head: LeafListNode | null): Leaf[] {
+  const result: Leaf[] = [];
+  for (let cur = head; cur !== null; cur = cur.next) {
+    result.push(cur.leaf);
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Allocate and initialise a new R-tree.
+ * @see label/index.c:RTreeOpen
+ */
+export function rTreeOpen(): RTree {
+  return { root: rTreeNewIndex(), split: makeSplitQ() };
+}
+
+/**
+ * Recursively free all nodes.  In GC'd TS the objects will be collected
+ * anyway; this mirrors the C traversal so behaviour is faithful.
+ * @see label/index.c:RTreeClose2
+ */
+function rTreeClose2(n: Node): void {
+  if (n.level > 0) {
+    for (let i = 0; i < NODECARD; i++) {
+      if (!n.branch[i].child) continue;
+      rTreeClose2(n.branch[i].child as Node);
+      disconnectBranch(n, i);
+    }
+  } else {
+    for (let i = 0; i < NODECARD; i++) {
+      if (!n.branch[i].child) continue;
+      disconnectBranch(n, i);
+    }
+  }
+}
+
+/**
+ * Close (free) the R-tree.
+ * In GC'd TS this is a no-op in practice, but we walk and clear the tree
+ * faithfully to mirror the C version and release references eagerly.
+ * @see label/index.c:RTreeClose
+ */
+export function rTreeClose(rtp: RTree): void {
+  if (rtp.root) {
+    rTreeClose2(rtp.root);
+    rtp.root = null;
+  }
+}
+
+/**
+ * Make a new empty index (single leaf node at level 0).
+ * @see label/index.c:RTreeNewIndex
+ */
+export function rTreeNewIndex(): Node {
+  const x = rTreeNewNode();
+  x.level = 0; // leaf
+  return x;
+}
+
+// ---------------------------------------------------------------------------
+// Search
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursive search helper.
+ *
+ * Leaf-list construction mirrors C exactly:
+ *   - Leaf node: `RTreeLeafListAdd` prepends each hit → reverse slot order
+ *     within a leaf.
+ *   - Internal node: each child's result list is appended to the tail of
+ *     the accumulator → child results in forward slot order.
+ *
+ * @see label/index.c:RTreeSearch
+ */
+/** Search internal node: recurse into overlapping children, append results. */
+function searchInternal(n: Node, r: Rect): LeafListNode | null {
+  let llp: LeafListNode | null = null;
+  for (let i = 0; i < NODECARD; i++) {
+    if (n.branch[i].child && overlap(r, n.branch[i].rect)) {
+      const tlp = rTreeSearchRec(n.branch[i].child as Node, r);
+      llp = leafListAppend(llp, tlp);
+    }
+  }
+  return llp;
+}
+
+/** Search leaf node: prepend each matching branch (reverse slot order). */
+function searchLeaf(n: Node, r: Rect): LeafListNode | null {
+  let llp: LeafListNode | null = null;
+  for (let i = 0; i < NODECARD; i++) {
+    if (n.branch[i].child && overlap(r, n.branch[i].rect)) {
+      llp = leafListAdd(llp, { rect: n.branch[i].rect, data: n.branch[i].child });
+    }
+  }
+  return llp;
+}
+
+function rTreeSearchRec(n: Node, r: Rect): LeafListNode | null {
+  return n.level > 0 ? searchInternal(n, r) : searchLeaf(n, r);
+}
+
+/**
+ * Search the index for all data rectangles overlapping `r`.
+ *
+ * Returns a Leaf[] whose iteration order matches C's LeafList_t traversal:
+ * within each leaf node hits are in reverse branch-slot order (list-cons
+ * prepend); across internal-node children results are in forward slot order.
+ *
+ * @see label/index.c:RTreeSearch
+ */
+export function rTreeSearch(rtp: RTree, n: Node, r: Rect): Leaf[] {
+  void rtp; // rtp unused in search (matches C signature for API parity)
+  return leafListToArray(rTreeSearchRec(n, r));
+}
+
+// ---------------------------------------------------------------------------
+// Insert
+// ---------------------------------------------------------------------------
+
+/** Bundled insert context — reduces per-call param count. */
+interface InsertCtx {
+  rtp: RTree;
+  r: Rect;
+  data: unknown;
+  level: number;
+}
+
+/** Insert2: handle n.level > ctx.level (descend, propagate split). */
+function insert2Descend(
+  ctx: InsertCtx, n: Node, newOut: { value: Node | null },
+): number {
+  const n2Out: { value: Node | null } = { value: null };
+  const i = pickBranch(ctx.r, n);
+  if (!rTreeInsert2(ctx, n.branch[i].child as Node, n2Out)) {
+    n.branch[i].rect = combineRect(ctx.r, n.branch[i].rect);
+    return 0;
+  }
+  n.branch[i].rect = nodeCover(n.branch[i].child as Node);
+  const b: Branch = { rect: nodeCover(n2Out.value as Node), child: n2Out.value };
+  return addBranch(ctx.rtp, b, n, newOut);
+}
+
+/**
+ * Recursive insert helper.
+ * Returns 0 if node not split; 1 + sets newOut.value if split.
+ * @see label/index.c:RTreeInsert2
+ */
+function rTreeInsert2(
+  ctx: InsertCtx, n: Node, newOut: { value: Node | null },
+): number {
+  if (n.level > ctx.level) return insert2Descend(ctx, n, newOut);
+  if (n.level === ctx.level) {
+    return addBranch(ctx.rtp, { rect: ctx.r, child: ctx.data as Node }, n, newOut);
+  }
+  return 0; // should never happen
+}
+
+/** Validate rect: low side must be <= high side per dimension. */
+function validateRect(r: Rect): void {
+  for (let i = 0; i < NUMDIMS; i++) {
+    if (r.boundary[i] > r.boundary[NUMDIMS + i]) {
+      throw new Error('rTreeInsert: rect low > high');
+    }
+  }
+}
+
+/** Grow a new root after the old root was split into oldRoot + sibling. */
+function growRoot(rtp: RTree, sibling: Node): void {
+  const newRoot = rTreeNewNode();
+  newRoot.level = (rtp.root as Node).level + 1;
+  addBranch(rtp, { rect: nodeCover(rtp.root as Node), child: rtp.root }, newRoot, { value: null });
+  addBranch(rtp, { rect: nodeCover(sibling), child: sibling }, newRoot, { value: null });
+  rtp.root = newRoot;
+}
+
+/**
+ * Insert a data rectangle into the index.
+ * Returns 1 if root was split, 0 otherwise. Updates rtp.root on split.
+ * @see label/index.c:RTreeInsert
+ */
+export function rTreeInsert(rtp: RTree, r: Rect, data: unknown): number {
+  validateRect(r);
+  const newNodeOut: { value: Node | null } = { value: null };
+  const ctx: InsertCtx = { rtp, r, data, level: 0 };
+  if (!rTreeInsert2(ctx, rtp.root as Node, newNodeOut)) return 0;
+  growRoot(rtp, newNodeOut.value as Node);
+  return 1;
+}
+
+/**
+ * Free a LeafList.  In GC'd TypeScript this is a documented no-op stub;
+ * the caller may discard the Leaf[] returned by rTreeSearch without calling
+ * this function.
+ *
+ * Kept as a named export so callers ported from C can call it without change.
+ *
+ * @see label/index.c:RTreeLeafListFree
+ */
+export function rTreeLeafListFree(_leaves: Leaf[]): void {
+  // No-op: GC handles deallocation.
+}