@wyxos/vibe 3.1.34 → 4.0.0

package/README.md

@@ -1,420 +1,643 @@
 # Vibe
 
-Vibe is an opinionated Vue 3 mixed-media feed and viewer engine for large datasets.
+Vibe is an initializable Vue 3 media feed with virtualized masonry and reel layouts.
 
-It is built for apps that need a virtualized desktop feed, fullscreen browsing, library-owned paging, removals, retries, and asset-failure handling without stitching together a masonry grid, lightbox, and feed state by hand.
+## Installation
 
-![Vibe desktop feed surface](./docs/readme-hero.jpg)
+```bash
+npm install @wyxos/vibe
+```
 
-[Live demo](https://vibe.wyxos.com/) · [In-app docs](https://vibe.wyxos.com/documentation)
+Import the packaged styles once in the consuming application:
 
-## Built for
+```ts
+import '@wyxos/vibe/style.css'
+```
 
-Vibe is built for applications that browse large mixed-media collections and need feed state to stay coherent as items load, fail, disappear, and move between desktop and fullscreen surfaces.
+## Remote feed
 
-It owns paging, fullscreen browsing, removals, retries, and asset-failure handling as part of one viewer model so those behaviors stay consistent under real feed pressure.
+```ts
+import { createVibe } from '@wyxos/vibe'
 
-Vibe is hardened in production through [Atlas](https://github.com/wyxos/atlas) as a downstream consumer.
+const vibe = createVibe({
+  target: '#gallery',
+  layout: 'responsive',
+  loadPage: async ({ cursor, signal }) => {
+    const response = await fetch(`/api/media?cursor=${cursor ?? ''}`, {
+      signal,
+    })
 
-## When Vibe fits
+    return response.json()
+  },
+})
 
-Use Vibe when your app needs:
+await vibe.mount()
+```
 
-- a large mixed-media feed of images, video, audio, and document-like items
-- library-owned paging driven by opaque cursors
-- a desktop masonry surface that opens into fullscreen
-- fullscreen-first behavior on mobile and tablet
-- built-in remove, restore, undo, retry, and asset-failure handling
-- a small customization surface through slots instead of a headless rendering API
+The target element must have a usable height. Vibe owns scrolling inside that target.
+In responsive layout, Vibe observes the target and uses reels on phones while
+keeping tablets and desktops in masonry. Use `masonry` or `reel` to force a
+renderer instead.
 
-## Quick start
+Phone reels load `preview.src`. Reels on tablets and desktops load the full
+`src`, including a reel forced with `layout: 'reel'` and a reel opened from a
+masonry card.
 
-Install the package and import the bundled stylesheet once:
+`loadPage` receives `cursor: null` for the initial request. It returns normalized Vibe items, the next opaque cursor, and an optional total:
 
-```bash
-npm i @wyxos/vibe
+```ts
+{
+  items: VibeItem[]
+  next: string | number | null
+  total?: number
+}
 ```
 
+## Static or preloaded feed
+
 ```ts
-import '@wyxos/vibe/style.css'
+const vibe = createVibe({
+  target: document.querySelector('#gallery')!,
+  layout: 'reel',
+  initialPage: {
+    items,
+    next: null,
+    total: items.length,
+  },
+})
+
+await vibe.mount()
 ```
 
-Tailwind scanning is not required for the package UI.
+Provide both `initialPage` and `loadPage` when preloaded items can continue to another cursor.
 
-### Plugin install
+## Custom card chrome
 
-The default export is the plugin:
+Use `cardHeader` and `cardFooter` to render application-owned regions above and
+below media:
 
 ```ts
-import { createApp } from 'vue'
-import App from './App.vue'
-
-import Vibe from '@wyxos/vibe'
-import '@wyxos/vibe/style.css'
-
-createApp(App)
-  .use(Vibe)
-  .mount('#app')
+import MediaInfo from './MediaInfo.vue'
+import MediaReactions from './MediaReactions.vue'
+
+const vibe = createVibe({
+  target: '#gallery',
+  layout: 'responsive',
+  loadPage,
+  cardHeader: {
+    component: MediaInfo,
+    height: 40,
+  },
+  cardFooter: {
+    component: MediaReactions,
+    height: 48,
+  },
+})
 ```
 
-That registers the global component as `VibeLayout`.
+The heights are CSS pixels and let Vibe include both regions in masonry before
+virtualized cards mount. In reel layout, one header and footer remain stationary
+while only the media viewport scrolls between posts. Each component controls its
+own content and alignment, and receives `item`, `layout`, `mediaSource`, zero-based `index`,
+`loadedCount`, the active `mediaItem`, its 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.
 
-### Direct import
+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
+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.
 
-If you prefer local registration, import `VibeLayout` directly:
+## Reel URLs with Vue Router
 
-```vue
-<script setup lang="ts">
-import {
-  VibeLayout,
-  type VibeResolveParams,
-  type VibeResolveResult,
-} from '@wyxos/vibe'
-import '@wyxos/vibe/style.css'
+Pass a Vue Router instance when the application should reflect the active reel
+in its URL. The consumer owns the route names and the item-to-location mapping:
 
-async function resolve({ cursor, pageSize }: VibeResolveParams): Promise<VibeResolveResult> {
-  const response = await fetch(`/api/feed?cursor=${cursor ?? ''}&pageSize=${pageSize}`)
-  return await response.json()
-}
-</script>
-
-<template>
-  <VibeLayout :resolve="resolve" />
-</template>
+```ts
+import { useRouter } from 'vue-router'
+import { createVibe } from '@wyxos/vibe'
+
+const router = useRouter()
+const vibe = createVibe({
+  target: '#gallery',
+  loadPage,
+  routing: {
+    router,
+    feed: { name: 'gallery' },
+    reel: ({ item }) => ({
+      name: 'gallery-file',
+      params: { fileId: String(item.postId) },
+    }),
+  },
+})
 ```
 
-## Core concepts
+Vibe pushes the first reel location, replaces it as the active reel changes,
+and replaces it with `feed` when the masonry-origin reel closes or responsive
+layout returns to masonry. The reel callback also receives the zero-based
+`index`, `loadedCount`, optional remote `total`, and whether the reel originated
+from `masonry` or the base `reel` layout. Return `null` to skip a URL update for
+an item. Vue Router is an optional peer dependency and is only needed when this
+integration is used.
+
+## Autofill
 
-### Item contract
+Autofill targets a number of new top-level cards after grouping and
+deduplication. `autofill.pageSize` is the minimum card target for one Vibe load
+cycle, not the server's own response size. For example, a server may return up
+to 30 cards per request while Vibe is configured with `pageSize: 40`; Vibe then
+follows cursors until the cycle contains at least 40 cards.
 
-Vibe keeps the item contract deliberately small:
+### Frontend autofill
+
+Frontend autofill follows cursors and commits the collected batch once the
+target is reached or the source is exhausted. Restore committed items with
+`initialPage`; its `next` value must follow the last restored item:
 
 ```ts
-type VibeViewerItem = {
-  id: string
-  type: 'image' | 'video' | 'audio' | 'other'
-  title?: string
-  url: string
-  preview?: {
-    url: string
-    width?: number
-    height?: number
-    mediaType?: 'image' | 'video'
-  }
-  healthCheck?: {
-    url: string
-    kind?: 'playback'
-  } | null
-  width?: number
-  height?: number
-  [key: string]: unknown
-}
+const restoredPage = await feedCache.read() // VibePage | null
+
+const vibe = createVibe({
+  target: '#gallery',
+  initialPage: restoredPage ?? undefined,
+  loadPage,
+  autofill: {
+    strategy: 'frontend',
+    pageSize: 40,
+    maxAdditionalPages: 10,
+    delayStepMs: 2_000,
+    delayMaxMs: 10_000,
+  },
+  onStateChange(state) {
+    void feedCache.write({
+      items: [...state.items],
+      next: state.next,
+      total: state.total ?? undefined,
+    })
+  },
+})
+
+await vibe.mount()
 ```
 
-Notes:
+There is no frontend session snapshot. With 25 restored cards and
+`pageSize: 40`, Vibe continues from `initialPage.next` until the load cycle has
+at least 40 unique cards. Without `initialPage`, Vibe starts at cursor `null`.
 
-- grid mode prefers `preview.url`, then falls back to `url`
-- fullscreen mode uses `url`
-- grid layout prefers preview dimensions, then root dimensions, then a square fallback tile
-- `other` stays intentionally broad so the consuming app can layer its own file subtypes and icon logic on top
-- `healthCheck` is optional and lets the app provide an explicit asset probe, for example when preview URLs are not enough to classify playback health reliably
+The first request is immediate. Each subsequent request waits
+`min(completedRequests * delayStepMs, delayMaxMs)`, so the defaults produce
+0s, 2s, 4s, 6s, 8s, then 10s between requests. Set both values to `0` when a
+frontend source should run without pacing. During a wait,
+`state.autofill.delayRemainingMs` counts down and `nextRequestAt` contains the
+absolute browser timestamp.
 
-### Resolve and feed state
+### Backend autofill
 
-Use `resolve` when you want Vibe to own the paging loop:
+Backend autofill lets the consuming application enqueue and cancel durable
+work. A restoration endpoint should return the currently committed page and,
+when work remains active, its persisted session:
 
 ```ts
-type VibeResolveParams = {
-  cursor: string | null
-  pageSize: number
-  signal?: AbortSignal
+interface BackendRestoration {
+  initialPage?: VibePage
+  session?: VibeAutofillSessionSnapshot
 }
 
-type VibeResolveResult = {
-  items: VibeViewerItem[]
-  nextPage: string | null
-  previousPage?: string | null
-}
+const restoration: BackendRestoration = await getBackendRestoration()
+
+const vibe = createVibe({
+  target: '#gallery',
+  initialPage: restoration.initialPage,
+  loadPage,
+  autofill: {
+    strategy: 'backend',
+    pageSize: 40,
+    feedKey: 'latest-images',
+    initialSession: restoration.session,
+    async onUnderfilled(context) {
+      const { signal, ...payload } = context
+      return await startBackendAutofill(payload, { signal })
+    },
+    onCancel: cancelBackendAutofill,
+  },
+})
+
+const unsubscribe = subscribeToAutofillUpdates((update) => {
+  vibe.applyAutofillUpdate(update)
+})
+
+await vibe.mount()
 ```
 
-Vibe owns:
+Subscribe before mounting so a fast Reverb, WebSocket, or polling update is not
+missed. A waiting update reports sequenced progress without items. A `complete`
+or `exhausted` update supplies the entire buffered batch and appends it once:
 
-- loaded items
-- active index
-- next-page prefetch
-- optional previous-page loading
-- duplicate cursor protection
-- initial retry state
-- removal-aware feed navigation
+The backend owns its delay policy and job scheduling. Return or emit the
+absolute `nextRequestAt` timestamp for a waiting job; Vibe derives the live
+`delayRemainingMs` countdown locally. Persist the timestamp in session
+snapshots so a refreshed client can resume the same countdown.
 
-### Default paging behavior
+```ts
+vibe.applyAutofillUpdate({
+  feedKey: 'latest-images',
+  sessionId: 'job-456',
+  sequence: 2,
+  requests: 2,
+  received: 48,
+  nextRequestAt: null,
+  status: 'complete',
+  items: completedBatch,
+  next: 'cursor-after-completed-batch',
+  total: 500,
+})
+
+await vibe.cancelAutofill()
+unsubscribe()
+vibe.destroy()
+```
 
-Vibe has one built-in paging model:
+Load-time restoration should provide both `initialPage` and
+`autofill.initialSession`; this renders committed items immediately and avoids
+starting a duplicate backend job. The snapshot `feedKey` and `pageSize` must
+match the configured backend autofill options. Use
+`vibe.restoreAutofillSession(snapshot)` only when a session becomes available
+after construction; it restores autofill lifecycle state, not a complete
+visible page.
 
-- 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
+`state.autofill` exposes the strategy, lifecycle status, target, received and
+missing counts, request count, countdown, session identity, sequence, and error. Backend
+results are appended only when an update is `complete` or `exhausted`; stale,
+duplicate, mismatched-feed, and post-cancellation updates are ignored.
+Terminal backend updates must include `next`, using `null` when the source is
+exhausted. Vibe resumes ordinary pagination from that terminal cursor after
+autofill completes. A terminal update without `next` is rejected so an older
+cursor cannot be requested again.
 
-Example:
+## Manual fill
 
-```vue
-<VibeLayout
-  :resolve="resolve"
-  :page-size="25"
-  :fill-delay-ms="2000"
-  :fill-delay-step-ms="1000"
-  :show-end-badge="false"
-  :show-status-badges="false"
-/>
+Manual fill is separate from autofill. It starts only when the consumer calls
+`vibe.fill()` and targets additional page requests rather than an item count:
+
+```ts
+await vibe.fill({ pages: 3 })
+await vibe.fill({ until: 'end' })
 ```
 
-### Seeded hydration
+`{ pages: 3 }` follows three cursors from the currently loaded page. It becomes
+`exhausted` if the source ends before all three requests complete. `{ until:
+'end' }` continues until a response returns `next: null`; reaching that end is
+a successful `complete` result. Duplicate post IDs are still removed, but they
+do not change how page requests are counted.
 
-Use `initialState` when the app already knows a restored slice of the feed and wants Vibe to hydrate from that snapshot immediately:
+### Frontend fill
 
-```vue
-<VibeLayout
-  :resolve="resolve"
-  :initial-state="{
-    cursor: 'page-10',
-    items: restoredItems,
-    nextCursor: 'page-11',
-    previousCursor: 'page-9',
-    activeIndex: 4,
-  }"
-/>
+```ts
+const restoredPage = await feedCache.read()
+
+const vibe = createVibe({
+  target: '#gallery',
+  initialPage: restoredPage ?? undefined,
+  loadPage,
+  fill: {
+    strategy: 'frontend',
+    delayStepMs: 2_000,
+    delayMaxMs: 10_000,
+  },
+  onStateChange(state) {
+    renderFillState(state.fill)
+    void feedCache.write({
+      items: [...state.items],
+      next: state.next,
+      total: state.total ?? undefined,
+    })
+  },
+})
+
+await vibe.mount()
+await vibe.fill({ pages: 3 })
+// or: await vibe.fill({ until: 'end' })
 ```
 
