@wyxos/vibe 5.16.8 → 5.17.0

package/README.md

@@ -5,6 +5,8 @@ Vibe is an initializable Vue 3 media feed with virtualized masonry and reel layo
 Try the [live demo](https://vibe.wyxos.com/) to explore the feed and its controls.
 Read the [full documentation](./docs/index.md) for guided setup, layout and data-loading concepts, and the API reference.
 
+For an existing host-owned player and large queue, use the [host-controlled reel](./docs/reference/controlled-reel.md) with a bounded previous/current/next projection and stable media slot.
+
 [![Vibe demo: scroll a masonry feed, open a card in the reel, and press Escape to return to the same scroll position.](https://raw.githubusercontent.com/wyxos/vibe/master/docs/assets/vibe-demo.gif)](https://vibe.wyxos.com/)
 
 The preview uses synthetic sample media. Open a masonry card to view it in a reel,

package/lib/components/CardRegion.vue.d.ts

@@ -3,7 +3,7 @@ type __VLS_Props = {
     index: number;
     item: VibeItem;
     layout: VibeLayout;
-    loadedCount: number | (() => number);
+    loadedCount: number;
     mediaIndex: number;
     mediaSource?: VibeMediaSource;
     placement: 'footer' | 'header';

package/lib/components/MediaCard.vue.d.ts

@@ -16,7 +16,7 @@ type __VLS_Props = {
     interactive?: boolean;
     leaving?: boolean;
     layout: VibeLayout;
-    loadedCount: number | (() => number);
+    loadedCount: number;
     mediaIndex: number;
     mediaCard?: VibeMediaCardOptions;
     mediaSource?: VibeMediaSource;

package/lib/components/VibeControlledReel.vue.d.ts

@@ -0,0 +1,24 @@
+import type { VibeControlledReelDirection, VibeControlledReelProps, VibeControlledReelSlotProps } from '../core/controlledReel';
+type __VLS_Slots = {
+    default(props: VibeControlledReelSlotProps): unknown;
+    previous?(props: VibeControlledReelSlotProps): unknown;
+    next?(props: VibeControlledReelSlotProps): unknown;
+};
+declare function navigate(direction: VibeControlledReelDirection): Promise<void>;
+declare const __VLS_base: import("vue").DefineComponent<VibeControlledReelProps, {
+    navigate: typeof navigate;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    navigationError: (error: unknown) => any;
+}, string, import("vue").PublicProps, Readonly<VibeControlledReelProps> & Readonly<{
+    onNavigationError?: ((error: unknown) => any) | undefined;
+}>, {
+    label: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/lib/components/mediaPlaybackDiagnostic.d.ts

@@ -0,0 +1,4 @@
+type PlaybackAction = 'load-requested' | 'play-requested' | 'play-resolved' | 'play-rejected';
+/** Numeric/media evidence belongs to the consumer; this event exposes fixed lifecycle categories only. */
+export declare function emitMediaPlaybackDiagnostic(media: HTMLMediaElement, action: PlaybackAction, error?: unknown): void;
+export {};

package/lib/components/useMediaLifecycle.d.ts

@@ -17,9 +17,9 @@ export declare function useMediaLifecycle(state: VibeRuntimeState, events: Media
     markPreviewReady: (postId: VibeItemId, mediaIndex: number) => void;
     markReelError: (postId: VibeItemId, mediaIndex: number) => void;
     markReelReady: (postId: VibeItemId, mediaIndex: number) => void;
-    originalStates: import("vue").ShallowRef<import("vue").ShallowReactive<Map<string, MediaPreviewState>>, import("vue").ShallowReactive<Map<string, MediaPreviewState>>>;
-    previewStates: import("vue").ShallowRef<import("vue").ShallowReactive<Map<string, MediaPreviewState>>, import("vue").ShallowReactive<Map<string, MediaPreviewState>>>;
-    reelStates: import("vue").ComputedRef<import("vue").ShallowReactive<Map<string, MediaPreviewState>>>;
+    originalStates: import("vue").ShallowRef<ReadonlyMap<string, MediaPreviewState>, ReadonlyMap<string, MediaPreviewState>>;
+    previewStates: import("vue").ShallowRef<ReadonlyMap<string, MediaPreviewState>, ReadonlyMap<string, MediaPreviewState>>;
+    reelStates: import("vue").ComputedRef<ReadonlyMap<string, MediaPreviewState>>;
     resetMediaLifecycle: () => void;
 };
 export {};

package/lib/components/useMediaLoading.d.ts

@@ -7,6 +7,7 @@ interface MediaLoadingOptions {
     mediaSource: () => string;
     mediaType: () => VibeMediaType | undefined;
     mediaElement: ShallowRef<HTMLMediaElement | null>;
+    playbackAllowed: () => boolean;
 }
 export declare function useMediaLoading(options: MediaLoadingOptions): {
     imageLoading: import("vue").ComputedRef<"lazy" | "eager">;

package/lib/core/controlledReel.d.ts

@@ -0,0 +1,41 @@
+import type { VibeItemId } from '../types';
+export type VibeControlledReelDirection = 'next' | 'previous';
+export interface VibeControlledReelItem {
+    id: VibeItemId;
+    artwork?: string;
+    label?: string;
+}
+/** A bounded projection of a host-owned queue. No full queue is required. */
+export interface VibeControlledReelState {
+    /** Change whenever source, order, membership or selection invalidates navigation. */
+    revision: string | number;
+    current: VibeControlledReelItem | null;
+    previous?: VibeControlledReelItem | null;
+    next?: VibeControlledReelItem | null;
+    canPrevious: boolean;
+    canNext: boolean;
+    /** Zero-based position, when known. */
+    position?: number;
+    total?: number;
+}
+export interface VibeControlledReelRequest {
+    direction: VibeControlledReelDirection;
+    snapshot: Readonly<VibeControlledReelState>;
+    signal: AbortSignal;
+}
+export interface VibeControlledReelProps {
+    state: VibeControlledReelState;
+    /** Commit through the host queue, then push state. false declines the intent. */
+    onNavigate: (request: VibeControlledReelRequest) => boolean | void | Promise<boolean | void>;
+    label?: string;
+}
+export interface VibeControlledReelSlotProps {
+    item: VibeControlledReelItem | null;
+    pending: boolean;
+}
+export interface VibeControlledReelExpose {
+    /** The pushed host state, rather than this promise, acknowledges selection. */
+    navigate: (direction: VibeControlledReelDirection) => Promise<void>;
+}
+/** Settle on abort even if an obsolete host callback ignores its signal. */
+export declare function waitForControlledReelNavigation(navigate: VibeControlledReelProps['onNavigate'], context: VibeControlledReelRequest): Promise<boolean | void>;

package/lib/core/fill.d.ts

@@ -21,7 +21,6 @@ interface CollectFrontendFillOptions {
     initialCursor: VibeCursor;
     loadPage: VibePageLoader;
     onCollection?: (collection: FrontendFillCollection) => void;
-    onPage?: (collection: FrontendFillCollection) => void;
     onDelayChange: (snapshot: RequestDelaySnapshot) => void;
     onProgress: (progress: FrontendFillProgress) => void;
     options: VibeFrontendFillOptions;
@@ -33,5 +32,5 @@ export declare function validateFillTarget(target: VibeFillTarget): VibeFillTarg
 export declare function validateFillOptions(options?: VibeFillOptions): void;
 export declare function createFillState(options?: VibeFillOptions, initialSession?: VibeFillSessionSnapshot, useConfiguredSession?: boolean): VibeFillState;
 export declare function isFillActive(state: VibeFillState): boolean;
-export declare function collectFrontendFill({ existingItems, getLoadedItemCount, initialCursor, loadPage, onCollection, onPage, onDelayChange, onProgress, options, shouldPause, signal, target, }: CollectFrontendFillOptions): Promise<FrontendFillResult>;
+export declare function collectFrontendFill({ existingItems, getLoadedItemCount, initialCursor, loadPage, onCollection, onDelayChange, onProgress, options, shouldPause, signal, target, }: CollectFrontendFillOptions): Promise<FrontendFillResult>;
 export {};

package/lib/core/page.d.ts

@@ -7,7 +7,5 @@ export interface LoadedPageRecord {
 }
 export declare function validatePage(page: VibePage): VibePage;
 export declare function appendUniqueItems(current: readonly VibeItem[], incoming: readonly VibeItem[]): VibeItem[];
-export declare function takeUniqueItems(postIds: Set<VibeItemId>, incoming: readonly VibeItem[]): VibeItem[];
-export declare function appendUniqueItemsIfChanged(current: VibeItem[], incoming: readonly VibeItem[]): VibeItem[];
 export declare function reconcilePageItems(current: readonly VibeItem[], incoming: readonly VibeItem[]): VibeItem[];
 export declare function pageCurrentCursor(page: VibePage): VibeCursor;

package/lib/core/reelScrollTransition.d.ts

@@ -1 +1,2 @@
-export declare function transitionReelScroll(element: HTMLElement, top: number, immediate: boolean): Promise<void>;
+export declare function prefersReducedReelMotion(): boolean;
+export declare function transitionReelScroll(element: HTMLElement, top: number, immediate: boolean, signal?: AbortSignal): Promise<void>;

package/lib/core/reelViewport.d.ts

@@ -0,0 +1,2 @@
+/** Shared native scroll-snap selection rule for feed and controlled reels. */
+export declare function reelIndexAtScrollOffset(top: number, height: number, count: number): number;