aeon-ui-engine 1.8.0 → 1.9.0

package/packages/primitives/src/machines/cache.ts

@@ -0,0 +1,395 @@
+import { assign, createActor, fromCallback, fromPromise, setup, type ActorRefFrom, type SnapshotFrom } from 'xstate'
+
+/** Stable lifecycle states of one cache entry (see STATES.md). */
+export const CACHE_STATES = ['idle', 'loading', 'ready', 'stale', 'refreshing', 'failed'] as const
+
+export type CacheState = (typeof CACHE_STATES)[number]
+
+/** Longest delay a timer can hold; a longer time-to-live is checked again when read. */
+const MAX_DELAY_MS = 2_147_483_647
+
+/**
+ * Caches named for secrets, keys or spend decisions are refused: those must be
+ * read fresh every time, never served from memory.
+ */
+const NEVER_CACHE = /\b(secrets?|private[-_ ]?keys?|mnemonics?|seeds?|passwords?|passphrases?|wif|xprv|signing[-_ ]?keys?|spend)\b/i
+
+export function isCacheableId(id: string): boolean {
+  return id.trim().length > 0 && !NEVER_CACHE.test(id)
+}
+
+export interface CacheEntryContext<T, K> {
+  key: K
+  ttl: number
+  data: T | undefined
+  error: string | null
+  /** When `data` was loaded; null while there is none. */
+  loadedAt: number | null
+  /** An invalidation landed mid-load: the result may predate the write, so load once more. */
+  dirty: boolean
+  now: () => number
+}
+
+export type CacheEntryEvent =
+  | { type: 'FETCH' }
+  | { type: 'REFRESH' }
+  | { type: 'INVALIDATE'; refetch?: boolean }
+  | { type: 'CLEAR' }
+
+export interface CacheEntryInput<K> {
+  key: K
+  ttl: number
+  now?: () => number
+}
+
+const message = (error: unknown) => (error instanceof Error ? error.message : String(error))
+
+/**
+ * One keyed entry: idle until fetched, loading the first time, ready while
+ * younger than its time-to-live, then stale. FETCH on a stale or expired entry
+ * revalidates in `refreshing` while the old data stays readable; FETCH while a
+ * load runs is dropped, so one load serves every caller. INVALIDATE marks the
+ * entry stale (and reloads when `refetch`); CLEAR drops the data and cancels a
+ * running load so its result never lands.
+ */
+export function createCacheEntryMachine<T, K = string>() {
+  return setup({
+    types: {
+      context: {} as CacheEntryContext<T, K>,
+      events: {} as CacheEntryEvent,
+      input: {} as CacheEntryInput<K>,
+    },
+    actors: {
+      load: fromPromise<T, { key: K }>(async () => {
+        throw new Error('cache entry load is not provided')
+      }),
+    },
+    delays: {
+      ttl: ({ context }) => {
+        const age = context.loadedAt === null ? 0 : context.now() - context.loadedAt
+        return Math.min(Math.max(0, context.ttl - age), MAX_DELAY_MS)
+      },
+    },
+    guards: {
+      expired: ({ context }) => context.loadedAt !== null && context.now() - context.loadedAt >= context.ttl,
+      dirty: ({ context }) => context.dirty,
+      refetch: ({ event }) => event.type === 'INVALIDATE' && event.refetch === true,
+    },
+    actions: {
+      markDirty: assign({ dirty: true }),
+      clear: assign({ data: undefined, error: null, loadedAt: null, dirty: false }),
+    },
+  }).createMachine({
+    id: 'cacheEntry',
+    context: ({ input }) => ({
+      key: input.key,
+      ttl: input.ttl,
+      data: undefined,
+      error: null,
+      loadedAt: null,
+      dirty: false,
+      now: input.now ?? Date.now,
+    }),
+    initial: 'idle',
+    on: { CLEAR: { target: '.idle', actions: 'clear' } },
+    states: {
+      idle: {
+        on: { FETCH: 'loading', REFRESH: 'loading', INVALIDATE: { guard: 'refetch', target: 'loading' } },
+      },
+      loading: {
+        invoke: {
+          src: 'load',
+          input: ({ context }) => ({ key: context.key }),
+          onDone: [
+            {
+              guard: 'dirty',
+              target: 'refreshing',
+              actions: assign(({ context, event }) => ({ data: event.output, error: null, loadedAt: context.now(), dirty: false })),
+            },
+            {
+              target: 'ready',
+              actions: assign(({ context, event }) => ({ data: event.output, error: null, loadedAt: context.now() })),
+            },
+          ],
+          onError: { target: 'failed', actions: assign(({ event }) => ({ error: message(event.error), dirty: false })) },
+        },
+        on: { INVALIDATE: { actions: 'markDirty' } },
+      },
+      ready: {
+        after: { ttl: { guard: 'expired', target: 'stale' } },
+        on: {
+          FETCH: { guard: 'expired', target: 'refreshing' },
+          REFRESH: 'refreshing',
+          INVALIDATE: [{ guard: 'refetch', target: 'refreshing' }, { target: 'stale' }],
+        },
+      },
+      stale: {
+        on: { FETCH: 'refreshing', REFRESH: 'refreshing', INVALIDATE: { guard: 'refetch', target: 'refreshing' } },
+      },
+      refreshing: {
+        invoke: {
+          src: 'load',
+          input: ({ context }) => ({ key: context.key }),
+          onDone: [
+            {
+              guard: 'dirty',
+              target: 'refreshing',
+              reenter: true,
+              actions: assign(({ context, event }) => ({ data: event.output, error: null, loadedAt: context.now(), dirty: false })),
+            },
+            {
+              target: 'ready',
+              actions: assign(({ context, event }) => ({ data: event.output, error: null, loadedAt: context.now() })),
+            },
+          ],
+          onError: { target: 'stale', actions: assign(({ event }) => ({ error: message(event.error), dirty: false })) },
+        },
+        on: { INVALIDATE: { actions: 'markDirty' } },
+      },
+      failed: {
+        on: { FETCH: 'loading', REFRESH: 'loading', INVALIDATE: { guard: 'refetch', target: 'loading' } },
+      },
+    },
+  })
+}
+
+export const cacheEntryMachine = createCacheEntryMachine()
+
+export type CacheEntryActor<T, K = string> = ActorRefFrom<ReturnType<typeof createCacheEntryMachine<T, K>>>
+type CacheEntrySnapshot<T, K> = SnapshotFrom<ReturnType<typeof createCacheEntryMachine<T, K>>>
+
+/**
+ * What a reader sees of one entry. The same object comes back until the entry
+ * changes, and `data` keeps its identity across ready, stale and refreshing,
+ * so selectors over a view never cause a re-render on their own.
+ */
+export interface CacheView<T> {
+  readonly state: CacheState
+  readonly data: T | undefined
+  readonly error: string | null
+  readonly loadedAt: number | null
+}
+
+const IDLE_VIEW: CacheView<never> = Object.freeze({ state: 'idle', data: undefined, error: null, loadedAt: null })
+
+/** Commands a chart sends the cache, directly or through the invoked cache actor. */
+export type CacheCommand<K> =
+  | { type: 'CACHE.FETCH'; key?: K }
+  | { type: 'CACHE.REFRESH'; key?: K }
+  | { type: 'CACHE.INVALIDATE'; key?: K; tag?: string }
+  | { type: 'CACHE.KEY'; key: K }
+  | { type: 'CACHE.CLEAR' }
+
+/** What the invoked cache actor sends its parent chart whenever its entry changes. */
+export interface CacheUpdate<T, K> {
+  type: 'CACHE.UPDATE'
+  cache: string
+  key: K
+  view: CacheView<T>
+}
+
+export interface ChartCacheOptions<T, K> {
+  /** Names the cache in logs and errors. Names of secrets, keys or spend decisions are refused. */
+  id: string
+  load: (key: K, context: { signal: AbortSignal }) => Promise<T>
+  /** Milliseconds an entry stays fresh, for every key or per key. */
+  ttl: number | ((key: K) => number)
+  tags?: (key: K) => readonly string[]
+  /** Turns a key into the string entries are stored under. Defaults to `String` for strings, else JSON. */
+  keyOf?: (key: K) => string
+  /** Most entries kept; the least recently used unwatched, settled ones go first. Default 100. */
+  maxEntries?: number
+  now?: () => number
+}
+
+export interface ChartCache<T, K = string> {
+  readonly id: string
+  /** Entries currently held. */
+  readonly size: number
+  /** The entry's current view, without loading it. Stable until the entry changes. */
+  peek(key: K): CacheView<T>
+  /** Loads the entry if it is missing, failed, stale or expired; a running load is reused. */
+  fetch(key: K): void
+  /** Reloads now, keeping the old data readable meanwhile. */
+  refresh(key: K): void
+  /** Resolves with the entry's data, serving stale data at once while it revalidates. */
+  read(key: K): Promise<T>
+  /** Marks entries stale; watched ones reload at once. */
+  invalidate(target: { key: K } | { tag: string }): void
+  /** Drops every entry's data and cancels running loads (lock, account or network switch). */
+  clear(): void
+  subscribe(key: K, listener: (view: CacheView<T>) => void): () => void
+  send(command: CacheCommand<K>): void
+  /**
+   * Invoke from a chart: `invoke: { id: 'cache', src: cache.actor, input: { key } }`.
+   * It fetches the key, sends `CACHE.UPDATE` on every change, and takes
+   * `CACHE.*` commands from the parent (`sendTo('cache', …)`); commands without
+   * a key apply to its own, and `CACHE.KEY` moves it to another key.
+   */
+  readonly actor: ReturnType<typeof fromCallback<CacheCommand<K>, { key: K; fetch?: boolean }>>
+}
+
+interface Slot<T, K> {
+  key: K
+  tags: readonly string[]
+  actor: CacheEntryActor<T, K>
+  view: CacheView<T>
+  listeners: Set<(view: CacheView<T>) => void>
+  usedAt: number
+}
+
+const defaultKeyOf = (key: unknown) => (typeof key === 'string' ? key : JSON.stringify(key))
+
+function viewOf<T, K>(snapshot: CacheEntrySnapshot<T, K>, previous: CacheView<T>): CacheView<T> {
+  const state = snapshot.value as CacheState
+  const { data, error, loadedAt } = snapshot.context
+  if (previous.state === state && previous.data === data && previous.error === error && previous.loadedAt === loadedAt) return previous
+  return Object.freeze({ state, data, error, loadedAt })
+}
+
+/**
+ * A keyed cache shared by every chart that reads it, so a remounted chart is
+ * served from memory instead of loading again. Each entry is its own
+ * `cacheEntryMachine`; create one cache per kind of data at module scope.
+ */
+export function createChartCache<T, K = string>(options: ChartCacheOptions<T, K>): ChartCache<T, K> {
+  if (!isCacheableId(options.id)) throw new Error(`refusing to cache "${options.id}": secrets, keys and spend decisions are never cached`)
+  const keyOf = options.keyOf ?? defaultKeyOf
+  const maxEntries = Math.max(1, options.maxEntries ?? 100)
+  const ttlOf = typeof options.ttl === 'function' ? options.ttl : () => options.ttl as number
+  const machine = createCacheEntryMachine<T, K>().provide({
+    actors: { load: fromPromise<T, { key: K }>(({ input, signal }) => options.load(input.key, { signal })) },
+  })
+  const slots = new Map<string, Slot<T, K>>()
+  let clock = 0
+
+  const busy = (slot: Slot<T, K>) => slot.view.state === 'loading' || slot.view.state === 'refreshing'
+
+  const evict = (keep?: Slot<T, K>) => {
+    if (slots.size <= maxEntries) return
+    const idle = [...slots.entries()]
+      .filter(([, slot]) => slot !== keep && slot.listeners.size === 0 && !busy(slot))
+      .sort((a, b) => a[1].usedAt - b[1].usedAt)
+    for (const [id, slot] of idle) {
+      if (slots.size <= maxEntries) break
+      slot.actor.stop()
+      slots.delete(id)
+    }
+  }
+
+  const slotFor = (key: K): Slot<T, K> => {
+    const id = keyOf(key)
+    const existing = slots.get(id)
+    if (existing) {
+      existing.usedAt = ++clock
+      return existing
+    }
+    const actor = createActor(machine, { input: { key, ttl: ttlOf(key), now: options.now } })
+    const slot: Slot<T, K> = { key, tags: options.tags?.(key) ?? [], actor, view: IDLE_VIEW, listeners: new Set(), usedAt: ++clock }
+    actor.subscribe((snapshot) => {
+      const next = viewOf(snapshot, slot.view)
+      if (next === slot.view) return
+      slot.view = next
+      for (const listener of [...slot.listeners]) listener(next)
+    })
+    slots.set(id, slot)
+    actor.start()
+    evict(slot)
+    return slot
+  }
+
+  const invalidateSlot = (slot: Slot<T, K>) => slot.actor.send({ type: 'INVALIDATE', refetch: slot.listeners.size > 0 })
+
+  const cache: Omit<ChartCache<T, K>, 'actor' | 'size'> & { actor?: ChartCache<T, K>['actor'] } = {
+    id: options.id,
+    peek: (key) => slots.get(keyOf(key))?.view ?? IDLE_VIEW,
+    fetch: (key) => slotFor(key).actor.send({ type: 'FETCH' }),
+    refresh: (key) => slotFor(key).actor.send({ type: 'REFRESH' }),
+    read: (key) =>
+      new Promise<T>((resolve, reject) => {
+        const slot = slotFor(key)
+        const settle = (view: CacheView<T>) => {
+          if (view.loadedAt !== null && view.state !== 'loading') resolve(view.data as T)
+          else if (view.state === 'failed') reject(new Error(view.error ?? `${options.id} failed to load`))
+          else return false
+          return true
+        }
+        slot.actor.send({ type: 'FETCH' })
+        if (settle(slot.view)) return
+        const stop = cache.subscribe(key, (view) => {
+          if (settle(view)) stop()
+        })
+      }),
+    invalidate: (target) => {
+      if ('key' in target) {
+        const slot = slots.get(keyOf(target.key))
+        if (slot) invalidateSlot(slot)
+        return
+      }
+      for (const slot of slots.values()) if (slot.tags.includes(target.tag)) invalidateSlot(slot)
+    },
+    clear: () => {
+      for (const [id, slot] of [...slots.entries()]) {
+        slot.actor.send({ type: 'CLEAR' })
+        if (slot.listeners.size === 0) {
+          slot.actor.stop()
+          slots.delete(id)
+        }
+      }
+    },
+    subscribe: (key, listener) => {
+      const slot = slotFor(key)
+      slot.listeners.add(listener)
+      return () => {
+        slot.listeners.delete(listener)
+        evict()
+      }
+    },
+    send: (command) => {
+      switch (command.type) {
+        case 'CACHE.FETCH':
+          if (command.key !== undefined) cache.fetch(command.key)
+          return
+        case 'CACHE.REFRESH':
+          if (command.key !== undefined) cache.refresh(command.key)
+          return
+        case 'CACHE.INVALIDATE':
+          if (command.tag !== undefined) cache.invalidate({ tag: command.tag })
+          else if (command.key !== undefined) cache.invalidate({ key: command.key })
+          return
+        case 'CACHE.KEY':
+          cache.fetch(command.key)
+          return
+        case 'CACHE.CLEAR':
+          cache.clear()
+          return
+      }
+    },
+  }
+
+  cache.actor = fromCallback<CacheCommand<K>, { key: K; fetch?: boolean }>(({ input, sendBack, receive }) => {
+    let key = input.key
+    let stop = () => {}
+    const watch = (next: K, fetch: boolean) => {
+      stop()
+      key = next
+      const report = (view: CacheView<T>) => sendBack({ type: 'CACHE.UPDATE', cache: options.id, key: next, view } satisfies CacheUpdate<T, K>)
+      stop = cache.subscribe(next, report)
+      report(cache.peek(next))
+      if (fetch) cache.fetch(next)
+    }
+    watch(key, input.fetch !== false)
+    receive((command) => {
+      if (command.type === 'CACHE.KEY') {
+        if (keyOf(command.key) !== keyOf(key)) watch(command.key, true)
+        return
+      }
+      if (command.type === 'CACHE.CLEAR') return cache.clear()
+      if (command.type === 'CACHE.INVALIDATE' && command.tag !== undefined) return cache.send(command)
+      cache.send({ ...command, key: command.key ?? key } as CacheCommand<K>)
+    })
+    return () => stop()
+  })
+
+  return Object.defineProperty(cache, 'size', { get: () => slots.size, enumerable: true }) as ChartCache<T, K>
+}

