@xprite/pixelate 0.0.0-stage → 0.1.0

package/dist/grid-ac-rl-consensus.js

@@ -0,0 +1,497 @@
+/**
+ * AC+RL consensus detector via Fixer Rust WASM.
+ *
+ * Returns grid dimensions when autocorrelation and run-lengths agree
+ * on pixel grid size (consensus="fast:ac+rl(S)").
+ *
+ * Overlap modes:
+ * - Node (pixelbench / Vite SSR): worker_threads — beginAcRlConsensusJob + sync
+ *   finishAcRlConsensusJob via receiveMessageOnPort (existing Exact harness path).
+ * - Browser product (import-worker): nested Worker + Promise join via
+ *   beginAcRlConsensusJobAsync / finishAcRlConsensusJobAsync — no COOP/COEP /
+ *   SharedArrayBuffer required (sync Atomics.wait join is what needed isolation).
+ * - Fallback: on-thread detectAcRlConsensus (sync job).
+ *
+ * Set XPRITE_AC_RL_WORKER=0 to force sync detect on Node. Product registers a
+ * browser worker factory with setAcRlBrowserWorkerFactory from import-worker.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+const NODE_FS = "node:fs";
+const WASM_BINARY = "../wasm/pixelfixer_detect_bg.wasm";
+const NODE_WORKER = "../wasm/ac-rl-detect-worker.mjs";
+/**
+ * A file in the package's `wasm/` folder, next to the compiled sources; null when this module
+ * was loaded from a URL that has no such neighbour (a bundle, a data: URL).
+ */
+function packageFile(relative) {
+    try {
+        const url = new URL(relative, import.meta.url);
+        return url.protocol === "file:" ? decodeURIComponent(url.pathname) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function nodeProcess() {
+    return globalThis.process;
+}
+function browserMessageChannelCtor() {
+    return globalThis.MessageChannel;
+}
+let wasmLoaded = false;
+let detectFastAcRl = null;
+let wtModule;
+let detectWorker = null;
+let workerReady = false;
+let workerFailed = false;
+let browserWorkerFactory = null;
+let browserDetectWorker = null;
+let browserWorkerReady = false;
+let browserWorkerFailed = false;
+let browserWorkerInitializing = null;
+const browserRequests = new Set();
+function nodeWorkerEnabled() {
+    const process = nodeProcess();
+    if (!process?.versions?.node)
+        return false;
+    if (process.env.XPRITE_AC_RL_WORKER === "0")
+        return false;
+    return true;
+}
+/**
+ * Product import-worker: register nested Worker factory (Vite `new URL(..., import.meta.url)`).
+ * Param is `() => unknown` so DOM `Worker` from apps/editor assigns without sharing DOM libs.
+ */
+export function setAcRlBrowserWorkerFactory(factory) {
+    browserWorkerFactory = factory ? () => factory() : null;
+    for (const cancel of browserRequests)
+        cancel();
+    if (browserDetectWorker) {
+        try {
+            browserDetectWorker.terminate();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    browserDetectWorker = null;
+    browserWorkerReady = false;
+    browserWorkerFailed = false;
+    browserWorkerInitializing = null;
+}
+/** Lazy-load worker_threads without a static import (browser-safe). */
+function loadWorkerThreads() {
+    if (wtModule !== undefined)
+        return wtModule;
+    if (!nodeWorkerEnabled()) {
+        wtModule = null;
+        return null;
+    }
+    const injected = globalThis.__XPRITE_WORKER_THREADS__;
+    if (injected &&
+        typeof injected.Worker === "function" &&
+        typeof injected.MessageChannel === "function" &&
+        typeof injected.receiveMessageOnPort === "function") {
+        wtModule = injected;
+        return wtModule;
+    }
+    try {
+        // eslint-disable-next-line no-new-func
+        const nodeRequire = new Function("m", "return require(m)");
+        wtModule = nodeRequire("node:worker_threads");
+        return wtModule;
+    }
+    catch {
+        wtModule = null;
+        return null;
+    }
+}
+/** Called from preloadWasm (async) so Vite SSR can import worker_threads without sync require. */
+async function loadWorkerThreadsAsync() {
+    const existing = loadWorkerThreads();
+    if (existing)
+        return existing;
+    if (!nodeWorkerEnabled())
+        return null;
+    try {
+        const spec = "node:worker_threads";
+        const wt = (await import(__rewriteRelativeImportExtension(/* @vite-ignore */ spec)));
+        wtModule = wt;
+        globalThis.__XPRITE_WORKER_THREADS__ = wt;
+        return wt;
+    }
+    catch {
+        wtModule = null;
+        return null;
+    }
+}
+function resolveWorkerPath() {
+    const process = nodeProcess();
+    if (process?.env.XPRITE_AC_RL_WORKER_PATH)
+        return process.env.XPRITE_AC_RL_WORKER_PATH;
+    return packageFile(NODE_WORKER);
+}
+function syncCall(wt, worker, payload, transfer = []) {
+    const { port1, port2 } = new wt.MessageChannel();
+    worker.postMessage({ ...payload, port: port2 }, [port2, ...transfer]);
+    for (;;) {
+        const msg = wt.receiveMessageOnPort(port1);
+        if (msg)
+            return msg.message;
+    }
+}
+function ensureDetectWorker() {
+    if (workerFailed)
+        return false;
+    if (detectWorker && workerReady)
+        return true;
+    const wt = loadWorkerThreads();
+    if (!wt)
+        return false;
+    const workerPath = resolveWorkerPath();
+    if (!workerPath) {
+        workerFailed = true;
+        return false;
+    }
+    try {
+        if (!detectWorker) {
+            detectWorker = new wt.Worker(workerPath);
+            // Do not keep the parent process alive (pixel-bench workers must exit)
+            const maybeUnref = detectWorker;
+            maybeUnref.unref?.();
+            detectWorker.on("error", () => {
+                workerFailed = true;
+                detectWorker = null;
+                workerReady = false;
+            });
+        }
+        const init = syncCall(wt, detectWorker, { type: "init" });
+        if (!init.ok) {
+            workerFailed = true;
+            detectWorker = null;
+            workerReady = false;
+            return false;
+        }
+        workerReady = true;
+        return true;
+    }
+    catch {
+        workerFailed = true;
+        detectWorker = null;
+        workerReady = false;
+        return false;
+    }
+}
+function portMessagePromise(port1, pending) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const cancel = () => finish({ ok: false });
+        const finish = (body) => {
+            if (settled)
+                return;
+            settled = true;
+            pending?.delete(cancel);
+            port1.onmessage = null;
+            port1.close?.();
+            resolve(body);
+        };
+        pending?.add(cancel);
+        // Node worker_threads MessagePort is an EventEmitter (prefer over onmessage).
+        const process = nodeProcess();
+        if (typeof port1.on === "function" && process?.versions?.node) {
+            const onMsg = (msg) => {
+                port1.off?.("message", onMsg);
+                finish(msg);
+            };
+            port1.on("message", onMsg);
+            port1.start?.();
+            return;
+        }
+        // Browser MessagePort
+        port1.onmessage = (ev) => {
+            port1.onmessage = null;
+            finish(ev.data);
+        };
+    });
+}
+function failBrowserDetectWorker(worker) {
+    if (browserDetectWorker !== worker)
+        return;
+    browserWorkerFailed = true;
+    browserDetectWorker = null;
+    browserWorkerReady = false;
+    try {
+        worker.terminate();
+    }
+    catch {
+        /* Already stopped. */
+    }
+    for (const cancel of browserRequests)
+        cancel();
+}
+async function initializeBrowserDetectWorker() {
+    let worker = browserDetectWorker;
+    try {
+        if (!worker) {
+            worker = browserWorkerFactory();
+            browserDetectWorker = worker;
+            const ownedWorker = worker;
+            worker.onerror = () => failBrowserDetectWorker(ownedWorker);
+        }
+        const MessageChannel = browserMessageChannelCtor();
+        if (!MessageChannel)
+            throw new Error("MessageChannel unavailable");
+        const { port1, port2 } = new MessageChannel();
+        const initPromise = portMessagePromise(port1, browserRequests);
+        worker.postMessage({ type: "init", port: port2 }, [port2]);
+        const init = await initPromise;
+        if (browserDetectWorker !== worker)
+            return false;
+        if (!init.ok) {
+            failBrowserDetectWorker(worker);
+            return false;
+        }
+        browserWorkerReady = true;
+        return true;
+    }
+    catch {
+        if (worker)
+            failBrowserDetectWorker(worker);
+        else
+            browserWorkerFailed = true;
+        return false;
+    }
+}
+async function ensureBrowserDetectWorker() {
+    if (browserWorkerFailed || !browserWorkerFactory)
+        return false;
+    if (browserDetectWorker && browserWorkerReady)
+        return true;
+    if (browserWorkerInitializing)
+        return browserWorkerInitializing;
+    const initializing = initializeBrowserDetectWorker();
+    browserWorkerInitializing = initializing;
+    try {
+        return await initializing;
+    }
+    finally {
+        if (browserWorkerInitializing === initializing)
+            browserWorkerInitializing = null;
+    }
+}
+/**
+ * Preload WASM module asynchronously (call during app/worker initialization).
+ * After this completes, detectAcRlConsensus will work synchronously without load overhead.
+ *
+ * Best practice: Call this during app startup or worker ready event, NOT on first recover call.
+ * Reduces first-image latency by ~5-10ms and eliminates async overhead from hot path.
+ *
+ * Also warms the Node AC+RL detect worker when worker_threads overlap is available,
+ * and the browser nested Worker when a factory was registered.
+ *
+ * @example
+ * // In worker initialization:
+ * await preloadWasm();
+ *
+ * // Or in app init:
+ * preloadWasm().catch(console.error);
+ */
+export async function preloadWasm() {
+    if (!wasmLoaded) {
+        const module = await import("../wasm/pixelfixer_detect.js");
+        try {
+            await module.default();
+        }
+        catch {
+            // Node: fetch() cannot read file:// URLs; read the binary next to the glue instead.
+            const process = nodeProcess();
+            if (process?.versions?.node) {
+                const binary = packageFile(WASM_BINARY);
+                if (!binary)
+                    throw new Error("WASM preload failed");
+                const fs = (await import(__rewriteRelativeImportExtension(/* @vite-ignore */ NODE_FS)));
+                module.initSync({ module: fs.readFileSync(binary) });
+            }
+            else {
+                throw new Error("WASM preload failed");
+            }
+        }
+        detectFastAcRl = module.detectFastAcRl;
+        wasmLoaded = true;
+    }
+    try {
+        await loadWorkerThreadsAsync();
+        ensureDetectWorker();
+    }
+    catch {
+        /* sync fallback remains */
+    }
+    try {
+        await ensureBrowserDetectWorker();
+    }
+    catch {
+        /* sync / Node path remains */
+    }
+}
+/**
+ * Detect pixel grid via AC+RL consensus (Fixer Rust WASM).
+ * WASM must be preloaded via preloadWasm() first.
+ *
+ * @param imageData - RGBA image data (Uint8ClampedArray or plain object with data/width/height)
+ * @returns Grid dimensions when consensus fires, otherwise null
+ */
+function detectAcRlConsensus(imageData) {
+    if (!wasmLoaded || !detectFastAcRl) {
+        // Silently skip if WASM not loaded - will use fallback grid detection
+        return null;
+    }
+    // Convert Uint8ClampedArray to Uint8Array if needed
+    const rgba = rgbaBytes(imageData);
+    const result = detectFastAcRl(rgba, imageData.width, imageData.height);
+    // Only return grid when consensus fires
+    if (result.consensus === "fast:ac+rl(S)") {
+        return {
+            cols: result.cols,
+            rows: result.rows,
+        };
+    }
+    return null;
+}
+/**
+ * Start AC+RL detect on a Node worker_threads worker (copy + postMessage).
+ * Run proposers on the calling thread, then finishAcRlConsensusJob.
+ * Falls back to deferred sync detect when workers are unavailable (browser / disable flag).
+ */
+export function beginAcRlConsensusJob(imageData) {
+    const wt = loadWorkerThreads();
+    if (!wt || !ensureDetectWorker() || !detectWorker) {
+        return { mode: "sync", imageData };
+    }
+    try {
+        const { port1, port2 } = new wt.MessageChannel();
+        const copy = copyRgba(imageData);
+        detectWorker.postMessage({
+            type: "detect",
+            width: imageData.width,
+            height: imageData.height,
+            data: copy.buffer,
+            port: port2,
+        }, [copy.buffer, port2]);
+        return { mode: "worker", port1 };
+    }
+    catch {
+        return { mode: "sync", imageData };
+    }
+}
+/**
+ * Join a job started by beginAcRlConsensusJob. Same consensus semantics as detectAcRlConsensus.
+ */
+export function finishAcRlConsensusJob(job) {
+    if (job.mode === "sync") {
+        return detectAcRlConsensus(job.imageData);
+    }
+    const wt = loadWorkerThreads();
+    if (!wt)
+        return null;
+    for (;;) {
+        const msg = wt.receiveMessageOnPort(job.port1);
+        if (!msg)
+            continue;
+        const body = msg.message;
+        if (!body.ok)
+            return null;
+        return body.consensus ?? null;
+    }
+}
+/** Reinterpret the exact typed-array slice without copying or including adjacent pixels. */
+function rgbaBytes(imageData) {
+    const { data } = imageData;
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+function copyRgba(imageData) {
+    // One owned allocation is required because transfer must not detach the caller's buffer.
+    return new Uint8Array(rgbaBytes(imageData));
+}
+/**
+ * Start AC+RL detect for async Auto: Node worker_threads or browser nested Worker.
+ * Promise is attached before proposers run; finishAcRlConsensusJobAsync awaits it
+ * (no SAB / COOP/COEP). Falls back to deferred sync detect when no worker is available.
+ * Async so browser nested Worker can be warmed on first use.
+ */
+export async function beginAcRlConsensusJobAsync(imageData) {
+    // Prefer Node worker_threads when available (harness / SSR).
+    const wt = loadWorkerThreads();
+    if (wt && ensureDetectWorker() && detectWorker) {
+        try {
+            const { port1, port2 } = new wt.MessageChannel();
+            const copy = copyRgba(imageData);
+            const promise = portMessagePromise(port1).then((body) => body.ok ? (body.consensus ?? null) : null);
+            detectWorker.postMessage({
+                type: "detect",
+                width: imageData.width,
+                height: imageData.height,
+                data: copy.buffer,
+                port: port2,
+            }, [copy.buffer, port2]);
+            return { mode: "async", promise };
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    // Browser nested Worker (product import-worker) — async join, no COOP/COEP.
+    if (browserWorkerFactory && !browserWorkerFailed) {
+        await ensureBrowserDetectWorker();
+    }
+    if (browserDetectWorker && browserWorkerReady && !browserWorkerFailed) {
+        const worker = browserDetectWorker;
+        try {
+            const MessageChannel = browserMessageChannelCtor();
+            if (!MessageChannel)
+                throw new Error("MessageChannel unavailable");
+            const { port1, port2 } = new MessageChannel();
+            const copy = copyRgba(imageData);
+            const promise = portMessagePromise(port1, browserRequests).then((body) => body.ok ? (body.consensus ?? null) : null);
+            worker.postMessage({
+                type: "detect",
+                width: imageData.width,
+                height: imageData.height,
+                data: copy.buffer,
+                port: port2,
+            }, [copy.buffer, port2]);
+            return { mode: "async", promise };
+        }
+        catch {
+            failBrowserDetectWorker(worker);
+        }
+    }
+    return { mode: "sync", imageData };
+}
+/**
+ * Await a job from beginAcRlConsensusJobAsync. Same consensus semantics as detectAcRlConsensus.
+ */
+export async function finishAcRlConsensusJobAsync(job) {
+    if (job.mode === "sync") {
+        return detectAcRlConsensus(job.imageData);
+    }
+    return job.promise;
+}
+/** Kick off browser nested Worker warm-up after setAcRlBrowserWorkerFactory (non-blocking OK). */
+export async function warmAcRlBrowserWorker() {
+    return ensureBrowserDetectWorker();
+}
+/** Test/harness: whether Node worker overlap is active after preload. */
+export function acRlWorkerOverlapActive() {
+    return !workerFailed && workerReady && nodeWorkerEnabled();
+}
+/** Test/harness: whether browser nested-Worker async overlap is ready. */
+export function acRlBrowserWorkerOverlapActive() {
+    return !browserWorkerFailed && browserWorkerReady && browserWorkerFactory !== null;
+}

package/dist/grid-arbitrate.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Grid arbitration via description-length (MDL).
+ *
+ * GridEvidenceReader shares the image description, line prefixes and distinct readings across
+ * arbitration, corroboration and consensus selection for one evaluation view.
+ */
+import type { PixelBuffer } from "./base.ts";
+import { type DescribedImage } from "./grid-description-length.ts";
+import { type PixelGridAnalysis } from "./types.ts";
+/** A grid reading: the hypothesis with its cuts, its length and its twin's, per sample. */
+export interface GridEvidence {
+    grid: PixelGridAnalysis;
+    length: number;
+    twin: number;
+    /** Phase evidence, per sample, the reading's strip search finds by chance. */
+    chance: number;
+    /** The image the reading describes: the input, or its straightened strips. */
+    frame: () => DescribedImage;
+}
+export interface ArbitratedGrid {
+    grid: PixelGridAnalysis;
+    /** Description length per sample, in nats. */
+    length: number;
+    /** The decision's score, per sample; lower is better. */
+    score: number;
+}
+export declare const phaseScore: (reading: Pick<GridEvidence, "length" | "twin" | "chance">) => number;
+/** The cuts moved half a cell: one cut at each cell middle, inside the same extent. */
+export declare function twinCuts(cuts: readonly number[]): number[];
+/** The cuts with every `period`th inner cut, from the `phase`th, moved to its cell's middle. */
+export declare function classTwinCuts(cuts: readonly number[], period: number, phase: number): number[];
+/** Phase evidence, per sample, the reading's cuts miss from their least evident class. */
+export declare function octaveShortfall(frame: DescribedImage, cutsX: readonly number[], cutsY: readonly number[]): number;
+/** Reuse one evaluation view's descriptions and distinct readings during Auto's decision. */
+export declare class GridEvidenceReader {
+    private readonly image;
+    private readonly described;
+    private readonly strips;
+    private readonly pixels;
+    private readonly readings;
+    constructor(image: PixelBuffer);
+    read(grids: readonly PixelGridAnalysis[]): {
+        readings: GridEvidence[];
+        pixels: number;
+    };
+}
+/**
+ * The best-scoring grid among the proposals, or null when the passthrough scores lower. The
+ * winner's confidence is the larger of its proposer's and the share of its twin's length that
+ * its phase saves.
+ */
+export declare function arbitrateGrids(image: PixelBuffer, grids: readonly PixelGridAnalysis[], evidence?: GridEvidenceReader): ArbitratedGrid | null;