@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/sequences-react/components/interaction-math.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Pure pointer-gesture math for the timeline editor. Every drag/trim/scrub
+ * gesture quantizes through these functions so the interactive behavior is
+ * unit-testable without a DOM. All inputs/outputs are integer frames except
+ * pixel deltas and zoom (px per frame), which are the only float-valued edge.
+ */
+import type { SnapPoint, SnapResult } from '../contracts';
+/** Quantize a horizontal pointer delta to whole frames at the current zoom. */
+export declare function framesFromPixelDelta(deltaX: number, zoom: number): number;
+export interface MoveDragInput {
+    originStartFrame: number;
+    durationFrames: number;
+    deltaFrames: number;
+    sequenceDurationFrames: number;
+}
+/** New start frame for a move drag, clamped so the clip stays fully inside
+ *  the sequence. */
+export declare function moveDragStartFrame(input: MoveDragInput): number;
+export interface TrimStartDragInput {
+    originStartFrame: number;
+    originDurationFrames: number;
+    originSourceInFrame: number;
+    deltaFrames: number;
+}
+export interface TrimStartDragResult {
+    startFrame: number;
+    durationFrames: number;
+    sourceInFrame: number;
+}
+/**
+ * Head trim: the clip END is invariant; start slides between two hard walls —
+ * it cannot reveal media before source frame 0 (sourceInFrame >= 0) and cannot
+ * pass within MIN_SEQUENCE_CLIP_FRAMES of the end. sourceInFrame shifts by
+ * exactly the start delta so the visible content stays anchored.
+ */
+export declare function trimStartDrag(input: TrimStartDragInput): TrimStartDragResult;
+export interface TrimEndDragInput {
+    originStartFrame: number;
+    originDurationFrames: number;
+    sourceInFrame: number;
+    deltaFrames: number;
+    sequenceDurationFrames: number;
+    /** Natural source length in frames when known; bounds how far the tail can
+     *  extend. Omit for stills and media of unknown length. */
+    sourceDurationFrames?: number;
+}
+/** Tail trim: start is invariant; duration is bounded below by the minimum
+ *  clip length and above by both the sequence end and the remaining source
+ *  material past the in-point. */
+export declare function trimEndDrag(input: TrimEndDragInput): {
+    durationFrames: number;
+};
+/**
+ * Smallest ruler step whose major ticks sit at least `minSpacingPx` apart at
+ * the current zoom; past the table it grows in whole minutes so labels never
+ * collide at extreme zoom-out.
+ */
+export declare function selectTickStepSeconds(input: {
+    zoom: number;
+    fps: number;
+    minSpacingPx?: number;
+}): number;
+export interface LetterboxRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Contain-fit a media aspect inside a container, centered with letterbox or
+ *  pillarbox bars. */
+export declare function letterboxRect(input: {
+    containerWidth: number;
+    containerHeight: number;
+    mediaWidth: number;
+    mediaHeight: number;
+}): LetterboxRect;
+/** Caption type scales with the rendered frame, floored so captions stay
+ *  legible on small previews. */
+export declare function captionFontPx(canvasCssHeight: number): number;
+/** Pixel geometry for a clip chip; width floors at 2px so 1-frame clips stay
+ *  grabbable. */
+export declare function clipChipGeometry(input: {
+    startFrame: number;
+    durationFrames: number;
+    zoom: number;
+}): {
+    left: number;
+    width: number;
+};
+/**
+ * A move drag snaps whichever clip edge lands closest to a snap point: the
+ * start edge directly, or the end edge re-expressed as a start. An unsnapped
+ * candidate passes through unchanged.
+ */
+export declare function chooseMoveSnap(input: {
+    candidateStartFrame: number;
+    durationFrames: number;
+    startSnap: SnapResult;
+    endSnap: SnapResult;
+}): {
+    startFrame: number;
+    point: SnapPoint | null;
+};

