@texuli/core 0.4.0 → 0.6.0

package/dist/motion/shared.js

@@ -0,0 +1,144 @@
+/**
+ * Shared-element transitions (ADR-013): a keyed snapshot of one element's box
+ * before a state change, played onto the element that represents the same
+ * thing after it (a thumbnail and its lightbox, a card and its detail view).
+ *
+ * The fallback everywhere is FLIP: the new element moves and scales from the
+ * captured box; when the old element is still on the page the two cross-fade.
+ * {@link startScopedViewTransition} uses an element-scoped View Transition
+ * when the browser has one and otherwise just applies the update.
+ */
+import { createRun, resolveMotion, startAnimation, } from "./animate.js";
+import { flipTransform } from "./flip.js";
+import { resolveMotionLevel } from "./preferences.js";
+function measure(element) {
+    if (!element?.isConnected || typeof element.getBoundingClientRect !== 'function')
+        return null;
+    const r = element.getBoundingClientRect();
+    const box = { left: r.left, top: r.top, width: r.width, height: r.height };
+    return Object.values(box).every(Number.isFinite) ? box : null;
+}
+/**
+ * Create a registry of keyed snapshots.
+ *
+ * @example
+ * const shared = createSharedElements({ duration: 250 });
+ * shared.capture('photo-3', thumbnail);
+ * openLightbox();                      // the DOM changes
+ * shared.play('photo-3', lightboxImage);
+ */
+export function createSharedElements(options = {}) {
+    const limit = Math.max(1, Math.min(4096, Math.floor(Number.isFinite(options.maxEntries) ? options.maxEntries : 256)));
+    const snapshots = new Map();
+    return {
+        capture(key, element) {
+            const box = element ? measure(element) : null;
+            const id = String(key);
+            snapshots.delete(id);
+            if (!box)
+                return false;
+            snapshots.set(id, { element, box });
+            while (snapshots.size > limit) {
+                const oldest = snapshots.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                snapshots.delete(oldest);
+            }
+            return true;
+        },
+        play(key, element) {
+            const id = String(key);
+            const snapshot = snapshots.get(id);
+            snapshots.delete(id);
+            const last = element ? measure(element) : null;
+            if (!snapshot || !last) {
+                return createRun([], options.onFinish, last ? 'no-properties' : 'detached');
+            }
+            const transform = flipTransform(snapshot.box, last, true);
+            const crossFade = snapshot.element !== element && snapshot.element.isConnected;
+            const toFrames = [
+                {
+                    transform: transform ?? 'none',
+                    transformOrigin: '0 0',
+                    ...(crossFade ? { opacity: 0 } : {}),
+                },
+                { transform: 'none', transformOrigin: '0 0', ...(crossFade ? { opacity: 1 } : {}) },
+            ];
+            if (!transform && !crossFade)
+                return createRun([], options.onFinish, 'no-properties');
+            // Read phase done; write phase.
+            const plans = [
+                [element, resolveMotion(element, toFrames, options)],
+            ];
+            if (crossFade) {
+                // The old element travels from its box onto the new one while it fades out.
+                const travel = flipTransform(last, snapshot.box, true) ?? 'none';
+                plans.push([
+                    snapshot.element,
+                    resolveMotion(snapshot.element, [
+                        { transform: 'none', transformOrigin: '0 0', opacity: 1 },
+                        { transform: travel, transformOrigin: '0 0', opacity: 0 },
+                    ], options),
+                ]);
+            }
+            const animations = [];
+            let reason = null;
+            for (const [target, plan] of plans) {
+                if (plan.instant) {
+                    reason ??= plan.reason;
+                    continue;
+                }
+                const animation = startAnimation(target, plan);
+                if (animation)
+                    animations.push(animation);
+                else
+                    reason ??= 'error';
+            }
+            return createRun(animations, options.onFinish, reason);
+        },
+        has: (key) => snapshots.has(String(key)),
+        release: (key) => {
+            snapshots.delete(String(key));
+        },
+        clear: () => snapshots.clear(),
+        get size() {
+            return snapshots.size;
+        },
+    };
+}
+/**
+ * Run `update` inside an element-scoped View Transition when the browser
+ * offers `element.startViewTransition`; otherwise (no support, the server,
+ * level `none`, reduced motion) apply it at once. Resolves `"finished"` after
+ * the transition, `"instant"` when the update was applied directly.
+ */
+export async function startScopedViewTransition(scope, update, options = {}) {
+    const host = scope;
+    // Same gates as any animation (server, detached, level, reduced motion);
+    // a missing Web Animations API does not matter here.
+    const probe = resolveMotion(host ?? null, [{ opacity: 1 }], {
+        level: resolveMotionLevel({ host: options.level }),
+        reducedMotion: options.reducedMotion,
+        duration: 1,
+    });
+    const usable = !probe.instant || probe.reason === 'no-waapi';
+    if (!host || !usable || typeof host.startViewTransition !== 'function') {
+        await update();
+        return 'instant';
+    }
+    let transition;
+    try {
+        transition = host.startViewTransition.call(host, update);
+    }
+    catch {
+        await update();
+        return 'instant';
+    }
+    try {
+        await transition.finished;
+        return 'finished';
+    }
+    catch {
+        return 'cancelled';
+    }
+}

