@glissade/core 0.11.0-pre.1 → 0.12.0-pre.0

package/dist/clips.d.ts

@@ -0,0 +1,114 @@
+import { J as EaseSpec, T as ValueTypeId, r as Track, t as Key } from "./track.js";
+import { r as TweenTarget } from "./targetRef.js";
+
+//#region src/clip.d.ts
+
+/**
+ * One channel of a clip: a relative-time key schedule (t from 0) plus the default
+ * target-suffix it binds to and an optional value type. `type` defaults via
+ * `inferValueType(keys[0].value)` at apply-time.
+ */
+interface ClipChannel<T = unknown> {
+  /** Relative-time keys; `t` runs from 0. Strictly-increasing t enforced at apply. */
+  keys: Key<T>[];
+  /** Default target suffix, e.g. 'opacity', 'scale', 'position'. */
+  path: string;
+  /** Registered value type; defaults to inferValueType(keys[0].value). */
+  type?: ValueTypeId;
+}
+/** A clip spec: a bag of named channels. */
+interface ClipSpec {
+  channels: Record<string, ClipChannel>;
+}
+/**
+ * Per-channel value/ease substitution. Keeps the channel's key TOPOLOGY — the
+ * first key's value becomes `from`, the last key's value becomes `to`, and `ease`
+ * replaces the arriving ease of the LAST segment. No keys are added or removed
+ * (0.12 scope).
+ */
+interface ChannelOverride<T = unknown> {
+  from?: T;
+  to?: T;
+  ease?: EaseSpec;
+}
+interface ApplyOpts {
+  /** Per-channel value/ease substitution (topology-preserving). */
+  overrides?: Record<string, ChannelOverride>;
+  /** Divides every relative `t` (speed 2 = half-time). Must be > 0. */
+  speed?: number;
+}
+interface ClipResult {
+  tracks: Track[];
+  /** Wall-clock end second of the longest channel. */
+  end: number;
+}
+/**
+ * A per-channel target map for `apply`: each channel name maps to a `TweenTarget`
+ * (string or property signal) overriding the channel's default-path resolution —
+ * e.g. a `glow` channel → `'card-halo/opacity'`. The string form of `apply` is a
+ * strict superset of this (it resolves every channel against ONE node id).
+ */
+type ClipTarget = string | Record<string, TweenTarget>;
+declare class ClipError extends Error {
+  constructor(message: string);
+}
+/** A compiled clip: the spec plus `apply`/`duration`. */
+interface Clip {
+  readonly spec: ClipSpec;
+  /** Longest channel's last relative key time (the clip's intrinsic length). */
+  readonly duration: number;
+  apply(target: ClipTarget, startSec: number, opts?: ApplyOpts): ClipResult;
+}
+/**
+ * Build a clip from a spec. Pure: holds no state; `apply` returns fresh tracks.
+ *
+ *   const fade = clip({ channels: { fade: { keys: [key(0, 0), key(0.3, 1)], path: 'opacity' } } });
+ *   const { tracks, end } = fade.apply('card', 1.0);   // → 'card/opacity' track at t∈[1.0,1.3]
+ */
+declare function clip(spec: ClipSpec): Clip;
+/** Per-target list fan-out delay — reuses the `stagger` shape/semantics. */
+type ClipListDelay = number | ((index: number) => number);
+interface ClipListOpts extends ApplyOpts {
+  /** Per-index offset (seconds), or a function of the index. Default 0. */
+  stagger?: ClipListDelay;
+}
+/**
+ * Fan a clip out over a list of targets, offsetting child i by a `stagger`-style
+ * delay (REUSES the existing `stagger` shape/semantics — number per-index gap, or
+ * a function of the index). `end` is the max child end.
+ *
+ *   clipList(popIn(), items.map((it) => it.id), 0, { stagger: 0.08 })
+ */
+declare function clipList(c: Clip, targets: readonly ClipTarget[], startSec: number, opts?: ClipListOpts): ClipResult;
+//#endregion
+//#region src/clipStdlib.d.ts
+interface DurationOpts {
+  /** Total clip length in seconds. */
+  duration?: number;
+  /** Arriving ease of the motion. */
+  ease?: EaseSpec;
+}
+/** Entrance: opacity 0→1 and scale 0.8→1 (a "pop" in). */
+declare function popIn(opts?: DurationOpts): Clip;
+type SlideEdge = 'left' | 'right' | 'top' | 'bottom';
+/**
+ * Entrance: fade in while sliding a position OFFSET in from one edge. The offset
+ * channel binds to a `position` suffix by default and animates a vec2 from the
+ * edge-displaced point to [0,0], so it composes as a local translation.
+ */
+declare function slideIn(edge: SlideEdge, opts?: (DurationOpts & {
+  distance?: number;
+})): Clip;
+/** Emphasis: a single scale up-and-back pulse. First/last value match (loopable). */
+declare function pulse(opts?: (DurationOpts & {
+  scale?: number;
+})): Clip;
+/**
+ * Ambient: a slow position drift out and back. First/last value match, so tiling
+ * (clipList or repeat) reads as a continuous loop with no seam.
+ */
+declare function driftLoop(opts?: (DurationOpts & {
+  amplitude?: number;
+})): Clip;
+//#endregion
+export { type ApplyOpts, type ApplyOpts as ClipApplyOpts, type ChannelOverride, type Clip, type ClipChannel, ClipError, type ClipListDelay, type ClipListOpts, type ClipResult, type ClipSpec, type ClipTarget, type DurationOpts, type SlideEdge, clip, clipList, driftLoop, popIn, pulse, slideIn };