-Notes:
+Frontend fill invokes `loadPage` in the browser, exposes progress through
+`state.fill`, and appends one buffered batch when the requested pages or end is
+reached. `await vibe.cancelFill()` aborts the active request and discards the
+uncommitted batch. A restored `initialPage.next` is the cursor from which the
+next manual fill starts. The first fill request is immediate; subsequent
+requests use the same capped incremental delay and expose
+`state.fill.delayRemainingMs` plus `state.fill.nextRequestAt`.
 
-- `resolve` is optional if you only need a seeded snapshot
-- when `resolve` is present, Vibe continues paging from the seeded cursors
+### Backend fill
 
-### Surface behavior
+```ts
+interface FillRestoration {
+  initialPage?: VibePage
+  session?: VibeFillSessionSnapshot
+}
 
-- desktop starts in the masonry list surface
-- clicking a grid tile opens fullscreen
-- `Escape` returns from fullscreen to the list on desktop
-- mobile and tablet always force fullscreen
-- grid uses preview assets and in-view loading
-- fullscreen uses the original asset and shows a spinner until ready
+const restoration: FillRestoration = await getFillRestoration()
+
+const vibe = createVibe({
+  target: '#gallery',
+  initialPage: restoration.initialPage,
+  loadPage,
+  fill: {
+    strategy: 'backend',
+    feedKey: 'latest-images',
+    initialSession: restoration.session,
+    async onStart(context) {
+      const { signal, ...payload } = context
+      return await startBackendFill(payload, { signal })
+    },
+    onCancel: cancelBackendFill,
+  },
+})
+
+const unsubscribe = subscribeToFillUpdates((update) => {
+  vibe.applyFillUpdate(update)
+})
+
+await vibe.mount()
+await vibe.fill({ pages: 3 })
+```
 