package/dist/motion/spring.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Spring: a pure damped harmonic oscillator solver (ADR-013).
+ *
+ * Framework-free and DOM-free. The solver moves a normalized progress from 0
+ * to 1 with the closed form for every damping case (under, critical and over
+ * damped), finds when the spring settles, samples it into keyframe offsets or
+ * a CSS `linear()` easing, and reports position and velocity at any time so an
+ * interrupted animation can be retargeted without a velocity jump.
+ *
+ * Hostile inputs are clamped: stiffness, damping, mass, velocity and sample
+ * counts have fixed ranges, NaN falls back to the defaults, and the settle
+ * search never evaluates more than `MAX_SPRING_MS + 1` points.
+ */
+/** Physical spring parameters (unitless, like the CSS-in-JS spring convention). */
+export type SpringParams = {
+    /** Spring constant `k`. Clamped to [1, 10000]. */
+    readonly stiffness: number;
+    /** Damping coefficient `c`. Clamped to [0, 1000]. */
+    readonly damping: number;
+    /** Mass `m`. Clamped to [0.01, 1000]. */
+    readonly mass: number;
+};
+/** Options shared by the solver helpers. */
+export type SpringSolveOptions = {
+    /**
+     * Initial velocity in progress units per second (1 = the whole distance per
+     * second). Clamped to [-1000, 1000]. Default 0.
+     */
+    velocity?: number;
+    /** Settled when |1 − progress| is below this. Default 0.001. */
+    restDelta?: number;
+    /** Settled when |velocity| (progress per second) is below this. Default 0.01. */
+    restSpeed?: number;
+};
+/** Position and velocity of the spring at one time. */
+export type SpringState = {
+    /** Normalized progress (0 at rest start, 1 at the target; may overshoot). */
+    readonly position: number;
+    /** Progress units per second. */
+    readonly velocity: number;
+};
+/** Settle result. */
+export type SpringSettle = {
+    /** Milliseconds until the spring stays within rest thresholds, at most `MAX_SPRING_MS`. */
+    readonly durationMs: number;
+    /** False when the spring was still moving at `MAX_SPRING_MS` (the last frame snaps to 1). */
+    readonly settled: boolean;
+};
+/** Sampled spring curve. */
+export type SpringSamples = SpringSettle & {
+    /** Progress values at evenly spaced times from 0 to `durationMs`; first 0, last 1. */
+    readonly points: readonly number[];
+};
+/** Longest spring (and any Texuli motion) duration, in milliseconds. */
+export declare const MAX_SPRING_MS = 1000;
+/** Default sample count for keyframes and `linear()` easings. */
+export declare const DEFAULT_SPRING_SAMPLES = 40;
+/** Largest sample count accepted (keeps `linear()` strings short). */
+export declare const MAX_SPRING_SAMPLES = 120;
+/** Spring used when parameters are missing or not finite. */
+export declare const DEFAULT_SPRING: SpringParams;
+/** Clamp spring parameters into the supported ranges; NaN takes the default. */
+export declare function normalizeSpring(params: Partial<SpringParams> | null | undefined): SpringParams;
+/** Damping ratio ζ = c / (2√(k·m)); below 1 overshoots, 1 is critical. */
+export declare function dampingRatio(params: Partial<SpringParams>): number;
+/** Position and velocity `ms` milliseconds after release (closed form, O(1)). */
+export declare function springState(params: Partial<SpringParams>, ms: number, options?: SpringSolveOptions): SpringState;
+/**
+ * When the spring comes to rest: the first millisecond after which every
+ * sampled millisecond stays inside the rest thresholds. Bounded: at most
+ * `MAX_SPRING_MS + 1` closed-form evaluations.
+ */
+export declare function springSettle(params: Partial<SpringParams>, options?: SpringSolveOptions): SpringSettle;
+/**
+ * Sample the spring at evenly spaced times across its settle duration. The
+ * first point is the start position (0) and the last is pinned to 1, so a
+ * spring cut at `MAX_SPRING_MS` lands exactly on its target.
+ */
+export declare function springSamples(params: Partial<SpringParams>, options?: SpringSolveOptions & {
+    samples?: number;
+}): SpringSamples;
+/**
+ * A CSS `linear()` easing that traces the spring, with its duration. Points
+ * are evenly spaced, so no stop percentages are needed.
+ *
+ * @example
+ * const { easing, durationMs } = springEasing({ stiffness: 400, damping: 30, mass: 1 });
+ * element.animate(keyframes, { duration: durationMs, easing });
+ */
+export declare function springEasing(params: Partial<SpringParams>, options?: SpringSolveOptions & {
+    samples?: number;
+}): SpringSettle & {
+    readonly easing: string;
+};
+/**
+ * Keyframes for any property: `build(progress)` maps a spring position to a
+ * keyframe (for example a transform). Offsets are evenly spaced.
+ */
+export declare function springKeyframes(params: Partial<SpringParams>, build: (progress: number) => Keyframe, options?: SpringSolveOptions & {
+    samples?: number;
+}): SpringSettle & {
+    readonly keyframes: Keyframe[];
+};
+/**
+ * Velocity for a retargeted spring: a velocity measured in the old segment's
+ * progress units, converted to the new segment (`newSpan` / `oldSpan` are the
+ * distances in any shared unit). Zero or non-finite spans give 0.
+ */
+export declare function retargetVelocity(velocity: number, oldSpan: number, newSpan: number): number;

