@agentick/core 0.0.1

package/dist/hooks/runtime-context.d.ts

@@ -0,0 +1,122 @@
+/**
+ * V2 Runtime Context
+ *
+ * Holds per-session state that hooks need access to.
+ * This is what makes each FiberCompiler/Session isolated.
+ */
+import React, { type ReactNode } from "react";
+import type { CompiledStructure } from "../compiler/types";
+import type { TickStartCallback, TickEndCallback, AfterCompileCallback, TickResult, TickState } from "./types";
+import type { COM } from "../com/object-model";
+export interface CacheEntry {
+    value: unknown;
+    tick: number;
+    deps?: unknown[];
+}
+export interface SerializableCacheEntry {
+    value: unknown;
+    tick: number;
+    deps?: unknown[];
+}
+/**
+ * Registration for a single knob in the runtime store.
+ * Stores primitive info + constraints — the resolved value is internal to useKnob.
+ */
+export interface KnobRegistration {
+    name: string;
+    description: string;
+    getPrimitive: () => string | number | boolean;
+    setPrimitive: (value: string | number | boolean) => void;
+    defaultValue: string | number | boolean;
+    options?: (string | number | boolean)[];
+    valueType: "string" | "number" | "boolean";
+    group?: string;
+    required?: boolean;
+    validate?: (value: any) => true | string;
+    min?: number;
+    max?: number;
+    step?: number;
+    maxLength?: number;
+    pattern?: string;
+}
+/**
+ * Per-session runtime state.
+ * Each FiberCompiler creates one of these.
+ */
+export interface RuntimeStore {
+    /** Data cache for useData */
+    dataCache: Map<string, CacheEntry>;
+    /** Pending data fetches */
+    pendingFetches: Map<string, Promise<unknown>>;
+    /** Lifecycle callbacks */
+    tickStartCallbacks: Set<TickStartCallback>;
+    tickEndCallbacks: Set<TickEndCallback>;
+    afterCompileCallbacks: Set<AfterCompileCallback>;
+    /** Knob registry — all active knobs registered by useKnob */
+    knobRegistry: Map<string, KnobRegistration>;
+}
+/**
+ * Create a new runtime store.
+ */
+export declare function createRuntimeStore(): RuntimeStore;
+/**
+ * Get the runtime store from context.
+ */
+export declare function useRuntimeStore(): RuntimeStore;
+/**
+ * Provider for runtime context.
+ */
+export declare function RuntimeProvider({ store, children, }: {
+    store: RuntimeStore;
+    children?: ReactNode;
+}): React.ReactElement;
+/**
+ * Check if store has pending data fetches.
+ */
+export declare function storeHasPendingData(store: RuntimeStore): boolean;
+/**
+ * Wait for all pending data fetches in store.
+ */
+export declare function storeResolvePendingData(store: RuntimeStore): Promise<void>;
+/**
+ * Run tick start callbacks with TickState and COM.
+ */
+export declare function storeRunTickStartCallbacks(store: RuntimeStore, tickState: TickState, ctx: COM): Promise<void>;
+/**
+ * Run tick end callbacks with TickResult and COM.
+ *
+ * Callbacks receive TickResult (data) and COM (context).
+ * TickResult contains both data about the completed tick and control methods
+ * (stop/continue) to influence whether execution continues.
+ *
+ * If a callback returns a boolean, it's automatically converted to a continue/stop call:
+ * - true = result.continue()
+ * - false = result.stop()
+ * - void/undefined = no automatic action (callback may have called methods directly)
+ */
+export declare function storeRunTickEndCallbacks(store: RuntimeStore, result: TickResult, ctx: COM): Promise<void>;
+/**
+ * Run after compile callbacks.
+ */
+export declare function storeRunAfterCompileCallbacks(store: RuntimeStore, compiled: CompiledStructure, ctx: COM): Promise<void>;
+/**
+ * Clear lifecycle callbacks.
+ */
+export declare function storeClearLifecycleCallbacks(store: RuntimeStore): void;
+/**
+ * Clear data cache.
+ */
+export declare function storeClearDataCache(store: RuntimeStore): void;
+/**
+ * Get serializable data cache.
+ */
+export declare function storeGetSerializableDataCache(store: RuntimeStore): Record<string, SerializableCacheEntry>;
+/**
+ * Restore data cache from serializable format.
+ */
+export declare function storeSetDataCache(store: RuntimeStore, data: Record<string, SerializableCacheEntry>): void;
+/**
+ * Invalidate cached data matching a pattern.
+ */
+export declare function storeInvalidateData(store: RuntimeStore, pattern: string | RegExp): void;
+//# sourceMappingURL=runtime-context.d.ts.map

