@wyxos/vibe 5.0.1 → 5.0.3

package/README.md

@@ -112,9 +112,12 @@ zero-based `mediaIndex`, its inclusive `mediaCount`, and the optional remote
 `total`. Import the `VibeCardRegionProps` type for typed Vue props. Interacting
 with these regions does not activate the underlying media.
 
-Masonry videos start muted, while reel videos start unmuted. Set
-`mediaCard.videoMuted` to explicitly override the initial state in either
-layout. Users can still change mute and volume through the timed-media controls.
+Masonry videos start muted, while the active reel video starts unmuted. Inactive
+reel videos are always paused and muted while they remain mounted for nearby
+virtualization; their user-selected mute state is restored when they become
+active again. Set `mediaCard.videoMuted` to explicitly override the initial
+state in either layout. Users can still change mute and volume through the
+timed-media controls.
 
 When a feed item has entries in `item.items`, Vibe treats the parent media as
 position one and the nested entries as the remaining positions. Masonry cards
@@ -122,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
 
@@ -501,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`
@@ -517,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
@@ -581,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
@@ -689,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/components/useReelVideoActivity.d.ts

@@ -0,0 +1,15 @@
+import { type Ref } from 'vue';
+import type { VibeLayout } from '../types';
+interface ReelVideoActivityOptions {
+    active: () => boolean | undefined;
+    layout: () => VibeLayout;
+    videoElement: Ref<HTMLVideoElement | null>;
+    videoIsMuted: Ref<boolean>;
+    videoIsPlaying: Ref<boolean>;
+}
+export declare function useReelVideoActivity(options: ReelVideoActivityOptions): {
+    effectiveMuted: import("vue").ComputedRef<boolean>;
+    onPlaying: () => void;
+    playbackAllowed: import("vue").ComputedRef<boolean>;
+};
+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;