@heyramzi/review 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/node/client/http.d.ts

@@ -0,0 +1,18 @@
+import type { ActionResult, ReviewAction, ReviewModel, Shelf } from "../core/types.js";
+/** Everything the page needs from a server, so a test or a demo can stand in for HTTP. */
+export type ReviewClient = {
+    load(): Promise<ReviewModel>;
+    /** The shelves the note box's @ picker offers. Left out, the picker stays shut. */
+    library?(): Promise<Shelf[]>;
+    act(action: ReviewAction): Promise<ActionResult>;
+    /** Push fresh models and the connection state. Returns the unsubscribe. */
+    subscribe(handlers: {
+        model(model: ReviewModel): void;
+        connection(up: boolean): void;
+    }): () => void;
+};
+export type ClientOptions = {
+    base: string;
+    id: string;
+};
+export declare function createHttpClient({ base, id }: ClientOptions): ReviewClient;

package/dist/node/client/http.js

@@ -0,0 +1,79 @@
+function isModel(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const model = value;
+    return (typeof model.id === "string" &&
+        Array.isArray(model.passes) &&
+        Array.isArray(model.groups) &&
+        Array.isArray(model.beats) &&
+        Array.isArray(model.notes) &&
+        Array.isArray(model.paragraphs) &&
+        Array.isArray(model.kinds));
+}
+const RECONNECT = [1000, 2000, 4000, 8000];
+export function createHttpClient({ base, id }) {
+    const root = `${base.replace(/\/+$/, "")}/${encodeURIComponent(id)}`;
+    return {
+        async load() {
+            const response = await fetch(`${root}/state`, { headers: { accept: "application/json" } });
+            const body = await response.json().catch(() => null);
+            if (!response.ok) {
+                const message = typeof body === "object" && body !== null && "error" in body
+                    ? String(body.error)
+                    : response.statusText;
+                throw new Error(message || "Couldn't load this video.");
+            }
+            if (!isModel(body))
+                throw new Error("Editor OS sent something this page can't read.");
+            return body;
+        },
+        async library() {
+            const response = await fetch(`${root}/library`, { headers: { accept: "application/json" } });
+            const body = await response.json().catch(() => null);
+            return response.ok && Array.isArray(body) ? body : [];
+        },
+        async act(action) {
+            const response = await fetch(`${root}/act`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(action),
+            });
+            const body = await response.json().catch(() => null);
+            if (typeof body === "object" && body !== null && "ok" in body)
+                return body;
+            return { ok: false, error: response.statusText || "Editor OS didn't answer." };
+        },
+        subscribe({ model, connection }) {
+            let source;
+            let retry;
+            let attempt = 0;
+            let stopped = false;
+            const open = () => {
+                source = new EventSource(`${root}/events`);
+                source.addEventListener("open", () => {
+                    attempt = 0;
+                    connection(true);
+                });
+                source.addEventListener("model", (event) => {
+                    const data = JSON.parse(event.data);
+                    if (isModel(data))
+                        model(data);
+                });
+                source.addEventListener("error", () => {
+                    connection(false);
+                    // WHY: a non-200 answer closes the EventSource for good, so we reopen it ourselves.
+                    if (source?.readyState !== EventSource.CLOSED || stopped)
+                        return;
+                    source.close();
+                    retry = setTimeout(open, RECONNECT[Math.min(attempt++, RECONNECT.length - 1)]);
+                });
+            };
+            open();
+            return () => {
+                stopped = true;
+                clearTimeout(retry);
+                source?.close();
+            };
+        },
+    };
+}

package/dist/node/core/draft.d.ts

@@ -0,0 +1,36 @@
+import type { JobStatus, RenderProgress } from "./types.js";
+/**
+ * The preview file the player should hold: a render rewrites it in pieces, so the new one waits
+ * until the studio says the render is over.
+ */
+export declare function previewToShow(shown: string | undefined, next: string | undefined, state: JobStatus["state"] | undefined): string | undefined;
+/** What a preview render with no progress feed shows: how far along it probably is, and how the time left reads. The page words it. */
+export type RenderEstimate = {
+    fraction: number;
+    pace: "left" | "soon" | "late";
+    /** For pace `left`: the time left, rounded the way a person says it. */
+    seconds: number;
+};
+/** A new project has no past renders, so a preview is guessed at half its length, and never under 15 seconds. */
+export declare const guessedRenderMs: (videoSeconds: number) => number;
+/**
+ * Time against the expected render, eased to 90% at the expected time and 95% after, because
+ * only the studio knows when the render is over and gets to say 100%.
+ */
+export declare function renderEstimate(elapsedMs: number, expectedMs: number): RenderEstimate;
+/**
+ * The renderer's progress as a bar and a percent; the matte is about two thirds of the wait
+ * (140s of 215s on P04), so it gets half the bar.
+ */
+export declare function progressOf(progress: RenderProgress): {
+    fraction: number;
+    words: string;
+};
+/** The studio route that starts a final render of this video. */
+export declare const finalRoute: (id: string) => string;
+/** What the Render final button says, and whether it can be pressed. A final that's in line, drawing or up to date can't be asked for again. */
+export declare function finalButton(final: JobStatus): {
+    label: string;
+    disabled: boolean;
+    tip?: string;
+};

