@quran.ws/engine 0.1.0 → 0.3.1

package/docs/LITE-PASSAGES.md

@@ -0,0 +1,54 @@
+# Lite passages
+
+`@quran.ws/engine/lite/passage` lays out a contiguous range of complete ayahs in JavaScript. It loads no Wasm. Words keep their original outlines, dots and reading signs; the layout moves them onto rows of the requested width. It includes every selected ayah medallion and the relevant division and sajdah marks. Page numbers, running heads, surah banners and unnumbered basmalahs belong to the printed page and are not part of an excerpt.
+
+This is an optional entry point. Importing `@quran.ws/engine/lite` alone does not load the passage layout. It is not a replacement for the full engine's page reader, zoom control, selection or styles.
+
+```js
+import { decodeGeometry } from '@quran.ws/engine/lite'
+import { QvpPassage } from '@quran.ws/engine/lite/passage'
+
+const response = await fetch('https://cdn.quran.ws/qvp/v0.4.0/042.qvp')
+if (!response.ok) throw new Error(`Page: HTTP ${response.status}`)
+const page = decodeGeometry(await response.arrayBuffer())
+const passage = new QvpPassage([page], { surah: 2, from: 255 })
+const layout = passage.layout({ width: 366, scale: 0.9 })
+
+const ratio = Math.max(2, window.devicePixelRatio || 1)
+canvas.width = Math.ceil(layout.width * ratio)
+canvas.height = Math.ceil(layout.height * ratio)
+canvas.style.width = `${layout.width}px`
+canvas.style.height = `${layout.height}px`
+passage.draw(canvas.getContext('2d'), layout, { pixelRatio: ratio, ink: '#231f20' })
+```
+
+## Inputs and results
+
+`new QvpPassage(pages, {surah, from, to = from})` accepts the geometry returned by `decodeGeometry()`, not `QvpLitePage`. Supply every page containing the requested range. Pages may arrive in any order. Missing ayahs, incomplete fragments, duplicate pages and passages over 4,096 words throw rather than show partial Quran text. The app decides which pages to fetch and how many ayahs to show; the module does not fetch anything. `passage.ayahs` contains `{surah, ayah, text}` in reading order, with the text from the page's own word records.
+
+`passage.layout({width, scale = 1, lineSpacing = 1, padding = 2, align = 'right'})` returns:
+
+- `width`, `height`, `scale`: CSS-pixel canvas dimensions and the actual scale from page units. Scale shrinks only if a whole word and its attached signs would exceed the width.
+- `rows`: each row's `box` and `baseline` in CSS pixels.
+- `words`: `{surah, ayah, word, row, box}`. A box includes signs that travel with that word.
+- `ayahs`: `{surah, ayah, text, box}`, suitable for an accessible text layer or scrolling to a cited ayah.
+
+`align` accepts `right` or `center`. `lineSpacing` is a multiplier, at least 1. The rows may need more room for tall ink. The layout balances row lengths without stretching the gaps; it is intentionally not the full page reader's fitted breaking or zoom policy. Layout is independent of canvas resolution and can run without the DOM.
+
+`passage.draw(context, layout, {pixelRatio = 1, ink = '#231f20'})` draws the layout made by that passage. It saves and restores the context but does not clear or resize its canvas. The caller supplies the backing ratio and caps the canvas dimensions or pixel budget as needed. Drawing requires Canvas2D and `Path2D`; decoding and layout do not.
+
+## Geometry and lifetime
+
+The decoder now exposes `lines`, `ayahs`, `decorations`, word `text`, and path `kind`, `mark` and `family` alongside the existing geometry. Indices are zero-based. Optional decoration and line indices are -1 when absent. Empty line/ayah/decoration bounds are `null`. The QVP wire format is unchanged.
+
+The passage module measures outlines in thin bands rather than separating word bounding boxes. It keeps deeply interlocked adjacent words at their printed relative position. All pages share the same band height, so a range spanning a page boundary can form one row. Curves are sampled only to measure spacing: drawing uses their unchanged original operations. The reference Rust engine supplies fixtures for line spacing and ink clearance; the clearance test allows 0.75 page units because the Rust reader's band height varies with each page while the passage bands must be shared across pages.
+
+Ayah medallions and sajdah signs travel with the word that closes their ayah. A division mark travels with the word it opens. A sajdah stroke belongs to the words geometrically underneath it, which can be in an earlier ayah than the closing sign. If those words wrap, the stroke is drawn on each affected row; only that stroke is stretched horizontally.
+
+Decoded pages are immutable inputs. Preparation is bounded per page to two million sample points and 32,768 allocated measurement bands; exceeding either limit throws. This prevents extreme coordinates or repeated geometry from expanding an otherwise bounded QVP file into unbounded work or memory. The complete 604-page dataset is checked against these limits. Preparation and Canvas paths use weak caches keyed by those pages. Keep a bounded app-owned page cache; dropping a passage, its layouts and unused pages releases the associated data. Reuse the passage when its container changes width. Do not lay it out on every scroll event.
+
+A canvas is not an accessible text document. Supply a Unicode text layer for screen readers and copying. The module's text is optional to the host; an app may keep its existing verified text corpus. Theme changes require drawing with a new ink colour, not recomputing the layout.
+
+## Checks
+
+`pnpm run test:lite` runs synthetic tests and the Rust codec fixture without data. With `dist/pages/` present, it also checks all 604 pages at three widths, all ayah medallions, a range spanning pages and the Rust-generated ink measurements. `scripts/check.sh gates` requires those data tests. `scripts/gen-conformance.sh` regenerates `conformance/lite-passage-metrics.json` from Rust; no Wasm is needed by passage consumers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quran.ws/engine",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "Rendering engine for interactive muṣḥaf pages: layout, hit-testing, styling and search over the QVP page format, as wasm with a Canvas2D wrapper.",
   "license": "MIT",
   "homepage": "https://quran.ws/blocks/quran-engine",