-Common behavior props:
+The backend callback should enqueue durable work and return a `sessionId`
+without waiting for every page. Each completed endpoint call can emit a
+sequenced `waiting` update containing `completedPages` and `received`. The
+backend remains responsible for delaying and dispatching each job. Include its
+absolute `nextRequestAt` in the returned session and waiting updates so Vibe can
+render the countdown. The terminal update supplies the entire buffered batch
+and its cursor boundary:
 
-- `surfaceMode`: lets the parent drive the desktop list/fullscreen surface explicitly
-- `emptyStateMode`: controls whether empty states render inline, as a badge, or stay hidden
-- `paginationDetail`: lets the parent attach app-owned cursor or page context to the built-in status UI
-- `showDominantImageTone`, `loopFullscreenVideo`, `showEndBadge`, and `showStatusBadges`: tune the built-in fullscreen and status behavior without taking over the surfaces
+```ts
+vibe.applyFillUpdate({
+  feedKey: 'latest-images',
+  sessionId: 'fill-job-456',
+  sequence: 3,
+  completedPages: 3,
+  received: 86,
+  nextRequestAt: null,
+  status: 'complete',
+  items: completedBatch,
+  lastCursor: 'cursor-used-for-page-3',
+  next: 'cursor-after-page-3',
+  total: 500,
+})
+```
 
