@cueframe/kernel 0.0.1

package/dist/_members/media-model/api.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { zid } from "convex-helpers/server/zod3";
+// Phase labels for media processing. One canonical vocabulary across desktop,
+// Convex, and OpenAPI — no per-consumer redefinition. Superset of every stage
+// either side runs:
+//   shared:        idle → pending_import → pending_upload → uploading → ...
+//                  → complete | error | cancelled
+//   desktop-local: extracting (audio extract), loading_model (whisper download),
+//                  transcribing, proxy (low-res preview transcode), embedding,
+//                  analyzing, indexing
+//   cloud-only:    generating (TTS / text-to-image), rendering (final encode)
+//   intermediate:  processing (generic in-flight when no specific stage applies)
+//
+// Legacy cloud writers that wrote 'completed'/'ready'/'failed'/'in_progress'/
+// 'transcoding' map onto this canonical via projectStatus() in
+// projections/mediaItems.ts; the data migration in PR 2 backfills them.
+export const MediaProcessingPhase = z.enum([
+    "idle",
+    "pending_import",
+    "pending_upload",
+    "uploading",
+    "extracting",
+    "loading_model",
+    "transcribing",
+    "proxy",
+    "embedding",
+    "analyzing",
+    "indexing",
+    "generating",
+    "rendering",
+    "processing",
+    "complete",
+    "error",
+    "cancelled",
+]);
+// ProxyStatus — lifecycle of the low-res preview proxy file. One canonical
+// enum across desktop SQLite, Convex `mediaItems.proxyStatus`, and any
+// OpenAPI shape that exposes proxy state.
+export const ProxyStatus = z.enum([
+    "none",
+    "generating",
+    "ready",
+    "failed",
+]);
+// MediaProcessingStatus — runtime state object combining phase + progress
+// detail. This is the single shape every consumer (desktop, Convex storage,
+// OpenAPI responses) sees. Older code that referenced `MediaProcessingStatus`
+// as an enum should now reference `MediaProcessingPhase`; older code that
+// hand-defined a `{phase, percent, message, error}` object (OpenAPI, desktop
+// discriminated unions) should now import this.
+// percent/message/error are nullable AND optional — desktop construction
+// sites typically omit them (`{ phase: 'idle' }`), worker writes nullable
+// (e.g. `{ phase: 'processing', percent: 60, message: 'Transcribing', error: null }`),
+// OpenAPI emission preserves whichever the producer sent. Consumers tolerate
+// any of: present-with-value | present-with-null | omitted.
+export const MediaProcessingStatus = z.object({
+    phase: MediaProcessingPhase,
+    percent: z.number().nullable().optional(),
+    message: z.string().nullable().optional(),
+    error: z.string().nullable().optional(),
+});
+// MediaUnderstanding — populated by the visual/topical analysis stage.
+// Shape is intentionally permissive at P0; pipeline stages may extend it.
+export const MediaUnderstanding = z.object({
+    summary: z.string().optional(),
+    topics: z.array(z.string()).optional(),
+    language: z.string().optional(),
+    notes: z.string().optional(),
+    extra: z.record(z.string(), z.unknown()).optional(),
+});
+// Generation — present iff MediaItem.source === 'generated'.
+// Provider is an open string mapping to a server-side generator registered with credentials;
+// new providers are additions to the generator registry, not schema migrations.
+export const TextToSpeechGeneration = z.object({
+    kind: z.literal("text-to-speech"),
+    provider: z.string().min(1),
+    text: z.string().min(1),
+    voice: z.string().min(1),
+    params: z.record(z.string(), z.unknown()).optional(),
+});
+export const TextToImageGeneration = z.object({
+    kind: z.literal("text-to-image"),
+    provider: z.string().min(1),
+    prompt: z.string().min(1),
+    params: z.record(z.string(), z.unknown()).optional(),
+});
+export const ImageToVideoGeneration = z.object({
+    kind: z.literal("image-to-video"),
+    provider: z.string().min(1),
+    sourceMediaId: zid("mediaItems"),
+    prompt: z.string().optional(),
+    params: z.record(z.string(), z.unknown()).optional(),
+});
+export const ManimGeneration = z.object({
+    kind: z.literal("manim"),
+    scriptId: z.string().optional(),
+    inlineScript: z.string().optional(),
+    params: z.record(z.string(), z.unknown()).optional(),
+});
+export const Generation = z.discriminatedUnion("kind", [
+    TextToSpeechGeneration,
+    TextToImageGeneration,
+    ImageToVideoGeneration,
+    ManimGeneration,
+]);
+// TranscriptRef — pointer to the transcript artifact (full word-level data lives in R2,
+// the row carries metadata + R2 key). `ready` flips when the transcribe stage completes.
+export const TranscriptRef = z.object({
+    id: z.string().min(1),
+    ready: z.boolean(),
+});
+// Agent-perception surface (filmstrip + per-frame analysis) — populated by
+// the perception pipeline stage post-ingestion. Placed before MediaItem so
+// MediaItem's `perception` field resolves.
+// FrameAnalysis — analysis derived from a single sampled frame: spatial
+// regions (faces, primary subject, safe regions for overlay placement) and
+// non-spatial signals (dominant colors). Keyed by timestamp `t`.
+export const FrameAnalysis = z.object({
+    t: z.number().nonnegative(),
+    faces: z.array(z.object({
+        bbox: z.tuple([z.number(), z.number(), z.number(), z.number()]),
+        confidence: z.number().min(0).max(1).optional(),
+    })).optional(),
+    primarySubject: z.object({
+        bbox: z.tuple([z.number(), z.number(), z.number(), z.number()]),
+    }).optional(),
+    safeRegions: z.array(z.object({
+        bbox: z.tuple([z.number(), z.number(), z.number(), z.number()]),
+        kind: z.string().optional(),
+    })).optional(),
+    dominantColors: z.array(z.string()).optional(),
+});
+export const Filmstrip = z.object({
+    mediaId: zid("mediaItems"),
+    sheetUrl: z.string().url(),
+    frameCount: z.number().int().positive(),
+    frameInterval: z.number().positive(),
+    frameWidth: z.number().int().positive(),
+    frameHeight: z.number().int().positive(),
+    columns: z.number().int().positive(),
+});
+// Perception — bundle of pre-computed perception artifacts for a MediaItem row.
+// Filmstrip is the visual artifact (sprite-sheet); frameAnalysis[] is the
+// per-moment structured analysis. Read by agents reasoning about content
+// without re-decoding the source.
+export const Perception = z.object({
+    mediaId: zid("mediaItems"),
+    filmstrip: Filmstrip.optional(),
+    frameAnalysis: z.array(FrameAnalysis).optional(),
+});
+export const MediaItem = z.object({
+    id: zid("mediaItems"),
+    // Track-routing kind; not in the data-model.md spec but load-bearing for
+    // the existing storage pipeline. video/audio/image determine ingest path.
+    kind: z.enum(["video", "audio", "image"]),
+    filename: z.string().min(1),
+    // Aliased per data-model.md § MediaItem — `mimeType` is the doc name; `size` is bytes.
+    mimeType: z.string().min(1),
+    size: z.number().int().nonnegative(),
+    duration: z.number().nonnegative().optional(), // seconds; populated post-transcode
+    width: z.number().int().positive().optional(),
+    height: z.number().int().positive().optional(),
+    fps: z.number().positive().optional(),
+    status: MediaProcessingPhase,
+    source: z.enum(["upload", "generated"]).optional(),
+    generation: Generation.optional(),
+    // Derived data populated through the pipeline
+    transcript: TranscriptRef.optional(),
+    mediaUnderstanding: MediaUnderstanding.optional(),
+    perception: Perception.optional(),
+    // Lifecycle timestamps — epoch ms (see CONVEX_ADAPTATIONS.md)
+    createdAt: z.number(),
+    updatedAt: z.number(),
+    ownerOrgId: z.string().optional(),
+});

