@wyxos/vibe 5.0.2 → 5.0.3

package/README.md

@@ -125,6 +125,8 @@ 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.
 
 ## Reel URLs with Vue Router
 
@@ -504,6 +506,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 +525,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 +596,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 +709,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, 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>;

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/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;