@texuli/deck 0.0.0-stage → 0.5.0

package/dist/math/symbols.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The command tables of the owned TeX subset. Every output character comes
+ * from these tables or from the author's own letters, digits and operators.
+ */
+/** Greek letters → identifiers (uppercase ones are upright, as in TeX). */
+export declare const GREEK: Readonly<Record<string, string>>;
+/** Other identifiers. */
+export declare const IDENTIFIERS: Readonly<Record<string, string>>;
+/** Operators, relations and arrows. */
+export declare const OPERATORS: Readonly<Record<string, string>>;
+/** Big operators: limits go under and over in display math (integrals keep scripts). */
+export declare const BIG_OPERATORS: Readonly<Record<string, {
+    text: string;
+    integral: boolean;
+}>>;
+/** Named functions, written upright; the `limits` ones take limits under them in display. */
+export declare const FUNCTIONS: Readonly<Record<string, {
+    limits: boolean;
+}>>;
+/** Accents over a base (`\hat{x}`). */
+export declare const ACCENTS: Readonly<Record<string, string>>;
+/** Accents under a base. */
+export declare const UNDER_ACCENTS: Readonly<Record<string, string>>;
+/** Spacing commands → `mspace` widths. */
+export declare const SPACES: Readonly<Record<string, string>>;
+/** `\mathbb{R}` and friends → MathML `mathvariant`. */
+export declare const FONTS: Readonly<Record<string, string>>;
+/** Characters a backslash makes literal (`\{`, `\%`). */
+export declare const ESCAPED: Readonly<Record<string, string>>;
+/** Delimiters after `\left`, `\right` and the `\big` family. */
+export declare const DELIMITERS: Readonly<Record<string, string>>;
+/** Sizing commands that only change a delimiter's size (read as the plain delimiter). */
+export declare const SIZING: Set<string>;
+/** Matrix-like environments: the fences around them and the column alignment. */
+export declare const ENVIRONMENTS: Readonly<Record<string, {
+    open: string;
+    close: string;
+    align?: string;
+}>>;
+/**
+ * Commands refused by policy: they would fetch, link, color, inject markup or
+ * define macros. Named so the diagnostic can say why.
+ */
+export declare const REFUSED: Set<string>;

package/dist/math/symbols.js