package/dist/node/core/draft.js

@@ -0,0 +1,75 @@
+import { renderWords } from "./render-words.js";
+/**
+ * The preview file the player should hold: a render rewrites it in pieces, so the new one waits
+ * until the studio says the render is over.
+ */
+export function previewToShow(shown, next, state) {
+    return state === "queued" || state === "rendering" ? shown : next;
+}
+/** A new project has no past renders, so a preview is guessed at half its length, and never under 15 seconds. */
+export const guessedRenderMs = (videoSeconds) => Math.max(15, videoSeconds * 0.5) * 1000;
+/**
+ * Time against the expected render, eased to 90% at the expected time and 95% after, because
+ * only the studio knows when the render is over and gets to say 100%.
+ */
+export function renderEstimate(elapsedMs, expectedMs) {
+    const expected = Math.max(expectedMs, 1000);
+    const fraction = 0.95 * (1 - Math.exp((-3 * Math.max(elapsedMs, 0)) / expected));
+    const left = (expected - elapsedMs) / 1000;
+    if (elapsedMs > expected * 1.25)
+        return { fraction, pace: "late", seconds: 0 };
+    if (left < 5)
+        return { fraction, pace: "soon", seconds: 0 };
+    const seconds = left < 60 ? Math.round(left / 5) * 5 : Math.round(left / 15) * 15;
+    return { fraction, pace: "left", seconds };
+}
+/**
+ * The renderer's progress as a bar and a percent; the matte is about two thirds of the wait
+ * (140s of 215s on P04), so it gets half the bar.
+ */
+export function progressOf(progress) {
+    if (progress.stage === "preparing")
+        return { fraction: 0.03, words: "getting ready" };
+    if (progress.stage === "finishing")
+        return { fraction: 0.97, words: "almost done" };
+    const share = progress.total > 0 ? progress.done / progress.total : 0;
+    const fraction = progress.stage === "matting" ? 0.05 + 0.5 * share : 0.55 + 0.4 * share;
+    const percent = `${Math.round(fraction * 100)}%`;
+    // The encode of a whole picture is minutes of one melt: it says so, instead of sitting at the matte's 55%.
+    return { fraction, words: progress.stage === "encoding" ? `encoding ${percent}` : percent };
+}
+/** The studio route that starts a final render of this video. */
+export const finalRoute = (id) => `/p/${encodeURIComponent(id)}/render`;
+/** What the Render final button says, and whether it can be pressed. A final that's in line, drawing or up to date can't be asked for again. */
+export function finalButton(final) {
+    switch (final.state) {
+        case "queued":
+            return {
+                label: renderWords.queued("final", final.ahead === 0 ? 0 : undefined),
+                disabled: true,
+            };
+        case "rendering":
+            return {
+                label: final.progress
+                    ? `${renderWords.making("final")}, ${progressOf(final.progress).words}`
+                    : renderWords.making("final"),
+                disabled: true,
+            };
+        case "current":
+            return { label: "Final is up to date", disabled: true };
+        case "failed":
+            return {
+                label: "Render final",
+                disabled: false,
+                tip: "The last try didn't finish. Try again.",
+            };
+        case "outdated":
+            return {
+                label: "Render final",
+                disabled: false,
+                tip: "The video changed since the last final",
+            };
+        case "none":
+            return { label: "Render final", disabled: false };
+    }
+}

package/dist/node/core/enums.d.ts

