@alpha2-sh/editor 0.0.0 → 0.1.0

package/dist/browser/runtime/fingerprint.js

@@ -0,0 +1,157 @@
+// Evidence of an imported file's media, recorded in the project so any host can tell later whether
+// media it finds is the same: the bytes' hash, their length and date, and what the demuxer sees.
+// Whether two fingerprints match is the engine's decision (`alpha2/assets`), never made here.
+import { sha256Blob } from "alpha2/assets";
+import { colorMetadataFromVideoColorSpace, sampleAspectForStream, } from "alpha2/hdr-frames";
+import { TICKS_PER_SECOND, validFrameRate } from "alpha2/project";
+import { ALL_FORMATS, BlobSource, EncodedPacketSink, Input } from "mediabunny";
+/**
+ * The fingerprint of `file` as media of `kind`. `size` is an image's decoded size; video and audio
+ * are probed. `hash` makes the content hash, `sha256Blob` on this thread unless the caller hashes
+ * elsewhere (`hashInWorker`).
+ * @param {File} file
+ * @param {string} kind
+ * @param {{ signal?: AbortSignal, onProgress?: (bytes: number) => void, size?: { width: number, height: number }, hash?: (file: Blob, options: { signal?: AbortSignal, onProgress?: (bytes: number) => void }) => Promise<string> }} [options]
+ * @returns {Promise<import("alpha2/project").MediaFingerprint>}
+ */
+export async function fingerprintFile(file, kind, options = {}) {
+    const hash = options.hash ?? sha256Blob;
+    const fingerprint = {
+        content_sha256: await hash(file, {
+            signal: options.signal,
+            onProgress: options.onProgress,
+        }),
+        byte_length: file.size,
+        modified_ms: file.lastModified,
+    };
+    if (kind === "image" && options.size)
+        return {
+            ...fingerprint,
+            streams: {
+                video: { width: options.size.width, height: options.size.height },
+            },
+        };
+    if (kind !== "video" && kind !== "audio")
+        return fingerprint;
+    return { ...fingerprint, ...(await probeEvidence(file)) };
+}
+/** What the demuxer sees: the primary streams' shapes, the duration, and a declared color. */
+export async function probeEvidence(file) {
+    const input = new Input({
+        source: new BlobSource(file),
+        formats: ALL_FORMATS,
+    });
+    try {
+        const video = await input.getPrimaryVideoTrack();
+        const audio = await input.getPrimaryAudioTrack();
+        const streams = {};
+        let color;
+        if (video) {
+            const rate = rationalRate(await presentedRate(video).catch(() => null));
+            const shown = await displaySize(video);
+            streams.video = {
+                width: shown.width,
+                height: shown.height,
+                ...(rate ? { frame_rate: rate } : {}),
+            };
+            const space = await video.getColorSpace().catch(() => null);
+            if (space &&
+                (space.primaries || space.transfer || space.matrix || space.fullRange))
+                color = colorMetadataFromVideoColorSpace(space);
+        }
+        if (audio)
+            streams.audio = {
+                channels: audio.numberOfChannels,
+                sample_rate: audio.sampleRate,
+            };
+        // The latest end of any track: a stream starting at 1.4 s and lasting 2 s ends at 3.4 s.
+        const seconds = await input.computeDuration().catch(() => null);
+        return {
+            ...(video || audio ? { streams } : {}),
+            ...(Number.isFinite(seconds)
+                ? { duration_ticks: Math.round(seconds * TICKS_PER_SECOND) }
+                : {}),
+            ...(color ? { color } : {}),
+        };
+    }
+    finally {
+        input.dispose();
+    }
+}
+/**
+ * The size a video track is shown at, in square pixels and turned as it is shown, as every host
+ * finds it: the sample aspect ratio is the container's when it declares one that is not square,
+ * else the one the H.264 or HEVC parameter sets signal (FFmpeg's `av_guess_sample_aspect_ratio`);
+ * mediabunny reads only the container's. The stretch is the engine's
+ * (`SampleAspectRatio::square_pixel_size`): the longer side of a sample grows, rounded to the
+ * nearest pixel.
+ * @param {import("mediabunny").InputVideoTrack} track
+ * @returns {Promise<{ width: number, height: number }>}
+ */
+export async function displaySize(track) {
+    const declared = await track.getPixelAspectRatio().catch(() => null);
+    let aspect = declared && declared.num !== declared.den ? declared : undefined;
+    if (!aspect) {
+        const config = await track.getDecoderConfig().catch(() => null);
+        const description = config?.description ?? undefined;
+        const first = description === undefined
+            ? await new EncodedPacketSink(track).getFirstPacket().catch(() => null)
+            : null;
+        aspect = sampleAspectForStream(config?.codec ?? track.codec, description, first?.data);
+    }
+    let width = track.codedWidth;
+    let height = track.codedHeight;
+    if (aspect && aspect.num > aspect.den)
+        width = Math.floor((width * aspect.num * 2 + aspect.den) / (2 * aspect.den));
+    else if (aspect && aspect.num < aspect.den)
+        height = Math.floor((height * aspect.den * 2 + aspect.num) / (2 * aspect.num));
+    return track.rotation % 180 === 0
+        ? { width, height }
+        : { width: height, height: width };
+}
+/** How many frames the rate is measured over, at least: about four seconds at 30 fps. */
+const RATE_FRAMES = 120;
+/**
+ * The rate `track` presents its first frames at, from packet times alone (durations differ between
+ * demuxers); past {@link RATE_FRAMES}, packets run up to the first presented after every one
+ * taken, so reordered frames stay in the span. `null` with fewer than two frames or no span. Twin
+ * of the engine's `alpha2_assets::FrameRateEvidence` (held equal by
+ * `tests/cases/media-evidence-corpus.json`); a declared rate is no common ground across hosts.
+ * @param {import("mediabunny").InputVideoTrack} track
+ * @returns {Promise<number | null>}
+ */
+async function presentedRate(track) {
+    let count = 0;
+    let first = Infinity;
+    let last = -Infinity;
+    for await (const packet of new EncodedPacketSink(track).packets(undefined, undefined, { metadataOnly: true })) {
+        const time = packet.timestamp;
+        if (!Number.isFinite(time))
+            continue;
+        if (count >= RATE_FRAMES && time > last)
+            break;
+        first = Math.min(first, time);
+        last = Math.max(last, time);
+        count += 1;
+    }
+    return count >= 2 && last > first ? (count - 1) / (last - first) : null;
+}
+/**
+ * A measured frame rate as the rational a stream declares: the NTSC rates and whole rates exactly,
+ * others to a thousandth (the engine's `alpha2_assets::rational_rate` is its twin). `null` when the
+ * measure is no rate a project holds (so slow it rounds to no frames, or a frame shorter than a
+ * tick, which only broken timestamps give): the fingerprint then records no rate rather than one
+ * the engine refuses.
+ */
+export function rationalRate(rate) {
+    if (!Number.isFinite(rate) || rate <= 0)
+        return null;
+    for (const base of [24, 30, 48, 60, 120]) {
+        if (Math.abs(rate - (base * 1000) / 1001) < 0.005)
+            return { num: base * 1000, den: 1001 };
+    }
+    const rational = Math.abs(rate - Math.round(rate)) < 0.005
+        ? { num: Math.round(rate), den: 1 }
+        : { num: Math.round(rate * 1000), den: 1000 };
+    return validFrameRate(rational) ? rational : null;
+}

