react-native-roster 0.0.0 → 0.1.0

package/llms.txt

@@ -0,0 +1,498 @@
+# react-native-roster
+
+> React Native read surfaces over layered absolute intervals with provenance.
+> Roster projects many lanes horizontally; Schedule projects one lane into day
+> columns. The core owns geometry, coverage, axis math, and caches. Adapters own
+> upstream conversion and recurrence. The gallery and integration guides describe
+> the implemented surface; package distribution status is in README.md.
+
+This file is for an agent integrating the package into a consumer app. Follow the
+setup, contract, and cache rules below. You do not need the repository's issues
+to render a roster. README.md is the human quick start; AGENTS.md is for modifying
+this repository. The demo is the working integration example, not a dependency.
+
+## Setup and first render
+
+Use Bun 1.4.2 and Node 22 for this checkout. Run at repository root:
+
+```sh
+bun install --ignore-scripts --frozen-lockfile
+bun run build
+bun run demo:web
+```
+
+The root install also installs demo dependencies. Use `EXPO_OFFLINE=1 bun run
+demo:web` if Expo cannot write its online dependency-validation cache. To consume from another app,
+`bun add react-native-roster`; for an unreleased checkout, run
+`bun pm pack --destination .cache` here, then `bun add` the actual absolute
+tarball path in your app. Add `@legendapp/list` and install the SDK's
+compatible Reanimated with `bunx expo install react-native-reanimated --bun`.
+Keep React, React Native, and Expo aligned with the app's SDK. The demo uses Expo
+54, React 19.1, RN 0.81.5, LegendList 2.0.19, and Reanimated 3.19.5. NativeWind is
+an optional peer (>=4.1); import react-native-roster/nativewind once at the app
+root to enable className props on Roster and Schedule. Web needs compatible
+React DOM and React Native Web. See demo/babel.config.js for workspace presets.
+
+Peer ranges: React >=18.2, React Native >=0.74, Expo >=51, LegendList >=2.
+Reanimated >=3.19 is optional for core-only installs and required for Roster.
+Tested dependency versions are not proof of every combination in those ranges.
+
+Save this as a screen component, or as demo/app/gallery/readme-example.tsx with
+`export default function Example` for Expo Router, and visit /gallery/readme-example:
+
+```tsx
+import { Roster } from 'react-native-roster';
+import type { Lane } from 'react-native-roster/core';
+
+const lanes: Lane[] = [{
+  id: 'one', label: 'Lane one', layers: [{
+    id: 'open', role: 'availability', z: 0, style: { color: '#4f9478' },
+    intervals: [{
+      start: Date.UTC(2024, 0, 1, 9), end: Date.UTC(2024, 0, 1, 17),
+      sources: [{ kind: 'table', id: 'row-one' }],
+    }],
+  }],
+}];
+export function Example() {
+  return <Roster lanes={lanes} style={{ height: 480, flex: undefined }}
+    windowSpec={{ span: 'week', anchorDate: '2024-01-01', timezone: 'UTC' }}
+    onIntervalPress={(rect, lane) => console.log(lane.id, rect.sources)} />;
+}
+```
+
+Expect a green 09:00 to 17:00 interval on January 1, 2024. Scroll horizontally to
+see the time range. A bounded viewport is required. Remove the scratch route
+when finished. In a controlled app, own WindowSpec in your screen's hook; update
+it in navigation handlers, and prepare adapter output for windowFor(spec).
+
+## Vocabulary
+
+| Term | Meaning |
+| --- | --- |
+| roster | Whole read surface: shared time axis, lanes, and layers. |
+| lane | One person or resource row containing layers and display metadata. |
+| layer | Ordered intervals and gaps with role, z-order, and style. |
+| interval | Covered end-exclusive absolute time with sources. |
+| gap | Removed end-exclusive absolute time with sources; survives complete subtraction. |
+| source | Provenance identity (kind, id); optional label is display metadata. |
+| window | Bare absolute { start, end }; no span or resolution. |
+| projection | Horizontal elapsed time or day columns using wall-clock hours. |
+| adapter | External conversion from upstream data to lanes and layers. |
+| schedule | One lane projected into days across and hours down. |
+
+Use these words in integration code. The LayerRole strings availability and
+booking, and their coverage-field names below, are exact contract identifiers.
+
+## Data contract
+
+```ts
+type Source = { kind: string; id: string; label?: string };
+type Interval = { start: number; end: number; sources: Source[] };
+type Gap = { start: number; end: number; sources: Source[] };
+type LayerRole = 'availability' | 'booking' | 'custom';
+type LayerStyle = { color: string; highlightColor?: string; inset?: number; opacity?: number };
+type Layer = {
+  id: string; role: LayerRole; z: number; style: LayerStyle;
+  intervals: Interval[]; gaps?: Gap[]; label?: string;
+};
+type LaneFlag = 'none' | 'never-set' | 'empty-in-window';
+type Lane = {
+  id: string; version?: string | number; label: string; timezone?: string;
+  flag?: LaneFlag; complete?: boolean; layers: Layer[]; meta?: unknown;
+};
+type Window = { start: number; end: number };
+type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+type Span = 'day' | 'week' | 'month';
+type WindowSpec =
+  | { span: Span; anchorDate: string; wkst?: Weekday; timezone: string }
+  | { span: 'custom'; window: Window; timezone: string };
+type Transition = { at: number; deltaMinutes: number };
+type DayColumn = {
+  start: number; end: number; localDate: string; label: string; transitions: Transition[];
+};
+type Projection =
+  | { orientation: 'horizontal'; viewTimezone: string; pxPerMinute: number; rowHeight: number }
+  | { orientation: 'columns'; viewTimezone: string; pxPerHour: number; columnWidth: number; days: DayColumn[] };
+type Rect = {
+  x: number; y: number; width: number; height: number; layerId: string;
+  z: number; sources: Source[]; column?: number;
+};
+type Coverage = {
+  availabilityMinutes: number; bookingMinutes: number; availabilityMinusBookingMinutes: number;
+};
+type LaneGeometry = {
+  laneId: string; rects: Rect[]; gapRects: Rect[]; coverage: Coverage; flag: LaneFlag;
+};
+```
+
+All bounds are integer epoch milliseconds, [start, end). Preserve exact times;
+minuteStep is only for ticks and pointer snapping. Source equality uses both
+kind and id, not reference or label. Distinct labels do not create distinct
+sources. Use stable lane ids and unique layer ids within a lane.
+
+Role determines union coverage, not z-order. availabilityMinusBookingMinutes
+subtracts the intersection of the two role unions. Gaps are not subtracted again;
+the adapter must already have netted intervals. Layout splits source sets exactly:
+A 09:00 to 11:00 and B 10:00 to 12:00 gives {A}, {A,B}, {B}.
+
+Only upstream knowledge justifies never-set. With no explicit flag, intervals
+outside the requested window infer empty-in-window; all other cases infer none.
+complete defaults to true. Set false for capped or partially fetched output and
+show the incompleteLabel; do not describe incomplete empty time as definitive.
+
+## Entry points
+
+| Import | Runtime exports and purpose |
+| --- | --- |
+| react-native-roster | Roster, Schedule, useRoster, useSchedule, default slot components, and core re-exports. |
+| react-native-roster/core | layoutLane, coverageFor, flagFor, windowFor, prev, next, today, dayColumnsFor, timeAtX, timeAtY, snapToStep, byLabel, byCoverage, and core counters/caches. |
+| react-native-roster/rrule | expandRuleSet, envelopeFor, expandStats, resetExpandStats, clearExpandCache; RuleSet, RosterRule, RosterDate, ExpandOptions, ExpandResult, and ExpandStats types. |
+| react-native-roster/nativewind | Side-effect registration of Roster and Schedule with NativeWind's cssInterop, plus the registered Roster and Schedule and the rosterClassNames/scheduleClassNames mappings. Imports the optional nativewind peer. |
+
+No default exports. Root exports renderer inputs/models/slot input types as well as
+core types. Core imports standard JS and Intl only. Only /rrule imports
+rrule-temporal 1.6.0 and @js-temporal/polyfill 0.5.1. Those are installed runtime
+dependencies but cannot enter root/core bundles through library imports.
+
+Metro selects TS source via exports' react-native condition. Keep package exports
+enabled and one React copy in a workspace. Other resolvers load built CommonJS
+from dist/src; declarations use the types condition. Build before Node export
+tests. Root needs a native renderer or web bundler; direct Node use of root is
+not a substitute for a React Native app. Core and /rrule work in Node/Bun.
+
+## 0.1.0 slot prop rename
+
+0.1.0 renamed every input-bearing render-function Zone prop to a Component prop;
+use the current names below instead of the 0.0.x props. Singleton emptyZone and
+cornerZone keep their names and now take nodes. See [docs/migrations.md](./docs/migrations.md).
+Zone props are ReactNode.
+Component props are ComponentType<Input>.
+
+## Renderer contracts
+
+Roster required props: lanes: Lane[], windowSpec: WindowSpec.
+Optional: minuteStep (60), rowHeight (48), pxPerMinute (minimum 0.5, fits viewport),
+sortLanes (byLabel), highlightSource, onNavigate, onIntervalPress, onGapPress,
+onCellPress, onIntervalHover (web only), style, headerStyle, laneLabelColumnStyle,
+bodyStyle, laneLabelWidth (180), neverSetLabel, incompleteLabel, and zones below.
+Each style prop has a className twin (className, headerClassName,
+laneLabelColumnClassName, bodyClassName) resolved only after importing
+react-native-roster/nativewind. A class entry replaces the region's default
+paint (background and border colors) and keeps its structure, because React
+Native Web renders object styles inline where they would beat any class. Labels default to "No availability set" and "Availability may
+be incomplete". Supply a bounded height; Roster waits for viewport measurement
+before mounting LegendList. Reanimated keeps horizontal and vertical offsets
+outside React state.
+
+useRoster returns window, projection, orderedLanes, coverage, laneState,
+geometryFor(lane), scroll, press(lane,x,y), ticks, contentWidth, viewport,
+onLayout, navigate, and status ('empty' or 'ready'). There is no visibleRange
+field in the shipped public model. Custom layouts must wire onLayout. Custom
+bodies compute geometry only for mounted lanes, preserving virtualization.
+A zero-duration window has contentWidth=0 and renders no Roster body. Positive
+windows use their exact elapsed duration, including sub-minute spans. Cell times
+are clamped up to window.start and rejected at or beyond window.end.
+
+Schedule required props: lane: Lane, windowSpec: WindowSpec & {span:'day'|'week'}.
+Optional: minuteStep (60), pxPerHour (48, positive finite), highlightSource,
+onNavigate, onIntervalPress, onGapPress, onCellPress, style, headerStyle,
+gutterStyle, daysStyle, incompleteLabel, and zones below. Class twins are
+className, headerClassName, gutterClassName, and daysClassName. No month/custom
+spec, sort, or interval-hover prop.
+
+useSchedule returns window, days, projection, geometry, now (epoch ms or null),
+press(columnIndex,x,y), and status:'ready'. The standalone hook uses a 280 px grid.
+The chassis measures width, reserves a 48 px gutter, and fits all actual day
+columns without horizontal scrolling; the body scrolls vertically. now updates
+every minute and is null outside the selected window.
+
+Props ending in Component accept ComponentType<Input>, mounted as React elements.
+Props ending in Zone accept ReactNode; pass null to suppress a singleton default.
+Define component types at module scope; hooks and class components work normally.
+Use exported defaults inside replacements to preserve geometry, scrolling, and
+interaction. Input types, including HeaderCellInput, are exported from root.
+Mount a React context provider above Roster for extra consumer data, and read it with useContext in a module-scope slot component.
+Avoid inline closures or memoized factories returning a new component per render; new interval types remount every interval and defeat the body's content key.
+
+RosterBody composes the exported RosterBodyLayout (gridZone/listZone nodes with
+scroll wiring) and RosterLaneList (LegendList, geometryFor, and LaneRow mounting).
+Keep its viewport gate and measured estimatedListSize in custom compositions.
+
+## Roster zones
+
+| Slot | Component inputs or node | Default and behavior |
+| --- | --- | --- |
+| `emptyZone` | `ReactNode` | `RosterEmpty`: No lanes. |
+| `laneLabelComponent` | `lane`, `flag`, `complete`, `viewTimezone`, localized labels | `RosterLaneLabel`: label, differing IANA zone badge, and notices. |
+| `headerCellComponent` | `HeaderCellInput` (`tick`) | `RosterHeaderCell`: tick label. |
+| `intervalComponent` | `rect`, `layer`, `lane`, `highlighted` | `RosterInterval`: positioned colored rect, with final inset bounds. |
+| `gapComponent` | `rect`, `layer`, `lane` | `RosterGap`: no visible content; the row supplies pressable bounds. |
+| `gridComponent` | `ticks`, `contentWidth` | `RosterGrid`: one hairline per tick behind every lane. |
+| `cornerZone` | `ReactNode` | `RosterCorner`: nothing; the cell above the labels, laneLabelWidth wide. |
+| `headerComponent` | `ticks`, `projection`, `scroll`, `contentWidth`, `headerCellComponent` | `RosterHeader`: frozen header following horizontal offset. |
+| `laneLabelColumnComponent` | `labels: LaneLabelInput[]`, `projection`, `scroll`, `laneLabelComponent` | `RosterLaneLabelColumn`: frozen labels following vertical offset. |
+| `bodyComponent` | Ordered `lanes`, `window`, `geometryFor`, `projection`, `scroll`, `press`, `ticks`, `viewport`, `contentWidth`, highlight/hover, incomplete label, and rect components | `RosterBody`: virtualized lanes. |
+
+## Schedule zones
+
+| Slot | Component inputs or node | Default and behavior |
+| --- | --- | --- |
+| `gutterComponent` | `hours`, `pxPerHour` | `ScheduleGutter`: 24 frozen hour labels. |
+| `gridComponent` | `hours`, `pxPerHour` | `ScheduleGrid`: 24 bordered hour bands behind each day's rects. |
+| `dayHeaderComponent` | `day` | `ScheduleDayHeader`: weekday, localDate, and transition badge. |
+| `skippedDateComponent` | `localDate` | `ScheduleSkippedDate`: zero-width header marker for a wholly skipped date. |
+| `columnComponent` | `day`, `rects`, `gapRects`, `lane`, `highlightSource`, `press`, interval/gap components | `ScheduleColumn`: final rect bounds in layer order. |
+| `transitionComponent` | `day`, `transition`, `y`, `dividerY`, `height`, `width` | `ScheduleTransition`: skipped-time hatch, or repeat divider and again label. |
+| `nowLineComponent` | `y`, `column` | `ScheduleNowLine`: line in the current day's column, updated each minute. |
+| `intervalComponent`, `gapComponent` | Same inputs as Roster | Shared `RosterInterval` and `RosterGap`. |
+| `incompleteComponent` | `lane`, `label` | `ScheduleIncomplete`: notice in reserved space above the grid when incomplete. |
+
+Position custom interval content at rect.x/y with width/height/z and
+pointerEvents="none". Gap content already sits in a positioned pressable.
+Column x coordinates are local; select the column through rect.column.
+Slot components are plain React Native views; under NativeWind they take className
+directly. The default RosterLaneLabel owns its row's bottom border, so a custom
+laneLabelComponent draws its own separators.
+
+## Navigation and zones
+
+windowFor(spec) returns the absolute window. anchorDate is a local YYYY-MM-DD;
+changing timezone preserves it. Week starts Monday unless wkst overrides it;
+Weekday is Monday=0 through Sunday=6. prev/next move one span; custom moves by
+its own absolute duration. today reanchors to the view zone's local today.
+Month navigation clamps to the target month's final day when needed.
+Consumer controls update the controlled spec; there is no automatic toolbar.
+
+Rule/date timezone interprets local hours during expansion. Lane timezone only
+controls the IANA badge. View timezone is windowSpec.timezone, becoming
+projection.viewTimezone. No other view-timezone component prop exists.
+
+Roster uses true elapsed width (Chicago transition weeks have 167/169 hours).
+Schedule always uses 24 equal wall-hour bands. Positive deltaMinutes means a
+skipped empty region; negative means two half-height repeat regions. Rects split
+at column edges, source changes, and every scale boundary. For repeat at T with
+magnitude d, boundaries are T-d, T, and T+d. A wholly skipped date produces no
+column; skippedDateComponent labels the header gap (Apia 2011-12-30).
+Each column spans the first instant of its date to the first instant of the next.
+Skipped wall spans belong to the date they interrupt. Its transitions include a
+skip at the exclusive end when it empties that date's final wall bands (Nuuk
+2024-03-30, 23:00 to 24:00). Those bands are hatched; timeAtY returns null there,
+and onCellPress does not fire.
+For rollbacks across midnight (St_Johns 2009, Goose_Bay 1988), earlier-date instants
+inside that span draw in a compressed repeat at the top edge, ending where
+ordinary wall time resumes. timeAtY inverts this region to the absolute occurrence.
+The repeat divider uses dividerY, the projected transition instant, even when
+the surviving repeat regions have unequal heights.
+
+timeAtX(projection,window,x) returns absolute time with origin from window.
+timeAtY(projection,columnIndex,y) returns an absolute occurrence or null for
+skipped time/outside bounds. Inverse times stay below each scale piece's exclusive
+end, including immediately inside the bottom edge.
+snapToStep(time,minuteStep,timezone) floors by wall clock and clamps to occurrence start if flooring would cross a transition.
+minuteStep must be a positive integer divisor of 60.
+
+## Interaction and ordering
+
+One press yields one callback. Hit-test final rect bounds at the original point:
+intervals first, gaps second, empty space last. Highest z wins, then later layer
+wins among equal z. A low-z interval therefore wins over a high-z gap. Skipped
+schedule time fires nothing. Only empty-space times snap; 10:30 intervals stay
+pressable on a 60-minute grid. onIntervalPress(rect,lane), onGapPress(rect,lane),
+and onCellPress(lane,time) expose the outcome. Cell times clamp up to window.start
+and are rejected at or beyond window.end. Roster onIntervalHover(rect,lane)
+reports the winning web interval; native attaches no hover handler.
+
+highlightSource matches a fresh {kind,id} across lanes, using highlightColor or
+the normal layer color; it changes no geometry. byLabel is the default comparator.
+byCoverage({measure:'availability'|'availabilityMinusBooking'}) sorts descending
+with label ties. Custom LaneComparator is (a,b,coverage:ReadonlyMap<string,Coverage>)
+=> number. Coverage is assembled for all lanes before sorting; sorting does not
+precompute geometry for offscreen lanes. Newly mounted target-cold lanes can run
+layout. Scroll retains viewport offset, not a lane anchor.
+
+## Caches and counters
+
+layoutLane(lane,window,projection) computes rects for visible lanes only.
+coverageFor(lane,window) computes role unions for all lanes, projection-independent.
+flagFor(lane,window) is cheap and uncached. Geometry assembly reads fresh flag and
+coverage outside cached rects. Repeated complete inputs retain references; treat
+all results as read-only.
+
+Geometry key: lane.id + lane.version (or structural encoding of layers only) +
+window bounds + every projection field. Coverage uses the same key without
+projection. Bump any supplied version when layers change. Label, lane timezone,
+flag, complete, and meta never invalidate rects. Clear retained windows explicitly
+when a consumer no longer needs them. This cache lifetime belongs to the consumer.
+
+| Function | Meaning |
+| --- | --- |
+| layoutStats() | Cumulative {runs, cacheHits}; runs are geometry computations. |
+| coverageStats() | Cumulative {runs, cacheHits}; runs are coverage computations. |
+| resetStats() | Zero layout and coverage counters, preserve keys. |
+| clearLayoutCache(), clearCoverageCache() | Empty corresponding keys, preserve counters. |
+| expandStats() | Cumulative {rules, dates, expanded, cacheHits, cacheMisses}; expanded counts occurrence computations. |
+| resetExpandStats() | Zero expansion counters, preserve keys. |
+| clearExpandCache() | Empty occurrence entries and retained envelopes, preserve counters. |
+
+Target-warm means exact requested keys exist. Target-cold means they do not.
+Neither describes the whole cache. A projection change can be target-cold for
+layout and target-warm for coverage. Equal absolute windows reuse coverage even
+when view zones differ. Reanchoring UTC to Chicago changes the absolute week and
+requires coverage for all lanes, plus geometry for mounted lanes.
+
+## Recurrence adapter
+
+expandRuleSet(set,window,options?) returns {intervals,gaps,envelope,complete,
+truncated:[{id,droppedAtLeast}],stats}. It throws on invalid window, hours,
+recurrence fields, timezone, or date input. Treat malformed upstream data as an
+error; do not silently map errors to definitive empty lanes. A zero-duration window
+(start=end) validates every rule and date, including date, dtstart, until, and
+timezone, then returns empty intervals and gaps, complete=true, and expanded=0.
+
+RuleSet is {rules:RosterRule[],dates:RosterDate[]}.
+RosterRule requires id, kind:'include'|'exclude', frequency:'DAILY'|'WEEKLY'|'MONTHLY',
+dtstart (ISO date/datetime), hourstart, hourend, and timezone (IANA).
+Optional: until, count, interval, wkst, byweekday, bymonth, bymonthday, bysetpos.
+RosterDate requires id, kind, date (local ISO date), and timezone; optional note
+becomes Source.label. Hours are both present for partial day, both absent for
+whole day. A wholly skipped local date has no occurrences for either kind, with
+or without hours. Hours satisfy 0<=hourstart<hourend<=24 and may be fractional.
+Unsupported fields: byyearday, byweekno, byhour, byminute, bysecond. Convert enums,
+Date values, and nulls at the boundary; reject unsupported active semantics.
+
+Expansion uses one absolute envelope for every include, exclude, and date:
+envelopeFor(window) is window +/-48 absolute hours. The view zone is not an input.
+Enumeration retains the original dtstart except for interval-1 rules without
+COUNT whose anchor is exactly local midnight. Those rules may skip whole periods
+in plain-date space, preserving the weekly weekday and monthly day, and stepping
+back past nonexistent dates. Date-only and local-datetime dtstart preserve their
+authored date and time, even inside a skipped date or hour. Explicit-offset dtstart
+remains an instant, converted to wall fields and an offset in the rule's zone.
+The engine iterates those wall fields in UTC calendar space.
+Every rule enumerates from the period containing DTSTART at the anchor wall time,
+aligned to WKST for WEEKLY and day 1 for MONTHLY, so interval phases follow the
+DTSTART period rather than the first matching date. Dates before DTSTART are
+rejected before COUNT and cap admission.
+DAILY weekday filters are applied by the adapter to the authored daily sequence
+because the engine otherwise re-anchors at the first matching date.
+The engine uses the end of UNTIL's local date as a conservative UTC enumeration bound.
+Explicit-offset UNTIL uses the end of the following local date instead; exact instant
+admission is its only UNTIL admission test. Clamp either bound to the corresponding
+UTC calendar bound of the envelope query.
+The enumeration bound is conservative through the wall date after any cross-date rollback
+at the envelope end, and envelope clipping discards the extra candidates.
+The adapter owns BYSETPOS after every other BYxxx filter, grouping plain dates
+by day, WKST week, or year-month before deduplication, UNTIL, COUNT, and cap admission.
+Positional enumeration includes complete edge periods, then rejects dates before
+DTSTART and spans outside the envelope. The engine iteration limit is the number
+of authored periods from the enumeration anchor through the query bound, so empty
+candidate periods terminate completely without an arbitrary cutoff. Only that
+exact engine limit error signals completed enumeration; other failures propagate.
+Replayed iterator passes stop before buffering positional candidates.
+YEARLY is unsupported and rejected by input validation.
+The adapter
+drops wholly nonexistent dates before counting existing dates from the original
+anchor for COUNT. A skipped date never becomes a different weekday or consumes
+COUNT. The adapter admits each emitted date only when that date is at or before
+the authored date-only UNTIL,
+including when its final hour or the whole date is skipped. Local datetime UNTIL
+compares plain date-times at the authored dtstart wall time, without normalizing
+skipped hours. Explicit-offset UNTIL compares exact instants, preferring an
+explicit-offset dtstart's offset in repeats and using compatible disambiguation
+otherwise. A datetime UNTIL before DTSTART admits nothing.
+This keeps UNTIL admission independent of anchor advancement and retained envelopes.
+Occurrences outside the envelope never consume the occurrence cap.
+Retained-envelope containment selects existing bounds before creating a new
+padded envelope. One shared LRU spans all sets (default maxEnvelopes=4);
+containment selects the most recently used matching envelope.
+Per-item keys use occurrence body content + exact envelope + perRuleOccurrences.
+Id and dated note attach freshly in assembly; include/exclude kind remains in the body key. Unchanged
+bodies reuse occurrences only if those exact keys still exist (maxEntries=2000).
+Editing a set reuses containing envelopes; unchanged item keys may still hit.
+Envelope retention alone never guarantees expanded=0 after occurrence eviction.
+
+Netting and total caps run fresh on every call, then clip to display window.
+Includes supply interval sources; excludes supply gap sources. Fully excluded
+includes leave gaps. No minute-step snapping. Defaults: caps.perRuleOccurrences=400,
+caps.totalOccurrences=10000; options.cache.maxEntries=2000, maxEnvelopes=4.
+All accept nonnegative integers. Zero cache budgets disable retention; zero caps
+admit no occurrences. Both occurrence entries and retained envelopes are bounded
+globally across sets; clear when discarding old windows.
+
+Per-rule cap truncation reports droppedAtLeast=1 (unknown remainder). The total
+cap admits whole lists in rule-id order, then date-id order. First list that
+cannot fit and every later list are dropped; exact fully enumerated counts are
+reported. Equality fits. Caps apply across the envelope, not only visible time.
+Changing the total cap changes assembly, not occurrence keys; changing the
+per-rule cap changes all requested occurrence keys. Incomplete output can omit
+exclusions too; it is not necessarily a conservative subset. Always map
+result.complete to Lane.complete.
+
+```ts
+import type { Lane } from 'react-native-roster/core';
+import { windowFor } from 'react-native-roster/core';
+import { expandRuleSet } from 'react-native-roster/rrule';
+import type { RuleSet } from 'react-native-roster/rrule';
+
+export function laneFromRules(set: RuleSet): Lane {
+  const window = windowFor({ span: 'week', anchorDate: '2024-01-01', timezone: 'UTC' });
+  const result = expandRuleSet(set, window);
+  return { id: 'one', label: 'One', complete: result.complete, layers: [{
+    id: 'open', role: 'availability', z: 0, style: { color: '#4f9478' },
+    intervals: result.intervals, gaps: result.gaps,
+  }] };
+}
+```
+
+## Gallery, evidence, and non-goals
+
+The home page derives links from named roster and schedule fixture records.
+Explicit routes cover each day/week/month at 15/30/60-minute steps, lane counts,
+provenance, flags, timezones, Schedule transitions, and default/replaced zones.
+Adapter weekly/override/cap routes render editable JSON beside the roster through
+ruleSetEditorZone. useRuleSetDraft owns text, parse result, and the applied set;
+Apply validates before updating the roster, keeping the last valid set on error.
+These are demo hooks/zones, not library exports.
+
+Every route exposes live counter functions on web window.__roster. Its identity
+stays stable until unmount; on-screen snapshots sample every 500 ms. The 200-lane
+route feeds real adapter output to workload W and includes cold-layout, rule-hour,
+and unrelated-lane-zone controls for the browser/device protocol.
+
+Web static export and Chromium checks complement iOS/Android implementations;
+physical-device rendering and Hermes Intl behavior remain unverified here.
+Production web Profiler callbacks are disabled. check:web also exports development
+web and checks actual LegendList LaneRow commits on the second scroll pass, with
+nonzero mount and highlight-update controls. The development 200-lane route exposes
+profileStats() through window.__roster. Bun host tests remain complementary; a
+native LaneRow profile is required for release. Pages deployment
+is configured from main but cannot be proven by local export.
+
+W: seed 1318, 200 lanes, week, two layers, 24-lane layout batch, 15-minute ticks;
+63 rects + 7 gap rects per lane. test/performance/baseline.json records layout
+2.070 ms and all-200-lane coverage 1.063 ms on GitHub Actions ubuntu-latest,
+Bun 1.4.0, 2026-09-08T05:18:00Z, commit
+1c4ac0e8580b1d46c043f946aa7ebc1ee316d0fa. Median of 11 target-cold samples after
+five runtime warmups. Each timing must stay below 16 ms; CI also enforces <=1.5x
+its baseline. Size gates: core <15 kB, root <44 kB minified/uncompressed, peers
+external. Phone fps and cold-layout numbers are not yet captured; the paired
+react-big-scheduler comparison is not yet measured. Do not claim relative speed.
+
+The package does not create, drag, resize, persist, or authorize intervals; it
+is not a general calendar. Consumers implement their own interactions. A rule
+editor in the gallery is an integration example, not a rule-authoring product.
+
+## Reference
+
+- [README](./README.md): runnable quick starts, setup, zones, and measured evidence.
+- [Adapter guide](./docs/adapters.md): table/feed conversion and memoization contract.
+- Area landing pages: [core](./src/core/README.md), [Roster](./src/components/roster/README.md),
+  [Schedule](./src/components/schedule/README.md), [layers](./src/components/layers/README.md),
+  [primitives](./src/components/primitives/README.md), [rrule adapter](./src/adapters/rrule/README.md),
+  [nativewind](./src/nativewind/README.md), [gallery](./demo/components/gallery/README.md),
+  [showcase](./demo/components/team-roster/README.md), [theme](./demo/components/theme/README.md);
+  [adding an adapter](./docs/adding-an-adapter.md).
+- [Design note](./docs/design.md): reasoning and non-goals.
+- [Performance](./docs/performance.md): automated budgets and exact-commit device capture.
+- [AGENTS.md](./AGENTS.md): repository conventions, not consumer API requirements.
+- [CONTRIBUTING.md](./CONTRIBUTING.md): commands and release process.