nuclo 0.2.32 → 0.2.34

package/dist/update/reactive-text.d.ts

@@ -0,0 +1,38 @@
+import type { UpdateScope } from "./scope";
+import type { TextResolver } from "./registry";
+/**
+ * Creates a reactive text node that automatically updates when its resolver function changes.
+ *
+ * The text node will be registered for reactive updates and its content will be synchronized
+ * whenever notifyReactiveTextNodes() is called.
+ *
+ * @param resolver - Function that returns the text content (string, number, boolean, etc.)
+ * @param preEvaluated - Optional pre-evaluated value to avoid calling resolver immediately
+ * @returns A Text node that will reactively update its content
+ *
+ * @example
+ * ```ts
+ * const count = signal(0);
+ * const textNode = createReactiveTextNode(() => `Count: ${count.value}`);
+ * // Later, when count changes and notifyReactiveTextNodes() is called,
+ * // the text content automatically updates
+ * ```
+ */
+export declare function createReactiveTextNode(resolver: TextResolver, preEvaluated?: unknown, sanitize?: boolean): Text | DocumentFragment;
+/**
+ * Updates all registered reactive text nodes.
+ *
+ * Iterates through all reactive text nodes, re-evaluates their resolver functions,
+ * and updates their content if it has changed. Automatically cleans up disconnected nodes.
+ *
+ * This function should be called after state changes to synchronize the DOM with application state.
+ *
+ * @example
+ * ```ts
+ * // After updating application state
+ * count.value++;
+ * notifyReactiveTextNodes(); // All reactive text nodes update
+ * ```
+ */
+export declare function notifyReactiveTextNodes(scope?: UpdateScope): void;
+//# sourceMappingURL=reactive-text.d.ts.map

package/dist/update/reactive-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactive-text.d.ts","sourceRoot":"","sources":["../../src/update/reactive-text.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,YAAY,EAAE,YAAY,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,gBAAgB,CAgClI;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CA0CjE"}