package/dist/browser/runtime/generators.d.ts

@@ -0,0 +1,188 @@
+export function defaultGenerator(kind?: string): {
+    kind: string;
+    colors: string[];
+    angle: number;
+    radius: number;
+    size: {
+        x: number;
+        y: number;
+    };
+    cornerRadius: number;
+    rotation: number;
+    fill: boolean;
+    stroke: {
+        enabled: boolean;
+        color: string;
+        width: number;
+    };
+};
+/** The `alpha2_model::Generator` for an editor description. */
+export function encodeGenerator(generator: any): {
+    type: string;
+    paint: {
+        type: string;
+        color: {
+            red: number;
+            green: number;
+            blue: number;
+            alpha: number;
+        };
+        start?: undefined;
+        end?: undefined;
+        stops?: undefined;
+        center?: undefined;
+        radius?: undefined;
+        angle_degrees?: undefined;
+    };
+    shape?: undefined;
+    center?: undefined;
+    size?: undefined;
+    rotation_degrees?: undefined;
+    fill?: undefined;
+    stroke?: undefined;
+} | {
+    type: string;
+    paint: {
+        type: string;
+        start: {
+            x: number;
+            y: number;
+        };
+        end: {
+            x: number;
+            y: number;
+        };
+        stops: {
+            offset: number;
+            color: {
+                red: number;
+                green: number;
+                blue: number;
+                alpha: number;
+            };
+        }[];
+        color?: undefined;
+        center?: undefined;
+        radius?: undefined;
+        angle_degrees?: undefined;
+    };
+    shape?: undefined;
+    center?: undefined;
+    size?: undefined;
+    rotation_degrees?: undefined;
+    fill?: undefined;
+    stroke?: undefined;
+} | {
+    type: string;
+    paint: {
+        type: string;
+        center: {
+            x: number;
+            y: number;
+        };
+        radius: number;
+        stops: {
+            offset: number;
+            color: {
+                red: number;
+                green: number;
+                blue: number;
+                alpha: number;
+            };
+        }[];
+        color?: undefined;
+        start?: undefined;
+        end?: undefined;
+        angle_degrees?: undefined;
+    };
+    shape?: undefined;
+    center?: undefined;
+    size?: undefined;
+    rotation_degrees?: undefined;
+    fill?: undefined;
+    stroke?: undefined;
+} | {
+    type: string;
+    paint: {
+        type: string;
+        center: {
+            x: number;
+            y: number;
+        };
+        angle_degrees: any;
+        stops: {
+            offset: number;
+            color: {
+                red: number;
+                green: number;
+                blue: number;
+                alpha: number;
+            };
+        }[];
+        color?: undefined;
+        start?: undefined;
+        end?: undefined;
+        radius?: undefined;
+    };
+    shape?: undefined;
+    center?: undefined;
+    size?: undefined;
+    rotation_degrees?: undefined;
+    fill?: undefined;
+    stroke?: undefined;
+} | {
+    type: string;
+    shape: {
+        type: string;
+        corner_radius: number;
+    } | {
+        type: string;
+        corner_radius?: undefined;
+    };
+    center: {
+        x: number;
+        y: number;
+    };
+    size: {
+        x: number;
+        y: number;
+    };
+    rotation_degrees: any;
+    fill: {
+        type: string;
+        color: {
+            red: number;
+            green: number;
+            blue: number;
+            alpha: number;
+        };
+    } | null;
+    stroke: {
+        width: number;
+        paint: {
+            type: string;
+            color: {
+                red: number;
+                green: number;
+                blue: number;
+                alpha: number;
+            };
+        };
+    } | null;
+    paint?: undefined;
+};
+/**
+ * Draws an approximation of the generator for a library thumbnail. Canvas gradients interpolate in
+ * sRGB where the engine uses linear light, so the middle of a gradient is a little darker here than
+ * in the preview.
+ */
+export function drawGenerator(context: any, generator: any, width: any, height: any): void;
+/** Checks a generator read from a project file. */
+export function isGenerator(value: any): boolean;
+export const GENERATOR_KINDS: {
+    value: string;
+    label: string;
+}[];
+export function isShape(kind: any): boolean;
+export function isGradient(kind: any): boolean;
+export function generatorLabel(kind: any): string;