package/dist/motion/spring.js

@@ -0,0 +1,166 @@
+/**
+ * Spring: a pure damped harmonic oscillator solver (ADR-013).
+ *
+ * Framework-free and DOM-free. The solver moves a normalized progress from 0
+ * to 1 with the closed form for every damping case (under, critical and over
+ * damped), finds when the spring settles, samples it into keyframe offsets or
+ * a CSS `linear()` easing, and reports position and velocity at any time so an
+ * interrupted animation can be retargeted without a velocity jump.
+ *
+ * Hostile inputs are clamped: stiffness, damping, mass, velocity and sample
+ * counts have fixed ranges, NaN falls back to the defaults, and the settle
+ * search never evaluates more than `MAX_SPRING_MS + 1` points.
+ */
+/** Longest spring (and any Texuli motion) duration, in milliseconds. */
+export const MAX_SPRING_MS = 1000;
+/** Default sample count for keyframes and `linear()` easings. */
+export const DEFAULT_SPRING_SAMPLES = 40;
+/** Largest sample count accepted (keeps `linear()` strings short). */
+export const MAX_SPRING_SAMPLES = 120;
+/** Spring used when parameters are missing or not finite. */
+export const DEFAULT_SPRING = Object.freeze({
+    stiffness: 170,
+    damping: 26,
+    mass: 1,
+});
+function clamp(value, min, max, fallback) {
+    if (typeof value !== 'number' || Number.isNaN(value))
+        return fallback;
+    return Math.min(max, Math.max(min, value));
+}
+/** Clamp spring parameters into the supported ranges; NaN takes the default. */
+export function normalizeSpring(params) {
+    const p = params ?? {};
+    return {
+        stiffness: clamp(p.stiffness ?? DEFAULT_SPRING.stiffness, 1, 10000, DEFAULT_SPRING.stiffness),
+        damping: clamp(p.damping ?? DEFAULT_SPRING.damping, 0, 1000, DEFAULT_SPRING.damping),
+        mass: clamp(p.mass ?? DEFAULT_SPRING.mass, 0.01, 1000, DEFAULT_SPRING.mass),
+    };
+}
+/** Damping ratio ζ = c / (2√(k·m)); below 1 overshoots, 1 is critical. */
+export function dampingRatio(params) {
+    const { stiffness, damping, mass } = normalizeSpring(params);
+    return damping / (2 * Math.sqrt(stiffness * mass));
+}
+function solver(params, velocity) {
+    const { stiffness, damping, mass } = normalizeSpring(params);
+    const v0 = clamp(velocity, -1000, 1000, 0);
+    const w0 = Math.sqrt(stiffness / mass);
+    const zeta = damping / (2 * Math.sqrt(stiffness * mass));
+    // Displacement y = position − 1, so y(0) = −1 and y'(0) = v0.
+    const a = -1;
+    if (Math.abs(zeta - 1) < 1e-6) {
+        const b = v0 + w0 * a;
+        return (t) => {
+            const e = Math.exp(-w0 * t);
+            return { position: 1 + (a + b * t) * e, velocity: e * (b - w0 * (a + b * t)) };
+        };
+    }
+    if (zeta < 1) {
+        const wd = w0 * Math.sqrt(1 - zeta * zeta);
+        const decay = zeta * w0;
+        const b = (v0 + decay * a) / wd;
+        return (t) => {
+            const e = Math.exp(-decay * t);
+            const cos = Math.cos(wd * t);
+            const sin = Math.sin(wd * t);
+            return {
+                position: 1 + e * (a * cos + b * sin),
+                velocity: e * ((-decay * a + wd * b) * cos + (-decay * b - wd * a) * sin),
+            };
+        };
+    }
+    const root = Math.sqrt(zeta * zeta - 1);
+    const r1 = -w0 * (zeta - root);
+    const r2 = -w0 * (zeta + root);
+    const c2 = (v0 - r1 * a) / (r2 - r1);
+    const c1 = a - c2;
+    return (t) => {
+        const e1 = Math.exp(r1 * t);
+        const e2 = Math.exp(r2 * t);
+        return { position: 1 + c1 * e1 + c2 * e2, velocity: r1 * c1 * e1 + r2 * c2 * e2 };
+    };
+}
+/** Position and velocity `ms` milliseconds after release (closed form, O(1)). */
+export function springState(params, ms, options = {}) {
+    const t = clamp(ms, 0, Number.MAX_SAFE_INTEGER, 0) / 1000;
+    return solver(params, options.velocity ?? 0)(t);
+}
+/**
+ * When the spring comes to rest: the first millisecond after which every
+ * sampled millisecond stays inside the rest thresholds. Bounded: at most
+ * `MAX_SPRING_MS + 1` closed-form evaluations.
+ */
+export function springSettle(params, options = {}) {
+    const solve = solver(params, options.velocity ?? 0);
+    const restDelta = clamp(options.restDelta ?? 0.001, 1e-6, 0.5, 0.001);
+    const restSpeed = clamp(options.restSpeed ?? 0.01, 1e-6, 100, 0.01);
+    let lastMoving = -1;
+    for (let ms = 0; ms <= MAX_SPRING_MS; ms++) {
+        const s = solve(ms / 1000);
+        if (Math.abs(1 - s.position) >= restDelta || Math.abs(s.velocity) >= restSpeed) {
+            lastMoving = ms;
+        }
+    }
+    if (lastMoving >= MAX_SPRING_MS)
+        return { durationMs: MAX_SPRING_MS, settled: false };
+    return { durationMs: lastMoving + 1, settled: true };
+}
+function sampleCount(samples) {
+    return Math.round(clamp(samples ?? DEFAULT_SPRING_SAMPLES, 2, MAX_SPRING_SAMPLES, DEFAULT_SPRING_SAMPLES));
+}
+/**
+ * Sample the spring at evenly spaced times across its settle duration. The
+ * first point is the start position (0) and the last is pinned to 1, so a
+ * spring cut at `MAX_SPRING_MS` lands exactly on its target.
+ */
+export function springSamples(params, options = {}) {
+    const settle = springSettle(params, options);
+    const count = sampleCount(options.samples);
+    const solve = solver(params, options.velocity ?? 0);
+    const points = [];
+    for (let i = 0; i < count; i++) {
+        const t = (settle.durationMs * i) / (count - 1) / 1000;
+        points.push(i === count - 1 ? 1 : round(solve(t).position));
+    }
+    points[0] = 0;
+    return { ...settle, points };
+}
+function round(value) {
+    const r = Math.round(value * 10000) / 10000;
+    return Object.is(r, -0) ? 0 : r;
+}
+/**
+ * A CSS `linear()` easing that traces the spring, with its duration. Points
+ * are evenly spaced, so no stop percentages are needed.
+ *
+ * @example
+ * const { easing, durationMs } = springEasing({ stiffness: 400, damping: 30, mass: 1 });
+ * element.animate(keyframes, { duration: durationMs, easing });
+ */
+export function springEasing(params, options = {}) {
+    const { points, durationMs, settled } = springSamples(params, options);
+    return { easing: `linear(${points.join(', ')})`, durationMs, settled };
+}
+/**
+ * Keyframes for any property: `build(progress)` maps a spring position to a
+ * keyframe (for example a transform). Offsets are evenly spaced.
+ */
+export function springKeyframes(params, build, options = {}) {
+    const { points, durationMs, settled } = springSamples(params, options);
+    const last = points.length - 1;
+    const keyframes = points.map((p, i) => ({ ...build(p), offset: i / last }));
+    return { keyframes, durationMs, settled };
+}
+/**
+ * Velocity for a retargeted spring: a velocity measured in the old segment's
+ * progress units, converted to the new segment (`newSpan` / `oldSpan` are the
+ * distances in any shared unit). Zero or non-finite spans give 0.
+ */
+export function retargetVelocity(velocity, oldSpan, newSpan) {
+    if (!Number.isFinite(velocity) || !Number.isFinite(oldSpan) || !Number.isFinite(newSpan))
+        return 0;
+    if (newSpan === 0)
+        return 0;
+    return clamp((velocity * oldSpan) / newSpan, -1000, 1000, 0);
+}

