@wyxos/vibe 5.10.1 → 5.12.0

package/README.md

@@ -170,8 +170,12 @@ 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:
+Vibe to render it. `onMediaVisible` reports each ready masonry media item once
+per feed visit when it first intersects the viewport. `onMediaFullyVisible`
+reports each ready media item once per layout and feed visit: after the masonry
+card reaches its full visibility threshold, or after the media is active and
+ready in a reel.
+`onReelMediaChange` reports reel selection changes:
 
 ```ts
 const vibe = createVibe({
@@ -180,19 +184,32 @@ const vibe = createVibe({
   onMediaReady: ({ postId, mediaId, layout, origin }) => {
     recordMediaReady({ postId, mediaId, layout, origin })
   },
+  onMediaVisible: ({ postId, mediaIndex }) => {
+    recordMediaPreviewed({ postId, mediaIndex })
+  },
+  onMediaFullyVisible: ({ postId, mediaIndex, layout }) => {
+    recordMediaViewed({ postId, mediaIndex, layout })
+  },
   onReelMediaChange: ({ postId, mediaId, postIndex, mediaIndex }) => {
     updateActiveMedia({ postId, mediaId, postIndex, mediaIndex })
   },
 })
 ```
 
-Both optional callbacks receive `VibeMediaLifecycleContext`: stable `postId`
+All lifecycle 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.
+ready again. A feed visit begins when Vibe mounts and restarts whenever
+`refresh()` or `reload()` replaces the feed. Visibility callbacks stay
+deduplicated while scrolling, loading more, or retrying pagination within that
+visit.
+Normal masonry cards require their complete height; cards taller than the
+viewport require 80% of their maximum attainable visible height. Reel fully
+visible events depend on active-and-ready state rather than intersection.
+Reel-change events describe selection changes, not load state.
 
 ## Reel URLs with Vue Router
 
@@ -790,6 +807,7 @@ vibe.destroy()
 `refresh()` replaces the visible feed from its current continuation cursor. At
 the end of the feed, it requests the cursor that produced the last loaded page
 again. Use `reload()` to replace the feed from its initial `null` cursor instead.
+Both operations begin a new feed visit for media visibility callbacks.
 
 Destroying an instance unmounts its Vue tree and aborts its active page request.
 

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

