@peekling/runtime 0.1.0

package/dist/loader.js

@@ -0,0 +1,477 @@
+import { packIssue, PackLoadError, PackValidationError, throwPackIssue, } from "./errors.js";
+import { isNormalizedPack, validateNormalizedPack } from "./normalized.js";
+import { parseManifestText, selectNativeDensity, validateNativePack, } from "./pack.js";
+import { inspectImageStructure, SHA256_PATTERN } from "./pack-shared.js";
+import { characterPackReference } from "./registry.js";
+import { OwnDataError, snapshotPackData } from "./own-data.js";
+import { compactRuntimeDiagnostics, runtimeMessage, } from "./runtime-diagnostics.js";
+import { isHttpPath } from "./contracts.js";
+const DEFAULT_RESOURCE_TIMEOUT_MS = 30_000;
+export function resolveManifestUrl(input, base) {
+    if (!isHttpPath(input, base))
+        throwPackIssue("url.protocol", "Relative path or HTTPS required");
+    try {
+        return new URL(input, base).href;
+    }
+    catch {
+        throwPackIssue("url.invalid", "Invalid pack URL");
+    }
+}
+function requireMime(response, allowed) {
+    const mime = response.headers
+        .get("content-type")
+        ?.split(";", 1)[0]
+        ?.trim()
+        .toLowerCase();
+    if (!mime || !allowed.includes(mime)) {
+        throwPackIssue("mime.invalid", "Invalid Content-Type");
+    }
+    return mime;
+}
+function failureCategory(error) {
+    if (error instanceof DOMException && error.name === "AbortError") {
+        return "abort";
+    }
+    if (error instanceof PackLoadError)
+        return error.category;
+    if (error instanceof PackValidationError) {
+        for (const code of error.issueCodes) {
+            const suffix = code.slice(code.indexOf(".") + 1);
+            if (suffix === "hash")
+                return "hash";
+            if (code === "mime.invalid" || suffix === "mime")
+                return "mime";
+            if (code.startsWith("png.") ||
+                code.startsWith("webp.") ||
+                (code.startsWith("atlas.") &&
+                    ["dimensions", "pixels", "alpha", "size"].includes(suffix))) {
+                return "image";
+            }
+            if (suffix === "size")
+                return "size";
+            if (suffix.startsWith("integrity-"))
+                return "integrity";
+        }
+    }
+    return "validation";
+}
+function isAbortFailure(error, signal) {
+    return (signal.aborted ||
+        (error instanceof DOMException && error.name === "AbortError"));
+}
+const packLoadMessage = compactRuntimeDiagnostics
+    ? (code) => code
+    : (code, value) => {
+        switch (code) {
+            case "manifest.network":
+                return value === 1
+                    ? "Manifest response failed"
+                    : "Manifest network request failed";
+            case "atlas.network":
+                return value === 1
+                    ? "Atlas response failed"
+                    : "Atlas network request failed";
+            case "manifest.timeout":
+                return "Manifest request timed out";
+            case "atlas.timeout":
+                return "Atlas request timed out";
+            case "manifest.http":
+                return `Manifest HTTP ${value}`;
+            case "atlas.http":
+                return `Atlas HTTP ${value}`;
+            case "atlas.decode":
+                return "Atlas decode failed";
+            case "atlas.unusable":
+                return "No usable atlas";
+            default:
+                return code;
+        }
+    };
+function resourceDeadline(parent, timeoutMs, timeoutCode) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const abort = () => controller.abort(parent.reason);
+    if (parent.aborted)
+        abort();
+    else
+        parent.addEventListener("abort", abort, { once: true });
+    const timer = globalThis.setTimeout(() => {
+        if (controller.signal.aborted)
+            return;
+        timedOut = true;
+        controller.abort(new DOMException(packLoadMessage(timeoutCode), "TimeoutError"));
+    }, timeoutMs);
+    return {
+        signal: controller.signal,
+        get timedOut() {
+            return timedOut;
+        },
+        close() {
+            globalThis.clearTimeout(timer);
+            parent.removeEventListener("abort", abort);
+        },
+    };
+}
+async function withResourceDeadline(parent, timeoutMs, timeoutCode, operation) {
+    const deadline = resourceDeadline(parent, timeoutMs, timeoutCode);
+    try {
+        return await operation(deadline.signal);
+    }
+    catch (error) {
+        if (deadline.timedOut &&
+            (error === deadline.signal.reason ||
+                (error instanceof DOMException &&
+                    (error.name === "AbortError" || error.name === "TimeoutError")))) {
+            throw new PackLoadError(timeoutCode, "timeout", packLoadMessage(timeoutCode), error);
+        }
+        throw error;
+    }
+    finally {
+        deadline.close();
+    }
+}
+async function fetchResource(fetcher, url, signal, code) {
+    try {
+        return await fetcher(url, { signal });
+    }
+    catch (error) {
+        if (isAbortFailure(error, signal))
+            throw error;
+        throw new PackLoadError(code, "network", packLoadMessage(code), error);
+    }
+}
+async function readResponseBytes(response, limit, signal, code) {
+    try {
+        return await responseBytes(response, limit, signal);
+    }
+    catch (error) {
+        if (isAbortFailure(error, signal) ||
+            error instanceof PackLoadError ||
+            error instanceof PackValidationError) {
+            throw error;
+        }
+        throw new PackLoadError(code, "network", packLoadMessage(code, 1), error);
+    }
+}
+function inspectAtlasBytes(bytes, mime, normalized, expected) {
+    const geometry = inspectImageStructure(bytes, mime);
+    if (geometry.width !== expected.width ||
+        geometry.height !== expected.height) {
+        throwPackIssue("atlas.dimensions", `Atlas must be exactly ${expected.width}x${expected.height}`);
+    }
+    if (!normalized && !geometry.hasAlpha) {
+        throwPackIssue("atlas.alpha", "Native PNG atlas requires alpha");
+    }
+}
+async function matchesSha256(bytes, expected, manifest = false) {
+    const subject = manifest ? "Selected character manifest" : "Atlas";
+    const codePrefix = manifest ? "manifest" : "atlas";
+    if (!SHA256_PATTERN.test(expected)) {
+        throwPackIssue(`${codePrefix}.integrity-declaration`, `${subject} SHA-256 declaration is invalid`);
+    }
+    let digest;
+    try {
+        const subtle = globalThis.crypto?.subtle;
+        digest = subtle?.digest.bind(subtle);
+    }
+    catch { }
+    if (!digest) {
+        throwPackIssue(`${codePrefix}.integrity-unavailable`, `${subject} SHA-256 integrity verification is unavailable`);
+    }
+    try {
+        const computed = new Uint8Array(await digest("SHA-256", bytes));
+        return !computed.some((byte, index) => byte !== Number.parseInt(expected.slice(index * 2, index * 2 + 2), 16));
+    }
+    catch {
+        throwPackIssue(`${codePrefix}.integrity-failed`, `${subject} SHA-256 integrity verification failed`);
+    }
+}
+async function imageGeometry(image, objectUrl, signal) {
+    await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            image.removeEventListener("load", load);
+            image.removeEventListener("error", error);
+            signal.removeEventListener("abort", abort);
+        };
+        const load = () => {
+            cleanup();
+            resolve();
+        };
+        const error = () => {
+            cleanup();
+            reject(new PackLoadError("atlas.decode", "decode", packLoadMessage("atlas.decode")));
+        };
+        const abort = () => {
+            cleanup();
+            image.removeAttribute("src");
+            reject(signal.reason);
+        };
+        image.addEventListener("load", load, { once: true });
+        image.addEventListener("error", error, { once: true });
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            return abort();
+        image.src = objectUrl;
+    });
+    return { width: image.naturalWidth, height: image.naturalHeight };
+}
+async function responseBytes(response, limit, signal) {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > limit)
+        throwPackIssue("resource.size", "Resource too large");
+    if (!response.body) {
+        const value = new Uint8Array(await response.arrayBuffer());
+        if (value.byteLength > limit)
+            throwPackIssue("resource.size", "Resource too large");
+        return value;
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > limit) {
+                await reader.cancel();
+                throwPackIssue("resource.size", "Resource too large");
+            }
+            chunks.push(value);
+        }
+    }
+    catch (error) {
+        try {
+            await reader.cancel(error);
+        }
+        catch {
+            // The original transport or abort failure is the useful diagnostic.
+        }
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const output = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return output;
+}
+export function requiredAtlasDensity(devicePixelRatio, renderScale, maxDensity = 4) {
+    const dpr = Number.isFinite(devicePixelRatio) && devicePixelRatio > 0
+        ? devicePixelRatio
+        : 1;
+    return Math.min(dpr * renderScale, maxDensity);
+}
+export async function loadNativePack(options) {
+    const resourceTimeoutMs = options.resourceTimeoutMs ?? DEFAULT_RESOURCE_TIMEOUT_MS;
+    if (options.pack === undefined &&
+        options.packUrl === undefined &&
+        options.character === undefined) {
+        throwPackIssue("manifest.selection", "Select an explicit character, packUrl, or pack");
+    }
+    let raw;
+    let manifestUrl = options.packUrl;
+    let manifestSha256;
+    if (options.pack !== undefined)
+        raw = options.pack;
+    else {
+        if (manifestUrl === undefined) {
+            const reference = characterPackReference(options.character);
+            manifestUrl = reference.url;
+            manifestSha256 = reference.sha256;
+        }
+        const requestedManifestUrl = resolveManifestUrl(manifestUrl, options.baseUrl);
+        manifestUrl = requestedManifestUrl;
+        const bytes = await withResourceDeadline(options.signal, resourceTimeoutMs, "manifest.timeout", async (signal) => {
+            const response = await fetchResource(options.fetch, requestedManifestUrl, signal, "manifest.network");
+            if (!response.ok)
+                throw new PackLoadError("manifest.http", "http", packLoadMessage("manifest.http", response.status));
+            requireMime(response, ["application/json"]);
+            return readResponseBytes(response, 64 * 1024, signal, "manifest.network");
+        });
+        if (manifestSha256 && !(await matchesSha256(bytes, manifestSha256, true))) {
+            throwPackIssue("manifest.hash", "Registered Peek manifest hash mismatch");
+        }
+        try {
+            raw = parseManifestText(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        }
+        catch (error) {
+            if (error instanceof PackValidationError)
+                throw error;
+            throwPackIssue("manifest.utf8", "Invalid manifest UTF-8");
+        }
+    }
+    try {
+        raw = snapshotPackData(raw);
+    }
+    catch (error) {
+        if (error instanceof OwnDataError) {
+            throw new PackValidationError([error.message], error.issueCode ? [error.issueCode] : []);
+        }
+        throw error;
+    }
+    const normalized = isNormalizedPack(raw);
+    const validate = normalized ? validateNormalizedPack : validateNativePack;
+    const first = validate(raw);
+    const preferred = options.densityOverride ??
+        requiredAtlasDensity(options.devicePixelRatio ?? 1, options.renderScale ?? first.defaultScale, options.maxDensity);
+    let selected = validate(raw, undefined, preferred);
+    let released = false;
+    let currentObjectUrl = "";
+    const resolveUrl = (src) => options.atlasUrl ??
+        (manifestUrl
+            ? new URL(src, new URL(manifestUrl, options.baseUrl)).href
+            : undefined);
+    const candidates = (required) => {
+        const variants = first.atlas.variants;
+        if (!variants?.length) {
+            const density = selected.atlas.density ?? 1;
+            if (options.densityOverride !== undefined &&
+                options.densityOverride !== density) {
+                throwPackIssue("atlas.override-density", "density must match the single atlas density");
+            }
+            if (density > (options.maxDensity ?? 4)) {
+                throwPackIssue("atlas.max-density", "Single atlas density exceeds maxDensity");
+            }
+            if (!selected.atlas.sha256) {
+                throwPackIssue("atlas.integrity-declaration", "Atlas SHA-256 declaration is missing");
+            }
+            return [
+                {
+                    src: selected.atlas.src,
+                    density,
+                    sha256: selected.atlas.sha256,
+                },
+            ];
+        }
+        const available = variants.filter((item) => item.density <= (options.maxDensity ?? 4));
+        if (!available.length)
+            throwPackIssue("atlas.max-density", "No atlas variant at or below maxDensity");
+        if (options.atlasUrl !== undefined) {
+            if (options.densityOverride === undefined) {
+                throwPackIssue("atlas.override-density", "atlasUrl with variants requires an explicit density");
+            }
+            const overridden = available.find((item) => item.density === options.densityOverride);
+            if (!overridden) {
+                throwPackIssue("atlas.override-density", "atlasUrl density must name a declared variant at or below maxDensity");
+            }
+            return [overridden];
+        }
+        const target = selectNativeDensity(available.map((item) => item.density), required);
+        return available
+            .filter((item) => item.density <= target)
+            .sort((a, b) => b.density - a.density);
+    };
+    const fetchCandidate = async (candidate) => {
+        const assetUrl = resolveUrl(candidate.src);
+        if (!assetUrl)
+            throwPackIssue("atlas.url", "atlasUrl required");
+        const [mime, bytes] = await withResourceDeadline(options.signal, resourceTimeoutMs, "atlas.timeout", async (signal) => {
+            const response = await fetchResource(options.fetch, assetUrl, signal, "atlas.network");
+            if (!response.ok)
+                throw new PackLoadError("atlas.http", "http", packLoadMessage("atlas.http", response.status));
+            const mime = requireMime(response, normalized ? ["image/png", "image/webp"] : ["image/png"]);
+            const bytes = await readResponseBytes(response, normalized ? 32 * 1024 * 1024 : 4 * 1024 * 1024, signal, "atlas.network");
+            return [mime, bytes];
+        });
+        if (!(await matchesSha256(bytes, candidate.sha256))) {
+            throwPackIssue("atlas.hash", "Atlas hash mismatch");
+        }
+        const candidatePack = validate(raw, undefined, candidate.density);
+        inspectAtlasBytes(bytes, mime, normalized, {
+            width: candidatePack.atlas.columns * candidatePack.atlas.cellWidth,
+            height: candidatePack.atlas.rows * candidatePack.atlas.cellHeight,
+        });
+        const objectUrl = options.createObjectURL(new Blob([bytes]));
+        try {
+            const geometry = await imageGeometry(options.image(), objectUrl, options.signal);
+            const pack = validate(raw, { ...geometry, byteLength: bytes.byteLength }, candidate.density);
+            return { pack, objectUrl };
+        }
+        catch (error) {
+            options.revokeObjectURL(objectUrl);
+            throw error;
+        }
+    };
+    const loadWithFallback = async (required, upgrading) => {
+        let lastError;
+        const available = candidates(required);
+        for (const [index, candidate] of available.entries()) {
+            if (upgrading && candidate.density <= (selected.atlas.density ?? 1))
+                return undefined;
+            try {
+                return await fetchCandidate(candidate);
+            }
+            catch (error) {
+                if (options.signal.aborted) {
+                    options.diagnostic?.(runtimeMessage("atlas.abort", "Atlas load aborted."), "abort");
+                    throw error;
+                }
+                lastError = error;
+                const category = failureCategory(error);
+                const fallback = index < available.length - 1;
+                options.diagnostic?.(runtimeMessage(`atlas.${category}.${fallback ? "fallback" : "exhausted"}`, () => `Atlas ${candidate.density}x failed (${category}); ${fallback ? "falling back" : "no fallback remains"}.`), category);
+            }
+        }
+        if (upgrading)
+            return undefined;
+        throw (lastError ??
+            new PackLoadError("atlas.unusable", "validation", packLoadMessage("atlas.unusable")));
+    };
+    const initial = await loadWithFallback(preferred, false);
+    if (!initial)
+        throw new PackLoadError("atlas.unusable", "validation", packLoadMessage("atlas.unusable"));
+    selected = initial.pack;
+    currentObjectUrl = initial.objectUrl;
+    let desiredDensity = selected.atlas.density ?? 1;
+    let upgradeGeneration = 0;
+    const loaded = {
+        get content() {
+            return selected;
+        },
+        get atlasObjectUrl() {
+            return currentObjectUrl;
+        },
+        get loadedDensity() {
+            return selected.atlas.density ?? 1;
+        },
+        async upgrade(requiredDensity) {
+            if (released ||
+                options.atlasUrl !== undefined ||
+                requiredDensity <= loaded.loadedDensity)
+                return false;
+            desiredDensity = Math.max(desiredDensity, requiredDensity);
+            const generation = ++upgradeGeneration;
+            const next = await loadWithFallback(desiredDensity, true);
+            const nextDensity = next?.pack.atlas.density ?? 1;
+            if (!next ||
+                released ||
+                nextDensity <= loaded.loadedDensity ||
+                (generation !== upgradeGeneration && nextDensity < desiredDensity)) {
+                if (next)
+                    options.revokeObjectURL(next.objectUrl);
+                return false;
+            }
+            const previous = currentObjectUrl;
+            selected = next.pack;
+            currentObjectUrl = next.objectUrl;
+            options.revokeObjectURL(previous);
+            return true;
+        },
+        release() {
+            if (released)
+                return;
+            released = true;
+            if (currentObjectUrl)
+                options.revokeObjectURL(currentObjectUrl);
+            currentObjectUrl = "";
+        },
+    };
+    return loaded;
+}

package/dist/locomotion.d.ts

@@ -0,0 +1,8 @@
+import type { LocomotionKeyframe, StateDefinition } from "./types.js";
+export declare function animationCycleMs(state: StateDefinition): number;
+export declare function locomotionSample(keyframes: readonly Readonly<LocomotionKeyframe>[] | undefined, phase: number): {
+    advance: number;
+    lift: number;
+};
+export declare function locomotionAdvance(keyframes: readonly Readonly<LocomotionKeyframe>[] | undefined, fromCycles: number, toCycles: number): number;
+//# sourceMappingURL=locomotion.d.ts.map

package/dist/locomotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locomotion.d.ts","sourceRoot":"","sources":["../src/locomotion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEtE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAI/D;AAED,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,QAAQ,CAAC,kBAAkB,CAAC,EAAE,GAAG,SAAS,EAC9D,KAAK,EAAE,MAAM,GACZ;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAgBnC;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,QAAQ,CAAC,kBAAkB,CAAC,EAAE,GAAG,SAAS,EAC9D,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,CAUR"}

package/dist/locomotion.js

@@ -0,0 +1,29 @@
+export function animationCycleMs(state) {
+    if (state.durations)
+        return state.durations.reduce((sum, value) => sum + value, 0);
+    return (state.frames.length / (state.fps ?? 1)) * 1000;
+}
+export function locomotionSample(keyframes, phase) {
+    const normalized = ((phase % 1) + 1) % 1;
+    if (!keyframes?.length)
+        return { advance: normalized, lift: 0 };
+    const nextIndex = keyframes.findIndex((item) => item.at >= normalized);
+    const next = keyframes[nextIndex < 0 ? keyframes.length - 1 : nextIndex];
+    const previous = keyframes[Math.max(0, (nextIndex < 0 ? keyframes.length - 1 : nextIndex) - 1)];
+    if (next.at === previous.at)
+        return { advance: next.advance, lift: next.lift };
+    const amount = (normalized - previous.at) / (next.at - previous.at);
+    return {
+        advance: previous.advance + (next.advance - previous.advance) * amount,
+        lift: previous.lift + (next.lift - previous.lift) * amount,
+    };
+}
+export function locomotionAdvance(keyframes, fromCycles, toCycles) {
+    const whole = Math.floor(toCycles) - Math.floor(fromCycles);
+    const cycleAdvance = keyframes?.length
+        ? keyframes.at(-1).advance - keyframes[0].advance
+        : 1;
+    return (whole * cycleAdvance +
+        locomotionSample(keyframes, toCycles).advance -
+        locomotionSample(keyframes, fromCycles).advance);
+}

package/dist/normalized.d.ts

@@ -0,0 +1,5 @@
+import { type AtlasGeometry, type NormalizedPack } from "./types.js";
+export declare function isNormalizedPack(input: unknown): input is NormalizedPack;
+export declare function validateNormalizedPack(input: unknown, geometry?: AtlasGeometry, preferredDensity?: number): NormalizedPack;
+export declare function resolveCapabilityName(requested: string | undefined, pack: NormalizedPack): string | undefined;
+//# sourceMappingURL=normalized.d.ts.map

package/dist/normalized.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalized.d.ts","sourceRoot":"","sources":["../src/normalized.ts"],"names":[],"mappings":"AAiBA,OAAO,EAEL,KAAK,aAAa,EAElB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAepB,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAKxE;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,QAAQ,CAAC,EAAE,aAAa,EACxB,gBAAgB,CAAC,EAAE,MAAM,GACxB,cAAc,CA+WhB;AAED,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,IAAI,EAAE,cAAc,GACnB,MAAM,GAAG,SAAS,CAKpB"}