@arraypress/covers 0.0.0-stage → 1.1.0

package/src/type/kern.js

@@ -0,0 +1,144 @@
+/**
+ * Pair kerning from a TrueType font: GPOS `kern` feature pair adjustments
+ * (formats 1 and 2, through extension lookups; lookups add up), else the
+ * legacy `kern` table.
+ *
+ * @module type/kern
+ */
+
+/**
+ * Pair kerning: GPOS `kern` feature pair adjustments (formats 1 and 2,
+ * through extension lookups), else the legacy `kern` table.
+ *
+ * @param {DataView} v
+ * @param {Record<string, number>} tables
+ * @returns {(a: number, b: number) => number} X advance adjustment, font units.
+ */
+export function pairKerning(v, tables) {
+  const u16 = (/** @type {number} */ o) => v.getUint16(o);
+  const i16 = (/** @type {number} */ o) => v.getInt16(o);
+  /** Pair lookups, each a list of subtables (the first that covers a pair applies; lookups add up). @type {((a: number, b: number) => number | undefined)[][]} */
+  const lookupsList = [];
+  /** @type {((a: number, b: number) => number | undefined)[]} */
+  let subtables = [];
+
+  const coverage = (/** @type {number} */ o) => {
+    const fmt = u16(o);
+    /** @type {Map<number, number>} */
+    const m = new Map();
+    if (fmt === 1) for (let i = 0, n = u16(o + 2); i < n; i++) m.set(u16(o + 4 + i * 2), i);
+    else for (let i = 0, n = u16(o + 2); i < n; i++) {
+      const r = o + 4 + i * 6;
+      for (let g = u16(r), idx = u16(r + 4); g <= u16(r + 2); g++, idx++) m.set(g, idx);
+    }
+    return m;
+  };
+  const classDef = (/** @type {number} */ o) => {
+    const fmt = u16(o);
+    /** @type {Map<number, number>} */
+    const m = new Map();
+    if (fmt === 1) { const s = u16(o + 2); for (let i = 0, n = u16(o + 4); i < n; i++) m.set(s + i, u16(o + 6 + i * 2)); }
+    else for (let i = 0, n = u16(o + 2); i < n; i++) { const r = o + 4 + i * 6; for (let g = u16(r); g <= u16(r + 2); g++) m.set(g, u16(r + 4)); }
+    return m;
+  };
+  const bits = (/** @type {number} */ f) => { let c = 0; for (let x = f; x; x >>= 1) c += x & 1; return c * 2; };
+  // XAdvance of a value record (or XPlacement, the rare alternative).
+  const xadv = (/** @type {number} */ o, /** @type {number} */ fmt) => {
+    let p = o;
+    let x = 0;
+    if (fmt & 1) { x += i16(p); p += 2; }
+    if (fmt & 2) p += 2;
+    if (fmt & 4) x += i16(p);
+    return x;
+  };
+
+  const pairPos = (/** @type {number} */ st) => {
+    const fmt = u16(st);
+    const cov = coverage(st + u16(st + 2));
+    const vf1 = u16(st + 4);
+    const vf2 = u16(st + 6);
+    const s1 = bits(vf1);
+    const s2 = bits(vf2);
+    if (fmt === 1) {
+      const sets = st + 10;
+      subtables.push((a, b) => {
+        const idx = cov.get(a);
+        if (idx === undefined) return undefined;
+        const ps = st + u16(sets + idx * 2);
+        const n = u16(ps);
+        const rec = 2 + s1 + s2;
+        let lo = 0;
+        let hi = n - 1;
+        while (lo <= hi) {
+          const mid = (lo + hi) >> 1;
+          const r = ps + 2 + mid * rec;
+          const g = u16(r);
+          if (g === b) return xadv(r + 2, vf1);
+          if (g < b) lo = mid + 1; else hi = mid - 1;
+        }
+        return undefined;
+      });
+    } else if (fmt === 2) {
+      const c1 = classDef(st + u16(st + 8));
+      const c2 = classDef(st + u16(st + 10));
+      const n2 = u16(st + 14);
+      const rec = s1 + s2;
+      subtables.push((a, b) => {
+        if (!cov.has(a)) return undefined;
+        const r = st + 16 + ((c1.get(a) ?? 0) * n2 + (c2.get(b) ?? 0)) * rec;
+        return xadv(r, vf1);
+      });
+    }
+  };
+
+  const gpos = tables.GPOS;
+  if (gpos != null) {
+    const features = gpos + u16(gpos + 6);
+    const lookups = gpos + u16(gpos + 8);
+    /** @type {Set<number>} */
+    const wanted = new Set();
+    for (let i = 0, n = u16(features); i < n; i++) {
+      const r = features + 2 + i * 6;
+      if (String.fromCharCode(v.getUint8(r), v.getUint8(r + 1), v.getUint8(r + 2), v.getUint8(r + 3)) !== 'kern') continue;
+      const f = features + u16(r + 4);
+      for (let k = 0, m = u16(f + 2); k < m; k++) wanted.add(u16(f + 4 + k * 2));
+    }
+    for (const li of [...wanted].sort((a, b) => a - b)) {
+      subtables = [];
+      lookupsList.push(subtables);
+      const l = lookups + u16(lookups + 2 + li * 2);
+      const type = u16(l);
+      for (let k = 0, m = u16(l + 4); k < m; k++) {
+        let st = l + u16(l + 6 + k * 2);
+        let t = type;
+        if (t === 9) { t = u16(st + 2); st += v.getUint32(st + 4); }
+        if (t === 2) pairPos(st);
+      }
+    }
+  }
+  if (!lookupsList.some((l) => l.length) && tables.kern != null && u16(tables.kern) === 0) {
+    subtables = [];
+    lookupsList.push(subtables);
+    const k = tables.kern;
+    const st = k + 4;
+    if (u16(st + 4) >> 8 === 0) {
+      /** @type {Map<number, number>} */
+      const pairs = new Map();
+      for (let i = 0, n = u16(st + 6); i < n; i++) {
+        const r = st + 14 + i * 6;
+        pairs.set(u16(r) * 65536 + u16(r + 2), i16(r + 4));
+      }
+      subtables.push((a, b) => pairs.get(a * 65536 + b));
+    }
+  }
+  return (a, b) => {
+    let total = 0;
+    for (const list of lookupsList) {
+      for (const s of list) {
+        const x = s(a, b);
+        if (x !== undefined) { total += x; break; }
+      }
+    }
+    return total;
+  };
+}