-## Customization
+For load-time restoration, provide both the committed `initialPage` and the
+persisted `fill.initialSession`. Subscribe to backend events before mounting.
+Use `vibe.restoreFillSession(snapshot)` when a session arrives after
+construction. `state.fill` exposes the strategy, target, status, completed page
+count, received unique-card count, countdown, session identity, sequence, and error.
+Ordinary pagination resumes from the terminal `next` cursor. Stale,
+mismatched-feed, invalid-terminal, and post-cancellation updates are ignored.
 
-### Surface slots
+## Auto scroll
 
-`VibeLayout` exposes a small set of app-owned surfaces instead of a headless render API:
+Auto scroll advances the masonry gallery smoothly in pixels per second. It is
+disabled by default and can be configured when the instance is created:
 
-- `empty-state`
-- `fullscreen-aside`
-- `fullscreen-footer`
-- `fullscreen-header-actions`
-- `fullscreen-overlay`
-- `fullscreen-status`
-- `grid-footer`
-- `grid-item-overlay`
-- `grid-status`
-- `item-icon`
+```ts
+const vibe = createVibe({
+  target: '#gallery',
+  layout: 'masonry',
+  loadPage,
+  autoScroll: {
+    speedPxPerSecond: 80,
+    minSpeedPxPerSecond: 20,
+    maxSpeedPxPerSecond: 240,
+  },
+})
+
+await vibe.mount()
+vibe.setAutoScroll(true, 120)
+vibe.pauseAutoScroll()
+vibe.resumeAutoScroll()
+vibe.setAutoScrollSpeed(160)
+vibe.setAutoScroll(false)
+```
 
