@wyxos/vibe 3.0.4 → 3.0.6

package/README.md

@@ -65,7 +65,7 @@ async function resolve({ cursor, pageSize }: VibeResolveParams): Promise<VibeRes
 </template>
 ```
 
-Optional auto-mode pacing props:
+Optional pacing props:
 
 ```vue
 <VibeLayout
@@ -74,6 +74,7 @@ Optional auto-mode pacing props:
   :fill-delay-step-ms="1000"
   :show-end-badge="false"
   :show-status-badges="false"
+  surface-mode="fullscreen"
 />
 ```
 
@@ -81,9 +82,10 @@ Optional auto-mode pacing props:
 - `fill-delay-step-ms`: extra delay added for each additional chained fill request in the same fill cycle
 - defaults: `2000` and `1000`
 - `show-end-badge`: controls the fullscreen `End reached` badge when the feed is exhausted
-- `show-status-badges`: controls the built-in loading/end status overlays in list and fullscreen
+- `show-status-badges`: controls the built-in lifecycle status overlays in list and fullscreen
+- `surface-mode`: optionally lets the parent drive the desktop fullscreen/list surface explicitly
 
-Optional auto-mode feed strategy:
+Optional feed strategy:
 
 ```vue
 <VibeLayout
@@ -95,12 +97,30 @@ Optional auto-mode feed strategy:
 - `dynamic` is the default
 - `static` reloads the current boundary cursor before advancing when the currently visible boundary page is underfilled
 
+Optional seeded hydration:
+
+```vue
+<VibeLayout
+  :resolve="resolve"
+  :initial-state="{
+    cursor: 'page-10',
+    items: restoredItems,
+    nextCursor: 'page-11',
+    previousCursor: 'page-9',
+    activeIndex: 4,
+  }"
+/>
+```
+
+- use `initialState` when the app already knows a restored slice of the feed
+- `resolve` is optional if you only need a seeded snapshot
+- when `resolve` is present, Vibe continues paging from the seeded cursors
+
 ## What Vibe does
 
 - Desktop masonry list with virtualization and staged page growth
 - Fullscreen viewer with swipe, wheel, keyboard, and custom media controls
-- Auto-loading mode with internal pagination ownership
-- Controlled mode for advanced/manual integrations
+- Library-owned loading and pagination, optionally seeded from `initialState`
 - Remove, restore, and undo by item `id`
 - Grid customization through slots for icons, overlays, and footer UI
 - Built-in loading and preload error states, including explicit `404` when known
@@ -134,9 +154,7 @@ Notes:
 - Grid layout prefers `preview.width/height`, then root `width/height`, then a square fallback tile
 - `other` is intentionally broad so the consuming app can layer its own subtypes and icon logic on top
 
-## Loading modes
-
-### Auto mode
+## Loading
 
 Use `resolve` when you want Vibe to own the paging loop:
 
@@ -172,7 +190,7 @@ async function resolve({ cursor, pageSize }: VibeResolveParams): Promise<VibeRes
 </template>
 ```
 
-In this mode, Vibe owns:
+Vibe owns:
 
 - loaded items
 - active index
@@ -181,7 +199,7 @@ In this mode, Vibe owns:
 - duplicate cursor protection
 - initial retry state
 
-Auto mode also supports two feed strategies:
+Vibe also supports two feed strategies:
 
 - `dynamic`:
   - default behavior
@@ -195,43 +213,19 @@ Auto mode also supports two feed strategies:
   - if it is, Vibe reloads that same cursor in place first
   - only once that boundary page is full again will the next edge hit advance to the next or previous cursor
 
-### Controlled mode
-
-Use controlled mode when the app needs to own item aggregation or paging policy:
+You can also seed the viewer from a known snapshot:
 
 ```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { VibeLayout, type VibeViewerItem } from '@wyxos/vibe'