package/src/type/layout-ref.d.ts

@@ -0,0 +1,10 @@
+// Text layout later layers can read: {layout.<id>.<field>}.
+
+/** Fields a reference can read. */
+export const LAYOUT_FIELDS: readonly ('x' | 'y' | 'top' | 'bottom' | 'left' | 'right' | 'width' | 'height' | 'baseline' | 'size' | 'lines')[];
+/** Whether a value holds a layout reference (outside nested layers). */
+export function hasLayoutRef(v: unknown): boolean;
+/** A layer with its layout references replaced by numbers. */
+export function resolveLayoutRefs<T>(v: T, layout: Map<string, Record<string, number>>): T;
+/** Record a text block's layout for later layers. */
+export function recordLayout(ctx: { layout?: Map<string, Record<string, number>> }, id: string | undefined, box: { x: number; y: number; width: number; height: number }, more: { x: number; y: number; baseline: number; size: number; lines: number }): void;

package/src/type/layout-ref.js

@@ -0,0 +1,74 @@
+/**
+ * Text layout other layers can read: a text layer with an `id` records
+ * where its block landed, and any later layer can use `{layout.<id>.<field>}`
+ * (optionally `+ n` or `- n`) as a number: `bottom`, `top`, `left`,
+ * `right`, `width`, `height`, `x`, `y` (the first baseline), `baseline`
+ * (the last one), `size` (as fitted) and `lines`. Units are the text
+ * layer's own (a group's grid inside a group).
+ *
+ * @module type/layout-ref
+ */
+
+/** A layout reference, whole or inside a string. */
+const TOKEN = /\{layout\.([\w-]+)\.(\w+)\s*(?:([+-])\s*([\d.]+))?\}/g;
+
+/** Fields a reference can read. */
+export const LAYOUT_FIELDS = Object.freeze(['x', 'y', 'top', 'bottom', 'left', 'right', 'width', 'height', 'baseline', 'size', 'lines']);
+
+/**
+ * Whether a value holds a layout reference (layers nested in it aside: they
+ * resolve when they're drawn).
+ *
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+export function hasLayoutRef(v) {
+  if (typeof v === 'string') return v.includes('{layout.');
+  if (Array.isArray(v)) return v.some(hasLayoutRef);
+  if (v && typeof v === 'object' && !(v instanceof Uint8Array)) return Object.entries(v).some(([k, x]) => !NESTED.has(k) && hasLayoutRef(x));
+  return false;
+}
+
+/** Options holding nested layers. */
+const NESTED = new Set(['layers', 'mask', 'knockout', 'clip']);
+
+/**
+ * A layer with its layout references replaced by numbers.
+ *
+ * @param {any} v
+ * @param {Map<string, Record<string, number>>} layout
+ * @returns {any}
+ * @throws {TypeError} On a reference to a text layer not drawn yet, or an unknown field.
+ */
+export function resolveLayoutRefs(v, layout) {
+  if (typeof v === 'string') {
+    const one = new RegExp(`^${TOKEN.source}$`).exec(v.trim());
+    if (one) return value(one, layout);
+    return v.replace(TOKEN, (...m) => String(value(/** @type {any} */ (m), layout)));
+  }
+  if (Array.isArray(v)) return v.map((x) => resolveLayoutRefs(x, layout));
+  if (v && typeof v === 'object' && !(v instanceof Uint8Array)) return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, NESTED.has(k) ? x : resolveLayoutRefs(x, layout)]));
+  return v;
+}
+
+/** @param {string[]} m @param {Map<string, Record<string, number>>} layout @returns {number} */
+function value(m, layout) {
+  const [, id, field, sign, n] = m;
+  const box = layout.get(id);
+  if (!box) throw new TypeError(`{layout.${id}.${field}}: no text layer "${id}" drawn before this one`);
+  if (!LAYOUT_FIELDS.includes(field)) throw new TypeError(`{layout.${id}.${field}}: unknown field (${LAYOUT_FIELDS.join(', ')})`);
+  return box[field] + (sign ? (sign === '-' ? -1 : 1) * Number(n) : 0);
+}
+
+/**
+ * Record a text block's layout for later layers.
+ *
+ * @param {any} ctx
+ * @param {string | undefined} id
+ * @param {{ x: number, y: number, width: number, height: number }} box - The block, from cap height to last baseline.
+ * @param {{ x: number, y: number, baseline: number, size: number, lines: number }} more
+ */
+export function recordLayout(ctx, id, box, more) {
+  if (!id || !ctx.layout) return;
+  ctx.layout.set(id, { ...more, top: box.y, bottom: box.y + box.height, left: box.x, right: box.x + box.width, width: box.width, height: box.height });
+}

