wolfy-reader 0.1.0

package/dist/search/normalize.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Search normalization — the folding policy that decides when two strings "match"
+ * for the purpose of full-text search. Applied to both the query and the extracted
+ * section text before literal substring matching.
+ *
+ * Policy (see docs/domains/search.md ## Key decisions):
+ * - **Case-insensitive.** Folded with `toLowerCase()`.
+ * - **Unicode NFC.** Each grapheme is canonically composed, so a pre-composed `é`
+ *   and a decomposed `e`+combining-acute match.
+ * - **Diacritics are preserved.** `café` does not match `cafe`. Stripping marks is a
+ *   locale-sensitive judgement (German ä, Turkish dotless ı) better left to a later,
+ *   opt-in dimension than baked into the default.
+ * - **Smart punctuation folded to ASCII.** Curly quotes → straight, en/em dashes and
+ *   the minus sign → hyphen-minus, non-breaking and other Unicode spaces → a normal
+ *   space. A reader types `don't`, the book prints `don’t`.
+ * - **Whitespace collapsed.** Every run of whitespace (including the newlines that
+ *   land between block elements during extraction) becomes a single space, and
+ *   leading/trailing space folds off, so a query never fails on invisible layout
+ *   whitespace.
+ *
+ * The fold must stay anchorable: the matcher works on the normalized string but each
+ * hit's text and `Position` anchor into the **raw extracted** text. So the fold is
+ * built grapheme by grapheme alongside an offset map from every normalized index
+ * back to the raw UTF-16 offset it came from. The raw text handed to
+ * `capturePosition` is never NFC-rewritten (it must stay byte-identical to what the
+ * paginator measures against), so composition happens only inside the folded copy.
+ */
+/** A normalized string plus the map from its indices back to raw UTF-16 offsets. */
+export interface NormalizedText {
+    /** The folded, whitespace-collapsed text the matcher searches. */
+    readonly text: string;
+    /**
+     * `map[i]` is the raw UTF-16 offset of the character that produced normalized
+     * code unit `i`; `map[text.length]` is the raw text length. Monotonic
+     * non-decreasing, so a normalized span `[a, b)` maps to the raw span
+     * `[map[a], map[b])`.
+     */
+    readonly map: readonly number[];
+}
+/**
+ * Folds `raw` under the search policy and returns the normalized text plus the
+ * index map back to raw UTF-16 offsets. A match found in `text` maps cleanly onto a
+ * raw span for `capturePosition`.
+ */
+export declare function normalizeText(raw: string): NormalizedText;
+/** The query folded to the same space as {@link normalizeText}'s `text`. */
+export declare function normalizeQuery(query: string): string;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/search/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/search/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AA6CD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CA2BzD;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/search/normalize.js

@@ -0,0 +1,103 @@
+/**
+ * Search normalization — the folding policy that decides when two strings "match"
+ * for the purpose of full-text search. Applied to both the query and the extracted
+ * section text before literal substring matching.
+ *
+ * Policy (see docs/domains/search.md ## Key decisions):
+ * - **Case-insensitive.** Folded with `toLowerCase()`.
+ * - **Unicode NFC.** Each grapheme is canonically composed, so a pre-composed `é`
+ *   and a decomposed `e`+combining-acute match.
+ * - **Diacritics are preserved.** `café` does not match `cafe`. Stripping marks is a
+ *   locale-sensitive judgement (German ä, Turkish dotless ı) better left to a later,
+ *   opt-in dimension than baked into the default.
+ * - **Smart punctuation folded to ASCII.** Curly quotes → straight, en/em dashes and
+ *   the minus sign → hyphen-minus, non-breaking and other Unicode spaces → a normal
+ *   space. A reader types `don't`, the book prints `don’t`.
+ * - **Whitespace collapsed.** Every run of whitespace (including the newlines that
+ *   land between block elements during extraction) becomes a single space, and
+ *   leading/trailing space folds off, so a query never fails on invisible layout
+ *   whitespace.
+ *
+ * The fold must stay anchorable: the matcher works on the normalized string but each
+ * hit's text and `Position` anchor into the **raw extracted** text. So the fold is
+ * built grapheme by grapheme alongside an offset map from every normalized index
+ * back to the raw UTF-16 offset it came from. The raw text handed to
+ * `capturePosition` is never NFC-rewritten (it must stay byte-identical to what the
+ * paginator measures against), so composition happens only inside the folded copy.
+ */
+const SMART = new Map([
+    ['‘', "'"], // ‘ left single quote
+    ['’', "'"], // ’ right single quote / apostrophe
+    ['‚', "'"], // ‚ single low-9 quote
+    ['‛', "'"], // ‛ single high-reversed-9 quote
+    ['“', '"'], // “ left double quote
+    ['”', '"'], // ” right double quote
+    ['„', '"'], // „ double low-9 quote
+    ['‟', '"'], // ‟ double high-reversed-9 quote
+    ['′', "'"], // ′ prime
+    ['″', '"'], // ″ double prime
+    ['‐', '-'], // ‐ hyphen
+    ['‑', '-'], // ‑ non-breaking hyphen
+    ['‒', '-'], // ‒ figure dash
+    ['–', '-'], // – en dash
+    ['—', '-'], // — em dash
+    ['―', '-'], // ― horizontal bar
+    ['−', '-'], // − minus sign
+]);
+const WHITESPACE = /^\s$/;
+let graphemeSegmenter;
+function segmenter() {
+    graphemeSegmenter ??= new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+    return graphemeSegmenter;
+}
+/** True when every code point in a grapheme is whitespace. */
+function isWhitespace(grapheme) {
+    for (const ch of grapheme) {
+        if (!WHITESPACE.test(ch) && ch !== '​' && ch !== '')
+            return false;
+    }
+    return true;
+}
+/** Folds a single grapheme under the punctuation/NFC/case policy. */
+function foldGrapheme(grapheme) {
+    const mapped = grapheme.length === 1 ? (SMART.get(grapheme) ?? grapheme) : grapheme;
+    return mapped.normalize('NFC').toLowerCase();
+}
+/**
+ * Folds `raw` under the search policy and returns the normalized text plus the
+ * index map back to raw UTF-16 offsets. A match found in `text` maps cleanly onto a
+ * raw span for `capturePosition`.
+ */
+export function normalizeText(raw) {
+    let text = '';
+    const map = [];
+    let pendingSpace = false;
+    let sawNonSpace = false;
+    let rawOffset = 0;
+    for (const { segment } of segmenter().segment(raw)) {
+        if (isWhitespace(segment)) {
+            if (sawNonSpace)
+                pendingSpace = true;
+            rawOffset += segment.length;
+            continue;
+        }
+        if (pendingSpace) {
+            map.push(rawOffset); // the collapsed space anchors at the start of the text it precedes
+            text += ' ';
+            pendingSpace = false;
+        }
+        const folded = foldGrapheme(segment);
+        for (let unit = 0; unit < folded.length; unit += 1)
+            map.push(rawOffset);
+        text += folded;
+        sawNonSpace = true;
+        rawOffset += segment.length;
+    }
+    map.push(raw.length); // trailing whitespace folds off; the terminal maps to raw end
+    return { text, map };
+}
+/** The query folded to the same space as {@link normalizeText}'s `text`. */
+export function normalizeQuery(query) {
+    return normalizeText(query).text;
+}
+//# sourceMappingURL=normalize.js.map

package/dist/search/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/search/normalize.ts"],"names":[],"mappings":"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"}

package/dist/view/allowlist.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What is allowed to survive sanitization, stated as allowlists.
+ *
+ * A blocklist loses to the next vector the platform invents; an allowlist only
+ * ever loses formatting. Anything absent from these tables is either unwrapped
+ * (the element goes, its text stays — a book is text before it is markup) or,
+ * when its children are not readable content, discarded whole.
+ */
+export declare const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+export declare const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+export declare const XLINK_NAMESPACE = "http://www.w3.org/1999/xlink";
+export declare const HTML_GLOBAL_ATTRIBUTES: ReadonlySet<string>;
+export declare const HTML_ELEMENTS: ReadonlyMap<string, ReadonlySet<string>>;
+/**
+ * Elements that go with everything inside them, because their children are not
+ * prose: raw-text elements whose content is source rather than text, form
+ * controls, and void elements with no children to keep.
+ *
+ * Everything else absent from the allowlist is *unwrapped* instead — the
+ * element goes, its text stays. That distinction is load-bearing twice over. A
+ * book is text before it is markup, and a malformed one nests half a chapter
+ * inside a stray element: an </noscript> end tag after an open <p> is ignored
+ * by the HTML parser, so an unclosed <noscript> swallows everything after it,
+ * and discarding that element would delete the rest of the chapter.
+ *
+ * <noscript> is also why unwrapping is the safer option and not merely the
+ * kinder one. Its content is markup when a document is parsed with scripting
+ * off and raw text when it is parsed with scripting on, so an element that
+ * survives into the frame is re-read in the other mode and attribute
+ * boundaries move under it — the mutation-XSS shape this pipeline exists to
+ * defeat. Removing the element removes the reinterpretation.
+ *
+ * The table itself lives in `src/core/reading-text.ts` (re-exported here under
+ * its frozen name): discarding decides not only what renders but what the
+ * frame's *text* is, and the headless search extractor must mirror it exactly
+ * so a hit's anchor exists in the text the frame resolves against. One table,
+ * two consumers — never fork it.
+ */
+export { DISCARDED_HTML_ELEMENTS as HTML_DISCARDED } from '../core/reading-text.ts';
+export declare const SVG_GLOBAL_ATTRIBUTES: ReadonlySet<string>;
+export declare const SVG_ELEMENTS: ReadonlyMap<string, ReadonlySet<string>>;
+/**
+ * SMIL animation is on this list, not merely absent from the allowlist, because
+ * `<animate attributeName="href" to="javascript:...">` turns an inert element
+ * into a live one after sanitization has already run.
+ *
+ * Shared from `src/core/reading-text.ts` for the same reason as HTML_DISCARDED:
+ * the search extractor mirrors what discarding removes from the frame's text.
+ */
+export { DISCARDED_SVG_ELEMENTS as SVG_DISCARDED } from '../core/reading-text.ts';
+/** Attributes carrying a reference, by element local name. */
+export declare const URL_ATTRIBUTES: ReadonlyMap<string, ReadonlySet<string>>;
+/**
+ * Whether a reference may stay on the attribute at all. Relative references are
+ * kept so they can be resolved to blob URLs; remote ones are kept so CSP is the
+ * layer that refuses them, and refuses them observably.
+ */
+export declare function isAllowedReference(element: string, attribute: string, kind: string, scheme: string | undefined): boolean;
+//# sourceMappingURL=allowlist.d.ts.map

package/dist/view/allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.d.ts","sourceRoot":"","sources":["../../src/view/allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,eAAO,MAAM,cAAc,iCAAiC,CAAC;AAC7D,eAAO,MAAM,aAAa,+BAA+B,CAAC;AAC1D,eAAO,MAAM,eAAe,iCAAiC,CAAC;AAE9D,eAAO,MAAM,sBAAsB,qBAYlC,CAAC;AAIF,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CA8EjE,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,uBAAuB,IAAI,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEpF,eAAO,MAAM,qBAAqB,qBAuCjC,CAAC;AAoBF,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CA2BhE,CAAC;AAEH;;;;;;;GAOG;AACH,OAAO,EAAE,sBAAsB,IAAI,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAElF,8DAA8D;AAC9D,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAUlE,CAAC;AAKH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAWxH"}

package/dist/view/allowlist.js

@@ -0,0 +1,198 @@
+/**
+ * What is allowed to survive sanitization, stated as allowlists.
+ *
+ * A blocklist loses to the next vector the platform invents; an allowlist only
+ * ever loses formatting. Anything absent from these tables is either unwrapped
+ * (the element goes, its text stays — a book is text before it is markup) or,
+ * when its children are not readable content, discarded whole.
+ */
+function set(...names) {
+    return new Set(names);
+}
+const NONE = new Set();
+export const HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml';
+export const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+export const XLINK_NAMESPACE = 'http://www.w3.org/1999/xlink';
+export const HTML_GLOBAL_ATTRIBUTES = set('class', 'dir', 'epub:type', 'hidden', 'id', 'lang', 'role', 'style', 'title', 'translate', 'xml:lang');
+const CELL = set('abbr', 'align', 'colspan', 'headers', 'rowspan', 'scope', 'valign', 'width');
+export const HTML_ELEMENTS = new Map([
+    ['a', set('href')],
+    ['abbr', NONE],
+    ['address', NONE],
+    ['article', NONE],
+    ['aside', NONE],
+    ['b', NONE],
+    ['bdi', NONE],
+    ['bdo', NONE],
+    ['big', NONE],
+    ['blockquote', set('cite')],
+    ['br', NONE],
+    ['caption', set('align')],
+    ['center', NONE],
+    ['cite', NONE],
+    ['code', NONE],
+    ['col', set('align', 'span', 'valign', 'width')],
+    ['colgroup', set('align', 'span', 'valign', 'width')],
+    ['dd', NONE],
+    ['del', set('cite', 'datetime')],
+    ['details', set('open')],
+    ['dfn', NONE],
+    ['div', NONE],
+    ['dl', NONE],
+    ['dt', NONE],
+    ['em', NONE],
+    ['figcaption', NONE],
+    ['figure', NONE],
+    ['footer', NONE],
+    ['h1', NONE],
+    ['h2', NONE],
+    ['h3', NONE],
+    ['h4', NONE],
+    ['h5', NONE],
+    ['h6', NONE],
+    ['header', NONE],
+    ['hgroup', NONE],
+    ['hr', NONE],
+    ['i', NONE],
+    ['img', set('alt', 'height', 'src', 'width')],
+    ['ins', set('cite', 'datetime')],
+    ['kbd', NONE],
+    ['li', set('value')],
+    ['link', set('href', 'media', 'rel', 'type')],
+    ['main', NONE],
+    ['mark', NONE],
+    ['nav', NONE],
+    ['ol', set('reversed', 'start', 'type')],
+    ['p', NONE],
+    ['pre', NONE],
+    ['q', set('cite')],
+    ['rp', NONE],
+    ['rt', NONE],
+    ['ruby', NONE],
+    ['s', NONE],
+    ['samp', NONE],
+    ['section', NONE],
+    ['small', NONE],
+    ['span', NONE],
+    ['strike', NONE],
+    ['strong', NONE],
+    ['style', set('media', 'type')],
+    ['sub', NONE],
+    ['summary', NONE],
+    ['sup', NONE],
+    ['table', set('align', 'border', 'cellpadding', 'cellspacing', 'summary', 'width')],
+    ['tbody', set('align', 'valign')],
+    ['td', CELL],
+    ['tfoot', set('align', 'valign')],
+    ['th', CELL],
+    ['thead', set('align', 'valign')],
+    ['time', set('datetime')],
+    ['tr', set('align', 'valign')],
+    ['tt', NONE],
+    ['u', NONE],
+    ['ul', NONE],
+    ['var', NONE],
+    ['wbr', NONE],
+]);
+/**
+ * Elements that go with everything inside them, because their children are not
+ * prose: raw-text elements whose content is source rather than text, form
+ * controls, and void elements with no children to keep.
+ *
+ * Everything else absent from the allowlist is *unwrapped* instead — the
+ * element goes, its text stays. That distinction is load-bearing twice over. A
+ * book is text before it is markup, and a malformed one nests half a chapter
+ * inside a stray element: an </noscript> end tag after an open <p> is ignored
+ * by the HTML parser, so an unclosed <noscript> swallows everything after it,
+ * and discarding that element would delete the rest of the chapter.
+ *
+ * <noscript> is also why unwrapping is the safer option and not merely the
+ * kinder one. Its content is markup when a document is parsed with scripting
+ * off and raw text when it is parsed with scripting on, so an element that
+ * survives into the frame is re-read in the other mode and attribute
+ * boundaries move under it — the mutation-XSS shape this pipeline exists to
+ * defeat. Removing the element removes the reinterpretation.
+ *
+ * The table itself lives in `src/core/reading-text.ts` (re-exported here under
+ * its frozen name): discarding decides not only what renders but what the
+ * frame's *text* is, and the headless search extractor must mirror it exactly
+ * so a hit's anchor exists in the text the frame resolves against. One table,
+ * two consumers — never fork it.
+ */
+export { DISCARDED_HTML_ELEMENTS as HTML_DISCARDED } from '../core/reading-text.js';
+export const SVG_GLOBAL_ATTRIBUTES = set('class', 'clip-path', 'clip-rule', 'color', 'display', 'dominant-baseline', 'fill', 'fill-opacity', 'fill-rule', 'font-family', 'font-size', 'font-style', 'font-weight', 'id', 'lang', 'letter-spacing', 'mask', 'opacity', 'overflow', 'paint-order', 'role', 'shape-rendering', 'space', 'stop-color', 'stop-opacity', 'stroke', 'stroke-dasharray', 'stroke-dashoffset', 'stroke-linecap', 'stroke-linejoin', 'stroke-opacity', 'stroke-width', 'style', 'text-anchor', 'transform', 'vector-effect', 'visibility', 'word-spacing');
+const GRADIENT = set('cx', 'cy', 'fr', 'fx', 'fy', 'gradientTransform', 'gradientUnits', 'r', 'spreadMethod', 'x1', 'x2', 'y1', 'y2');
+const TEXT_POSITION = set('dx', 'dy', 'rotate', 'textLength', 'x', 'y');
+export const SVG_ELEMENTS = new Map([
+    ['a', set('href')],
+    ['circle', set('cx', 'cy', 'r')],
+    ['clipPath', set('clipPathUnits')],
+    ['defs', NONE],
+    ['desc', NONE],
+    ['ellipse', set('cx', 'cy', 'rx', 'ry')],
+    ['g', NONE],
+    ['image', set('height', 'href', 'preserveAspectRatio', 'width', 'x', 'y')],
+    ['line', set('x1', 'x2', 'y1', 'y2')],
+    ['linearGradient', GRADIENT],
+    ['marker', set('markerHeight', 'markerUnits', 'markerWidth', 'orient', 'refX', 'refY', 'viewBox')],
+    ['mask', set('height', 'maskContentUnits', 'maskUnits', 'width', 'x', 'y')],
+    ['path', set('d', 'pathLength')],
+    ['pattern', set('height', 'patternContentUnits', 'patternTransform', 'patternUnits', 'viewBox', 'width', 'x', 'y')],
+    ['polygon', set('points')],
+    ['polyline', set('points')],
+    ['radialGradient', GRADIENT],
+    ['rect', set('height', 'rx', 'ry', 'width', 'x', 'y')],
+    ['stop', set('offset')],
+    ['style', set('media', 'type')],
+    ['svg', set('height', 'preserveAspectRatio', 'version', 'viewBox', 'width', 'x', 'y')],
+    ['symbol', set('preserveAspectRatio', 'viewBox')],
+    ['text', TEXT_POSITION],
+    ['title', NONE],
+    ['tspan', TEXT_POSITION],
+    ['use', set('height', 'href', 'width', 'x', 'y')],
+]);
+/**
+ * SMIL animation is on this list, not merely absent from the allowlist, because
+ * `<animate attributeName="href" to="javascript:...">` turns an inert element
+ * into a live one after sanitization has already run.
+ *
+ * Shared from `src/core/reading-text.ts` for the same reason as HTML_DISCARDED:
+ * the search extractor mirrors what discarding removes from the frame's text.
+ */
+export { DISCARDED_SVG_ELEMENTS as SVG_DISCARDED } from '../core/reading-text.js';
+/** Attributes carrying a reference, by element local name. */
+export const URL_ATTRIBUTES = new Map([
+    ['a', set('href')],
+    ['blockquote', set('cite')],
+    ['del', set('cite')],
+    ['image', set('href')],
+    ['img', set('src')],
+    ['ins', set('cite')],
+    ['link', set('href')],
+    ['q', set('cite')],
+    ['use', set('href')],
+]);
+const LINK_SCHEMES = set('http', 'https', 'mailto', 'tel');
+const MEDIA_SCHEMES = set('data', 'http', 'https');
+/**
+ * Whether a reference may stay on the attribute at all. Relative references are
+ * kept so they can be resolved to blob URLs; remote ones are kept so CSP is the
+ * layer that refuses them, and refuses them observably.
+ */
+export function isAllowedReference(element, attribute, kind, scheme) {
+    // <use href> reaches into the same document and nowhere else: a data: URI
+    // there is a document-injection vector, not an image reference.
+    if (element === 'use')
+        return kind === 'fragment';
+    if (kind === 'fragment')
+        return element === 'a';
+    if (kind === 'relative')
+        return true;
+    if (kind !== 'scheme' || scheme === undefined)
+        return false;
+    if (attribute === 'src' || (element === 'image' && attribute === 'href') || element === 'link') {
+        return MEDIA_SCHEMES.has(scheme);
+    }
+    return LINK_SCHEMES.has(scheme);
+}
+//# sourceMappingURL=allowlist.js.map

package/dist/view/allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.js","sourceRoot":"","sources":["../../src/view/allowlist.ts"],"names":[],"mappings":"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"}

package/dist/view/appearance.d.ts

@@ -0,0 +1,137 @@
+/** A built-in theme name, or `'custom'` for a caller-supplied variable set. */
+export type ThemeName = 'light' | 'dark' | 'sepia' | 'custom';
+/** Text alignment for body prose: publisher default, ragged left, or justified. */
+export type TextAlign = 'start' | 'justify';
+/**
+ * The live appearance state: the theme half (content colours) plus the typography
+ * half (font, size, line height, margin, alignment, hyphenation, columns). Both
+ * flow through the same `--wr-*` namespace and the same cascade, so publisher CSS
+ * can restyle its own content but can never reach an appearance variable.
+ * `customProperties` supplies bespoke `--wr-*` values that merge over the resolved
+ * theme (they win), so a `'custom'` theme is any override set and the built-in
+ * themes are equally overridable.
+ */
+export interface Appearance {
+    /**
+     * Which theme drives content colours. Omitted (or `undefined`) means "do not
+     * force a theme" — the frame follows `prefers-color-scheme`. A named theme
+     * overrides the media query.
+     */
+    readonly theme?: ThemeName;
+    /**
+     * Caller-supplied `--wr-*` custom properties, merged over the resolved theme.
+     * Keys may be given with or without the leading `--`. Values are emitted
+     * verbatim into an inline `<style>` (CSP allows `style-src 'unsafe-inline'`),
+     * so a caller controls exactly what its own book renders.
+     */
+    readonly customProperties?: Readonly<Record<string, string>>;
+    /** Body font family (a CSS `font-family` value). Reflows. */
+    readonly fontFamily?: string;
+    /** Body font size in CSS px. Reflows. */
+    readonly fontSize?: number;
+    /** Body line height, a unitless multiplier. Reflows. */
+    readonly lineHeight?: number;
+    /**
+     * Page margin in CSS px — the whitespace framing the text on both page edges,
+     * which also serves as the gutter between columns (a page reads
+     * margin/col/margin/col/margin). It is not a `--wr-*` variable: page geometry
+     * belongs to the paginator, so it rides `PaginateOptions` (as `columnGap`) and
+     * reflows the layout. Reflows.
+     */
+    readonly margin?: number;
+    /** Text alignment: `'start'` (publisher default) or `'justify'`. May reflow. */
+    readonly textAlign?: TextAlign;
+    /** Shorthand for `textAlign: 'justify'` when `true`, `'start'` when `false`. */
+    readonly justify?: boolean;
+    /** Whether the content root hyphenates. May reflow line breaks. */
+    readonly hyphenate?: boolean;
+    /** Number of text columns per page: 1 or 2. Reflows. */
+    readonly columns?: 1 | 2;
+}
+/**
+ * The theme portion of the `--wr-*` contract. These names are the public,
+ * frozen-ish vocabulary a custom theme supplies; content colours flow through
+ * them so a theme change repaints without touching layout.
+ */
+export interface ThemeVariables {
+    /** Reading surface background. */
+    readonly '--wr-background': string;
+    /** Body text colour. */
+    readonly '--wr-color': string;
+    /** Hyperlink colour. */
+    readonly '--wr-link-color': string;
+    /** Selection background. */
+    readonly '--wr-selection-background': string;
+    /** Selection text colour. */
+    readonly '--wr-selection-color': string;
+}
+/**
+ * The built-in themes. Each is a full {@link ThemeVariables} set so a forced
+ * theme is self-contained — it needs no media query to be complete.
+ */
+export declare const THEMES: Readonly<Record<Exclude<ThemeName, 'custom'>, ThemeVariables>>;
+/**
+ * The typography portion of the `--wr-*` contract. Each maps a live appearance
+ * knob to a custom property the content stylesheet consumes; publisher CSS never
+ * names these, so it cannot clobber them, exactly like the theme variables. All
+ * are optional: an unset knob leaves the publisher's own value in place.
+ */
+export interface TypographyVariables {
+    /** Body font family. */
+    readonly '--wr-font-family'?: string;
+    /** Body font size (a CSS length, e.g. `18px`). */
+    readonly '--wr-font-size'?: string;
+    /** Body line height (unitless multiplier). */
+    readonly '--wr-line-height'?: string;
+    /** Body text alignment. */
+    readonly '--wr-text-align'?: string;
+    /** Content-root hyphenation (`auto` or `manual`). */
+    readonly '--wr-hyphens'?: string;
+    /** Number of text columns per page. */
+    readonly '--wr-column-count'?: string;
+}
+/**
+ * Merge two partial `Appearance`s. `update` wins field-by-field; `customProperties`
+ * shallow-merges (an update's keys override the base's, and only the base's other
+ * keys survive). Passing `theme: undefined` in `update` does not clear the base
+ * theme — omit the key to keep it, since `exactOptionalPropertyTypes` distinguishes
+ * absent from `undefined`.
+ */
+export declare function mergeAppearance(base: Appearance, update: Appearance): Appearance;
+/**
+ * The resolved `--wr-*` variables for a forced theme, or `null` when no theme is
+ * forced (the frame follows `prefers-color-scheme` instead). Custom properties
+ * merge over the theme's base and win; for `theme: 'custom'` the base is the light
+ * theme so an incomplete custom set still yields a complete, readable variable set.
+ */
+export declare function resolveThemeProperties(appearance: Appearance): Record<string, string> | null;
+/**
+ * The resolved typography `--wr-*` variables for an appearance, or `null` when no
+ * typography knob is set. `columns` maps to `--wr-column-count`; `justify` folds
+ * into `--wr-text-align` (an explicit `textAlign` wins over `justify`). Only the
+ * knobs the caller supplied are emitted — an unset knob leaves the publisher's own
+ * value in place rather than forcing a default.
+ */
+export declare function resolveTypographyProperties(appearance: Appearance): TypographyVariables | null;
+/**
+ * The full appearance stylesheet the frame injects at document assembly, before
+ * the publisher's `headHtml`. It carries the theme half (colours) and the
+ * typography half (font/size/line-height/alignment/hyphenation) through one
+ * `--wr-*` namespace. It declares the theme layer first (so its ordering is fixed
+ * regardless of any `@layer` a book declares later), emits the themeable defaults
+ * and the unlayered surface guarantee, then the `prefers-color-scheme` defaults,
+ * then — if a theme is forced — an unlayered `:root` block that overrides the
+ * media query, and finally the unlayered typography guarantee. `null` from
+ * {@link resolveThemeProperties} means "follow the OS"; a variable set means
+ * "force it".
+ */
+export declare function themeStyleSheet(appearance: Appearance): string;
+/**
+ * The typography knobs that change chunk geometry and therefore require a re-layout
+ * (a `paginate`), not just a variable poke: font family, font size, line height,
+ * page margin, and column count. Alignment and hyphenation can shift line breaks
+ * too, so they are treated as reflowing to be safe. Whether an `update` touches any
+ * of these decides which path {@link Reader.setAppearance} takes.
+ */
+export declare function isReflowingUpdate(update: Appearance): boolean;
+//# sourceMappingURL=appearance.d.ts.map

package/dist/view/appearance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance.d.ts","sourceRoot":"","sources":["../../src/view/appearance.ts"],"names":[],"mappings":"AAkBA,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE9D,mFAAmF;AACnF,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7D,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,wBAAwB;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,wBAAwB;IACxB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,4BAA4B;IAC5B,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;IAC7C,6BAA6B;IAC7B,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;CACzC;AAED;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,cAAc,CAAC,CAsBxE,CAAC;AAEX;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,wBAAwB;IACxB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,kDAAkD;IAClD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,8CAA8C;IAC9C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,2BAA2B;IAC3B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,qDAAqD;IACrD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,uCAAuC;IACvC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAeD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,GAAG,UAAU,CAkChF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAgB5F;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,UAAU,GACrB,mBAAmB,GAAG,IAAI,CAY5B;AAiGD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAW9D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAW7D"}