package/dist/update/registry.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared types and registries for reactive nodes.
+ * Single source of truth — imported by reactiveText.ts and reactiveAttributes.ts.
+ *
+ * Registry structure: the iteration sets only hold WeakRefs; the actual info
+ * records live in WeakMaps keyed by the node. Info records may strongly
+ * reference the node (e.g. attribute applyValue closures capture the
+ * element), so storing them in a strongly-held map would pin the node in
+ * memory forever. With WeakMap storage the whole record is collectible as
+ * soon as the node is unreachable.
+ *
+ * Dead WeakRefs left in the iteration sets are pruned by the notify passes as
+ * they iterate (deref() === undefined, or node disconnected). Registration is
+ * the hottest path in list-heavy renders (one text node + often one element
+ * per row), so no per-node FinalizationRegistry is used here: its register()
+ * cost per row outweighs keeping the sets tidy between updates, and a stale
+ * husk is just an empty WeakRef until the next update() sweeps it.
+ */
+export type TextResolver = () => Primitive;
+export interface ReactiveTextNodeInfo {
+    resolver: TextResolver;
+    lastValue: string;
+    /**
+     * DSL semantics: nullish and non-primitive resolver results render as ""
+     * (instead of String(value)). Set by the tag-builder text path so it can
+     * register the user's resolver directly rather than allocating a
+     * sanitizing wrapper closure per text node.
+     */
+    sanitize?: boolean;
+}
+export type AttributeResolver = () => unknown;
+export interface AttributeResolverRecord {
+    key: string;
+    resolver: AttributeResolver;
+    applyValue: (value: unknown) => void;
+    lastValue: unknown;
+}
+export interface ReactiveElementInfo {
+    /**
+     * Flat keyed array rather than a Map: elements almost always carry one or
+     * two reactive attributes, so linear key lookup on registration beats a Map
+     * allocation per element, and the per-update flush iterates with a plain
+     * index loop (no iterator/destructuring allocations).
+     */
+    attributeResolvers: AttributeResolverRecord[];
+}
+/**
+ * Iteration set of weak references to reactive text nodes.
+ */
+export declare const reactiveTextNodes: Set<WeakRef<Text>>;
+/**
+ * WeakMap for O(1) lookups of reactive text node info by node reference.
+ */
+export declare const reactiveTextNodesByNode: WeakMap<Text, {
+    ref: WeakRef<Text>;
+    info: ReactiveTextNodeInfo;
+}>;
+/**
+ * Iteration set of weak references to reactive elements.
+ */
+export declare const reactiveElements: Set<WeakRef<Element>>;
+/**
+ * WeakMap for O(1) lookups of reactive element info by element reference.
+ */
+export declare const reactiveElementsByNode: WeakMap<Element, {
+    ref: WeakRef<Element>;
+    info: ReactiveElementInfo;
+}>;
+/**
+ * Registers a reactive text node in both lookup structures.
+ */
+export declare function registerReactiveTextNode(node: Text, info: ReactiveTextNodeInfo): void;
+/**
+ * Registers a reactive element in both lookup structures.
+ */
+export declare function registerReactiveElement(element: Element, info: ReactiveElementInfo): void;
+/**
+ * Removes a reactive text node's WeakRef entry from the iteration set.
+ */
+export declare function removeReactiveTextNodeRef(ref: WeakRef<Text>): void;
+/**
+ * Removes a reactive element's WeakRef entry from the iteration set.
+ */
+export declare function removeReactiveElementRef(ref: WeakRef<Element>): void;
+/**
+ * Manually removes reactive text node info for a specific text node.
+ * This should be called when a text node is removed from the DOM to prevent memory leaks.
+ */
+export declare function cleanupReactiveTextNode(node: Text): void;
+/**
+ * Manually removes reactive element info for a specific element.
+ * This should be called when an element is removed from the DOM to prevent memory leaks.
+ */
+export declare function cleanupReactiveElement(element: Element): void;
+export interface ConditionalInfo<TTagName extends ElementTagName = ElementTagName> {
+    condition: () => boolean;
+    tagName: TTagName;
+    modifiers: Array<NodeMod<TTagName> | NodeModFn<TTagName>>;
+    isSvg: boolean;
+}
+/**
+ * Attach conditional info to a node and register it.
+ */
+export declare function storeConditionalInfo<TTagName extends ElementTagName>(node: Node, info: ConditionalInfo<TTagName>): void;
+/**
+ * Explicit unregister helper (optional use on teardown if needed).
+ * O(1) via reverse lookup WeakMap.
+ */
+export declare function unregisterConditionalNode(node: Node): void;
+/**
+ * Returns an array of currently tracked conditional nodes that are still alive.
+ * Automatically cleans up garbage-collected nodes.
+ */
+export declare function getActiveConditionalNodes(): Node[];
+export declare function getConditionalInfo(node: Node): ConditionalInfo<ElementTagName> | null;
+//# sourceMappingURL=registry.d.ts.map

package/dist/update/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/update/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,SAAS,CAAC;AAE3C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,CAAC;AAE9C,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,kBAAkB,EAAE,uBAAuB,EAAE,CAAC;CAC/C;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,oBAA2B,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,uBAAuB;SAA4B,OAAO,CAAC,IAAI,CAAC;UAAQ,oBAAoB;EAAK,CAAC;AAE/G;;GAEG;AACH,eAAO,MAAM,gBAAgB,uBAA8B,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,sBAAsB;SAA+B,OAAO,CAAC,OAAO,CAAC;UAAQ,mBAAmB;EAAK,CAAC;AAEnH;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAYrF;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,mBAAmB,GAAG,IAAI,CASzF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAElE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAEpE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAMxD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAM7D;AAOD,MAAM,WAAW,eAAe,CAAC,QAAQ,SAAS,cAAc,GAAG,cAAc;IAChF,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,OAAO,EAAE,QAAQ,CAAC;IAClB,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC1D,KAAK,EAAE,OAAO,CAAC;CACf;AAyBD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,SAAS,cAAc,EACnE,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,eAAe,CAAC,QAAQ,CAAC,GAC7B,IAAI,CAON;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAQ1D;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,EAAE,CAalD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,eAAe,CAAC,cAAc,CAAC,GAAG,IAAI,CAErF"}

package/dist/update/scope.d.ts