package/dist/_members/media-model/index.d.ts

@@ -0,0 +1 @@
+export * from "./api.js";

package/dist/_members/media-model/index.js

@@ -0,0 +1 @@
+export * from "./api";

package/dist/_members/media-model/media-kind.d.ts

@@ -0,0 +1,36 @@
+/** `opaque` is `asset` renamed (spec §5): "asset" was the word that made two
+ *  different concepts — storage furniture and a media classification — look
+ *  like one. `opaque` states the contract: no pipeline, not placeable. */
+export type MediaKind = "video" | "audio" | "image" | "opaque";
+export declare const IMAGE_CONTENT_TYPES: readonly ["image/png", "image/jpeg", "image/webp"];
+/** Closed allowlist — the complete set of accepted content-types (the acceptance
+ *  gate). mediaKind() routes each: video/audio/still-image do real work;
+ *  fonts/json/svg/gif route to the opaque path. Unknown bytes (not here)
+ *  are rejected at the edge. */
+export declare const ALLOWED_CONTENT_TYPES: readonly ["video/mp4", "video/quicktime", "video/x-matroska", "video/webm", "audio/mpeg", "audio/wav", "audio/x-wav", "audio/mp4", "audio/aac", "image/png", "image/jpeg", "image/webp", "image/gif", "image/svg+xml", "application/json", "font/ttf", "font/otf", "font/woff", "font/woff2"];
+export type AllowedContentType = (typeof ALLOWED_CONTENT_TYPES)[number];
+export declare function mediaKind(contentType: string): MediaKind;
+export declare function extensionForContentType(contentType: string): string;
+/** What a file IS, from nothing but its name — the ONE derivation the import
+ *  door, the project-file parse gate, and migration 020's SQL all mirror. */
+export declare function mediaKindForFilename(filename: string): MediaKind;
+/** Every extension whose derived kind can occupy time. The import door's
+ *  accept-list IS this list — derived, so the door and the authority cannot
+ *  disagree (the disagreement was a thrown import for `.jpeg`/`.m4a`). */
+export declare const POOL_EXTENSIONS: readonly string[];
+/**
+ * The content-type to UPLOAD a file as, given what the platform claimed and
+ * what the file is called.
+ *
+ * WHY THIS EXISTS. The upload client used to send `file.type || "video/mp4"`.
+ * Both halves are wrong: the alias case rejects real MP3s (see above), and the
+ * fallback silently relabels ANY untyped file as video — so an MP3 dragged in
+ * without a MIME is accepted and then routed down the VIDEO transcode path by
+ * `mediaKind()`, which is a wrong pipeline rather than an honest refusal.
+ *
+ * Order: an already-allowed type wins, then a known alias, then the extension.
+ * If none of those resolve, the ORIGINAL string is returned unchanged — never a
+ * guess. The closed gate then refuses it and names the type the user actually
+ * has, which is the error message they need.
+ */
+export declare function contentTypeForUpload(filename: string, claimed?: string | null): string;