@@ -31,6 +31,8 @@
       "import": "./web/index.mjs",
       "require": "./web/index.cjs"
     },
+    "./lite": "./web/lite.mjs",
+    "./lite/passage": "./web/lite-passage.mjs",
     "./qvp.js": "./web/qvp.js",
     "./qvp_ffi.wasm": "./web/qvp_ffi.wasm",
     "./package.json": "./package.json"
@@ -40,6 +42,11 @@
   "files": [
     "web/index.mjs",
     "web/index.cjs",
+    "web/lite.mjs",
+    "web/lite-path.mjs",
+    "web/lite-passage.mjs",
+    "web/lite-passage-geometry.mjs",
+    "docs/LITE-PASSAGES.md",
     "web/qvp.js",
     "web/qvp_ffi.wasm",
     "docs/API.md",
@@ -56,6 +63,7 @@
   "scripts": {
     "build:wasm": "cargo build -p qvp-ffi --release --target wasm32-unknown-unknown && cp target/wasm32-unknown-unknown/release/qvp_ffi.wasm web/qvp_ffi.wasm",
     "prepack": "npm run build:wasm",
-    "test": "node web/smoke.mjs"
+    "test": "node web/smoke.mjs && node web/lite.test.mjs && node web/lite-passage.test.mjs",
+    "test:lite": "node web/lite.test.mjs && node web/lite-passage.test.mjs"
   }
 }

package/web/index.mjs

