@ai-matrx/summon 0.0.0-stage → 0.1.0

package/dist/handles.d.cts

@@ -0,0 +1,166 @@
+type CallbackContext = Record<string, unknown>;
+interface ProgressInfo {
+    progress?: number;
+    status?: "pending" | "running" | "completed" | "error";
+    error?: Error;
+}
+type Callback<T = unknown, C extends CallbackContext = CallbackContext> = (data: T, context?: C) => void | Promise<void>;
+/** What an entry's slot holds: a callback, or an object handle retrieved with `get`. */
+type HandleSlot = Callback<never, never> | object;
+interface RegisterOptions<C extends CallbackContext = CallbackContext> {
+    context?: C;
+    groupId?: string;
+    /** The InstanceKey (`overlayId:instanceId`) that owns this entry; disposed when it closes. */
+    owner?: string;
+}
+interface TriggerOptions<C extends CallbackContext = CallbackContext> {
+    context?: C;
+    progress?: ProgressInfo;
+    removeAfterTrigger?: boolean;
+}
+declare const HANDLES_SLOT = "ai-matrx.summon.handles";
+/** Internal registration options beyond the public ones (used by the typed helpers). */
+interface InternalRegisterOptions extends RegisterOptions {
+    id?: string;
+    onRemove?: () => void;
+}
+declare class CallbackManager {
+    private get s();
+    /**
+     * Observe the registry itself: `listener` runs after any entry is added or removed. This lets a
+     * view that resolves ids with `get` re-render when an id goes away (`useSyncExternalStore`).
+     */
+    subscribeToRegistry(listener: () => void): () => void;
+    private notifyRegistry;
+    /** Register a callback; returns its id. */
+    register<T>(callback: Callback<T>): string;
+    /** Register with optional context, group and owner. */
+    registerWithContext<T, C extends CallbackContext = CallbackContext>(callback: Callback<T, C>, options?: RegisterOptions<C>): string;
+    /** @internal The one insertion path (typed helpers pass a fixed id and a removal hook). */
+    registerEntry(slot: HandleSlot, options: InternalRegisterOptions): string;
+    /** Subscribe to results for a callback id. */
+    subscribe<T, C extends CallbackContext = CallbackContext>(callbackId: string, listener: Callback<T, C>): boolean;
+    /** Unsubscribe a listener from a callback id. */
+    unsubscribe<T, C extends CallbackContext = CallbackContext>(callbackId: string, listener: Callback<T, C>): boolean;
+    /** Run a callback once, notify its listeners, then remove it. */
+    trigger<T>(callbackId: string, data: T): void;
+    /** Trigger with merged context and progress; removes unless `removeAfterTrigger: false`. */
+    triggerWithContext<T, C extends CallbackContext = CallbackContext>(callbackId: string, data: T, options?: TriggerOptions<C>): void;
+    /** Trigger every callback in a group. */
+    triggerGroup<T, C extends CallbackContext = CallbackContext>(groupId: string, data: T, options?: TriggerOptions<C>): void;
+    /**
+     * Run the one durable command registered for a group. A command is retained on rejection so its
+     * caller can retry, and is removed only after its promise settles successfully.
+     */
+    triggerGroupCommand<T, C extends CallbackContext = CallbackContext>(groupId: string, data: T, options?: {
+        context?: C;
+        removeAfterSuccess?: boolean;
+    }): Promise<void>;
+    /** Report progress to a callback (or every callback of a group) without removing it. */
+    updateProgress(id: string, progress: number, options?: {
+        status?: ProgressInfo["status"];
+        error?: Error;
+        groupId?: boolean;
+    }): void;
+    /** Create a new, empty group and return its id. */
+    createGroup(): string;
+    /** Remove one entry (and its group/owner membership). */
+    remove(callbackId: string): void;
+    /** Alias of `remove` — the preferred name when unregistering a handle on unmount. */
+    unregister(callbackId: string): void;
+    /** The stored callback or object handle for an id, without invoking it. */
+    get<T = unknown>(callbackId: string): T | undefined;
+    /** True when the id is registered. */
+    has(callbackId: string): boolean;
+    /**
+     * Register an object handle (a widget handle, an editor API, …). The object occupies the slot;
+     * it is never invoked by `trigger`, only retrieved with `get`.
+     */
+    registerWidgetHandle<H extends object>(handle: H, options?: {
+        owner?: string;
+    }): string;
+    /** Remove a group and all its callbacks. */
+    removeGroup(groupId: string): void;
+    /** Remove everything registered with `owner` (an InstanceKey). Returns how many were removed. */
+    disposeOwner(owner: string): number;
+    /** Ids currently owned by `owner`. */
+    ownedBy(owner: string): readonly string[];
+    /** The member ids of a group (empty when unknown). */
+    groupMembers(groupId: string): readonly string[];
+    /** Total registered entries (diagnostics, leak tests). */
+    size(): number;
+    /**
+     * The one removal path. Reads the entry BEFORE deleting it so group and owner membership shrink
+     * (the old `removeFromGroups`-after-delete bug), then runs the entry's removal hook.
+     */
+    private deleteEntry;
+}
+/** The process-wide handles registry (state in the global slot; every instance shares it). */
+declare const callbackManager: CallbackManager;
+/** Remove everything owned by an open instance (`overlayId:instanceId`). */
+declare function disposeOwner(owner: string): number;
+
+interface OwnerOption {
+    /** The InstanceKey (`overlayId:instanceId`) that owns this handle; disposed when it closes. */
+    owner?: string;
+}
+/** Thrown into a request's promise when it is disposed before being answered. */
+declare class HandleDisposedError extends Error {
+    readonly handleId: string;
+    constructor(handleId: string, message?: string);
+}
+/**
+ * Register an imperative object handle under a caller-chosen id (an editor API, a widget handle,
+ * a ref's methods). Re-registering an id replaces the previous handle. Returns a disposer that
+ * removes the handle only if it is still the one registered (safe for React effect cleanup).
+ */
+declare function registerHandle<T extends object>(id: string, handle: T, options?: OwnerOption): () => void;
+/** The object handle registered under `id`, or undefined. */
+declare function getHandle<T extends object>(id: string): T | undefined;
+/** Remove the handle registered under `id`. */
+declare function removeHandle(id: string): void;
+interface EventChannel<Events> {
+    readonly id: string;
+    /** Deliver an event to every subscriber (no-op after dispose). */
+    emit(event: Events): void;
+    /** Listen; returns the unsubscribe. */
+    subscribe(listener: (event: Events) => void): () => void;
+    /** Remove the channel and drop every subscriber. */
+    dispose(): void;
+    readonly disposed: boolean;
+}
+/**
+ * A many-shot event stream between an opener and an overlay. Pass `channel.id` in open data; the
+ * overlay resolves it with `getEventChannel(id)`.
+ */
+declare function createEventChannel<Events>(options?: OwnerOption): EventChannel<Events>;
+/** The channel registered under `id`, or undefined once disposed. */
+declare function getEventChannel<Events>(id: string): EventChannel<Events> | undefined;
+interface PendingRequest<Req, Res> {
+    readonly id: string;
+    /** What the asker sent. */
+    readonly request: Req;
+    /** Answer the request (first answer wins; later calls are ignored). */
+    resolve(response: Res): void;
+    /** Fail the request. */
+    reject(reason: unknown): void;
+    readonly settled: boolean;
+}
+interface RequestHandle<Req, Res> extends PendingRequest<Req, Res> {
+    /** Settles with the answer; rejects with `HandleDisposedError` when disposed unanswered. */
+    readonly promise: Promise<Res>;
+    /** Remove the request; an unanswered one rejects. */
+    dispose(): void;
+}
+/**
+ * A one-shot promise bridge: the asker awaits `promise`, the overlay answers through
+ * `getRequest(id).resolve(…)`. Disposing it unanswered (or closing its owner) rejects.
+ */
+declare function createRequest<Req, Res>(request: Req, options?: OwnerOption): RequestHandle<Req, Res>;
+/** The pending request registered under `id`, or undefined once answered or disposed. */
+declare function getRequest<Req, Res>(id: string): PendingRequest<Req, Res> | undefined;
+
+/** A fresh handle id: `crypto.randomUUID` when present, else a v4 UUID from `getRandomValues`. */
+declare function newHandleId(): string;
+
+export { type Callback, type CallbackContext, CallbackManager, type EventChannel, HANDLES_SLOT, HandleDisposedError, type HandleSlot, type OwnerOption, type PendingRequest, type ProgressInfo, type RegisterOptions, type RequestHandle, type TriggerOptions, callbackManager, createEventChannel, createRequest, disposeOwner, getEventChannel, getHandle, getRequest, newHandleId, registerHandle, removeHandle };