package/dist/clips.js

@@ -0,0 +1,208 @@
+import { i as resolveTweenTarget, p as track, s as key, x as inferValueType } from "./targetRef.js";
+//#region src/clip.ts
+/**
+* Motion clips (DESIGN.md §2 build-time sugar): `clip()` captures a relative-time
+* key schedule over named prop CHANNELS; `clip.apply()` compiles to ordinary keyed
+* `Track[]` at apply-time — authoring SUGAR exactly like `springTo`/`stagger`, NOT a
+* runtime concept and NOT part of the serialized Timeline document. Emitted tracks
+* are BYTE-INDISTINGUISHABLE from hand-authored `track(...)`: every channel compiles
+* through `track(target, type, keys)`, so `validateTrack` runs and the output is
+* deep-equal to the literal form.
+*
+* The binding shape locked here (the channel-spec + apply signature) is FROZEN for
+* the later 1.0 cards (presence / each / morph), which inherit it.
+*/
+var ClipError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ClipError";
+	}
+};
+function channelDuration(ch) {
+	return ch.keys.length === 0 ? 0 : ch.keys[ch.keys.length - 1].t;
+}
+/**
+* Resolve a channel's canonical track target. A string `target` resolves every
+* channel against the single node id (`'<nodeId>/<channel.path>'`); a map looks
+* the channel up and resolves the supplied `TweenTarget` directly (free rejection
+* of structural / anonymous ids via `resolveTweenTarget`).
+*/
+function resolveChannelTarget(target, channel, path) {
+	if (typeof target === "string") return resolveTweenTarget(`${target}/${path}`);
+	const override = target[channel];
+	if (override === void 0) throw new ClipError(`clip target map is missing channel '${channel}' — provide a target for every channel, or pass a node-id string`);
+	return resolveTweenTarget(override);
+}
+/**
+* Compile ONE channel into a hand-authored-equivalent `Track`. Applies the
+* override (value/ease) topology-preservingly, then scales relative `t` by
+* `1/speed` and offsets by `startSec`. Routes through `track()` so `validateTrack`
+* runs (strictly-increasing t, hold-canonicalize) and the output is byte-identical
+* to the literal `track(target, type, keys)` form.
+*/
+function compileChannel(target, ch, startSec, speed, override) {
+	if (ch.keys.length === 0) throw new ClipError(`clip channel '${target}' has no keys`);
+	const type = ch.type ?? inferValueType(ch.keys[0].value);
+	const lastIdx = ch.keys.length - 1;
+	return track(target, type, ch.keys.map((k, i) => {
+		let value = k.value;
+		if (override) {
+			if (i === 0 && override.from !== void 0) value = override.from;
+			if (i === lastIdx && override.to !== void 0) value = override.to;
+		}
+		const out = {
+			t: startSec + k.t / speed,
+			value
+		};
+		const ease = override && i === lastIdx && override.ease !== void 0 ? override.ease : k.ease;
+		if (ease !== void 0) out.ease = ease;
+		if (k.interp !== void 0) out.interp = k.interp;
+		if (k.id !== void 0) out.id = k.id;
+		if (k.derived !== void 0) out.derived = k.derived;
+		return out;
+	}));
+}
+/**
+* Build a clip from a spec. Pure: holds no state; `apply` returns fresh tracks.
+*
+*   const fade = clip({ channels: { fade: { keys: [key(0, 0), key(0.3, 1)], path: 'opacity' } } });
+*   const { tracks, end } = fade.apply('card', 1.0);   // → 'card/opacity' track at t∈[1.0,1.3]
+*/
+function clip(spec) {
+	const names = Object.keys(spec.channels);
+	if (names.length === 0) throw new ClipError("clip() requires at least one channel");
+	let duration = 0;
+	for (const name of names) {
+		const ch = spec.channels[name];
+		if (ch.keys.length === 0) throw new ClipError(`clip channel '${name}' has no keys`);
+		duration = Math.max(duration, channelDuration(ch));
+	}
+	function apply(target, startSec, opts) {
+		const speed = opts?.speed ?? 1;
+		if (!(speed > 0)) throw new ClipError(`clip speed must be > 0 (got ${speed})`);
+		const overrides = opts?.overrides;
+		const tracks = [];
+		let end = startSec;
+		for (const name of names) {
+			const ch = spec.channels[name];
+			const trackTarget = resolveChannelTarget(target, name, ch.path);
+			tracks.push(compileChannel(trackTarget, ch, startSec, speed, overrides?.[name]));
+			end = Math.max(end, startSec + channelDuration(ch) / speed);
+		}
+		if (overrides) {
+			for (const name of Object.keys(overrides)) if (!(name in spec.channels)) throw new ClipError(`clip override references unknown channel '${name}'`);
+		}
+		return {
+			tracks,
+			end
+		};
+	}
+	return {
+		spec,
+		duration,
+		apply
+	};
+}
+/**
+* Fan a clip out over a list of targets, offsetting child i by a `stagger`-style
+* delay (REUSES the existing `stagger` shape/semantics — number per-index gap, or
+* a function of the index). `end` is the max child end.
+*
+*   clipList(popIn(), items.map((it) => it.id), 0, { stagger: 0.08 })
+*/
+function clipList(c, targets, startSec, opts) {
+	const delay = opts?.stagger ?? 0;
+	const at = typeof delay === "function" ? delay : (i) => i * delay;
+	const { stagger: _stagger, ...applyOpts } = opts ?? {};
+	const tracks = [];
+	let end = startSec;
+	targets.forEach((target, i) => {
+		const r = c.apply(target, startSec + at(i), applyOpts);
+		tracks.push(...r.tracks);
+		if (r.end > end) end = r.end;
+	});
+	return {
+		tracks,
+		end
+	};
+}
+//#endregion
+//#region src/clipStdlib.ts
+/**
+* Stdlib motion clips (DESIGN.md §2 build-time sugar): a small set of `clip(...)`
+* literals for the common entrance / emphasis / ambient motions. Tree-shakeable —
+* shipped from the `@glissade/core/clips` SUB-PATH, never the base index, because
+* the keyframe literals are the byte weight (the base core budget is tight).
+*
+* Loop clips (`pulse`, `driftLoop`) author first-key-value == last-key-value, so
+* tiling them under `clipList` (or repeating the clip) reads seamlessly.
+*/
+/** Entrance: opacity 0→1 and scale 0.8→1 (a "pop" in). */
+function popIn(opts) {
+	const d = opts?.duration ?? .3;
+	const ease = opts?.ease ?? "easeOutCubic";
+	return clip({ channels: {
+		opacity: {
+			path: "opacity",
+			keys: [key(0, 0), key(d, 1, ease)]
+		},
+		scale: {
+			path: "scale",
+			keys: [key(0, .8), key(d, 1, ease)]
+		}
+	} });
+}
+/**
+* Entrance: fade in while sliding a position OFFSET in from one edge. The offset
+* channel binds to a `position` suffix by default and animates a vec2 from the
+* edge-displaced point to [0,0], so it composes as a local translation.
+*/
+function slideIn(edge, opts) {
+	const d = opts?.duration ?? .3;
+	const ease = opts?.ease ?? "easeOutCubic";
+	const dist = opts?.distance ?? 40;
+	const from = edge === "left" ? [-dist, 0] : edge === "right" ? [dist, 0] : edge === "top" ? [0, -dist] : [0, dist];
+	return clip({ channels: {
+		opacity: {
+			path: "opacity",
+			keys: [key(0, 0), key(d, 1, ease)]
+		},
+		offset: {
+			path: "position",
+			keys: [key(0, from), key(d, [0, 0], ease)]
+		}
+	} });
+}
+/** Emphasis: a single scale up-and-back pulse. First/last value match (loopable). */
+function pulse(opts) {
+	const d = opts?.duration ?? .4;
+	const ease = opts?.ease ?? "easeInOutSine";
+	const peak = opts?.scale ?? 1.1;
+	return clip({ channels: { scale: {
+		path: "scale",
+		keys: [
+			key(0, 1),
+			key(d / 2, peak, ease),
+			key(d, 1, ease)
+		]
+	} } });
+}
+/**
+* Ambient: a slow position drift out and back. First/last value match, so tiling
+* (clipList or repeat) reads as a continuous loop with no seam.
+*/
+function driftLoop(opts) {
+	const d = opts?.duration ?? 2;
+	const ease = opts?.ease ?? "easeInOutSine";
+	const a = opts?.amplitude ?? 8;
+	return clip({ channels: { drift: {
+		path: "position",
+		keys: [
+			key(0, [0, 0]),
+			key(d / 2, [a, 0], ease),
+			key(d, [0, 0], ease)
+		]
+	} } });
+}
+//#endregion
+export { ClipError, clip, clipList, driftLoop, popIn, pulse, slideIn };