package/dist/_members/media-model/media-kind.js

@@ -0,0 +1,116 @@
+export const IMAGE_CONTENT_TYPES = ["image/png", "image/jpeg", "image/webp"];
+/** Closed allowlist — the complete set of accepted content-types (the acceptance
+ *  gate). mediaKind() routes each: video/audio/still-image do real work;
+ *  fonts/json/svg/gif route to the opaque path. Unknown bytes (not here)
+ *  are rejected at the edge. */
+export const ALLOWED_CONTENT_TYPES = [
+    "video/mp4", "video/quicktime", "video/x-matroska", "video/webm",
+    "audio/mpeg", "audio/wav", "audio/x-wav", "audio/mp4", "audio/aac",
+    "image/png", "image/jpeg", "image/webp",
+    "image/gif", "image/svg+xml", "application/json",
+    "font/ttf", "font/otf", "font/woff", "font/woff2",
+];
+export function mediaKind(contentType) {
+    const ct = (contentType || "").toLowerCase();
+    if (ct.startsWith("video/"))
+        return "video";
+    if (ct.startsWith("audio/"))
+        return "audio";
+    if (IMAGE_CONTENT_TYPES.includes(ct))
+        return "image";
+    return "opaque";
+}
+const EXT = {
+    "video/mp4": "mp4", "audio/mp4": "mp4", "video/quicktime": "mov",
+    "video/x-matroska": "mkv", "video/webm": "webm", "video/x-msvideo": "avi",
+    "audio/mpeg": "mp3", "audio/wav": "wav", "audio/x-wav": "wav", "audio/aac": "aac",
+    "audio/ogg": "ogg", "audio/flac": "flac",
+    "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp",
+    "font/ttf": "ttf", "font/otf": "otf", "font/woff": "woff", "font/woff2": "woff2",
+    "application/json": "json", "image/svg+xml": "svg", "image/gif": "gif",
+};
+export function extensionForContentType(contentType) {
+    return EXT[(contentType || "").toLowerCase()] ?? "bin";
+}
+/**
+ * MIME ALIASES THE PLATFORM EMITS FOR TYPES WE ALREADY ACCEPT.
+ *
+ * `ALLOWED_CONTENT_TYPES` is a CLOSED gate keyed on an exact string, and the
+ * same bytes get different strings depending on who describes them: WebKit says
+ * `audio/mp3` where the registry says `audio/mpeg`, Apple says `audio/x-m4a`
+ * where the registry says `audio/mp4`. Rejecting those is not the gate doing
+ * its job — it is the gate mistaking a spelling for a format, and the user gets
+ * "Unsupported file type" for a plain MP3.
+ *
+ * Only aliases of types ALREADY on the allowlist belong here. This must not
+ * become a way to smuggle in a format the pipeline cannot decode.
+ */
+const CONTENT_TYPE_ALIASES = {
+    "audio/mp3": "audio/mpeg",
+    "audio/x-mp3": "audio/mpeg",
+    "audio/x-mpeg": "audio/mpeg",
+    "audio/mpeg3": "audio/mpeg",
+    "audio/x-mpeg-3": "audio/mpeg",
+    "audio/x-m4a": "audio/mp4",
+    "audio/m4a": "audio/mp4",
+    "audio/wave": "audio/wav",
+    "audio/vnd.wave": "audio/wav",
+    "audio/x-aac": "audio/aac",
+    "image/jpg": "image/jpeg",
+    "video/x-quicktime": "video/quicktime",
+    "video/mov": "video/quicktime",
+    "video/x-m4v": "video/mp4",
+    "video/mkv": "video/x-matroska",
+};
+/** Extension → canonical content-type, derived from the EXT map so the two
+ *  cannot drift. Built once. */
+const TYPE_BY_EXTENSION = Object.entries(EXT).reduce((acc, [contentType, ext]) => {
+    // First writer wins, so `audio/mp4` does not steal `mp4` from `video/mp4`.
+    if (!(ext in acc))
+        acc[ext] = contentType;
+    return acc;
+}, {});
+// Spellings EXT cannot carry (it is contentType→ext, one ext per type): the
+// long form of jpg, and m4a — whose canonical type audio/mp4 lost the "mp4"
+// slot to video above.
+TYPE_BY_EXTENSION["jpeg"] = "image/jpeg";
+TYPE_BY_EXTENSION["m4a"] = "audio/mp4";
+/** What a file IS, from nothing but its name — the ONE derivation the import
+ *  door, the project-file parse gate, and migration 020's SQL all mirror. */
+export function mediaKindForFilename(filename) {
+    return mediaKind(contentTypeForUpload(filename, null));
+}
+/** Every extension whose derived kind can occupy time. The import door's
+ *  accept-list IS this list — derived, so the door and the authority cannot
+ *  disagree (the disagreement was a thrown import for `.jpeg`/`.m4a`). */
+export const POOL_EXTENSIONS = Object.entries(TYPE_BY_EXTENSION)
+    .filter(([, contentType]) => mediaKind(contentType) !== "opaque")
+    .map(([ext]) => ext);
+/**
+ * The content-type to UPLOAD a file as, given what the platform claimed and
+ * what the file is called.
+ *
+ * WHY THIS EXISTS. The upload client used to send `file.type || "video/mp4"`.
+ * Both halves are wrong: the alias case rejects real MP3s (see above), and the
+ * fallback silently relabels ANY untyped file as video — so an MP3 dragged in
+ * without a MIME is accepted and then routed down the VIDEO transcode path by
+ * `mediaKind()`, which is a wrong pipeline rather than an honest refusal.
+ *
+ * Order: an already-allowed type wins, then a known alias, then the extension.
+ * If none of those resolve, the ORIGINAL string is returned unchanged — never a
+ * guess. The closed gate then refuses it and names the type the user actually
+ * has, which is the error message they need.
+ */
+export function contentTypeForUpload(filename, claimed) {
+    const ct = (claimed ?? "").trim().toLowerCase();
+    const allowed = ALLOWED_CONTENT_TYPES;
+    if (ct && allowed.includes(ct))
+        return ct;
+    if (ct && CONTENT_TYPE_ALIASES[ct])
+        return CONTENT_TYPE_ALIASES[ct];
+    const ext = filename.toLowerCase().split(".").pop() ?? "";
+    const byExt = TYPE_BY_EXTENSION[ext];
+    if (byExt)
+        return byExt;
+    return ct;
+}

