@codingfactory/mediables-vue 2.9.2 → 2.10.0

package/dist/types/mediaLibraryPicker.d.ts

@@ -125,6 +125,55 @@ export interface MediaLibraryPickerLabels {
     albumUnavailableTitle?: string;
     albumUnavailableBody?: string;
     goToLibrary?: string;
+    /**
+     * Tab label for the "all media" view inside the picker. Hosts can override
+     * to e.g. "Saved Media" or "Saved uploads" to match brand vocabulary.
+     * BUG-008-CR3-R13-009-A.
+     */
+    allMediaTab?: string;
+    /**
+     * Loading copy shown inside the media grid before the first page resolves.
+     */
+    loadingMedia?: string;
+    /**
+     * Label for the bottom "load more" button when more results are available.
+     */
+    loadMore?: string;
+    /**
+     * Label rendered while the load-more button is fetching the next page.
+     */
+    loadingMore?: string;
+    /**
+     * Visible label inside the upload dropzone. Defaults to
+     * "Drop files here or browse".
+     */
+    uploadDropzone?: string;
+    /**
+     * Optional helper text under the upload dropzone explaining accepted file
+     * types. Hosts that know their accept rule should pass concrete copy.
+     */
+    uploadDropzoneHelper?: string;
+    /**
+     * Label for the upload sheet's "Done" close button.
+     */
+    uploadDone?: string;
+    /**
+     * aria-label for the upload sheet's close button.
+     */
+    uploadDoneAria?: string;
+    /**
+     * Visually-hidden label tied to the upload file input for screen readers.
+     */
+    uploadFileInputLabel?: string;
+    /**
+     * Preview-sheet labels — exposed here so the picker can pass them down to
+     * MediaPreviewSheet without each host wiring slot overrides.
+     */
+    previewClose?: string;
+    previewPrevious?: string;
+    previewNext?: string;
+    previewSelect?: string;
+    previewDeselect?: string;
 }
 export interface MediaLibraryPickerProps {
     deps: MediaLibraryPickerDeps;
@@ -181,3 +230,73 @@ export interface MediaLibraryPickerSlots {
         media: Media;
     }) => VNode[];
 }
+/**
+ * Scoped slot payloads exposed by Liquid Glass host components in this
+ * package. Hosts (e.g., blowglass) bind these slots to branded primitives
+ * such as `GlassNavigationTabs`, `GlassSearchInput`, and `GlassBadge`. The
+ * default rendering remains in place when a slot is not provided so that
+ * non-Blowglass consumers see no change.
+ *
+ * BUG-008-CR3-R13-008-A: Named-slot host-component contract.
+ */
+/** Identifier for the picker tab the user is currently viewing. */
+export type MediaLibraryPickerTabId = 'upload' | 'media' | 'albums';
+/** Identifier for the management-view tab the user is currently viewing. */
+export type MediaManagementTabId = 'library' | 'trash';
+/**
+ * Payload for the picker `tabs` slot. Hosts get the active tab id, an
+ * activate handler, and the resolved labels so they can render any tab
+ * primitive that takes `{ id, label, onChange }`.
+ */
+export interface MediaLibraryPickerTabsSlotProps {
+    activeTab: MediaLibraryPickerTabId;
+    setActiveTab: (tabId: MediaLibraryPickerTabId) => void;
+    enableUpload: boolean;
+    labels: {
+        uploadLabel: string;
+        allMediaTab: string;
+        browseAlbums: string;
+    };
+}
+/** Payload for the picker `search` slot. */
+export interface MediaLibraryPickerSearchSlotProps {
+    query: string;
+    setQuery: (next: string) => void;
+    placeholder: string;
+}
+/** Payload for the management-view `tabs` slot. */
+export interface MediaManagementTabsSlotProps {
+    activeTab: MediaManagementTabId;
+    setActiveTab: (tabId: MediaManagementTabId) => void;
+    trashCount: number;
+    showTrash: boolean;
+    labels: {
+        libraryTab: string;
+        trashTab: string;
+    };
+}
+/** Payload for the management-view `bulk-actions` slot. */
+export interface MediaManagementBulkActionsSlotProps {
+    selectedCount: number;
+    isDeleting: boolean;
+    onBulkDelete: () => void | Promise<void>;
+    labels: {
+        deleteButton: string;
+        selectedCount: (count: number) => string;
+    };
+}
+/**
+ * Payload for the management-view `trash-action` slot. Rendered per-row
+ * inside the trash grid. Hosts can replace the default Restore button with
+ * a branded affordance while keeping per-item gating logic in the package.
+ */
+export interface MediaManagementTrashActionSlotProps {
+    media: Media;
+    canRestore: boolean;
+    isRestoring: boolean;
+    onRestore: () => void | Promise<void>;
+    labels: {
+        restoreButton: string;
+        restoreUnavailable: string;
+    };
+}

