@wyxos/vibe 5.0.3 → 5.2.1

package/README.md

@@ -128,6 +128,33 @@ transition, while vertical reel scrolling continues to move between posts.
 Media assets may include a stable `mediaId` (`string | number`) when consumers
 need to select exact grouped media independently of its array position.
 
+## Media lifecycle hooks
+
+Use `onMediaReady` when an image has loaded or a video has enough metadata for
+Vibe to render it, and `onReelMediaChange` when a reel first selects media or
+moves to another parent, nested, or single-item post:
+
+```ts
+const vibe = createVibe({
+  target: '#gallery',
+  loadPage,
+  onMediaReady: ({ postId, mediaId, layout, origin }) => {
+    recordMediaReady({ postId, mediaId, layout, origin })
+  },
+  onReelMediaChange: ({ postId, mediaId, postIndex, mediaIndex }) => {
+    updateActiveMedia({ postId, mediaId, postIndex, mediaIndex })
+  },
+})
+```
+
+Both optional callbacks receive `VibeMediaLifecycleContext`: stable `postId`
+and `mediaId` identity, zero-based `postIndex` and `mediaIndex`, the complete
+`item` and selected `media`, the rendered `layout`, and `origin`. `mediaId` is
+`null` when the source asset does not define one. `origin` is `null` for the
+masonry grid, `reel` for the base reel, and `masonry` for a reel opened from a
+masonry card. The readiness hook may run again if media remounts and becomes
+ready again; reel-change events describe selection changes, not load state.
+
 ## Reel URLs with Vue Router
 
 Pass a Vue Router instance when the application should reflect the active reel

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

@@ -1,5 +1,5 @@
 import { type VibeRuntimeState } from '../core/runtime';