@@ -11,7 +11,7 @@ if (!QVP) throw new Error('@quran.ws/engine: qvp.js did not define globalThis.QV
 
 export const {
   QvpEngine, QvpPage, QvpAtlas, CanvasRenderer,
-  Sel, T, KIND, FAMILY, CATEGORY, DECO, FORM, LAYER, MARK, MARKS, NONE,
+  Sel, T, KIND, FAMILY, CATEGORY, DECORATION, FORM, LAYER, NAMES_TABLE, DEFAULTS, NONE,
   css, rgba, parseTarget,
 } = QVP;
 

package/web/lite-passage-geometry.mjs

@@ -0,0 +1,174 @@
+// Measure passage ink; Canvas still draws the untouched curves, not these samples.
+const prepared_pages = new WeakMap()
+const band_height = 0.375
+const curve_steps = 8
+
+export function bounds(boxes) {
+  const result = [Infinity, Infinity, -Infinity, -Infinity]
+  for (const box of boxes) {
+    if (!box) continue
+    result[0] = Math.min(result[0], box[0])
+    result[1] = Math.min(result[1], box[1])
+    result[2] = Math.max(result[2], box[2])
+    result[3] = Math.max(result[3], box[3])
+  }
+  return Number.isFinite(result[0]) ? result : null
+}
+
+export function median(values, fallback = 0) {
+  if (!values.length) return fallback
+  values.sort((a, b) => a - b)
+  return values[Math.floor(values.length / 2)]
+}
+
+// A shared band height lets words from different printed pages share one row.
+function trace(paths, baseline, budget) {
+  const bands = new Map()
+  const mark = (x, y) => {
+    if (--budget.points < 0) throw new RangeError('QVP passage measurement limit exceeded')
+    const row = Math.floor((y - baseline) / band_height)
+    const span = bands.get(row)
+    if (span) {
+      span[0] = Math.min(span[0], x)
+      span[1] = Math.max(span[1], x)
+    } else {
+      if (--budget.bands < 0) throw new RangeError('QVP passage measurement limit exceeded')
+      bands.set(row, [x, x])
+    }
+  }
+  const segment = (a, b) => {
+    const steps = Math.max(1, Math.min(512, Math.ceil(Math.abs(b[1] - a[1]) / band_height)))
+    for (let i = 0; i <= steps; i++) {
+      const t = i / steps
+      mark(a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t)
+    }
+  }
+  for (const { ops, pts } of paths) {
+    let point = 0
+    let here = [0, 0]
+    let start = here
+    const take = () => [pts[point++], pts[point++]]
+    for (const op of ops) {
+      if (op === 0) {
+        here = take()
+        start = here
+        mark(...here)
+      } else if (op === 1 || op === 4) {
+        const to = op === 4 ? start : take()
+        segment(here, to)
+        here = to
+      } else {
+        const first = take()
+        const second = take()
+        const to = op === 2 ? second : take()
+        let previous = here
+        for (let i = 1; i <= curve_steps; i++) {
+          const t = i / curve_steps
+          const u = 1 - t
+          const next = [0, 1].map(axis => op === 2
+            ? u * u * here[axis] + 2 * u * t * first[axis] + t * t * to[axis]
+            : u ** 3 * here[axis] + 3 * u * u * t * first[axis] + 3 * u * t * t * second[axis] + t ** 3 * to[axis])
+          segment(previous, next)
+          previous = next
+        }
+        here = to
+      }
+    }
+  }
+  return [...bands].sort((a, b) => a[0] - b[0]).map(([row, [left, right]]) => [row, left, right])
+}
+
+export function clearance(a, b) {
+  let air = Infinity
+  let i = 0
+  let j = 0
+  while (i < a.length && j < b.length) {
+    if (a[i][0] < b[j][0]) i++
+    else if (b[j][0] < a[i][0]) j++
+    else {
+      air = Math.min(air, a[i][1] - b[j][2])
+      i++
+      j++
+    }
+  }
+  return Number.isFinite(air) ? air : null
+}
+
+function merged_slices(groups) {
+  const rows = new Map()
+  for (const slices of groups) for (const [row, left, right] of slices) {
+    const previous = rows.get(row)
+    rows.set(row, previous ? [Math.min(left, previous[0]), Math.max(right, previous[1])] : [left, right])
+  }
+  return [...rows].sort((a, b) => a[0] - b[0]).map(([row, [left, right]]) => [row, left, right])
+}
+
+export function preparePage(page) {
+  if (prepared_pages.has(page)) return prepared_pages.get(page)
+  // Shared across the page: large coordinates must not amplify bounded QVP input
+  // into unbounded maps or work. Current pages use <447k samples and <13k bands.
+  const budget = { points: 2000000, bands: 32768 }
+  const paths_of = record => page.paths.slice(record.firstPath, record.firstPath + record.nPaths)
+  const line_words = page.lines.map(line => page.words.slice(line.firstWord, line.firstWord + line.nWords))
+  const centres = page.lines.map((line, i) => {
+    let box = bounds(line_words[i].flatMap(word => paths_of(word).filter(path => path.kind === 0).map(path => path.box)))
+    if (!box) box = bounds(page.decorations.filter(d => d.lineIndex === i && [1, 2].includes(d.decoration)).map(d => d.box))
+    return box ? (box[1] + box[3]) / 2 : 0
+  })
+  const pitch = median(centres.slice(1).map((y, i) => Math.abs(y - centres[i])).filter(gap => gap > 1), page.height / 15)
+  const baselines = line_words.map((words, i) => median(words.map(word => word.box[3]), centres[i]))
+  const word_slices = page.words.map(word => trace(paths_of(word), baselines[word.lineIndex], budget))
+  const gaps = []
+  for (const words of line_words) for (let i = 1; i < words.length; i++) {
+    const a = words[i - 1]
+    const b = words[i]
+    if (a.surah !== b.surah || a.ayah !== b.ayah) continue
+    const air = clearance(word_slices[a.index], word_slices[b.index])
+    if (air > 0) gaps.push(air)
+  }
+  const gap = median(gaps, pitch / 4)
+  const attached = page.words.map(() => [])
+  const strokes = []
+  for (const decoration of page.decorations) {
+    if (![0, 3, 4].includes(decoration.decoration)) continue
+    const path_indices = Array.from({ length: decoration.nPaths }, (_, i) => decoration.firstPath + i)
+    for (const index of path_indices.filter(index => page.paths[index].mark === 31)) {
+      const box = page.paths[index].box
+      const under = page.words.filter(word => word.box[0] < box[2] && word.box[2] > box[0] && word.box[1] >= box[1] - 2)
+        .sort((a, b) => a.box[1] - b.box[1])[0]
+      if (!under) throw new Error('Sajdah line has no words')
+      const words = line_words[under.lineIndex].filter(word => word.box[0] < box[2] && word.box[2] > box[0])
+      strokes.push({ path: index, words: words.map(word => word.index), box, baseline: baselines[under.lineIndex] })
+    }
+    const indices = path_indices.filter(index => page.paths[index].mark !== 31)
+    if (!indices.length) continue
+    const box = bounds(indices.map(index => page.paths[index].box))
+    let word
+    if (decoration.decoration === 0 || decoration.decoration === 4) {
+      word = page.words.filter(word => word.surah === decoration.surah && word.ayah === decoration.ayah).pop()
+    } else {
+      const line = decoration.lineIndex >= 0 ? decoration.lineIndex : centres.reduce((best, y, i) =>
+        Math.abs(y - (box[1] + box[3]) / 2) < Math.abs(centres[best] - (box[1] + box[3]) / 2) ? i : best, 0)
+      const candidates = line_words[line]
+      word = candidates.filter(word => word.box[2] <= box[0] + gap).sort((a, b) => b.box[2] - a.box[2])[0]
+      word ||= [...candidates].sort((a, b) => Math.min(Math.abs(a.box[0] - box[0]), Math.abs(a.box[2] - box[2])) -
+        Math.min(Math.abs(b.box[0] - box[0]), Math.abs(b.box[2] - box[2])))[0]
+    }
+    if (!word) throw new Error('QVP passage decoration has no word')
+    attached[word.index].push({ indices, box, decoration: decoration.index,
+      slices: trace(indices.map(index => page.paths[index]), baselines[word.lineIndex], budget) })
+  }
+  const atoms = page.words.map(word => {
+    const decorations = attached[word.index]
+    const indices = Array.from({ length: word.nPaths }, (_, i) => word.firstPath + i)
+    for (const decoration of decorations) indices.push(...decoration.indices)
+    return { page, word, indices, decorations, pitch, gap,
+      baseline: baselines[word.lineIndex],
+      box: bounds([word.box, ...decorations.map(d => d.box)]),
+      slices: merged_slices([word_slices[word.index], ...decorations.map(d => d.slices)]),
+      wordSlices: word_slices[word.index] }
+  })
+  const result = { atoms, strokes, pitch, gap, baselines }
+  prepared_pages.set(page, result)
+  return result
+}

package/web/lite-passage.mjs

@@ -0,0 +1,199 @@
+// Lay out complete ayahs as a standalone passage without loading Wasm.
+import { buildPath } from './lite-path.mjs'
+import { bounds, clearance, median, preparePage } from './lite-passage-geometry.mjs'
+
+const canvas_paths = new WeakMap()
+
+/** Lay out and draw a contiguous ayah range from decoded QVP pages. */
+export class QvpPassage {
+  #atoms
+  #pages
+  #gaps
+  #layouts = new WeakMap()
+
+  /** Select complete ayahs; pages come from decodeGeometry(), in any order. */
+  constructor(pages, { surah, from, to = from }) {
+    if (!Number.isInteger(surah) || surah < 1 || surah > 114 ||
+        !Number.isInteger(from) || from < 1 || !Number.isInteger(to) || to < from || to > 286) {
+      throw new RangeError('Invalid passage ayah range')
+    }
+    if (new Set(pages.map(page => page.number)).size !== pages.length) throw new Error('Duplicate QVP pages')
+    this.#pages = pages
+    this.#atoms = []
+    this.ayahs = []
+    for (let ayah = from; ayah <= to; ayah++) {
+      const words = pages.flatMap(page => page.words.filter(word => word.surah === surah && word.ayah === ayah)
+        .map(word => ({ page, word }))).sort((a, b) => a.word.word - b.word.word)
+      const fragments = pages.flatMap(page => page.ayahs.filter(record => record.surah === surah && record.ayah === ayah))
+      fragments.sort((a, b) => a.fragment - b.fragment)
+      if (!words.length || !fragments.length || fragments.length !== fragments[0].fragments ||
+          fragments.some((record, i) => record.fragment !== i + 1 || record.fragments !== fragments.length) ||
+          words.length !== fragments.reduce((sum, record) => sum + record.nWords, 0) ||
+          words.some(({ word }, i) => word.word !== i + 1)) {
+        throw new Error(`Incomplete passage ayah ${surah}:${ayah}`)
+      }
+      if (this.#atoms.length + words.length > 4096) throw new RangeError('A passage may contain at most 4096 words')
+      for (const { page, word } of words) this.#atoms.push(preparePage(page).atoms[word.index])
+      this.ayahs.push({ surah, ayah, text: words.map(({ word }) => word.text).join(' ') })
+    }
+    this.#gaps = this.#atoms.map((atom, index) => {
+      if (!index) return 0
+      const previous = this.#atoms[index - 1]
+      const natural = previous.box[0] - atom.box[2]
+      const word_air = clearance(previous.wordSlices, atom.wordSlices)
+      const joined = previous.page === atom.page && previous.word.lineIndex === atom.word.lineIndex &&
+        previous.word.index + 1 === atom.word.index && word_air !== null && -word_air >= atom.pitch * 0.15
+      if (joined) return natural
+      const air = clearance(previous.slices, atom.slices)
+      const wanted = (previous.gap + atom.gap) / 2
+      return air === null ? wanted : natural + wanted - air
+    })
+  }
+
+  /** Return rows and word/ayah bounds in CSS pixels, at the requested width and scale. */
+  layout({ width, scale = 1, lineSpacing = 1, padding = 2, align = 'right' }) {
+    if (!Number.isFinite(width) || width <= 0 || width > 32768 ||
+        !Number.isFinite(scale) || scale <= 0 || scale > 32 ||
+        !Number.isFinite(padding) || padding < 0 || 2 * padding >= width ||
+        !Number.isFinite(lineSpacing) || lineSpacing < 1 || lineSpacing > 4 ||
+        !['right', 'center'].includes(align)) throw new RangeError('Invalid passage layout')
+    const atoms = this.#atoms
+    const widest = Math.max(...atoms.map(atom => atom.box[2] - atom.box[0]))
+    // An indivisible word and its signs must fit even at an unusually narrow width.
+    scale = Math.min(scale, (width - 2 * padding) / widest)
+    const row_width = (width - 2 * padding) / scale
+    const rows = break_rows(atoms, this.#gaps, row_width)
+    const drawings = []
+    const placements = new Map()
+    const result = { width, height: 0, scale, rows: [], words: [], ayahs: [] }
+    const pitch = median(atoms.map(atom => atom.pitch)) * lineSpacing
+    let last_bottom = 0
+    let last_baseline = 0
+    for (const indices of rows) {
+      const used = indices.reduce((sum, index, i) => sum + atoms[index].box[2] - atoms[index].box[0] + (i ? this.#gaps[index] : 0), 0)
+      const ascent = Math.max(...indices.map(index => atoms[index].baseline - atoms[index].box[1]))
+      const descent = Math.max(...indices.map(index => atoms[index].box[3] - atoms[index].baseline))
+      // Signs and tall marks have the same right to vertical space as the letters.
+      const baseline = result.rows.length ? Math.max(last_baseline + pitch, last_bottom + ascent + 1) : ascent
+      let cursor = align === 'center' ? (row_width + used) / 2 : row_width
+      const row = result.rows.length
+      const row_bounds = []
+      for (let i = 0; i < indices.length; i++) {
+        const index = indices[i]
+        const atom = atoms[index]
+        if (i) cursor -= this.#gaps[index]
+        const dx = cursor - atom.box[2]
+        const dy = baseline - atom.baseline
+        const placement = { dx, dy, row }
+        placements.set(atom, placement)
+        for (const path of atom.indices) drawings.push({ page: atom.page, path, dx, dy, kx: 1, row })
+        const box = [atom.box[0] + dx, atom.box[1] + dy, atom.box[2] + dx, atom.box[3] + dy]
+        row_bounds.push(box)
+        result.words.push({ surah: atom.word.surah, ayah: atom.word.ayah, word: atom.word.word, row, box })
+        cursor -= atom.box[2] - atom.box[0]
+      }
+      result.rows.push({ box: bounds(row_bounds), baseline })
+      last_baseline = baseline
+      last_bottom = baseline + descent
+    }
+    // A sajdah line belongs to the words underneath it, not necessarily to the ayah
+    // carrying the sign. Its stroke is repeated only when those words span rows.
+    for (const page of this.#pages) for (const stroke of preparePage(page).strokes) {
+      const spans = new Map()
+      for (const index of stroke.words) {
+        const atom = preparePage(page).atoms[index]
+        const placement = placements.get(atom)
+        if (!placement) continue
+        const box = [atom.word.box[0] + placement.dx, atom.word.box[1] + placement.dy,
+          atom.word.box[2] + placement.dx, atom.word.box[3] + placement.dy]
+        const old = spans.get(placement.row)
+        spans.set(placement.row, { box: bounds([old?.box, box]), dy: placement.dy })
+      }
+      for (const [row, { box, dy }] of spans) {
+        const kx = (box[2] - box[0]) / (stroke.box[2] - stroke.box[0])
+        const dx = box[0] - kx * stroke.box[0]
+        drawings.push({ page, path: stroke.path, dx, dy, kx, row })
+        result.rows[row].box = bounds([result.rows[row].box, [box[0], stroke.box[1] + dy, box[2], stroke.box[3] + dy]])
+      }
+    }
+    // Include the strokes in row spacing too. Moving whole rows cannot reshape ink.
+    for (let row = 1; row < result.rows.length; row++) {
+      const needed = result.rows[row - 1].box[3] + 1 - result.rows[row].box[1]
+      if (needed <= 0) continue
+      for (let i = row; i < result.rows.length; i++) {
+        result.rows[i].box[1] += needed
+        result.rows[i].box[3] += needed
+        result.rows[i].baseline += needed
+      }
+      for (const word of result.words) if (word.row >= row) {
+        word.box[1] += needed
+        word.box[3] += needed
+      }
+      for (const drawing of drawings) if (drawing.row >= row) drawing.dy += needed
+    }
+    const ink = bounds(result.rows.map(row => row.box))
+    const offset = padding / scale - ink[1]
+    for (const drawing of drawings) {
+      drawing.dx += padding / scale
+      drawing.dy += offset
+    }
+    const css_box = box => [box[0] * scale + padding, (box[1] + offset) * scale,
+      box[2] * scale + padding, (box[3] + offset) * scale]
+    for (const word of result.words) word.box = css_box(word.box)
+    for (const row of result.rows) {
+      row.box = css_box(row.box)
+      row.baseline = (row.baseline + offset) * scale
+    }
+    result.height = (ink[3] - ink[1]) * scale + 2 * padding
+    result.ayahs = this.ayahs.map(ayah => ({ ...ayah,
+      box: bounds(result.words.filter(word => word.surah === ayah.surah && word.ayah === ayah.ayah).map(word => word.box)) }))
+    this.#layouts.set(result, drawings)
+    return result
+  }
+
+  /** Draw a layout without clearing or sizing the canvas; pixelRatio is its backing ratio. */
+  draw(ctx, layout, { pixelRatio = 1, ink = '#231f20' } = {}) {
+    const drawings = this.#layouts.get(layout)
+    if (!drawings) throw new Error('Layout belongs to another passage')
+    if (!Number.isFinite(pixelRatio) || pixelRatio <= 0) throw new RangeError('Invalid pixel ratio')
+    const scale = layout.scale * pixelRatio
+    ctx.save()
+    ctx.fillStyle = ink
+    for (const { page, path, dx, dy, kx } of drawings) {
+      let paths = canvas_paths.get(page)
+      if (!paths) canvas_paths.set(page, paths = new Map())
+      if (!paths.has(path)) paths.set(path, buildPath(page.paths[path]))
+      ctx.setTransform(scale * kx, 0, 0, scale, dx * scale, dy * scale)
+      ctx.fill(paths.get(path), page.paths[path].rule)
+    }
+    ctx.restore()
+  }
+}
+
+// Balance a bounded passage without stretching its gaps. The last row may be short.
+function break_rows(atoms, gaps, width) {
+  const n = atoms.length
+  const best = new Float64Array(n + 1).fill(Infinity)
+  const previous = new Uint32Array(n + 1)
+  best[0] = 0
+  for (let end = 1; end <= n; end++) {
+    let used = 0
+    for (let start = end - 1; start >= 0; start--) {
+      used += atoms[start].box[2] - atoms[start].box[0] + (start < end - 1 ? gaps[start + 1] : 0)
+      if (used > width + 0.001) break
+      const slack = width - used
+      const cost = best[start] + (end === n ? 0 : slack * slack) + 1
+      if (cost < best[end]) {
+        best[end] = cost
+        previous[end] = start
+      }
+    }
+  }
+  const rows = []
+  for (let end = n; end > 0;) {
+    const start = previous[end]
+    rows.push(Array.from({ length: end - start }, (_, i) => start + i))
+    end = start
+  }
+  return rows.reverse()
+}

package/web/lite-path.mjs

@@ -0,0 +1,16 @@
+// Build a Canvas path without changing the decoded outline or its fill rule.
+export function buildPath({ ops, pts }) {
+  const path = new Path2D()
+  let point = 0
+  for (const operation of ops) {
+    switch (operation) {
+      case 0: path.moveTo(pts[point++], pts[point++]); break
+      case 1: path.lineTo(pts[point++], pts[point++]); break
+      case 2: path.quadraticCurveTo(pts[point++], pts[point++], pts[point++], pts[point++]); break
+      case 3: path.bezierCurveTo(pts[point++], pts[point++], pts[point++], pts[point++], pts[point++], pts[point++]); break
+      case 4: path.closePath(); break
+      default: throw new Error(`Unknown QVP operation: ${operation}`)
+    }
+  }
+  return path
+}