@wyxos/vibe 5.0.2 → 5.1.0

package/README.md

@@ -125,6 +125,35 @@ show looping previous/next controls on hover or keyboard focus. Reel layout
 keeps those controls visible and supports native horizontal-wheel or touch-swipe
 navigation through grouped media. Media changes use a directional horizontal
 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
 
@@ -504,6 +533,9 @@ vibe.previousReelMediaItem()
 // Posts within the reel (vertical reel navigation).
 vibe.nextReelPost()
 vibe.previousReelPost()
+
+// An exact loaded post/media pair by stable identity.
+vibe.navigateToReelItem({ postId: 'post-42', mediaId: 'asset-101' })
 ```
 
 Each navigation method returns `true` when it accepted a navigation and `false`
@@ -520,6 +552,13 @@ Successful navigation updates `state.activeReelPostId`, the selected media item,
 card-region props, route synchronization, and an open information sheet's
 consumer context through the same handlers used by gestures and keyboard input.
 
+`navigateToReelItem()` returns `navigated` when both identities resolve,
+including when the requested media is already active. It returns `not-found`
+when the loaded post or media is missing, and `reel-inactive` before mount,
+after destroy, during initial loading, or while only masonry is visible. The
+method does not load, insert, or fall back to another item. Every targetable
+parent or nested `VibeMediaAsset` must provide its stable `mediaId`.
+
 ## Reel information sheet
 
 Provide an application-owned Vue component when a reel should offer a
@@ -584,6 +623,11 @@ reel still updates this requested state; the sheet becomes visible when a valid
 reel context exists. This preserves the existing persistent sheet-state
 behavior across masonry viewer closes.
 
+When a sheet contains another Vibe instance, Escape is owned by the topmost
+active reel. A nested masonry-origin reel therefore closes back to its nested
+feed without also closing the parent sheet or reel. Single-instance Escape
+behavior is unchanged.
+
 ## Custom feed footer
 
 Set `feedFooter.component` to replace the built-in `GalleryFooter`. Consumers
@@ -692,6 +736,7 @@ vibe.nextReelMediaItem()
 vibe.previousReelMediaItem()
 vibe.nextReelPost()
 vibe.previousReelPost()
+vibe.navigateToReelItem({ postId: 'post-42', mediaId: 'asset-101' })
 vibe.setAutoScroll(true, 80)
 vibe.pauseAutoScroll()
 vibe.resumeAutoScroll()

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

@@ -3,6 +3,7 @@ import type { VibeItemId } from '../types';
 declare function loadIfNearBottom(): void;
 declare function changeActiveMedia(direction: -1 | 1): boolean;
 declare function moveActivePost(direction: -1 | 1): boolean;
+declare function navigateToItem(postId: VibeItemId, mediaIndex: number): boolean;
 declare function transitionActivePost(postId: VibeItemId): Promise<boolean>;
 declare function transitionActiveMedia(direction: -1 | 1): Promise<boolean>;
 declare const __VLS_export: import("vue").DefineComponent<ReelFeedProps, {
@@ -11,6 +12,7 @@ declare const __VLS_export: import("vue").DefineComponent<ReelFeedProps, {
     changeActiveMedia: typeof changeActiveMedia;
     loadIfNearBottom: typeof loadIfNearBottom;
     moveActivePost: typeof moveActivePost;
+    navigateToItem: typeof navigateToItem;
     transitionActiveMedia: typeof transitionActiveMedia;
     transitionActivePost: typeof transitionActivePost;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {

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

@@ -3,12 +3,14 @@ import type { VibeItemId } from '../types';
 declare function changeActiveMedia(direction: -1 | 1): boolean;
 declare function loadIfNearBottom(): void;
 declare function moveActivePost(direction: -1 | 1): boolean;
+declare function navigateToItem(postId: VibeItemId, mediaIndex: number): boolean;
 declare function transitionActiveMedia(direction: -1 | 1): Promise<boolean>;
 declare function transitionActivePost(postId: VibeItemId): Promise<boolean>;
 declare const __VLS_export: import("vue").DefineComponent<ReelLayoutProps, {
     changeActiveMedia: typeof changeActiveMedia;
     loadIfNearBottom: typeof loadIfNearBottom;
     moveActivePost: typeof moveActivePost;
+    navigateToItem: typeof navigateToItem;
     transitionActiveMedia: typeof transitionActiveMedia;
     transitionActivePost: typeof transitionActivePost;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {

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 } from '../types';
+import type { VibeCardRegion, VibeFeedFooter, VibeFeedFooterActions, VibeItemId, VibeMediaCardOptions, VibeMediaLifecycleContext, VibeReelInfoSheetOptions, VibeReelItemTarget, VibeReelNavigationResult } from '../types';
 type __VLS_Props = {
     canRetryEnd: boolean;
     cardFooter?: VibeCardRegion;
@@ -13,6 +13,7 @@ type __VLS_Props = {
 declare function loadIfNearBottom(): Promise<void>;
 declare function changeActiveReelMedia(direction: -1 | 1): boolean;
 declare function moveActiveReelPost(direction: -1 | 1): boolean;
+declare function navigateToReelItem(target: VibeReelItemTarget): VibeReelNavigationResult;
 declare function getAutoScrollElement(): HTMLElement | null;
 declare function startItemRemoval(postIds: readonly VibeItemId[]): number;
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
@@ -20,6 +21,7 @@ declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
     getAutoScrollElement: typeof getAutoScrollElement;
     loadIfNearBottom: typeof loadIfNearBottom;
     moveActiveReelPost: typeof moveActiveReelPost;
+    navigateToReelItem: typeof navigateToReelItem;
     startItemRemoval: typeof startItemRemoval;
     transitionActiveReelMedia: (direction: -1 | 1) => Promise<boolean>;
     transitionActiveReelPost: (postId: VibeItemId) => Promise<boolean>;
@@ -29,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;
@@ -37,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/components/useReelKeyboard.d.ts

@@ -0,0 +1,12 @@
+import type { FeedRendererExpose } from '../core/feed';
+import type { VibeRuntimeState } from '../core/runtime';
+interface ReelKeyboardOptions {
+    closeMasonryReel: () => void;
+    element: () => HTMLElement | null;
+    isReelLeaving: () => boolean;
+    reelRenderer: () => FeedRendererExpose | null;
+    setReelInfoSheet: (enabled: boolean) => void;
+    state: VibeRuntimeState;
+}
+export declare function useReelKeyboard(options: ReelKeyboardOptions): void;
+export {};

package/lib/core/feed.d.ts

@@ -1,4 +1,4 @@
-import type { VibeCardRegion, VibeFeedFooter, VibeFeedFooterActions, VibeItem, VibeItemId, VibeMediaSource, VibeMediaCardOptions, VibeReelAutoAdvanceState, VibeReelForwardState, VibeReelInfoSheetOptions, VibeReelOrigin, VibeState } from '../types';
+import type { VibeCardRegion, VibeFeedFooter, VibeFeedFooterActions, VibeItem, VibeItemId, VibeMediaSource, VibeMediaCardOptions, VibeReelAutoAdvanceState, VibeReelForwardState, VibeReelInfoSheetOptions, VibeReelItemTarget, VibeReelNavigationResult, VibeReelOrigin, VibeState } from '../types';
 import type { MediaPreviewState } from './mediaPreview';
 export interface FeedRendererProps {
     canRetryEnd: boolean;
@@ -30,6 +30,7 @@ export interface FeedRendererExpose {
     getScrollElement?: () => HTMLElement | null;
     loadIfNearBottom: () => void;
     moveActivePost?: (direction: -1 | 1) => boolean;
+    navigateToItem?: (postId: VibeItemId, mediaIndex: number) => boolean;
     transitionActiveMedia?: (direction: -1 | 1) => Promise<boolean>;
     transitionActivePost?: (postId: VibeItemId) => Promise<boolean>;
 }
@@ -52,6 +53,7 @@ export interface VibeSurfaceExpose {
     getAutoScrollElement: () => HTMLElement | null;
     loadIfNearBottom: () => Promise<void>;
     moveActiveReelPost: (direction: -1 | 1) => boolean;
+    navigateToReelItem: (target: VibeReelItemTarget) => VibeReelNavigationResult;
     startItemRemoval: (postIds: readonly VibeItemId[]) => number;
     transitionActiveReelMedia: (direction: -1 | 1) => Promise<boolean>;
     transitionActiveReelPost: (postId: VibeItemId) => Promise<boolean>;

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/reelEscapeStack.d.ts

@@ -0,0 +1,6 @@
+export interface ReelEscapeParticipant {
+    element: () => HTMLElement | null;
+    isActive: () => boolean;
+}
+export declare function registerReelEscapeParticipant(participant: ReelEscapeParticipant): () => void;
+export declare function isTopmostActiveReel(participant: ReelEscapeParticipant): boolean;