Coordinated Lazy

type ChunkComponentProps<T extends {} = {}, P = unknown, O = unknown> = {
  /** Build-time/precomputed value for this chunk. */
  preloaded?: P;
  /** Authoritative/controlled value: render content directly, never the loaders. */
  controlled?: boolean;
  /**
   * Force client-side rendering: ignore the server `Loader`/`InitialLoader` for
   * this render so the decision routes to a content/client branch instead. Lets
   * a consumer that *configures* server loaders statically opt out of them
   * per-render (e.g. when no server loading functions are available, or the
   * caller explicitly wants the client to drive). Has no effect once
   * `isLoaded`/`controlled` already render the content.
   */
  forceClient?: boolean;
  /**
   * Per-render override for the `isInitial` decision input (whether the initial
   * paint is already in hand). Mirrors how `controlled` overrides `isLoaded`:
   * lets a consumer whose initial-readiness depends on per-render context it
   * cannot express as a pure `config.isInitial(preloaded)` predicate compute it
   * in its own router and pass the result. Takes precedence over
   * `config.isInitial`.
   */
  isInitial?: boolean;
  /**
   * For the server render modes (`server-loader`/`server-initial`), block the
   * server render on the loader instead of streaming a fallback: render the
   * server loader *without* a Suspense boundary, so its content lands in the
   * initial HTML (e.g. for no-JS / crawler SSR). When unset (the default) the
   * loader streams under Suspense, showing `ChunkLoading` until it resolves.
   */
  awaitServerLoad?: boolean;
  /**
   * Skip the initial-loader stage: ignore the `InitialLoader` / source-`initial`
   * for this render so a not-yet-loaded chunk loads the full content directly
   * rather than fetching a quick initial first. For consumers that have no
   * loading UI to show an initial paint into (so a 2-stage initial->full load
   * would be wasted).
   */
  skipInitialLoad?: boolean;
  /** Per-render loader options (merged over the config's `loaderOptions`). */
  loaderOptions?: O;
  /** User generic props forwarded to `ChunkContent` / `ChunkLoading`. */
  userProps?: T;
  /** Settle gate to register with (defaults to the surrounding controller / page). */
  gate?: SettleGate;
}

type ChunkContentProps<T extends {} = {}, P = unknown> = {
  data?: P;
  loading: boolean;
  refresh?: () => Promise<void>;
  revalidating?: boolean;
} & T

type ChunkLoadingProps<T extends {} = {}, P = unknown> = { data?: P; loading: true } & T

type ChunkRenderDecision = { mode: ChunkRenderMode; loading: boolean }

type ChunkRenderInputs = {
  /** Evaluated `isLoaded(preloaded)` (or the controlled override). */
  isLoaded: boolean;
  /** Evaluated `isInitial(preloaded)`. */
  isInitial: boolean;
  /** A server initial is configured: an `InitialLoader`, or a `data`-mode `source.initial`. */
  hasServerInitial: boolean;
  /** A server full loader is configured: a `Loader`, or a `data`-mode `source.load`. */
  hasServerLoader: boolean;
}

type ChunkRenderMode =
  | 'content'
  | 'content-initial'
  | 'server-initial'
  | 'server-loader'
  | 'attempt-initial-client'

type ChunkSwapConfig = { defer?: boolean; requireHoist?: boolean; channelKey?: string | null }

type CoordinatedContentContext = React.Context<CoordinatedContentContextValue>

type CoordinatedContentContextValue = {
  hoisted: Record<string, unknown>;
  /**
   * The content calls this once it has loaded (its dynamic import resolved), so
   * the swap can register readiness with the settle gate. Used by `LazyContent`.
   */
  reportReady?: () => void;
  /**
   * The loading fallback to show *while a dynamically-imported content loads*.
   * After the swap reveals the content, a `LazyContent` shows this as its own
   * Suspense fallback during the `import()` - so the same placeholder the swap
   * showed keeps covering the load, with no empty flash. Generalizes "hand the
   * `ContentLoading` to the lazy content".
   */
  fallback?: React.ReactNode;
}

type CoordinatedFallbackContext = React.Context<CoordinatedFallbackContextValue | undefined>

type CoordinatedFallbackContextValue = {
  /**
   * Hoist a keyed value up to the swap so it can be folded into the consumer's
   * `ready` decision and handed down to the full content via
   * [`CoordinatedContentContextValue`](#coordinatedcontentcontextvalue). Generalizes `setFallbackHasts`.
   */
  hoist?: (key: string, value: unknown) => void;
  /**
   * Signal that the fallback's hoist hook ran. The generic swap force-mounts
   * the fallback on its own, so this is optional - consumers (e.g.
   * `CodeHighlighter`) use it to validate that the loading component wired its
   * hoist hook. Generalizes `onHookCalled`.
   */
  onReady?: () => void;
  /**
   * `true` when this instance is nested inside an outer `CoordinatedLazy` still
   * showing its own fallback. The inner stays in fallback while set, collapsing
   * a "fallback -> content -> fallback -> content" flicker into one transition.
   * Generalizes `isNestedInsideOuterFallback`.
   */
  isNested?: boolean;
  /** Arbitrary parent->fallback data (generalizes `extraVariants`). */
  data?: Record<string, unknown>;
}