package/packages/primitives/src/machines/clipboard.ts

@@ -0,0 +1,56 @@
+import { playSound } from '@aeon-ui/core'
+import { fromPromise, setup } from 'xstate'
+
+/**
+ * Copy-to-clipboard feedback.
+ *
+ * Events: COPY { value } writes `value` to the system clipboard.
+ * States: idle → copying → copied | failed, back to idle after `timeout` ms. COPY again restarts.
+ * Entering copied / failed plays the `copy` / `error` sound (silent unless the app enabled sounds).
+ */
+export interface ClipboardContext {
+  /** How long `copied` / `failed` show before returning to idle, in ms. */
+  timeout: number
+}
+
+export type ClipboardEvent = { type: 'COPY'; value: string }
+
+export const CLIPBOARD_STATES = ['idle', 'copying', 'copied', 'failed'] as const
+export type ClipboardStatus = (typeof CLIPBOARD_STATES)[number]
+
+export const clipboardMachine = setup({
+  types: {
+    context: {} as ClipboardContext,
+    events: {} as ClipboardEvent,
+    input: {} as Partial<ClipboardContext> | undefined,
+  },
+  actors: {
+    write: fromPromise<void, { value: string }>(async ({ input }) => {
+      await navigator.clipboard.writeText(input.value)
+    }),
+  },
+  actions: {
+    soundCopied: () => playSound('copy'),
+    soundFailed: () => playSound('error'),
+  },
+  delays: {
+    timeout: ({ context }) => context.timeout,
+  },
+}).createMachine({
+  id: 'clipboard',
+  context: ({ input }) => ({ timeout: input?.timeout ?? 1500 }),
+  initial: 'idle',
+  states: {
+    idle: { on: { COPY: 'copying' } },
+    copying: {
+      invoke: {
+        src: 'write',
+        input: ({ event }) => ({ value: (event as ClipboardEvent).value }),
+        onDone: 'copied',
+        onError: 'failed',
+      },
+    },
+    copied: { entry: 'soundCopied', after: { timeout: 'idle' }, on: { COPY: 'copying' } },
+    failed: { entry: 'soundFailed', after: { timeout: 'idle' }, on: { COPY: 'copying' } },
+  },
+})