@@ -0,0 +1,333 @@
+/**
+ * The command tables of the owned TeX subset. Every output character comes
+ * from these tables or from the author's own letters, digits and operators.
+ */
+/** Greek letters → identifiers (uppercase ones are upright, as in TeX). */
+export const GREEK = Object.freeze({
+    alpha: 'α',
+    beta: 'β',
+    gamma: 'γ',
+    delta: 'δ',
+    epsilon: 'ϵ',
+    varepsilon: 'ε',
+    zeta: 'ζ',
+    eta: 'η',
+    theta: 'θ',
+    vartheta: 'ϑ',
+    iota: 'ι',
+    kappa: 'κ',
+    lambda: 'λ',
+    mu: 'μ',
+    nu: 'ν',
+    xi: 'ξ',
+    pi: 'π',
+    varpi: 'ϖ',
+    rho: 'ρ',
+    varrho: 'ϱ',
+    sigma: 'σ',
+    varsigma: 'ς',
+    tau: 'τ',
+    upsilon: 'υ',
+    phi: 'ϕ',
+    varphi: 'φ',
+    chi: 'χ',
+    psi: 'ψ',
+    omega: 'ω',
+    Gamma: 'Γ',
+    Delta: 'Δ',
+    Theta: 'Θ',
+    Lambda: 'Λ',
+    Xi: 'Ξ',
+    Pi: 'Π',
+    Sigma: 'Σ',
+    Upsilon: 'Υ',
+    Phi: 'Φ',
+    Psi: 'Ψ',
+    Omega: 'Ω',
+});
+/** Other identifiers. */
+export const IDENTIFIERS = Object.freeze({
+    infty: '∞',
+    partial: '∂',
+    nabla: '∇',
+    ell: 'ℓ',
+    hbar: 'ℏ',
+    emptyset: '∅',
+    varnothing: '∅',
+    aleph: 'ℵ',
+    Re: 'ℜ',
+    Im: 'ℑ',
+    degree: '°',
+});
+/** Operators, relations and arrows. */
+export const OPERATORS = Object.freeze({
+    le: '≤',
+    leq: '≤',
+    ge: '≥',
+    geq: '≥',
+    ne: '≠',
+    neq: '≠',
+    approx: '≈',
+    equiv: '≡',
+    sim: '∼',
+    simeq: '≃',
+    cong: '≅',
+    propto: '∝',
+    in: '∈',
+    notin: '∉',
+    ni: '∋',
+    subset: '⊂',
+    subseteq: '⊆',
+    supset: '⊃',
+    supseteq: '⊇',
+    cup: '∪',
+    cap: '∩',
+    setminus: '∖',
+    times: '×',
+    cdot: '⋅',
+    div: '÷',
+    pm: '±',
+    mp: '∓',
+    ast: '∗',
+    star: '⋆',
+    circ: '∘',
+    bullet: '∙',
+    oplus: '⊕',
+    otimes: '⊗',
+    to: '→',
+    rightarrow: '→',
+    leftarrow: '←',
+    leftrightarrow: '↔',
+    Rightarrow: '⇒',
+    Leftarrow: '⇐',
+    Leftrightarrow: '⇔',
+    implies: '⟹',
+    iff: '⟺',
+    mapsto: '↦',
+    uparrow: '↑',
+    downarrow: '↓',
+    forall: '∀',
+    exists: '∃',
+    nexists: '∄',
+    neg: '¬',
+    lnot: '¬',
+    land: '∧',
+    wedge: '∧',
+    lor: '∨',
+    vee: '∨',
+    ldots: '…',
+    cdots: '⋯',
+    vdots: '⋮',
+    ddots: '⋱',
+    dots: '…',
+    mid: '∣',
+    parallel: '∥',
+    perp: '⊥',
+    angle: '∠',
+    prime: '′',
+    langle: '⟨',
+    rangle: '⟩',
+    lfloor: '⌊',
+    rfloor: '⌋',
+    lceil: '⌈',
+    rceil: '⌉',
+    vert: '|',
+    Vert: '‖',
+});
+/** Big operators: limits go under and over in display math (integrals keep scripts). */
+export const BIG_OPERATORS = Object.freeze({
+    sum: { text: '∑', integral: false },
+    prod: { text: '∏', integral: false },
+    coprod: { text: '∐', integral: false },
+    bigcup: { text: '⋃', integral: false },
+    bigcap: { text: '⋂', integral: false },
+    bigoplus: { text: '⨁', integral: false },
+    bigotimes: { text: '⨂', integral: false },
+    int: { text: '∫', integral: true },
+    iint: { text: '∬', integral: true },
+    iiint: { text: '∭', integral: true },
+    oint: { text: '∮', integral: true },
+});
+/** Named functions, written upright; the `limits` ones take limits under them in display. */
+export const FUNCTIONS = Object.freeze({
+    sin: { limits: false },
+    cos: { limits: false },
+    tan: { limits: false },
+    cot: { limits: false },
+    sec: { limits: false },
+    csc: { limits: false },
+    arcsin: { limits: false },
+    arccos: { limits: false },
+    arctan: { limits: false },
+    sinh: { limits: false },
+    cosh: { limits: false },
+    tanh: { limits: false },
+    log: { limits: false },
+    ln: { limits: false },
+    lg: { limits: false },
+    exp: { limits: false },
+    deg: { limits: false },
+    arg: { limits: false },
+    dim: { limits: false },
+    ker: { limits: false },
+    det: { limits: true },
+    gcd: { limits: true },
+    lim: { limits: true },
+    max: { limits: true },
+    min: { limits: true },
+    sup: { limits: true },
+    inf: { limits: true },
+    Pr: { limits: true },
+});
+/** Accents over a base (`\hat{x}`). */
+export const ACCENTS = Object.freeze({
+    hat: '^',
+    widehat: '^',
+    bar: '¯',
+    vec: '→',
+    dot: '˙',
+    ddot: '¨',
+    tilde: '~',
+    widetilde: '~',
+    acute: '´',
+    grave: '`',
+    check: 'ˇ',
+    breve: '˘',
+    overline: '‾',
+    overrightarrow: '→',
+    overleftarrow: '←',
+    overbrace: '⏞',
+});
+/** Accents under a base. */
+export const UNDER_ACCENTS = Object.freeze({
+    underline: '_',
+    underbrace: '⏟',
+});
+/** Spacing commands → `mspace` widths. */
+export const SPACES = Object.freeze({
+    ',': '0.1667em',
+    ':': '0.2222em',
+    '>': '0.2222em',
+    ';': '0.2778em',
+    ' ': '0.3333em',
+    '!': '-0.1667em',
+    quad: '1em',
+    qquad: '2em',
+    thinspace: '0.1667em',
+    medspace: '0.2222em',
+    thickspace: '0.2778em',
+    enspace: '0.5em',
+});
+/** `\mathbb{R}` and friends → MathML `mathvariant`. */
+export const FONTS = Object.freeze({
+    mathrm: 'normal',
+    mathup: 'normal',
+    mathbf: 'bold',
+    mathit: 'italic',
+    mathbb: 'double-struck',
+    mathcal: 'script',
+    mathscr: 'script',
+    mathfrak: 'fraktur',
+    mathsf: 'sans-serif',
+    mathtt: 'monospace',
+    boldsymbol: 'bold-italic',
+});
+/** Characters a backslash makes literal (`\{`, `\%`). */
+export const ESCAPED = Object.freeze({
+    '{': '{',
+    '}': '}',
+    '%': '%',
+    $: '$',
+    '&': '&',
+    '#': '#',
+    _: '_',
+    '|': '‖',
+});
+/** Delimiters after `\left`, `\right` and the `\big` family. */
+export const DELIMITERS = Object.freeze({
+    '(': '(',
+    ')': ')',
+    '[': '[',
+    ']': ']',
+    '|': '|',
+    '/': '/',
+    '.': '',
+    '\\{': '{',
+    '\\}': '}',
+    '\\|': '‖',
+    '\\langle': '⟨',
+    '\\rangle': '⟩',
+    '\\lfloor': '⌊',
+    '\\rfloor': '⌋',
+    '\\lceil': '⌈',
+    '\\rceil': '⌉',
+    '\\vert': '|',
+    '\\Vert': '‖',
+});
+/** Sizing commands that only change a delimiter's size (read as the plain delimiter). */
+export const SIZING = new Set([
+    'big',
+    'Big',
+    'bigg',
+    'Bigg',
+    'bigl',
+    'bigr',
+    'Bigl',
+    'Bigr',
+    'biggl',
+    'biggr',
+    'Biggl',
+    'Biggr',
+]);
+/** Matrix-like environments: the fences around them and the column alignment. */
+export const ENVIRONMENTS = Object.freeze({
+    matrix: { open: '', close: '' },
+    smallmatrix: { open: '', close: '' },
+    pmatrix: { open: '(', close: ')' },
+    bmatrix: { open: '[', close: ']' },
+    Bmatrix: { open: '{', close: '}' },
+    vmatrix: { open: '|', close: '|' },
+    Vmatrix: { open: '‖', close: '‖' },
+    cases: { open: '{', close: '', align: 'left' },
+    aligned: { open: '', close: '', align: 'right left' },
+    align: { open: '', close: '', align: 'right left' },
+    gathered: { open: '', close: '' },
+    array: { open: '', close: '' },
+});
+/**
+ * Commands refused by policy: they would fetch, link, color, inject markup or
+ * define macros. Named so the diagnostic can say why.
+ */
+export const REFUSED = new Set([
+    'href',
+    'url',
+    'includegraphics',
+    'color',
+    'textcolor',
+    'colorbox',
+    'fcolorbox',
+    'htmlClass',
+    'htmlId',
+    'htmlStyle',
+    'htmlData',
+    'html',
+    'def',
+    'gdef',
+    'edef',
+    'xdef',
+    'let',
+    'newcommand',
+    'renewcommand',
+    'providecommand',
+    'DeclareMathOperator',
+    'input',
+    'include',
+    'verb',
+    'tag',
+    'label',
+    'ref',
+    'eqref',
+    'style',
+    'class',
+    'cssId',
+]);