package/dist/cmap.js

@@ -0,0 +1,112 @@
+//#region src/cmap.ts
+/**
+* Minimal sfnt `cmap` reader (DESIGN.md §3.6 glyph-coverage check) — pure,
+* byte-only, ZERO DOM / ZERO Node. Given the raw bytes of a TrueType/OpenType
+* (or the first table of a TTC) font, returns the set of Unicode code points
+* the font claims to cover. I/O (reading the file / fetching the URL) happens
+* at the call site; this function only parses bytes.
+*
+* Hand-rolled (no font-parsing dependency) to keep core zero-dep and in budget.
+* It covers the two cmap subtable formats that matter in practice:
+*   - format 4  (segment mapping to delta values — the BMP workhorse)
+*   - format 12 (segmented coverage — astral planes, e.g. emoji)
+* Malformed or unsupported input yields an empty set; it never throws or hangs.
+*/
+const PLATFORM_UNICODE = 0;
+const PLATFORM_WINDOWS = 3;
+/** Read a big-endian u16 with bounds checking (0 when out of range). */
+function u16(dv, off) {
+	return off + 2 <= dv.byteLength ? dv.getUint16(off) : 0;
+}
+function u32(dv, off) {
+	return off + 4 <= dv.byteLength ? dv.getUint32(off) : 0;
+}
+/** Rank a (platform, encoding) cmap subtable: higher = better Unicode coverage. */
+function encodingScore(platform, encoding) {
+	if (platform === PLATFORM_WINDOWS && encoding === 10) return 5;
+	if (platform === PLATFORM_UNICODE && encoding >= 4) return 5;
+	if (platform === PLATFORM_WINDOWS && encoding === 1) return 3;
+	if (platform === PLATFORM_UNICODE) return 3;
+	return 0;
+}
+function parseFormat4(dv, base, into) {
+	const segCountX2 = u16(dv, base + 6);
+	const segCount = segCountX2 >> 1;
+	const endOff = base + 14;
+	const startOff = endOff + segCountX2 + 2;
+	const deltaOff = startOff + segCountX2;
+	const rangeOff = deltaOff + segCountX2;
+	for (let i = 0; i < segCount; i++) {
+		const end = u16(dv, endOff + i * 2);
+		const start = u16(dv, startOff + i * 2);
+		if (start > end) continue;
+		const idDelta = u16(dv, deltaOff + i * 2);
+		const idRangeOffset = u16(dv, rangeOff + i * 2);
+		for (let c = start; c <= end; c++) {
+			if (c === 65535) continue;
+			let glyph;
+			if (idRangeOffset === 0) glyph = c + idDelta & 65535;
+			else {
+				const g = u16(dv, rangeOff + i * 2 + idRangeOffset + (c - start) * 2);
+				glyph = g === 0 ? 0 : g + idDelta & 65535;
+			}
+			if (glyph !== 0) into.add(c);
+		}
+	}
+}
+function parseFormat12(dv, base, into) {
+	const declared = u32(dv, base + 12);
+	const maxGroups = Math.max(0, Math.floor((dv.byteLength - (base + 16)) / 12));
+	const nGroups = Math.min(declared, maxGroups);
+	let off = base + 16;
+	for (let i = 0; i < nGroups; i++, off += 12) {
+		const startChar = u32(dv, off);
+		const endChar = u32(dv, off + 4);
+		const startGlyph = u32(dv, off + 8);
+		if (startChar > endChar) continue;
+		if (endChar - startChar > 2097152) continue;
+		for (let c = startChar; c <= endChar; c++) if (startGlyph + (c - startChar) !== 0) into.add(c);
+	}
+}
+function parseCmap(bytes) {
+	const out = /* @__PURE__ */ new Set();
+	try {
+		const dv = ArrayBuffer.isView(bytes) ? new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength) : new DataView(bytes);
+		if (dv.byteLength < 12) return out;
+		let sfntOff = 0;
+		if (u32(dv, 0) === 1953784678) sfntOff = u32(dv, 12);
+		const numTables = u16(dv, sfntOff + 4);
+		let cmapOff = 0;
+		for (let i = 0; i < numTables; i++) {
+			const rec = sfntOff + 12 + i * 16;
+			if (u32(dv, rec) === 1668112752) {
+				cmapOff = u32(dv, rec + 8);
+				break;
+			}
+		}
+		if (cmapOff === 0) return out;
+		const nSub = u16(dv, cmapOff + 2);
+		let bestOff = 0;
+		let bestScore = -1;
+		for (let i = 0; i < nSub; i++) {
+			const rec = cmapOff + 4 + i * 8;
+			const platform = u16(dv, rec);
+			const encoding = u16(dv, rec + 2);
+			const subOff = cmapOff + u32(dv, rec + 4);
+			const score = encodingScore(platform, encoding);
+			if (score > bestScore && subOff + 2 <= dv.byteLength) {
+				bestScore = score;
+				bestOff = subOff;
+			}
+		}
+		if (bestScore < 0) return out;
+		const format = u16(dv, bestOff);
+		if (format === 4) parseFormat4(dv, bestOff, out);
+		else if (format === 12) parseFormat12(dv, bestOff, out);
+	} catch {
+		return out;
+	}
+	return out;
+}
+//#endregion
+export { parseCmap as t };