-
-const items = ref<VibeViewerItem[]>([])
-const activeIndex = ref(0)
-const loading = ref(false)
-const hasNextPage = ref(true)
-const hasPreviousPage = ref(false)
-
-async function requestNextPage() {
-  // app-owned fetch and append
-}
-
-async function requestPreviousPage() {
-  // app-owned fetch and prepend
-}
-</script>
-
-<template>
-  <VibeLayout
-    :items="items"
-    :active-index="activeIndex"
-    :loading="loading"
-    :has-next-page="hasNextPage"
-    :has-previous-page="hasPreviousPage"
-    pagination-detail="P10-12 · V11"
-    :request-next-page="requestNextPage"
-    :request-previous-page="requestPreviousPage"
-    @update:active-index="activeIndex = $event"
-  />
-</template>
+<VibeLayout
+  :resolve="resolve"
+  :initial-state="{
+    cursor: 'page-10',
+    items: restoredItems,
+    nextCursor: 'page-11',
+    previousCursor: 'page-9',
+    activeIndex: 4,
+  }"
+/>
 ```
 
 ## Slots
@@ -329,14 +323,14 @@ type VibeStatus = {
   fillTargetCount: number | null
   hasNextPage: boolean
   hasPreviousPage: boolean
-  isAutoMode: boolean
   itemCount: number
   loadState: 'failed' | 'loaded' | 'loading'
-  mode: 'dynamic' | 'static' | null
+  mode: 'dynamic' | 'static'
   nextCursor: string | null
-  phase: 'failed' | 'filling' | 'idle' | 'loading' | 'reloading'
+  phase: 'failed' | 'filling' | 'idle' | 'initializing' | 'loading' | 'refreshing'
   previousCursor: string | null
   removedCount: number
+  removedIds: readonly string[]
   surfaceMode: 'fullscreen' | 'list'
 }
 ```
@@ -347,6 +341,7 @@ Example:
 vibe.value?.remove(['item-2', 'item-5'])
 vibe.value?.undo()
 console.log(vibe.value?.status.itemCount)