package/dist/math/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The MathML node tree the owned TeX subset produces (ADR-009, math policy).
+ * A renderer walks it with a closed tag and attribute allowlist; no string of
+ * markup is ever produced, so nothing here reaches an HTML sink.
+ */
+/** The MathML Core elements the converter emits. */
+export declare const MATH_TAGS: readonly ["math", "mrow", "mi", "mn", "mo", "mtext", "mspace", "msup", "msub", "msubsup", "mfrac", "msqrt", "mroot", "mover", "munder", "munderover", "mtable", "mtr", "mtd", "mstyle"];
+export type MathTag = (typeof MATH_TAGS)[number];
+/** The attributes the converter may set (values are always from its own tables). */
+export declare const MATH_ATTRIBUTES: readonly ["display", "alttext", "mathvariant", "stretchy", "fence", "separator", "largeop", "movablelimits", "accent", "accentunder", "linethickness", "width", "columnalign", "displaystyle", "scriptlevel", "form", "lspace", "rspace"];
+export type MathAttribute = (typeof MATH_ATTRIBUTES)[number];
+export interface MathNode {
+    tag: MathTag;
+    attrs?: Partial<Record<MathAttribute, string>>;
+    /** Token elements (`mi`, `mn`, `mo`, `mtext`) carry text; the others carry children. */
+    text?: string;
+    children?: MathNode[];
+}
+export declare const MATH_CODES: Readonly<{
+    /** A command or environment outside the subset (`\href`, `\color`, macros…). */
+    readonly unsupported: "tex-unsupported";
+    /** Unbalanced braces, a missing argument, a double script… */
+    readonly syntax: "tex-syntax";
+    /** Over a size, nesting or node bound. */
+    readonly limit: "tex-limit";
+}>;
+export type MathCode = (typeof MATH_CODES)[keyof typeof MATH_CODES];
+export interface MathIssue {
+    code: MathCode;
+    message: string;
+    /** UTF-16 offset in the TeX source. */
+    offset: number;
+}
+export interface MathResult {
+    /** True when the whole source converted. */
+    ok: boolean;
+    /**
+     * The `math` root. When `ok` is false it holds the TeX source as `mtext`,
+     * so a failed formula still shows what the author wrote.
+     */
+    node: MathNode;
+    issues: MathIssue[];
+}
+export interface TexToMathOptions {
+    /** Block (`$$`) math; default false (inline). */
+    display?: boolean;
+}
+/** Bounds per formula (hostile input stays cheap). */
+export declare const MATH_LIMITS: Readonly<{
+    /** TeX source length in UTF-16 units. */
+    source: 2000;
+    /** Nested groups, environments and fractions. */
+    depth: 16;
+    /** Output nodes. */
+    nodes: 2000;
+    /** Rows and cells of one environment. */
+    rows: 50;
+    cells: 400;
+}>;