-Example:
+The default speed is 80 px/s within a default 20–240 px/s range. Consumer
+values outside the configured range are clamped. `state.autoScroll` exposes the
+effective speed, bounds, and `enabled` / `paused` flags. The controller uses the
+gallery's animation frames rather than repeated smooth-scroll commands, so
+movement remains continuous and responds immediately to speed changes.
 
-```vue
-<VibeLayout :resolve="resolve">
-  <template #item-icon="{ item, icon }">
-    <component :is="item.type === 'other' ? MyCustomIcon : icon" />
-  </template>
-
-  <template #grid-item-overlay="{ item, hovered }">
-    <div v-if="hovered" class="absolute inset-x-0 bottom-0 p-3">
-      <div class="pointer-events-auto bg-black/45 px-3 py-2 backdrop-blur">
-        Like {{ item.title }}
-      </div>
-    </div>
-  </template>
-
-  <template #grid-footer>
-    <div class="bg-black/55 px-4 py-3 backdrop-blur">
-      Custom footer UI
-    </div>
-  </template>
-</VibeLayout>
-```
+Auto scroll waits while reel layout or a masonry-origin reel viewer is active.
+It resumes without a position jump when masonry becomes active again. Infinite
+scroll continues to work normally because the gallery remains the only scroll
+owner.
 
