@tangle-network/agent-app 0.45.54 → 0.45.56

package/dist/{store-B7LLlk9p.d.ts → sequences/model.d.ts}

@@ -11,20 +11,20 @@
  * dispatcher converts exactly once). Nothing here touches a database, the DOM,
  * or React.
  */
-declare const MIN_SEQUENCE_CLIP_FRAMES = 1;
+export declare const MIN_SEQUENCE_CLIP_FRAMES = 1;
 /** Track kinds. `reference` holds non-rendered guide media; `agent` holds the
  *  agent-decision lane rendered as markers, never as media. */
-type SequenceTrackKind = 'video' | 'audio' | 'caption' | 'reference' | 'agent';
+export type SequenceTrackKind = 'video' | 'audio' | 'caption' | 'reference' | 'agent';
 /** Define sequence status as one of the specific lifecycle stages draft, active, exporting, or archived */
-type SequenceStatus = 'draft' | 'active' | 'exporting' | 'archived';
+export type SequenceStatus = 'draft' | 'active' | 'exporting' | 'archived';
 /** Define export formats available for sequence data including video, subtitle, and metadata types */
-type SequenceExportFormat = 'mp4' | 'otio' | 'xml' | 'edl' | 'vtt' | 'srt' | 'contact_sheet';
+export type SequenceExportFormat = 'mp4' | 'otio' | 'xml' | 'edl' | 'vtt' | 'srt' | 'contact_sheet';
 /** Represent export status of a sequence as queued, processing, completed, failed, or cancelled */
-type SequenceExportStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled';
+export type SequenceExportStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled';
 /** Define media types allowed in a sequence including video, image, and audio */
-type SequenceMediaKind = 'video' | 'image' | 'audio';
+export type SequenceMediaKind = 'video' | 'image' | 'audio';
 /** Describe metadata and properties of a media sequence including dimensions, duration, and status */