+console.log(vibe.value?.status.removedIds)
 ```
 
 ## Events
@@ -354,6 +349,7 @@ console.log(vibe.value?.status.itemCount)
 `VibeLayout` emits:
 
 - `update:activeIndex`
+- `update:surfaceMode`
 - `asset-loads`
 - `asset-errors`
 

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

@@ -1,16 +1,27 @@
 import type { Component } from 'vue';
 import type { VibeViewerItem } from './viewer';
 import type { VibeAssetErrorReporter, VibeAssetLoadReporter } from './viewer-core/assetErrors';
-import type { VibeFullscreenStatusSlotProps, VibeSurfaceSlotProps } from './viewer-core/surfaceSlots';
-import type { VibeControlledProps } from './viewer-core/useViewer';
+import type { VibeEmptyStateMode, VibeEmptyStateSlotProps, VibeFullscreenStatusSlotProps, VibeSurfaceSlotProps } from './viewer-core/surfaceSlots';
+import type { VibeLoadPhase } from './viewer-core/useViewer';
 import './viewer-core/fullscreenMediaBar.css';
-type __VLS_Props = VibeControlledProps & {
+interface FullscreenSurfaceProps {
     active?: boolean;
+    activeIndex?: number;
+    emptyStateMode?: VibeEmptyStateMode;
+    errorMessage?: string | null;
+    hasNextPage?: boolean;
+    items: VibeViewerItem[];
+    loading?: boolean;
+    paginationDetail?: string | null;
+    phase?: VibeLoadPhase | null;
     reportAssetError?: VibeAssetErrorReporter | null;
     reportAssetLoad?: VibeAssetLoadReporter | null;
     showBackToList?: boolean;
-};
+    showEndBadge?: boolean;
+    showStatusBadges?: boolean;
+}
 type __VLS_Slots = {
+    'empty-state'?: (props: VibeEmptyStateSlotProps) => unknown;
     'fullscreen-aside'?: (props: VibeSurfaceSlotProps) => unknown;
     'fullscreen-header-actions'?: (props: VibeSurfaceSlotProps) => unknown;
     'fullscreen-overlay'?: (props: VibeSurfaceSlotProps) => unknown;
@@ -20,19 +31,22 @@ type __VLS_Slots = {
         item: VibeViewerItem;
     }) => unknown;
 };
-declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+declare const __VLS_base: import("vue").DefineComponent<FullscreenSurfaceProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:activeIndex": (value: number) => any;
     "back-to-list": () => any;
-}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+}, string, import("vue").PublicProps, Readonly<FullscreenSurfaceProps> & Readonly<{
     "onUpdate:activeIndex"?: ((value: number) => any) | undefined;
     "onBack-to-list"?: (() => any) | undefined;
 }>, {
     loading: boolean;
-    activeIndex: number;
-    hasNextPage: boolean;
+    emptyStateMode: VibeEmptyStateMode;
     paginationDetail: string | null;
     showEndBadge: boolean;
     showStatusBadges: boolean;
+    activeIndex: number;
+    errorMessage: string | null;
+    hasNextPage: boolean;
+    phase: VibeLoadPhase | null;
     showBackToList: boolean;
     active: boolean;
     reportAssetError: VibeAssetErrorReporter | null;

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

@@ -1,9 +1,10 @@
 import { type Component } from 'vue';
 import type { VibeViewerItem } from './viewer';
 import { type VibeAssetErrorEvent, type VibeAssetLoadEvent } from './viewer-core/assetErrors';
-import type { VibeFullscreenStatusSlotProps, VibeGridStatusSlotProps, VibeSurfaceSlotProps } from './viewer-core/surfaceSlots';
-import type { VibeHandle } from './viewer-core/useViewer';
+import type { VibeEmptyStateSlotProps, VibeFullscreenStatusSlotProps, VibeGridStatusSlotProps, VibeSurfaceSlotProps } from './viewer-core/surfaceSlots';
+import type { VibeHandle, VibeProps } from './viewer-core/useViewer';
 type __VLS_Slots = {
+    'empty-state'?: (props: VibeEmptyStateSlotProps) => unknown;
     'fullscreen-aside'?: (props: VibeSurfaceSlotProps) => unknown;
     'fullscreen-header-actions'?: (props: VibeSurfaceSlotProps) => unknown;
     'fullscreen-overlay'?: (props: VibeSurfaceSlotProps) => unknown;
@@ -23,12 +24,14 @@ type __VLS_Slots = {
         item: VibeViewerItem;
     }) => unknown;
 };
-declare const __VLS_base: import("vue").DefineComponent<import("..").VibeControlledProps | import("..").VibeAutoProps, VibeHandle, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+declare const __VLS_base: import("vue").DefineComponent<VibeProps, VibeHandle, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:activeIndex": (value: number) => any;
+    "update:surfaceMode": (value: "fullscreen" | "list") => any;
     "asset-errors": (errors: VibeAssetErrorEvent[]) => any;
     "asset-loads": (loads: VibeAssetLoadEvent[]) => any;
-}, string, import("vue").PublicProps, Readonly<import("..").VibeControlledProps | import("..").VibeAutoProps> & Readonly<{
+}, string, import("vue").PublicProps, Readonly<VibeProps> & Readonly<{
     "onUpdate:activeIndex"?: ((value: number) => any) | undefined;
+    "onUpdate:surfaceMode"?: ((value: "fullscreen" | "list") => any) | undefined;
     "onAsset-errors"?: ((errors: VibeAssetErrorEvent[]) => any) | undefined;
     "onAsset-loads"?: ((loads: VibeAssetLoadEvent[]) => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

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

@@ -1,26 +1,30 @@
 import type { Component } from 'vue';
 import type { VibeViewerItem } from './viewer';
 import type { VibeAssetErrorReporter, VibeAssetLoadReporter } from './viewer-core/assetErrors';
-import type { VibeGridStatusSlotProps } from './viewer-core/surfaceSlots';
+import type { VibeEmptyStateMode, VibeEmptyStateSlotProps, VibeGridStatusSlotProps } from './viewer-core/surfaceSlots';
+import type { VibeLoadPhase } from './viewer-core/useViewer';
 type __VLS_Props = {
     active?: boolean;
     activeIndex?: number;
     allowExhaustedNextPageRefresh?: boolean;
     commitPendingAppend?: (() => void | Promise<void>) | null;
+    emptyStateMode?: VibeEmptyStateMode;
+    errorMessage?: string | null;
     hasNextPage?: boolean;
     hasPreviousPage?: boolean;
     items: VibeViewerItem[];
     loading?: boolean;
     pendingAppendItems?: VibeViewerItem[];
     paginationDetail?: string | null;
+    phase?: VibeLoadPhase | null;
     reportAssetError?: VibeAssetErrorReporter | null;
     reportAssetLoad?: VibeAssetLoadReporter | null;
     requestNextPage?: (() => void | Promise<void>) | null;
     requestPreviousPage?: (() => void | Promise<void>) | null;
-    restoreToken: number;
     showStatusBadges?: boolean;
 };
 type __VLS_Slots = {
+    'empty-state'?: (props: VibeEmptyStateSlotProps) => unknown;
     'grid-footer'?: () => unknown;
     'grid-item-overlay'?: (props: {
         active: boolean;
@@ -44,19 +48,22 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     "onOpen-fullscreen"?: ((index: number) => any) | undefined;
 }>, {
     loading: boolean;
+    emptyStateMode: VibeEmptyStateMode;
+    paginationDetail: string | null;
+    showStatusBadges: boolean;
     activeIndex: number;
+    errorMessage: string | null;
     hasNextPage: boolean;
+    phase: VibeLoadPhase | null;
     hasPreviousPage: boolean;
-    paginationDetail: string | null;
-    requestNextPage: (() => void | Promise<void>) | null;
-    requestPreviousPage: (() => void | Promise<void>) | null;
-    showStatusBadges: boolean;
     active: boolean;
     reportAssetError: VibeAssetErrorReporter | null;
     reportAssetLoad: VibeAssetLoadReporter | null;
     allowExhaustedNextPageRefresh: boolean;
     commitPendingAppend: (() => void | Promise<void>) | null;
     pendingAppendItems: VibeViewerItem[];
+    requestNextPage: (() => void | Promise<void>) | null;
+    requestPreviousPage: (() => void | Promise<void>) | null;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

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

@@ -0,0 +1,21 @@
+import type { VibeEmptyStateSlotProps } from './viewer-core/surfaceSlots';
+type __VLS_Props = {
+    message: string;
+    mode: VibeEmptyStateSlotProps['mode'];
+    surface: VibeEmptyStateSlotProps['surface'];
+};
+declare var __VLS_1: {}, __VLS_3: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+} & {
+    default?: (props: typeof __VLS_3) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/lib/components/viewer-core/autoResolveHelpers.d.ts

@@ -13,7 +13,7 @@ export type ResolveFn = (params: {
     previousPage?: string | null;
 }>;
 export type VibeAutoDirection = 'backward' | 'forward';
-export declare function isActiveLoadPhase(phase: VibeLoadPhase): phase is "filling" | "loading" | "reloading";
+export declare function isActiveLoadPhase(phase: VibeLoadPhase): phase is "filling" | "initializing" | "refreshing" | "loading";
 export declare function normalizePageSize(value: number | undefined): number;
 export declare function getCursorKey(cursor: string | null): string;
 export declare function clamp(value: number, min: number, max: number): number;

package/lib/components/viewer-core/removalState.d.ts

@@ -2,7 +2,8 @@ export interface VibeRemoveResult {
     ids: string[];
 }
 export type VibeFeedMode = 'dynamic' | 'static';
-export type VibeLoadPhase = 'failed' | 'filling' | 'idle' | 'loading' | 'reloading';
+export type VibeLoadPhase = 'failed' | 'filling' | 'idle' | 'initializing' | 'loading' | 'refreshing';
+export type VibeSurfaceMode = 'fullscreen' | 'list';
 export interface VibeStatus {
     activeIndex: number;
     currentCursor: string | null;
@@ -12,15 +13,15 @@ export interface VibeStatus {
     fillTargetCount: number | null;
     hasNextPage: boolean;
     hasPreviousPage: boolean;
-    isAutoMode: boolean;
     itemCount: number;
     loadState: 'failed' | 'loaded' | 'loading';
-    mode: VibeFeedMode | null;
+    mode: VibeFeedMode;
     nextCursor: string | null;
     phase: VibeLoadPhase;
     previousCursor: string | null;
     removedCount: number;
-    surfaceMode: 'fullscreen' | 'list';
+    removedIds: readonly string[];
+    surfaceMode: VibeSurfaceMode;
 }
 export interface VibeHandle {
     cancel: () => void;

package/lib/components/viewer-core/surfaceSlots.d.ts

@@ -7,7 +7,15 @@ export type VibeSurfaceSlotProps = {
     paginationDetail: string | null;
     total: number;
 };
-export type VibeSurfaceStatusKind = 'end' | 'loading-more';
+export type VibeEmptyStateMode = 'inline' | 'badge' | 'hidden';
+export type VibeEmptyStateSlotProps = {
+    loading: boolean;
+    message: string;
+    mode: Exclude<VibeEmptyStateMode, 'hidden'>;
+    surface: 'fullscreen' | 'grid';
+    total: number;
+};
+export type VibeSurfaceStatusKind = 'end' | 'failed' | 'filling' | 'initializing' | 'loading-more' | 'refreshing';
 export type VibeFullscreenStatusSlotProps = VibeSurfaceSlotProps & {
     kind: VibeSurfaceStatusKind;
     message: string;

package/lib/components/viewer-core/surfaceStatus.d.ts

@@ -0,0 +1,18 @@
+import type { VibeLoadPhase } from './removalState';
+import type { VibeSurfaceStatusKind } from './surfaceSlots';
+export interface VibeSurfaceStatus {
+    kind: VibeSurfaceStatusKind;
+    message: string;
+}
+export declare function resolveVibeSurfacePhase(options: {
+    itemCount: number;
+    loading: boolean;
+    phase?: VibeLoadPhase | null;
+}): VibeLoadPhase;
+export declare function getVibeSurfaceStatus(options: {
+    errorMessage?: string | null;
+    hasItems: boolean;
+    hasNextPage: boolean;
+    phase: VibeLoadPhase;
+    surface: 'fullscreen' | 'grid';
+}): VibeSurfaceStatus | null;

package/lib/components/viewer-core/useController.d.ts

@@ -1,10 +1,9 @@
+import type { VibeSurfaceMode } from './removalState';
 import { type VibeEmit, type VibeProps } from './useDataSource';
 export declare const DESKTOP_BREAKPOINT_PX = 1024;
-type VibeDesktopSurface = 'fullscreen' | 'list';
 export declare function useController(props: Readonly<VibeProps>, emit: VibeEmit): {
     cancel: () => void;
     isDesktop: import("vue").ComputedRef<boolean>;
-    listRestoreToken: import("vue").Ref<number, number>;
     loadNext: () => Promise<void>;
     loadPrevious: () => Promise<void>;
     openFullscreen: (index: number) => void;
@@ -20,38 +19,37 @@ export declare function useController(props: Readonly<VibeProps>, emit: VibeEmit
         readonly fillTargetCount: number | null;
         readonly hasNextPage: boolean;
         readonly hasPreviousPage: boolean;
-        readonly isAutoMode: boolean;
         readonly itemCount: number;
         readonly loadState: "failed" | "loaded" | "loading";
-        readonly mode: import("./removalState").VibeFeedMode | null;
+        readonly mode: import("./removalState").VibeFeedMode;
         readonly nextCursor: string | null;
         readonly phase: import("./removalState").VibeLoadPhase;
         readonly previousCursor: string | null;
         readonly removedCount: number;
-        readonly surfaceMode: "fullscreen" | "list";
+        readonly removedIds: readonly string[];
+        readonly surfaceMode: VibeSurfaceMode;
     };
-    surfaceMode: import("vue").ComputedRef<VibeDesktopSurface>;
+    surfaceMode: import("vue").ComputedRef<VibeSurfaceMode>;
     activeIndex: import("vue").ComputedRef<number>;
     canRefreshExhaustedNextPage: import("vue").ComputedRef<boolean>;
     canRetryInitialLoad: import("vue").ComputedRef<boolean>;
     clearRemoved: () => void;
     commitPendingAppend: () => Promise<void>;
     currentCursor: import("vue").ComputedRef<string | null>;
-    errorMessage: import("vue").ComputedRef<string | null>;
-    fillCollectedCount: import("vue").ComputedRef<number | null>;
-    fillDelayRemainingMs: import("vue").ComputedRef<number | null>;
-    fillTargetCount: import("vue").ComputedRef<number | null>;
+    errorMessage: import("vue").Ref<string | null, string | null>;
+    fillCollectedCount: import("vue").Ref<number | null, number | null>;
+    fillDelayRemainingMs: import("vue").Ref<number | null, number | null>;
+    fillTargetCount: import("vue").Ref<number | null, number | null>;
     getRemovedIds: () => string[];
     hasNextPage: import("vue").ComputedRef<boolean>;
     hasPreviousPage: import("vue").ComputedRef<boolean>;
-    isAutoMode: import("vue").ComputedRef<boolean>;
     items: import("vue").ComputedRef<import("../viewer").VibeViewerItem[]>;
     loading: import("vue").ComputedRef<boolean>;
-    mode: import("vue").ComputedRef<import("./removalState").VibeFeedMode | null>;
+    mode: import("vue").ComputedRef<import("./removalState").VibeFeedMode>;
     nextCursor: import("vue").ComputedRef<string | null>;
     paginationDetail: import("vue").ComputedRef<string | null>;
     pendingAppendItems: import("vue").ComputedRef<import("../viewer").VibeViewerItem[]>;
-    phase: import("vue").ComputedRef<import("./removalState").VibeLoadPhase>;
+    phase: import("vue").Ref<import("./removalState").VibeLoadPhase, import("./removalState").VibeLoadPhase>;
     prefetchNextPage: () => Promise<void>;
     prefetchPreviousPage: () => Promise<void>;
     previousCursor: import("vue").ComputedRef<string | null>;
@@ -69,4 +67,3 @@ export declare function useController(props: Readonly<VibeProps>, emit: VibeEmit
         ids: string[];
     } | null;
 };
-export {};

package/lib/components/viewer-core/useDataSource.d.ts

@@ -1,6 +1,7 @@
 import type { VibeViewerItem } from '../viewer';
+import type { VibeEmptyStateMode } from './surfaceSlots';
 export type { VibeHandle, VibeRemoveResult } from './removalState';
-export type { VibeFeedMode, VibeLoadPhase } from './removalState';
+export type { VibeFeedMode, VibeLoadPhase, VibeSurfaceMode } from './removalState';
 export interface VibeResolveParams {
     cursor: string | null;
     pageSize: number;
@@ -18,46 +19,24 @@ export interface VibeInitialState {
     previousCursor?: string | null;
     activeIndex?: number;
 }
-interface VibeSharedProps {
-    hasPreviousPage?: boolean;
-    paginationDetail?: string | null;
-    requestNextPage?: (() => void | Promise<void>) | null;
-    requestPreviousPage?: (() => void | Promise<void>) | null;
-    showEndBadge?: boolean;
-    showStatusBadges?: boolean;
-}
-export interface VibeControlledProps extends VibeSharedProps {
-    items: VibeViewerItem[];
-    activeIndex?: number;
-    fillDelayMs?: never;
-    fillDelayStepMs?: never;
-    initialState?: never;
-    loading?: boolean;
-    hasNextPage?: boolean;
-    mode?: never;
-    resolve?: never;
-    initialCursor?: never;
-    pageSize?: never;
-}
-export interface VibeAutoProps extends VibeSharedProps {
-    resolve: (params: VibeResolveParams) => Promise<VibeResolveResult>;
+export interface VibeProps {
+    emptyStateMode?: VibeEmptyStateMode;
     fillDelayMs?: number;
     fillDelayStepMs?: number;
     initialCursor?: string | null;
     initialState?: VibeInitialState;
     mode?: import('./removalState').VibeFeedMode;
     pageSize?: number;
-    items?: never;
-    activeIndex?: never;
-    hasPreviousPage?: never;
-    loading?: never;
-    hasNextPage?: never;
-    paginationDetail?: never;
-    requestNextPage?: never;
-    requestPreviousPage?: never;
+    paginationDetail?: string | null;
+    resolve?: (params: VibeResolveParams) => Promise<VibeResolveResult>;
+    showEndBadge?: boolean;
+    showStatusBadges?: boolean;
+    surfaceMode?: import('./removalState').VibeSurfaceMode;
+}
+export interface VibeEmit {
+    (event: 'update:activeIndex', value: number): void;
+    (event: 'update:surfaceMode', value: import('./removalState').VibeSurfaceMode): void;
 }
-export type VibeProps = VibeControlledProps | VibeAutoProps;
-export type VibeEmit = (event: 'update:activeIndex', value: number) => void;
 export declare function useDataSource(props: Readonly<VibeProps>, emit: VibeEmit): {
     activeIndex: import("vue").ComputedRef<number>;
     canRefreshExhaustedNextPage: import("vue").ComputedRef<boolean>;
@@ -66,23 +45,22 @@ export declare function useDataSource(props: Readonly<VibeProps>, emit: VibeEmit
     clearRemoved: () => void;
     commitPendingAppend: () => Promise<void>;
     currentCursor: import("vue").ComputedRef<string | null>;
-    errorMessage: import("vue").ComputedRef<string | null>;
-    fillCollectedCount: import("vue").ComputedRef<number | null>;
-    fillDelayRemainingMs: import("vue").ComputedRef<number | null>;
-    fillTargetCount: import("vue").ComputedRef<number | null>;
+    errorMessage: import("vue").Ref<string | null, string | null>;
+    fillCollectedCount: import("vue").Ref<number | null, number | null>;
+    fillDelayRemainingMs: import("vue").Ref<number | null, number | null>;
+    fillTargetCount: import("vue").Ref<number | null, number | null>;
     getRemovedIds: () => string[];
     hasNextPage: import("vue").ComputedRef<boolean>;
     hasPreviousPage: import("vue").ComputedRef<boolean>;
-    isAutoMode: import("vue").ComputedRef<boolean>;
     items: import("vue").ComputedRef<VibeViewerItem[]>;
     loading: import("vue").ComputedRef<boolean>;
     loadNext: () => Promise<void>;
     loadPrevious: () => Promise<void>;
-    mode: import("vue").ComputedRef<import("./removalState").VibeFeedMode | null>;
+    mode: import("vue").ComputedRef<import("./removalState").VibeFeedMode>;
     nextCursor: import("vue").ComputedRef<string | null>;
     paginationDetail: import("vue").ComputedRef<string | null>;
     pendingAppendItems: import("vue").ComputedRef<VibeViewerItem[]>;
-    phase: import("vue").ComputedRef<import("./removalState").VibeLoadPhase>;
+    phase: import("vue").Ref<import("./removalState").VibeLoadPhase, import("./removalState").VibeLoadPhase>;
     prefetchNextPage: () => Promise<void>;
     prefetchPreviousPage: () => Promise<void>;
     previousCursor: import("vue").ComputedRef<string | null>;

package/lib/components/viewer-core/useEdgeBoundary.d.ts

@@ -2,6 +2,7 @@ import { type Ref } from 'vue';
 export type VibeMasonryEdgeDirection = 'bottom' | 'top';
 export declare function useEdgeBoundary(options: {
     direction: VibeMasonryEdgeDirection;
+    interactionLocked?: Ref<boolean>;
     hasPage: Ref<boolean>;
     isAtBoundary: () => boolean;
     loading: Ref<boolean>;

package/lib/components/viewer-core/useFullscreenSurfaceMedia.d.ts

@@ -0,0 +1,23 @@
+import type { Ref } from 'vue';
+import type { VibeViewerItem } from '../viewer';
+export declare function useFullscreenSurfaceMedia(options: {
+    active: Ref<boolean | undefined>;
+    resolvedActiveIndex: Ref<number>;
+    viewer: {
+        getAssetErrorKind: (id: string) => unknown;
+        getAssetErrorLabel: (id: string) => string | null | undefined;
+        getImageSource: (item: VibeViewerItem) => string | undefined;
+        isImageReady: (id: string) => boolean;
+        isMediaReady: (id: string) => boolean;
+    };
+}): {
+    getAssetErrorKind: (item: VibeViewerItem) => unknown;
+    getAssetErrorLabel: (item: VibeViewerItem) => string;
+    getFullscreenImageSource: (index: number, item: VibeViewerItem) => string | undefined;
+    getFullscreenMediaSource: (index: number, item: VibeViewerItem) => string | undefined;
+    getItemKey: (item: VibeViewerItem) => string;
+    getMediaActionLabel: (action: "Play" | "Pause", item: VibeViewerItem) => string;
+    isAssetErrored: (index: number, item: VibeViewerItem) => boolean;
+    isAssetLoading: (index: number, item: VibeViewerItem) => boolean;
+    shouldPreloadSlideAsset: (index: number) => boolean;
+};