@@ -0,0 +1,13 @@
+import type { BeatState, NoteAct, NoteStatus } from "./types.js";
+/** Each list is checked against its union at compile time, so a new member can't be forgotten. */
+type Covers<Union, List extends readonly Union[]> = Exclude<Union, List[number]> extends never ? List : never;
+export declare const BEAT_STATES: readonly ["proposed", "changed", "approved", "skipped"];
+export declare const NOTE_ACTS: readonly ["tick", "reopen", "accept", "dismiss", "remove"];
+export declare const NOTE_STATUSES: readonly ["open", "queued", "working", "answered", "done", "proposal", "dismissed"];
+export declare const TONES: readonly ["neutral", "accent", "ok", "warn", "bad"];
+export declare const LINE_MARKS: readonly ["cut", "moved", "pause"];
+export declare const checkedBeatStates: Covers<BeatState, typeof BEAT_STATES>;
+export declare const checkedNoteActs: Covers<NoteAct, typeof NOTE_ACTS>;
+export declare const checkedNoteStatuses: Covers<NoteStatus, typeof NOTE_STATUSES>;
+export declare const isOneOf: <T extends string>(list: readonly T[], value: unknown) => value is T;
+export {};

package/dist/node/core/enums.js

@@ -0,0 +1,28 @@
+export const BEAT_STATES = [
+    "proposed",
+    "changed",
+    "approved",
+    "skipped",
+];
+export const NOTE_ACTS = [
+    "tick",
+    "reopen",
+    "accept",
+    "dismiss",
+    "remove",
+];
+export const NOTE_STATUSES = [
+    "open",
+    "queued",
+    "working",
+    "answered",
+    "done",
+    "proposal",
+    "dismissed",
+];
+export const TONES = ["neutral", "accent", "ok", "warn", "bad"];
+export const LINE_MARKS = ["cut", "moved", "pause"];
+export const checkedBeatStates = BEAT_STATES;
+export const checkedNoteActs = NOTE_ACTS;
+export const checkedNoteStatuses = NOTE_STATUSES;
+export const isOneOf = (list, value) => typeof value === "string" && list.includes(value);

package/dist/node/core/notes.d.ts

@@ -0,0 +1,34 @@
+import type { IconName, Note, NoteAct, NoteStatus, NoteTarget } from "./types.js";
+/**
+ * The note verbs, once. The server applies them, the optimistic reducer applies them, and the
+ * feedback panel draws exactly the ones legal for a note's status.
+ */
+export type Verb = {
+    act: NoteAct;
+    label: string;
+    icon: IconName;
+    /** A single-letter shortcut on the active note. */
+    key?: string;
+    /** The statuses this verb is legal from. */
+    from: readonly NoteStatus[];
+    /** Where the note lands. `null` removes it. */
+    to: NoteStatus | null;
+    /** The main button when it is the first legal verb. */
+    primary?: boolean;
+};
+export declare const NOTE_VERBS: Record<NoteAct, Verb>;
+export declare const verbsFor: (status: NoteStatus) => Verb[];
+/** The four tabs of the panel, and which statuses each one holds. */
+export type Stage = "needs" | "agents" | "done";
+export declare const STAGES: Record<Stage, {
+    label: string;
+    statuses: readonly NoteStatus[];
+    empty: string;
+}>;
+export declare const STAGE_ORDER: readonly Stage[];
+export declare const stageOf: (note: Pick<Note, "status">) => Stage;
+/** Nothing left for anyone to do on it. */
+export declare const isSettled: (note: Pick<Note, "status">) => boolean;
+/** A note the page made and the server hasn't answered for yet. */
+export declare const isPending: (note: Pick<Note, "id">) => boolean;
+export declare const sameTarget: (a: NoteTarget, b: NoteTarget) => boolean;

package/dist/node/core/notes.js