package/dist/hooks/runtime-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-context.d.ts","sourceRoot":"","sources":["../../src/hooks/runtime-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,UAAU,EACV,SAAS,EACV,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAS/C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;CAClB;AAMD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC9C,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,KAAK,IAAI,CAAC;IACzD,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACxC,OAAO,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;IACxC,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAE3C,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,GAAG,MAAM,CAAC;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,6BAA6B;IAC7B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAEnC,2BAA2B;IAC3B,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAE9C,0BAA0B;IAC1B,kBAAkB,EAAE,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC3C,gBAAgB,EAAE,GAAG,CAAC,eAAe,CAAC,CAAC;IACvC,qBAAqB,EAAE,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAEjD,6DAA6D;IAC7D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CASjD;AAQD;;GAEG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAM9C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,EAC9B,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,GAAG,KAAK,CAAC,YAAY,CAErB;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAEhE;AAED;;GAEG;AACH,wBAAsB,uBAAuB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhF;AAED;;GAEG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,GAAG,GACP,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,GAAG,GACP,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;GAEG;AACH,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,GAAG,EAAE,GAAG,GACP,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAItE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAE7D;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,YAAY,GAClB,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAUxC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,GAC3C,IAAI,CAKN;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOvF"}

package/dist/hooks/runtime-context.js

@@ -0,0 +1,149 @@
+/**
+ * V2 Runtime Context
+ *
+ * Holds per-session state that hooks need access to.
+ * This is what makes each FiberCompiler/Session isolated.
+ */
+import React, { createContext, useContext } from "react";
+// Helper for createElement
+const h = React.createElement;
+/**
+ * Create a new runtime store.
+ */
+export function createRuntimeStore() {
+    return {
+        dataCache: new Map(),
+        pendingFetches: new Map(),
+        tickStartCallbacks: new Set(),
+        tickEndCallbacks: new Set(),
+        afterCompileCallbacks: new Set(),
+        knobRegistry: new Map(),
+    };
+}
+// ============================================================
+// React Context
+// ============================================================
+const RuntimeContext = createContext(null);
+/**
+ * Get the runtime store from context.
+ */
+export function useRuntimeStore() {
+    const store = useContext(RuntimeContext);
+    if (!store) {
+        throw new Error("useRuntimeStore must be used within a RuntimeProvider");
+    }
+    return store;
+}
+/**
+ * Provider for runtime context.
+ */
+export function RuntimeProvider({ store, children, }) {
+    return h(RuntimeContext.Provider, { value: store }, children);
+}
+// ============================================================
+// Store Operations (for use outside React render)
+// ============================================================
+/**
+ * Check if store has pending data fetches.
+ */
+export function storeHasPendingData(store) {
+    return store.pendingFetches.size > 0;
+}
+/**
+ * Wait for all pending data fetches in store.
+ */
+export async function storeResolvePendingData(store) {
+    if (store.pendingFetches.size === 0)
+        return;
+    await Promise.all(store.pendingFetches.values());
+}
+/**
+ * Run tick start callbacks with TickState and COM.
+ */
+export async function storeRunTickStartCallbacks(store, tickState, ctx) {
+    for (const callback of store.tickStartCallbacks) {
+        await callback(tickState, ctx);
+    }
+}
+/**
+ * Run tick end callbacks with TickResult and COM.
+ *
+ * Callbacks receive TickResult (data) and COM (context).
+ * TickResult contains both data about the completed tick and control methods
+ * (stop/continue) to influence whether execution continues.
+ *
+ * If a callback returns a boolean, it's automatically converted to a continue/stop call:
+ * - true = result.continue()
+ * - false = result.stop()
+ * - void/undefined = no automatic action (callback may have called methods directly)
+ */
+export async function storeRunTickEndCallbacks(store, result, ctx) {
+    for (const callback of store.tickEndCallbacks) {
+        const decision = await callback(result, ctx);
+        // If callback returns boolean, auto-convert to continue/stop
+        if (decision === true) {
+            result.continue();
+        }
+        else if (decision === false) {
+            result.stop();
+        }
+        // void/undefined = callback handled it or wants default behavior
+    }
+}
+/**
+ * Run after compile callbacks.
+ */
+export async function storeRunAfterCompileCallbacks(store, compiled, ctx) {
+    for (const callback of store.afterCompileCallbacks) {
+        await callback(compiled, ctx);
+    }
+}
+/**
+ * Clear lifecycle callbacks.
+ */
+export function storeClearLifecycleCallbacks(store) {
+    store.tickStartCallbacks.clear();
+    store.tickEndCallbacks.clear();
+    store.afterCompileCallbacks.clear();
+}
+/**
+ * Clear data cache.
+ */
+export function storeClearDataCache(store) {
+    store.dataCache.clear();
+}
+/**
+ * Get serializable data cache.
+ */
+export function storeGetSerializableDataCache(store) {
+    const result = {};
+    for (const [key, entry] of store.dataCache) {
+        result[key] = {
+            value: entry.value,
+            tick: entry.tick,
+            deps: entry.deps,
+        };
+    }
+    return result;
+}
+/**
+ * Restore data cache from serializable format.
+ */
+export function storeSetDataCache(store, data) {
+    store.dataCache.clear();
+    for (const [key, entry] of Object.entries(data)) {
+        store.dataCache.set(key, entry);
+    }
+}
+/**
+ * Invalidate cached data matching a pattern.
+ */
+export function storeInvalidateData(store, pattern) {
+    for (const key of store.dataCache.keys()) {
+        const matches = typeof pattern === "string" ? key === pattern : pattern.test(key);
+        if (matches) {
+            store.dataCache.delete(key);
+        }
+    }
+}
+//# sourceMappingURL=runtime-context.js.map