package/dist/sequences-react/contracts.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Seams between the timeline editor's engine, media pipeline, and components.
+ * Everything here is interface-only so the three layers build independently
+ * and products can substitute any layer (e.g. a different frame provider)
+ * without forking the editor.
+ *
+ * Persistence model: the command stack executes optimistically against local
+ * timeline state and emits the equivalent `SequenceOperation[]` through
+ * `TimelineEditorProps.onApplyOperations`. A rejected promise rolls the
+ * command back — the server stays the source of truth, the editor stays
+ * responsive.
+ */
+import type { SequenceApplyResult } from '../sequences/apply';
+import type { SequenceClip, SequenceTimeline } from '../sequences/model';
+import type { SequenceOperation } from '../sequences/operations';
+/** One undoable edit. `execute`/`undo` mutate ONLY local editor state; the
+ *  emitted operations are the durable form sent to the product. */
+export interface TimelineCommand {
+    label: string;
+    execute(state: EditorTimelineState): EditorTimelineState;
+    undo(state: EditorTimelineState): EditorTimelineState;
+    /** Durable operations equivalent to `execute` (sent on commit). */
+    operations(): SequenceOperation[];
+    /** Durable operations equivalent to `undo` (sent when the user undoes a
+     *  committed command). */
+    inverseOperations(): SequenceOperation[];
+}
+/** Local editor state — the timeline plus volatile view state the server
+ *  never sees. */
+export interface EditorTimelineState {
+    timeline: SequenceTimeline;
+    playheadFrame: number;
+    selectedClipIds: string[];
+    zoom: number;
+    scrollLeft: number;
+}
+/** Manage and track command execution with undo, redo, state subscription, and timeline reset capabilities */
+export interface CommandStack {
+    execute(command: TimelineCommand): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Subscribe to state changes; returns an unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    getState(): EditorTimelineState;
+    /** Replace timeline state from a server refresh WITHOUT clearing history. */
+    reset(timeline: SequenceTimeline): void;
+}
+/** Exponential zoom mapping so the slider feels linear across a 10x+ range.
+ *  zoom = pixels per frame. */
+export interface ZoomMath {
+    sliderToZoom(slider: number): number;
+    zoomToSlider(zoom: number): number;
+    minZoom: number;
+    maxZoom: number;
+}
+/** Define a point in a timeline where snapping occurs based on frame and kind */
+export interface SnapPoint {
+    frame: number;
+    kind: 'clip-start' | 'clip-end' | 'playhead' | 'sequence-end';
+}
+/** Describe the result of snapping a point to a frame including success status and snapped point details */
+export interface SnapResult {
+    frame: number;
+    snapped: boolean;
+    point: SnapPoint | null;
+}
+/** rAF-driven playback clock. `performance.now()` deltas drive the playhead;
+ *  emits one callback per animation frame while playing. */
+export interface PlaybackClock {
+    play(): void;
+    pause(): void;
+    seek(frame: number): void;
+    isPlaying(): boolean;
+    getFrame(): number;
+    subscribe(listener: (frame: number) => void): () => void;
+    dispose(): void;
+}
+/** Supplies decoded frames for preview rendering. The baseline implementation
+ *  seeks an off-DOM HTMLVideoElement (works everywhere); a WebCodecs
+ *  implementation can replace it behind the same seam. */
+export interface VideoFrameProvider {
+    /** Draw the frame at `sourceSeconds` into `ctx` at the given rect. Resolves
+     *  when the frame is painted; rejects when the media cannot be decoded. */
+    drawFrame(mediaUrl: string, sourceSeconds: number, ctx: CanvasRenderingContext2D, rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): Promise<void>;
+    /** Pre-warm a media URL so the first `drawFrame` doesn't stall. */
+    prefetch(mediaUrl: string): void;
+    dispose(): void;
+}
+/** min/max sample peaks per pixel bucket for waveform rendering. */
+export interface WaveformData {
+    peaks: Float32Array;
+    /** Samples represented per peak pair. */
+    samplesPerBucket: number;
+    durationSeconds: number;
+}
+/** Represent a segment of transcription with text and start and end times in seconds */
+export interface TranscriptionSegment {
+    text: string;
+    startSeconds: number;
+    endSeconds: number;
+}
+/** Whisper-in-a-worker contract. Implementations dynamically import the model
+ *  runtime; `available` is false when the optional peer is not installed. */
+export interface TranscriptionProvider {
+    available: boolean;
+    transcribe(mediaUrl: string, opts?: {
+        language?: string;
+        onProgress?: (fraction: number) => void;
+    }): Promise<TranscriptionSegment[]>;
+}
+/** Overridable copy for the editor's product-facing labels. Every field is
+ *  optional; the editor ships clear defaults (see `DEFAULT_TIMELINE_LABELS`).
+ *  Accessible names (the `*AriaLabel` fields) stay descriptive for screen
+ *  readers; the short visible labels carry the on-screen verb. Products rename
+ *  per their own vocabulary without forking the component. */
+export interface TimelineEditorLabels {
+    /** Visible verb on the split-at-playhead tool. */
+    splitClip?: string;
+    splitClipAriaLabel?: string;
+    /** Visible verb on the add-caption-at-playhead tool. */
+    addCaption?: string;
+    addCaptionAriaLabel?: string;
+    /** Visible verb on the export action (rendered only when `onCreateExport`). */
+    createExport?: string;
+    /** Empty-state heading + the three doors. */
+    emptyTitle?: string;
+    emptyBody?: string;
+    emptyTemplateDoor?: string;
+    emptyClipDoor?: string;
+    emptyAgentDoor?: string;
+    /** Phone gate shown instead of the gesture-heavy editor below `sm`. */
+    smallScreenTitle?: string;
+    smallScreenBody?: string;
+    /** Ghost-lane names shown at rest so time reads as a timeline before any
+     *  track exists. */
+    ghostVideoLane?: string;
+    ghostCaptionLane?: string;
+}
+/** Define properties and callbacks for editing and applying operations on a sequence timeline */
+export interface TimelineEditorProps {
+    timeline: SequenceTimeline;
+    canWrite: boolean;
+    /** Persist operations the user produced. Reject to roll the edit back.
+     *  Resolve with the per-operation `SequenceApplyResult[]` (what
+     *  `applySequenceOperations` returns, index-aligned with `operations`) so
+     *  the editor can reconcile its optimistic `local-…` clip ids to the
+     *  server-minted ids — without it, undoing a committed place/split/caption
+     *  after a timeline refresh emits operations the server cannot resolve.
+     *  Resolving void skips reconciliation. */
+    onApplyOperations(operations: SequenceOperation[]): Promise<SequenceApplyResult[] | void>;
+    /** Selection + playhead surface to the host (e.g. to attach agent context). */
+    onSelectionChange?(clips: SequenceClip[]): void;
+    onPlayheadChange?(frame: number): void;
+    /** Host-rendered side panel (agent chat) and shelf (draggable assets). */
+    renderSidePanel?(ctx: {
+        selectedClips: SequenceClip[];
+        playheadFrame: number;
+    }): React.ReactNode;
+    renderAssetShelf?(): React.ReactNode;
+    /** Frame provider override; omitted → the baseline HTMLVideoElement provider. */
+    frameProvider?: VideoFrameProvider;
+    /** Overridable product-facing copy; defaults are clear on their own. */
+    labels?: TimelineEditorLabels;
+    /** Empty-state doors. Supplying a handler renders that door; omitting it
+     *  hides it. With none supplied the empty state shows guidance only. */
+    onStartFromTemplate?(): void;
+    onAddClip?(): void;
+    onAskAgent?(): void;
+    /** Render the export action (a toolbar "Export…" button). Omitted → no export
+     *  affordance. The handler owns the dialog/flow; this surface only invokes it. */
+    onCreateExport?(): void;
+    /** Off by default. When true AND the consuming product supplies a branded
+     *  export pipeline, the export door/button is marked as Tangle-branded. This
+     *  surface has no render pipeline of its own to brand, so the flag is a
+     *  forward-compatible hint to `onCreateExport`, never a baked watermark. */
+    brandedExport?: boolean;
+    className?: string;
+}
+/** Provide default labels and accessibility text for timeline editor UI elements */
+export declare const DEFAULT_TIMELINE_LABELS: Required<TimelineEditorLabels>;

