@calmdown/pyxis 1.0.0-rc.2 → 1.0.0-rc.4

package/dist/core.d.ts

@@ -17,32 +17,54 @@ type PropsType = { readonly [_ in string]?: any; };
  */
 declare const S_NODE_TYPE: unique symbol;
 /**
- * Infers the specific Node type from its props typings.
+ * Infers the specific Node type from its props typings, if available.
  */
 type NodeType<P> = P extends {
   readonly [S_NODE_TYPE]?: infer N;
 } ? N : unknown;
 /**
- * A tuple of up to 2 arguments.
+ * A symbol to include in props typings containing the element name.
+ * @deprecated **Type only, does not exist at runtime!**
  */
-type ArgsMax2<A0 = any, A1 = any> = [a0?: A0, a1?: A1];
+declare const S_ELEM_NAME: unique symbol;
 /**
- * Describes a callback with up to two stored arguments.
+ * Infers the specific element name from its props typings, if available.
  */
-interface Callback<TArgs extends ArgsMax2 = ArgsMax2, TReturn = void> {}
-//#endregion
-//#region src/data/Dependency.d.ts
+type ElemName<P> = P extends {
+  readonly [S_ELEM_NAME]?: infer N extends string;
+} ? N : string;
 /**
- * A dependency callback of an Atom. The callback will be run whenever the relevant Atom changes.
+ * Flattens an intersection of objects into a single object.
+ *
+ * Note: The extra `& {}` appendix causes TypeScript to display the resulting type in its expanded
+ * form, rather than showing `Flatten<...>`.
  */