package/dist/browser/runtime/generators.js

@@ -0,0 +1,173 @@
+// Generated sources: pictures the engine draws itself (`kind: "generated"`). Positions are
+// normalized ((0, 0) top-left, (1, 1) bottom-right); radii and strokes are fractions of the shorter
+// side.
+import { rgba } from "./color.js";
+export const GENERATOR_KINDS = [
+    { value: "solid", label: "Solid color" },
+    { value: "linear", label: "Linear gradient" },
+    { value: "radial", label: "Radial gradient" },
+    { value: "conic", label: "Conic gradient" },
+    { value: "rectangle", label: "Rectangle" },
+    { value: "ellipse", label: "Ellipse" },
+];
+export const isShape = (kind) => kind === "rectangle" || kind === "ellipse";
+export const isGradient = (kind) => kind === "linear" || kind === "radial" || kind === "conic";
+export const generatorLabel = (kind) => GENERATOR_KINDS.find((item) => item.value === kind)?.label ?? "Generated";
+export function defaultGenerator(kind = "linear") {
+    return {
+        kind,
+        colors: ["#6d78ff", "#12b5a4"],
+        // Degrees clockwise from up, as CSS gradients measure them.
+        angle: 135,
+        radius: 0.9,
+        size: { x: 0.6, y: 0.35 },
+        cornerRadius: 0.04,
+        rotation: 0,
+        fill: true,
+        stroke: { enabled: false, color: "#ffffff", width: 0.012 },
+    };
+}
+/** The `alpha2_model::Generator` for an editor description. */
+export function encodeGenerator(generator) {
+    const [first, second] = generator.colors;
+    const stops = [
+        { offset: 0, color: rgba(first) },
+        { offset: 1, color: rgba(second) },
+    ];
+    const center = { x: 0.5, y: 0.5 };
+    switch (generator.kind) {
+        case "solid":
+            return { type: "fill", paint: { type: "solid", color: rgba(first) } };
+        case "linear": {
+            const radians = (generator.angle * Math.PI) / 180;
+            const dx = 0.5 * Math.sin(radians);
+            const dy = -0.5 * Math.cos(radians);
+            return {
+                type: "fill",
+                paint: {
+                    type: "linear_gradient",
+                    start: { x: 0.5 - dx, y: 0.5 - dy },
+                    end: { x: 0.5 + dx, y: 0.5 + dy },
+                    stops,
+                },
+            };
+        }
+        case "radial":
+            return {
+                type: "fill",
+                paint: {
+                    type: "radial_gradient",
+                    center,
+                    radius: Math.max(0.01, generator.radius),
+                    stops,
+                },
+            };
+        case "conic":
+            return {
+                type: "fill",
+                paint: {
+                    type: "conic_gradient",
+                    center,
+                    angle_degrees: generator.angle,
+                    stops,
+                },
+            };
+        default: {
+            const stroked = generator.stroke.enabled;
+            const filled = generator.fill || !stroked;
+            return {
+                type: "shape",
+                shape: generator.kind === "rectangle"
+                    ? {
+                        type: "rectangle",
+                        corner_radius: Math.max(0, generator.cornerRadius),
+                    }
+                    : { type: "ellipse" },
+                center,
+                size: {
+                    x: Math.max(0, generator.size.x),
+                    y: Math.max(0, generator.size.y),
+                },
+                rotation_degrees: generator.rotation,
+                fill: filled ? { type: "solid", color: rgba(first) } : null,
+                stroke: stroked
+                    ? {
+                        width: Math.max(0.001, generator.stroke.width),
+                        paint: { type: "solid", color: rgba(generator.stroke.color) },
+                    }
+                    : null,
+            };
+        }
+    }
+}
+/**
+ * Draws an approximation of the generator for a library thumbnail. Canvas gradients interpolate in
+ * sRGB where the engine uses linear light, so the middle of a gradient is a little darker here than
+ * in the preview.
+ */
+export function drawGenerator(context, generator, width, height) {
+    const [first, second] = generator.colors;
+    const short = Math.min(width, height);
+    const gradient = (paint) => {
+        paint.addColorStop(0, first);
+        paint.addColorStop(1, second);
+        return paint;
+    };
+    context.clearRect(0, 0, width, height);
+    switch (generator.kind) {
+        case "solid":
+            context.fillStyle = first;
+            context.fillRect(0, 0, width, height);
+            return;
+        case "linear": {
+            const radians = (generator.angle * Math.PI) / 180;
+            const dx = 0.5 * Math.sin(radians) * width;
+            const dy = -0.5 * Math.cos(radians) * height;
+            context.fillStyle = gradient(context.createLinearGradient(width / 2 - dx, height / 2 - dy, width / 2 + dx, height / 2 + dy));
+            context.fillRect(0, 0, width, height);
+            return;
+        }
+        case "radial":
+            context.fillStyle = gradient(context.createRadialGradient(width / 2, height / 2, 0, width / 2, height / 2, generator.radius * short));
+            context.fillRect(0, 0, width, height);
+            return;
+        case "conic":
+            // Canvas measures from the +x axis; the engine, like CSS, from up.
+            context.fillStyle = gradient(context.createConicGradient(((generator.angle - 90) * Math.PI) / 180, width / 2, height / 2));
+            context.fillRect(0, 0, width, height);
+            return;
+        default: {
+            const w = generator.size.x * width;
+            const h = generator.size.y * height;
+            context.save();
+            context.translate(width / 2, height / 2);
+            context.rotate((generator.rotation * Math.PI) / 180);
+            context.beginPath();
+            if (generator.kind === "rectangle")
+                context.roundRect(-w / 2, -h / 2, w, h, Math.min(generator.cornerRadius * short, w / 2, h / 2));
+            else
+                context.ellipse(0, 0, w / 2, h / 2, 0, 0, Math.PI * 2);
+            if (generator.fill || !generator.stroke.enabled) {
+                context.fillStyle = first;
+                context.fill();
+            }
+            if (generator.stroke.enabled) {
+                context.strokeStyle = generator.stroke.color;
+                context.lineWidth = Math.max(1, generator.stroke.width * short);
+                context.stroke();
+            }
+            context.restore();
+        }
+    }
+}
+/** Checks a generator read from a project file. */
+export function isGenerator(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        GENERATOR_KINDS.some((item) => item.value === value.kind) &&
+        Array.isArray(value.colors) &&
+        value.colors.length === 2 &&
+        [value.angle, value.radius, value.cornerRadius, value.rotation].every(Number.isFinite) &&
+        typeof value.size === "object" &&
+        typeof value.stroke === "object");
+}