package/src/type/line.d.ts

@@ -0,0 +1,11 @@
+// Setting one line of type.
+import type { LoadedFont } from '../fonts.js';
+import type { Shaped } from '../text.js';
+import type { RenderContext } from '../render/context.js';
+
+/** A face for a family, weight, style and variable axes (`'pixel'`: the built-in 5×7 face). */
+export function faceFor(ctx: RenderContext, o: { font?: string; weight?: number; style?: string; axes?: Record<string, number> }): Promise<LoadedFont>;
+/** Glyph outlines of a run through a map from glyph px (y down, baseline 0) to canvas px. */
+export function mappedPath(face: LoadedFont, run: Shaped, size: number, map: (gx: number, gy: number, glyph: Shaped['glyphs'][number]) => [number, number], only?: (glyph: Shaped['glyphs'][number]) => boolean): string;
+/** Shape, justify (`width`) and draw one line anchored at `x` by `align`. */
+export function setLine(o: { face: LoadedFont; text: string; size: number; tracking: number; x: number; y: number; align: 'left' | 'center' | 'right'; width?: number; adjust?: 'spacingAndGlyphs' | 'spacing'; shape?: (tracking: number) => Shaped; only?: (glyph: Shaped['glyphs'][number]) => boolean }): { d: string; width: number; left: number; run: Shaped; scaleX: number };

package/src/type/line.js

