@wyxos/vibe 3.1.7 → 3.1.9

package/README.md

@@ -147,28 +147,24 @@ Vibe owns:
 - initial retry state
 - removal-aware feed navigation
 
-### Feed strategies
-
-Vibe supports two feed strategies:
-
-- `dynamic`:
-  - default behavior
-  - if a resolve returns fewer items than `pageSize`, Vibe enters a fill loop
-  - 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
+### Default paging behavior
+
+Vibe has one built-in paging model:
+
+- if a resolve returns fewer visible items than `pageSize`, Vibe enters a fill loop
+- 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
+- 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 and reconciles only that page's content in the grid
+- if that boundary refresh comes back empty, the same boundary attempt can continue to the next or previous cursor
+- when the trailing edge is exhausted, another bottom-edge attempt reloads the trailing cursor so newly available pages can be discovered
 
 Example:
 
 ```vue
 <VibeLayout
   :resolve="resolve"
-  mode="dynamic"
   :page-size="25"
   :fill-delay-ms="2000"
   :fill-delay-step-ms="1000"
@@ -292,13 +288,13 @@ type VibeStatus = {
   currentCursor: string | null
   errorMessage: string | null
   fillCollectedCount: number | null
+  fillCursor: string | null
   fillDelayRemainingMs: number | null
   fillTargetCount: number | null
   hasNextPage: boolean
   hasPreviousPage: boolean
   itemCount: number
   loadState: 'failed' | 'loaded' | 'loading'
-  mode: 'dynamic' | 'static'
   nextBoundaryLoadProgress: number
   nextCursor: string | null
   pageLoadingLocked: boolean
@@ -402,8 +398,7 @@ Routes:
 
 - `/` - default feed surface
 - `/documentation` - in-app documentation
-- `/demo/dynamic-feed` - dynamic feed fill-loop demo
-- `/demo/advanced-integration` - static feed, removals, and paging-lock demo
+- `/demo/feed-behavior` - unified fill, retry, boundary refresh, removals, and paging-lock demo
 - `/debug/fake-server` - fake-server inspection route
 
 ## Local development

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

@@ -47,4 +47,4 @@ export declare function hydrateAutoResolveState(options: {
 };
 export declare function getActiveOccurrenceKey(items: VibeViewerItem[], activeIndex: number): string | null;
 export declare function getSyncedActiveIndex(items: VibeViewerItem[], activeIndex: number, anchorOccurrenceKey?: string | null): number;
-export declare function isStaticBoundaryUnderfilled(bucket: VibeAutoBucket | null, removedIds: Set<string>, pageSize: number): boolean;
+export declare function isBoundaryPageUnderfilled(bucket: VibeAutoBucket | null, removedIds: Set<string>, pageSize: number): boolean;

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

@@ -1,7 +1,7 @@
-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 const DEFAULT_FILL_DELAY_MS = 2000;
+export declare const DEFAULT_FILL_DELAY_STEP_MS = 1000;
+export declare function getFillDelayMs(fillRequestIndex: number, baseDelayMs?: number, stepDelayMs?: number): number;
+export declare function normalizeFillDelayMs(value: number | undefined, fallback: number): number;
 export declare function useFillDelayCountdown(): {
     clear: (resolvePending?: boolean) => void;
     remainingMs: import("vue").Ref<number | null, number | null>;

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

@@ -1,7 +1,6 @@
 export interface VibeRemoveResult {
     ids: string[];
 }
-export type VibeFeedMode = 'dynamic' | 'static';
 export type VibeLoadPhase = 'failed' | 'filling' | 'idle' | 'initializing' | 'loading' | 'refreshing';
 export type VibeSurfaceMode = 'fullscreen' | 'list';
 export interface VibeStatus {
@@ -9,13 +8,13 @@ export interface VibeStatus {
     currentCursor: string | null;
     errorMessage: string | null;
     fillCollectedCount: number | null;
+    fillCursor: string | null;
     fillDelayRemainingMs: number | null;
     fillTargetCount: number | null;
     hasNextPage: boolean;
     hasPreviousPage: boolean;
     itemCount: number;
     loadState: 'failed' | 'loaded' | 'loading';
-    mode: VibeFeedMode;
     nextBoundaryLoadProgress: number;
     nextCursor: string | null;
     pageLoadingLocked: boolean;

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

@@ -1,6 +1,6 @@
 import { type Ref } from 'vue';
 import type { VibeViewerItem } from '../viewer';
-import type { VibeFeedMode, VibeLoadPhase } from './removalState';
+import type { VibeLoadPhase } from './removalState';
 import { type ResolveFn } from './autoResolveHelpers';
 type VibeAutoEmit = (event: 'update:activeIndex', value: number) => void;
 export declare function useAutoResolveSource(options: {
@@ -15,7 +15,6 @@ export declare function useAutoResolveSource(options: {
         nextCursor?: string | null;
         previousCursor?: string | null;
     };
-    mode?: VibeFeedMode;
     pageSize?: number;
     removedIds: Ref<Set<string>>;
     resolve?: ResolveFn;
@@ -28,6 +27,7 @@ export declare function useAutoResolveSource(options: {
     currentCursor: import("vue").ComputedRef<string | null>;
     errorMessage: Ref<string | null, string | null>;
     fillCollectedCount: Ref<number | null, number | null>;
+    fillCursor: Ref<string | null, string | null>;
     fillDelayRemainingMs: Ref<number | null, number | null>;
     fillTargetCount: Ref<number | null, number | null>;
     hasNextPage: import("vue").ComputedRef<boolean>;
@@ -37,7 +37,6 @@ export declare function useAutoResolveSource(options: {
     items: import("vue").ComputedRef<VibeViewerItem[]>;
     lockPageLoading: () => void;
     loading: import("vue").ComputedRef<boolean>;
-    mode: import("vue").ComputedRef<VibeFeedMode>;
     maybePrefetchAround: () => Promise<void>;
     nextCursor: import("vue").ComputedRef<string | null>;
     pendingAppendItems: import("vue").ComputedRef<VibeViewerItem[]>;

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

@@ -20,13 +20,13 @@ export declare function useController(props: Readonly<VibeProps>, emit: VibeEmit
         readonly currentCursor: string | null;
         readonly errorMessage: string | null;
         readonly fillCollectedCount: number | null;
+        readonly fillCursor: string | null;
         readonly fillDelayRemainingMs: number | null;
         readonly fillTargetCount: number | null;
         readonly hasNextPage: boolean;
         readonly hasPreviousPage: boolean;
         readonly itemCount: number;
         readonly loadState: "failed" | "loaded" | "loading";
-        readonly mode: import("./removalState").VibeFeedMode;
         readonly nextBoundaryLoadProgress: number;
         readonly nextCursor: string | null;
         readonly pageLoadingLocked: boolean;
@@ -47,6 +47,7 @@ export declare function useController(props: Readonly<VibeProps>, emit: VibeEmit
     currentCursor: import("vue").ComputedRef<string | null>;
     errorMessage: import("vue").Ref<string | null, string | null>;
     fillCollectedCount: import("vue").Ref<number | null, number | null>;
+    fillCursor: import("vue").Ref<string | null, string | null>;
     fillDelayRemainingMs: import("vue").Ref<number | null, number | null>;
     fillTargetCount: import("vue").Ref<number | null, number | null>;
     getRemovedIds: () => string[];
@@ -55,7 +56,6 @@ export declare function useController(props: Readonly<VibeProps>, emit: VibeEmit
     isPageLoadingLocked: import("vue").Ref<boolean, boolean>;
     items: import("vue").ComputedRef<import("../viewer").VibeViewerItem[]>;
     loading: import("vue").ComputedRef<boolean>;
-    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[]>;

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

@@ -1,7 +1,7 @@
 import type { VibeViewerItem } from '../viewer';
 import type { VibeEmptyStateMode } from './surfaceSlots';
 export type { VibeHandle, VibeRemoveResult } from './removalState';
-export type { VibeFeedMode, VibeLoadPhase, VibeSurfaceMode } from './removalState';
+export type { VibeLoadPhase, VibeSurfaceMode } from './removalState';
 export interface VibeResolveParams {
     cursor: string | null;
     pageSize: number;
@@ -26,7 +26,6 @@ export interface VibeProps {
     initialCursor?: string | null;
     initialState?: VibeInitialState;
     loopFullscreenVideo?: boolean;
-    mode?: import('./removalState').VibeFeedMode;
     pageSize?: number;
     paginationDetail?: string | null;
     resolve?: (params: VibeResolveParams) => Promise<VibeResolveResult>;
@@ -49,6 +48,7 @@ export declare function useDataSource(props: Readonly<VibeProps>, emit: VibeEmit
     currentCursor: import("vue").ComputedRef<string | null>;
     errorMessage: import("vue").Ref<string | null, string | null>;
     fillCollectedCount: import("vue").Ref<number | null, number | null>;
+    fillCursor: import("vue").Ref<string | null, string | null>;
     fillDelayRemainingMs: import("vue").Ref<number | null, number | null>;
     fillTargetCount: import("vue").Ref<number | null, number | null>;
     getRemovedIds: () => string[];
@@ -60,7 +60,6 @@ export declare function useDataSource(props: Readonly<VibeProps>, emit: VibeEmit
     loading: import("vue").ComputedRef<boolean>;
     loadNext: () => Promise<void>;
     loadPrevious: () => Promise<void>;
-    mode: import("vue").ComputedRef<import("./removalState").VibeFeedMode>;
     nextCursor: import("vue").ComputedRef<string | null>;
     paginationDetail: import("vue").ComputedRef<string | null>;
     pendingAppendItems: import("vue").ComputedRef<VibeViewerItem[]>;

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

@@ -3,7 +3,7 @@ import type { VibeViewerItem } from '../viewer';
 import type { VibeAssetErrorReporter, VibeAssetLoadReporter } from './assetErrors';
 import { formatPlaybackTime } from './format';
 import type { VibeLoadPhase } from './removalState';
-export type { VibeResolveParams, VibeResolveResult, VibeEmit, VibeFeedMode, VibeHandle, VibeInitialState, VibeLoadPhase, VibeProps, VibeSurfaceMode, } from './useDataSource';
+export type { VibeResolveParams, VibeResolveResult, VibeEmit, VibeHandle, VibeInitialState, VibeLoadPhase, VibeProps, VibeSurfaceMode, } from './useDataSource';
 export type { VibeAssetErrorKind } from './loadError';
 export type { VibeStatus } from './removalState';
 export type { VibeAssetErrorEvent, VibeAssetErrorReporter, VibeAssetErrorSurface, VibeAssetLoadEvent, VibeAssetLoadReporter, VibeAssetLoadSurface } from './assetErrors';