-### Exposed handle
+## Reel auto advance
 
-Get a component ref and use `VibeHandle`:
+Reel auto advance renders a countdown progress strip at the bottom of an active
+reel and moves to the next post when the configured interval expires:
 
 ```ts
-import { ref } from 'vue'
-import type { VibeHandle } from '@wyxos/vibe'
-
-const vibe = ref<VibeHandle | null>(null)
+const vibe = createVibe({
+  target: '#gallery',
+  layout: 'reel',
+  loadPage,
+  reelAutoAdvance: {
+    enabled: true,
+    intervalMs: 5_000,
+    includePostItems: false,
+  },
+})
+
+await vibe.mount()
+vibe.setReelAutoAdvance(false)
+vibe.setReelAutoAdvance({
+  enabled: true,
+  intervalMs: 8_000,
+  includePostItems: true,
+})
 ```
 
-```vue
-<VibeLayout ref="vibe" :resolve="resolve" />
-```
+The default interval is five seconds and grouped post items are excluded by
+default. When `includePostItems` is enabled, Vibe counts through the parent media
+and then each item in its `items` array before moving vertically to the next post.
+Still images use the countdown. Audio and video stop looping while auto advance
+is enabled and advance from their playback `ended` event instead, so pausing the
+media also pauses progression. Manual vertical or horizontal navigation restarts
+the countdown for the newly active image. The feature is inactive in masonry and
+becomes visible in either a base reel layout or a reel opened from masonry.
 
-Available methods:
+`state.reelAutoAdvance` exposes `enabled`, `intervalMs`, and `includePostItems`.
+At the loaded boundary, normal pagination is requested when another cursor is
+available; the load-more lock continues to prevent that request when active.
 
-- `lockPageLoading()`
-- `unlockPageLoading()`
-- `loadNext()`
-- `loadPrevious()`
-- `retry()`
-- `cancel()`
-- `remove(ids)`
-- `restore(ids)`
-- `undo()`
-- `getRemovedIds()`
-- `clearRemoved()`
+## Reel runtime controls
 
-Available state:
+Use the instance to drive the active reel through the same state paths as
+horizontal and vertical reel gestures:
 
 ```ts
-type VibeStatus = {
-  activeIndex: number
-  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'
-  nextBoundaryLoadProgress: number
-  nextCursor: string | null
-  pageLoadingLocked: boolean
-  phase: 'failed' | 'filling' | 'idle' | 'initializing' | 'loading' | 'refreshing'
-  previousBoundaryLoadProgress: number
-  previousCursor: string | null
-  removedCount: number
-  removedIds: readonly string[]
-  surfaceMode: 'fullscreen' | 'list'
-}
-```
+// Media items within the active post (horizontal reel navigation).
+vibe.nextReelMediaItem()
+vibe.previousReelMediaItem()
 
-Example:
-
-```ts
-vibe.value?.lockPageLoading()
-vibe.value?.remove(['item-2', 'item-5'])
-vibe.value?.undo()
-vibe.value?.unlockPageLoading()
-console.log(vibe.value?.status.itemCount)
-console.log(vibe.value?.status.pageLoadingLocked)
-console.log(vibe.value?.status.nextBoundaryLoadProgress)
-console.log(vibe.value?.status.removedIds)
+// Posts within the reel (vertical reel navigation).
+vibe.nextReelPost()
+vibe.previousReelPost()
 ```
 