package/packages/react/dist/index.d.ts

@@ -1,12 +1,12 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, HTMLAttributes, InputHTMLAttributes, LabelHTMLAttributes, TextareaHTMLAttributes, RefObject, ImgHTMLAttributes, FormHTMLAttributes } from 'react';
+import { ButtonHTMLAttributes, ReactNode, HTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, CSSProperties, ForwardedRef, LabelHTMLAttributes, RefObject, ImgHTMLAttributes, FormHTMLAttributes } from 'react';
 import * as xstate from 'xstate';
 import { AnyStateMachine } from 'xstate';
 import { useMachine } from '@xstate/react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { AsyncContext, ContentRegionState, AppNavChild, StickyBarState } from '@aeon-ui/primitives';
 export { AppNavChild, AppNavContext, createAsyncMachine, fieldMachine } from '@aeon-ui/primitives';
-import { fieldFace, AeonColorMode, ResponsiveLayoutSpec, LayoutMode, LayoutCompositionSpec } from '@aeon-ui/core';
+import { fieldFace, ListWindowAxis, ListWindow, AeonColorMode, ResponsiveLayoutSpec, LayoutMode, LayoutCompositionSpec } from '@aeon-ui/core';
 export { AeonColorMode as AeonMode } from '@aeon-ui/core';
 
 /** Action button lifecycle — see STATES.md and `buttonLifecycleMachine`. */