package/dist/video/project/assetBlobCache.d.ts

@@ -0,0 +1,41 @@
+/**
+ * IndexedDB-backed cache for not-yet-uploaded asset blobs — see plan §7.B.
+ *
+ * Drafts must never serialize `File` or `blob:` URLs as durable state. When
+ * the user picks a file, we stash the binary in IndexedDB keyed by the
+ * client-side `assetId`. If the page reloads before the upload finishes, the
+ * draft restoration code can re-mint a fresh `blob:` URL from the cached
+ * binary so the editor still has something to play.
+ *
+ * Once the upload transitions to 'ready', the cache entry is dropped — the
+ * server is the source of truth from that point on.
+ *
+ * The interface intentionally mirrors `idb-keyval`'s shape so the runtime
+ * can swap the underlying store without touching call sites.
+ */
+/**
+ * Asset-blob cache backed by IndexedDB. The class is fully async; throw / reject
+ * paths bubble up so the caller can decide whether to fall back to a plain
+ * object-URL for the in-memory session.
+ */
+export declare class AssetBlobCache {
+    private dbPromise;
+    private openDb;
+    put(assetId: string, blob: Blob): Promise<void>;
+    get(assetId: string): Promise<Blob | null>;
+    delete(assetId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare function getSharedAssetBlobCache(): AssetBlobCache;
+/**
+ * Best-effort wrapper that falls back to in-memory storage when IndexedDB is
+ * unavailable (Safari private browsing, certain WebViews). The fallback only
+ * survives the current session.
+ */
+export declare class InMemoryAssetBlobCache {
+    private readonly store;
+    put(assetId: string, blob: Blob): Promise<void>;
+    get(assetId: string): Promise<Blob | null>;
+    delete(assetId: string): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/video/project/assetLifecycle.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Asset lifecycle types and contracts — see plan §7.B and P0-1.
+ *
+ * Every imported asset moves through explicit states. The renderer never
+ * reads `File` objects or `blob:` URLs from durable state; it only consumes
+ * `assetId` references that resolve to a backend-owned media URL once the
+ * upload completes.
+ *
+ * The composable exposes a `MediaAssetUploader` interface so the host
+ * application (blowglass) can supply a real Laravel-backed implementation
+ * while tests use a mock. Splitting the interface from the composable keeps
+ * the package agnostic to the backend shape — a critical boundary requirement
+ * from the package's CLAUDE.md.
+ */
+export type AssetUploadStatus = 'local-selected' | 'uploading' | 'processing' | 'ready' | 'failed' | 'missing' | 'unauthorized';
+export interface AssetLifecycleRecord {
+    /** Stable client-side id assigned at selection time, kept across the lifecycle. */
+    assetId: string;
+    /** Optional server-side identifier once the upload resolves. */
+    mediaUuid?: string;
+    /** Backend playback URL once status transitions to 'ready'. */
+    mediaUrl?: string;
+    /** Original filename of the imported asset, for display. */
+    filename: string;
+    /** MIME type sniffed by the upload pipeline. */
+    mime: string;
+    /** Size in bytes; unknown for streaming sources. */
+    sizeBytes?: number;
+    /** Duration in seconds; populated as soon as the browser can decode metadata. */
+    durationSeconds?: number;
+    /** Pixel width for video / image; undefined for audio. */
+    width?: number;
+    /** Pixel height for video / image; undefined for audio. */
+    height?: number;
+    /** Optional checksum so reloaded drafts can detect drift. */
+    checksum?: string;
+    /** Current lifecycle state. */
+    status: AssetUploadStatus;
+    /** Upload progress, 0-1, while status === 'uploading'. */
+    uploadProgress?: number;
+    /** User-facing failure message when status === 'failed'. */
+    failureMessage?: string;
+}
+export interface MediaAssetSelection {
+    file: File;
+    /** Optional preview URL hint; the uploader is free to mint its own. */
+    previewUrl?: string;
+}
+export interface MediaAssetUploadProgress {
+    assetId: string;
+    progress: number;
+    status: AssetUploadStatus;
+}
+/**
+ * Host-supplied uploader. blowglass plugs in a Laravel-backed implementation
+ * that posts to /api/v1/video/assets; tests can supply a mock. The interface
+ * is intentionally narrow.
+ */
+export interface MediaAssetUploader {
+    /**
+     * Upload a freshly selected asset. Returns a record that starts in either
+     * 'uploading' or 'ready' (for backends that finalize synchronously).
+     *
+     * Implementations MUST call `onProgress` at least once with the final state
+     * (`'ready'` or `'failed'`).
+     */
+    upload(selection: MediaAssetSelection, onProgress?: (event: MediaAssetUploadProgress) => void): Promise<AssetLifecycleRecord>;
+    /**
+     * Re-fetch the lifecycle record for an asset by its backend `mediaUuid`.
+     * Used by draft recovery to confirm an asset still exists and is owned by
+     * the current user.
+     */
+    resolve(mediaUuid: string): Promise<AssetLifecycleRecord | null>;
+}
+/** Maximum file size accepted at the frontend preflight. 2 GiB. */
+export declare const ASSET_MAX_BYTES: number;
+/** Maximum video / audio duration accepted, in seconds. 1 hour. */
+export declare const ASSET_MAX_DURATION: number;
+export type AssetPreflightFailure = 'unsupported_mime' | 'oversize' | 'duration_exceeded';
+export interface AssetPreflightResult {
+    ok: true;
+    kind: 'video' | 'image' | 'audio';
+}
+export interface AssetPreflightFailureResult {
+    ok: false;
+    reason: AssetPreflightFailure;
+    message: string;
+}
+export type AssetPreflightOutcome = AssetPreflightResult | AssetPreflightFailureResult;
+/**
+ * Frontend preflight before any upload starts. Backend-side enforcement is
+ * still required (MIME sniffing + per-user quota live there); this just
+ * catches the common rejections before they touch the network.
+ */
+export declare function preflightAsset(file: File, durationSeconds?: number): AssetPreflightOutcome;

package/dist/video/project/editorCommandResult.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Editor command result contract — see plan §7.C.
+ *
+ * Every mutation in `useVideoEditor` returns this shape. `VideoEditorV2`
+ * consumes it and surfaces failure reasons through a single accessible live
+ * region. Callers should never branch on a bare boolean.
+ */
+export type EditorCommandFailureReason = 'last_clip' | 'no_selection' | 'track_locked' | 'track_missing' | 'track_type_mismatch' | 'overlap' | 'asset_not_ready' | 'invariant_violation' | 'source_not_found' | 'source_in_use';
+export interface EditorCommandFailure {
+    ok: false;
+    reason: EditorCommandFailureReason;
+    message: string;
+}
+export interface EditorCommandSuccess<T> {
+    ok: true;
+    value: T;
+}
+export type EditorCommandResult<T = void> = EditorCommandSuccess<T> | EditorCommandFailure;
+export declare function commandOk(): EditorCommandSuccess<void>;
+export declare function commandOk<T>(value: T): EditorCommandSuccess<T>;
+export declare function commandFail(reason: EditorCommandFailureReason, message: string): EditorCommandFailure;
+/**
+ * Default user-facing message for a failure reason. Caller can override.
+ */
+export declare function defaultMessageFor(reason: EditorCommandFailureReason): string;

package/dist/video/project/projectDraftStore.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Server-backed project draft client — see plan §7 P0-7.
+ *
+ * The package exposes a `ProjectDraftStore` interface and a default
+ * `RestProjectDraftStore` implementation that hits a JSON endpoint with the
+ * canonical contract:
+ *
+ *   GET    /api/v1/video/projects/:projectId/drafts/latest
+ *          → { draft: ProjectDraftEnvelope } | { draft: null }
+ *
+ *   PUT    /api/v1/video/projects/:projectId/drafts
+ *          { recipe, version, sessionId }
+ *          → 201 { draft: ProjectDraftEnvelope }
+ *          → 409 { conflict: ProjectDraftEnvelope }    when versions diverge
+ *
+ *   GET    /api/v1/video/projects/:projectId/drafts/recent
+ *          → { drafts: ProjectDraftEnvelope[] }
+ *
+ * Hosts that don't ship the backend yet can plug in `InMemoryProjectDraftStore`
+ * for local-only operation. Tests use the in-memory store directly.
+ *
+ * Multi-tab coordination uses BroadcastChannel: the active tab announces
+ * `{ type: 'draft-saved', projectId, version }` after each successful save,
+ * and other tabs editing the same project show a "Newer version available"
+ * banner. When BroadcastChannel is unavailable (older Safari), the conflict
+ * is still detected on the next save attempt via the 409 response.
+ */
+import type { VideoRecipe } from '../../types/video';
+export interface ProjectDraftEnvelope {
+    projectId: string;
+    version: number;
+    recipe: VideoRecipe;
+    /** ISO 8601 timestamp the server stored the draft. */
+    savedAt: string;
+    /** Identifier of the editor session that wrote this draft. */
+    sessionId: string;
+}
+export interface SaveDraftRequest {
+    recipe: VideoRecipe;
+    /** Last known server version; the request is rejected if the server is ahead. */
+    baseVersion: number | null;
+    sessionId: string;
+}
+export type SaveDraftResult = {
+    ok: true;
+    draft: ProjectDraftEnvelope;
+} | {
+    ok: false;
+    reason: 'conflict';
+    remote: ProjectDraftEnvelope;
+} | {
+    ok: false;
+    reason: 'unauthorized' | 'network' | 'unknown';
+    message: string;
+};
+export interface ProjectDraftStore {
+    /** Load the most recent draft for a project, or `null` if none exists. */
+    loadLatest(projectId: string): Promise<ProjectDraftEnvelope | null>;
+    /** Save a new draft. Returns conflict when the server version is ahead. */
+    save(projectId: string, request: SaveDraftRequest): Promise<SaveDraftResult>;
+    /** List the recent draft envelopes for the project (server-side rotation). */
+    listRecent?(projectId: string): Promise<ProjectDraftEnvelope[]>;
+}
+/**
+ * Convenience id generator for editor sessions. Stable across saves within a
+ * single tab; new tab opens get a fresh id.
+ */
+export declare function generateSessionId(): string;
+/**
+ * In-memory store, primarily for tests and for hosts that haven't shipped
+ * the backend yet. Persists to a Map keyed by projectId.
+ */
+export declare class InMemoryProjectDraftStore implements ProjectDraftStore {
+    private readonly latest;
+    private readonly history;
+    loadLatest(projectId: string): Promise<ProjectDraftEnvelope | null>;
+    save(projectId: string, request: SaveDraftRequest): Promise<SaveDraftResult>;
+    listRecent(projectId: string): Promise<ProjectDraftEnvelope[]>;
+}
+/**
+ * Lightweight REST client. Adapts `fetch` to the contract documented above.
+ * Hosts can subclass or wrap this to add CSRF tokens, retries, etc.
+ */
+export declare class RestProjectDraftStore implements ProjectDraftStore {
+    private readonly baseUrl;
+    private readonly fetcher;
+    constructor(baseUrl: string, fetcher?: typeof fetch);
+    loadLatest(projectId: string): Promise<ProjectDraftEnvelope | null>;
+    save(projectId: string, request: SaveDraftRequest): Promise<SaveDraftResult>;
+    listRecent(projectId: string): Promise<ProjectDraftEnvelope[]>;
+}

package/dist/video/project/sourceUsage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Single source-of-truth for "which media sources is this project actually
+ * using right now?" — see plan §7 P1-11.
+ *
+ * Used by:
+ *  - removeMediaSource → block deletion when in-use
+ *  - export validators → confirm every referenced source resolves
+ *  - draft serializer → optionally prune orphaned sources
+ *
+ * The function intentionally checks every place a TimelineClipSource id can be
+ * referenced, not just `state.clips`. As soon as graphics layers, text layers,
+ * or future visual layers also gain `sourceRefId`, add them here and every
+ * caller stays correct.
+ */
+import type { TimelineClip } from '../../types/video';
+export interface SourceUsageInput {
+    clips: readonly TimelineClip[];
+}
+export declare function collectReferencedSourceIds(input: SourceUsageInput): ReadonlySet<string>;
+export declare function isSourceInUse(input: SourceUsageInput, sourceId: string): boolean;

package/dist/video/project/timelineCollision.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Timeline collision resolver — see plan §7 P0-6.
+ *
+ * Shared by `duplicateSelectedClip`, `appendMediaSourceToTimeline`, and the
+ * cross-track drag path. Finds a non-overlapping insertion slot for a clip on
+ * a given track, or reports that none exists.
+ *
+ * All time values are seconds.
+ */
+import type { TimelineClip } from '../../types/video';
+export interface InsertionSlotInput {
+    /** Clips currently on the target track, in any order. */
+    trackClips: readonly TimelineClip[];
+    /** Duration the new clip will occupy on the timeline, in seconds. */
+    desiredDuration: number;
+    /** Preferred start time (e.g. playhead, or the existing clip's end). */
+    preferredStart: number;
+    /**
+     * Clip id to ignore in the collision check, e.g. when the moving clip is
+     * already on the track and we want to skip it during slot search.
+     */
+    ignoreClipId?: string;
+}
+export interface InsertionSlotFound {
+    ok: true;
+    start: number;
+}
+export interface InsertionSlotMissing {
+    ok: false;
+}
+export type InsertionSlotResult = InsertionSlotFound | InsertionSlotMissing;
+/**
+ * Find a non-overlapping insertion slot on a track.
+ *
+ * Strategy:
+ * 1. If the preferred start fits, use it.
+ * 2. Otherwise, find the next gap large enough at or after the preferred start.
+ * 3. If the track is "full" up to the preferred area, append after the last clip.
+ * 4. If `desiredDuration` is non-positive, return `{ ok: false }`.
+ */
+export declare function findInsertionSlot(input: InsertionSlotInput): InsertionSlotResult;

package/dist/video/project/trackCompatibility.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Track / clip type compatibility matrix — see plan §7.E.
+ *
+ * Used by cross-track drag, AssetRail "add to track", and programmatic
+ * `appendMediaSourceToTimeline` to decide whether a clip is a legal payload
+ * for a given track.
+ */
+import type { TimelineClipKind, TimelineTrackType } from '../../types/video';
+export declare function isClipKindAllowedOnTrack(clipKind: TimelineClipKind, trackType: TimelineTrackType): boolean;
+export declare function allowedClipKindsForTrack(trackType: TimelineTrackType): readonly TimelineClipKind[];
+/**
+ * Z-order semantics — see plan §7.F.
+ * Higher `track.order` = visually higher in the stacking sequence.
+ * This constant is the documented default; renderers must read it.
+ */
+export declare const TRACK_Z_ORDER_HIGHER_IS_TOP: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codingfactory/mediables-vue",
-  "version": "2.9.2",
+  "version": "2.10.0",
   "publishConfig": {
     "access": "restricted"
   },