@@ -0,0 +1,57 @@
+export const NOTE_VERBS = {
+    accept: {
+        act: "accept",
+        label: "Accept",
+        icon: "check",
+        key: "a",
+        from: ["proposal"],
+        to: "open",
+        primary: true,
+    },
+    dismiss: {
+        act: "dismiss",
+        label: "Ignore",
+        icon: "x",
+        key: "x",
+        from: ["proposal"],
+        to: "dismissed",
+    },
+    tick: {
+        act: "tick",
+        label: "Mark done",
+        icon: "check",
+        key: "t",
+        from: ["answered"],
+        to: "done",
+        primary: true,
+    },
+    reopen: { act: "reopen", label: "Reopen", icon: "undo", from: ["done", "dismissed"], to: "open" },
+    remove: {
+        act: "remove",
+        label: "Delete",
+        icon: "trash",
+        from: ["open", "done", "dismissed"],
+        to: null,
+    },
+};
+export const verbsFor = (status) => Object.values(NOTE_VERBS).filter((verb) => verb.from.includes(status));
+export const STAGES = {
+    needs: {
+        label: "Needs you",
+        statuses: ["proposal", "answered"],
+        empty: "Nothing waiting on you.",
+    },
+    agents: {
+        label: "Agents",
+        statuses: ["open", "queued", "working"],
+        empty: "No note is with an agent.",
+    },
+    done: { label: "Done", statuses: ["done", "dismissed"], empty: "Nothing done yet." },
+};
+export const STAGE_ORDER = ["needs", "agents", "done"];
+export const stageOf = (note) => STAGE_ORDER.find((stage) => STAGES[stage].statuses.includes(note.status)) ?? "agents";
+/** Nothing left for anyone to do on it. */
+export const isSettled = (note) => note.status === "done" || note.status === "dismissed";
+/** A note the page made and the server hasn't answered for yet. */
+export const isPending = (note) => note.id.startsWith("tmp-");
+export const sameTarget = (a, b) => JSON.stringify(a) === JSON.stringify(b);