@@ -134,7 +134,7 @@ declare const StatusBanner: {
     Action: react.ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & react.RefAttributes<HTMLButtonElement>>;
 };
 
-interface TabsRootProps {
+interface TabsRootProps extends Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange' | 'children'> {
     value?: string;
     defaultValue?: string;
     onValueChange?: (value: string) => void;
@@ -162,6 +162,64 @@ declare const Separator: {
     Root: react.ForwardRefExoticComponent<SeparatorRootProps & react.RefAttributes<HTMLDivElement>>;
 };
 
+type ProseRootProps = HTMLAttributes<HTMLDivElement>;
+declare const Prose: {
+    Root: react.ForwardRefExoticComponent<ProseRootProps & react.RefAttributes<HTMLDivElement>>;
+};
+
+/** Row limits as the CSS variables Aeon's auto-growing textareas read (Textarea, Composer.Input). */
+declare function rowLimits(minRows?: number, maxRows?: number): CSSProperties;
+/**
+ * Grows a textarea to its content where CSS `field-sizing` is missing (Firefox); the recipe's
+ * min / max height still clamp it. Spread the result onto the textarea.
+ */
+declare function useAutoGrow(forwarded: ForwardedRef<HTMLTextAreaElement>, value: unknown): {
+    ref: (el: HTMLTextAreaElement | null) => void;
+    onInput: () => void;
+};
+interface TextareaRootProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** Height floor in lines. */
+    minRows?: number;
+    /** Height ceiling in lines; past it the textarea scrolls. Omit to grow without limit. */
+    maxRows?: number;
+}
+declare const Textarea: {
+    Root: react.ForwardRefExoticComponent<TextareaRootProps & react.RefAttributes<HTMLTextAreaElement>>;
+};
+
+interface SegmentGroupRootProps extends Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange'> {
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    disabled?: boolean;
+    orientation?: 'horizontal' | 'vertical';
+}
+interface SegmentGroupItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'value'> {
+    value: string;
+}
+declare const SegmentGroup: {
+    Root: react.ForwardRefExoticComponent<SegmentGroupRootProps & react.RefAttributes<HTMLDivElement>>;
+    Item: react.ForwardRefExoticComponent<SegmentGroupItemProps & react.RefAttributes<HTMLButtonElement>>;
+};
+
+/** Read the copy status from any part inside Clipboard.Root. */
+declare const useClipboardStatus: () => "idle" | "copying" | "copied" | "failed";
+interface ClipboardRootProps extends HTMLAttributes<HTMLDivElement> {
+    /** Text written to the clipboard; read at the moment of copying. */
+    value: string;
+    /** How long copied / failed show, in ms. */
+    timeout?: number;
+}
+interface ClipboardIndicatorProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Shown while copied; `children` show otherwise. */
+    copied?: ReactNode;
+}
+declare const Clipboard: {
+    Root: react.ForwardRefExoticComponent<ClipboardRootProps & react.RefAttributes<HTMLDivElement>>;
+    Trigger: react.ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & react.RefAttributes<HTMLButtonElement>>;
+    Indicator: react.ForwardRefExoticComponent<ClipboardIndicatorProps & react.RefAttributes<HTMLSpanElement>>;
+};
+
 interface ProgressRootProps extends HTMLAttributes<HTMLDivElement> {
     value?: number;
     max?: number;
@@ -176,7 +234,7 @@ declare const Progress: {
     Label: react.ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElement> & react.RefAttributes<HTMLSpanElement>>;
 };
 
-interface RadioGroupRootProps {
+interface RadioGroupRootProps extends Omit<HTMLAttributes<HTMLDivElement>, 'defaultValue' | 'onChange' | 'children'> {
     value?: string;
     defaultValue?: string;
     onValueChange?: (value: string) => void;
@@ -472,6 +530,33 @@ declare const Field: {
 /** Subscribe to scroll + resize; returns data-aeon-state value for a viewport. */
 declare function useScrollState(ref: RefObject<HTMLElement | null>): string;
 
+interface UseWindowedRangeOptions {
+    total: number;
+    /** Fallback row pitch, used until a row can be measured. */
+    itemExtent: number;
+    /** Fallback column count for grids; the real count is read from the grid. */
+    columns?: number;
+    overscan?: number;
+    /** Restrict measuring to real rows when the list also holds other chrome. */
+    rowSelector?: string;
+    minItems?: number;
+    /** `x` windows a horizontal strip by item width; columns do not apply. */
+    axis?: ListWindowAxis;
+    /** The list element itself; its scrollable ancestor drives the window. */
+    scrollRef: RefObject<HTMLElement | null>;
+}
+/**
+ * Windowed slice for long lists and grids. Render `items.slice(start, end)`
+ * between spacers of `padStart` / `padEnd` (spread `listWindowPadAttrs`) or
+ * as list padding; each row keeps its own data-aeon-* projection.
+ *
+ * The first render windows from the hints, so a long list never mounts whole.
+ * Measuring reads layout, so it runs at most once per frame, and the window is
+ * published only when it moves: a scroll inside the current window renders
+ * nothing.
+ */
+declare function useWindowedRange(options: UseWindowedRangeOptions): ListWindow;
+
 interface ScrollContextValue {
     stateAttr: string;
 }
@@ -488,6 +573,10 @@ declare const Scroll: {
     Content: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
 };
 
+type AnchorSide = 'top' | 'bottom';
+type AnchorAlign = 'start' | 'end' | 'center';
+type AnchorPlacement = `${AnchorSide}-${AnchorAlign}`;
+
 interface SelectRootProps {
     value: string;
     onValueChange?: (value: string) => void;
@@ -498,6 +587,11 @@ interface SelectRootProps {
 interface SelectPositionerProps extends HTMLAttributes<HTMLDivElement> {
     /** Mount listbox in document.body (default true). */
     portalled?: boolean;
+    placement?: AnchorPlacement;
+    /** Align to this region rather than the trigger. See `FloatingPositioner`. */
+    anchorRef?: RefObject<HTMLElement | null>;
+    /** Size the listbox to the anchor (default true). */
+    matchAnchorWidth?: boolean;
     children?: ReactNode;
 }
 interface SelectContentProps extends HTMLAttributes<HTMLDivElement> {
@@ -540,10 +634,6 @@ declare const Combobox: {
     Empty: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
 };
 
-type AnchorSide = 'top' | 'bottom';
-type AnchorAlign = 'start' | 'end' | 'center';
-type AnchorPlacement = `${AnchorSide}-${AnchorAlign}`;
-
 interface PopoverRootProps {
     open?: boolean;
     defaultOpen?: boolean;
@@ -900,9 +990,15 @@ interface ComposerRootProps extends FormHTMLAttributes<HTMLFormElement> {
     state?: ComposerState;
     children?: ReactNode;
 }
+interface ComposerInputProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** Height floor in lines (default 1). */
+    minRows?: number;
+    /** Height ceiling in lines before the input scrolls (default 4). */
+    maxRows?: number;
+}
 declare const Composer: {
     Root: react.ForwardRefExoticComponent<ComposerRootProps & react.RefAttributes<HTMLFormElement>>;
-    Input: react.ForwardRefExoticComponent<TextareaHTMLAttributes<HTMLTextAreaElement> & react.RefAttributes<HTMLTextAreaElement>>;
+    Input: react.ForwardRefExoticComponent<ComposerInputProps & react.RefAttributes<HTMLTextAreaElement>>;
     Actions: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
     Send: react.ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElement> & react.RefAttributes<HTMLSpanElement>>;
     Toolbar: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
@@ -1211,4 +1307,4 @@ declare const Slot: react.ForwardRefExoticComponent<HTMLAttributes<HTMLElement>
     children?: ReactNode;
 } & react.RefAttributes<HTMLElement>>;
 
-export { Accordion, type AccordionItemContentProps, type AccordionItemProps, type AccordionItemTriggerProps, type AccordionRootProps, AppNav, type AppNavBreadcrumbProps, type AppNavRootProps, type AppNavSectionProps, AppShell, type AppShellRootProps, Async, AsyncActions, AsyncProvider, AsyncReadout, AsyncRoot, AsyncTrack, Avatar, type AvatarRootProps, type AvatarStatus, Bar, type BarRootProps, Button, type ButtonRootProps, type ButtonStatus, Checkbox, type CheckboxRootProps, Combobox, type ComboboxItemProps, type ComboboxRootProps, Composer, type ComposerRootProps, type ComposerState, Content, type ContentRootProps, Conversation, type ConversationItemProps, type ConversationItemState, type ConversationRootProps, Dialog, type DialogPortalProps, type DialogRootProps, Entry, type EntryListProps, type EntryRootProps, type EntryState, Field, type FieldControlProps, type FieldRootProps, type FieldTextareaProps, FileUpload, type FileUploadRootProps, Identity, type IdentityRootProps, ListRow, type ListRowRootProps, Menu, type MenuItemProps, type MenuPositionerProps, type MenuRootProps, MetricStrip, type MetricStripRootProps, Nav, type NavItemProps, type NavRootProps, Panel, type PanelContentProps, type PanelGroupProps, type PanelLabelProps, type PanelRootProps, type PanelTriggerProps, PinInput, type PinInputInputProps, type PinInputRootProps, Popover, type PopoverPositionerProps, type PopoverRootProps, type PresenceState, ProfileHeader, type ProfileHeaderRootProps, Progress, type ProgressRootProps, Prompt, type PromptRootProps, type PromptStatus, RadioGroup, type RadioGroupItemProps, type RadioGroupRootProps, RangeSlider, type RangeSliderRootProps, type RangeSliderThumbProps, Scroll, type ScrollRootProps, type ScrollViewportProps, Select, type SelectContentProps, type SelectItemProps, type SelectPositionerProps, type SelectRootProps, Separator, type SeparatorRootProps, Slider, type SliderContextValue, type SliderRootProps, Slot, StatusBanner, type StatusBannerRootProps, type StatusBannerTone, StickyBar, type StickyBarRootProps, Switch, type SwitchRootProps, Tabs, type TabsContentProps, type TabsRootProps, type TabsTriggerProps, ThemeSwitcher, type ThemeSwitcherModeBtnProps, type ThemeSwitcherModesProps, type ThemeSwitcherRootProps, type ThemeSwitcherThemeSelectProps, Thread, type ThreadItemFace, type ThreadItemProps, type ThreadMessageState, type ThreadRootProps, Toast, ToastItem, type ToastPlacement, type ToastProviderProps, type ToastPublishOptions, type ToastRecord, type ToastRootProps, type ToastStore, type ToastViewportProps, Tooltip, type TooltipPositionerProps, type TooltipRootProps, asyncStatusToContentState, useAeonMachine, useAppNav, useAppNavMachine, useAppShellContext, useAsyncContext, useContentContext, useFieldContext, useFileUploadCtx as useFileUpload, useFitText, useLayoutMode, useScrollContext, useScrollState, useSliderContext, useStickyBarContext, useToast, useToastStore };
+export { Accordion, type AccordionItemContentProps, type AccordionItemProps, type AccordionItemTriggerProps, type AccordionRootProps, AppNav, type AppNavBreadcrumbProps, type AppNavRootProps, type AppNavSectionProps, AppShell, type AppShellRootProps, Async, AsyncActions, AsyncProvider, AsyncReadout, AsyncRoot, AsyncTrack, Avatar, type AvatarRootProps, type AvatarStatus, Bar, type BarRootProps, Button, type ButtonRootProps, type ButtonStatus, Checkbox, type CheckboxRootProps, Clipboard, type ClipboardIndicatorProps, type ClipboardRootProps, Combobox, type ComboboxItemProps, type ComboboxRootProps, Composer, type ComposerInputProps, type ComposerRootProps, type ComposerState, Content, type ContentRootProps, Conversation, type ConversationItemProps, type ConversationItemState, type ConversationRootProps, Dialog, type DialogPortalProps, type DialogRootProps, Entry, type EntryListProps, type EntryRootProps, type EntryState, Field, type FieldControlProps, type FieldRootProps, type FieldTextareaProps, FileUpload, type FileUploadRootProps, Identity, type IdentityRootProps, ListRow, type ListRowRootProps, Menu, type MenuItemProps, type MenuPositionerProps, type MenuRootProps, MetricStrip, type MetricStripRootProps, Nav, type NavItemProps, type NavRootProps, Panel, type PanelContentProps, type PanelGroupProps, type PanelLabelProps, type PanelRootProps, type PanelTriggerProps, PinInput, type PinInputInputProps, type PinInputRootProps, Popover, type PopoverPositionerProps, type PopoverRootProps, type PresenceState, ProfileHeader, type ProfileHeaderRootProps, Progress, type ProgressRootProps, Prompt, type PromptRootProps, type PromptStatus, Prose, type ProseRootProps, RadioGroup, type RadioGroupItemProps, type RadioGroupRootProps, RangeSlider, type RangeSliderRootProps, type RangeSliderThumbProps, Scroll, type ScrollRootProps, type ScrollViewportProps, SegmentGroup, type SegmentGroupItemProps, type SegmentGroupRootProps, Select, type SelectContentProps, type SelectItemProps, type SelectPositionerProps, type SelectRootProps, Separator, type SeparatorRootProps, Slider, type SliderContextValue, type SliderRootProps, Slot, StatusBanner, type StatusBannerRootProps, type StatusBannerTone, StickyBar, type StickyBarRootProps, Switch, type SwitchRootProps, Tabs, type TabsContentProps, type TabsRootProps, type TabsTriggerProps, Textarea, type TextareaRootProps, ThemeSwitcher, type ThemeSwitcherModeBtnProps, type ThemeSwitcherModesProps, type ThemeSwitcherRootProps, type ThemeSwitcherThemeSelectProps, Thread, type ThreadItemFace, type ThreadItemProps, type ThreadMessageState, type ThreadRootProps, Toast, ToastItem, type ToastPlacement, type ToastProviderProps, type ToastPublishOptions, type ToastRecord, type ToastRootProps, type ToastStore, type ToastViewportProps, Tooltip, type TooltipPositionerProps, type TooltipRootProps, type UseWindowedRangeOptions, asyncStatusToContentState, rowLimits, useAeonMachine, useAppNav, useAppNavMachine, useAppShellContext, useAsyncContext, useAutoGrow, useClipboardStatus, useContentContext, useFieldContext, useFileUploadCtx as useFileUpload, useFitText, useLayoutMode, useScrollContext, useScrollState, useSliderContext, useStickyBarContext, useToast, useToastStore, useWindowedRange };