package/dist/overlay/core.js

@@ -161,10 +161,16 @@ export function createOverlayCore(options, features = {}) {
     /**
      * R16: an exempt region shown in the top layer (the toast region as a
      * `popover`) must keep painting above the overlay that just joined it.
-     * The top layer orders by show time, so re-show it.
+     * The top layer orders by show time, so re-show it. Exemptions registered
+     * with `raise: false` (a dialog backdrop, a menu or listbox opened inside a
+     * modal) stay where they are: re-showing them would cover this overlay.
      */
     function raiseExemptPopovers() {
-        for (const region of exemptElements()) {
+        const regions = (inertRegistry()?.exemptions() ?? [])
+            .filter((entry) => entry.raise !== false)
+            .map((entry) => entry.element)
+            .filter((region) => region !== element && !element.contains(region));
+        for (const region of regions) {
             const popover = region;
             try {
                 if (!popover.matches(':popover-open'))
@@ -239,12 +245,19 @@ export function createOverlayCore(options, features = {}) {
         else if (inert && inert.size() > 0 && isLive(element)) {
             // A menu or popover opened from inside a modal: keep it live while open,
             // even when it sits outside the modal (portaled to the body).
-            liveExemption = inert.exempt({ element, label: options.label ?? 'overlay' });
+            // `raise: false`: an overlay opened later from this one must stay above it.
+            liveExemption = inert.exempt({
+                element,
+                label: options.label ?? 'overlay',
+                raise: false,
+            });
         }
         if (wantsTrap && features.focusScope) {
             focusScope = features.focusScope(element, {
                 ...(options.initialFocus ? { initialFocus: options.initialFocus } : {}),
                 ...(options.cycleTabNavigation ? { cycleTabNavigation: true } : {}),
+                // Focus-exempt regions (the toast region) keep their own Tab order.
+                exemptRegions: exemptElements,
                 onBeforeRestoreFocus: (event) => {
                     if (options.restoreFocus === false)
                         event.preventDefault();

package/dist/url-policy/filter-image-srcset.d.ts

@@ -0,0 +1,11 @@
+import type { HrefTrust } from '../url/safe-href.js';
+/**
+ * Filter an image `srcset` candidate by candidate, where `safeImageSrcset`
+ * refuses the whole value. Every candidate URL goes through the image URL
+ * policy (`safeImageSrc`) at `trust`; a refused or malformed candidate (or one
+ * whose URL holds a comma) is dropped and the rest are kept. Candidates keep
+ * the descriptor kind of the first kept one (`x` or `w`), since a srcset
+ * cannot mix them. Returns `undefined` when nothing is left, so a caller can
+ * drop `sizes` with it.
+ */
+export declare function filterImageSrcset(value: unknown, trust?: HrefTrust): string | undefined;

package/dist/url-policy/filter-image-srcset.js

@@ -0,0 +1,60 @@
+import { safeImageSrcset } from "./safe-image-srcset.js";
+/**
+ * Split a `srcset` into candidates the way the HTML parser reads it: a URL is
+ * a run of non-whitespace (so a `data:` URL may hold commas), trailing commas
+ * end it, and descriptors run to the next comma.
+ */
+function candidates(value) {
+    const out = [];
+    let index = 0;
+    while (index < value.length) {
+        while (index < value.length && /[\s,]/.test(value[index] ?? ''))
+            index += 1;
+        if (index >= value.length)
+            break;
+        let end = index;
+        while (end < value.length && !/\s/.test(value[end] ?? ''))
+            end += 1;
+        let url = value.slice(index, end);
+        index = end;
+        if (url.endsWith(',')) {
+            url = url.replace(/,+$/, '');
+            out.push({ url, descriptors: '' });
+            continue;
+        }
+        let close = index;
+        while (close < value.length && value[close] !== ',')
+            close += 1;
+        out.push({ url, descriptors: value.slice(index, close).trim() });
+        index = close + 1;
+    }
+    return out;
+}
+/**
+ * Filter an image `srcset` candidate by candidate, where `safeImageSrcset`
+ * refuses the whole value. Every candidate URL goes through the image URL
+ * policy (`safeImageSrc`) at `trust`; a refused or malformed candidate (or one
+ * whose URL holds a comma) is dropped and the rest are kept. Candidates keep
+ * the descriptor kind of the first kept one (`x` or `w`), since a srcset
+ * cannot mix them. Returns `undefined` when nothing is left, so a caller can
+ * drop `sizes` with it.
+ */
+export function filterImageSrcset(value, trust = 'untrusted') {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > 16_384)
+        return undefined;
+    const kept = [];
+    let kind;
+    for (const { url, descriptors } of candidates(value)) {
+        if (url === '' || url.includes(','))
+            continue;
+        const candidate = safeImageSrcset(descriptors ? `${url} ${descriptors}` : url, trust);
+        if (candidate === undefined)
+            continue;
+        const candidateKind = descriptors.endsWith('w') ? 'width' : 'density';
+        kind ??= candidateKind;
+        if (candidateKind !== kind)
+            continue;
+        kept.push(candidate);
+    }
+    return kept.length > 0 ? safeImageSrcset(kept.join(', '), trust) : undefined;
+}

package/dist/url-policy/index.d.ts

@@ -1,4 +1,5 @@
 export { type HrefTrust, safeHref } from '../url/safe-href.js';
+export { filterImageSrcset } from './filter-image-srcset.js';
 export { safeImageSrc } from './safe-image-src.js';
 export { safeImageSrcset } from './safe-image-srcset.js';
 export { type SafeMediaSrcOptions, safeMediaSrc } from './safe-media-src.js';

package/dist/url-policy/index.js

@@ -1,4 +1,5 @@
 export { safeHref } from "../url/safe-href.js";
+export { filterImageSrcset } from "./filter-image-srcset.js";
 export { safeImageSrc } from "./safe-image-src.js";
 export { safeImageSrcset } from "./safe-image-srcset.js";
 export { safeMediaSrc } from "./safe-media-src.js";

package/dist/zip/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @texuli/core/zip: a deterministic ZIP writer (stored, or deflated through
+ * the platform `CompressionStream`) and CRC-32 (ADR-016).
+ */
+export { assertZipPath, type CompressionFormatName, canCompress, compressBytes, crc32, writeZip, writeZipAsync, type ZipEntry, type ZipOptions, } from './zip.js';

package/dist/zip/index.js

@@ -0,0 +1,5 @@
+/**
+ * @texuli/core/zip: a deterministic ZIP writer (stored, or deflated through
+ * the platform `CompressionStream`) and CRC-32 (ADR-016).
+ */
+export { assertZipPath, canCompress, compressBytes, crc32, writeZip, writeZipAsync, } from "./zip.js";

package/dist/zip/zip.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A deterministic ZIP writer for export packages (ADR-016). Entries keep
+ * their order, use UTF-8 names and a fixed 1980-01-01 timestamp, so the
+ * same input always produces the same bytes. `writeZip` stores entries
+ * (synchronous, no compression); `writeZipAsync` deflates them through the
+ * platform `CompressionStream` when it exists and keeps an entry stored when
+ * deflate is missing or would not make it smaller. ZIP64 is not supported.
+ */
+export interface ZipEntry {
+    path: string;
+    data: Uint8Array | string;
+    /** `writeZipAsync` only: `false` keeps this entry stored (an already compressed image). */
+    compress?: boolean;
+}
+export interface ZipOptions {
+    /** Deflate entries when the platform can (default true). */
+    compress?: boolean;
+}
+export type CompressionFormatName = 'deflate' | 'deflate-raw';
+/** CRC-32 (IEEE 802.3), as ZIP and PNG use. */
+export declare function crc32(data: Uint8Array): number;
+/** Refuse empty, absolute, backslashed, dot-segment and control-character paths (no traversal on extract). */
+export declare function assertZipPath(path: string): void;
+/** A stored (uncompressed) ZIP, synchronously. */
+export declare function writeZip(entries: readonly ZipEntry[]): Uint8Array;
+/** True when the platform has `CompressionStream` with raw deflate. */
+export declare function canCompress(format?: CompressionFormatName): boolean;
+/**
+ * Compress bytes with the platform `CompressionStream` (`deflate` is the
+ * zlib wrapper PDF's FlateDecode reads; `deflate-raw` is what ZIP stores),
+ * or `null` when the platform has no such stream.
+ */
+export declare function compressBytes(data: Uint8Array, format: CompressionFormatName): Promise<Uint8Array | null>;
+/** A ZIP whose entries are deflated where the platform can and where it makes them smaller. */
+export declare function writeZipAsync(entries: readonly ZipEntry[], options?: ZipOptions): Promise<Uint8Array>;