package/dist/sequences-react/engine/command-stack.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Undo/redo command stack over immutable `EditorTimelineState`.
+ *
+ * Invariant that makes `reset()` safe: history entries hold COMMANDS — each a
+ * pair of state transforms plus the durable operations captured at
+ * construction — never state snapshots. Rebasing the timeline from a server
+ * refresh therefore cannot stale the history: a later undo re-applies the
+ * command's inverse transform to whatever timeline is current. If a rebase
+ * removed a clip a historical command targets, that command's transform throws
+ * (fail loud) rather than silently editing the wrong clip — the host decides
+ * whether to drop history at that point.
+ */
+import type { SequenceTimeline } from '../../sequences/model';
+import type { CommandStack } from '../contracts';
+/** Oldest entries are dropped past this bound; redo is cleared on execute. */
+export declare const COMMAND_HISTORY_LIMIT = 200;
+/** Create a command stack managing undo and redo operations for a given timeline */
+export declare function createCommandStack(initial: SequenceTimeline): CommandStack;

package/dist/sequences-react/engine/commands.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Concrete `TimelineCommand` factories. Every factory captures the inverse
+ * from PRE-state at construction — undo is a value computed once, never a
+ * re-derivation from whatever state exists later. Local execute/undo update
+ * `EditorTimelineState` immutably; `operations()`/`inverseOperations()` return
+ * the durable `SequenceOperation[]` equivalent, built per call from captured
+ * primitives so callers can never alias command internals.
+ *
+ * Id boundary: `place_clip`, `add_caption`, and `split_clip` mint clip ids
+ * server-side, so factories that create local clips take a caller-minted id.
+ * Every factory also takes an optional `resolveClipId` — a LIVE local→server
+ * alias lookup the host feeds from `onApplyOperations` results. Resolution
+ * runs at execute/undo/emission time (never at construction), so a command
+ * captured against an optimistic `local-…` id keeps working after a server
+ * refresh replaced it with the minted id. Residual boundary: clips a durable
+ * undo recreates (e.g. the `place_clip` inverse of a delete) mint FRESH
+ * server ids that only the next refresh reconciles.
+ *
+ * Transforms re-resolve their target clip at execute/undo time and throw when
+ * it no longer exists (e.g. removed by a `reset()` rebase) — editing a wrong
+ * or absent clip silently would corrupt the durable op stream.
+ */
+import { type SequenceTimeline } from '../../sequences/model';
+import type { TimelineCommand } from '../contracts';
+/** Live local→server clip-id lookup (see module header). Must return its
+ *  argument when no alias exists. */
+export type ClipIdResolver = (clipId: string) => string;
+/** Define input parameters to move a clip within a timeline including optional track and resolver */
+export interface MoveClipInput {
+    timeline: SequenceTimeline;
+    clipId: string;
+    startFrame: number;
+    /** Omitted → stays on its current track. */
+    trackId?: string;
+    resolveClipId?: ClipIdResolver;
+}
+/** Drag-move. The target start clamps through the model's `clampClipStart`
+ *  so drags past either edge land at the boundary instead of throwing
+ *  mid-gesture; the emitted operation carries the clamped value. */
+export declare function moveClipCommand(input: MoveClipInput): TimelineCommand;
+/** Define input parameters for trimming a clip within a sequence timeline */
+export interface TrimClipInput {
+    timeline: SequenceTimeline;
+    clipId: string;
+    startFrame: number;
+    durationFrames: number;
+    /** New source in-point when trimming the head; omitted → unchanged. */
+    sourceInFrame?: number;
+    resolveClipId?: ClipIdResolver;
+}
+/** Trim is strict where move is forgiving: the caller (a trim handle) already
+ *  knows both edges, so out-of-bounds input is a bug, not a gesture. */
+export declare function trimClipCommand(input: TrimClipInput): TimelineCommand;
+/** Define input parameters required to place a clip within a sequence timeline */
+export interface PlaceClipInput {
+    timeline: SequenceTimeline;
+    /** Caller-minted optimistic id for the local clip (see module header). */
+    clipId: string;
+    trackId: string;
+    label: string;
+    startFrame: number;
+    durationFrames: number;
+    /** Omitted → 0 (start of the source). */
+    sourceInFrame?: number;
+    media?: {
+        url: string;
+        kind: 'video' | 'image' | 'audio';
+    };
+    generationId?: string;
+    assetId?: string;
+    metadata?: Record<string, unknown>;
+    resolveClipId?: ClipIdResolver;
+}
+/** Resolve and validate clip placement parameters to create a timeline command */
+export declare function placeClipCommand(input: PlaceClipInput): TimelineCommand;
+/** Define input parameters required to delete a clip from a sequence timeline */
+export interface DeleteClipInput {
+    timeline: SequenceTimeline;
+    clipId: string;
+    resolveClipId?: ClipIdResolver;
+}
+/** Snapshots the full clip at construction so undo restores it exactly. The
+ *  durable inverse rebuilds within the closed operation union: caption clips
+ *  (caption track + text) invert through `add_caption` — `place_clip` cannot
+ *  carry text/language — everything else through `place_clip` with media,
+ *  product references, source window, and disabled state intact. Boundary:
+ *  the caption path cannot carry `disabled` or `metadata`, so a deleted
+ *  disabled caption resurrects ENABLED server-side and caption metadata is
+ *  lost — local undo stays exact (same class of loss as the `set_clip_text`
+ *  language-clear boundary). */
+export declare function deleteClipCommand(input: DeleteClipInput): TimelineCommand;
+/** Define input parameters for splitting a clip at a specific frame within a timeline */
+export interface SplitClipInput {
+    timeline: SequenceTimeline;
+    clipId: string;
+    /** Sequence-frame to cut at; must fall strictly inside the clip. */
+    atFrame: number;
+    /** Caller-minted id for the second (tail) clip. */
+    newClipId: string;
+    resolveClipId?: ClipIdResolver;
+}
+/** Source mapping is 1:1 frames (no rate ramps in the model), so the tail's
+ *  source in-point is the head's in-point advanced by the head duration. */
+export declare function splitClipCommand(input: SplitClipInput): TimelineCommand;
+/** Define input parameters for adding a caption clip to a sequence timeline */
+export interface AddCaptionInput {
+    timeline: SequenceTimeline;
+    /** Caller-minted optimistic id for the local caption clip. */
+    clipId: string;
+    /** Editor commands are concrete: the caller resolves placement (e.g. via
+     *  `chooseCaptionPlacement`) and the target track before constructing. */
+    trackId: string;
+    text: string;
+    language?: string;
+    startFrame: number;
+    durationFrames: number;
+    resolveClipId?: ClipIdResolver;
+}
+/** Resolve a command to add a caption to a specified caption track within a timeline */
+export declare function addCaptionCommand(input: AddCaptionInput): TimelineCommand;
+/** Define input parameters for setting text and optional language on a specific clip in a timeline */
+export interface SetClipTextInput {
+    timeline: SequenceTimeline;
+    clipId: string;
+    text: string;
+    /** Omitted → language unchanged. */
+    language?: string;
+    resolveClipId?: ClipIdResolver;
+}
+/** Requires the clip to already carry text: `set_clip_text` has no "create"
+ *  semantics in the union, and an inverse for a text-less clip would have to
+ *  invent an empty string. Boundary: when the clip had NO language and this
+ *  command sets one, local undo restores `undefined` exactly but the durable
+ *  inverse cannot clear language (the op has no clear form) — flagged to the
+ *  apply layer. */
+export declare function setClipTextCommand(input: SetClipTextInput): TimelineCommand;
+/** Define input parameters to toggle the disabled state of a clip within a timeline */
+export interface ToggleClipDisabledInput {
+    timeline: SequenceTimeline;
+    clipId: string;
+    resolveClipId?: ClipIdResolver;
+}
+/** The target value is captured at construction (not flipped at execute time)
+ *  so redo after a rebase applies the same durable op the stack already
+ *  emitted. */
+export declare function toggleClipDisabledCommand(input: ToggleClipDisabledInput): TimelineCommand;