@@ -0,0 +1,105 @@
+/**
+ * Setting one line of type: a face for a layer, glyph outlines through any
+ * affine map, and a line justified to a width (`textLength`).
+ *
+ * @module type/line
+ */
+
+import { num } from '../svg.js';
+import { loadFont, pickFont, variationsFor } from '../fonts.js';
+import { shape, outline } from '../text.js';
+import { pixelFace } from './pixel.js';
+
+/**
+ * A face for a layer's family, weight, style and axes (`'pixel'` is the
+ * built-in 5×7 face, unless a font of that name is registered).
+ *
+ * @param {import('../layers.js').RenderContext} ctx
+ * @param {{ font?: string, weight?: number, style?: string, axes?: Record<string, number> }} o
+ * @returns {Promise<import('../fonts.js').LoadedFont>}
+ */
+export async function faceFor(ctx, o) {
+  if (o.font === 'pixel' && !ctx.fonts.some((f) => f.name === 'pixel')) return pixelFace();
+  const weight = o.weight ?? 600;
+  const source = pickFont(ctx.fonts, o.font ?? 'Inter', weight, o.style);
+  return loadFont(source, variationsFor(source, weight, o.axes));
+}
+
+/**
+ * Glyph outlines of a shaped run, through an affine map: glyph point
+ * (gx, gy) in px (y down, baseline 0) goes to `map(gx, gy)`.
+ *
+ * @param {import('../fonts.js').LoadedFont} face
+ * @param {import('../text.js').Shaped} run
+ * @param {number} size
+ * @param {(gx: number, gy: number, glyph: { x: number, y: number }) => [number, number]} map
+ * @param {(glyph: any) => boolean} [only] - Draw only these glyphs (one paint at a time).
+ * @returns {string}
+ */
+export function mappedPath(face, run, size, map, only) {
+  const parts = [];
+  for (const g of run.glyphs) {
+    if (only && !only(g)) continue;
+    const f = g.face ?? face;
+    const s = (g.size ?? size) / f.upem;
+    const t = g.t;
+    let coords = [];
+    let even = true;
+    let px = 0;
+    for (const c of outline(f, g.gid)) {
+      if (typeof c === 'string') {
+        if (coords.length) parts.push(coords.join(' '));
+        parts.push(c);
+        coords = [];
+        even = true;
+      } else if (even) {
+        px = c;
+        even = false;
+      } else {
+        // A glyph's own transform (per-glyph scale, turn, shift) is about its pen position.
+        const gx = px * s;
+        const gy = -c * s;
+        const [X, Y] = t ? map(g.x + t[0] * gx + t[2] * gy + t[4], g.y + t[1] * gx + t[3] * gy + t[5], g) : map(g.x + gx, g.y + gy, g);
+        coords.push(num(X), num(Y));
+        even = true;
+      }
+    }
+    if (coords.length) parts.push(coords.join(' '));
+  }
+  return parts.join('');
+}
+
+/**
+ * Set one line: shape, justify and draw.
+ *
+ * @param {object} o
+ * @param {import('../fonts.js').LoadedFont} o.face
+ * @param {string} o.text
+ * @param {number} o.size
+ * @param {number} o.tracking - Letter-spacing, px.
+ * @param {number} o.x - Anchor x (start, middle or end by `align`).
+ * @param {number} o.y - Baseline.
+ * @param {'left' | 'center' | 'right'} o.align
+ * @param {number} [o.width] - Justify to this width.
+ * @param {'spacingAndGlyphs' | 'spacing'} [o.adjust]
+ * @param {(tracking: number) => import('../text.js').Shaped} [o.shape] - Shapes the line at a tracking (fallback faces, spans, per-glyph control); default the face alone.
+ * @param {(glyph: any) => boolean} [o.only] - Draw only these glyphs.
+ * @returns {{ d: string, width: number, left: number, run: import('../text.js').Shaped, scaleX: number }}
+ */
+export function setLine(o) {
+  const shapeAt = o.shape ?? ((/** @type {number} */ tracking) => shape(o.face, o.text, o.size, tracking));
+  let run = shapeAt(o.tracking);
+  let scaleX = 1;
+  if (o.width && run.width > 0) {
+    if (o.adjust === 'spacing') {
+      const gaps = Math.max(1, new Set(o.face.shapeRun(o.text).map((g) => g.cluster)).size - 1);
+      run = shapeAt(o.tracking + (o.width - run.width) / gaps);
+    } else {
+      scaleX = o.width / run.width;
+    }
+  }
+  const w = run.width * scaleX;
+  const left = o.align === 'center' ? o.x - w / 2 : o.align === 'right' ? o.x - w : o.x;
+  const d = mappedPath(o.face, run, o.size, (gx, gy) => [left + gx * scaleX, o.y + gy], o.only);
+  return { d, width: w, left, run, scaleX };
+}

package/src/type/live.d.ts