package/dist/browser/runtime/locks.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Holds the shared lock `name` until `release()`. Resolves once held; where the browser has no Web
+ * Locks, or refuses the lock, at once and holding nothing. `release()` returns a promise that
+ * settles when the lock is let go.
+ * @param {string} name
+ * @returns {Promise<{ release(): Promise<void> }>}
+ */
+export function holdShared(name: string): Promise<{
+    release(): Promise<void>;
+}>;
+/**
+ * Runs `remove` holding the lock `name` exclusively, only if no page holds it, and resolves to
+ * whether it ran. Without Web Locks it runs.
+ * @param {string} name
+ * @param {() => Promise<void>} remove
+ * @returns {Promise<boolean>}
+ */
+export function whenUnheld(name: string, remove: () => Promise<void>): Promise<boolean>;
+/**
+ * Runs `body` holding the lock `name` exclusively, waiting for any page that holds it, and resolves
+ * to what `body` resolves to; `body` is told whether it holds the lock. Where the browser has no
+ * Web Locks, or refuses the lock, `body` runs at once, holding nothing. Rejects with
+ * `signal.reason` once `signal` aborts while it waits.
+ * @template T
+ * @param {string} name
+ * @param {{ signal?: AbortSignal }} options
+ * @param {(held: boolean) => Promise<T>} body
+ * @returns {Promise<T>}
+ */
+export function withExclusive<T>(name: string, { signal }: {
+    signal?: AbortSignal;
+} | undefined, body: (held: boolean) => Promise<T>): Promise<T>;