package/dist/_members/media-model/testing/index.d.ts

@@ -0,0 +1,2 @@
+export { runMediaStoreContract } from './mediaStoreContract.js';
+export type { ContractMediaStore, ContractPoolItem, ContractPoolKind, } from './mediaStoreContract.js';

package/dist/_members/media-model/testing/index.js

@@ -0,0 +1 @@
+export { runMediaStoreContract } from './mediaStoreContract';

package/dist/_members/media-model/testing/mediaStoreContract.d.ts

@@ -0,0 +1,17 @@
+export type ContractPoolKind = 'video' | 'audio' | 'image';
+export interface ContractPoolItem {
+    id: string;
+    name: string;
+    kind: ContractPoolKind;
+    metadata: {
+        duration?: number;
+        width: number;
+        height: number;
+    } | null;
+}
+export interface ContractMediaStore {
+    getPoolItems(): Promise<ContractPoolItem[]>;
+    savePoolItem(item: ContractPoolItem): Promise<void>;
+    deletePoolItem(id: string): Promise<void>;
+}
+export declare function runMediaStoreContract(name: string, makeStore: () => Promise<ContractMediaStore>): void;

package/dist/_members/media-model/testing/mediaStoreContract.js

@@ -0,0 +1,82 @@
+/**
+ * THE MEDIA STORE CONTRACT — one executable statement, every store.
+ *
+ * A pool item is persisted by TWO independent implementations: the desktop's
+ * sqlite (`src-tauri/src/database/pool_items.rs`) and the org's Convex
+ * documents, reached through an adapter each. A third lives in the test double
+ * the app's own tests run against.
+ *
+ * The surface is three verbs — getPoolItems / savePoolItem / deletePoolItem —
+ * and until now it had NO contract, which is the same setup that let
+ * `conversations` and `restorePoints` diverge invisibly for weeks.
+ *
+ * WHY THE RUST LANE IS NOT DRIVEN FROM HERE: it lives behind `cargo test`. The
+ * same facts are written as `#[tokio::test]`s in `database/mod.rs`
+ * (`media_store_contract_tests`) UNDER THE SAME NAMES — matching names are the
+ * seam that makes a one-sided fact one grep away. NOTE: no CI workflow runs
+ * `cargo`, so that half executes only when someone runs it by hand. This is
+ * not coverage.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+const still = (id) => ({
+    id,
+    name: `${id}.png`,
+    kind: 'image',
+    metadata: { width: 1920, height: 1080 },
+});
+const clip = (id) => ({
+    id,
+    name: `${id}.mp4`,
+    kind: 'video',
+    metadata: { duration: 12.5, width: 1920, height: 1080 },
+});
+export function runMediaStoreContract(name, makeStore) {
+    describe(`media store contract: ${name}`, () => {
+        let store;
+        beforeEach(async () => {
+            store = await makeStore();
+        });
+        it('round-trips kind', async () => {
+            await store.savePoolItem(clip('v1'));
+            await store.savePoolItem(still('i1'));
+            const items = await store.getPoolItems();
+            expect(items.find((i) => i.id === 'v1')?.kind).toBe('video');
+            expect(items.find((i) => i.id === 'i1')?.kind).toBe('image');
+        });
+        it('admits only the three placeable kinds', async () => {
+            await store.savePoolItem(clip('v2'));
+            await store.savePoolItem(still('i2'));
+            const kinds = new Set((await store.getPoolItems()).map((i) => i.kind));
+            for (const k of kinds)
+                expect(['video', 'audio', 'image']).toContain(k);
+        });
+        // The bug this whole change came from: a still has no source timeline
+        // (compositionRender.ts:609). A store that hands back 0 has invented one.
+        it('gives a still back with NO duration', async () => {
+            await store.savePoolItem(still('i3'));
+            const got = (await store.getPoolItems()).find((i) => i.id === 'i3');
+            expect(got?.metadata?.duration).toBeUndefined();
+        });
+        it('keeps a real duration on motion media', async () => {
+            await store.savePoolItem(clip('v3'));
+            const got = (await store.getPoolItems()).find((i) => i.id === 'v3');
+            expect(got?.metadata?.duration).toBe(12.5);
+        });
+        it('an audio item is never handed back as video', async () => {
+            await store.savePoolItem({
+                id: 'a1',
+                name: 'a1.mp3',
+                kind: 'audio',
+                metadata: { duration: 30, width: 0, height: 0 },
+            });
+            const got = (await store.getPoolItems()).find((i) => i.id === 'a1');
+            expect(got?.kind).toBe('audio');
+        });
+        it('deleting removes it from the list', async () => {
+            await store.savePoolItem(clip('v4'));
+            await store.deletePoolItem('v4');
+            const items = await store.getPoolItems();
+            expect(items.find((i) => i.id === 'v4')).toBeUndefined();
+        });
+    });
+}

package/dist/_members/media-model/transcriptSearch.d.ts

@@ -0,0 +1,54 @@
+/**
+ * WHAT COUNTS AS A SPOKEN-WORD HIT, AND WHAT IT IS WORTH.
+ *
+ * This rule is implemented TWICE and has to be — the desktop searches its local
+ * `transcript_segments` table in Rust (`src-tauri/src/database/transcripts.rs`),
+ * and the web searches the utterances in an R2 blob in TypeScript. Neither can
+ * call the other: one is a SQL `LIKE` chain inside a Tauri command, the other
+ * runs in a browser against a JSON object it just downloaded.
+ *
+ * SO THE RULE IS DATA, AND BOTH LANES RUN THE SAME DATA. `cases.json` beside
+ * this file is the shared table: each row is a query, some spoken lines, and
+ * the hits they must produce, in order. This module is the TypeScript runner;
+ * `contract_transcript_search_cases` in `database/mod.rs` is the Rust one,
+ * reading the same file. A rule change that lands in one lane and not the other
+ * fails the table on the side that was missed.
+ *
+ * WHY A TABLE AND NOT A PARAMETERISED SUITE: this is a pure, stateless
+ * operation — inputs in, ranking out, no store to set up — which is exactly the
+ * case CLAUDE.md's decision table assigns to fixtures-as-data. A suite is for
+ * stateful CRUD behind one interface.
+ *
+ * WHY THE SCORES MATTER RATHER THAN JUST THE ORDER: `desktopScope`'s library
+ * search puts spoken hits above visual ones and says in its own comment that a
+ * transcript score and a CLIP cosine are different units that must not be
+ * merged by value. That reasoning only holds if a transcript score means one
+ * fixed thing, so two lanes scoring the same line differently would quietly
+ * make the ordering arbitrary.
+ */
+/** One spoken line, as either lane holds it. */
+export interface SpokenLine {
+    text: string;
+    start: number;
+    end: number;
+}
+/** One line that matched, with what it is worth. */
+export interface TranscriptHit extends SpokenLine {
+    /** Term coverage, 0–1. NOT comparable to a CLIP cosine. */
+    score: number;
+}
+/**
+ * A line containing the whole query as a PHRASE is a stronger answer than one
+ * that happens to contain the same words apart. Both outrank nothing.
+ */
+export declare const PHRASE_SCORE = 1;
+export declare const SCATTERED_SCORE = 0.6;
+/** The query, lowercased and split. Empty query = no terms = no hits. */
+export declare function searchTerms(query: string): string[];
+/**
+ * Rank the lines that match every term.
+ *
+ * `limit` is applied LAST, after ranking, so the strongest hits survive a small
+ * limit rather than whichever happened to be spoken first.
+ */
+export declare function rankTranscriptHits(query: string, lines: readonly SpokenLine[], limit?: number): TranscriptHit[];