@@ -0,0 +1,6 @@
+// Live text: @font-face rules.
+import type { LoadedFont } from '../fonts.js';
+import type { RenderContext } from '../render/context.js';
+
+/** The face's `@font-face` rule (empty when this document has it already) and its family name. */
+export function fontFace(face: LoadedFont, ctx: RenderContext): Promise<{ family: string; css: string }>;

package/src/type/live.js

@@ -0,0 +1,39 @@
+/**
+ * Live text: the `@font-face` rule for a face, embedded (or linked by URL)
+ * once per document.
+ *
+ * @module type/live
+ */
+
+import { fontBytes } from '../fonts.js';
+import { toBase64 } from '../platform/bytes.js';
+
+/** Faces embedded in this document already (live text). @type {WeakMap<object, Set<string>>} */
+const embedded = new WeakMap();
+
+/**
+ * `@font-face` for a face, once per document.
+ *
+ * @param {import('../fonts.js').LoadedFont} face
+ * @param {import('../layers.js').RenderContext} ctx
+ * @returns {Promise<{ family: string, css: string }>}
+ */
+export async function fontFace(face, ctx) {
+  const src = face.source;
+  const family = `covers-${src.name}-${Array.isArray(src.weight) ? 'var' : src.weight ?? 400}-${src.style ?? 'normal'}`.replace(/[^\w-]/g, '_');
+  const doc = /** @type {any} */ (ctx).doc ?? ctx;
+  let seen = embedded.get(doc);
+  if (!seen) embedded.set(doc, (seen = new Set()));
+  if (seen.has(family)) return { family, css: '' };
+  seen.add(family);
+  let url;
+  if (src.data == null && typeof src.src === 'string' && !src.src.startsWith('covers:')) url = src.src;
+  else {
+    const bytes = await fontBytes(src);
+    const tag = new DataView(bytes.buffer, bytes.byteOffset, 4).getUint32(0);
+    const mime = tag === 0x774f4646 ? 'font/woff' : tag === 0x774f4632 ? 'font/woff2' : tag === 0x4f54544f ? 'font/otf' : 'font/ttf';
+    url = `data:${mime};base64,${toBase64(bytes)}`;
+  }
+  const weight = Array.isArray(src.weight) ? `${src.weight[0]} ${src.weight[1]}` : src.weight ?? 400;
+  return { family, css: `@font-face{font-family:"${family}";src:url("${url}");font-weight:${weight};font-style:${src.style ?? 'normal'}}` };
+}

package/src/type/name.d.ts

@@ -0,0 +1,4 @@
+// A font's family name.
+
+/** The typographic family (name ID 16), else the family (1), else ''. */
+export function familyName(v: DataView, bytes: Uint8Array, base: number | undefined): string;

package/src/type/name.js

@@ -0,0 +1,32 @@
+/**
+ * A font's family name from its `name` table.
+ *
+ * @module type/name
+ */
+
+/**
+ * The family name from the `name` table (typographic family, else family).
+ *
+ * @param {DataView} v @param {Uint8Array} bytes @param {number | undefined} base
+ * @returns {string}
+ */
+export function familyName(v, bytes, base) {
+  if (base == null) return '';
+  const count = v.getUint16(base + 2);
+  const strings = base + v.getUint16(base + 4);
+  /** @type {Record<number, string>} */
+  const found = {};
+  for (let i = 0; i < count; i++) {
+    const r = base + 6 + i * 12;
+    const pid = v.getUint16(r);
+    const id = v.getUint16(r + 6);
+    if ((id !== 1 && id !== 16) || found[id]) continue;
+    const len = v.getUint16(r + 8);
+    const off = strings + v.getUint16(r + 10);
+    let s = '';
+    if (pid === 3 || pid === 0) for (let k = 0; k < len; k += 2) s += String.fromCharCode(v.getUint16(off + k));
+    else for (let k = 0; k < len; k++) s += String.fromCharCode(bytes[off + k]);
+    found[id] = s;
+  }
+  return found[16] ?? found[1] ?? '';
+}

package/src/type/path.d.ts