package/dist/font-ingest.d.ts

@@ -0,0 +1,154 @@
+import { a as FontFaceRef } from "./timeline.js";
+
+//#region src/fontIngest.d.ts
+
+/** The four sfnt/woff magic-byte families this front door understands. */
+type FontFormat = 'truetype' | 'opentype' | 'collection' | 'woff' | 'woff2';
+/** Raw bytes in any form the ingest accepts; a path is read by the caller's I/O. */
+type FontSource = Uint8Array | ArrayBuffer;
+/**
+ * A fixed variable-axis tuple to INSTANCE at (e.g. `{ wght: 600 }` or
+ * `{ wght: 600, wdth: 100 }`). Each axis is pinned to a single value, producing
+ * a static face — the parity-safe case (DESIGN §3.6). Animatable axes are
+ * deferred; an axis RANGE is intentionally not accepted here.
+ */
+type AxisTuple = Record<string, number>;
+interface RegisterFontInit {
+  /** The CSS family name to register under (the §3.6 asset-id convention). */
+  family: string;
+  /** Raw font bytes (a path is read to bytes by the caller before this point). */
+  src: FontSource;
+  weight?: number | undefined;
+  style?: 'normal' | 'italic' | undefined;
+  /**
+   * Pin these variable axes to fixed values, instancing the variable font to a
+   * single static sfnt at ingest time. Omitted → the face is used as-is.
+   */
+  axes?: AxisTuple | undefined;
+  /** Explicit fallback family chain (mirrors AssetRef.fallback). */
+  fallback?: readonly string[] | undefined;
+}
+/**
+ * The result of ingesting one face: the decoded/instanced STATIC sfnt bytes,
+ * a content hash (stable identity for caching + the asset url), the parsed
+ * coverage, and a `covers()` predicate. `toFaceRef()` / `toAssetRef()` bridge
+ * back into the serializable Timeline document the render path consumes.
+ */
+interface FontFaceResult {
+  family: string;
+  weight: number;
+  style: 'normal' | 'italic';
+  /** The decoded + (optionally) instanced static sfnt bytes (ttf/otf). */
+  bytes: Uint8Array;
+  /** Detected source format before any decode/instance. */
+  sourceFormat: FontFormat;
+  /** FNV-1a content hash of `bytes` (hex), stable across runs for equal input. */
+  hash: string;
+  /** The code points the instanced face's cmap covers. */
+  coverage: ReadonlySet<number>;
+  fallback: readonly string[];
+  /** True iff every code point in `text` is covered by this face. */
+  covers(text: string): boolean;
+  /** Code points in `text` this face does NOT cover (ascending, de-duped). */
+  missing(text: string): number[];
+}
+/** Sniff the leading 4 bytes; throws on input that is not a recognized font. */
+declare function sniffFontFormat(src: FontSource): FontFormat;
+declare class FontIngestError extends Error {
+  constructor(message: string);
+}
+/**
+ * Ingest one face: sniff → (woff2 decode) → (instance at `axes`) → a static
+ * sfnt + content hash + coverage. The heavy path (woff2 / instancing) runs
+ * hb-subset; a plain ttf/otf with no axes skips it entirely (zero-dep fast
+ * path), keeping the common case off the wasm boundary.
+ */
+declare function ingestFont(init: RegisterFontInit): Promise<FontFaceResult>;
+/** A registered face plus the bytes the render path will hand to the rasterizer. */
+interface IngestedFace extends FontFaceResult {
+  /** The `FontFaceRef` this face contributes to a Timeline AssetRef. */
+  faceRef(url: string): FontFaceRef;
+}
+/**
+ * `registerFont(...)` — the merged front door. Ingests `init` and records it in
+ * `store` (the in-process registry the render path consumes). Returns the
+ * ingested face (bytes + coverage + `covers()`); the caller decides whether to
+ * persist the static sfnt to disk (content-hashed url) and/or feed Skia.
+ */
+declare function registerFont(init: RegisterFontInit, store?: FontStore): Promise<IngestedFace>;
+/**
+ * A tiny in-process store the export/prepare path fills via `registerFont` and
+ * the renderer drains. Groups faces by family and remembers each family's
+ * declared fallback chain — the same shape `buildFontRegistry` consumes, so the
+ * programmatic and document-driven paths converge on one registry.
+ */
+declare class FontStore {
+  private readonly byFamily;
+  private readonly fallbacks;
+  add(face: IngestedFace): void;
+  families(): string[];
+  facesOf(family: string): readonly IngestedFace[];
+  fallbackOf(family: string): readonly string[];
+  /** Every ingested face across every family (the renderer registers these). */
+  all(): IngestedFace[];
+}
+/**
+ * One source entry in a `font()` plan: a file path (or raw bytes) plus the
+ * (weight, style) it represents. Paths are resolved to bytes by the ingest
+ * caller (`buildFontPlan`'s `read`), keeping this module's pure spec free of I/O.
+ */
+interface FontSrcEntry {
+  path?: string | undefined;
+  bytes?: FontSource | undefined;
+  weight?: number | undefined;
+  style?: 'normal' | 'italic' | undefined;
+}
+/** The declarative plan a `font(...).build()` produces — pure data, no I/O. */
+interface FontPlan {
+  family: string;
+  sources: FontSrcEntry[];
+  fallback: string[];
+  /** When set, every source is instanced at this fixed axis tuple. */
+  axes?: AxisTuple | undefined;
+  /** Marks the plan as a variable font (axes are expected / required). */
+  variable: boolean;
+}
+/**
+ * Fluent author-time builder for a font family (DESIGN §3.6). PURE: it only
+ * assembles a `FontPlan`; no bytes are read and no wasm is touched until the
+ * plan is ingested. Two shapes:
+ *
+ *   font('Inter').src('Inter.ttf').weights([400, 600, 700]).fallback(['Arial']).build()
+ *   font('InterVar').src('InterVar.woff2').variable().axis('wght', 600).build()
+ *
+ * `.weights([...])` is sugar for "the same src at each of these weights" only
+ * when a single src is given; with explicit per-weight `.src(path, weight)`
+ * calls it is ignored in favor of the explicit entries.
+ */
+interface FontBuilder {
+  src(path: string, opts?: {
+    weight?: number;
+    style?: 'normal' | 'italic';
+  }): FontBuilder;
+  bytes(data: FontSource, opts?: {
+    weight?: number;
+    style?: 'normal' | 'italic';
+  }): FontBuilder;
+  weights(weights: readonly number[]): FontBuilder;
+  fallback(families: readonly string[]): FontBuilder;
+  /** Mark this family as variable (axes are pinned via `.axis()`). */
+  variable(): FontBuilder;
+  /** Pin a variable axis to a fixed value (static instancing). */
+  axis(tag: string, value: number): FontBuilder;
+  build(): FontPlan;
+}
+declare function font(family: string): FontBuilder;
+/**
+ * Ingest a whole `FontPlan` into `store`. `read` resolves a source path to bytes
+ * (the I/O seam — the CLI reads files, a bundler plugin could fetch). Every
+ * source becomes one ingested face under the plan's family; the family fallback
+ * is attached to the first face so the store records it once.
+ */
+declare function buildFontPlan(plan: FontPlan, read: (path: string) => Promise<FontSource>, store?: FontStore): Promise<IngestedFace[]>;
+//#endregion
+export { type AxisTuple, type FontBuilder, type FontFaceResult, type FontFormat, FontIngestError, type FontPlan, type FontSource, type FontSrcEntry, FontStore, type IngestedFace, type RegisterFontInit, buildFontPlan, font, ingestFont, registerFont, sniffFontFormat };