package/dist/_members/media-model/transcriptSearch.js

@@ -0,0 +1,70 @@
+/**
+ * WHAT COUNTS AS A SPOKEN-WORD HIT, AND WHAT IT IS WORTH.
+ *
+ * This rule is implemented TWICE and has to be — the desktop searches its local
+ * `transcript_segments` table in Rust (`src-tauri/src/database/transcripts.rs`),
+ * and the web searches the utterances in an R2 blob in TypeScript. Neither can
+ * call the other: one is a SQL `LIKE` chain inside a Tauri command, the other
+ * runs in a browser against a JSON object it just downloaded.
+ *
+ * SO THE RULE IS DATA, AND BOTH LANES RUN THE SAME DATA. `cases.json` beside
+ * this file is the shared table: each row is a query, some spoken lines, and
+ * the hits they must produce, in order. This module is the TypeScript runner;
+ * `contract_transcript_search_cases` in `database/mod.rs` is the Rust one,
+ * reading the same file. A rule change that lands in one lane and not the other
+ * fails the table on the side that was missed.
+ *
+ * WHY A TABLE AND NOT A PARAMETERISED SUITE: this is a pure, stateless
+ * operation — inputs in, ranking out, no store to set up — which is exactly the
+ * case CLAUDE.md's decision table assigns to fixtures-as-data. A suite is for
+ * stateful CRUD behind one interface.
+ *
+ * WHY THE SCORES MATTER RATHER THAN JUST THE ORDER: `desktopScope`'s library
+ * search puts spoken hits above visual ones and says in its own comment that a
+ * transcript score and a CLIP cosine are different units that must not be
+ * merged by value. That reasoning only holds if a transcript score means one
+ * fixed thing, so two lanes scoring the same line differently would quietly
+ * make the ordering arbitrary.
+ */
+/**
+ * A line containing the whole query as a PHRASE is a stronger answer than one
+ * that happens to contain the same words apart. Both outrank nothing.
+ */
+export const PHRASE_SCORE = 1.0;
+export const SCATTERED_SCORE = 0.6;
+/** The query, lowercased and split. Empty query = no terms = no hits. */
+export function searchTerms(query) {
+    return query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((t) => t.length > 0);
+}
+/**
+ * Rank the lines that match every term.
+ *
+ * `limit` is applied LAST, after ranking, so the strongest hits survive a small
+ * limit rather than whichever happened to be spoken first.
+ */
+export function rankTranscriptHits(query, lines, limit) {
+    const terms = searchTerms(query);
+    if (terms.length === 0)
+        return [];
+    const phrase = terms.join(" ");
+    const hits = [];
+    for (const line of lines) {
+        const lower = line.text.toLowerCase();
+        // EVERY term, not any — an `AND` chain, matching the SQL the desktop runs.
+        if (!terms.every((t) => lower.includes(t)))
+            continue;
+        hits.push({
+            text: line.text,
+            start: line.start,
+            end: line.end,
+            score: lower.includes(phrase) ? PHRASE_SCORE : SCATTERED_SCORE,
+        });
+    }
+    // Score first, then earliest — stable within a score band, so one media
+    // item's hits stay in the order they were spoken.
+    hits.sort((a, b) => b.score - a.score || a.start - b.start);
+    return limit === undefined ? hits : hits.slice(0, limit);
+}