@@ -0,0 +1,18 @@
+// Paths for text.
+import type { Length } from '../index.js';
+
+/** A path for text: an arc, circle, ellipse or wave, or any path data. */
+export type TextPath = string | { d: string } | {
+  kind?: 'circle' | 'arc' | 'ellipse' | 'wave';
+  cx?: Length | `${number}%`; cy?: Length | `${number}%`; r?: Length; rx?: Length; ry?: Length;
+  /** Degrees, 0 at 12 o'clock, clockwise. */
+  start?: number; end?: number;
+  direction?: 'cw' | 'ccw'; side?: 'outside' | 'inside';
+  x1?: Length; x2?: Length; y?: Length; amplitude?: Length; wavelength?: Length; phase?: number;
+};
+
+
+/** A text path as path data, px. */
+export function textPathD(p: TextPath, canvas: { width: number; height: number }): string;
+/** A sampler along path data: point and unit tangent at a distance (continuing straight past the ends). */
+export function pathSampler(d: string): { length: number; at: (s: number) => { x: number; y: number; tx: number; ty: number } };

package/src/type/path.js

@@ -0,0 +1,89 @@
+/**
+ * Paths for text: circles, arcs, ellipses and waves as path data, and a
+ * sampler that gives a point and tangent at any distance along a path.
+ *
+ * @module type/path
+ */
+
+import { num } from '../svg.js';
+import { len } from '../geometry.js';
+import { flattenPath } from '../flatten.js';
+import { pos } from '../layers/util.js';
+
+/**
+ * A text path as path data, in px.
+ *
+ * @param {any} p - `{ kind: 'circle' | 'arc' | 'ellipse' | 'wave', … }` or `{ d }`.
+ * @param {{ width: number, height: number }} canvas
+ * @returns {string}
+ */
+export function textPathD(p, canvas) {
+  const X = (/** @type {any} */ v, /** @type {any} */ f) => pos(v ?? f, 'x', canvas);
+  const Y = (/** @type {any} */ v, /** @type {any} */ f) => pos(v ?? f, 'y', canvas);
+  if (typeof p === 'string') return p;
+  if (p.d) return p.d;
+  const kind = p.kind ?? 'circle';
+  if (kind === 'circle' || kind === 'ellipse' || kind === 'arc') {
+    const cx = X(p.cx, '50%');
+    const cy = Y(p.cy, '50%');
+    const rx = len(p.rx ?? p.r, canvas, '30vmin');
+    const ry = len(p.ry ?? p.r, canvas, '30vmin');
+    // Angles: 0 is 12 o'clock, clockwise. A circle starts at its `start` and goes all the way round.
+    const ccw = p.direction === 'ccw' || p.side === 'inside';
+    const a0 = p.start ?? (kind === 'arc' ? -90 : 180);
+    const sweep = kind === 'arc' ? (p.end ?? 90) - a0 : 360;
+    const n = Math.max(24, Math.ceil(Math.abs(sweep) / 2));
+    const pts = [];
+    for (let i = 0; i <= n; i++) {
+      const a = ((a0 + (ccw ? -1 : 1) * Math.abs(sweep) * (i / n)) * Math.PI) / 180;
+      pts.push(`${i ? 'L' : 'M'}${num(cx + rx * Math.sin(a), 3)} ${num(cy - ry * Math.cos(a), 3)}`);
+    }
+    return pts.join('');
+  }
+  if (kind === 'wave') {
+    const x1 = X(p.x1, 0);
+    const x2 = X(p.x2, '100%');
+    const y = Y(p.y, '50%');
+    const amp = len(p.amplitude, canvas, '2vmin');
+    const wl = len(p.wavelength, canvas, '40vmin');
+    const ph = p.phase ?? 0;
+    const pts = [];
+    for (let x = x1, i = 0; x <= x2 + 0.01; x += 2, i++) pts.push(`${i ? 'L' : 'M'}${num(x, 3)} ${num(y + Math.sin(((x - x1) / wl) * Math.PI * 2 + ph) * amp, 3)}`);
+    return pts.join('');
+  }
+  throw new TypeError(`Unknown text path kind "${kind}" (circle, arc, ellipse, wave, or { d })`);
+}
+
+/**
+ * A sampler along path data: point and tangent at a distance.
+ *
+ * @param {string} d
+ * @returns {{ length: number, at: (s: number) => { x: number, y: number, tx: number, ty: number } }}
+ */
+export function pathSampler(d) {
+  const subs = flattenPath(d, 1);
+  const pts = subs.flatMap((s) => s.points);
+  if (pts.length < 2) throw new TypeError('A text path needs at least two points');
+  const cum = [0];
+  for (let i = 1; i < pts.length; i++) cum.push(cum[i - 1] + Math.hypot(pts[i][0] - pts[i - 1][0], pts[i][1] - pts[i - 1][1]));
+  const length = cum[cum.length - 1];
+  return {
+    length,
+    at(s) {
+      const t = Math.max(0, Math.min(length, s));
+      let lo = 0;
+      let hi = cum.length - 1;
+      while (hi - lo > 1) { const mid = (lo + hi) >> 1; if (cum[mid] <= t) lo = mid; else hi = mid; }
+      const seg = cum[hi] - cum[lo] || 1;
+      const f = (t - cum[lo]) / seg;
+      const [ax, ay] = pts[lo];
+      const [bx, by] = pts[hi];
+      const dl = Math.hypot(bx - ax, by - ay) || 1;
+      // Beyond the ends, keep going along the end tangent.
+      const over = s - t;
+      const tx = (bx - ax) / dl;
+      const ty = (by - ay) / dl;
+      return { x: ax + (bx - ax) * f + tx * over, y: ay + (by - ay) * f + ty * over, tx, ty };
+    },
+  };
+}