package/dist/sequences-react/engine/playback.d.ts

@@ -0,0 +1,18 @@
+/**
+ * rAF playback clock. The playhead is derived from a (start time, start
+ * frame) anchor and `performance.now()` deltas — never from per-tick
+ * increments — so dropped animation frames cannot accumulate drift.
+ *
+ * Browser-only at PLAY time, import-safe everywhere: `requestAnimationFrame`
+ * and `performance` are resolved off `globalThis` when playback starts, never
+ * at module load or construction, so server bundles that import the editor
+ * engine do not crash.
+ */
+import type { PlaybackClock } from '../contracts';
+/** Define configuration settings for playback clock including frames per second and total duration frames */
+export interface PlaybackClockConfig {
+    fps: number;
+    durationFrames: number;
+}
+/** Create a playback clock that manages frame timing and playback state based on configuration */
+export declare function createPlaybackClock(config: PlaybackClockConfig): PlaybackClock;

package/dist/sequences-react/engine/snap.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Drag snapping. Snap points come from the timeline's structure (clip edges,
+ * playhead, sequence end); the snap THRESHOLD is measured in screen pixels at
+ * the current zoom — what feels "close" is a screen distance, not a frame
+ * count — and converts to frames as thresholdPx / zoom.
+ */
+import type { SequenceTimeline } from '../../sequences/model';
+import type { SnapPoint, SnapResult } from '../contracts';
+/** Snap point with its owning clip when it came from one, so a drag can
+ *  exclude the dragged clip's own edges. Structurally a `SnapPoint`. */
+export interface TimelineSnapPoint extends SnapPoint {
+    clipId?: string;
+}
+/** Disabled clips still occupy timeline space visually, so their edges remain
+ *  snap targets. */
+export declare function collectSnapPoints(timeline: SequenceTimeline, playheadFrame: number): TimelineSnapPoint[];
+/** Define options to configure snapping behavior including zoom, threshold, and exclusion criteria */
+export interface ApplySnapOptions {
+    /** Pixels per frame — converts the pixel threshold into frames. */
+    zoom: number;
+    /** Screen-distance threshold; 10px matches the editor's hit-slop. */
+    thresholdPx?: number;
+    /** Return true to remove a point from consideration (e.g. the dragged
+     *  clip's own edges via `TimelineSnapPoint.clipId`). */
+    exclude?: (point: SnapPoint) => boolean;
+}
+/** Nearest candidate wins; ties keep the first candidate in `points` order
+ *  (sorted by frame from `collectSnapPoints`, so the lower frame). */
+export declare function applySnap(frame: number, points: SnapPoint[], opts: ApplySnapOptions): SnapResult;