package/dist/math/types.js

@@ -0,0 +1,69 @@
+/**
+ * The MathML node tree the owned TeX subset produces (ADR-009, math policy).
+ * A renderer walks it with a closed tag and attribute allowlist; no string of
+ * markup is ever produced, so nothing here reaches an HTML sink.
+ */
+/** The MathML Core elements the converter emits. */
+export const MATH_TAGS = [
+    'math',
+    'mrow',
+    'mi',
+    'mn',
+    'mo',
+    'mtext',
+    'mspace',
+    'msup',
+    'msub',
+    'msubsup',
+    'mfrac',
+    'msqrt',
+    'mroot',
+    'mover',
+    'munder',
+    'munderover',
+    'mtable',
+    'mtr',
+    'mtd',
+    'mstyle',
+];
+/** The attributes the converter may set (values are always from its own tables). */
+export const MATH_ATTRIBUTES = [
+    'display',
+    'alttext',
+    'mathvariant',
+    'stretchy',
+    'fence',
+    'separator',
+    'largeop',
+    'movablelimits',
+    'accent',
+    'accentunder',
+    'linethickness',
+    'width',
+    'columnalign',
+    'displaystyle',
+    'scriptlevel',
+    'form',
+    'lspace',
+    'rspace',
+];
+export const MATH_CODES = Object.freeze({
+    /** A command or environment outside the subset (`\href`, `\color`, macros…). */
+    unsupported: 'tex-unsupported',
+    /** Unbalanced braces, a missing argument, a double script… */
+    syntax: 'tex-syntax',
+    /** Over a size, nesting or node bound. */
+    limit: 'tex-limit',
+});
+/** Bounds per formula (hostile input stays cheap). */
+export const MATH_LIMITS = Object.freeze({
+    /** TeX source length in UTF-16 units. */
+    source: 2_000,
+    /** Nested groups, environments and fractions. */
+    depth: 16,
+    /** Output nodes. */
+    nodes: 2_000,
+    /** Rows and cells of one environment. */
+    rows: 50,
+    cells: 400,
+});

package/dist/model/backgrounds/contrast.d.ts