-interface Dependency<TArgs extends ArgsMax2 = ArgsMax2> extends Callback<TArgs> {}
-interface DependencyList<TArgs extends ArgsMax2 = ArgsMax2> {}
-declare function bind(lifecycle: Lifecycle, target: DependencyList, block: () => void): void;
+type Flatten<T> = { [K in keyof T]: T[K]; } & {};
+/**
+ * A tuple of up to 3 arguments.
+ */
+type ArgsMax3<A0 = any, A1 = any, A2 = any> = [a0?: A0, a1?: A1, a2?: A2];
+/**
+ * Describes a callback with up to two stored arguments.
+ */
+interface Callback<TArgs extends ArgsMax3 = ArgsMax3, TReturn = void> {
+  fn: (this: any, ...args: TArgs) => TReturn;
+  a0?: TArgs[0];
+  a1?: TArgs[1];
+  a2?: TArgs[2];
+}
+//#endregion
+//#region src/symbols.d.ts
+export declare const S_ATOM: unique symbol;
+export declare const S_COMPONENT: unique symbol;
+export declare const S_TAG_NAME: unique symbol;
+/** used as a key to attach and access dev info on JSX objects */
+declare const S_DEV_INFO: unique symbol;
 //#endregion
 //#region src/data/Lifecycle.d.ts
 interface Lifecycle extends DependencyList {
-  /** whether this Lifecycle is currently mounted or not */
-  mounted: boolean;
+  /** gets a boolean indicating whether this Lifecycle is currently mounted or not */
+  readonly mounted: boolean;
 }
 interface MountBlock {
   (): (() => void) | void;
@@ -51,36 +73,82 @@ interface UnmountBlock {
   (): void;
 }
 /**
- * Registers a callback to run just after the current Component has mounted.
+ * Registers a block of code to run once the current Component has mounted.
  *
  * If a teardown callback is returned, it will be run just before the Component unmounts (equivalent
  * to adding a separate `unmounted` block).
  * @see {@link unmounted}
  */
-declare function mounted(block: MountBlock, lifecycle?: Lifecycle): void;
+export declare function mounted(block: MountBlock, lifecycle?: Lifecycle): void;
+/**
+ * Similar to {@link mounted}, but instead accepts a {@link Callback} object. Useful in hot paths
+ * where it may be desirable to reuse callback objects, avoid closures, or {@link Lifecycle} needs
+ * to be tightly controlled.
+ * @see {@link mounted}
+ */
+export declare function onceMounted<TArgs extends ArgsMax3>(lifecycle: Lifecycle, callback: Callback<TArgs>): void;
 /**
- * Registers a callback to run once the current Component is just about to unmount.
+ * Registers a block of code to run once the current Component is just about to unmount.
  * @see {@link mounted}
  */
-declare function unmounted(block: UnmountBlock, lifecycle?: Lifecycle): void;
+export declare function unmounted(block: UnmountBlock, lifecycle?: Lifecycle): void;
+/**
+ * Similar to {@link unmounted}, but instead accepts a {@link Callback} object. Useful in hot paths
+ * where it may be desirable to reuse callback objects, avoid closures, or {@link Lifecycle} needs
+ * to be tightly controlled.
+ * @see {@link unmounted}
+ */
+export declare function onceUnmounted<TArgs extends ArgsMax3>(lifecycle: Lifecycle, callback: Callback<TArgs>): void;
 /**
  * Gets the Lifecycle of the calling component.
  */
-declare function getLifecycle(): Lifecycle;
+export declare function getLifecycle(): Lifecycle;
 /**
  * Runs a block of code with the provided Lifecycle. Calls to `getLifecycle` within the block will
  * return the specified object.
  * @see {@link getLifecycle}
  */
-declare function withLifecycle<TArgs extends [arg?: any], TReturn>(lifecycle: Lifecycle, block: (...args: TArgs) => TReturn, ...args: TArgs): TReturn;
+export declare function withLifecycle<TArgs extends ArgsMax3, TReturn>(lifecycle: Lifecycle, block: (...args: TArgs) => TReturn, ...args: TArgs): TReturn;
+//#endregion
+//#region src/data/Dependency.d.ts
+/**
+ * A dependency callback of an Atom. The callback will be run whenever the relevant Atom changes.
+ */
+interface Dependency<TArgs extends ArgsMax3 = ArgsMax3> extends Callback<TArgs> {}
+/**
+ * Represents an object capable of holding links to Dependencies and dispatching notifications
+ * to them.
+ */
+interface DependencyList<TArgs extends ArgsMax3 = ArgsMax3> {
+  /**
+   * In chained data relations (proxy and context atoms), tracks the upstream atom forwarding
+   * notifications to this atom.
+   */
+  $upstream?: Nil<DependencyList>;
+}
+/**
+ * Invokes the provided {@link Dependency} and binds it to run again with each notification emitted
+ * by the specified target. The return value of the initial run is forwarded.
+ */
+export declare function bind<TArgs extends ArgsMax3, TResult>(lifecycle: Lifecycle, target: DependencyList, dependency: Dependency & Callback<TArgs, TResult>): TResult;
+/**
+ * Links a {@link Dependency} to an {@link Atom} and {@link Lifecycle}.
+ */
+export declare function link<TArgs extends ArgsMax3>(lifecycle: Lifecycle, target: DependencyList, dep: Dependency<TArgs>): void;
+/**
+ * Unlinks a Dependency from the Atom and Lifecycle it has been linked to.
+ */
+export declare function unlink(dep: Dependency): void;
 //#endregion
 //#region src/data/Atom.d.ts
 /**
- * Pyxis Atom type guard marker.
+ * Holds any single value, managing reactions to its changes. A bare Atom is read-only. Use the
+ * `read` and `peek` functions to access its value.
+ * @see {@link read}
+ * @see {@link peek}
+ * @see {@link WriteAtom}
  */
-declare const S_ATOM: unique symbol;
-/** Contract for Atoms where they need to be read. */
-interface ReadAtom<out T> extends DependencyList {
+interface Atom<out T = unknown> extends DependencyList {
   /** Pyxis Atom type guard marker. */
   readonly [S_ATOM]: true;
   /**
@@ -94,18 +162,22 @@ interface ReadAtom<out T> extends DependencyList {
   get: () => T;
 }
 /**
- * Holds any single value, managing reactions to its changes. Use the `read`, `write` functions to
- * access its value.
+ * Holds any single value, managing reactions to its changes. Values of WriteAtom are mutable and
+ * can be freely changed at any time. Use the `read`, `peek`, `write` or `update` functions to
+ * access or manipulate its value.
  * @see {@link read}
+ * @see {@link peek}
  * @see {@link write}
+ * @see {@link update}
+ * @see {@link Atom}
  */
-interface Atom<T = unknown> extends ReadAtom<T> {
+interface WriteAtom<T = unknown> extends Atom<T> {
   /**
-   * Sets the value of this Atom. Does nothing if this Atom is readonly. Only use this method when
-   * the target is guaranteed to be an Atom, otherwise it is recommended to use the `write` or
-   * `update` functions.
+   * Sets the value of this Atom. Does nothing if this Atom is readonly. This method does *not*
+   * emit any change notification to the Atom's observers; Using it recklessly can leave observers
+   * out of date with stale state! Please make sure you know exactly what you're doing; It is
+   * *strongly* recommended to use the `write` or `update` functions instead.
    *
-   * This method does *not* send out any change notifications to observers!
    * @returns Boolean indicating whether the value of this Atom changed.
    * @see {@link write}
    * @see {@link update}
@@ -113,48 +185,56 @@ interface Atom<T = unknown> extends ReadAtom<T> {
   set: (value: T) => boolean;
 }
 /**
- * Union of the given type or an Atom of that type. Use the `read`, `peek`, `write`, `update` or
- * `isAtom` functions to interact with such values.
+ * Union of the given type or an Atom of that type. Use the `read`, `peek` or `isAtom` functions to
+ * interact with such values.
  * @see {@link read}
  * @see {@link peek}
- * @see {@link write}
- * @see {@link update}
  * @see {@link isAtom}
  */
 type MaybeAtom<T> = Atom<T> | T;
 /**
- * Union of the given type or the ReadAtom contract of that type. Use the `read`, `peek` or `isAtom`
- * functions to interact with such values.
+ * Union of the given type or a WriteAtom of that type. Use the `read`, `peek`, `write`, `update` or
+ * `isAtom` functions to interact with such values.
  * @see {@link read}
  * @see {@link peek}
+ * @see {@link write}
+ * @see {@link update}
  * @see {@link isAtom}
  */
-type MaybeReadAtom<T> = ReadAtom<T> | T;
+type MaybeWriteAtom<T> = WriteAtom<T> | T;
 /**
- * Creates an empty Atom; i.e. value set to `undefined`.
+ * Creates an empty WriteAtom; i.e. value set to `undefined`.
  */
-declare function atomOf<T>(): Atom<T | undefined>;
+export declare function atomOf<T>(): WriteAtom<T | undefined>;
 /**
- * Creates an Atom initialized to the provided value. If the provided value is already an Atom, it
- * is returned as-is.
- * @see {@link isAtom}
+ * Creates a WriteAtom initialized to the provided value.
+ *
+ * If the provided initial value is itself an Atom, its value is automatically unwrapped.
+ *
+ * If you're intentionally creating an Atom intended to hold other Atoms, create an empty Atom first
+ * and write it separately, e.g.:
+ *
+ * ```ts
+ * const atom = atomOf<Atom<number>>();
+ * write(atom, otherAtom);
+ * ```
  */
-declare function atomOf<T>(initialValue: MaybeAtom<T>, lifecycle?: Lifecycle, devId?: string): Atom<T>;
+export declare function atomOf<T>(initialValue: MaybeAtom<T>, lifecycle?: Lifecycle, devId?: string): WriteAtom<T>;
 /**
  * Atom type guard, checks if the provided input is an Atom.
  */
-declare function isAtom<T = unknown>(input: Nil<MaybeAtom<T>>): input is Atom<T>;
-declare function isAtom<T = unknown>(input: Nil<MaybeReadAtom<T>>): input is ReadAtom<T>;
-declare function isAtom<T = unknown>(input: unknown): input is Atom<T>;
+export declare function isAtom<T = unknown>(input: Nil<MaybeWriteAtom<T>>): input is WriteAtom<T>;
+export declare function isAtom<T = unknown>(input: Nil<MaybeAtom<T>>): input is Atom<T>;
+export declare function isAtom<T = unknown>(input: unknown): input is WriteAtom<T>;
 /**
  * Checks if the provided input is an Atom and reads its value. Non-atom inputs are returned as-is.
  * Reports read access when inside an effect.
  * @see {@link isAtom}
- * @see {@link write}
  * @see {@link peek}
+ * @see {@link write}
  * @see {@link update}
  */
-declare function read<A>(input: A): A extends MaybeReadAtom<infer T> ? T : never;
+export declare function read<A>(input: A): A extends MaybeAtom<infer T> ? T : never;
 /**
  * Checks if the provided input is an Atom and reads its value. Non-atom inputs are returned as-is.
  * Does NOT report read access when inside an effect.
@@ -163,29 +243,261 @@ declare function read<A>(input: A): A extends MaybeReadAtom<infer T> ? T : never
  * @see {@link write}
  * @see {@link update}
  */
-declare function peek<A>(input: A): A extends MaybeReadAtom<infer T> ? T : never;
+export declare function peek<A>(input: A): A extends MaybeAtom<infer T> ? T : never;
 /**
  * Checks if the provided input is an Atom, writes its value and returns the new value.
  *
+ * Writing readonly Atoms is simply a no-op. Their current value will be returned and the provided
+ * new value discarded.
+ *
  * Non-atom inputs are never modified in any way. Instead the provided new value is discarded and
  * the input is returned as-is.
  * @see {@link isAtom}
  * @see {@link read}
- * @see {@link write}
+ * @see {@link peek}
  * @see {@link update}
  */
-declare function write<A>(input: A, value: A extends Atom<infer T> ? T : never, force?: boolean): A extends MaybeAtom<infer T> ? T : never;
+export declare function write<A>(input: A, value: A extends WriteAtom<infer T> ? T : never, force?: boolean): A extends MaybeWriteAtom<infer T> ? T : never;
 /**
  * Checks if the provided input is an Atom, updates its value using the provided transform function
  * and returns the new value.
  *
+ * Updating readonly Atoms is simply a no-op. Their current value will be returned and the
+ * transformed new value discarded.
+ *
  * Non-atom inputs are never modified in any way and the input is returned as-is.
  * @see {@link isAtom}
  * @see {@link read}
  * @see {@link peek}
  * @see {@link write}
  */
-declare function update<A>(input: A, transform: A extends Atom<infer T> ? (value: T) => T : never, force?: boolean): A extends MaybeAtom<infer T> ? T : never;
+export declare function update<A>(input: A, transform: A extends WriteAtom<infer T> ? (value: T) => T : never, force?: boolean): A extends MaybeWriteAtom<infer T> ? T : never;
+//#endregion
+//#region src/data/Scheduler.d.ts
+/**
+ * A function able to schedule a callback to be executed at a later time, e.g. `queueMicrotask`.
+ * The function must guarantee that the callback will be eventually executed.
+ */
+interface TickFn {
+  (onTick: () => void): void;
+}
+/**
+ * Runs a block of code on the next tick of the scheduler, synchronized with other updates. Unless
+ * a tick is already pending, a new one is scheduled.
+ *
+ * Atoms written within the block will deliver their update notifications synchronously within the
+ * same tick.
+ */
+export declare function tick(block: () => void, lifecycle?: Lifecycle): void;
+/**
+ * Similar to {@link tick}, but instead accepts a {@link Callback} object. Useful in hot paths
+ * where it may be desirable to reuse callback objects and/or avoid closures.
+ * @see {@link tick}
+ */
+export declare function scheduleTick<TArgs extends ArgsMax3>(lifecycle: Lifecycle, callback: Callback<TArgs>): void;
+/**
+ * Runs a block of code immediately after the next tick of the scheduler, once all regular updates
+ * have finished. Unless a tick is already pending, a new one is scheduled.
+ *
+ * While it is possible to write Atoms within the block, their update notifications are
+ * no longer delivered in the same scheduler tick - they're postponed to the next one.
+ */
+export declare function tock(block: () => void, lifecycle?: Lifecycle): void;
+/**
+ * Similar to {@link tock}, but instead accepts a {@link Callback} object. Useful in hot paths
+ * where it may be desirable to reuse callback objects and/or avoid closures.
+ * @see {@link tock}
+ */
+export declare function scheduleTock<TArgs extends ArgsMax3>(lifecycle: Lifecycle, callback: Callback<TArgs>): void;
+//#endregion
+//#region src/Adapter.d.ts
+interface Adapter<TNode, TElements extends ElementsType = ElementsType> {
+  /**
+   * Carries information about the available intrinsic elements when using this Adapter.
+   * @deprecated **Type only, does not exist at runtime!**
+   */
+  readonly $elements?: TElements;
+  /**
+   * A function able to schedule a callback to be executed at a later time, e.g. `queueMicrotask`.
+   * The function must guarantee that the callback will be eventually executed.
+   */
+  readonly tick: TickFn;
+  /**
+   * Creates a native (intrinsic) element node by the element name.
+   */
+  readonly element: (name: string) => TNode;
+  /**
+   * Creates or updates a text node. In both cases the node is returned.
+   */
+  readonly text: (value: string, node: TNode | null) => TNode;
+  /**
+   * Creates a marker node used to preserve a position within the node tree.
+   */
+  readonly marker: (comment?: string) => TNode;
+  /**
+   * Creates a batch to which nodes can be inserted "offline," without causing any updates. The
+   * batch is later inserted all at once using the `insert` function, causing only a single
+   * update.
+   *
+   * Adapters may omit this function when batching is not supported.
+   */
+  readonly batch?: () => TNode;
+  /**
+   * Inserts the given `node` as a child of the `parent`. If `before` is provided, the child will
+   * be inserted just before the referenced node (which itself must be a child of the parent),
+   * otherwise the child is inserted at the end, becoming the new last child of the parent.
+   */
+  readonly insert: (node: TNode, parent: TNode, before: TNode | null) => void;
+  /**
+   * Removes a node from the hierarchy.
+   */
+  readonly remove: (node: TNode) => void;
+  /**
+   * Sets a named property of the given node.
+   */
+  readonly set: (elem: TNode, prop: string, value: any) => void;
+}
+type ExtensionsType<TNode> = { [_ in string]?: Extension<TNode>; };
+interface Extension<TNode, TPropMapping extends ExtensionPropMapping<unknown> = ExtensionPropMapping<unknown>> {
+  /**
+   * Carries a mapping type used to infer the props this extension adds to native elements.
+   * @deprecated **Type only, does not exist at runtime!**
+   */
+  readonly $mapping?: TPropMapping;
+  /**
+   * Sets a named extension property of the given element. The prop name arrives unprefixed, i.e.
+   * without any extension key prefix.
+   */
+  readonly set: (node: TNode, prop: string, value: any, group: MountingGroup<TNode>) => void;
+}
+interface ExtensionPropMapping<TNode> {
+  /** Will contain a concrete type of the element for which props are being mapped. */
+  node: TNode;
+  /** Will contain a name of the element for which props are being mapped. */
+  name: string;
+  /**
+   * Override this field with an inferred object containing typed extension props. Prop names
+   * should be plain, do not include their extension prefix. It will be added automatically.
+   *
+   * To infer concrete types, you may use:
+   *
+   * - `this["node"]` ... concrete type of the element node
+   * - `this["name"]` ... the name of the element, as used in JSX
+   */
+  extension: {};
+}
+/** Creates an extension with a shared-runtime ID independent of its registered JSX prefix. */
+export declare function extension<TNode, TPropMapping extends ExtensionPropMapping<TNode>>(propSetter: Extension<TNode>["set"]): Extension<TNode, TPropMapping>;
+/**
+ * Builds a set of extension props using an Extension reference rather than relying on a globally
+ * registered prefixed extension props. The resulting object is intended to be ...spread directly
+ * onto JSX elements.
+ *
+ * Typically used in libraries where relying on a specific prefix convention would limit the users.
+ * Does not require an active component lifecycle. Repeated spreads use the last value for each
+ * extension/prop pair, while props from different extensions remain independent.
+ */
+export declare function ext<TMapping extends ExtensionPropMapping<any>, TNodeType, TElemName>(extension: Extension<any, TMapping>, extensionProps: (TMapping & {
+  node: TNodeType;
+  name: TElemName;
+})["extension"], targetPropsObject?: { [_ in string]?: any; }): {
+  readonly [S_NODE_TYPE]?: TNodeType;
+  readonly [S_ELEM_NAME]?: TElemName;
+};
+//#endregion
+//#region src/Renderer.d.ts
+interface Renderer<TNode, TElements extends ElementsType = ElementsType> extends Lifecycle {
+  /**
+   * Carries information about the available intrinsic elements when using this Renderer.
+   * @deprecated **Type only, does not exist at runtime!**
+   */
+  readonly $elements?: TElements;
+  mount: (root: TNode, jsx: JsxResult) => MountingGroup<TNode>;
+  unmount: (group: MountingGroup<TNode>) => void;
+}
+/** Extracts the typings of intrinsic elements supported by the given Renderer. */
+type ElementsOf<TRenderer, TFallback extends ElementsType = {}> = (TRenderer extends {
+  readonly $elements?: infer TElements extends ElementsType;
+} ? TElements : TFallback);
+interface MountingGroup<TNode> extends Lifecycle, Hierarchy<TNode> {
+  /** the Adapter rendering this MountingGroup */
+  readonly adapter: Adapter<TNode>;
+}
+interface NativeNode<TNode> extends Hierarchy<TNode> {}
+interface Hierarchy<TNode> {
+  /**
+   * tracks whether unmounting is in progress for this node, guarding against duplicate or cyclic
+   * unmount attempts
+   */
+  $isUnmounting?: boolean;
+}
+type HNode<TNode> = MountingGroup<TNode> | NativeNode<TNode>;
+/**
+ * Unmounts a MountingGroup and removes it from the hierarchy. The removal is guaranteed even if
+ * user code throws during unmount. Also clears refs to its original parent node. Destroyed groups
+ * cannot be reused.
+ */
+export declare function destroy<TNode>(hGroup: MountingGroup<TNode>): void;
+/**
+ * Creates a sub-group within the provided MountingGroup. Needed whenever a subtree needs to mount
+ * or unmount dynamically.
+ */
+export declare function fork<TNode>(hParent: HNode<TNode>, hBefore?: HNode<TNode> | null): MountingGroup<TNode>;
+/**
+ * Inserts a HNode to the hierarchy. When reusing nodes, callers must make sure `untrack` has been
+ * previously called on the node to be re-inserted.
+ * @see {@link untrack}
+ */
+export declare function track<TNode>(hNode: HNode<TNode>, hParent: HNode<TNode>, hBefore?: HNode<TNode> | null): void;
+/**
+ * Removes a HNode from the tracking hierarchy. Removed nodes may be reused and re-inserted using
+ * the `track` function.
+ * @see {@link track}
+ */
+export declare function untrack<TNode>(hNode: HNode<TNode>): void;
+/**
+ * Creates a reusable callback for a complete render operation, including reactive reads, nested
+ * mounts and batch commits. Each invocation defers conflicting unmounts until the outermost render
+ * finishes, preserves the caller's reactive tracking, and returns the block's result unchanged.
+ *
+ * Deferred teardown errors are reported by the outermost render, after all requests are processed.
+ */
+export declare function willMount<TNode, TArgs extends ArgsMax3, TResult>(hGroup: MountingGroup<TNode>, block: (...args: TArgs) => TResult): (...args: TArgs) => TResult;
+/**
+ * Mounts JSX into a group that is not already mounted. When rendering into an externally owned
+ * batch, enclose the complete operation (including the commit and `flush`) in {@link willMount}.
+ */
+export declare function mount<TNode>(jsx: any, hParent: MountingGroup<TNode>, hBefore: HNode<TNode> | null, nUsedParent: TNode, nRealParent: TNode, isBatch: boolean): void;
+/**
+ * Marks the provided hGroup and all of its descendants as mounted and dispatches notifications
+ * where appropriate.
+ *
+ * Normally this happens automatically as part of calling {@link mount}, but it is necessary to
+ * flush manually when rendering into a batch. Batch owners are responsible for calling this
+ * function once the batch has been committed.
+ */
+export declare function flush<TNode>(hGroup: MountingGroup<TNode>): void;
+/**
+ * Unmounts the contents of a MountingGroup from the node tree. The group itself, though empty,
+ * remains usable and can be remounted later.
+ *
+ * If teardown would interrupt an active render, it is deferred until the outermost render
+ * operation finishes. Any teardown errors are then reported by that operation.
+ */
+export declare function unmount<TNode>(hGroup: MountingGroup<TNode>): void;
+/**
+ * Mounts components described by JSX to the specified location in the node tree.
+ */
+export declare function mountJsx<TNode>(jsx: any, hParent: HNode<TNode>, hBefore: HNode<TNode> | null, nUsedParent: TNode, nRealParent: TNode, isBatch: boolean): void;
+/**
+ * Inserts a native node and adds it to the tracking hierarchy. Necessary to preserve render order.
+ * Returns the newly created tracking node, or null when tracking is skipped. Only a direct child
+ * of hParent is used as a tracking insertion point; an outer anchor means appending within hParent.
+ * Batched native insertions append, while hBefore still determines the tracking position.
+ * Should only be called by component handlers!
+ */
+export declare function insert<TNode>(nNode: TNode, children: any, hParent: HNode<TNode>, hBefore: HNode<TNode> | null, nUsedParent: TNode, isBatch: boolean, forceTrack: true): NativeNode<TNode>;
+export declare function insert<TNode>(nNode: TNode, children: any, hParent: HNode<TNode>, hBefore: HNode<TNode> | null, nUsedParent: TNode, isBatch: boolean, forceTrack?: boolean): NativeNode<TNode> | null;
 //#endregion
 //#region src/Component.d.ts
 /**
@@ -202,7 +514,7 @@ type PropsOf<T> = T extends Component<infer TProps> ? TProps : unknown;
 interface DataTemplate<TData> {
   (data: TData): JsxResult;
 }
-declare function component<TPropsArg extends [{}]>(block: (...args: TPropsArg) => JsxResult, devId?: string): (...args: [props: JsxProps<TPropsArg[0]>]) => JsxResult;
+export declare function component<TPropsArg extends [{}]>(block: (...args: TPropsArg) => JsxResult, devId?: string): (...args: [props: JsxProps<TPropsArg[0]>]) => JsxResult;
 /**
  * Infers the props object for use with JSX. Because Pyxis always supplies components with child
  * arrays (or tuples), the type needs to be adjusted to reflect the internal mechanics.
@@ -222,23 +534,32 @@ type JsxProps<T> = { readonly [K in keyof T]: K extends "children" ? JsxChildren
  */
 type JsxChildrenProp<T> = T extends readonly [any, any, ...any[]] ? T extends readonly [...infer C] ? readonly [...C] : T : T extends readonly [infer SC] ? SC : T extends readonly (infer C)[] ? readonly C[] | C : T;
 /**
- * Primitive types accepted to render as text.
+ * Primitive values (or Atoms of such primitives) accepted as text children. Nil and boolean values
+ * do not render any text.
  */
-type JsxText = MaybeReadAtom<Nil<string | number | boolean | bigint>>;
+type JsxText = MaybeAtom<Nil<string | number | boolean | bigint>>;
 /**
  * Describes the objects returned by JSX factories.
  *
- * Pyxis uses very lightweight factories returning the props object directly,
- * adding a few extra props:
- *
- * - S_COMPONENT ... hidden, contains a reference to the ComponentHandler function
- * - S_TAG_NAME ... hidden, specifies the tag name, only populated for native elements
- * - children ... always present and always an array, empty array for childless components
+ * Pyxis uses lightweight factories returning the props object directly, only adding a few extra
+ * symbol-keyed props.
  */
 interface JsxObject {
   [propName: string]: unknown;
+  /** specifies the ComponentHandler function used to render this object */
+  readonly [S_COMPONENT]: ComponentHandler;
+  /** specifies the native element tag name, only populated for native elements */
+  readonly [S_TAG_NAME]?: string;
+  /** holds source code location of individual JSX nodes, only populated in dev mode */
+  readonly [S_DEV_INFO]?: JsxDevSourceInfo;
+  /** always present and always an array, empty array for childless components */
   readonly children: readonly unknown[];
 }
+interface JsxDevSourceInfo {
+  readonly fileName: string;
+  readonly lineNumber: number;
+  readonly columnNumber: number;
+}
 /**
  * Union of all admissible values within JSX.
  */
@@ -253,6 +574,22 @@ type JsxChildren = JsxResult | readonly JsxChildren[];
 type WithChildren<T extends PropsType> = T & {
   children?: JsxChildren;
 };
+/**
+ * A handler function rendering a specific Component type. This is the real shape of Pyxis
+ * components used internally by the framework. `hBefore` is a tracked native anchor. When
+ * `isBatch` is true, native insertions append while `hBefore` still determines the position in the
+ * tracking hierarchy.
+ */
+interface ComponentHandler {
+  <TNode>(jsx: JsxObject, hParent: HNode<TNode>, hBefore: HNode<TNode> | null, nUsedParent: TNode, nRealParent: TNode, isBatch: boolean): void;
+}
+declare global {
+  namespace JSX {
+    interface ElementChildrenAttribute {
+      children: {};
+    }
+  }
+}
 //#endregion
 //#region src/component/Fragment.d.ts
 interface FragmentProps {
@@ -261,38 +598,40 @@ interface FragmentProps {
 /**
  * The built-in Fragment Component wrapping multiple Components.
  */
-declare function Fragment(props: JsxProps<FragmentProps>): JsxResult;
+export declare function Fragment(props: JsxProps<FragmentProps>): JsxResult;
 //#endregion
 //#region src/data/ListDelta.d.ts
-declare enum ChangeKind {
-  Change = 1,
-  Insert = 2,
-  Remove = 3,
-  Clear = 4
-}
+export declare const LC_CHANGE = 1;
+export declare const LC_INSERT = 2;
+export declare const LC_REMOVE = 3;
+export declare const LC_CLEAR = 4;
 interface ListDelta<T> {
-  readonly changes: ListChange<T>[];
-  lengthChange: number;
+  /** raw snapshot of the List as observed at the time this ListDelta was emitted */
+  readonly snapshot: readonly T[];
+  /** changes made to the List since its last update */
+  readonly changes: readonly ListChange<T>[];
+  /** the relative change of the List size (its item count) */
+  readonly relSize: number;
 }
 type ListChange<T> = ListItemChanged<T> | ListItemInserted<T> | ListItemRemoved<T> | ListCleared;
 interface ListItemChanged<T> {
-  kind: ChangeKind.Change;
+  kind: typeof LC_CHANGE;
   index: number;
   oldItem: T;
   newItem: T;
 }
 interface ListItemInserted<T> {
-  kind: ChangeKind.Insert;
+  kind: typeof LC_INSERT;
   index: number;
   newItem: T;
 }
 interface ListItemRemoved<T> {
-  kind: ChangeKind.Remove;
+  kind: typeof LC_REMOVE;
   index: number;
   oldItem: T;
 }
 interface ListCleared {
-  kind: ChangeKind.Clear;
+  kind: typeof LC_CLEAR;
   index: number;
 }
 interface Equals<T> {
@@ -303,31 +642,54 @@ interface Equals<T> {
 interface ReadonlyList<T> extends Iterable<T>, DependencyList {
   /**
    * Gets the size of this List.
+   *
    * Reactive in effects and derivations.
    */
   size(): number;
   /**
    * Gets the item at the specified index. Return undefined when outside of the List's bounds.
+   *
    * Reactive in effects and derivations.
    */
   get(index: number): T | undefined;
   /**
-   * Gets a set of changes made to this List within the current tick. Returns null when no changes
-   * were made.
-   * Reactive in effects and derivations.
+   * Gets a boolean indicating whether changes have been made to this List that have not yet been
+   * delivered to its observers.
+   *
+   * Non-reactive in effects and derivations.
    */
-  delta(): ListDelta<T> | null;
+  dirty(): boolean;
   /**
-   * Gets the underlying array of items. The array is read-only, mutating it will cause observers
-   * to go out of sync.
+   * Registers a callback to run whenever one or more changes are made to this List. The callback
+   * receives a ListDelta object describing all changes made since the last notification.
+   *
    * Non-reactive in effects and derivations.
    */
+  delta(block: (delta: ListDelta<T>) => void, lifecycle?: Lifecycle): void;
+  /**
+   * Gets the underlying array of items of this List. The array is read-only, but may change when
+   * the List itself is mutated.
+   *
+   * Non-reactive in effects and derivations.
+   *
+   * *Mutating the array directly (e.g. in unchecked JS code) will cause any and all observers to
+   * go out of sync, breaking the rendered state in unpredictable ways!*
+   */
   raw(): readonly T[];
   /**
-   * Runs the provided callback for each item of this List.
+   * Runs a block of code for each item of this List.
+   *
    * Reactive in effects and derivations.
    */
-  forEach(callback: (item: T, index: number) => void, thisArg?: any): void;
+  forEach(block: (item: T, index: number) => void): void;
+  /**
+   * Runs a block of code with a stable, immutable snapshot of the items within this List. The
+   * List itself may be mutated as a result of running this code, but the provided snapshot will
+   * not reflect any such changes.
+   *
+   * Non-reactive in effects and derivations.
+   */
+  stable<R>(block: (snapshot: readonly T[]) => R): R;
 }
 interface List<T> extends ReadonlyList<T> {
   /**
@@ -387,36 +749,37 @@ interface List<T> extends ReadonlyList<T> {
  * Creates an empty List. This List emits deltas with each mutation which can be observed by
  * Components to efficiently update the rendered state.
  */
-declare function listOf<T>(): List<T>;
-declare function listOf<T>(source: Nil<never>, lifecycle?: Lifecycle, devId?: string): List<T>;
+export declare function listOf<T>(): List<T>;
+export declare function listOf<T>(source: Nil<never>, lifecycle?: Lifecycle, devId?: string): List<T>;
 /**
  * Creates a List initialized with items copied from the provided Iterable. This List emits deltas
  * with each mutation which can be observed by Components to efficiently update the rendered state.
  */
-declare function listOf<T>(source: Iterable<T>, lifecycle?: Lifecycle, devId?: string): List<T>;
+export declare function listOf<T>(source: Iterable<T>, lifecycle?: Lifecycle, devId?: string): List<T>;
 /**
  * Synchronizes the provided List with the given data source. After this operation, the list will
  * contain an exact copy of the source.
  *
- * Note: This function is separated instead of being a List method since the underlying diff
- * algorithm (Myers) is a relatively large chunk of code which would otherwise always get included
- * into bundled builds. This way, tools like Terser can eliminate the extra code when unused.
+ * Note: This function is separated instead of being a List method as the underlying diff algorithm
+ * (Myers) is a relatively large chunk of code which would otherwise always get bundled into
+ * applications. This way, tools like Terser can easily eliminate the extra code when unused.
  */
-declare function sync<T>(list: List<T>, source: readonly T[], eq?: Equals<T>): void;
+export declare function sync<T>(list: List<T>, source: Iterable<T>, eq?: Equals<T>): void;
 //#endregion
 //#region src/data/ProxyAtom.d.ts
-interface ProxyAtom<T> extends Atom<T> {
+interface ProxyAtom<T> extends WriteAtom<T> {
   /**
    * Binds this ProxyAtom to a new value. If it is an Atom, the proxy will mirror it, otherwise it
    * will be a read-only atom with a static value until rebound.
+   * Binding a proxy to itself throws in development and is ignored in production.
    */
   use(value: MaybeAtom<T>): void;
 }
 /**
  * Creates a ProxyAtom bound to the provided initial value. If it is an Atom, the proxy will mirror
- * it, otherwise it will be a read-only atom with a static value until rebound.
+ * it, otherwise it will be a read-only atom with a static value until rebound via its `use` method.
  */
-declare function proxyOf<T>(initialValue: MaybeAtom<T>, lifecycle?: Lifecycle): ProxyAtom<T>;
+export declare function proxyOf<T>(initialValue: MaybeAtom<T>, lifecycle?: Lifecycle): ProxyAtom<T>;
 type Proxied<T, P extends readonly (keyof T)[]> = {
   readonly proxied: T;
 } & { readonly [K in P[number]]: ProxyAtom<T[K] extends MaybeAtom<infer V> ? V : T[K]>; };
@@ -429,163 +792,18 @@ interface RemountIteratorProps<T> {
 }
 interface ProxyIteratorProps<T, P extends readonly (keyof T)[]> {
   source: ReadonlyList<T>;
-  proxy: P;
+  proxy: P & ("proxied" extends P[number] ? never : unknown);
   children: [template: DataTemplate<Proxied<T, P>>];
 }
 /**
  * The built-in Iterator Component efficiently rendering collections of items
  * based on updates from a Pyxis `list`.
  */
-declare function Iterator<T>(props: JsxProps<RemountIteratorProps<T>>): JsxResult;
-declare function Iterator<T, P extends readonly (keyof T)[]>(props: JsxProps<ProxyIteratorProps<T, P>>): JsxResult;
-//#endregion
-//#region src/data/Scheduler.d.ts
-/**
- * A function able to schedule a callback to be executed at a later time, e.g. `queueMicrotask`.
- * The function must guarantee that the callback will be eventually executed.
- */
-interface TickFn {
-  (onTick: () => void): void;
-}
-/**
- * Runs a block of code on the next tick of the scheduler, synchronized with other updates. If a
- * tick is not currently pending, a new one is scheduled.
- */
-declare function tick(block: () => void, lifecycle?: Lifecycle): void;
-/**
- * Runs a block of code after the next tick of the scheduler, once all regular updates finished.
- * If a tick is not currently pending, a new one is scheduled.
- */
-declare function tock(block: () => void, lifecycle?: Lifecycle): void;
-//#endregion
-//#region src/Adapter.d.ts
-interface Adapter<TNode, TIntrinsicElements extends ElementsType = ElementsType> {
-  /**
-   * Carries information about the available intrinsic elements when using this Adapter.
-   * @deprecated **Type only, does not exist at runtime!**
-   */
-  readonly $elements?: TIntrinsicElements;
-  /**
-   * A function able to schedule a callback to be executed at a later time, e.g. `queueMicrotask`.
-   * The function must guarantee that the callback will be eventually executed.
-   */
-  readonly tick: TickFn;
-  /**
-   * Creates a native (intrinsic) element node by its name.
-   */
-  readonly element: (name: string) => TNode;
-  /**
-   * Creates or updates a text node. In both cases the node is returned.
-   */
-  readonly text: (value: string, node: TNode | null) => TNode;
-  /**
-   * Creates a marker node used to preserve a position within the node tree.
-   */
-  readonly marker: (comment?: string) => TNode;
-  /**
-   * Creates a batch to which nodes can be inserted "offline," without causing any updates. The
-   * batch is later inserted all at once using the `insert` function, causing only a single
-   * update.
-   *
-   * Adapters may omit this function when batching is not supported.
-   */
-  readonly batch?: () => TNode;
-  /**
-   * Inserts the given `node` as a child of the `parent`. If `before` is provided, the child will
-   * be inserted just before the referenced node, otherwise the child is inserted as the new last
-   * child.
-   */
-  readonly insert: (node: TNode, parent: TNode, before: TNode | null) => void;
-  /**
-   * Removes a node from the hierarchy.
-   */
-  readonly remove: (node: TNode) => void;
-  /**
-   * Sets a named property of the given node.
-   */
-  readonly set: (node: TNode, prop: string, value: any) => void;
-}
-interface Extension<TNode, TExtensionKey extends string = string, TIntrinsicElements extends ElementsType = ElementsType, TExtendedIntrinsicElements extends ElementsType = ElementsType> {
-  /**
-   * Infers prop types to decorate existing types with extensions.
-   * Type only, this call signature does not exist at runtime!
-   */
-  (extensionKey: TExtensionKey, intrinsicElements: TIntrinsicElements): TExtendedIntrinsicElements;
-  /**
-   * Sets a named extension property of the given node.
-   */
-  readonly set: (node: TNode, prop: string, value: any, group: MountingGroup<TNode>) => void;
-}
-type ExtensionsType<TNode> = { [_ in string]?: Extension<TNode>; };
-type ExtensionProps<TExtensionKey extends string, TProps extends PropsType> = { readonly [TExtPropKey in `${TExtensionKey}:${keyof TProps & string}`]?: (TExtPropKey extends `${TExtensionKey}:${infer TPropKey}` ? TProps[TPropKey] : never); };
-//#endregion
-//#region src/Renderer.d.ts
-interface Renderer<TNode, TIntrinsicElements extends ElementsType = ElementsType> {
-  /**
-   * Carries information about the available intrinsic elements when using this Renderer.
-   * @deprecated **Type only, does not exist at runtime!**
-   */
-  readonly $elements?: TIntrinsicElements;
-  mount: (root: TNode, jsx: JsxResult) => void;
-  unmount: () => void;
-}
-type ElementsOf<TRenderer> = TRenderer extends {
-  readonly $elements?: infer TElements;
-} ? TElements : {};
-interface MountingGroup<TNode> extends Lifecycle, Hierarchy<TNode> {
-  readonly $isGroup: true;
-  readonly $isNative?: never;
-  /** the Adapter rendering this MountingGroup */
-  readonly adapter: Adapter<TNode>;
-}
-interface NativeNode<TNode> extends Hierarchy<TNode> {
-  readonly $isNative: true;
-  readonly $isGroup?: never;
-  readonly $nn: TNode;
-}
-interface Hierarchy<TNode> {}
-type HNode<TNode> = MountingGroup<TNode> | NativeNode<TNode>;
-/**
- * Creates a sub-group within the provided MountingGroup. Needed whenever a subtree needs to mount
- * or unmount dynamically.
- */
-declare function fork<TNode>(hParent: HNode<TNode>, hBefore?: HNode<TNode> | null): MountingGroup<TNode>;
-/**
- * Adds a HNode to the hierarchy.
- */
-declare function track<TNode>(hNode: HNode<TNode>, hParent: HNode<TNode>, hBefore?: HNode<TNode> | null): void;
-/**
- * Removes a HNode from the tracking hierarchy.
- */
-declare function untrack<TNode>(hNode: HNode<TNode>): void;
-/**
- * Mounts a MountingGroup to the specified location in the node tree. If the group is already
- * mounted (i.e. its native nodes are already rendered somewhere), it is moved to the new location
- * without re-mounting Pyxis components.
- *
- * Note that for successfully moving a group within the tree, you should first `untrack` the group,
- * then re-`track` it to the new location and only then call `mount` to commit the move.
- * @see {@link track}
- * @see {@link untrack}
- */
-declare function mount<TNode>(jsx: any, hGroup: MountingGroup<TNode>, nUsedParent: TNode, nRealParent: TNode, nBefore: TNode | null, isBatch: boolean): void;
-/**
- * Unmounts the contents of a MountingGroup from the node tree. The group itself, though empty,
- * remains usable and can be remounted later.
- */
-declare function unmount<TNode>(group: MountingGroup<TNode>): void;
-/**
- * Mounts components described by the JsxResult to the specified location in the node tree.
- */
-declare function mountJsx<TNode>(jsx: any, hParent: HNode<TNode>, nUsedParent: TNode, nRealParent: TNode, nBefore: TNode | null, isBatch: boolean): void;
-/**
- * Inserts a native node and adds it to the tracking hierarchy. Necessary to preserve render order.
- * Should only be called by component handlers!
- */
-declare function insert<TNode>(nNode: TNode, children: any, hParent: HNode<TNode>, nUsedParent: TNode, nBefore: TNode | null, isBatch: boolean): void;
+export declare function Iterator<T>(props: JsxProps<RemountIteratorProps<T>>): JsxResult;
+export declare function Iterator<T, P extends readonly (keyof T)[]>(props: JsxProps<ProxyIteratorProps<T, P>>): JsxResult;
 //#endregion
 //#region src/component/Native.d.ts
-declare function Native<TNode>(jsx: JsxObject, hParent: HNode<TNode>, nUsedParent: TNode, _nRealParent: TNode, nBefore: TNode | null, isBatch: boolean): void;
+export declare function Native<TNode>(jsx: JsxObject, hParent: HNode<TNode>, hBefore: HNode<TNode> | null, nUsedParent: TNode, _nRealParent: TNode, isBatch: boolean): TNode;
 //#endregion
 //#region src/component/Show.d.ts
 interface ShowProps {
@@ -596,145 +814,225 @@ interface ShowDataProps<T> {
   when?: MaybeAtom<boolean>;
   proxy?: never;
   data: MaybeAtom<T>;
-  children: [template: DataTemplate<T> | ReadAtom<Nil<DataTemplate<T>>>];
+  children: [template: DataTemplate<T> | Atom<Nil<DataTemplate<T>>>];
 }
 interface ShowProxyDataProps<T, P extends readonly (keyof T)[]> {
   when?: MaybeAtom<boolean>;
-  proxy: P;
+  proxy: P & ("proxied" extends P[number] ? never : unknown);
   data: MaybeAtom<T>;
-  children: [template: DataTemplate<Proxied<T, P>> | ReadAtom<Nil<DataTemplate<Proxied<T, P>>>>];
+  children: [template: DataTemplate<Proxied<T, P>> | Atom<Nil<DataTemplate<Proxied<T, P>>>>];
 }
 /**
  * The built-in Show Component dynamically mounting and unmounting a Template
  * based on a reactive condition result.
  */
-declare function Show(props: JsxProps<ShowProps>): JsxResult;
-declare function Show<T>(props: JsxProps<ShowDataProps<T>>): JsxResult;
-declare function Show<T, P extends readonly (keyof T)[]>(props: JsxProps<ShowProxyDataProps<T, P>>): JsxResult;
+export declare function Show(props: JsxProps<ShowProps>): JsxResult;
+export declare function Show<T>(props: JsxProps<ShowDataProps<T>>): JsxResult;
+export declare function Show<T, P extends readonly (keyof T)[]>(props: JsxProps<ShowProxyDataProps<T, P>>): JsxResult;
 //#endregion
 //#region src/data/Context.d.ts
 /**
- * Describes a Context distributing data throughout the Component hierarchy.
- * @see {@link createContext}
+ * Describes a Context propagating data throughout the Component hierarchy.
+ * @see {@link contextOf}
  */
 interface Context<T> {
   /**
-   * A fake property kept for TypeScript to properly type-check Context compatibility.
+   * Carries typings of the data propagated by this Context. Typed as a function to enforce
+   * correct variance of the generic value type.
    * @deprecated **Type only, does not exist at runtime!**
    */
-  readonly $contract?: (value: T) => void;
+  readonly $contract?: (value: T) => T;
 }
 /**
- * Creates a typed Context that can be used to propagate observable data throughout entire component
- * trees without "prop drilling."
- * @see {@link context}
+ * Creates a typed Context allowing propagation of observable data throughout entire component trees
+ * without "prop drilling."
  */
-declare function createContext<T>(devId?: string): Context<T>;
-interface ContextAtom<T> extends Atom<T> {
-  $dep?: Nil<Dependency>;
-  $ancestor?: Nil<Atom<T>>;
-  $value?: T;
-}
+export declare function contextOf<T>(devId?: string): Context<T>;
+/**
+ * Augments the current Component to act as a host (aka provider) of the given Context. Returns a
+ * mutable Atom carrying the contextual value propagated to all descendant Components that consume
+ * the Context.
+ *
+ * When a default value is specified, it will immediately be used as the hosted value, overriding
+ * any value hosted by ancestors of this Component.
+ *
+ * Without a default value specified, the Context initializes as "transparent," forwarding values
+ * hosted by ancestors of this Component. Once the returned Atom is written into for the first time,
+ * it breaks this link and begins hosting the new value from that point onwards. In forwarding mode,
+ * if no ancestor hosts the Context, the value is not well defined and reading the Atom fails until
+ * at least one of the hosts define a value.
+ *
+ * Descendants of this Component are able to consume the hosted value via `contextual(context)`
+ * receiving a readonly Atom.
+ *
+ * Note that due to how JavaScript arguments are handled, `undefined` is always treated as no
+ * default provided, even if it is an allowed value of the Context. To explicitly initialize hosts
+ * to the literal value `undefined`, you need to write the Atom separately, e.g.:
+ *
+ * ```ts
+ * const MyContext = contextOf<number | undefined>();
+ *
+ * // ...then, within a component:
+ * const value = host(MyContext);
+ * write(value, undefined);
+ * ```
+ * @see {@link contextual}
+ */
+export declare function host<C>(context: C, defaultValue?: C extends Context<infer T> ? T : never, lifecycle?: Lifecycle, devId?: string): C extends Context<infer T> ? WriteAtom<T> : never;
 /**
- * Gets a consumer Atom for the given Context. This atom will be read-only.
+ * Gets a readonly Atom carrying the value inherited from the nearest ancestor of the current
+ * Component hosting the specified Context. This call fails if no ancestor is hosting the Context.
  * @see {@link host}
  */
-declare function consumerOf<T>(context: Context<T>): Atom<T> | null;
+export declare function contextual<T>(context: Context<T>): Atom<T>;
+//#endregion
+//#region src/data/Derivation.d.ts
+/**
+ * Holds a value derived from values of other Atoms, managing reactions to their changes.
+ * Derivations are read-only. Use the `read` function to access its value.
+ * @see {@link read}
+ */
+interface Derivation<T = unknown> extends Atom<T> {}
 /**
- * Marks the current component as a host for the given context. Returns a mutable ContextAtom;
- * Values written to it will be propagated to any descendant component that consumes the context via
- * `consumerOf(context)`.
- * @see {@link consumerOf}
+ * Creates a Derivation - an Atom with its value computed from other Atoms. The block runs once
+ * eagerly to compute the initial value, then re-runs within scheduler ticks whenever its source
+ * Atoms change. Observers are only notified if the new value differs from the previous.
  */
-declare function host<C>(context: C, defaultValue?: C extends Context<infer T> ? T : never, devId?: string): C extends Context<infer T> ? ContextAtom<T> : never;
+export declare function derived<T>(block: () => T, lifecycle?: Lifecycle): Derivation<T>;
 //#endregion
 //#region src/data/Effect.d.ts
 interface EffectBlock {
   (): (() => void) | void;
 }
-interface Effect<T> {}
 /**
  * Creates an Effect - a block of logic executed each time any of the Atoms accessed within it
- * change. The block is first synchronously executed when the Effect is created.
+ * change. The block is first synchronously executed when the Effect is created. Atoms may be
+ * written or even created within the block, but note that writing an Atom this Effect depends on
+ * may cause an infinite update loop when the state doesn't converge to a point where no more
+ * re-runs of this Effect are required.
  *
- * If a teardown callback is returned, it will be run before the next effect re-run, or on component
- * unmount.
+ * When a teardown callback is returned, it will be run before the next re-run of this Effect, or
+ * once the enclosing Component unmounts, whichever comes first.
  */
-declare function effect(block: EffectBlock, lifecycle?: Lifecycle): void;
+export declare function effect(block: EffectBlock, lifecycle?: Lifecycle): void;
 /**
  * Runs a block of code removed from any effects. Accessing atoms within this block will be ignored
  * by any effect that may otherwise be observing this code.
  */
-declare function noEffect<T>(block: () => T): T;
-//#endregion
-//#region src/data/Derivation.d.ts
-/**
- * Holds a value derived from values of other Atoms, managing reactions to their changes.
- * Derivations are read-only. Use the `read` function to access its value.
- * @see {@link read}
- */
-interface Derivation<T = unknown> extends Atom<T>, Effect<T> {}
-/**
- * Creates a Derivation - an Atom with its value computed from other Atoms. The block runs once
- * eagerly to compute the initial value, then re-runs within scheduler ticks whenever its source
- * Atoms change. Observers are only notified if the new value differs from the previous.
- */
-declare function derived<T>(block: () => T, lifecycle?: Lifecycle): Derivation<T>;
+export declare function noEffect<TArgs extends ArgsMax3, TReturn>(block: (...args: TArgs) => TReturn, ...args: TArgs): TReturn;
 //#endregion
 //#region src/extension/RefExtension.d.ts
-interface RefExtensionType {
-  <TExtensionKey extends string, TElements extends ElementsType>(extensionKey: TExtensionKey, elements: TElements): { [TElementName in keyof TElements]: TElements[TElementName] & ExtensionProps<TExtensionKey, {
-    readonly atom?: Atom<NodeType<TElements[TElementName]> | null>;
-    readonly call?: RefFn<NodeType<TElements[TElementName]>>;
-  }>; };
-  set: (node: any, prop: string, value: any, group?: MountingGroup<any>) => void;
+interface RefPropMapping extends ExtensionPropMapping<unknown> {
+  extension: RefProps<this["node"]>;
+}
+interface RefProps<TNode> {
+  readonly atom?: WriteAtom<TNode | null>;
+  readonly call?: RefFn<TNode>;
 }
 interface RefFn<TNode> {
-  (node: TNode | null): void;
+  (node: TNode): (() => void) | void;
 }
 /**
- * Extension adding direct reference access to any element. Recommended prefix:
- * `"ref"`
+ * Extension adding direct reference access to any element. Recommended prefix: `"ref"`
+ *
+ * References can be stored into Atoms:
  *
- * References can be stored into atoms:
  * ```tsx
- * const wrapperRef = atomOf<HTMLDivElement>();
+ * const wrapperRef = atomOf<HTMLDivElement | null>(null);
  * <div ref:atom={wrapperRef} />
  * ```
- * or handled with a custom callback:
+ *
+ * The Atom will be set to the referenced node once it mounts. Later, when the node unmounts, the
+ * Atom is set back to `null`.
+ *
+ * References can also be received via callbacks:
+ *
  * ```tsx
- * const onWrapperRef = (node: HTMLDivElement) => { ... };
+ * const onWrapperRef = (node: HTMLDivElement) => {
+ *   // ...
+ * };
+ *
  * <div ref:call={onWrapperRef} />
  * ```
+ *
+ * Ref callbacks are only called when the node mounts, they never receive `null`. Instead,
+ * unmounted nodes may be handled by returning a teardown callback.
  */
-declare const RefExtension: RefExtensionType;
+export declare const RefExtension: Extension<any, RefPropMapping>;
 //#endregion
-//#region src/support/text.d.ts
+//#region src/support/common.d.ts
 /**
- * A template literal tag that automatically wraps each substitution in a `read` call.
- * @see {@link read}
+ * Invokes a {@link Callback} passing stored arguments and forwarding its return value.
  */
-declare function reads(strings: TemplateStringsArray, ...values: JsxText[]): string;
+export declare function invoke<TArgs extends ArgsMax3, TReturn>(callback: Callback<TArgs, TReturn>): TReturn;
+//#endregion
+//#region src/support/atoms.d.ts
 /**
- * A template literal tag that automatically wraps each substitution in a `peek` call.
- * @see {@link peek}
+ * A template string tag that creates a Derivation Atom from the tagged template. The derivation
+ * automatically observes any Atoms among substitutions and updates the resulting string whenever
+ * one or more of these Atoms change.
+ *
+ * Substitutions use String conversion; Failed conversions get replaced with `[error]`. Ideally,
+ * you'd want to make sure `String(yourValue)` never fails.
  */
-declare function peeks(strings: TemplateStringsArray, ...values: JsxText[]): string;
-//#endregion
-//#region src/Builder.d.ts
-interface PyxisBuilder<TNode, TIntrinsicElements extends ElementsType> {
-  build: () => Renderer<TNode, TIntrinsicElements>;
-  extend: <TExtensionKey extends string, TExtendedIntrinsicElements extends ElementsType>(extensionKey: TExtensionKey, extension: (extensionKey: TExtensionKey, intrinsicElements: TIntrinsicElements) => TExtendedIntrinsicElements) => PyxisBuilder<TNode, Merged<TExtendedIntrinsicElements>>;
-}
-type MergeIntersection<T> = { [K in keyof T]: T[K]; } & {};
-type Merged<T> = { [K in keyof T]: MergeIntersection<T[K]>; };
-declare function pyxis<TNode, TIntrinsicElements extends ElementsType>(adapter: Adapter<TNode, TIntrinsicElements>): PyxisBuilder<TNode, TIntrinsicElements>;
+export declare function text(strings: TemplateStringsArray, ...values: unknown[]): Derivation<string>;
+/**
+ * Creates a callback wrapping a call to the {@link write} function. Useful for decluttering inline
+ * event handlers in JSX templates.
+ * @see {@link write}
+ */
+export declare function writes<A>(input: A, value: A extends WriteAtom<infer T> ? T : never, force?: boolean): () => void;
+/**
+ * Creates a callback wrapping a call to the {@link update} function. Useful for decluttering inline
+ * event handlers in JSX templates.
+ * @see {@link update}
+ */
+export declare function updates<A>(input: A, transform: A extends WriteAtom<infer T> ? (value: T) => T : never, force?: boolean): () => void;
+/**
+ * Extracts the type of value represented by the given type, unwrapping Atoms if they're part of the
+ * type.
+ */
+type ValueType<T> = T extends Atom<infer V> ? V : T;
+/**
+ * Infers an object with its fields' values wrapped in Atoms. Optionally, if a specific TKeys union
+ * is provided, only select fields will be wrapped.
+ */
+type AtomsOf<TData extends { readonly [K in string]: any; }, TKeys extends (keyof TData & (string | number)) | undefined = undefined> = (undefined extends TKeys ? { [K in keyof TData as K extends string | number ? K : never]: undefined extends TData[K] ? MaybeWriteAtom<ValueType<TData[K]>> : WriteAtom<ValueType<TData[K]>>; } : Flatten<({ [K in TKeys & keyof TData & (string | number)]-?: WriteAtom<ValueType<TData[K]>>; } & Omit<Pick<TData, keyof TData & (string | number)>, TKeys & keyof TData>)>);
+/**
+ * Creates a new data object mapped from the one provided, with its fields' values wrapped in
+ * mutable Atoms. Optionally, a tuple of keys can be given to only wrap the select fields, copying
+ * others as-is.
+ */
+export declare function atomsOf<TData extends { readonly [K in string]: any; }>(data: TData, lifecycle?: Lifecycle): AtomsOf<TData>;
+export declare function atomsOf<TData extends { readonly [K in string]: any; }, const TKeys extends readonly (keyof TData & (string | number))[]>(data: TData, keys: TKeys & (number extends TKeys["length"] ? never : unknown), lifecycle?: Lifecycle): AtomsOf<TData, TKeys[number]>;
+/**
+ * Assigns values taken from the provided data object to the store (typically previously created
+ * via {@link atomsOf}). Optionally, a tuple of keys can be given to treat select fields as
+ * guaranteed Atoms while copying others as-is. Typically, you'd pass the same keys tuple to both
+ * `atomsOf` and later `assign` calls.
+ */
+export declare function assign<TData extends { readonly [K in string]: any; }, TStore extends AtomsOf<TData>>(store: TStore, data: TData, lifecycle?: Lifecycle): TStore;
+export declare function assign<TData extends { readonly [K in string]: any; }, const TKeys extends readonly (keyof TData & (string | number))[], TStore extends AtomsOf<TData, TKeys[number]>>(store: TStore, data: TData, keys: TKeys & (number extends TKeys["length"] ? never : unknown), lifecycle?: Lifecycle): TStore;
 //#endregion
 //#region src/jsx.d.ts
-declare function jsx(tagName: string, props: PropsType, key?: any): JsxResult;
-declare function jsx<TProps extends PropsType>(component: Component<TProps>, props: TProps, key?: any): JsxResult;
-declare function jsxs(tagName: string, props: PropsType, key?: any): JsxResult;
-declare function jsxs<TProps extends PropsType>(component: Component<TProps>, props: TProps, key?: any): JsxResult;
+export declare function jsx(tagName: string, props: PropsType, key?: any): JsxResult;
+export declare function jsx<TProps extends PropsType>(component: Component<TProps>, props: TProps, key?: any): JsxResult;
+export declare function jsxs(tagName: string, props: PropsType, key?: any): JsxResult;
+export declare function jsxs<TProps extends PropsType>(component: Component<TProps>, props: TProps, key?: any): JsxResult;
+//#endregion
+//#region src/RendererBuilder.d.ts
+interface RendererBuilder<TNode, TElements extends ElementsType, TUsedPrefixes extends string = never> {
+  create: () => Renderer<TNode, TElements>;
+  extend: <TPrefix extends string, TExtension extends Extension<TNode>>(prefix: TPrefix & (TPrefix extends TUsedPrefixes ? never : unknown), extension: TExtension) => RendererBuilder<TNode, ExtendedElements<TNode, TElements, TExtension, TPrefix>, TUsedPrefixes | TPrefix>;
+}
+type ExtendedElements<TNode, TElements extends ElementsType, TExtension extends Extension<TNode>, TPrefix extends string> = (TExtension extends {
+  readonly $mapping?: infer TMapping extends ExtensionPropMapping<unknown>;
+} ? { [TElementName in keyof TElements]: ((TMapping & {
+  node: NodeType<TElements[TElementName]>;
+  name: TElementName;
+})["extension"] extends (infer TExtensionProps extends PropsType) ? [keyof TExtensionProps] extends [never] ? TElements[TElementName] : Flatten<TElements[TElementName] & PrefixedProps<TExtensionProps, TPrefix>> : TElements[TElementName]); } : TElements);
+type PrefixedProps<TProps extends PropsType, TPrefix extends string> = { readonly [TPrefixed in `${TPrefix}:${keyof TProps & string}`]?: (TPrefixed extends `${TPrefix}:${infer TName extends (keyof TProps & string)}` ? TProps[TName] : never); };
+export declare function renderer<TNode, TElements extends ElementsType>(adapter: Adapter<TNode, TElements>): RendererBuilder<TNode, TElements, never>;
 //#endregion
-export { type Adapter, type Atom, ChangeKind, type Component, type Context, type DataTemplate, type Derivation, type EffectBlock, type ElementsOf, type ElementsType, type Equals, type Extension, type ExtensionProps, type ExtensionsType, Fragment, type FragmentProps, type HNode, Iterator, type JsxChildren, type JsxChildrenProp, type JsxObject, type JsxProps, type JsxResult, type JsxText, type Lifecycle, type List, type ListChange, type ListCleared, type ListDelta, type ListItemChanged, type ListItemInserted, type ListItemRemoved, type MaybeAtom, type MaybeReadAtom, type MountBlock, type MountingGroup, Native, type Nil, type NodeType, type PropsOf, type PropsType, type Proxied, type ProxyAtom, type ProxyIteratorProps, type PyxisBuilder, type ReadAtom, type ReadonlyList, RefExtension, type RefExtensionType, type RefFn, type RemountIteratorProps, type Renderer, type S_ATOM, type S_NODE_TYPE, Show, type ShowProps, type TickFn, type UnmountBlock, type WithChildren, atomOf, bind, component, consumerOf, createContext, derived, effect, fork, getLifecycle, host, insert, isAtom, jsx, jsxs, listOf, mount, mountJsx, mounted, noEffect, peek, peeks, proxyOf, pyxis, read, reads, sync, tick, tock, track, unmount, unmounted, untrack, update, withLifecycle, write };
+export type { Adapter, ArgsMax3, Atom, AtomsOf, Callback, Component, ComponentHandler, Context, DataTemplate, Dependency, DependencyList, Derivation, EffectBlock, ElemName, ElementsOf, ElementsType, Equals, Extension, ExtensionPropMapping, ExtensionsType, Flatten, FragmentProps, HNode, JsxChildren, JsxChildrenProp, JsxDevSourceInfo, JsxObject, JsxProps, JsxResult, JsxText, Lifecycle, List, ListChange, ListCleared, ListDelta, ListItemChanged, ListItemInserted, ListItemRemoved, MaybeAtom, MaybeWriteAtom, MountBlock, MountingGroup, Nil, NodeType, PropsOf, PropsType, Proxied, ProxyAtom, ProxyIteratorProps, ReadonlyList, RefFn, RemountIteratorProps, Renderer, RendererBuilder, S_ELEM_NAME, S_NODE_TYPE, ShowDataProps, ShowProps, ShowProxyDataProps, TickFn, UnmountBlock, ValueType, WithChildren, WriteAtom };
 //# sourceMappingURL=core.d.ts.map