@wyxos/vibe 3.0.3 → 3.0.5

package/README.md

@@ -65,20 +65,27 @@ async function resolve({ cursor, pageSize }: VibeResolveParams): Promise<VibeRes
 </template>
 ```
 
-Optional auto-mode pacing props:
+Optional pacing props:
 
 ```vue
 <VibeLayout
   :resolve="resolve"
-  :fill-delay-ms="1000"
-  :fill-delay-step-ms="250"
+  :fill-delay-ms="2000"
+  :fill-delay-step-ms="1000"
+  :show-end-badge="false"
+  :show-status-badges="false"
+  surface-mode="fullscreen"
 />
 ```
 
 - `fill-delay-ms`: base delay before the first chained fill request
 - `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 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
@@ -90,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
@@ -129,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:
 
@@ -167,7 +190,7 @@ async function resolve({ cursor, pageSize }: VibeResolveParams): Promise<VibeRes
 </template>
 ```
 
-In this mode, Vibe owns:
+Vibe owns:
 
 - loaded items
 - active index
@@ -176,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
@@ -184,48 +207,25 @@ Auto mode also supports two feed strategies:
   - it waits `fillDelayMs`, then `fillDelayMs + fillDelayStepMs`, and so on for each chained request
   - it keeps accumulating results until the collected count reaches `pageSize` or there is no further cursor
   - then it commits that batch into the layout once
+  - when the trailing edge is exhausted, another bottom-edge attempt reloads the trailing cursor so newly available pages can be discovered
 - `static`:
   - before advancing at the bottom or top, Vibe checks whether the current boundary page is underfilled after local removals
   - 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
@@ -323,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'
 }
 ```
@@ -341,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
@@ -348,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

@@ -2,15 +2,23 @@ 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 { VibeLoadPhase } from './viewer-core/useViewer';
 import './viewer-core/fullscreenMediaBar.css';