package/dist/handles.d.ts

@@ -0,0 +1,166 @@
+type CallbackContext = Record<string, unknown>;
+interface ProgressInfo {
+    progress?: number;
+    status?: "pending" | "running" | "completed" | "error";
+    error?: Error;
+}
+type Callback<T = unknown, C extends CallbackContext = CallbackContext> = (data: T, context?: C) => void | Promise<void>;
+/** What an entry's slot holds: a callback, or an object handle retrieved with `get`. */
+type HandleSlot = Callback<never, never> | object;
+interface RegisterOptions<C extends CallbackContext = CallbackContext> {
+    context?: C;
+    groupId?: string;
+    /** The InstanceKey (`overlayId:instanceId`) that owns this entry; disposed when it closes. */
+    owner?: string;
+}
+interface TriggerOptions<C extends CallbackContext = CallbackContext> {
+    context?: C;
+    progress?: ProgressInfo;
+    removeAfterTrigger?: boolean;
+}
+declare const HANDLES_SLOT = "ai-matrx.summon.handles";
+/** Internal registration options beyond the public ones (used by the typed helpers). */
+interface InternalRegisterOptions extends RegisterOptions {
+    id?: string;
+    onRemove?: () => void;
+}
+declare class CallbackManager {
+    private get s();
+    /**
+     * Observe the registry itself: `listener` runs after any entry is added or removed. This lets a
+     * view that resolves ids with `get` re-render when an id goes away (`useSyncExternalStore`).
+     */
+    subscribeToRegistry(listener: () => void): () => void;
+    private notifyRegistry;
+    /** Register a callback; returns its id. */
+    register<T>(callback: Callback<T>): string;
+    /** Register with optional context, group and owner. */
+    registerWithContext<T, C extends CallbackContext = CallbackContext>(callback: Callback<T, C>, options?: RegisterOptions<C>): string;
+    /** @internal The one insertion path (typed helpers pass a fixed id and a removal hook). */
+    registerEntry(slot: HandleSlot, options: InternalRegisterOptions): string;
+    /** Subscribe to results for a callback id. */
+    subscribe<T, C extends CallbackContext = CallbackContext>(callbackId: string, listener: Callback<T, C>): boolean;
+    /** Unsubscribe a listener from a callback id. */
+    unsubscribe<T, C extends CallbackContext = CallbackContext>(callbackId: string, listener: Callback<T, C>): boolean;
+    /** Run a callback once, notify its listeners, then remove it. */
+    trigger<T>(callbackId: string, data: T): void;
+    /** Trigger with merged context and progress; removes unless `removeAfterTrigger: false`. */
+    triggerWithContext<T, C extends CallbackContext = CallbackContext>(callbackId: string, data: T, options?: TriggerOptions<C>): void;
+    /** Trigger every callback in a group. */
+    triggerGroup<T, C extends CallbackContext = CallbackContext>(groupId: string, data: T, options?: TriggerOptions<C>): void;
+    /**
+     * Run the one durable command registered for a group. A command is retained on rejection so its
+     * caller can retry, and is removed only after its promise settles successfully.
+     */
+    triggerGroupCommand<T, C extends CallbackContext = CallbackContext>(groupId: string, data: T, options?: {
+        context?: C;
+        removeAfterSuccess?: boolean;
+    }): Promise<void>;
+    /** Report progress to a callback (or every callback of a group) without removing it. */
+    updateProgress(id: string, progress: number, options?: {
+        status?: ProgressInfo["status"];
+        error?: Error;
+        groupId?: boolean;
+    }): void;
+    /** Create a new, empty group and return its id. */
+    createGroup(): string;
+    /** Remove one entry (and its group/owner membership). */
+    remove(callbackId: string): void;
+    /** Alias of `remove` — the preferred name when unregistering a handle on unmount. */
+    unregister(callbackId: string): void;
+    /** The stored callback or object handle for an id, without invoking it. */
+    get<T = unknown>(callbackId: string): T | undefined;
+    /** True when the id is registered. */
+    has(callbackId: string): boolean;
+    /**
+     * Register an object handle (a widget handle, an editor API, …). The object occupies the slot;
+     * it is never invoked by `trigger`, only retrieved with `get`.
+     */
+    registerWidgetHandle<H extends object>(handle: H, options?: {
+        owner?: string;
+    }): string;
+    /** Remove a group and all its callbacks. */
+    removeGroup(groupId: string): void;
+    /** Remove everything registered with `owner` (an InstanceKey). Returns how many were removed. */
+    disposeOwner(owner: string): number;
+    /** Ids currently owned by `owner`. */
+    ownedBy(owner: string): readonly string[];
+    /** The member ids of a group (empty when unknown). */
+    groupMembers(groupId: string): readonly string[];
+    /** Total registered entries (diagnostics, leak tests). */
+    size(): number;
+    /**
+     * The one removal path. Reads the entry BEFORE deleting it so group and owner membership shrink
+     * (the old `removeFromGroups`-after-delete bug), then runs the entry's removal hook.
+     */
+    private deleteEntry;
+}
+/** The process-wide handles registry (state in the global slot; every instance shares it). */
+declare const callbackManager: CallbackManager;
+/** Remove everything owned by an open instance (`overlayId:instanceId`). */
+declare function disposeOwner(owner: string): number;
+
+interface OwnerOption {
+    /** The InstanceKey (`overlayId:instanceId`) that owns this handle; disposed when it closes. */
+    owner?: string;
+}
+/** Thrown into a request's promise when it is disposed before being answered. */
+declare class HandleDisposedError extends Error {
+    readonly handleId: string;
+    constructor(handleId: string, message?: string);
+}
+/**
+ * Register an imperative object handle under a caller-chosen id (an editor API, a widget handle,
+ * a ref's methods). Re-registering an id replaces the previous handle. Returns a disposer that
+ * removes the handle only if it is still the one registered (safe for React effect cleanup).
+ */
+declare function registerHandle<T extends object>(id: string, handle: T, options?: OwnerOption): () => void;
+/** The object handle registered under `id`, or undefined. */
+declare function getHandle<T extends object>(id: string): T | undefined;
+/** Remove the handle registered under `id`. */
+declare function removeHandle(id: string): void;
+interface EventChannel<Events> {
+    readonly id: string;
+    /** Deliver an event to every subscriber (no-op after dispose). */
+    emit(event: Events): void;
+    /** Listen; returns the unsubscribe. */
+    subscribe(listener: (event: Events) => void): () => void;
+    /** Remove the channel and drop every subscriber. */
+    dispose(): void;
+    readonly disposed: boolean;
+}
+/**
+ * A many-shot event stream between an opener and an overlay. Pass `channel.id` in open data; the
+ * overlay resolves it with `getEventChannel(id)`.
+ */
+declare function createEventChannel<Events>(options?: OwnerOption): EventChannel<Events>;
+/** The channel registered under `id`, or undefined once disposed. */
+declare function getEventChannel<Events>(id: string): EventChannel<Events> | undefined;
+interface PendingRequest<Req, Res> {
+    readonly id: string;
+    /** What the asker sent. */
+    readonly request: Req;
+    /** Answer the request (first answer wins; later calls are ignored). */
+    resolve(response: Res): void;
+    /** Fail the request. */
+    reject(reason: unknown): void;
+    readonly settled: boolean;
+}
+interface RequestHandle<Req, Res> extends PendingRequest<Req, Res> {
+    /** Settles with the answer; rejects with `HandleDisposedError` when disposed unanswered. */
+    readonly promise: Promise<Res>;
+    /** Remove the request; an unanswered one rejects. */
+    dispose(): void;
+}
+/**
+ * A one-shot promise bridge: the asker awaits `promise`, the overlay answers through
+ * `getRequest(id).resolve(…)`. Disposing it unanswered (or closing its owner) rejects.
+ */
+declare function createRequest<Req, Res>(request: Req, options?: OwnerOption): RequestHandle<Req, Res>;
+/** The pending request registered under `id`, or undefined once answered or disposed. */
+declare function getRequest<Req, Res>(id: string): PendingRequest<Req, Res> | undefined;
+
+/** A fresh handle id: `crypto.randomUUID` when present, else a v4 UUID from `getRandomValues`. */
+declare function newHandleId(): string;
+
+export { type Callback, type CallbackContext, CallbackManager, type EventChannel, HANDLES_SLOT, HandleDisposedError, type HandleSlot, type OwnerOption, type PendingRequest, type ProgressInfo, type RegisterOptions, type RequestHandle, type TriggerOptions, callbackManager, createEventChannel, createRequest, disposeOwner, getEventChannel, getHandle, getRequest, newHandleId, registerHandle, removeHandle };