@@ -0,0 +1,7 @@
+export interface UpdateScope {
+    roots: ReadonlyArray<Element>;
+    contains(node: Node): boolean;
+}
+export declare function getScopeRoots(ids: readonly string[]): Element[];
+export declare function scope<TTagName extends ElementTagName = ElementTagName>(...ids: string[]): NodeModFn<TTagName>;
+//# sourceMappingURL=scope.d.ts.map

package/dist/update/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/update/scope.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC;CAC/B;AAoCD,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,EAAE,CAoC/D;AAED,wBAAgB,KAAK,CAAC,QAAQ,SAAS,cAAc,GAAG,cAAc,EACpE,GAAG,GAAG,EAAE,MAAM,EAAE,GACf,SAAS,CAAC,QAAQ,CAAC,CAQrB"}

package/dist/update/update.d.ts

@@ -0,0 +1,4 @@
+import type { UpdateScope } from "./scope";
+export declare function update(...scopeIds: string[]): void;
+export declare function dispatchGlobalUpdateEvent(scope?: UpdateScope): void;
+//# sourceMappingURL=update.d.ts.map

package/dist/update/update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/update/update.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAY3C,wBAAgB,MAAM,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAiClD;AAED,wBAAgB,yBAAyB,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CAqBnE"}

package/dist/when/builder.d.ts

@@ -0,0 +1,16 @@
+import type { WhenCondition, WhenContent, WhenGroup } from "./runtime";
+declare class WhenBuilderImpl<TTagName extends ElementTagName = ElementTagName> {
+    private groups;
+    private elseContent;
+    constructor(initialCondition: WhenCondition, ...content: WhenContent<TTagName>[]);
+    cloneWith(additionalGroup?: WhenGroup<TTagName>, newElseContent?: WhenContent<TTagName>[]): WhenBuilderImpl<TTagName>;
+    when(condition: WhenCondition, ...content: WhenContent<TTagName>[]): WhenBuilderImpl<TTagName>;
+    else(...content: WhenContent<TTagName>[]): WhenBuilderImpl<TTagName>;
+    render(host: ExpandedElement<TTagName>, index: number): Node | null;
+    private freshRender;
+    private hydrateRender;
+    private createRuntimeFromMarkers;
+}
+export declare function createWhenBuilderFunction<TTagName extends ElementTagName>(builder: WhenBuilderImpl<TTagName>): WhenBuilder<TTagName>;
+export { WhenBuilderImpl };
+//# sourceMappingURL=builder.d.ts.map

package/dist/when/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/when/builder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAe,MAAM,WAAW,CAAC;AAyBpF,cAAM,eAAe,CAAC,QAAQ,SAAS,cAAc,GAAG,cAAc;IACpE,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,WAAW,CAA+B;IAElD,YAAY,gBAAgB,EAAE,aAAa,EAAE,GAAG,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,EAE/E;IAED,SAAS,CACP,eAAe,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,EACrC,cAAc,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,GACvC,eAAe,CAAC,QAAQ,CAAC,CAM3B;IAED,IAAI,CAAC,SAAS,EAAE,aAAa,EAAE,GAAG,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,GAAG,eAAe,CAAC,QAAQ,CAAC,CAG7F;IAED,IAAI,CAAC,GAAG,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,GAAG,eAAe,CAAC,QAAQ,CAAC,CAGnE;IAED,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAUlE;IAED,OAAO,CAAC,WAAW;IAgBnB,OAAO,CAAC,aAAa;IAgFrB,OAAO,CAAC,wBAAwB;CAwBjC;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,SAAS,cAAc,EACvE,OAAO,EAAE,eAAe,CAAC,QAAQ,CAAC,GACjC,WAAW,CAAC,QAAQ,CAAC,CAavB;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/when/index.d.ts