@@ -12,6 +12,7 @@ declare const __VLS_export: import("vue").DefineComponent<MasonryFeedProps, {
     retryEnd: () => any;
     activate: (postId: VibeItemId, input: "keyboard" | "pointer") => any;
     mediaChange: (postId: VibeItemId, mediaIndex: number) => any;
+    fullyVisible: (postId: VibeItemId, mediaIndex: number) => any;
     visible: (postId: VibeItemId, mediaIndex: number) => any;
 }, string, import("vue").PublicProps, Readonly<MasonryFeedProps> & Readonly<{
     onReady?: ((postId: VibeItemId, mediaIndex: number) => any) | undefined;
@@ -20,6 +21,7 @@ declare const __VLS_export: import("vue").DefineComponent<MasonryFeedProps, {
     onRetryEnd?: (() => any) | undefined;
     onActivate?: ((postId: VibeItemId, input: "keyboard" | "pointer") => any) | undefined;
     onMediaChange?: ((postId: VibeItemId, mediaIndex: number) => any) | undefined;
+    onFullyVisible?: ((postId: VibeItemId, mediaIndex: number) => any) | undefined;
     onVisible?: ((postId: VibeItemId, mediaIndex: number) => any) | undefined;
 }>, {
     leavingPostIds: ReadonlySet<VibeItemId>;

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

@@ -26,6 +26,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
     loadIfNearBottom: typeof loadIfNearBottom;
     moveActiveReelPost: typeof moveActiveReelPost;
     navigateToReelItem: typeof navigateToReelItem;
+    resetMediaLifecycle: () => void;
     startItemRemoval: typeof startItemRemoval;
     transitionActiveReelMedia: (direction: -1 | 1) => Promise<boolean>;
     transitionActiveReelPost: (postId: VibeItemId) => Promise<boolean>;
@@ -36,6 +37,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
     retryForward: () => any;
     activeReelChange: (postId: VibeItemId) => any;
     closeReel: () => any;
+    mediaFullyVisible: (context: VibeMediaLifecycleContext) => any;
     mediaReady: (context: VibeMediaLifecycleContext) => any;
     mediaVisible: (context: VibeMediaLifecycleContext) => any;
     openReel: (postId: VibeItemId) => any;
@@ -48,6 +50,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
     onRetryForward?: (() => any) | undefined;
     onActiveReelChange?: ((postId: VibeItemId) => any) | undefined;
     onCloseReel?: (() => any) | undefined;
+    onMediaFullyVisible?: ((context: VibeMediaLifecycleContext) => any) | undefined;
     onMediaReady?: ((context: VibeMediaLifecycleContext) => any) | undefined;
     onMediaVisible?: ((context: VibeMediaLifecycleContext) => any) | undefined;
     onOpenReel?: ((postId: VibeItemId) => any) | undefined;

package/lib/components/useMasonryMediaVisibility.d.ts

@@ -0,0 +1,13 @@
+import type { MediaPreviewState } from '../core/mediaPreview';
+import type { VibeItem, VibeItemId } from '../types';
+interface MasonryMediaVisibilityOptions {
+    fullyVisibleIndices: () => readonly number[];
+    items: () => readonly VibeItem[];
+    mediaIndices: () => ReadonlyMap<VibeItemId, number>;
+    onFullyVisible: (postId: VibeItemId, mediaIndex: number) => void;
+    onVisible: (postId: VibeItemId, mediaIndex: number) => void;
+    previewStates: () => ReadonlyMap<string, MediaPreviewState>;
+    visibleIndices: () => readonly number[];
+}
+export declare function useMasonryMediaVisibility(options: MasonryMediaVisibilityOptions): void;
+export {};

package/lib/components/useMediaLifecycle.d.ts

@@ -2,11 +2,13 @@ import type { MediaPreviewState } from '../core/mediaPreview';
 import type { VibeRuntimeState } from '../core/runtime';
 import type { VibeItemId, VibeMediaLifecycleContext } from '../types';
 interface MediaLifecycleEvents {
+    fullyVisible: (context: VibeMediaLifecycleContext) => void;
     ready: (context: VibeMediaLifecycleContext) => void;
     reelChange: (context: VibeMediaLifecycleContext) => void;
     visible: (context: VibeMediaLifecycleContext) => void;
 }
 export declare function useMediaLifecycle(state: VibeRuntimeState, events: MediaLifecycleEvents): {
+    markMasonryFullyVisible: (postId: VibeItemId, mediaIndex: number) => void;
     markMasonryVisible: (postId: VibeItemId, mediaIndex: number) => void;
     markPreviewError: (postId: VibeItemId, mediaIndex: number) => void;
     markPreviewReady: (postId: VibeItemId, mediaIndex: number) => void;
@@ -15,5 +17,6 @@ export declare function useMediaLifecycle(state: VibeRuntimeState, events: Media
     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/useReelVideoActivity.d.ts

@@ -2,6 +2,7 @@ import { type Ref } from 'vue';
 import type { VibeLayout } from '../types';
 interface ReelTimedMediaActivityOptions {
     active: () => boolean | undefined;
+    inViewport: () => boolean;
     layout: () => VibeLayout;
     mediaElement: Ref<HTMLMediaElement | null>;
     mediaIsMuted: Ref<boolean>;

package/lib/components/useTimedMediaCard.d.ts

@@ -2,6 +2,7 @@ import { type Ref } from 'vue';
 import type { VibeLayout, VibeMediaCardOptions, VibeReelAudioState } from '../types';
 interface TimedMediaCardOptions {
     active: () => boolean | undefined;
+    inViewport: () => boolean;
     layout: () => VibeLayout;
     mediaCard: () => VibeMediaCardOptions | undefined;
     mediaElement: Ref<HTMLMediaElement | null>;

package/lib/core/feed.d.ts

@@ -58,6 +58,7 @@ export interface VibeSurfaceExpose {
     loadIfNearBottom: () => Promise<void>;
     moveActiveReelPost: (direction: -1 | 1) => boolean;
     navigateToReelItem: (target: VibeReelItemTarget) => VibeReelNavigationResult;
+    resetMediaLifecycle: () => void;
     startItemRemoval: (postIds: readonly VibeItemId[], options?: VibeItemRemovalOptions) => number;
     transitionActiveReelMedia: (direction: -1 | 1) => Promise<boolean>;
     transitionActiveReelPost: (postId: VibeItemId) => Promise<boolean>;

package/lib/core/masonry.d.ts

@@ -26,6 +26,10 @@ export interface MasonryViewportOptions {
     viewportHeight: number;
     overscan: number;
 }
+export interface MasonryVisibilityOptions {
+    scrollTop: number;
+    viewportHeight: number;
+}
 interface MasonryOptions {
     additionalHeight?: number;
     gap: number;
@@ -33,5 +37,6 @@ interface MasonryOptions {
 }
 export declare function calculateMasonryEntryOffset(options: MasonryEntryOptions): number;
 export declare function calculateVisibleMasonryIndices(items: MasonryPosition[], options: MasonryViewportOptions): number[];
+export declare function calculateFullyVisibleMasonryIndices(items: readonly MasonryPosition[], candidates: readonly number[], options: MasonryVisibilityOptions): number[];
 export declare function calculateMasonryLayout(media: readonly MasonryMediaDimensions[], containerWidth: number, options: MasonryOptions): MasonryLayout;
 export {};