type CoordinatedGateContext = React.Context<SettleGate | null>

type CoordinatedLazyProps = {
  /** Full content, shown after the swap. Pre-rendered on the server. */
  content: React.ReactNode;
  /** Loading placeholder; force-mounted once so its hoist hook runs. */
  fallback?: React.ReactNode;
  /** Whether the content's data is ready to display. */
  ready: boolean;
  /** Hold the swap while real async work is in flight even though `ready`. */
  defer?: boolean;
  /**
   * Hold the settle gate open without re-showing the fallback (content stays
   * rendered). See .
   */
  holdGate?: boolean;
  /** Skip the fallback entirely. */
  skipFallback?: boolean;
  /** Hold the swap until the fallback hoists at least once. */
  requireHoist?: boolean;
  /**
   * Hold the swap until the content reports it has loaded, mounting the content
   * behind the fallback so a code-split (e.g. `LazyContent`) content can load in
   * the background and reveal only once its chunk has arrived. See
   * .
   */
  awaitContent?: boolean;
  /**
   * Settle gate to register this swap with. When omitted, the ambient gate from
   * a surrounding coordinator (e.g. the `useStream` controller, via
   * [`CoordinatedGateContext`](#coordinatedgatecontext)) is used instead. The page-global gate is
   * always registered on top of either, so a page-wide coordinated commit waits
   * for the swap regardless.
   */
  gate?: SettleGate;
  /** Arbitrary parent->fallback data exposed to the fallback subtree. */
  data?: Record<string, unknown>;
  /**
   * Speculative preload hook. See :
   * fired with the hoisted data so the consumer can start dynamic imports of
   * helpers in parallel with loading the full content.
   */
  preload?: (hoisted: Record<string, unknown>) => void;
}

type CreateChunkConfig<T extends {} = {}, P = unknown, O = unknown> = {
  /** The full content component. */
  ChunkContent: React.ComponentType<ChunkContentProps<T, P>>;
  /** The loading placeholder. Defaults to a component that renders `null`. */
  ChunkLoading?: React.ComponentType<ChunkLoadingProps<T, P>>;
  /** Whether the preloaded value suffices for the full content. */
  isLoaded?: IsLoaded<P>;
  /** Whether the preloaded value suffices for the initial state. */
  isInitial?: IsInitial<P>;
  /**
   * Data source (discriminated by `mode`). Its loader functions run **on the
   * server only** - a `data`-mode source is executed by `ChunkServerLoader`
   * (`source.load` for the full content, `source.initial` for a quick streamed
   * paint) and never serialized into a Client Component. To load on the *client*,
   * supply the source through a `ChunkProvider` (which lazily imports it)
   * rather than this field. (Calling `useChunk` directly inside your own client
   * component with a `source` is still fine - no server/client boundary is
   * crossed there.)
   */
  source?: StreamSource<P, O>;
  /**
   * Server component rendered (under Suspense) to produce the full content.
   * Always dynamically imported, and only imported when the render decision
   * routes to it - so it never reaches the client bundle.
   */
  Loader?: LazyComponentImport<ChunkContentProps<T, P>>;
  /** Server component rendered (under Suspense) to produce the initial state. */
  InitialLoader?: LazyComponentImport<ChunkContentProps<T, P>>;
  /** Swap timing forwarded to `CoordinatedLazy`. */
  swap?: ChunkSwapConfig;
  /** Default options passed to the source loaders. */
  loaderOptions?: O;
  /**
   * The `ChunkContent` component performs its own client-side loading and
   * fallback->content swap. When set, the client-driven render modes render
   * `ChunkContent` directly (with `loading: true`) instead of wrapping it in the
   * framework's [`useChunk`](#usechunk)+swap (`CoordinatedLazyClient`) - so a
   * self-managing content (e.g. one already built on `useCoordinatedSwap`) is not
   * double-swapped. Server and content/`content-initial` modes are unaffected.
   */
  contentManagesSwap?: boolean;
  /**
   * Opt into stale-while-revalidate: once the chunk has loaded, automatically
   * re-run the loader once on the first idle period (via `requestIdleCallback`)
   * to refresh potentially-stale data in the background. Client-only. The chunk
   * keeps showing its current data while the refresh is in flight.
   */
  revalidateOnIdle?: boolean;
}

type LazyContentProps<T extends {} = {}> = {
  /** Dynamic import of the component to render. */
  content: LazyComponentImport<T>;
  /** Props forwarded to the imported component. */
  props?: T;
  /** Placeholder shown while the module loads. Defaults to `null`. */
  fallback?: React.ReactNode;
  /**
   * Additional settle gate to report readiness to once the component has loaded
   * and mounted (e.g. a `useStream` controller gate). The page-global gate is
   * always registered too. Client path only - the server path streams via
   * Suspense and has no client gate to report to.
   */
  gate?: SettleGate;
}