-type __VLS_Props = VibeControlledProps & {
+interface FullscreenSurfaceProps {
     active?: boolean;
+    activeIndex?: number;
+    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 = {
     'fullscreen-aside'?: (props: VibeSurfaceSlotProps) => unknown;
     'fullscreen-header-actions'?: (props: VibeSurfaceSlotProps) => unknown;
@@ -21,18 +29,21 @@ 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;
     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,12 +1,13 @@
 import { type Component } from 'vue';
 import type { VibeViewerItem } from './viewer';
-import type { VibeEmptyStateSlotProps, VibeFullscreenStatusSlotProps, VibeGridStatusSlotProps, VibeSurfaceSlotProps } from './viewer-core/surfaceSlots';
+import { type VibeAssetErrorEvent, type VibeAssetLoadEvent } from './viewer-core/assetErrors';
+import type { VibeFullscreenStatusSlotProps, VibeGridStatusSlotProps, VibeSurfaceSlotProps } from './viewer-core/surfaceSlots';
+import type { VibeHandle, VibeProps } from './viewer-core/useViewer';
 type __VLS_Slots = {
     'fullscreen-aside'?: (props: VibeSurfaceSlotProps) => unknown;
     'fullscreen-header-actions'?: (props: VibeSurfaceSlotProps) => unknown;
     'fullscreen-overlay'?: (props: VibeSurfaceSlotProps) => unknown;
     'fullscreen-status'?: (props: VibeFullscreenStatusSlotProps) => unknown;
-    'empty-state'?: (props: VibeEmptyStateSlotProps) => unknown;
     'grid-footer'?: () => unknown;
     'grid-item-overlay'?: (props: {
         active: boolean;
@@ -22,7 +23,17 @@ type __VLS_Slots = {
         item: VibeViewerItem;
     }) => unknown;
 };
-declare const __VLS_base: import("vue").DefineSetupFnComponent<Record<string, any>, {}, {}, Record<string, any> & {}, import("vue").PublicProps>;
+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<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>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;

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

@@ -1,10 +1,8 @@
 import type { Component } from 'vue';
 import type { VibeViewerItem } from './viewer';
 import type { VibeAssetErrorReporter, VibeAssetLoadReporter } from './viewer-core/assetErrors';
-import { type VibeAssetLoadQueue } from './viewer-core/useAssetLoadQueue';
 type __VLS_Props = {
     active?: boolean;
-    assetLoadQueue?: VibeAssetLoadQueue | null;
     index?: number;
     item: VibeViewerItem;
     reportAssetError?: VibeAssetErrorReporter | null;
@@ -34,7 +32,6 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     reportAssetError: VibeAssetErrorReporter | null;
     reportAssetLoad: VibeAssetLoadReporter | null;
     index: number;
-    assetLoadQueue: VibeAssetLoadQueue | null;
     surfaceActive: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;

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

@@ -2,23 +2,24 @@ 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 { VibeAssetLoadQueue } from './viewer-core/useAssetLoadQueue';
+import type { VibeLoadPhase } from './viewer-core/useViewer';
 type __VLS_Props = {
     active?: boolean;
     activeIndex?: number;
-    assetLoadQueue?: VibeAssetLoadQueue | null;
+    allowExhaustedNextPageRefresh?: boolean;
     commitPendingAppend?: (() => void | Promise<void>) | null;
+    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 = {
@@ -45,19 +46,21 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {},
     "onOpen-fullscreen"?: ((index: number) => any) | undefined;
 }>, {
     loading: boolean;
+    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;
-    assetLoadQueue: VibeAssetLoadQueue | 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/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/fillDelay.d.ts

@@ -1,5 +1,5 @@
-export declare const DEFAULT_DYNAMIC_FILL_DELAY_MS = 1000;
-export declare const DEFAULT_DYNAMIC_FILL_DELAY_STEP_MS = 250;
+export declare const DEFAULT_DYNAMIC_FILL_DELAY_MS = 2000;
+export declare const DEFAULT_DYNAMIC_FILL_DELAY_STEP_MS = 1000;
 export declare function getDynamicFillDelayMs(fillRequestIndex: number, baseDelayMs?: number, stepDelayMs?: number): number;
 export declare function normalizeDynamicFillDelayMs(value: number | undefined, fallback: number): number;
 export declare function useFillDelayCountdown(): {

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

@@ -2,7 +2,7 @@ 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;
@@ -13,14 +13,14 @@ 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;
+    removedIds: readonly string[];
     surfaceMode: VibeSurfaceMode;
 }
 export interface VibeHandle {

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

@@ -7,7 +7,7 @@ export type VibeSurfaceSlotProps = {
     paginationDetail: string | null;
     total: number;
 };
-export type VibeSurfaceStatusKind = 'end' | 'loading-more';
+export type VibeSurfaceStatusKind = 'end' | 'failed' | 'filling' | 'initializing' | 'loading-more' | 'refreshing';
 export type VibeFullscreenStatusSlotProps = VibeSurfaceSlotProps & {
     kind: VibeSurfaceStatusKind;
     message: string;
@@ -20,8 +20,3 @@ export type VibeGridStatusSlotProps = {
     paginationDetail: string | null;
     total: number;
 };
-export type VibeEmptyStateSlotProps = {
-    canRetry: boolean;
-    loading: boolean;
-    retry: () => void | Promise<void>;
-};

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

@@ -14,10 +14,9 @@ export interface VibeAssetLoadLease {
     refresh: () => void;
     release: () => void;
 }
-export interface VibeAssetLoadQueue {
-    getLimits: () => VibeAssetLoadQueueLimits;
+export declare function createAssetLoadQueue(limits?: VibeAssetLoadQueueLimits): {
     request: (options: VibeAssetLoadRequest) => VibeAssetLoadLease;
-    setLimits: (limits?: Partial<VibeAssetLoadQueueLimits> | null) => void;
-}
-export declare function resolveAssetLoadQueueLimits(limits?: Partial<VibeAssetLoadQueueLimits> | null): VibeAssetLoadQueueLimits;
-export declare function createAssetLoadQueue(initialLimits?: Partial<VibeAssetLoadQueueLimits> | null): VibeAssetLoadQueue;
+};
+export declare const defaultAssetLoadQueue: {
+    request: (options: VibeAssetLoadRequest) => VibeAssetLoadLease;
+};

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

@@ -23,6 +23,7 @@ export declare function useAutoResolveSource(options: {
     activeIndex: import("vue").ComputedRef<number>;
     canRetryInitialLoad: import("vue").ComputedRef<boolean>;
     cancel: () => void;
+    canRefreshTrailingBoundary: import("vue").ComputedRef<boolean>;
     commitPendingAppend: () => Promise<void>;
     currentCursor: import("vue").ComputedRef<string | null>;
     errorMessage: Ref<string | null, string | null>;

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

@@ -1,11 +1,9 @@
 import type { VibeSurfaceMode } from './removalState';
 import { type VibeEmit, type VibeProps } from './useDataSource';
 export declare const DESKTOP_BREAKPOINT_PX = 1024;
-type VibeControllerEmit = VibeEmit & ((event: 'update:surfaceMode', value: VibeSurfaceMode) => void);
-export declare function useController(props: Readonly<VibeProps>, emit: VibeControllerEmit): {
+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;
@@ -21,37 +19,37 @@ export declare function useController(props: Readonly<VibeProps>, emit: VibeCont
         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 removedIds: readonly string[];
         readonly surfaceMode: VibeSurfaceMode;
     };
     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: VibeCont
         ids: string[];
     } | null;
 };
-export {};

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

@@ -1,8 +1,6 @@
 import type { VibeViewerItem } from '../viewer';
-import { type VibeSurfaceMode } from './removalState';
-import type { VibeAssetLoadQueueLimits } from './useAssetLoadQueue';
 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;
@@ -20,71 +18,47 @@ export interface VibeInitialState {
     previousCursor?: string | null;
     activeIndex?: number;
 }
-interface VibeSharedProps {
-    assetLoadLimits?: Partial<VibeAssetLoadQueueLimits>;
-    hasPreviousPage?: boolean;
-    paginationDetail?: string | null;
-    requestNextPage?: (() => void | Promise<void>) | null;
-    requestPreviousPage?: (() => void | Promise<void>) | null;
-    showStatusBadges?: boolean;
-    surfaceMode?: VibeSurfaceMode;
-}
-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 {
     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>;
     canRetryInitialLoad: import("vue").ComputedRef<boolean>;
     cancel: () => void;
     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/useMasonryList.d.ts

@@ -2,6 +2,7 @@ import { type Ref } from 'vue';
 import type { VibeViewerItem } from '../viewer';
 export declare function useVibeMasonryList(options: {
     active: Ref<boolean>;
+    allowExhaustedNextPageRefresh: Ref<boolean>;
     items: Ref<VibeViewerItem[]>;
     activeIndex: Ref<number>;
     loading: Ref<boolean>;
@@ -12,12 +13,10 @@ export declare function useVibeMasonryList(options: {
     commitPendingAppend: Ref<(() => void | Promise<void>) | null | undefined>;
     requestNextPage: Ref<(() => void | Promise<void>) | null | undefined>;
     requestPreviousPage: Ref<(() => void | Promise<void>) | null | undefined>;
-    restoreToken: Ref<number>;
     setActiveIndex: (index: number) => void;
 }): {
     columnWidth: import("vue").ComputedRef<number>;
     containerHeight: import("vue").ComputedRef<number>;
-    footerStatusMessage: import("vue").ComputedRef<"Loading the first page" | "Loading more items" | "End of list" | null>;
     getCardStyle: (index: number) => {
         height: string;
         width: string;