-import type { VibeCardRegion, VibeFeedFooter, VibeFeedFooterActions, VibeItemId, VibeMediaCardOptions, VibeReelInfoSheetOptions, VibeReelItemTarget, VibeReelNavigationResult } from '../types';
+import type { VibeCardRegion, VibeFeedFooter, VibeFeedFooterActions, VibeItemId, VibeMediaCardOptions, VibeMediaLifecycleContext, VibeReelInfoSheetOptions, VibeReelItemTarget, VibeReelNavigationResult } from '../types';
 type __VLS_Props = {
     canRetryEnd: boolean;
     cardFooter?: VibeCardRegion;
@@ -31,7 +31,9 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
     retryForward: () => any;
     activeReelChange: (postId: VibeItemId) => any;
     closeReel: () => any;
+    mediaReady: (context: VibeMediaLifecycleContext) => any;
     openReel: (postId: VibeItemId) => any;
+    reelMediaChange: (context: VibeMediaLifecycleContext) => any;
     reelInfoSheetChange: (enabled: boolean) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     onLoadMore?: (() => any) | undefined;
@@ -39,7 +41,9 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
     onRetryForward?: (() => any) | undefined;
     onActiveReelChange?: ((postId: VibeItemId) => any) | undefined;
     onCloseReel?: (() => any) | undefined;
+    onMediaReady?: ((context: VibeMediaLifecycleContext) => any) | undefined;
     onOpenReel?: ((postId: VibeItemId) => any) | undefined;
+    onReelMediaChange?: ((context: VibeMediaLifecycleContext) => any) | undefined;
     onReelInfoSheetChange?: ((enabled: boolean) => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;

package/lib/core/autofill.d.ts

@@ -1,5 +1,6 @@
 import type { VibeAutofillOptions, VibeAutofillSessionSnapshot, VibeAutofillState, VibeCursor, VibeFrontendAutofillOptions, VibeItem, VibePageLoader } from '../types';
 import type { VibeRuntimeState } from './runtime';
+import { type LoadedPageRecord } from './page';
 import { type RequestDelaySnapshot } from './requestDelay';
 export declare const DEFAULT_MAX_ADDITIONAL_PAGES = 10;
 export declare function frontendAutofillRequestLimit(options: VibeFrontendAutofillOptions, includeInitialRequest?: boolean): number;
@@ -15,6 +16,7 @@ export interface FrontendAutofillCollection extends FrontendAutofillProgress {
     total?: number;
 }
 export interface FrontendAutofillResult extends FrontendAutofillCollection {
+    pages: LoadedPageRecord[];
     status: 'complete' | 'exhausted';
 }
 interface CollectFrontendAutofillOptions {

package/lib/core/exactMediaRemovalController.d.ts

@@ -3,6 +3,8 @@ import type { VibeRuntimeState } from './runtime';
 import type { VibeItemId, VibeMediaRemoval, VibeMediaTarget } from '../types';
 interface ExactMediaRemovalControllerOptions {
     onActivate: (postId: VibeItemId) => void;
+    onPostRemoved: (postId: VibeItemId) => void;
+    onPostRestored: (postId: VibeItemId) => void;
     reelForward: ReelForwardController;
     state: VibeRuntimeState;
 }

package/lib/core/fill.d.ts

@@ -1,3 +1,4 @@
+import { type LoadedPageRecord } from './page';
 import type { VibeFillOptions, VibeFillSessionSnapshot, VibeFillState, VibeFillTarget, VibeCursor, VibeFrontendFillOptions, VibeItem, VibePageLoader } from '../types';
 import { type RequestDelaySnapshot } from './requestDelay';
 export interface FrontendFillProgress {
@@ -8,6 +9,7 @@ export interface FrontendFillProgress {
 export interface FrontendFillResult extends FrontendFillProgress {
     items: VibeItem[];
     lastCursor: VibeCursor;
+    pages: LoadedPageRecord[];
     status: 'complete' | 'exhausted';
     total?: number;
 }

package/lib/core/fillController.d.ts

@@ -1,9 +1,11 @@
+import type { LoadedPageRecord } from './page';
 import type { VibeRuntimeState } from './runtime';
 import type { VibeBackendFillUpdate, VibeCursor, VibeFillOptions, VibeFillSessionSnapshot, VibeFillTarget, VibePageLoader } from '../types';
 interface FillControllerOptions {
     fill?: VibeFillOptions;
     loadPage?: VibePageLoader;
     onLastCursor: (cursor: VibeCursor) => void;
+    onPages: (pages: readonly LoadedPageRecord[]) => void;
     state: VibeRuntimeState;
 }
 export declare class VibeFillController {

package/lib/core/initialAutofill.d.ts

@@ -1,4 +1,5 @@
 import { type FrontendAutofillCollection } from './autofill';
+import type { LoadedPageRecord } from './page';
 import type { VibeRuntimeState } from './runtime';
 import type { CreateVibeOptions, VibeCursor } from '../types';
 interface InitialAutofillContext {
@@ -6,9 +7,10 @@ interface InitialAutofillContext {
     isCurrent: () => boolean;
     onCollection: (collection: FrontendAutofillCollection) => void;
     onLastCursor: (cursor: VibeCursor) => void;
+    onPages: (pages: readonly LoadedPageRecord[]) => void;
     options: CreateVibeOptions;
     signal: AbortSignal;
     state: VibeRuntimeState;
 }
-export declare function autofillInitialPage({ cycleId, isCurrent, onCollection, onLastCursor, options, signal, state, }: InitialAutofillContext): Promise<void>;
+export declare function autofillInitialPage({ cycleId, isCurrent, onCollection, onLastCursor, onPages, options, signal, state, }: InitialAutofillContext): Promise<void>;
 export {};

package/lib/core/mediaLifecycle.d.ts

@@ -0,0 +1,4 @@
+import type { VibeRuntimeState } from './runtime';
+import type { VibeItemId, VibeLayout, VibeMediaLifecycleContext, VibeReelOrigin } from '../types';
+export declare function mediaLifecycleContext(state: VibeRuntimeState, postId: VibeItemId, mediaIndex: number, layout: VibeLayout, origin: VibeReelOrigin | null): VibeMediaLifecycleContext | null;
+export declare function useReelMediaChangeLifecycle(state: VibeRuntimeState, onChange: (context: VibeMediaLifecycleContext) => void): void;

package/lib/core/page.d.ts

@@ -1,3 +1,9 @@
-import type { VibeItem, VibePage } from '../types';
+import type { VibeCursor, VibeItem, VibeItemId, VibePage } from '../types';
+export interface LoadedPageRecord {
+    contributionIds: VibeItemId[];
+    cursor: VibeCursor;
+    next: VibeCursor;
+    returnedIds: VibeItemId[];
+}
 export declare function validatePage(page: VibePage): VibePage;
 export declare function appendUniqueItems(current: readonly VibeItem[], incoming: readonly VibeItem[]): VibeItem[];

package/lib/core/pageRequest.d.ts

@@ -0,0 +1,18 @@
+import type { CreateVibeOptions, VibeCursor, VibePageRequest } from '../types';
+import type { VibeAutofillController } from './autofillController';
+import { type LoadedPageRecord } from './page';
+import type { VibeRuntimeState } from './runtime';
+interface PageRequestOptions {
+    append: boolean;
+    autofillController: VibeAutofillController;
+    cursor: VibeCursor;
+    isCurrent: () => boolean;
+    loadPage: (request: VibePageRequest) => ReturnType<NonNullable<CreateVibeOptions['loadPage']>>;
+    onLastCursor: (cursor: VibeCursor) => void;
+    onPages: (pages: readonly LoadedPageRecord[]) => void;
+    options: CreateVibeOptions;
+    signal: AbortSignal;
+    state: VibeRuntimeState;
+}
+export declare function performPageRequest({ append, autofillController, cursor, isCurrent, loadPage, onLastCursor, onPages, options, signal, state, }: PageRequestOptions): Promise<void>;
+export {};

package/lib/core/removalControllers.d.ts

@@ -9,6 +9,8 @@ interface RemovalControllerOptions {
     historyLimit: number | undefined;
     loadNext: () => Promise<void>;
     onActivate: (postId: VibeItemId) => void;
+    onItemsRemoved: (postIds: readonly VibeItemId[]) => void;
+    onItemsRestored: (postIds: readonly VibeItemId[]) => void;
     retryEnd: () => Promise<void>;
     state: VibeRuntimeState;
     surface: () => VibeSurfaceExpose | null;

package/lib/core/removalReconciliationController.d.ts

@@ -0,0 +1,35 @@
+import type { CreateVibeOptions, VibeCursor, VibeItem, VibeItemId, VibePageLoader } from '../types';
+import { type LoadedPageRecord } from './page';
+interface ReconciliationResult {
+    items: VibeItem[];
+    lastCursor: VibeCursor;
+    next: VibeCursor;
+    pages: LoadedPageRecord[];
+    replaceFrom: number;
+    total?: number;
+}
+interface ReconcileOptions {
+    existingItems: readonly VibeItem[];
+    loadPage: VibePageLoader;
+    signal: AbortSignal;
+}
+export declare class RemovalReconciliationController {
+    private readonly delay;
+    private readonly enabled;
+    private readonly maxReplayPages;
+    private readonly pageSize;
+    private pages;
+    private readonly tombstones;
+    constructor(options: CreateVibeOptions);
+    completeReconciliation(result: ReconciliationResult): void;
+    filterItems(items: readonly VibeItem[]): VibeItem[];
+    needsReconciliation(items: readonly VibeItem[]): boolean;
+    recordPages(records: readonly LoadedPageRecord[]): void;
+    remove(postIds: readonly VibeItemId[]): void;
+    reset(): void;
+    restore(postIds: readonly VibeItemId[]): void;
+    reconcile({ existingItems, loadPage, signal, }: ReconcileOptions): Promise<ReconciliationResult>;
+    private findUnderfilledPage;
+    private recordPage;
+}
+export {};