type StreamSource<P = unknown, O = unknown> =
  | {
      mode: 'data';
      load: (options: O, signal: AbortSignal) => Promise<P>;
      initial?: (options: O) => P;
    }
  | {
      mode: 'urls';
      loadUrls: (options: O, signal: AbortSignal) => Promise<StreamUrlsResult>;
      loadChunk: (url: URL, options: O, signal: AbortSignal) => Promise<P>;
      initialUrls?: (options: O) => StreamUrlsResult;
      initialChunk?: (url: URL, options: O) => P;
    }
  | {
      mode: 'stream';
      stream: (chunks: P[], options: O, signal: AbortSignal) => AsyncGenerator<void, void, void>;
    }

type StreamUrlsResult = { chunks: URL[]; lastChunk?: boolean }

type UseChunkResult<P> = {
  /** The chunk's data: the loaded value, or the initial/preloaded value while loading. */
  data: P | undefined;
  /** `true` until the full data has loaded. */
  loading: boolean;
  /** `true` while a background refresh is in flight; the current `data` stays visible. */
  revalidating: boolean;
  /**
   * Re-run the `data`-mode loader and swap in fresh data, keeping the current
   * data visible meanwhile (stale-while-revalidate). Aborts any prior in-flight
   * refresh. A no-op for non-`data` sources or when no source resolves.
   */
  refresh: () => Promise<void>;
}

type UseCoordinatedFallbackResult = {
  /** Parent->fallback data provided via . */
  data?: Record<string, unknown>;
  /** Whether this fallback's `CoordinatedLazy` is nested inside an outer, still-loading one. */
  isNested: boolean;
}

type UseCoordinatedSwapOptions = {
  /** Whether the content's data is ready to display. */
  ready: boolean;
  /** Hold the swap while real async work is still in flight even though `ready`. */
  defer?: boolean;
  /**
   * Hold the settle gate open WITHOUT re-showing the fallback - the content stays
   * rendered while the page-wide coordination waits. Unlike `defer` (which holds
   * the rendered fallback), this only affects gate registration, for content that
   * has swapped in but is still finishing deferred work it gates internally (e.g.
   * the code highlighter rendering plain text, then highlighting in place).
   */
  holdGate?: boolean;
  /** Whether a fallback element exists to show. */
  hasFallback: boolean;
  /** Skip the fallback entirely. */
  skipFallback?: boolean;
  /** Additionally hold the swap until the fallback hoists at least once. */
  requireHoist?: boolean;
  /**
   * Hold the swap until the content reports it has loaded. The consumer mounts
   * the content (e.g. a `LazyContent`) while the fallback is shown so it can
   * load in the background, returning `null` until ready and then calling the
   * content context's `reportReady` - so a code-split content component loads
   * behind the placeholder and reveals only once its chunk has arrived.
   */
  awaitContent?: boolean;
  /**
   * Settle gate to register this swap with. When omitted, the ambient gate from
   * a surrounding coordinator (e.g. the `useStream` controller, via
   * [`CoordinatedGateContext`](#coordinatedgatecontext)) is used instead. The page-global gate is
   * always registered on top of either, so a page-wide coordinated commit waits
   * for the swap regardless.
   */
  gate?: SettleGate;
  /** Arbitrary parent->fallback data exposed via the fallback context. */
  data?: Record<string, unknown>;
  /**
   * Fired as soon as the fallback hoists data, with the hoisted map. Lets the
   * consumer kick off dynamic `import()`s of heavy helpers it can tell from the
   * data it will need - in parallel with loading the full content, instead of
   * the content mounting and then requesting them in a serial roundtrip. Should
   * be idempotent (the module cache dedups within a graph); cross-instance
   * dedup is the layout provider's job.
   */
  preload?: (hoisted: Record<string, unknown>) => void;
}

type UseCoordinatedSwapResult = {
  /** Whether the fallback branch should mount this render. */
  showFallback: boolean;
  /** Context value to provide to the fallback subtree. */
  fallbackContext: CoordinatedFallbackContextValue;
  /** Data hoisted up from the fallback so far, keyed. */
  hoisted: Record<string, unknown>;
  /** `true` while the fallback is being shown. */
  loading: boolean;
  /** In `awaitContent` mode, whether the content has reported it loaded. */
  contentReady: boolean;
  /** Passed to the content (via the content context) so it can report it loaded. */
  reportContentReady: () => void;
  /**
   * Hoist a keyed value up to the swap directly (the same channel the fallback's
   * `useCoordinatedFallback` uses). Lets the consumer populate the hoisted map
   * from outside the fallback subtree - e.g. a client-loaded data path that has
   * no fallback mounted but still needs to feed the hoisted dictionary.
   */
  hoist: (key: string, value: unknown) => void;
}