octane 0.1.32 → 0.1.34

package/README.md

@@ -21,6 +21,12 @@ Direct Node or Bun server scripts can preload `octane/compiler/register` to
 compile imported Octane components without going through Vite. See the
 [SSR guide](https://github.com/octanejs/octane/blob/main/docs/ssr.md#run-an-ssg-script-directly).
 
+Applications that stream or update their own server-rendered DOM can import
+`attachBehaviorRoot` from `octane/behavior`. Behavior-only roots attach native
+interactions and disposable behavior without creating a component root or
+taking ownership of the existing markup. See the
+[external ownership guide](https://github.com/octanejs/octane/blob/main/docs/deferred-hydration.md#behavior-only-roots-and-external-ownership).
+
 For the full story, see the
 [main README](https://github.com/octanejs/octane#readme).
 

package/dist/behavior-root.d.ts

@@ -0,0 +1,70 @@
+/** A behavior-only root observes existing DOM without taking reconciliation ownership. */
+export interface BehaviorRootOptions {
+    /** Dispose this root when the enclosing page or document lifetime ends. */
+    signal?: AbortSignal;
+    /** Explicitly dispose an existing behavior root attached to this container. */
+    replace?: boolean;
+}
+export interface BehaviorDisposeOptions {
+    /** Existing DOM is retained unless its removal is explicitly requested. */
+    preserveDOM?: boolean;
+}
+export interface ExternalRangeOptions {
+    /** Identity of the component, stream, or application owning this subtree. */
+    owner: unknown;
+    /** Delay adoption until the independently owned stream is ready. */
+    ready?: PromiseLike<unknown>;
+    signal?: AbortSignal;
+    /** Explicitly hand the same subtree from its previous owner to this owner. */
+    replace?: boolean;
+}
+export interface ExternalRange {
+    readonly element: Element;
+    readonly owner: unknown;
+    readonly signal: AbortSignal;
+    readonly ready: Promise<void>;
+    dispose(): void;
+}
+export interface BehaviorContext {
+    /** Per-element lifetime, canceled when its adoption or registration ends. */
+    readonly signal: AbortSignal;
+    /** The original native interaction when adoption was started by that event. */
+    readonly event?: Event;
+    /** The closest externally owned range, if this target belongs to one. */
+    readonly range?: ExternalRange;
+}
+export type BehaviorCleanup = () => void;
+export interface BehaviorEntry {
+    id?: string;
+    target: string | Element;
+    /** Restrict adoption to the closest range belonging to this exact owner. */
+    owner?: unknown;
+    events?: readonly string[];
+    ready?: PromiseLike<unknown>;
+    dependencies?: readonly string[];
+    conflicts?: readonly string[];
+    signal?: AbortSignal;
+    adopt(element: Element, context: BehaviorContext): void | BehaviorCleanup | PromiseLike<void | BehaviorCleanup>;
+    handleEvent?(event: Event, element: Element, context: BehaviorContext): void;
+}
+export interface BehaviorRegistration {
+    readonly id?: string;
+    readonly signal: AbortSignal;
+    readonly ready: Promise<void>;
+    dispose(): void;
+}
+export interface BehaviorRoot {
+    readonly container: Element;
+    readonly signal: AbortSignal;
+    /** A snapshot of currently active ranges, registrations, and asynchronous adoptions. */
+    readonly ready: Promise<void>;
+    registerExternalRange(element: Element, options: ExternalRangeOptions): ExternalRange;
+    registerBehavior(entry: BehaviorEntry): BehaviorRegistration;
+    dispose(options?: BehaviorDisposeOptions): void;
+}
+/**
+ * Attach behavior to existing DOM without rendering, replacing, or reconciling it.
+ * Every owner, observer, listener, and constructor is scoped to the container's
+ * own Document, including elements imported from another JavaScript realm.
+ */
+export declare function attachBehaviorRoot(container: Element, options?: BehaviorRootOptions): BehaviorRoot;