@@ -0,0 +1,44 @@
+import type { WhenCondition, WhenContent } from "./runtime";
+export { updateWhenRuntimes } from "./runtime";
+/**
+ * Creates a conditional rendering block (when/else logic).
+ *
+ * Renders different content based on boolean conditions, similar to if/else statements.
+ * Conditions can be static booleans or reactive functions that are re-evaluated on updates.
+ *
+ * @param condition - Boolean value or function returning a boolean
+ * @param content - Content to render when condition is true
+ * @returns A builder that allows chaining additional .when() or .else() branches
+ *
+ * @example
+ * ```ts
+ * const isLoggedIn = signal(false);
+ *
+ * div(
+ *   when(() => isLoggedIn.value,
+ *     span('Welcome back!')
+ *   )
+ *   .else(
+ *     button('Login', on('click', () => login()))
+ *   )
+ * )
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Multiple conditions
+ * div(
+ *   when(() => status.value === 'loading',
+ *     spinner()
+ *   )
+ *   .when(() => status.value === 'error',
+ *     errorMessage()
+ *   )
+ *   .else(
+ *     contentView()
+ *   )
+ * )
+ * ```
+ */
+export declare function when<TTagName extends ElementTagName = ElementTagName>(condition: WhenCondition, ...content: WhenContent<TTagName>[]): WhenBuilder<TTagName>;
+//# sourceMappingURL=index.d.ts.map

package/dist/when/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/when/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,IAAI,CAAC,QAAQ,SAAS,cAAc,GAAG,cAAc,EACnE,SAAS,EAAE,aAAa,EACxB,GAAG,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,GAClC,WAAW,CAAC,QAAQ,CAAC,CAGvB"}

package/dist/when/runtime.d.ts

@@ -0,0 +1,59 @@
+import type { UpdateScope } from "../update/scope";
+export type WhenCondition = boolean | (() => boolean);
+export type WhenContent<TTagName extends ElementTagName = ElementTagName> = NodeModLike<TTagName>;
+export interface WhenGroup<TTagName extends ElementTagName = ElementTagName> {
+    condition: WhenCondition;
+    content: WhenContent<TTagName>[];
+}
+export interface WhenRuntime<TTagName extends ElementTagName = ElementTagName> {
+    startMarker: Comment;
+    endMarker: Comment;
+    host: ExpandedElement<TTagName>;
+    index: number;
+    groups: WhenGroup<TTagName>[];
+    elseContent: WhenContent<TTagName>[];
+    /**
+     * Tracks which branch is currently rendered:
+     *  - null:  nothing rendered yet (initial state)
+     *  - -1:    else branch is active
+     *  - >= 0:  groups[activeIndex] is active
+     */
+    activeIndex: number | null;
+    update(): void;
+}
+/**
+ * Evaluates which condition branch should be active.
+ * Returns the index of the first truthy condition, -1 for else branch, or null for no match.
+ */
+export declare function evaluateActiveCondition<TTagName extends ElementTagName>(groups: ReadonlyArray<WhenGroup<TTagName>>, elseContent: ReadonlyArray<WhenContent<TTagName>>): number | null;
+/**
+ * Main render function for when/else conditionals.
+ * Evaluates conditions, clears old content, and renders the active branch.
+ */
+export declare function renderWhenContent<TTagName extends ElementTagName>(runtime: WhenRuntime<TTagName>): void;
+/**
+ * Registers a when runtime for tracking and updates.
+ * Uses WeakRef to prevent memory leaks when elements are removed.
+ * The runtime object itself is mutable and will be updated in place.
+ */
+export declare function registerWhenRuntime<TTagName extends ElementTagName>(runtime: WhenRuntime<TTagName>): void;
+/**
+ * Updates all active when/else conditional runtimes.
+ *
+ * Re-evaluates all conditional branches and re-renders if the active branch has changed.
+ * Automatically cleans up runtimes that are garbage collected or disconnected from DOM.
+ *
+ * This function should be called after state changes that affect conditional expressions.
+ *
+ * @example
+ * ```ts
+ * isLoggedIn.value = true;
+ * updateWhenRuntimes(); // All when() conditionals re-evaluate
+ * ```
+ */
+export declare function updateWhenRuntimes(scope?: UpdateScope): void;
+/**
+ * Renders a list of content items and collects the resulting nodes.
+ */
+export declare function renderContentItems<TTagName extends ElementTagName>(items: ReadonlyArray<WhenContent<TTagName>>, host: ExpandedElement<TTagName>, index: number, endMarker: Comment): Node[];
+//# sourceMappingURL=runtime.d.ts.map