package/src/type/pixel.d.ts

@@ -0,0 +1,9 @@
+// The built-in 5×7 pixel face.
+import type { LoadedFont } from '../fonts.js';
+
+/** The pixel face (`font: 'pixel'`): A–Z, 0–9 and basic punctuation, as merged cell paths. */
+export function pixelFace(): LoadedFont;
+/** The characters it draws (lowercase is drawn as capitals). */
+export const PIXEL_CHARS: string;
+/** A glyph's 5×7 bitmap (35 cells row by row, `#` inked), or undefined. */
+export function pixelBitmap(ch: string): string | undefined;

package/src/type/pixel.js

@@ -0,0 +1,115 @@
+/**
+ * A built-in 5×7 pixel face (`font: 'pixel'`): A–Z, 0–9 and basic
+ * punctuation, each glyph a set of square cells merged into row runs. It
+ * is a face like any other (layout, fitting, justification, text on a
+ * path, per-glyph control all work), drawn as paths.
+ *
+ * Metrics, in a 1000-unit em: a cell is 100 units, capitals are 7 cells
+ * (700), the advance is 6 cells (a cell's gap after each glyph), a space
+ * is 4 cells. Lowercase is drawn as capitals.
+ *
+ * @module type/pixel
+ */
+
+/** Glyph bitmaps, 5 wide × 7 tall, `#` inked. */
+const BITMAPS = /** @type {Record<string, string>} */ ({
+  A: '.###.#...##...#######...##...##...#', B: '####.#...##...#####.#...##...#####.', C: '.###.#...##....#....#....#...#.###.',
+  D: '####.#...##...##...##...##...#####.', E: '######....#....####.#....#....#####', F: '######....#....####.#....#....#....',
+  G: '.###.#...##....#.####...##...#.####', H: '#...##...##...#######...##...##...#', I: '.###...#....#....#....#....#...###.',
+  J: '..###...#....#....#....#.#..#..##..', K: '#...##..#.#.#..##...#.#..#..#.#...#', L: '#....#....#....#....#....#....#####',
+  M: '#...###.###.#.##.#.##...##...##...#', N: '#...##...###..##.#.##..###...##...#', O: '.###.#...##...##...##...##...#.###.',
+  P: '####.#...##...#####.#....#....#....', Q: '.###.#...##...##...##.#.##..#..##.#', R: '####.#...##...#####.#.#..#..#.#...#',
+  S: '.#####....#.....###.....#....#####.', T: '#####..#....#....#....#....#....#..', U: '#...##...##...##...##...##...#.###.',
+  V: '#...##...##...##...##...#.#.#...#..', W: '#...##...##...##.#.##.#.##.#.#.#.#.', X: '#...##...#.#.#...#...#.#.#...##...#',
+  Y: '#...##...#.#.#...#....#....#....#..', Z: '#####....#...#...#...#...#....#####', '0': '.###.#...##..###.#.###..##...#.###.',
+  '1': '..#...##....#....#....#....#...###.', '2': '.###.#...#....#...#...#...#...#####', '3': '#####...#...#.....#.....##...#.###.',
+  '4': '...#...##..#.#.#..#.#####...#....#.', '5': '######....####.....#....##...#.###.', '6': '..##..#...#....####.#...##...#.###.',
+  '7': '#####....#...#...#...#....#....#...', '8': '.###.#...##...#.###.#...##...#.###.', '9': '.###.#...##...#.####....#...#..##..',
+  '.': '..........................##...##..', ',': '.....................##....#...#...', '!': '..#....#....#....#....#.........#..',
+  '?': '.###.#...#....#...#...#.........#..', '-': '................###................', ':': '......##...##........##...##.......',
+  ';': '......##...##........##....#...#...', "'": '..#....#...#.......................', '"': '.#.#..#.#..#.#.....................',
+  '/': '.........#...#...#...#...#.........', '&': '.##..#..#.#.#...#...#.#.##..#..##.#', '+': '.......#....#..#####..#....#.......',
+  '=': '..........#####.....#####..........', '(': '...#...#...#....#....#.....#.....#.', ')': '.#.....#.....#....#....#...#...#...',
+  '#': '.#.#..#.#.#####.#.#.#####.#.#..#.#.', '@': '.###.#...##.####.#.##.####.....###.', '%': '##...##..#...#...#...#...#..##...##',
+  '*': '.......#..#.#.#.###.#.#.#..#.......', _: '..............................#####', '<': '...#...#...#...#.....#.....#.....#.',
+  '>': '.#.....#.....#.....#...#...#...#...', '[': '.###..#....#....#....#....#....###.', ']': '.###....#....#....#....#....#..###.',
+  '|': '..#....#....#....#....#....#....#..', '$': '..#...#####.#...###...#.#####...#..', '·': '.................#.................',
+});
+
+/** Cell size, font units. */
+const CELL = 100;
+
+/** Glyph id per character (1-based; 0 is missing), and back. */
+const CHARS = Object.keys(BITMAPS);
+const GID = new Map(CHARS.map((c, i) => [c, i + 1]));
+const SPACE = CHARS.length + 1;
+
+/**
+ * A bitmap's cells as path data, row runs merged: font units, y up,
+ * baseline 0.
+ *
+ * @param {string} bits - 35 cells, row by row from the top.
+ * @returns {string}
+ */
+function cellsPath(bits) {
+  let d = '';
+  for (let row = 0; row < 7; row++) {
+    const top = (7 - row) * CELL;
+    for (let col = 0; col < 5; col++) {
+      if (bits[row * 5 + col] !== '#') continue;
+      let end = col;
+      while (end + 1 < 5 && bits[row * 5 + end + 1] === '#') end++;
+      const x0 = col * CELL;
+      const x1 = (end + 1) * CELL;
+      d += `M${x0},${top}L${x1},${top}L${x1},${top - CELL}L${x0},${top - CELL}Z`;
+      col = end;
+    }
+  }
+  return d;
+}
+
+/** @type {Map<number, string>} */
+const PATHS = new Map(CHARS.map((c, i) => [i + 1, cellsPath(BITMAPS[c])]));
+
+/** @type {any} */
+let face;
+
+/**
+ * The pixel face, shaped and outlined in JavaScript (no font file).
+ *
+ * @returns {import('../fonts.js').LoadedFont}
+ */
+export function pixelFace() {
+  face ??= {
+    name: 'pixel',
+    weight: 400,
+    style: 'normal',
+    font: null,
+    upem: 1000,
+    ascender: 800,
+    descender: -200,
+    capHeight: 7 * CELL,
+    paths: new Map(),
+    axes: {},
+    variations: {},
+    source: { name: 'pixel', src: 'covers:pixel', weight: 400 },
+    glyphToPath: (/** @type {number} */ gid) => PATHS.get(gid) ?? '',
+    shapeRun: (/** @type {string} */ text) => Array.from(text).map((ch, i) => {
+      const c = BITMAPS[ch] ? ch : ch.toUpperCase();
+      const gid = ch === ' ' ? SPACE : GID.get(c) ?? 0;
+      return { gid, cluster: i, xAdvance: ch === ' ' ? 4 * CELL : 6 * CELL, xOffset: 0, yOffset: 0 };
+    }),
+  };
+  return face;
+}
+
+/** Characters the pixel face draws. */
+export const PIXEL_CHARS = Object.freeze(CHARS.join(''));
+
+/**
+ * A glyph's 5×7 bitmap (35 cells row by row, `#` inked), or undefined.
+ *
+ * @param {string} ch
+ * @returns {string | undefined}
+ */
+export const pixelBitmap = (ch) => (Object.hasOwn(BITMAPS, ch.toUpperCase()) ? BITMAPS[ch.toUpperCase()] : undefined);