octane 0.2.2 → 0.2.4

package/dist/runtime.d.ts

@@ -387,10 +387,25 @@ interface PendingEffect {
 }
 interface TransitionActionSlot<T> {
     value: T;
+    renderTransition?: {
+        value: T;
+    };
     pendingActionBatch?: TransitionActionBatch;
     pendingActionValue?: T;
 }
 interface TransitionActionUpdate<T = unknown> {
+    /** An urgent replacement can cancel a held value even when its base is equal. */
+    superseded?: boolean;
+    state?: StateSlot<T>;
+    /** Already queued work precedes this batch; later urgent work stays on the cell. */
+    previous?: TransitionActionUpdate<T>;
+    next?: TransitionActionUpdate<T>;
+    stateUpdates?: Array<T | ((previous: T) => T)>;
+    reducerActions?: any[];
+    replayBaseValue?: T;
+    urgentOperations?: number[];
+    batch?: TransitionActionBatch;
+    reducer?: ReducerSlot<T, any>;
     slot: TransitionActionSlot<T>;
     block: Block;
     operations: Array<(value: T) => T>;
@@ -405,6 +420,17 @@ interface TransitionActionBatch {
     pendingActions: number;
     closed: boolean;
     flushed: boolean;
+    /**
+     * Only hook-started actions own pending indicators. Nearly every batch has
+     * exactly one starting hook, so the first is a plain field and only a second
+     * distinct hook (a nested start from another component) allocates the list.
+     */
+    hook: TransitionHookSlot | null;
+    hooks: TransitionHookSlot[] | null;
+    /** True while this batch is counted in its hooks' pending batch counts. */
+    hooksPending: boolean;
+    pendingHolds?: number;
+    workComplete?: boolean;
 }
 type TransitionMemoSwap = [kind: 0, hooks: Map<HookSlot, unknown>, slot: HookSlot, previous: unknown, next: unknown] | [kind: 1, cells: any[], base: number, previous: any[], next: any[]];
 interface WarmHarvestEntry {
@@ -416,6 +442,8 @@ interface WarmHarvestEntry {
 }
 /** The same single-origin staged cells as P1, owned by a root rather than a TrySlot. */
 interface RootTransitionHold {
+    /** Coalesce retries when an urgent action changes the retained forward value. */
+    replayScheduled?: boolean;
     origin: Block;
     entries: Array<TransitionActionUpdate<any>>;
     memoSwaps: TransitionMemoSwap[] | null;
@@ -599,8 +627,8 @@ export declare function scheduleRenderCleanup(schedule: (callback: () => void) =
  */
 export declare function setIsOctaneActEnvironment(value: boolean): void;
 /**
- * React-DOM parity. Runs `fn` and synchronously drains any renders/effects it scheduled
- * before returning. Bypasses the microtask-batched flush — used by the benchmark
+ * Runs `fn` and synchronously drains scheduled renders and insertion/layout work.
+ * Newly queued passive effects retain Octane's post-paint scheduling. Bypasses the microtask-batched flush — used by the benchmark
  * timing rig to measure operation wall-clock without microtask coalescing. Also the
  * controlled-restore commit path: maybeFlushDiscrete flushes through here at the
  * outermost boundary of a discrete event that armed a controlled `value`/`checked`
@@ -676,9 +704,27 @@ export declare function act<T>(fn: () => T | Promise<T>): Promise<T>;
 export declare function renderBlock(block: Block): void;
 export declare function componentSlotLite<P>(parentScope: Scope, slotKey: number, host: Node, comp: ComponentBody<P>, props: P, anchor?: Node): void;
 declare const SLOT_FLAG_TEARDOWN: number;
+/** @internal Invoke a provider that owns the trailing hook-slot ABI. */
+export declare function invokeManualHook<T>(fn: (...args: any[]) => T, receiver: unknown, args: IArguments): T;
+/** @internal Adapt an expression provider that owns the trailing hook-slot ABI. */
+export declare function manualHook<F extends (...args: any[]) => any>(fn: F, name?: string): F;
 export declare function withSlot<T>(sym: symbol, fn: (...a: any[]) => T, ...args: any[]): T;
 /** @internal Optional native hooks use the existing compiler slot and Scope lifetime. */
 export declare function nativeLocalHook<T>(name: string, initialize: () => T, dispose: (value: T) => void, slot?: HookSlot): T;
+interface StateSlot<T> {
+    value: T;
+    setter: (next: T | ((prev: T) => T)) => void;
+    /** Queued functional work is evaluated in the owner's next render. */
+    updates?: Array<T | ((previous: T) => T)>;
+    /** Promoted transition work folds with the inputs of the rendering owner. */
+    renderTransition?: TransitionActionUpdate<T>;
+    /** An urgent ancestor reads queued urgent operations without consuming the transition. */
+    urgentTransition?: boolean;
+    /** Allocated only for compiler-selected third-tuple consumers. */
+    getter?: () => T;
+    pendingActionBatch?: TransitionActionBatch;
+    pendingActionValue?: T;
+}
 type StateSetter<T> = (next: T | ((prev: T) => T)) => void;
 type StateTuple<T> = [T, StateSetter<T>, () => T];
 export declare function useState<T = undefined>(): StateTuple<T | undefined>;
@@ -705,6 +751,20 @@ type LinkedStateTuple<Value> = [Value, StateSetter<Value>, () => Value];
 export declare function useLinkedState<Source, Value>(source: Source, reconcile: (source: Source, previous: LinkedStatePrevious<Source, Value> | undefined) => Value, options?: LinkedStateOptions<Source, Value>, slot?: symbol): LinkedStateTuple<Value>;
 /** Compiler-selected linked-state variant when the current-value getter is observed. */
 export declare function __useLinkedStateWithGetter<Source, Value>(source: Source, reconcile: (source: Source, previous: LinkedStatePrevious<Source, Value> | undefined) => Value, options?: LinkedStateOptions<Source, Value>, slot?: symbol): LinkedStateTuple<Value>;
+interface ReducerSlot<S, A> {
+    value: S;
+    dispatch: (action: A) => void;
+    reducer: (state: S, action: A) => S;
+    /** Render-phase actions are reduced by the reducer from the replaying render. */
+    renderPhaseActions?: A[];
+    /** A promoted Action is reduced with this render's reducer before publication. */
+    renderTransition?: TransitionActionUpdate<S>;
+    urgentTransition?: boolean;
+    /** Allocated only for compiler-selected third-tuple consumers. */
+    getter?: () => S;
+    pendingActionBatch?: TransitionActionBatch;
+    pendingActionValue?: S;
+}
 type ReducerTuple<S, A> = [S, (action: A) => void, () => S];
 export declare function useReducer<S, A, I = S>(reducer: (s: S, a: A) => S, initialArg: I, initOrSlot?: ((arg: I) => S) | symbol, slot?: symbol): ReducerTuple<S, A>;
 /** Compiler-emitted useReducer variant for a tuple whose third member is observable. */
@@ -739,6 +799,9 @@ export declare function hookMemoPublish4<T>(cells: any[], base: number, value: T
 export declare function hookMemoPublish<T>(cells: any[], base: number, value: T, ...deps: any[]): T;
 /** One-cell form for compiler-owned lifetime-invariant callback values. */
 export declare function hookMemoPublishInvariant<T>(cells: any[], base: number, value: T): T;
+export declare function useRef<T = undefined>(): {
+    current: T | undefined;
+};
 export declare function useRef<T>(initial: T, slot?: symbol): {
     current: T;
 };
@@ -760,47 +823,6 @@ type ImperativeRef<T> = {
  * nested array refs share one factory result across all non-null owners.
  */
 export declare function useImperativeHandle<T>(ref: ImperativeRef<T>, factory: () => T, deps?: any[] | null, slot?: symbol): void;
-/**
- * React 18+ `useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?)`.
- *
- * Mirrors React's contract: subscribe is called on mount with an
- * `onStoreChange` callback; the returned function unsubscribes on unmount
- * (and on subscribe identity change). `getSnapshot()` is called on every
- * render to return the current snapshot. When the store calls
- * `onStoreChange`, the component re-renders and `getSnapshot()` runs again.
- *
- * `getServerSnapshot` IS used: on the server it supplies the SSR snapshot, and
- * during client hydration the first read uses it (see below) so the adopted DOM
- * matches the server value before the commit-time store-sync reconciles any
- * client/server difference. Client-only builds discard the capability method
- * that supplies this state.
- *
- * Implementation. A single identity-stable `inst` cell (StoreInst) holds the
- * last-COMMITTED snapshot, the latest getSnapshot, the block's forceUpdate, and a
- * stable onStoreChange handler. Two derived sub-slots host it: `<slot>:uses:inst`
- * (the cell, in the hooks map) and `<slot>:uses:effect` (the passive subscribe
- * effect). The value-sync that reconciles the render-read snapshot at commit does
- * NOT go through a layout effect — it rides the dedicated, sort-free
- * `storeSyncQueue` (drainStoreSyncs, run after the layout phase). Two payoffs:
- *
- *  1. The commit-sync entry carries no cleanup and never reorders, so the generic
- *     effect machinery (deps compare, PendingEffect alloc, post-order sort,
- *     per-entry cleanup/finalizer bookkeeping) is skipped for it.
- *  2. The enqueue is GATED: a re-render whose snapshot is Object.is-unchanged (and
- *     whose store wasn't swapped) enqueues NOTHING, even with a fresh inline
- *     getSnapshot every render (the dominant zustand/query pattern). getSnapshot is
- *     refreshed in RENDER instead of at commit, so onStoreChange always dedups
- *     against the freshest read while unchanged renders stay allocation-free.
- *
- * DIVERGENCE FROM REACT (documented in docs/react-parity-migration-plan.md):
- * React's updateSyncExternalStore re-pushes updateStoreInstance whenever
- * `inst.getSnapshot !== getSnapshot`, giving a commit-time snapshot re-read even
- * when the value was unchanged. We drop that: a store that mutates WITHOUT
- * notifying in the render→commit window is no longer caught on a render where ONLY
- * getSnapshot identity changed. Octane's synchronous renderer closes React's
- * motivating concurrent-interleaving window, and any store that actually notifies
- * is unaffected (onStoreChange uses the render-fresh getSnapshot).
- */
 export declare function useSyncExternalStore<T>(subscribe: (onStoreChange: () => void) => () => void, getSnapshot: () => T, getServerSnapshot?: () => T, slot?: symbol): T;
 /**
  * React 19 `useEffectEvent` — returns a fresh wrapper each render whose shared
@@ -1061,6 +1083,8 @@ export declare function nativeWarmMemo(compute: () => any, deps: any[], slot: Ho
  * cannot prove finite.
  */
 export declare function warmChild(comp: any, props: any): void;
+/** Compiler-owned plans must not follow static hoisting onto unrelated HOCs. */
+export declare function markWarm<T extends Function>(component: T, plan: unknown): T;
 export declare const puMiss: unique symbol;
 export declare function puTake0(slot: HookSlot): any;
 export declare function puTake1(slot: HookSlot, d0: any): any;
@@ -1104,7 +1128,9 @@ export declare function memoPublishAlways<T>(slot: HookSlot, value: T): T;
  */
 export declare function lazy<C extends ComponentBody<any>>(load: () => PromiseLike<{
     default: C;
-} | C>): C;
+} | C>): C & {
+    displayName?: string;
+};
 export declare function useId(slot?: symbol): string;
 export declare function template(html: string, ns?: number, frag?: number): Element;
 export declare function clone<T extends Node>(node: T, loc?: string, partialStyles?: string): T;
@@ -1191,7 +1217,12 @@ export declare function setHTML(el: Element, value: any): void;
 /** Complete validated write used by direct, spread, and html-only compiler paths. */
 export declare function setDangerouslySetInnerHTML(el: Element, value: any): void;
 /** Resolve source-ordered direct/spread raw-HTML writers and apply only the winner. */
-export declare function setDangerouslySetInnerHTMLSources(el: Element, sources: readonly (readonly [isSpread: boolean, sourceOrName: unknown, value?: unknown])[], ignoreSourceChildren?: boolean): void;
+export declare function setDangerouslySetInnerHTMLSources(el: Element, sources: readonly (readonly [
+    isSpread: boolean,
+    sourceOrName: unknown,
+    value?: unknown,
+    merge?: boolean
+])[], ignoreSourceChildren?: boolean): void;
 /** Stamp a compiler-proven non-nullish child onto a potential raw-HTML host. */
 export declare function markDangerouslySetInnerHTMLChildren(el: Element): void;
 export declare function attachRef(ref: any, el: Element | FragmentInstance | null, prevTarget?: Element | FragmentInstance | null): void;
@@ -1381,9 +1412,7 @@ export declare function setStringData(el: Element, name: string, value: unknown)
 export declare function setBooleanAttribute(el: Element, name: string, value: unknown): void;
 /**
  * Compiler-only fast path for a valid, statically named lowercase `aria-*`
- * attribute. ARIA values are enumerated: only nullish removes, while booleans,
- * functions, symbols, numbers, and objects stringify exactly like the generic
- * attribute path.
+ * attribute. Booleans stringify; nullish, function, and symbol values remove.
  */
 export declare function setAriaAttribute(el: Element, name: string, value: unknown): void;
 import { normalizeClass } from './css.js';
@@ -1400,7 +1429,12 @@ export declare function setStyle(el: HTMLElement | SVGElement, value: any, prev:
 export declare function setStyleProperty(el: HTMLElement | SVGElement, name: string, value: any, staticCss: string, previous: any): void;
 /** Snapshot a JSX spread with own-enumerable Object.assign semantics. */
 export declare function snapshotSpread(value: unknown): Record<string, unknown> | null;
-type HostPropSource = readonly [isSpread: boolean, sourceOrName: unknown, value?: unknown];
+type HostPropSource = readonly [
+    isSpread: boolean,
+    sourceOrName: unknown,
+    value?: unknown,
+    merge?: boolean
+];
 /**
  * Resolve a spread-bearing compiled host's complete prop set before touching
  * the DOM. JSX spread merging is last-writer-wins, but aliases such as
@@ -1408,6 +1442,12 @@ type HostPropSource = readonly [isSpread: boolean, sourceOrName: unknown, value?
  * property. Canonical identities ensure a vanished earlier source cannot
  * remove an unchanged later winner, and hydration compares only the final
  * client value against the final server value.
+ *
+ * A synthesized scope-hash class (4th tuple flag) is not an authored later
+ * writer: after identity last-writer-wins, it composes onto the winning class
+ * instead of replacing a spread's class. An authored `class` beside a spread
+ * stays last-writer-wins because its hash is baked into that authored value
+ * and carries no merge flag.
  */
 export declare function setHostPropSources(el: Element, sources: readonly HostPropSource[], prev: Record<string, unknown> | undefined, scope: Scope, hasNestedChildren?: boolean): Record<string, unknown>;
 export declare function setSpread(el: Element, value: any, prev: any, mountScope?: Scope, skipDangerouslySetInnerHTML?: boolean, skipFormControls?: boolean): void;
@@ -1457,7 +1497,7 @@ export declare function delegateCaptureEvents(eventNames: string[]): void;
 export interface FormStatus {
     pending: boolean;
     data: FormData | null;
-    method: string;
+    method: string | null;
     action: ((formData: FormData) => unknown) | string | null;
 }
 /**
@@ -1476,11 +1516,11 @@ export declare function requestFormReset(form: HTMLFormElement): void;
 /**
  * Compiler-emitted binding for `<form action={fn}>` / `<button formAction={fn}>`.
  * A FUNCTION value wires submit interception (stored on the element as
- * `$$formAction`, with the form gaining a delegated `$$submit` handler once);
+ * `$$formAction`, with submit delegation installed once);
  * a string/null value falls back to the native attribute so ordinary form posts
- * still work. `prev` lets the update path clean up when switching function→string.
+ * still work. The previous-value argument remains part of the compiler ABI.
  */
-export declare function setFormAction(el: HTMLFormElement | HTMLButtonElement | HTMLInputElement, name: string, value: unknown, prev: unknown): void;
+export declare function setFormAction(el: HTMLFormElement | HTMLButtonElement | HTMLInputElement, name: string, value: unknown, _prev: unknown): void;
 /**
  * Compiler-emitted binding for `autoFocus` (React parity): client mounts never
  * write an attribute and focus supported controls once, before layout effects.
@@ -1525,12 +1565,7 @@ export declare function setSelectValue(el: Element, value: unknown): void;
  * option defaultSelected), never the live value: a dirty control keeps what
  * the user typed. Re-synced on updates (React parity; attribute-only).
  */
-export declare function setDefaultValue(el: Element, value: unknown): void;
-/**
- * Compiler-only defaultValue binding for a statically-known input/textarea
- * with no value writer or spread. The element is necessarily uncontrolled, so
- * it needs neither a controlled-state record nor edit/composition listeners.
- */
+export declare function setDefaultValue(el: Element, value: unknown, initial?: boolean): void;
 export declare function setDefaultValueUncontrolled(el: Element, value: unknown): void;
 /** Compiler-emitted binding for `defaultChecked` (uncontrolled checkables). */
 export declare function setDefaultChecked(el: Element, value: unknown): void;
@@ -1542,11 +1577,12 @@ export declare function setDefaultChecked(el: Element, value: unknown): void;
  * controlled value before its default fallback) while the compiler-owned
  * source bindings preserve authored evaluation order and single getter reads.
  */
-export declare function setFormControlSources(el: Element, sources: ReadonlyArray<readonly [boolean, unknown, unknown?]>): void;
+export declare function setFormControlSources(el: Element, sources: ReadonlyArray<readonly [boolean, unknown, unknown?, boolean?]>): void;
 interface PortalSlot {
     __kind: 'portalSlotSlot';
     block: Block | null;
     target: Element | null;
+    key: string | null;
     host: Node;
     start: Comment | null;
     end: Comment | null;
@@ -1563,10 +1599,9 @@ interface PortalSlot {
  */
 export declare function portal(parentScope: Scope, slotKey: number, target: Element, body: ComponentBody, props: any, host?: Node, env?: any[], fragmentOwners?: FragmentInstance | readonly FragmentInstance[], fragmentAnchor?: Node): void;
 /**
- * `createPortal(children, target, props?)`. The first two arguments mirror ReactDOM's
- * `createPortal(children, container)`; the OPTIONAL THIRD argument is Octane-specific
- * `props` for the portal wrapper — NOT ReactDOM's `key`. That third slot is an
- * intentional divergence from React (Octane has no `key`-as-third-arg portal form). The
+ * `createPortal(children, target, keyOrProps?)`. A string/number third argument
+ * is a reconciliation key. An object remains Octane's optional props for a
+ * function portal body. The
  * compiler recognises `{createPortal(...)}` at JSX child position and lowers it to a
  * direct `portal(...)` runtime call — no descriptor allocation on the hot path. This
  * function exists so non-JSX call sites (storing in a variable, passing through props,
@@ -1575,6 +1610,7 @@ export declare function portal(parentScope: Scope, slotKey: number, target: Elem
 declare const PORTAL_TAG: unique symbol;
 export interface PortalDescriptor {
     $$kind: typeof PORTAL_TAG;
+    key: string | null;
     body: ComponentBody | ElementDescriptor | unknown;
     target: Element;
     props: any;
@@ -1725,7 +1761,14 @@ export declare function compilerCacheContext(scope: Scope, slotKey: number, prev
  * "equal"), `false` to re-render. When omitted, a shallow Object.is comparison
  * of own enumerable keys is used.
  */
-export declare function memo<P>(component: ComponentBody<P>, arePropsEqual?: (prevProps: Readonly<P>, nextProps: Readonly<P>) => boolean): ComponentBody<P>;
+export declare function memo<C extends ComponentBody<any>>(component: C, arePropsEqual?: (prevProps: Readonly<Parameters<C>[0]>, nextProps: Readonly<Parameters<C>[0]>) => boolean): C & {
+    readonly type: C;
+    displayName?: string;
+};
+export declare function memo<P>(component: ComponentBody<P>, arePropsEqual?: (prevProps: Readonly<P>, nextProps: Readonly<P>) => boolean): ComponentBody<P> & {
+    readonly type: ComponentBody<P>;
+    displayName?: string;
+};
 export declare const HMR: unique symbol;
 export declare function hmr<P>(fn: ComponentBody<P>): ComponentBody<P>;
 export declare function setTransitionFallbackTimeout(ms: number): void;
@@ -1856,6 +1899,21 @@ declare function teardownErrorSlot(state: ErrorSlot, detachDom: boolean): void;
 export declare function errorBlock(parentScope: Scope, slotKey: number, domParent: Node, tryBody: ComponentBody, catchBody: ComponentBody, anchor?: Node | null, env?: any[]): () => void;
 export declare function tryBlock(parentScope: Scope, slotKey: number, domParent: Node, tryBody: ComponentBody, catchBody: ComponentBody | null, pendingBody: ComponentBody | null, anchor?: Node | null, env?: any[], propagateSuspense?: boolean): () => void;
 export declare function startTransition(fn: () => void | Promise<unknown>): void;
+interface TransitionHookSlot {
+    isPending: boolean;
+    block: Block;
+    /**
+     * Action batches this hook started or was re-held into that have not
+     * finished. The batches themselves list their hooks; the hook only needs
+     * the count to publish its falling edge, so no per-hook collection exists.
+     */
+    pendingBatches: number;
+    error?: {
+        value: unknown;
+    };
+    start: (fn: () => void | Promise<unknown>) => void;
+    publish: (pending: boolean) => void;
+}
 export declare function useTransition(slot?: symbol): [boolean, (fn: () => void | Promise<unknown>) => void];
 export declare function useActionState<S>(action: (prevState: S, payload: any) => S | Promise<S>, initialState: S, permalinkOrSlot?: string | symbol, slot?: symbol): [S, (payload?: any) => void, boolean];
 export declare function useFormStatus(slot?: symbol): FormStatus;
@@ -1954,11 +2012,12 @@ interface InlineCaughtErrorReport {
     handler: (error: unknown) => void;
     resume: EffectEventCommitAction;
 }
+export type RootContainer = Element | Document | DocumentFragment;
 /** Compiler ABI: validate an authored candidate and publish only from a DEV render. */
 export declare function devHtmlNesting(childTag: string, ancestors: string[], childLocation?: string, ancestorLocation?: string): void;
-export declare function createRoot(container: Element, options?: RootOptions): Root;
+export declare function createRoot(container: RootContainer, options?: RootOptions): Root;
 /** Compiler-only root for a statically proven void `@{}` entry component. */
-export declare function __createVoidRoot(container: Element, options?: RootOptions): Root;
+export declare function __createVoidRoot(container: RootContainer, options?: RootOptions): Root;
 /**
  * Hydrate a server-rendered container and return a live {@link Root} — the
  * React-18 `hydrateRoot(container, element)` shape (container FIRST). Instead of
@@ -1974,8 +2033,8 @@ export declare function __createVoidRoot(container: Element, options?: RootOptio
  * component updates props in place on the adopted DOM, a different component
  * tears down and remounts.
  */
-export declare function hydrateRoot(container: Element, element: ElementDescriptor, options?: RootOptions): Root;
-export declare function hydrateRoot(container: Element, body: ComponentBody, props?: any, options?: RootOptions): Root;
+export declare function hydrateRoot(container: RootContainer, element: ElementDescriptor, options?: RootOptions): Root;
+export declare function hydrateRoot(container: RootContainer, body: ComponentBody, props?: any, options?: RootOptions): Root;
 /** React DOM `preload(href, {as, …})` — `<link rel="preload">`. */
 export declare function preload(href: string, options: {
     as: string;