package/dist/when/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/when/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;AACtD,MAAM,MAAM,WAAW,CAAC,QAAQ,SAAS,cAAc,GAAG,cAAc,IACtE,WAAW,CAAC,QAAQ,CAAC,CAAC;AAExB,MAAM,WAAW,SAAS,CAAC,QAAQ,SAAS,cAAc,GAAG,cAAc;IACzE,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,WAAW,CAAC,QAAQ,SAAS,cAAc,GAAG,cAAc;IAC3E,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC9B,WAAW,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;IACrC;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,IAAI,IAAI,CAAC;CAChB;AAmBD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,SAAS,cAAc,EACrE,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,EAC1C,WAAW,EAAE,aAAa,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,GAChD,MAAM,GAAG,IAAI,CAOf;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,SAAS,cAAc,EAC/D,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,GAC7B,IAAI,CAoBN;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,SAAS,cAAc,EACjE,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,GAC7B,IAAI,CAKN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CA0C5D;AA8BD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,SAAS,cAAc,EAChE,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,EAC3C,IAAI,EAAE,eAAe,CAAC,QAAQ,CAAC,EAC/B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,GACjB,IAAI,EAAE,CASR"}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "nuclo",
 	"private": false,
-	"version": "0.2.32",
+	"version": "0.2.34",
 	"description": "Lightweight, type-safe DOM library with plain mutable state and explicit updates — global tag builders, SSR, hydration, and typed CSS, no virtual DOM, no compiler.",
 	"license": "MIT",
 	"author": "Danilo Celestino de Castro (https://github.com/dan2dev)",