package/dist/browser/runtime/locks.js

@@ -0,0 +1,86 @@
+// Web Locks marking OPFS entries in use: users hold the lock shared, removers take it exclusively
+// only if unheld. Closed pages release their locks; without Web Locks nothing is held.
+const locks = () => globalThis.navigator?.locks ?? null;
+/**
+ * Holds the shared lock `name` until `release()`. Resolves once held; where the browser has no Web
+ * Locks, or refuses the lock, at once and holding nothing. `release()` returns a promise that
+ * settles when the lock is let go.
+ * @param {string} name
+ * @returns {Promise<{ release(): Promise<void> }>}
+ */
+export async function holdShared(name) {
+    const manager = locks();
+    if (!manager)
+        return { release: async () => { } };
+    let letGo;
+    const done = new Promise((resolve) => (letGo = resolve));
+    let held;
+    const acquired = new Promise((resolve) => (held = resolve));
+    const request = manager
+        .request(name, { mode: "shared" }, () => {
+        held();
+        return done;
+    })
+        .catch(() => held());
+    await acquired;
+    let released = null;
+    return {
+        release() {
+            if (!released) {
+                letGo();
+                released = request;
+            }
+            return released;
+        },
+    };
+}
+/**
+ * Runs `remove` holding the lock `name` exclusively, only if no page holds it, and resolves to
+ * whether it ran. Without Web Locks it runs.
+ * @param {string} name
+ * @param {() => Promise<void>} remove
+ * @returns {Promise<boolean>}
+ */
+export async function whenUnheld(name, remove) {
+    const manager = locks();
+    if (!manager) {
+        await remove();
+        return true;
+    }
+    return manager.request(name, { mode: "exclusive", ifAvailable: true }, async (lock) => {
+        if (!lock)
+            return false;
+        await remove();
+        return true;
+    });
+}
+/**
+ * Runs `body` holding the lock `name` exclusively, waiting for any page that holds it, and resolves
+ * to what `body` resolves to; `body` is told whether it holds the lock. Where the browser has no
+ * Web Locks, or refuses the lock, `body` runs at once, holding nothing. Rejects with
+ * `signal.reason` once `signal` aborts while it waits.
+ * @template T
+ * @param {string} name
+ * @param {{ signal?: AbortSignal }} options
+ * @param {(held: boolean) => Promise<T>} body
+ * @returns {Promise<T>}
+ */
+export async function withExclusive(name, { signal } = {}, body) {
+    signal?.throwIfAborted();
+    const manager = locks();
+    if (!manager)
+        return body(false);
+    let started = false;
+    try {
+        return await manager.request(name, signal ? { mode: "exclusive", signal } : { mode: "exclusive" }, () => {
+            started = true;
+            return body(true);
+        });
+    }
+    catch (error) {
+        if (started)
+            throw error;
+        signal?.throwIfAborted();
+        return body(false);
+    }
+}