@onmark/cli 0.1.3

package/packages/bundler/dist/src/html_image.js

@@ -0,0 +1,337 @@
+// Native HTML image freezing at the deterministic bundle boundary.
+// Local bytes become opaque resources; projected documents retain exact uses.
+import { createHash } from "node:crypto";
+import { open } from "node:fs/promises";
+import { extname, isAbsolute, resolve } from "node:path";
+import { parse } from "parse5";
+import { hasAmbientImageAnimation } from "./image_admission.js";
+const IMAGE_EXTENSIONS = new Set([
+    ".avif",
+    ".gif",
+    ".jpeg",
+    ".jpg",
+    ".png",
+    ".svg",
+    ".webp",
+]);
+const DATA_IMAGE_EXTENSIONS = new Map([
+    ["image/avif", ".avif"],
+    ["image/gif", ".gif"],
+    ["image/jpeg", ".jpeg"],
+    ["image/png", ".png"],
+    ["image/svg+xml", ".svg"],
+    ["image/webp", ".webp"],
+]);
+const RESOURCE_DIRECTORY = "resources";
+/** Invalid or unreadable native image input. */
+export class HtmlImageError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "HtmlImageError";
+    }
+}
+/** Native image bytes exceed the bounded presentation artifact. */
+export class HtmlImageLimitError extends HtmlImageError {
+    constructor() {
+        super("authored HTML images exceed the presentation output-byte limit");
+        this.name = "HtmlImageLimitError";
+    }
+}
+/** Freezes local `img[src]` bytes and rewrites their authored references. */
+export async function freezeHtmlImages(source, directory, maxOutputBytes) {
+    const references = imageReferences(source);
+    const files = new Map();
+    const sources = new Map();
+    const edits = [];
+    let retainedBytes = 0;
+    for (const reference of references) {
+        const inline = inlineImageSource(reference.source);
+        if (inline !== undefined) {
+            rejectAmbientAnimation("inline image", inline.extension, inline.contents);
+            continue;
+        }
+        const local = localImageSource(reference.source);
+        const absolute = resolve(directory, local.path);
+        let path = sources.get(absolute);
+        if (path === undefined) {
+            const contents = await readBoundedImage(absolute, maxOutputBytes);
+            rejectAmbientAnimation(local.path, local.extension, contents);
+            path = resourcePath(contents, local.extension);
+            sources.set(absolute, path);
+            if (!files.has(path)) {
+                retainedBytes = retainBytes(retainedBytes, contents.byteLength, maxOutputBytes);
+                files.set(path, contents);
+            }
+        }
+        edits.push({
+            ...reference.valueRange,
+            replacement: `./${path}${local.suffix}`,
+        });
+    }
+    const resources = [...files]
+        .sort(([left], [right]) => comparePath(left, right))
+        .map(([path, contents]) => Object.freeze({ contents, path }));
+    return Object.freeze({
+        document: applyEdits(source, edits),
+        resources: Object.freeze(resources),
+    });
+}
+/** Selects only frozen images referenced by one projected document. */
+export function projectedImageResources(document, resources) {
+    const referenced = new Set(imageReferences(document)
+        .map(({ source }) => bundledResourcePath(source))
+        .filter((path) => path !== undefined));
+    return resources.filter(({ path }) => referenced.has(path));
+}
+function imageReferences(source) {
+    const references = [];
+    visit(parseDocument(source), (element) => {
+        rejectResponsiveImageSource(element);
+        if (element.tagName !== "img") {
+            return;
+        }
+        const attribute = element.attrs.find(({ name }) => name === "src");
+        if (attribute === undefined) {
+            return;
+        }
+        const location = element.sourceCodeLocation?.attrs?.["src"];
+        if (location === undefined) {
+            throw new HtmlImageError("cannot locate src on authored <img>");
+        }
+        references.push({
+            source: attribute.value,
+            valueRange: attributeValueRange(source, location),
+        });
+    });
+    return references;
+}
+function rejectResponsiveImageSource(element) {
+    if ((element.tagName === "img" || element.tagName === "source") &&
+        element.attrs.some(({ name }) => name === "srcset")) {
+        throw new HtmlImageError("authored HTML images must use src; srcset is not yet supported");
+    }
+}
+function attributeValueRange(source, location) {
+    const attribute = source.slice(location.startOffset, location.endOffset);
+    const equals = attribute.indexOf("=");
+    if (equals === -1) {
+        throw new HtmlImageError("local image src must have a value");
+    }
+    let start = equals + 1;
+    while (start < attribute.length && isHtmlSpace(attribute[start])) {
+        start += 1;
+    }
+    const quote = attribute[start];
+    return quote === '"' || quote === "'"
+        ? {
+            end: location.endOffset - 1,
+            start: location.startOffset + start + 1,
+        }
+        : {
+            end: location.endOffset,
+            start: location.startOffset + start,
+        };
+}
+function localImageSource(source) {
+    if (source.length === 0 || source !== source.trim()) {
+        throw new HtmlImageError("local image src must be nonempty and trimmed");
+    }
+    if (source.startsWith("//") || /^[a-z][a-z0-9+.-]*:/iu.test(source)) {
+        throw new HtmlImageError("authored HTML images must use a local relative path or data URL");
+    }
+    const suffixOffset = source.search(/[?#]/u);
+    const encodedPath = suffixOffset === -1 ? source : source.slice(0, suffixOffset);
+    const suffix = suffixOffset === -1 ? "" : source.slice(suffixOffset);
+    const path = decodeImagePath(encodedPath);
+    const extension = extname(path).toLowerCase();
+    if (!IMAGE_EXTENSIONS.has(extension)) {
+        throw new HtmlImageError(`authored HTML image uses unsupported extension ${extension || "(none)"}`);
+    }
+    return { extension, path, suffix };
+}
+function inlineImageSource(source) {
+    if (!/^data:/iu.test(source)) {
+        return undefined;
+    }
+    const separator = source.indexOf(",");
+    if (separator === -1) {
+        throw new HtmlImageError("inline image src is not a valid data URL");
+    }
+    const metadata = source.slice("data:".length, separator).split(";");
+    const mime = metadata.shift()?.toLowerCase() ?? "";
+    const extension = DATA_IMAGE_EXTENSIONS.get(mime);
+    if (extension === undefined) {
+        throw new HtmlImageError(`inline image uses unsupported media type ${mime || "(none)"}`);
+    }
+    const base64 = metadata.some((value) => value.toLowerCase() === "base64");
+    const unsupported = metadata.filter((value) => value.length > 0 &&
+        value.toLowerCase() !== "base64" &&
+        !/^charset=/iu.test(value));
+    if (unsupported.length > 0) {
+        throw new HtmlImageError("inline image data URL has unsupported metadata");
+    }
+    const payload = source.slice(separator + 1);
+    const contents = base64
+        ? decodeBase64Image(payload)
+        : decodeTextImage(payload, extension);
+    return { contents, extension };
+}
+function decodeBase64Image(source) {
+    if (!/^(?:[a-z0-9+/]{4})*(?:[a-z0-9+/]{2}==|[a-z0-9+/]{3}=)?$/iu.test(source)) {
+        throw new HtmlImageError("inline image data URL has invalid base64");
+    }
+    return Buffer.from(source, "base64");
+}
+function decodeTextImage(source, extension) {
+    if (extension !== ".svg") {
+        throw new HtmlImageError("inline binary images must use base64 data URLs");
+    }
+    try {
+        return new TextEncoder().encode(decodeURIComponent(source));
+    }
+    catch (error) {
+        throw new HtmlImageError("inline image data URL is not valid UTF-8", {
+            cause: error,
+        });
+    }
+}
+function rejectAmbientAnimation(source, extension, contents) {
+    if (hasAmbientImageAnimation(extension, contents)) {
+        throw new HtmlImageError(`${source} contains ambient animation; use an Onmark frame effect`);
+    }
+}
+function decodeImagePath(source) {
+    let path;
+    try {
+        path = decodeURIComponent(source);
+    }
+    catch (error) {
+        throw new HtmlImageError("local image src is not a valid URL", {
+            cause: error,
+        });
+    }
+    if (path.includes("\\") || isAbsolute(path)) {
+        throw new HtmlImageError("authored HTML images must use a portable relative path");
+    }
+    return path;
+}
+function bundledResourcePath(source) {
+    const suffixOffset = source.search(/[?#]/u);
+    const path = suffixOffset === -1 ? source : source.slice(0, suffixOffset);
+    const prefix = `./${RESOURCE_DIRECTORY}/`;
+    return path.startsWith(prefix) ? path.slice(2) : undefined;
+}
+// ── Frozen bytes
+async function readBoundedImage(path, limit) {
+    let file;
+    try {
+        file = await open(path, "r");
+    }
+    catch (error) {
+        throw new HtmlImageError(`cannot open local image ${path}`, {
+            cause: error,
+        });
+    }
+    try {
+        const chunks = [];
+        let length = 0;
+        while (length <= limit) {
+            const capacity = Math.min(64 * 1024, limit - length + 1);
+            const chunk = Buffer.allocUnsafe(capacity);
+            const { bytesRead } = await file.read(chunk, 0, capacity, length);
+            if (bytesRead === 0) {
+                return Buffer.concat(chunks, length);
+            }
+            chunks.push(chunk.subarray(0, bytesRead));
+            length += bytesRead;
+        }
+        throw new HtmlImageLimitError();
+    }
+    catch (error) {
+        if (error instanceof HtmlImageError) {
+            throw error;
+        }
+        throw new HtmlImageError(`cannot read local image ${path}`, {
+            cause: error,
+        });
+    }
+    finally {
+        await file.close();
+    }
+}
+function retainBytes(retained, added, limit) {
+    if (added > limit - retained) {
+        throw new HtmlImageLimitError();
+    }
+    return retained + added;
+}
+function resourcePath(contents, extension) {
+    const digest = createHash("sha256").update(contents).digest("hex");
+    return `${RESOURCE_DIRECTORY}/${digest}${extension}`;
+}
+// ── Parsed HTML and edits
+function parseDocument(source) {
+    const errors = [];
+    const document = parse(source, {
+        onParseError(error) {
+            if (error.code !== "missing-doctype") {
+                errors.push(error);
+            }
+        },
+        sourceCodeLocationInfo: true,
+    });
+    if (errors.length > 0) {
+        throw new HtmlImageError(`cannot freeze images after parse error ${errors[0].code}`);
+    }
+    return document;
+}
+function visit(node, visitor) {
+    const pending = [node];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined) {
+            break;
+        }
+        if ("tagName" in current) {
+            visitor(current);
+        }
+        if ("childNodes" in current) {
+            for (let index = current.childNodes.length - 1; index >= 0; index -= 1) {
+                const child = current.childNodes[index];
+                if (child !== undefined) {
+                    pending.push(child);
+                }
+            }
+        }
+    }
+}
+function applyEdits(source, edits) {
+    const ordered = edits.toSorted((left, right) => left.start - right.start);
+    const parts = [];
+    let cursor = 0;
+    for (const edit of ordered) {
+        if (edit.start < cursor || edit.end < edit.start) {
+            throw new HtmlImageError("authored image edits overlap");
+        }
+        parts.push(source.slice(cursor, edit.start), edit.replacement);
+        cursor = edit.end;
+    }
+    parts.push(source.slice(cursor));
+    return parts.join("");
+}
+function comparePath(left, right) {
+    if (left < right) {
+        return -1;
+    }
+    if (left > right) {
+        return 1;
+    }
+    return 0;
+}
+function isHtmlSpace(character) {
+    return (character === "\t" ||
+        character === "\n" ||
+        character === "\f" ||
+        character === "\r" ||
+        character === " ");
+}

package/packages/bundler/dist/src/image_admission.d.ts

@@ -0,0 +1,2 @@
+/** Reports whether browser wall time could change the decoded image pixels. */
+export declare function hasAmbientImageAnimation(extension: string, contents: Uint8Array): boolean;

package/packages/bundler/dist/src/image_admission.js

@@ -0,0 +1,217 @@
+// Deterministic admission for image bytes consumed by browser presentations.
+// Static pixels may cross the bundle boundary; self-advancing formats may not.
+import { parse } from "parse5";
+const PNG_SIGNATURE = Uint8Array.from([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+const GIF_HEADERS = ["GIF87a", "GIF89a"];
+const SVG_ANIMATION_ELEMENTS = new Set([
+    "animate",
+    "animatemotion",
+    "animatetransform",
+    "foreignobject",
+    "image",
+    "script",
+    "set",
+]);
+const CSS_ANIMATION = /(?:@keyframes|\banimation(?:-[a-z-]+)?\s*:|\btransition(?:-[a-z-]+)?\s*:)/iu;
+/** Reports whether browser wall time could change the decoded image pixels. */
+export function hasAmbientImageAnimation(extension, contents) {
+    if (gifFrameCount(contents) > 1 ||
+        pngHasAnimationControl(contents) ||
+        webpHasAnimation(contents) ||
+        avifIsImageSequence(contents)) {
+        return true;
+    }
+    return extension === ".svg" || looksLikeSvg(contents)
+        ? svgHasAnimation(contents)
+        : false;
+}
+// ── Raster containers
+function pngHasAnimationControl(contents) {
+    if (!startsWith(contents, PNG_SIGNATURE)) {
+        return false;
+    }
+    let offset = PNG_SIGNATURE.length;
+    while (offset + 12 <= contents.length) {
+        const length = readU32BigEndian(contents, offset);
+        const type = ascii(contents, offset + 4, 4);
+        const next = offset + 12 + length;
+        if (!Number.isSafeInteger(next) || next > contents.length) {
+            return false;
+        }
+        if (type === "acTL") {
+            return true;
+        }
+        if (type === "IEND") {
+            return false;
+        }
+        offset = next;
+    }
+    return false;
+}
+function gifFrameCount(contents) {
+    if (contents.length < 13 || !GIF_HEADERS.includes(ascii(contents, 0, 6))) {
+        return 0;
+    }
+    let offset = 13 + colorTableBytes(contents[10]);
+    let frames = 0;
+    while (offset < contents.length) {
+        switch (contents[offset]) {
+            case 0x2c: {
+                if (offset + 10 > contents.length) {
+                    return frames;
+                }
+                frames += 1;
+                if (frames > 1) {
+                    return frames;
+                }
+                offset += 10 + colorTableBytes(contents[offset + 9]);
+                if (offset >= contents.length) {
+                    return frames;
+                }
+                offset = skipSubBlocks(contents, offset + 1);
+                break;
+            }
+            case 0x21:
+                offset = skipSubBlocks(contents, offset + 2);
+                break;
+            case 0x3b:
+                return frames;
+            default:
+                return frames;
+        }
+    }
+    return frames;
+}
+function colorTableBytes(flags) {
+    return (flags & 0x80) === 0 ? 0 : 3 * 2 ** ((flags & 0x07) + 1);
+}
+function skipSubBlocks(contents, initialOffset) {
+    let offset = initialOffset;
+    while (offset < contents.length) {
+        const length = contents[offset];
+        offset += 1;
+        if (length === 0) {
+            return offset;
+        }
+        offset += length;
+    }
+    return contents.length;
+}
+function webpHasAnimation(contents) {
+    if (ascii(contents, 0, 4) !== "RIFF" || ascii(contents, 8, 4) !== "WEBP") {
+        return false;
+    }
+    let offset = 12;
+    while (offset + 8 <= contents.length) {
+        const type = ascii(contents, offset, 4);
+        const length = readU32LittleEndian(contents, offset + 4);
+        const payload = offset + 8;
+        const next = payload + length + (length % 2);
+        if (!Number.isSafeInteger(next) || next > contents.length) {
+            return false;
+        }
+        if (type === "ANIM" || type === "ANMF") {
+            return true;
+        }
+        if (type === "VP8X" && length > 0 && (contents[payload] & 0x02) !== 0) {
+            return true;
+        }
+        offset = next;
+    }
+    return false;
+}
+function avifIsImageSequence(contents) {
+    if (ascii(contents, 4, 4) !== "ftyp" || contents.length < 16) {
+        return false;
+    }
+    const boxLength = readU32BigEndian(contents, 0);
+    if (boxLength < 16 || boxLength > contents.length) {
+        return false;
+    }
+    for (let offset = 8; offset + 4 <= boxLength; offset += 4) {
+        const brand = ascii(contents, offset, 4);
+        if (brand === "avis" || brand === "msf1") {
+            return true;
+        }
+    }
+    return false;
+}
+// ── SVG document
+function svgHasAnimation(contents) {
+    let source;
+    try {
+        source = new TextDecoder("utf-8", { fatal: true }).decode(contents);
+    }
+    catch {
+        return false;
+    }
+    const pending = [parse(source)];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined) {
+            break;
+        }
+        if ("tagName" in current && svgElementHasAnimation(current)) {
+            return true;
+        }
+        if ("childNodes" in current) {
+            for (let index = current.childNodes.length - 1; index >= 0; index -= 1) {
+                const child = current.childNodes[index];
+                if (child !== undefined) {
+                    pending.push(child);
+                }
+            }
+        }
+    }
+    return false;
+}
+function looksLikeSvg(contents) {
+    const prefix = new TextDecoder()
+        .decode(contents.subarray(0, 512))
+        .trimStart();
+    return prefix.startsWith("<svg") || prefix.startsWith("<?xml");
+}
+function svgElementHasAnimation(element) {
+    if (SVG_ANIMATION_ELEMENTS.has(element.tagName.toLowerCase())) {
+        return true;
+    }
+    for (const attribute of element.attrs) {
+        if (attribute.name.toLowerCase().startsWith("on")) {
+            return true;
+        }
+        if (attribute.name === "style" && cssCanAnimate(attribute.value)) {
+            return true;
+        }
+    }
+    if (element.tagName === "style") {
+        return element.childNodes.some((child) => "value" in child && cssCanAnimate(child.value));
+    }
+    return false;
+}
+function cssCanAnimate(source) {
+    return source.includes("\\") || CSS_ANIMATION.test(source);
+}
+// ── Byte reading
+function startsWith(contents, prefix) {
+    return prefix.every((byte, index) => contents[index] === byte);
+}
+function ascii(contents, offset, length) {
+    if (offset < 0 || offset + length > contents.length) {
+        return "";
+    }
+    return String.fromCharCode(...contents.subarray(offset, offset + length));
+}
+function readU32BigEndian(contents, offset) {
+    return (contents[offset] * 0x1_00_00_00 +
+        (contents[offset + 1] << 16) +
+        (contents[offset + 2] << 8) +
+        contents[offset + 3]);
+}
+function readU32LittleEndian(contents, offset) {
+    return (contents[offset] +
+        (contents[offset + 1] << 8) +
+        (contents[offset + 2] << 16) +
+        contents[offset + 3] * 0x1_00_00_00);
+}

package/packages/bundler/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { BundleError, bundlePresentation, type BundleArtifact, type BundleErrorKind, type BundleFile, type BundleManifest, type BundleOptions, } from "./presentation.js";
+export { BUNDLE_ASSET_DIRECTORY, BUNDLE_ENTRY_POINT, BUNDLE_MANIFEST_FILE, BUNDLE_REGION_DIRECTORY, BUNDLE_TEMPORAL_CAPABILITIES, BUNDLE_VERSION, } from "./generated/bundle-manifest.js";

package/packages/bundler/dist/src/index.js

@@ -0,0 +1,3 @@
+// Public facade for deterministic presentation bundling.
+export { BundleError, bundlePresentation, } from "./presentation.js";
+export { BUNDLE_ASSET_DIRECTORY, BUNDLE_ENTRY_POINT, BUNDLE_MANIFEST_FILE, BUNDLE_REGION_DIRECTORY, BUNDLE_TEMPORAL_CAPABILITIES, BUNDLE_VERSION, } from "./generated/bundle-manifest.js";

package/packages/bundler/dist/src/presentation.d.ts

@@ -0,0 +1,41 @@
+import type { PresentationFrameBehavior, PresentationTemporalCapability, PresentationVisualCapability } from "../../../runtime/dist/src/index.js";
+import { type BundleFile as WireBundleFile, type BundleManifest as WireBundleManifest } from "./generated/bundle-manifest.js";
+type Immutable<T> = T extends object ? {
+    readonly [Key in keyof T]: Immutable<T[Key]>;
+} : T;
+/** Immutable view of one Rust-owned bundle payload entry. */
+export type BundleFile = Immutable<WireBundleFile>;
+/** Immutable view of the versioned Rust-owned bundle manifest. */
+export type BundleManifest = Immutable<WireBundleManifest>;
+/** Explicit inputs for one authored HTML document. */
+export interface BundleOptions {
+    /** Authored document or a private snapshot containing its exact bytes. */
+    readonly document: string;
+    /** Base for inline-module imports when `document` is a private snapshot. */
+    readonly resolveDirectory?: string;
+    readonly outputDirectory: string;
+    readonly maxOutputBytes: number;
+    readonly temporalCapability: PresentationTemporalCapability;
+    readonly visualCapability: PresentationVisualCapability;
+    readonly frameBehavior: PresentationFrameBehavior;
+}
+/** Published directory and its owned immutable manifest snapshot. */
+export interface BundleArtifact {
+    readonly directory: string;
+    readonly manifest: BundleManifest;
+    readonly regions: readonly BundleRegionArtifact[];
+}
+/** One shot-scoped immutable browser artifact within a random-access build. */
+export interface BundleRegionArtifact {
+    readonly directory: string;
+    readonly manifest: BundleManifest;
+}
+export type BundleErrorKind = "configuration" | "build" | "output" | "outputLimit";
+/** Typed failure from presentation compilation or artifact publication. */
+export declare class BundleError extends Error {
+    readonly kind: BundleErrorKind;
+    constructor(kind: BundleErrorKind, message: string, cause?: unknown);
+}
+/** Builds one HTML-authored presentation without a parallel entry file. */
+export declare function bundlePresentation(options: BundleOptions): Promise<BundleArtifact>;
+export {};