@@ -62,20 +62,20 @@
 		"lint:fix": "eslint . --ext .ts,.js,.json,.jsonc,.json5,.md,.css --fix"
 	},
 	"devDependencies": {
-		"@eslint/css": "^1.4.0",
+		"@eslint/css": "^2.0.0",
 		"@eslint/js": "^10.0.1",
-		"@eslint/json": "^2.0.1",
+		"@eslint/json": "^2.1.0",
 		"@eslint/markdown": "^8.0.3",
-		"@types/node": "^26.2.0",
-		"@vitest/coverage-v8": "4.1.11",
-		"eslint": "^10.9.0",
-		"globals": "^17.11.0",
+		"@types/node": "^26.6.2",
+		"@vitest/coverage-v8": "5.0.0",
+		"eslint": "^10.11.0",
+		"globals": "^17.12.0",
 		"jiti": "^2.7.0",
-		"jsdom": "^30.0.1",
-		"tsdown": "^0.22.14",
+		"jsdom": "^30.1.0",
+		"tsdown": "^0.23.0",
 		"typescript": "^7.0.2",
-		"typescript-eslint": "^8.67.0",
-		"vitest": "^4.1.11"
+		"typescript-eslint": "^8.70.0",
+		"vitest": "^5.0.1"
 	},
 	"repository": {
 		"type": "git",

package/types/core/base.d.ts

@@ -1,4 +1,5 @@
 import "./events";
+import "./lifecycle";
 
 declare const anyParentNodeModifierTag: unique symbol;
 
@@ -13,6 +14,16 @@ type LowercaseEventAttributes<TTagName extends ElementTagName> = {
   [K in Extract<keyof HTMLElementTagNameMap[TTagName], `on${string}`>]?: never;
 };
 
+/**
+ * `onMount` / `onDestroy` attributes — not real DOM events (no native
+ * `on${string}` IDL property exists for them), so they're typed here rather
+ * than derived from HTMLElementEventAttributeNameMap. See src/element/lifecycle.ts.
+ */
+type LifecycleElementAttributes<TTagName extends ElementTagName> = {
+  onMount?: MountCallback<HTMLElementTagNameMap[TTagName]>;
+  onDestroy?: DestroyCallback<HTMLElementTagNameMap[TTagName]>;
+};
+
 declare global {
   export type Primitive = string | number | bigint | boolean | symbol | null | undefined;
   export type ElementTagName = keyof HTMLElementTagNameMap;
@@ -43,6 +54,7 @@ declare global {
   > = NativeElementAttributes<TTagName>
     & CamelCaseEventAttributes<TTagName>
     & LowercaseEventAttributes<TTagName>
+    & LifecycleElementAttributes<TTagName>
     & {
       // Allow custom attributes (data-*, aria-*, etc.)
       [key: string]: ValueOrFactory<unknown>;

package/types/core/lifecycle.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Mount/destroy lifecycle hook types.
+ *
+ * Two equivalent ways to register them (both typed from these two aliases):
+ *   - `on("mount", cb)` / `on("destroy", cb)`            (types/features/on.d.ts)
+ *   - `{ onMount: cb }` / `{ onDestroy: cb }` attributes  (LifecycleElementAttributes below)
+ *
+ * See src/element/lifecycle.ts for exactly when each callback fires.
+ */
+
+declare global {
+  /** Cleanup returned by a mount callback, run once the element is destroyed. */
+  export type MountCleanup = () => void;
+
+  /**
+   * Called once, after the element has been created and connected to the
+   * live document. May return a cleanup function — equivalent to also
+   * registering it with `on("destroy", ...)` / `{ onDestroy }`.
+   */
+  export type MountCallback<TElement extends Element = HTMLElement> =
+    (element: TElement) => void | MountCleanup;
+
+  /** Called once the element has been removed. */
+  export type DestroyCallback<TElement extends Element = HTMLElement> =
+    (element: TElement) => void;
+}
+
+export {};

package/types/features/on.d.ts

@@ -10,9 +10,12 @@
  *     })
  *   );
  *
- * Overloads:
+ * Overloads (order matters — TS resolves the first structural match, and the
+ * "mount"/"destroy" and custom-event overloads all accept `string`, so the
+ * more specific ones must come first):
  * 1. DOM standard events (strongly typed via the tag's native event map)
- * 2. Custom / arbitrary event names with user-specified event type
+ * 2. "mount" / "destroy" lifecycle pseudo-events (not real DOM events)
+ * 3. Custom / arbitrary event names with user-specified event type
  */
 
 declare global {
@@ -37,6 +40,28 @@ declare global {
     options?: boolean | AddEventListenerOptions
   ): NodeModFn<TTagName>;
 
+  /**
+   * Fires once, after the element has been created and connected to the live
+   * document. Equivalent to `{ onMount: ... }`. May return a cleanup function
+   * — equivalent to also registering it with `on("destroy", ...)`.
+   *
+   * See src/element/lifecycle.ts for exactly when "connected" is guaranteed.
+   */
+  function on<TTagName extends ElementTagName = ElementTagName>(
+    type: "mount",
+    listener: MountCallback<HTMLElementTagNameMap[TTagName]>,
+  ): NodeModFn<TTagName>;
+
+  /**
+   * Fires once the element has been removed. Equivalent to `{ onDestroy: ... }`.
+   *
+   * See src/element/lifecycle.ts for exactly when this is guaranteed to run.
+   */
+  function on<TTagName extends ElementTagName = ElementTagName>(
+    type: "destroy",
+    listener: DestroyCallback<HTMLElementTagNameMap[TTagName]>,
+  ): NodeModFn<TTagName>;
+
   /**
    * Add a custom / arbitrary event listener (e.g. "my-event").
    *

package/types/index.d.ts

@@ -85,6 +85,14 @@ export function on<
   >,
   options?: boolean | AddEventListenerOptions
 ): NodeModFn<TTagName>;
+export function on<TTagName extends ElementTagName = ElementTagName>(
+  type: "mount",
+  listener: MountCallback<HTMLElementTagNameMap[TTagName]>,
+): NodeModFn<TTagName>;
+export function on<TTagName extends ElementTagName = ElementTagName>(
+  type: "destroy",
+  listener: DestroyCallback<HTMLElementTagNameMap[TTagName]>,
+): NodeModFn<TTagName>;
 export function on<K extends string, E extends Event = Event, TTagName extends ElementTagName = ElementTagName>(
   type: K,
   listener: TypedEventListener<HTMLElementTagNameMap[TTagName], E>,