-### Events
+Each navigation method returns `true` when it accepted a navigation and `false`
+when it was a no-op. Media-item navigation loops from the first item to the last
+and from the last item to the first, matching reel swipes; a post with only one
+media item returns `false`. Post navigation does not loop and returns `false` at
+the first or last currently loaded post. It does not implicitly load another
+page.
 
-`VibeLayout` emits:
+All four methods return `false` before mount, during the initial loading or empty
+state, after destroy, and while the instance is showing only its masonry feed.
+They work in both a base reel layout and an open masonry-origin reel viewer.
+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.
 
-- `update:activeIndex`
-- `update:surfaceMode`
-- `asset-loads`
-- `asset-errors`
+## Reel information sheet
 
-`asset-loads` is micro-batched and emits an array payload:
+Provide an application-owned Vue component when a reel should offer a
+customizable information sheet. The component is fixed for the lifetime of the
+Vibe instance, while its open state can be initialized and changed at runtime:
 
 ```ts
-type VibeAssetLoadEvent = {
-  item: VibeViewerItem
-  occurrenceKey: string
-  url: string
-  surface: 'grid' | 'fullscreen'
-}
+import ReelInformationSheet from './ReelInformationSheet.vue'
+
+const vibe = createVibe({
+  target: '#gallery',
+  layout: 'responsive',
+  loadPage,
+  reelInfoSheet: {
+    component: ReelInformationSheet,
+    enabled: false,
+  },
+})
+
+await vibe.mount()
+vibe.setReelInfoSheet(true)
+vibe.setReelInfoSheet(false)
 ```
 
-`asset-errors` is micro-batched and emits an array payload:
-
-```ts
-type VibeAssetErrorEvent = {
-  item: VibeViewerItem
-  occurrenceKey: string
-  url: string
-  kind: 'generic' | 'not-found'
-  surface: 'grid' | 'fullscreen'
-}
-```
-
-Example:
+Import `VibeReelInfoSheetProps` to type the consumer component. It receives the
+active `item`, zero-based post and media indexes, the active media item and
+source, inclusive media count, loaded and optional total counts, `layout:
+'reel'`, whether the reel originated from `reel` or `masonry`, and a `close()`
+callback. The component owns its visible controls and content:
 
 ```vue
 <script setup lang="ts">
-import type { VibeAssetErrorEvent, VibeAssetLoadEvent } from '@wyxos/vibe'
+import type { VibeReelInfoSheetProps } from '@wyxos/vibe'
 
-function onAssetLoads(loads: VibeAssetLoadEvent[]) {
-  console.log(loads)
-}
-
-function onAssetErrors(errors: VibeAssetErrorEvent[]) {
-  console.log(errors)
-}
+defineProps<VibeReelInfoSheetProps>()
 </script>
 
 <template>
-  <VibeLayout
-    :resolve="resolve"
-    @asset-loads="onAssetLoads"
-    @asset-errors="onAssetErrors"
-  />
+  <aside>
+    <button type="button" @click="close">Close</button>
+    <h2>Post {{ item.postId }}</h2>
+  </aside>
 </template>
 ```
 
-Notes:
+Phones render the sheet as a full-width modal overlay and make the reel inert
+until it closes. Tablets through 1024px render a full-width non-overlay sheet
+below the reel. Larger layouts render it beside the reel at 25% width, changing
+to 40% at a 1920px viewport. Non-phone sheets stay mounted while vertical reel
+swipes update their active context. All presentations animate open and closed
+and honor reduced-motion preferences.
+
+`state.reelInfoSheet.enabled` reports the requested open state. Enabling without
+a configured component throws an error; disabling is always safe. In a base
+reel, Escape closes an open sheet. In a masonry-origin reel, Escape closes the
+viewer without disabling the sheet, so it is open again when another masonry
+card opens a reel. The consumer close control or `setReelInfoSheet(false)`
+explicitly disables it. The underlying masonry renderer stays mounted, so
+closing either surface preserves its scroll, media selections, and focus target.
+Calling `setReelInfoSheet()` before mount, during loading, or outside an active
+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.
+
+## Load-more lock
+
+Pause ordinary forward pagination without disabling the feed or cancelling a request
+that is already running:
 