-interface SequenceMeta {
+export interface SequenceMeta {
     id: string;
     title: string;
     fps: number;
@@ -36,7 +36,7 @@ interface SequenceMeta {
     metadata: Record<string, unknown>;
 }
 /** Define properties and state for a sequence track including id, kind, name, order, and flags */
-interface SequenceTrack {
+export interface SequenceTrack {
     id: string;
     kind: SequenceTrackKind;
     name: string;
@@ -48,7 +48,7 @@ interface SequenceTrack {
 /** Resolved playable media behind a clip. The store resolves product-specific
  *  references (generation rows, asset rows) into this shape; the core model
  *  never sees the product's tables. */
-interface SequenceClipMedia {
+export interface SequenceClipMedia {
     url: string;
     kind: SequenceMediaKind;
     /** Natural duration of the source media when known. */
@@ -57,7 +57,7 @@ interface SequenceClipMedia {
     providerStatus?: 'queued' | 'processing' | 'completed' | 'failed';
 }
 /** Define properties for a media sequence clip including timing, source, track, and caption details */
-interface SequenceClip {
+export interface SequenceClip {
     id: string;
     trackId: string;
     label: string;
@@ -82,7 +82,7 @@ interface SequenceClip {
 /** One entry in the sequence's decision log — human edits, agent proposals,
  *  agent edits, exports, and notes all land here so the edit history is a
  *  single auditable lane. */
-interface SequenceDecision {
+export interface SequenceDecision {
     id: string;
     clipId: string | null;
     kind: 'human_edit' | 'agent_proposal' | 'agent_edit' | 'export' | 'note';
@@ -93,7 +93,7 @@ interface SequenceDecision {
     createdAt: Date;
 }
 /** Describe a record representing the export details and status of a sequence */
-interface SequenceExportRecord {
+export interface SequenceExportRecord {
     id: string;
     format: SequenceExportFormat;
     status: SequenceExportStatus;
@@ -103,14 +103,14 @@ interface SequenceExportRecord {
 }
 /** The full timeline aggregate — what `get_timeline_state` returns and what
  *  every operation validates against. */
-interface SequenceTimeline {
+export interface SequenceTimeline {
     sequence: SequenceMeta;
     tracks: SequenceTrack[];
     clips: SequenceClip[];
 }
 /** What is on screen/audible at a single frame — the answer shape for
  *  "what is happening at 0:34". */
-interface SequenceFrameSnapshot {
+export interface SequenceFrameSnapshot {
     frame: number;
     seconds: number;
     /** Active (enabled, in-range) clips at this frame, with their track. */
@@ -126,37 +126,37 @@ interface SequenceFrameSnapshot {
     }>;
 }
 /** Convert seconds to the nearest whole number of frames based on frames per second */
-declare function secondsToFrames(seconds: number, fps: number): number;
+export declare function secondsToFrames(seconds: number, fps: number): number;
 /** Convert a frame count to seconds based on the given frames per second rate */
-declare function framesToSeconds(frames: number, fps: number): number;
+export declare function framesToSeconds(frames: number, fps: number): number;
 /** Format a number of seconds into a string with integer or two-decimal precision suffix s */
-declare function formatSeconds(seconds: number): string;
+export declare function formatSeconds(seconds: number): string;
 /** `m:ss.ff` timecode for UI and agent-readable frame references. */
-declare function formatTimecode(frames: number, fps: number): string;
+export declare function formatTimecode(frames: number, fps: number): string;
 /** Define the start frame and duration in frames for a timeline clip's bounds */
-interface TimelineClipBounds {
+export interface TimelineClipBounds {
     startFrame: number;
     durationFrames: number;
 }
 /** Define a time range with inclusive start and end frame numbers */
-interface TimelineInterval {
+export interface TimelineInterval {
     startFrame: number;
     endFrame: number;
 }
 /** Clamp the clip start frame within the valid range of the sequence duration and clip length */
-declare function clampClipStart(input: {
+export declare function clampClipStart(input: {
     startFrame: number;
     durationFrames: number;
     sequenceDurationFrames: number;
 }): number;
 /** Clamp clip duration to fit within sequence bounds and minimum length constraints */
-declare function clampClipDuration(input: {
+export declare function clampClipDuration(input: {
     startFrame: number;
     durationFrames: number;
     sequenceDurationFrames: number;
 }): number;
 /** Validate that a clip's start and duration fit within the sequence duration without overflow */
-declare function assertClipFitsSequence(input: {
+export declare function assertClipFitsSequence(input: {
     startFrame: number;
     durationFrames: number;
     sequenceDurationFrames: number;
@@ -167,97 +167,13 @@ declare function assertClipFitsSequence(input: {
  *  holding (or first after) the playhead wins; with everything ahead occupied
  *  the latest earlier gap is used instead. Throws when no gap can hold the
  *  minimum — the caller must supply explicit bounds or clear space. */
-declare function chooseCaptionPlacement(input: {
+export declare function chooseCaptionPlacement(input: {
     playheadFrame: number;
     fps: number;
     sequenceDurationFrames: number;
     occupiedIntervals: TimelineInterval[];
 }): TimelineClipBounds;
 /** Resolve everything active at one frame — the core of `get_frame_at_time`. */
-declare function snapshotFrame(timeline: SequenceTimeline, frame: number): SequenceFrameSnapshot;
+export declare function snapshotFrame(timeline: SequenceTimeline, frame: number): SequenceFrameSnapshot;
 /** Occupied intervals on one track, for placement collision checks. */
-declare function trackIntervals(timeline: SequenceTimeline, trackId: string): TimelineInterval[];
-
-/**
- * Storage contract binding the sequence model to a product's database. The
- * product constructs one store per (workspace, sequence, actor) request scope —
- * RBAC and workspace isolation happen BEFORE construction (the product's
- * `requireWorkspaceAccess` equivalent); the store never re-checks identity.
- *
- * Every method throws on failure — no silent nulls, no `{ ok: false }` wrappers
- * at this layer. The MCP dispatcher (./mcp) is the boundary that converts
- * thrown errors into structured tool errors the model can read and react to.
- *
- * Mutations append to the decision log themselves only when the operation
- * dispatcher asks (`recordDecision`); plain CRUD stays log-free so human edits
- * driven by the UI can batch their own decision entries.
- */
-
-/** Define properties for a new sequence track including kind, name, and optional sort order */
-interface NewSequenceTrack {
-    kind: SequenceTrackKind;
-    name: string;
-    sortOrder?: number;
-}
-/** Define properties for a new sequence clip including timing, labels, and optional metadata */
-interface NewSequenceClip {
-    trackId: string;
-    label: string;
-    startFrame: number;
-    durationFrames: number;
-    sourceInFrame?: number;
-    sourceOutFrame?: number | null;
-    text?: string;
-    language?: string;
-    generationId?: string;
-    assetId?: string;
-    metadata?: Record<string, unknown>;
-}
-/** Define optional properties to update or patch a sequence clip's attributes in a timeline */
-interface SequenceClipPatch {
-    trackId?: string;
-    label?: string;
-    startFrame?: number;
-    durationFrames?: number;
-    sourceInFrame?: number;
-    sourceOutFrame?: number | null;
-    disabled?: boolean;
-    text?: string;
-    language?: string;
-    metadata?: Record<string, unknown>;
-}
-/** Define the structure for a new sequence decision with optional metadata and acceptance status */
-interface NewSequenceDecision {
-    clipId?: string | null;
-    kind: SequenceDecision['kind'];
-    instruction: string;
-    reasoningSummary?: string | null;
-    accepted?: boolean | null;
-    metadata?: Record<string, unknown>;
-}
-/** Manage sequences by providing methods to get timelines, clips, and modify tracks and clips */
-interface SequenceStore {
-    /** Full aggregate: sequence meta + tracks + clips with resolved media. */
-    getTimeline(): Promise<SequenceTimeline>;
-    getClip(clipId: string): Promise<SequenceClip>;
-    createTrack(input: NewSequenceTrack): Promise<SequenceTrack>;
-    createClip(input: NewSequenceClip): Promise<SequenceClip>;
-    updateClip(clipId: string, patch: SequenceClipPatch): Promise<SequenceClip>;
-    deleteClip(clipId: string): Promise<void>;
-    /** Grow (or shrink, never below the last clip end) the sequence duration. */
-    updateSequenceDuration(durationFrames: number): Promise<SequenceMeta>;
-    recordDecision(input: NewSequenceDecision): Promise<SequenceDecision>;
-    createExport(format: SequenceExportFormat, metadata?: Record<string, unknown>): Promise<SequenceExportRecord>;
-    listDecisions(limit?: number): Promise<SequenceDecision[]>;
-    listExports(limit?: number): Promise<SequenceExportRecord[]>;
-}
-/** Per-request scope a product binds when constructing its store. Carried so
- *  decision rows and export rows attribute to the acting user; never trusted
- *  from tool arguments. */
-interface SequenceStoreScope {
-    workspaceId: string;
-    sequenceId: string;
-    userId: string;
-}
-
-export { snapshotFrame as A, trackIntervals as B, MIN_SEQUENCE_CLIP_FRAMES as M, type NewSequenceClip as N, type SequenceStoreScope as S, type TimelineClipBounds as T, type SequenceClipMedia as a, type SequenceStore as b, type SequenceTrackKind as c, type SequenceExportFormat as d, type SequenceTrack as e, type SequenceTimeline as f, type SequenceClip as g, type SequenceExportRecord as h, type SequenceMeta as i, type SequenceMediaKind as j, type TimelineInterval as k, type NewSequenceDecision as l, type NewSequenceTrack as m, type SequenceClipPatch as n, type SequenceDecision as o, type SequenceExportStatus as p, type SequenceFrameSnapshot as q, type SequenceStatus as r, assertClipFitsSequence as s, chooseCaptionPlacement as t, clampClipDuration as u, clampClipStart as v, formatSeconds as w, formatTimecode as x, framesToSeconds as y, secondsToFrames as z };
+export declare function trackIntervals(timeline: SequenceTimeline, trackId: string): TimelineInterval[];

package/dist/sequences/operations.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The sequence operation union — the ONE mutation vocabulary shared by every
+ * writer of a timeline: the MCP tool dispatcher (agent edits), the React
+ * editor's command stack (human edits, undo/redo), and batch agent plans.
+ * Positions are integer frames; the seconds→frames conversion happens at the
+ * tool-argument edge (./mcp), never here.
+ *
+ * Validation lives in ./validate (`validateSequenceOperations`) and runs
+ * against a `SequenceTimeline` BEFORE any store write; application lives in
+ * ./apply (`applySequenceOperation`) which maps one validated operation to
+ * `SequenceStore` calls. Keeping the union closed and frame-typed is what lets
+ * undo work: every operation has a computable inverse given the pre-state.
+ */
+import type { SequenceExportFormat, SequenceTrackKind } from './model';
+/** Define an operation to place a media clip with timing, track, and playback options */
+export interface PlaceClipOperation {
+    type: 'place_clip';
+    /** Omitted → first unlocked track matching the media kind. */
+    trackId?: string;
+    label: string;
+    startFrame: number;
+    durationFrames: number;
+    sourceInFrame?: number;
+    /** Explicit source out-point; null/omitted → natural end of the source.
+     *  Carried so the durable inverse of a delete can restore a split clip's
+     *  exact playable window. */
+    sourceOutFrame?: number | null;
+    /** Create the clip disabled; omitted → enabled. Carried so the durable
+     *  inverse of deleting a disabled clip does not resurrect it visible. */
+    disabled?: boolean;
+    media?: {
+        url: string;
+        kind: 'video' | 'image' | 'audio';
+    };
+    generationId?: string;
+    assetId?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Add a caption with optional language, timing, and track placement details */
+export interface AddCaptionOperation {
+    type: 'add_caption';
+    text: string;
+    /** BCP-47 tag; omitted → sequence default language. */
+    language?: string;
+    /** Omitted → placed near the playhead via `chooseCaptionPlacement`. */
+    startFrame?: number;
+    durationFrames?: number;
+    /** Target caption track; omitted → first unlocked caption track, creating
+     *  a per-language track when `language` names one that has none. */
+    trackId?: string;
+}
+/** Resolve an operation to move a clip to a new start frame and optional track */
+export interface MoveClipOperation {
+    type: 'move_clip';
+    clipId: string;
+    startFrame: number;
+    trackId?: string;
+}
+/** Define an operation to trim a clip by adjusting its start, duration, and optional source in/out points */
+export interface TrimClipOperation {
+    type: 'trim_clip';
+    clipId: string;
+    startFrame: number;
+    durationFrames: number;
+    /** New source in-point when trimming the head; omitted → unchanged. */
+    sourceInFrame?: number;
+    /** New source out-point; null releases it to the source's natural end;
+     *  omitted → unchanged. Required when extending a clip whose stored window
+     *  (e.g. a split head's cut point) is too short for the new duration, and
+     *  by the durable inverse of `split_clip` to restore the original window. */
+    sourceOutFrame?: number | null;
+}
+/** Split a clip at a specified frame inside the clip to create two separate segments */
+export interface SplitClipOperation {
+    type: 'split_clip';
+    clipId: string;
+    /** Sequence-frame to cut at; must fall strictly inside the clip. */
+    atFrame: number;
+}
+/** Resolve an operation to set clipboard text with optional language and clip identifier */
+export interface SetClipTextOperation {
+    type: 'set_clip_text';
+    clipId: string;
+    text: string;
+    language?: string;
+}
+/** Define an operation to enable or disable a clip by its identifier */
+export interface SetClipDisabledOperation {
+    type: 'set_clip_disabled';
+    clipId: string;
+    disabled: boolean;
+}
+/** Represent a delete clip operation with a specified clip identifier */
+export interface DeleteClipOperation {
+    type: 'delete_clip';
+    clipId: string;
+}
+/** Define an operation to create a new sequence track with a specified kind and name */
+export interface CreateTrackOperation {
+    type: 'create_track';
+    kind: SequenceTrackKind;
+    name: string;
+}
+/** Define an operation to extend a sequence by a specified number of frames */
+export interface ExtendSequenceOperation {
+    type: 'extend_sequence';
+    durationFrames: number;
+}
+/** Define the structure for a queue export operation with format and optional metadata */
+export interface QueueExportOperation {
+    type: 'queue_export';
+    format: SequenceExportFormat;
+    metadata?: Record<string, unknown>;
+}
+/** Represent sequence editing actions for manipulating clips, tracks, captions, and exports */
+export type SequenceOperation = PlaceClipOperation | AddCaptionOperation | MoveClipOperation | TrimClipOperation | SplitClipOperation | SetClipTextOperation | SetClipDisabledOperation | DeleteClipOperation | CreateTrackOperation | ExtendSequenceOperation | QueueExportOperation;
+/** A batch of operations with the agent's stated intent — the decision-log
+ *  unit for agent edits. */
+export interface SequencePlan {
+    summary: string;
+    operations: SequenceOperation[];
+}
+/** Extract the type of operation from a sequence operation object */
+export type SequenceOperationType = SequenceOperation['type'];
+/** List all valid sequence operation types used in editing workflows */
+export declare const SEQUENCE_OPERATION_TYPES: readonly SequenceOperationType[];