package/dist/hooks/runtime-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-context.js","sourceRoot":"","sources":["../../src/hooks/runtime-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EAAE,aAAa,EAAE,UAAU,EAAkB,MAAM,OAAO,CAAC;AAWzE,2BAA2B;AAC3B,MAAM,CAAC,GAAG,KAAK,CAAC,aAAa,CAAC;AAsE9B;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,SAAS,EAAE,IAAI,GAAG,EAAE;QACpB,cAAc,EAAE,IAAI,GAAG,EAAE;QACzB,kBAAkB,EAAE,IAAI,GAAG,EAAE;QAC7B,gBAAgB,EAAE,IAAI,GAAG,EAAE;QAC3B,qBAAqB,EAAE,IAAI,GAAG,EAAE;QAChC,YAAY,EAAE,IAAI,GAAG,EAAE;KACxB,CAAC;AACJ,CAAC;AAED,+DAA+D;AAC/D,gBAAgB;AAChB,+DAA+D;AAE/D,MAAM,cAAc,GAAG,aAAa,CAAsB,IAAI,CAAC,CAAC;AAEhE;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,cAAc,CAAC,CAAC;IACzC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,KAAK,EACL,QAAQ,GAIT;IACC,OAAO,CAAC,CAAC,cAAc,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,CAAC;AAChE,CAAC;AAED,+DAA+D;AAC/D,kDAAkD;AAClD,+DAA+D;AAE/D;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAmB;IACrD,OAAO,KAAK,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,KAAmB;IAC/D,IAAI,KAAK,CAAC,cAAc,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO;IAC5C,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,KAAmB,EACnB,SAAoB,EACpB,GAAQ;IAER,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,kBAAkB,EAAE,CAAC;QAChD,MAAM,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACjC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,KAAmB,EACnB,MAAkB,EAClB,GAAQ;IAER,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAC9C,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC7C,6DAA6D;QAC7D,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,CAAC;aAAM,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,CAAC;QACD,iEAAiE;IACnE,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,KAAmB,EACnB,QAA2B,EAC3B,GAAQ;IAER,KAAK,MAAM,QAAQ,IAAI,KAAK,CAAC,qBAAqB,EAAE,CAAC;QACnD,MAAM,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAChC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAAmB;IAC9D,KAAK,CAAC,kBAAkB,CAAC,KAAK,EAAE,CAAC;IACjC,KAAK,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;IAC/B,KAAK,CAAC,qBAAqB,CAAC,KAAK,EAAE,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAmB;IACrD,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAC3C,KAAmB;IAEnB,MAAM,MAAM,GAA2C,EAAE,CAAC;IAC1D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,CAAC,GAAG;YACZ,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,KAAK,CAAC,IAAI;SACjB,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAmB,EACnB,IAA4C;IAE5C,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACxB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAmB,EAAE,OAAwB;IAC/E,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClF,IAAI,OAAO,EAAE,CAAC;YACZ,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/hooks/signal.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Signal implementation for reactive state management.
+ *
+ * Signals provide a lightweight, framework-agnostic way to manage reactive state.
+ * Similar to Angular/SolidJS signals.
+ *
+ * This is the full signal library with:
+ * - AsyncLocalStorage for concurrency safety
+ * - Auto-tracking computed signals
+ * - Batch operations
+ * - COM state integration
+ * - Compiler integration for automatic recompilation
+ *
+ * @example
+ * ```typescript
+ * // Create a signal
+ * const count = signal(0);
+ *
+ * // Read value
+ * console.log(count()); // 0
+ *
+ * // Update value
+ * count.set(10);
+ * console.log(count()); // 10
+ *
+ * // Update with function
+ * count.update(n => n + 1);
+ * console.log(count()); // 11
+ *
+ * // Computed signal (memoized, auto-updates)
+ * const doubled = computed(() => count() * 2);
+ * console.log(doubled()); // 22
+ *
+ * // Cleanup when done
+ * count.dispose();
+ * ```
+ *
+ * @see docs/state-management.md for full documentation
+ */
+/**
+ * Run a function within a signal context.
+ * Used by FiberCompiler to establish per-execution context.
+ *
+ * @internal
+ */
+export declare function runWithSignalContext<T>(fn: () => T): T;
+/**
+ * Run an async function within a signal context.
+ * Used by FiberCompiler to establish per-execution context.
+ *
+ * @internal
+ */
+export declare function runWithSignalContextAsync<T>(fn: () => Promise<T>): Promise<T>;
+export declare const SIGNAL_SYMBOL: unique symbol;
+export declare const COMPUTED_SYMBOL: unique symbol;
+export declare const EFFECT_SYMBOL: unique symbol;
+type EqualityFn<T> = (a: T, b: T) => boolean;
+type CleanupFn = () => void;
+export interface SignalOptions<T> {
+    /** Custom equality function. Default: Object.is */
+    equal?: EqualityFn<T>;
+    /** Signal name for debugging */
+    name?: string;
+}
+export interface Signal<T> {
+    /** Read the current value */
+    (): T;
+    /** Set a new value */
+    set: (value: T | ((prev: T) => T)) => void;
+    /** Update value with a function */
+    update: (updater: (value: T) => T) => void;
+    /** Subscribe to value changes */
+    subscribe?: (callback: (value: T) => void) => () => void;
+    /** Current value (property access) */
+    readonly value: T;
+    /** Dispose this signal and clean up all listeners */
+    dispose?: () => void;
+    /** Check if signal is disposed */
+    readonly disposed?: boolean;
+}
+export interface ComputedSignal<T> {
+    /** Read the current value */
+    (): T;
+    /** Current value (property access) */
+    readonly value: T;
+    /** Dispose this computed and stop tracking */
+    dispose: () => void;
+    /** Check if computed is disposed */
+    readonly disposed: boolean;
+}
+/**
+ * A read-only signal that can be observed but not modified.
+ * Used for watching state owned by another component.
+ */
+export interface ReadonlySignal<T> {
+    /** Read the current value */
+    (): T;
+    /** Current value (property access) */
+    readonly value: T;
+    /** Dispose this signal and stop watching */
+    dispose: () => void;
+    /** Check if disposed */
+    readonly disposed: boolean;
+}
+export interface EffectRef {
+    /** Dispose this effect and stop running */
+    dispose: () => void;
+    /** Check if effect is disposed */
+    readonly disposed: boolean;
+}
+/**
+ * Batch multiple signal updates together.
+ * Effects only run once after all updates complete.
+ *
+ * @example
+ * ```typescript
+ * batch(() => {
+ *   count.set(1);
+ *   name.set('Alice');
+ *   // Effects run once here, not twice
+ * });
+ * ```
+ */
+export declare function batch<T>(fn: () => T): T;
+/**
+ * Creates a writable signal with an initial value.
+ *
+ * @example
+ * ```typescript
+ * const count = signal(0);
+ * count();           // 0
+ * count.set(10);     // set to 10
+ * count.update(n => n + 1);  // increment
+ * count.dispose();   // cleanup
+ * ```
+ */
+export declare function signal<T>(initialValue: T, options?: SignalOptions<T>): Signal<T>;
+/**
+ * Create a standalone signal (not tied to a component).
+ * Alias for signal() for API compatibility.
+ */
+export declare function createSignal<T>(initialValue: T, options?: SignalOptions<T>): Signal<T>;
+/**
+ * Creates a computed signal that derives its value from other signals.
+ * Computed values are memoized and only recompute when dependencies change.
+ *
+ * @example
+ * ```typescript
+ * const count = signal(0);
+ * const doubled = computed(() => count() * 2);
+ *
+ * doubled();  // 0
+ * count.set(5);
+ * doubled();  // 10 (recomputed)
+ * doubled();  // 10 (cached, no recompute)
+ * ```
+ */
+export declare function computed<T>(computation: () => T, options?: SignalOptions<T>): ComputedSignal<T>;
+/**
+ * Runs an effect that automatically re-runs when dependencies change.
+ * Use sparingly - prefer computed() for derived values.
+ *
+ * Best for: syncing to external APIs (localStorage, canvas, DOM, etc.)
+ *
+ * @example
+ * ```typescript
+ * const count = signal(0);
+ *
+ * const ref = effect(() => {
+ *   console.log('Count:', count());
+ * });
+ *
+ * count.set(5);  // logs "Count: 5"
+ *
+ * ref.dispose();  // stop the effect
+ * ```
+ */
+export declare function effect(fn: (onCleanup: (cleanup: CleanupFn) => void) => void | CleanupFn): EffectRef;
+/**
+ * Create a signal - reactive state that can trigger reconciliation.
+ *
+ * Unlike useState, signals:
+ * - Can be read outside of render
+ * - Can be subscribed to
+ * - Don't cause immediate re-render (schedule reconcile instead)
+ *
+ * @example
+ * ```tsx
+ * const MyComponent = () => {
+ *   const count = useSignal(0);
+ *
+ *   const handleClick = () => {
+ *     count.set(c => c + 1);
+ *   };
+ *
+ *   return <Section>Count: {count()}</Section>;
+ * };
+ * ```
+ */
+export declare function useSignal<T>(initialValue: T): Signal<T>;
+/**
+ * Create a computed signal that derives from other signals.
+ *
+ * @example
+ * ```tsx
+ * const count = useSignal(5);
+ * const doubled = useComputed(() => count() * 2, [count]);
+ * // doubled() === 10
+ * ```
+ */
+export declare function useComputed<T>(compute: () => T, deps: readonly Signal<any>[]): Signal<T>;
+/**
+ * Read a signal without tracking it as a dependency.
+ * Useful when you want to read a value in a computed/effect without
+ * triggering re-runs when that value changes.
+ *
+ * @example
+ * ```typescript
+ * effect(() => {
+ *   const user = currentUser();
+ *   const count = untracked(() => counter());  // won't trigger re-run
+ *   console.log(`User ${user} has count ${count}`);
+ * });
+ * ```
+ */
+export declare function untracked<T>(fn: () => T): T;
+/**
+ * Check if a value is a signal.
+ */
+export declare function isSignal(value: unknown): value is Signal<unknown>;
+/**
+ * Check if a value is a computed signal.
+ */
+export declare function isComputed(value: unknown): value is ComputedSignal<unknown>;
+/**
+ * Check if a value is an effect ref.
+ */
+export declare function isEffect(value: unknown): value is EffectRef;
+export declare const COM_SIGNAL_SYMBOL: unique symbol;
+/**
+ * Creates a signal bound to COM state.
+ * Changes sync bidirectionally between signal and COM.
+ *
+ * @internal Used by comState() after COM is available
+ */
+export declare function createCOMStateSignal<T>(ctx: {
+    getState: (key: string) => T | undefined;
+    setState: (key: string, value: unknown) => void;
+    on: (event: any, handler: (...args: any[]) => void) => any;
+    off?: (event: any, handler: (...args: any[]) => void) => any;
+}, key: string, initialValue?: T): Signal<T | undefined>;
+export declare const WATCH_SIGNAL_SYMBOL: unique symbol;
+export declare const PROPS_SIGNAL_SYMBOL: unique symbol;
+export declare const REQUIRED_INPUT_SYMBOL: unique symbol;
+/**
+ * Creates a read-only signal that watches COM state.
+ * The signal updates when COM state changes, but cannot modify it.
+ *
+ * @internal Used by watchComState() and watch()
+ */
+export declare function createReadonlyCOMStateSignal<T>(ctx: {
+    getState: (key: string) => T | undefined;
+    on: (event: any, handler: (...args: any[]) => void) => any;
+    off?: (event: any, handler: (...args: any[]) => void) => any;
+}, key: string, defaultValue?: T): ReadonlySignal<T | undefined>;
+export {};
+//# sourceMappingURL=signal.d.ts.map

package/dist/hooks/signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../src/hooks/signal.ts"],"names":[],"mappings":"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"}