-- successful loads that happen close together are batched into one event
-- grid load events usually report `preview.url` when a preview exists
-- fullscreen load events report `item.url`
-- multiple failures that happen close together are batched into one event
-- identical failures are deduped inside the same batch
-- if the same item fails again later, it can emit again in a later batch
-- built-in Vibe error surfaces allow retrying `generic` failures, but not `not-found`
+```ts
+vibe.setLoadMoreLocked(true)
 
-## Local demo routes
+// Existing items remain interactive. Later, allow pagination again.
+vibe.setLoadMoreLocked(false)
+```
 
-Run:
+While locked, Vibe ignores `loadNext()`, infinite-scroll boundary triggers, the
+load-more action, and the end-of-feed retry. `reload()`, initial loading, autofill,
+and explicit `fill()` operations keep their own lifecycles. If infinite scroll is
+enabled when the instance is unlocked, Vibe immediately checks the current bottom
+boundary so the consumer does not need to nudge the scroll position.
 
-```bash
-npm run dev
-```
+Read `state.loadMoreLocked` through `getState()` or `onStateChange` when application
+chrome needs to reflect the gate. The built-in pagination action is disabled and
+shown as `Loading paused` while the gate is active.
+
+## Feed state
+
+Use `onStateChange` to render request and layout state outside Vibe, such as an
+application-header lifecycle indicator:
 
-Routes:
+```ts
+const vibe = createVibe({
+  target: '#gallery',
+  loadPage,
+  onStateChange: (state) => {
+    renderFeedState({
+      layout: state.layout,
+      lifecycle: state.lifecycle,
+    })
+  },
+})
+```
 
-- `/` - default feed surface
-- `/documentation` - in-app documentation
-- `/demo/feed-behavior` - unified fill, retry, boundary refresh, removals, and paging-lock demo
-- `/debug/fake-server` - fake-server inspection route
+The callback receives an initial snapshot when the instance is created and a
+new snapshot whenever its public state changes. The typed `lifecycle` value is
+`loading`, `loaded`, or `error`; it covers initial and pagination requests.
+Individual media preview errors do not mark the feed request as failed.
 
-## Local development
+## Instance lifecycle
 
-```bash
-npm run check
-npm run build
-npm run build:lib
-npm run build:types
-npm run test:unit
-npm run test:e2e
+```ts
+vibe.setLayout('reel')
+vibe.setLayout('responsive')
+vibe.setInfiniteScroll(false)
+vibe.setLoadMoreLocked(true)
+vibe.setLoadMoreLocked(false)
+vibe.setReelAutoAdvance(true)
+vibe.setReelAutoAdvance({ includePostItems: true, intervalMs: 8_000 })
+vibe.setReelInfoSheet(true)
+vibe.setReelInfoSheet(false)
+vibe.nextReelMediaItem()
+vibe.previousReelMediaItem()
+vibe.nextReelPost()
+vibe.previousReelPost()
+vibe.setAutoScroll(true, 80)
+vibe.pauseAutoScroll()
+vibe.resumeAutoScroll()
+vibe.setAutoScroll(false)
+await vibe.loadNext()
+await vibe.reload()
+vibe.getState()
+vibe.destroy()
 ```
 
-## Notes
+Destroying an instance unmounts its Vue tree and aborts its active page request.
 
-- `lib/` is generated output
-- source of truth is under `src/`
-- the package ships compiled CSS at `@wyxos/vibe/style.css`
+In masonry layout, activating a card opens that post in a reel layered over the
+still-mounted masonry feed. Pressing Escape returns to the same masonry scroll
+position. `getState()` reports the viewer session through `reelOrigin` and
+`activeReelPostId`; Escape does not exit a reel configured as the base layout.