package/dist/node/core/openscreen.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The OpenScreen backend's host side: the feature gate, its studio routes and UI conversions, with no DOM so it tests alone.
+ */
+import type { ReviewBackend, ReviewModel } from "./types.js";
+/** What the studio's `/features` route answers, whether the gate is on and whether the app is there. */
+export type Features = {
+    openscreen: boolean;
+    openscreenInstalled: boolean;
+};
+/** The gate is shut until the studio says otherwise, so an unread answer is off. */
+export declare const FEATURES_OFF: Features;
+/** The routes Worker C serves on the studio. The UI calls these and never touches OpenScreen. */
+export declare const OPENSCREEN_ROUTES: {
+    readonly features: "/features";
+    readonly pair: "/projects/openscreen/pair";
+    readonly record: "/projects/openscreen/record";
+    readonly preview: "/projects/openscreen/preview";
+    readonly sync: "/projects/openscreen/sync";
+    readonly export: "/projects/openscreen/export";
+};
+/** The OpenScreen build this UI was written against. Anything older is untested. */
+export declare const OPENSCREEN_TESTED_VERSION = "1.13.0";
+/** Homebrew has no cask for OpenScreen, so the install line points at the releases page. */
+export declare const OPENSCREEN_RELEASES = "https://github.com/getopenscreen/openscreen/releases";
+/** A route's answer. `out` carries the exported file's path. */
+export type HostResult = {
+    ok: true;
+    out?: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * POST one studio route: a body with `ok` is taken as is, a bare 2xx counts as success, and every failure becomes readable text.
+ */
+export declare function hostPost(path: string, body: unknown): Promise<HostResult>;
+/** The gate is open only when the studio says so. A missing answer keeps it shut. */
+export declare function gateOpen(features: Features | null | undefined): boolean;
+/** A model is on the OpenScreen backend when its adapter says so. */
+export declare function isOpenScreen(model: Pick<ReviewModel, "backend"> | null | undefined): boolean;
+/** Read the `/features` body without trusting its shape. */
+export declare function readFeatures(value: unknown): Features;
+/** Seconds from a field into whole milliseconds. A blank or unreadable value means no offset. */
+export declare function secondsToMs(value: string | number | null | undefined): number;
+export type PairFields = {
+    name: string;
+    screen: string;
+    camera: string;
+    offset: string | number;
+};
+/** What the pair route's body wants: trimmed paths and the offset in milliseconds. */
+export declare function pairBody(fields: PairFields): {
+    name: string;
+    screen: string;
+    camera: string;
+    offsetMs: number;
+};
+/** What the form still needs before it can send. Empty means it can. */
+export declare function pairProblem(fields: Pick<PairFields, "name" | "screen">): string;
+/** A route's error as one line a person reads, or an empty line when it worked. */
+export declare function resultText(result: HostResult | null | undefined): string;
+/** The backend a model runs on, defaulting to what every existing video uses. */
+export declare function backendOf(model: Pick<ReviewModel, "backend">): ReviewBackend;

package/dist/node/core/openscreen.js

@@ -0,0 +1,97 @@
+/**
+ * The OpenScreen backend's host side: the feature gate, its studio routes and UI conversions, with no DOM so it tests alone.
+ */
+/** The gate is shut until the studio says otherwise, so an unread answer is off. */
+export const FEATURES_OFF = { openscreen: false, openscreenInstalled: false };
+/** The routes Worker C serves on the studio. The UI calls these and never touches OpenScreen. */
+export const OPENSCREEN_ROUTES = {
+    features: "/features",
+    pair: "/projects/openscreen/pair",
+    record: "/projects/openscreen/record",
+    preview: "/projects/openscreen/preview",
+    sync: "/projects/openscreen/sync",
+    export: "/projects/openscreen/export",
+};
+/** The OpenScreen build this UI was written against. Anything older is untested. */
+export const OPENSCREEN_TESTED_VERSION = "1.13.0";
+/** Homebrew has no cask for OpenScreen, so the install line points at the releases page. */
+export const OPENSCREEN_RELEASES = "https://github.com/getopenscreen/openscreen/releases";
+/**
+ * POST one studio route: a body with `ok` is taken as is, a bare 2xx counts as success, and every failure becomes readable text.
+ */
+export async function hostPost(path, body) {
+    try {
+        const response = await fetch(path, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        const answer = await response.json().catch(() => null);
+        if (typeof answer === "object" && answer !== null) {
+            const record = answer;
+            if ("ok" in record)
+                return record;
+            if (!response.ok && typeof record.error === "string" && record.error)
+                return { ok: false, error: record.error };
+        }
+        if (response.ok)
+            return { ok: true };
+        return { ok: false, error: response.statusText || "The studio didn't answer." };
+    }
+    catch {
+        return { ok: false, error: "Couldn't reach the studio." };
+    }
+}
+/** The gate is open only when the studio says so. A missing answer keeps it shut. */
+export function gateOpen(features) {
+    return features?.openscreen === true;
+}
+/** A model is on the OpenScreen backend when its adapter says so. */
+export function isOpenScreen(model) {
+    return model?.backend === "openscreen";
+}
+/** Read the `/features` body without trusting its shape. */
+export function readFeatures(value) {
+    const body = (typeof value === "object" && value !== null ? value : {});
+    return {
+        openscreen: body.openscreen === true,
+        openscreenInstalled: body.openscreenInstalled === true,
+    };
+}
+/** Seconds from a field into whole milliseconds. A blank or unreadable value means no offset. */
+export function secondsToMs(value) {
+    if (value === null || value === undefined)
+        return 0;
+    const text = String(value).trim();
+    if (text === "")
+        return 0;
+    const seconds = Number(text);
+    return Number.isFinite(seconds) ? Math.round(seconds * 1000) : 0;
+}
+/** What the pair route's body wants: trimmed paths and the offset in milliseconds. */
+export function pairBody(fields) {
+    return {
+        name: fields.name.trim(),
+        screen: fields.screen.trim(),
+        camera: fields.camera.trim(),
+        offsetMs: secondsToMs(fields.offset),
+    };
+}
+/** What the form still needs before it can send. Empty means it can. */
+export function pairProblem(fields) {
+    if (!fields.name.trim())
+        return "Name the video first.";
+    if (!fields.screen.trim())
+        return "Add the screen recording.";
+    return "";
+}
+/** A route's error as one line a person reads, or an empty line when it worked. */
+export function resultText(result) {
+    if (!result || result.ok)
+        return "";
+    return result.error || "That didn't work.";
+}
+/** The backend a model runs on, defaulting to what every existing video uses. */
+export function backendOf(model) {
+    return model.backend ?? "descript";
+}

package/dist/node/core/render-words.d.ts

@@ -0,0 +1,8 @@
+/** What a render is, in the words a person uses: the preview video, or the final. */
+export type RenderNoun = "video" | "final";
+/** Every render state, worded once. The cover on the frame and the Render final button both read from here. */
+export declare const renderWords: {
+    /** `ahead` left out says only that it's waiting, for a space with no room for the count. */
+    queued: (noun: RenderNoun, ahead?: number) => string;
+    making: (noun: RenderNoun, updating?: boolean) => string;
+};

package/dist/node/core/render-words.js

@@ -0,0 +1,12 @@
+/** Every render state, worded once. The cover on the frame and the Render final button both read from here. */
+export const renderWords = {
+    /** `ahead` left out says only that it's waiting, for a space with no room for the count. */
+    queued: (noun, ahead) => {
+        if (ahead === 0)
+            return `Your ${noun} is next in line`;
+        if (ahead === undefined)
+            return `Your ${noun} is in line`;
+        return `Your ${noun} is in line, ${ahead} ${ahead === 1 ? "video" : "videos"} ahead of it`;
+    },
+    making: (noun, updating = false) => `${updating ? "Updating" : "Making"} your ${noun}`,
+};