@@ -0,0 +1,77 @@
+/**
+ * WCAG 2.x contrast math for deck backgrounds, on sRGB hex colors only.
+ *
+ * Every function here is pure and framework-free. Inputs are `#rgb` or
+ * `#rrggbb` (and, through `opaqueColor`, `rgb()`/`rgba()` composited over a
+ * base); `oklch()` and other color spaces are converted by the caller (the
+ * stage reads them from `@texuli/tokens`). Outputs are always lowercase
+ * `#rrggbb`, so a computed color can go into CSS without escaping.
+ */
+/** WCAG AA for normal-size body text: the floor every background guarantees. */
+export declare const DECK_TEXT_CONTRAST_MIN = 4.5;
+/** Scrim alphas move in steps of 0.05 … */
+export declare const DECK_SCRIM_STEP = 0.05;
+/** … up to 0.9 (an image or video always stays faintly visible). */
+export declare const DECK_SCRIM_MAX = 0.9;
+/** Light ink and the scrim under it; dark ink and the scrim under it. */
+export declare const PURE_LIGHT = "#ffffff";
+export declare const PURE_DARK = "#000000";
+export type TextTone = 'light' | 'dark';
+export type Rgb = readonly [number, number, number];
+/** `#rgb` or `#rrggbb` (any case, surrounding spaces ignored) as 0–255 channels; anything else is `null`. */
+export declare function parseHexColor(color: unknown): Rgb | null;
+/** Channels → lowercase `#rrggbb` (channels are clamped and rounded). */
+export declare function toHex(rgb: Rgb): string;
+/** A hex color in its canonical form (`#rrggbb`, lowercase), or `null`. */
+export declare function normalizeHex(color: unknown): string | null;
+/** WCAG relative luminance (0 for black, 1 for white). Throws `TypeError` on a non-hex color. */
+export declare function relativeLuminance(color: string): number;
+/** WCAG contrast ratio, 1 to 21, order independent. Throws `TypeError` on a non-hex color. */
+export declare function contrastRatio(a: string, b: string): number;
+/** `top` over `base` at `alpha` (0–1), composited in sRGB as browsers paint it. */
+export declare function compositeOver(base: string, top: string, alpha: number): string;
+/**
+ * A palette color as an opaque hex: hex passes through (canonicalized),
+ * `rgb()`/`rgba()` is composited over `base` (dark-mode borders carry alpha).
+ * Anything else is `null`, so the contrast math never guesses at a color.
+ */
+export declare function opaqueColor(color: unknown, base: string): string | null;
+/** Points along a linear sRGB gradient: every stop and `perSegment - 1` points between each pair. */
+export declare function sampleGradient(stops: readonly string[], perSegment?: number): string[];
+/** The lowest contrast of `ink` over any of `backgrounds` (21 for an empty list). */
+export declare function worstContrast(ink: string, backgrounds: readonly string[]): number;
+/** The first scrim step at or above `alpha` (an author overlay is never weakened). */
+export declare function scrimStepFor(alpha: number): number;
+export interface InkChoice {
+    tone: TextTone;
+    ink: string;
+    /** Black under light ink, white under dark ink. */
+    scrimColor: string;
+    /** 0 to 0.9 in 0.05 steps; 0 means no scrim is painted. */
+    scrim: number;
+    /** Worst-case contrast of `ink` over every background with the scrim, ≥ `minimum`. */
+    contrast: number;
+}
+/**
+ * The lowest scrim (in 0.05 steps, from `minimumScrim` up to 0.9) under which
+ * `ink` reaches `minimum` over every background, or `null` when none does.
+ */
+export declare function inkWithScrim(tone: TextTone, ink: string, backgrounds: readonly string[], minimumScrim?: number, minimum?: number): InkChoice | null;
+export interface ChooseInkOptions {
+    /** Only this tone (an image declared dark or light). */
+    forced?: TextTone;
+    /** The author's overlay: the scrim never goes below it. */
+    minimumScrim?: number;
+    /** The contrast floor; values below 4.5 are raised to 4.5. */
+    minimum?: number;
+}
+/**
+ * The ink for a set of backgrounds. Each tone tries the theme ink first and
+ * pure white or black second; the choice needs the lightest scrim, then
+ * prefers the theme ink, then the higher contrast. Pure ink over a 0.9 scrim
+ * always clears AA (about 15:1 against any pixel), so a result always exists.
+ */
+export declare function chooseInk(backgrounds: readonly string[], inks: {
+    light: string;
+    dark: string;
+}, options?: ChooseInkOptions): InkChoice;