Story Rail
alphav0.4.0Horizontal story rail with unread gradient rings, drag-free skim scrolling, optional arrows, an add-story tile, and scroll-aware edge fades.
Context
Seventh of 8 in the social-posts-system arc — story doublet, part 1. Embla used directly (sealed-folder rule — story-rail's start-aligned + drag-free + small-rectangle config differs structurally from media-carousel's centered + snap + large-square gallery). Migration origin: kasder kas-social-front-v0 StoriesSection.tsx + StoryThumbnail.tsx. Realtime contract identical shape to engagement-bar / comment-thread / post-card — single Subscribe<TDelta> mental model across the family. Click does NOT auto-mark-viewed (matches Instagram); host calls ref.current.markViewed(itemId) when their viewer closes. Edge fades adapt to framed mode (from-card when wrapped in card chrome, from-background when bare) and show only on a side the rail can scroll toward. v0.4 hardening for the ilinxa Social Platform: optional preview with an avatar-card fallback, story-ring tokens, muted authors, opt-in arrows, controlled items, RTL. Pairs with story-viewer for the full doublet — viewer takes the FULL Story shape with items[] inner content; rail takes a minimal preview shape. TypeScript structural typing means hosts can pass a Story to story-rail if its fields are a superset; no adapter needed.
Installation
pnpm dlx shadcn@latest initpnpm dlx shadcn@latest add @ilinxa/story-railAdd -fixtures for dummy data:
pnpm dlx shadcn@latest add @ilinxa/story-rail-fixturesCLI can't resolve @ilinxa? The namespace is listed in the official shadcn registry directory, so current CLIs need no configuration. If yours can't resolve it (older or pinned versions, self-hosted mirrors), register it manually in components.json:
"registries": {
"@ilinxa": "https://ui.ilinxa.com/r/{name}.json"
}Preview
Demo source
"use client"; import { useMemo, useRef, useState } from "react";import { Button } from "@/components/ui/button";import { Tabs, TabsContent, TabsTrigger } from "@/components/ui/tabs";import { SwipeTabsList } from "@/components/site/swipe-tabs-list";import { StoryViewer } from "../../media/story-viewer";import type { Story } from "../../media/story-viewer";import { StoryRail } from "./story-rail";import { AddStoryThumbnail } from "./parts/add-story-thumbnail";import { DUMMY_STORIES, DUMMY_VIEWER_AVATAR, createDummyStoryRailSubscribe,} from "./dummy-data";import type { StoryRailHandle, StoryRailItem } from "./types"; function log(tag: string, payload: unknown) { if (typeof console !== "undefined") { console.log(`[demo:story-rail:${tag}]`, payload); }} const NOW = new Date("2026-05-03T14:00:00Z");const isoMinusMin = (min: number) => new Date(NOW.getTime() - min * 60_000).toISOString(); /** * Real Unsplash + w3schools URLs (verified working) cycled across the rail items * so the viewer's nav arrows + tap zones visibly advance to a different image * each time. Demo-only — NOT in dummy-data.ts (which ships via story-rail-fixtures * and stays viewer-free). */const SECONDARY_IMAGES = [ "https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=900&h=1600&fit=crop", "https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=900&h=1600&fit=crop", "https://images.unsplash.com/photo-1454496522488-7a8e488e8606?w=900&h=1600&fit=crop", "https://images.unsplash.com/photo-1504805572947-34fad45aed93?w=900&h=1600&fit=crop", "https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=900&h=1600&fit=crop", "https://images.unsplash.com/photo-1444080748397-f442aa95c3e5?w=900&h=1600&fit=crop", "https://images.unsplash.com/photo-1505765050516-f72dcac9c60e?w=900&h=1600&fit=crop",]; /** * Full-Story shape for the viewer, derived from a rail item (same id). Rail * items are minimal previews; the viewer needs full items[] + createdAt. * Items without a preview fall back to a SECONDARY_IMAGES entry (modulo, so the * array length never matters). */function toFullStory(rail: StoryRailItem, idx: number): Story { const first = rail.previewImage ?? SECONDARY_IMAGES[idx % SECONDARY_IMAGES.length]; const second = SECONDARY_IMAGES[(idx + 1) % SECONDARY_IMAGES.length]; return { id: rail.id, userId: rail.userId ?? `u${idx + 1}`, username: rail.username, avatar: rail.avatar, hasUnread: rail.hasUnread, createdAt: isoMinusMin((idx + 1) * 18), items: idx === 1 ? [ { id: `${rail.id}-i1`, type: "video", src: "https://www.w3schools.com/html/mov_bbb.mp4" }, { id: `${rail.id}-i2`, type: "image", src: first, duration: 5 }, ] : idx === 4 ? [ { id: `${rail.id}-i1`, type: "image", src: first, duration: 5 }, { id: `${rail.id}-i2`, type: "video", src: "https://www.w3schools.com/html/movie.mp4" }, ] : [ { id: `${rail.id}-i1`, type: "image", src: first, duration: 5 }, { id: `${rail.id}-i2`, type: "image", src: second, duration: 5 }, ], };} type RailProps = React.ComponentProps<typeof StoryRail>; interface RailWithViewerProps { framed?: boolean; showAddLeading?: boolean; renderThumbnail?: RailProps["renderThumbnail"]; subscribe?: RailProps["subscribe"]; /** Uncontrolled seed. Defaults to DUMMY_STORIES. */ defaultItems?: StoryRailItem[]; /** Controlled mode: pass `items` together with `onItemsChange`. */ items?: StoryRailItem[]; onItemsChange?: RailProps["onItemsChange"]; onPreviewError?: RailProps["onPreviewError"]; arrows?: RailProps["arrows"]; dir?: RailProps["dir"]; labels?: RailProps["labels"]; /** Custom `leading` node; wins over `showAddLeading`. */ leading?: RailProps["leading"]; /** Lets a parent reach the rail handle too (controlled tab). */ railRef?: React.RefObject<StoryRailHandle | null>;} /** * Shared rail+viewer wiring — the canonical pattern from the guide: * rail click sets activeIdx, viewer opens, viewer's onStoryViewed feeds back * into railRef.markViewed to clear the unread ring. */function RailWithViewer({ framed = true, showAddLeading = false, renderThumbnail, subscribe, defaultItems, items, onItemsChange, onPreviewError, arrows, dir, labels, leading, railRef: externalRef,}: RailWithViewerProps) { const ownRef = useRef<StoryRailHandle | null>(null); const railRef = externalRef ?? ownRef; const [activeIdx, setActiveIdx] = useState(-1); const controlled = items !== undefined && onItemsChange !== undefined; const seed = items ?? defaultItems ?? DUMMY_STORIES; const fullStories = useMemo(() => seed.map(toFullStory), [seed]); const leadingNode = leading ?? (showAddLeading ? ( <AddStoryThumbnail userAvatar={DUMMY_VIEWER_AVATAR} onClick={() => log("add-story", null)} /> ) : undefined); return ( <div className="mx-auto flex max-w-2xl flex-col gap-3"> <StoryRail ref={railRef} {...(controlled ? { items, onItemsChange } : { defaultItems: seed })} framed={framed} leading={leadingNode} renderThumbnail={renderThumbnail} subscribe={subscribe} onSubscribeDelta={subscribe ? (d) => log("delta", d) : undefined} onPreviewError={onPreviewError} arrows={arrows} dir={dir} labels={labels} onItemClick={({ item, index }) => { log("click", { item, index }); setActiveIdx(index); }} /> {activeIdx >= 0 && fullStories[activeIdx] ? ( <StoryViewer stories={fullStories} initialStoryIndex={activeIdx} isOpen onClose={() => setActiveIdx(-1)} onStoryViewed={(id) => { log("story-viewed", id); railRef.current?.markViewed(id); }} onAutoCloseAtEnd={() => log("auto-close-at-end", null)} /> ) : null} </div> );} function DefaultTab() { return <RailWithViewer />;} function WithAddTab() { return <RailWithViewer showAddLeading />;} function MixedReadUnreadTab() { return <RailWithViewer />;} function RealtimeTab() { const subscribe = useMemo(() => createDummyStoryRailSubscribe(), []); return <RailWithViewer showAddLeading subscribe={subscribe} />;} function CustomRenderTab() { return ( <RailWithViewer renderThumbnail={(item: StoryRailItem, isUnread, { onClick }) => ( <button type="button" onClick={onClick} aria-label={item.username} className="group flex h-20 w-20 shrink-0 items-center justify-center overflow-hidden rounded-2xl border-2 border-card bg-muted shadow-sm transition-transform hover:scale-105" > {item.previewImage ? ( <img src={item.previewImage} alt="" className="h-full w-full object-cover" style={{ filter: isUnread ? "saturate(1.1)" : "saturate(0.4)", }} /> ) : ( <span aria-hidden="true" className="h-full w-full bg-muted" /> )} </button> )} /> );} function BareTab() { return <RailWithViewer framed={false} showAddLeading />;} function EmptyTab() { const [items] = useState<StoryRailItem[]>([]); return ( <div className="mx-auto max-w-2xl"> <StoryRail defaultItems={items} /> </div> );} const BROKEN_URL = "https://images.unsplash.com/photo-0000000000000-broken?w=200";const RECOVERED_URL = "https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=400&h=600&fit=crop&q=80"; const FALLBACK_ITEMS: StoryRailItem[] = [ { id: "fb-none", userId: "fb1", username: "no-preview", avatar: DUMMY_STORIES[0]?.avatar, hasUnread: true, }, { id: "fb-muted", userId: "fb2", username: "muted", avatar: DUMMY_STORIES[1]?.avatar, previewImage: DUMMY_STORIES[1]?.previewImage, hasUnread: true, muted: true, }, { id: "fb-recover", userId: "fb3", username: "recovers", avatar: DUMMY_STORIES[2]?.avatar, previewImage: BROKEN_URL, hasUnread: true, }, { id: "fb-dead", userId: "fb4", username: "stays-broken", avatar: DUMMY_STORIES[3]?.avatar, previewImage: BROKEN_URL, hasUnread: true, },]; async function resolvePreview(item: StoryRailItem): Promise<string | void> { log("preview-error", item.id); // "recovers" gets a fresh URL (think: a re-signed one). Everything else // resolves nothing, so the rail falls back to the avatar card. if (item.id === "fb-recover") return RECOVERED_URL;} function FallbacksTab() { return ( <div className="flex flex-col gap-3"> <RailWithViewer defaultItems={FALLBACK_ITEMS} onPreviewError={resolvePreview} /> <p className="mx-auto max-w-2xl text-xs text-muted-foreground"> 1: no <code>previewImage</code> (avatar card). 2: <code>muted</code> + unread (grey ring). 3: broken URL, <code>onPreviewError</code> resolves a working one. 4: broken URL, nothing resolves, so the avatar card. </p> </div> );} let nextControlledId = 1; function ControlledTab() { const railRef = useRef<StoryRailHandle | null>(null); const [items, setItems] = useState<StoryRailItem[]>(() => DUMMY_STORIES.slice(0, 6), ); const unread = items.filter((i) => i.hasUnread && !i.muted).length; const addStory = () => setItems((prev) => { const n = nextControlledId++; const src = DUMMY_STORIES[(prev.length + n) % DUMMY_STORIES.length]; return [ { ...src, id: `ctl-${n}`, userId: `ctl-u${n}`, username: `new${n}`, hasUnread: true, muted: false, }, ...prev, ]; }); const flipFirst = () => setItems((prev) => prev.map((it, i) => (i === 0 ? { ...it, hasUnread: !it.hasUnread } : it)), ); const reorder = () => setItems((prev) => (prev.length > 1 ? [...prev.slice(1), prev[0]] : prev)); return ( <div className="flex flex-col gap-3"> <RailWithViewer railRef={railRef} items={items} onItemsChange={(next) => { log("items-change", next.length); setItems(next); }} /> <div className="mx-auto flex w-full max-w-2xl flex-wrap items-center gap-2"> <Button size="sm" variant="outline" onClick={addStory}> Add story </Button> <Button size="sm" variant="outline" onClick={flipFirst}> Flip first unread </Button> <Button size="sm" variant="outline" onClick={reorder}> Reorder </Button> <span data-testid="controlled-unread-count" className="ms-auto font-mono text-xs text-muted-foreground" > {unread} unread / {items.length} total </span> </div> <p className="mx-auto max-w-2xl text-xs text-muted-foreground"> Parent state owns the list. Open a story: the viewer calls{" "} <code>markViewed</code>, the rail reports it through{" "} <code>onItemsChange</code>, and the count above drops. </p> </div> );} function ArrowsTab() { const items = useMemo<StoryRailItem[]>( () => Array.from({ length: 16 }, (_, i) => { const base = DUMMY_STORIES[i % DUMMY_STORIES.length]; return { ...base, id: `arr-${i}`, username: `${base.username}${i + 1}` }; }), [], ); return ( <div className="flex flex-col gap-3"> <RailWithViewer defaultItems={items} arrows="always" showAddLeading /> <p className="mx-auto max-w-2xl text-xs text-muted-foreground"> <code>arrows="always"</code> shows on touch screens too; production consumers typically use{" "} <code>arrows="fine-pointer"</code>. </p> </div> );} const RTL_LABELS: NonNullable<RailProps["labels"]> = { railLabel: "القصص", addStoryLabel: "أضف قصة", addStoryAriaLabel: "أضف قصة جديدة", previousLabel: "القصص السابقة", nextLabel: "القصص التالية", thumbnailAriaLabel: (item) => item.muted ? `${item.username}، مكتومة` : item.hasUnread ? `${item.username}، قصة غير مقروءة` : `${item.username}، تمت المشاهدة`, emptyState: "لا توجد قصص بعد.",}; function RtlTab() { const items = useMemo<StoryRailItem[]>( () => Array.from({ length: 12 }, (_, i) => { const base = DUMMY_STORIES[i % DUMMY_STORIES.length]; return { ...base, id: `rtl-${i}`, username: `${base.username}${i + 1}` }; }), [], ); return ( <div dir="rtl"> <RailWithViewer defaultItems={items} arrows="always" labels={RTL_LABELS} leading={ <AddStoryThumbnail userAvatar={DUMMY_VIEWER_AVATAR} onClick={() => log("add-story", null)} /> } /> </div> );} export default function StoryRailDemo() { return ( <Tabs defaultValue="default" className="w-full"> <SwipeTabsList> <TabsTrigger value="default">Default</TabsTrigger> <TabsTrigger value="add">+ Add</TabsTrigger> <TabsTrigger value="mixed">Mixed</TabsTrigger> <TabsTrigger value="realtime">Realtime</TabsTrigger> <TabsTrigger value="custom">Custom</TabsTrigger> <TabsTrigger value="bare">Bare</TabsTrigger> <TabsTrigger value="empty">Empty</TabsTrigger> <TabsTrigger value="fallbacks">Fallbacks</TabsTrigger> <TabsTrigger value="controlled">Controlled</TabsTrigger> <TabsTrigger value="arrows">Arrows</TabsTrigger> <TabsTrigger value="rtl">RTL</TabsTrigger> </SwipeTabsList> <TabsContent value="default" className="mt-4"> <DefaultTab /> </TabsContent> <TabsContent value="add" className="mt-4"> <WithAddTab /> </TabsContent> <TabsContent value="mixed" className="mt-4"> <MixedReadUnreadTab /> </TabsContent> <TabsContent value="realtime" className="mt-4"> <RealtimeTab /> </TabsContent> <TabsContent value="custom" className="mt-4"> <CustomRenderTab /> </TabsContent> <TabsContent value="bare" className="mt-4"> <BareTab /> </TabsContent> <TabsContent value="empty" className="mt-4"> <EmptyTab /> </TabsContent> <TabsContent value="fallbacks" className="mt-4"> <FallbacksTab /> </TabsContent> <TabsContent value="controlled" className="mt-4"> <ControlledTab /> </TabsContent> <TabsContent value="arrows" className="mt-4"> <ArrowsTab /> </TabsContent> <TabsContent value="rtl" className="mt-4"> <RtlTab /> </TabsContent> </Tabs> );} Usage
When to use
Reach for StoryRail when you need a horizontal stories rail at the top of a feed — portrait thumbnails with a gradient ring (unread) or muted ring (read), drag-free skim-scroll, scroll-aware edge fades and optional prev / next arrows. Decoupled from the viewer: onItemClick({ item, index }) hands off to whatever your host renders (your own viewer, story-viewer, a navigation push, etc.).
Items: uncontrolled, controlled, legacy
- Uncontrolled —
defaultItemsseeds the rail once on mount.markViewed,dispatch,resetand realtimesubscribedeltas mutate the rail's internal list. - Controlled — pass
itemstogether withonItemsChange. The prop wins on every render. Every mutation (markViewed,dispatch,reset, subscribe deltas) is computed from the latest prop and reported throughonItemsChange(next); the DOM changes only when youritemsdo. Two deltas before a re-render both land. To discard a reported change, re-render with a fresh array; untilitemschanges identity the rail keeps building on the last list it reported. - Notified uncontrolled —
defaultItemsplusonItemsChange: the rail keeps its own list and also reports every next list. - Legacy —
itemsalone (noonItemsChange) is read once on mount and later changes are ignored. It still works, and a dev-only warning points you atdefaultItemsoronItemsChange.
Minimal usage (uncontrolled)
import { StoryRail } from "@/components/story-rail";
<StoryRail
defaultItems={stories}
onItemClick={({ item, index }) => openViewer(index)}
/>Controlled
const [stories, setStories] = useState(initialStories);
const railRef = useRef<StoryRailHandle>(null);
<StoryRail
ref={railRef}
items={stories}
onItemsChange={setStories}
onItemClick={({ item, index }) => openViewer(index)}
/>
// viewer.onStoryViewed -> railRef.current?.markViewed(id)
// -> onItemsChange(next) -> setStories(next) -> rail re-rendersWith AddStoryThumbnail
import {
StoryRail,
AddStoryThumbnail,
} from "@/components/story-rail";
<StoryRail
defaultItems={stories}
leading={
<AddStoryThumbnail
userAvatar={viewer.avatar}
onClick={() => openStoryComposer()}
/>
}
onItemClick={({ item, index }) => openViewer(index)}
/>Inside a rail, AddStoryThumbnail reads labels.addStoryLabel and labels.addStoryAriaLabel from the rail through context, so you localize once. Its own label / ariaLabel props still win. Used standalone (outside a rail) it uses the English defaults. It shows a visible focus ring on keyboard focus.
Missing, broken or expired previews
<StoryRail
defaultItems={stories} // previewImage is optional
onPreviewError={async (item) => {
// Resolve a fresh URL (e.g. re-signed) -> retried once.
// Resolve nothing, or reject -> avatar card.
return await api.refreshStoryPreview(item.id);
}}
/>previewImage is optional. When it is absent, or it fails and onPreviewErrorcannot refresh it, the tile renders an avatar card: the author's avatar (initials fallback) centred on bg-muted, same 80×112 size. A new previewImage on the item resets the state. Pass previewSrcSet / previewSizes (sizes defaults to 80px) for responsive previews.
Muted authors
{ id: "9", username: "burak", hasUnread: true, muted: true, ... }muted: truedraws the grey ring even when the story is unread, and renders the tile and name at reduced opacity. Ordering stays yours. The default aria label reads "{username}, muted".
Arrows
<StoryRail defaultItems={stories} arrows="fine-pointer" />arrows is "none" (default), "fine-pointer" (mouse / trackpad only, resolved after mount so the first render matches the server) or "always". An arrow is hidden when the rail cannot scroll that way. Each press scrolls a page, arrows mirror in RTL, and prefers-reduced-motion jumps instead of animating. Names come from labels.previousLabel / labels.nextLabel. Without arrows, a mouse can only click-drag (there is no wheel / trackpad-swipe scrolling), so desktop layouts usually want "fine-pointer". Arrows sit on the default tile's centre; set --story-rail-arrow-top for custom tiles.
RTL and localization
<div dir="rtl">
<StoryRail
defaultItems={stories}
arrows="always"
leading={<AddStoryThumbnail userAvatar={viewer.avatar} />}
labels={{
railLabel: "القصص",
addStoryLabel: "أضف قصة",
addStoryAriaLabel: "أضف قصة جديدة",
previousLabel: "القصص السابقة",
nextLabel: "القصص التالية",
emptyState: "لا توجد قصص بعد.",
}}
/>
</div>Direction comes from the dir prop, else the nearest [dir] ancestor (resolved after mount), and feeds Embla. Fades, the arrows and the Add badge use logical positions. Every string lives in labels (defaults in DEFAULT_STORY_RAIL_LABELS), including the thumbnailAriaLabel(item) function.
Realtime via subscribe
import type {
Subscribe,
StoryRailDelta,
} from "@/components/story-rail";
const subscribe = useCallback<Subscribe<StoryRailDelta>>(
(handler) => channel.on("stories", handler),
[channel],
);
<StoryRail
defaultItems={stories}
subscribe={subscribe}
onSubscribeDelta={(d) => analytics.track("story-rail-delta", d)}
/>Hosts must memoize subscribe via useCallback — identity changes trigger a clean teardown + re-call. In controlled mode each delta is reported through onItemsChange instead of being applied internally.
Mark viewed (from your viewer)
const railRef = useRef<StoryRailHandle>(null);
<StoryRail
ref={railRef}
defaultItems={stories}
onItemClick={({ item, index }) => {
setActiveStoryIndex(index);
setViewerOpen(true);
}}
/>
<MyStoryViewer
open={viewerOpen}
story={stories[activeStoryIndex]}
onClose={() => {
setViewerOpen(false);
railRef.current?.markViewed(stories[activeStoryIndex].id);
}}
/>Click does NOT auto-mark-viewed (matches Instagram — the ring stays until the user actually completes the story). Host calls markViewed(itemId) when their viewer closes. ref.scrollTo(index) takes an index into items; the leading slot is not counted.
Custom thumbnail render
<StoryRail
defaultItems={stories}
renderThumbnail={(item, isUnread, { onClick, baseId, showRing }) => (
<BrandedStoryThumbnail
item={item}
preview={item.previewImage /* string | undefined */}
ring={showRing /* hasUnread && !muted; isUnread is raw hasUnread */}
onClick={onClick}
ariaLabelledBy={baseId}
/>
)}
/>Bare (no card frame)
<StoryRail defaultItems={stories} framed={false} className="px-4" />With framed: false, the card chrome is removed and the edge fades use from-background so they blend with whatever container you embed in.
Theming
:root {
--story-ring-from: oklch(0.80 0.20 132);
--story-ring-to: oklch(0.70 0.18 60);
--story-rail-fade-width: 2rem; /* default 3rem */
}
.dark {
--story-ring-from: oklch(0.86 0.18 132);
--story-ring-to: oklch(0.75 0.16 60);
}The unread ring is a gradient from --story-ring-from to --story-ring-to. Define them in your :root / .dark; the install adds --color-story-ring-* mappings with fallbacks that never override yours. The edge fades are scroll-aware: each shows only on a side the rail can scroll toward, so at rest the first tile and its focus ring are never covered. Width is --story-rail-fade-width.
Upgrading from 0.3
previewImageis optional: inrenderThumbnailand any reducer reader it is nowstring | undefined. Guard before using it as animg src.- Move
items=todefaultItems=(or addonItemsChangeto control it). Bareitemsstill works but dev-warns. - Ring colours are token-driven. The old
from-accent via-warning to-destructiveclasses are gone; set--story-ring-from/--story-ring-to. - Edge fades are scroll-aware instead of always showing.
ref.scrollTo(index)now targets the item index even whenleadingis mounted.
Notes
- Embla used inline with
align: "start",containScroll: "trimSnaps",dragFree: true. No indicator dots — story rails are skim-scroll, not snap carousels. - Thumbnail dimensions are fixed at
w-20 h-28(80×112). For different sizes, use therenderThumbnailslot. - Edge fades are
aria-hidden+pointer-events-none; they don't intercept drag. linkComponent+getHrefco-exist withonItemClick— both fire on click. Use this for analytics on a navigation-mode rail.- For external state coordination, the
storyRailReduceranduseStoryRailStateare publicly exported.
Features
- Kasder-exact thumbnail aesthetic — w-20 h-28 portrait, gradient ring (unread) vs muted ring (read), avatar+username row below
- Optional `previewImage` — absent or failing → avatar card (author avatar on bg-muted); `onPreviewError(item)` can resolve a refreshed URL, retried once; lazy/async `<img>` with width/height/srcSet/sizes
- Unread ring from `--story-ring-from` / `--story-ring-to` (item cssVars.theme mappings with fallbacks — your theme wins)
- `muted` items — grey ring even when unread, tile + name at reduced opacity; the aria-label function receives the item
- Opt-in previous / next arrows (`arrows="fine-pointer" | "always"`) — page-wise scroll, hidden where the rail cannot scroll, labelled via `labels`, mirrored in RTL, jump under reduced motion; no wheel scrolling, so arrows are the desktop path
- RTL — `dir` prop or the nearest `[dir]` ancestor drives Embla direction; logical positions; mirrored fades
- AddStoryThumbnail standalone sub-export — dashed-border placeholder + 50%-opacity user avatar + Plus badge
- leading?: ReactNode slot — render any custom prefix (AddStoryThumbnail / Live indicator / Pinned callout / etc.)
- Realtime via Subscribe<StoryRailDelta> contract — added / removed / viewed / updated; same shape as engagement-bar / comment-thread / post-card
- onSubscribeDelta callback fires for every delta
- Embla used inline (no wrapper hook, no cross-import) — align: 'start', containScroll: 'trimSnaps', dragFree: true (kasder-exact)
- No indicator dots — story rails are skim-scroll, not snap carousels
- Mode-aware, scroll-aware edge fades — from-card when framed, from-background when bare; shown only where the rail can scroll; width via `--story-rail-fade-width` (default 3rem)
- Edge gradients render only when items present (not over empty state)
- Click does NOT auto-mark-viewed — host owns viewing semantics via ref.current.markViewed(itemId)
- renderThumbnail slot for full per-thumbnail takeover (themed rings, video previews, custom shapes)
- Polymorphic linkComponent + getHref for navigation-mode (rare; thumbnails usually open modal viewer)
- Imperative handle: scrollTo(itemIndex — `leading` not counted) / getCurrentItems / reset / dispatch / markViewed
- storyRailReducer + useStoryRailState publicly exported (external state coordination)
- Controlled or uncontrolled — `items` + `onItemsChange` (the prop wins every render; mutations and realtime deltas are reported) or `defaultItems`; `items` alone keeps the read-once behaviour with a dev warning
- i18n via the labels object (rail, Add tile, arrows, empty state, thumbnailAriaLabel(item)) — `AddStoryThumbnail` reads the rail's labels from context; its own props still win
- a11y — section role=region, button per thumbnail with descriptive aria-label, edge gradients aria-hidden
- motion-safe:group-hover:scale-105 on thumbnails — reduced-motion users see static
- Tailwind v4-clean (no legacy class names)
- No new shadcn primitives — avatar already installed
- No framer-motion — CSS transitions only