package/dist/sequences-react/engine/zoom.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Zoom + viewport coordinate math. Zoom is PIXELS PER FRAME; the slider is a
+ * normalized [0, 1] control mapped exponentially (zoom = min·(max/min)^slider)
+ * so each slider step multiplies the scale by a constant factor — linear
+ * slider feel across a 10x+ range.
+ */
+import type { ZoomMath } from '../contracts';
+/** Define configuration settings for minimum and maximum zoom levels */
+export interface ZoomMathConfig {
+    minZoom: number;
+    maxZoom: number;
+}
+/** Create a ZoomMath object that validates config and calculates zoom ratio within bounds */
+export declare function createZoomMath(config: ZoomMathConfig): ZoomMath;
+/** Horizontal viewport: zoom in pixels per frame, scrollLeft in pixels. */
+export interface ViewportTransform {
+    zoom: number;
+    scrollLeft: number;
+}
+/** Frame → viewport-relative pixel x. Output is fractional; round through
+ *  `snapPixel` before drawing. */
+export declare function frameToPixel(frame: number, view: ViewportTransform): number;
+/** Viewport-relative pixel x → integer frame. Frames are integer positions,
+ *  so the result rounds to the nearest frame and floors at 0 (a pointer left
+ *  of frame 0 resolves to 0). */
+export declare function pixelToFrame(pixel: number, view: ViewportTransform): number;
+/** Snap a CSS-pixel value to the device pixel grid so 1px timeline rules
+ *  render crisp on fractional-DPR displays. */
+export declare function snapPixel(value: number, devicePixelRatio: number): number;