package/dist/_members/media-model/transcriptSearchCases.json

@@ -0,0 +1,79 @@
+{
+    "$comment": "THE SHARED TABLE. Read by the TypeScript runner (transcriptSearch.test.ts) and by the Rust one (contract_transcript_search_cases in src-tauri/src/database/mod.rs). Adding a row here obliges BOTH lanes. See transcriptSearch.ts for why this rule is data rather than a shared function.",
+    "cases": [
+        {
+            "name": "every term must be present, not just one",
+            "query": "pricing model",
+            "lines": [
+                { "text": "our pricing model is simple", "start": 1, "end": 3 },
+                { "text": "the pricing is simple", "start": 4, "end": 6 },
+                { "text": "a model of the product", "start": 7, "end": 9 }
+            ],
+            "expected": [{ "text": "our pricing model is simple", "start": 1, "end": 3, "score": 1.0 }]
+        },
+        {
+            "name": "the whole phrase outranks the same words apart",
+            "query": "pricing model",
+            "lines": [
+                { "text": "the model behind our pricing", "start": 1, "end": 3 },
+                { "text": "our pricing model", "start": 5, "end": 7 }
+            ],
+            "expected": [
+                { "text": "our pricing model", "start": 5, "end": 7, "score": 1.0 },
+                { "text": "the model behind our pricing", "start": 1, "end": 3, "score": 0.6 }
+            ]
+        },
+        {
+            "name": "within a score band, earliest first",
+            "query": "pricing model",
+            "lines": [
+                { "text": "model, and then pricing", "start": 9, "end": 10 },
+                { "text": "pricing comes after the model", "start": 2, "end": 3 }
+            ],
+            "expected": [
+                { "text": "pricing comes after the model", "start": 2, "end": 3, "score": 0.6 },
+                { "text": "model, and then pricing", "start": 9, "end": 10, "score": 0.6 }
+            ]
+        },
+        {
+            "name": "matching ignores case on both sides",
+            "query": "PRICING",
+            "lines": [{ "text": "Our Pricing Page", "start": 1, "end": 2 }],
+            "expected": [{ "text": "Our Pricing Page", "start": 1, "end": 2, "score": 1.0 }]
+        },
+        {
+            "name": "a term matches inside a word",
+            "query": "price",
+            "lines": [{ "text": "repriced last quarter", "start": 1, "end": 2 }],
+            "expected": [{ "text": "repriced last quarter", "start": 1, "end": 2, "score": 1.0 }]
+        },
+        {
+            "name": "an empty query is no hits, never every hit",
+            "query": "   ",
+            "lines": [{ "text": "anything at all", "start": 1, "end": 2 }],
+            "expected": []
+        },
+        {
+            "name": "extra whitespace in the query does not create an unmatchable term",
+            "query": "  pricing   model  ",
+            "lines": [{ "text": "our pricing model", "start": 1, "end": 2 }],
+            "expected": [{ "text": "our pricing model", "start": 1, "end": 2, "score": 1.0 }]
+        },
+        {
+            "name": "no match is an empty answer",
+            "query": "onboarding",
+            "lines": [{ "text": "our pricing model", "start": 1, "end": 2 }],
+            "expected": []
+        },
+        {
+            "name": "the limit keeps the strongest, not the earliest",
+            "query": "pricing model",
+            "limit": 1,
+            "lines": [
+                { "text": "model, then pricing", "start": 1, "end": 2 },
+                { "text": "our pricing model", "start": 8, "end": 9 }
+            ],
+            "expected": [{ "text": "our pricing model", "start": 8, "end": 9, "score": 1.0 }]
+        }
+    ]
+}

package/dist/_members/nle-export/compact-timeline.d.ts

@@ -0,0 +1,2 @@
+import type { TimelineClip, DeletedRange } from "./types.js";
+export declare function compactTimeline(clips: TimelineClip[], deletedRanges: DeletedRange[]): TimelineClip[];