crann 1.0.49 → 2.0.2

package/dist/types/errors.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Crann Error Classes
+ *
+ * Custom error types for better debugging and error handling.
+ */
+/**
+ * Base error class for all Crann errors.
+ */
+export declare class CrannError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when there's an issue with the config schema.
+ */
+export declare class ConfigError extends CrannError {
+    readonly field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+/**
+ * Thrown when a store or agent has been destroyed/disconnected.
+ */
+export declare class LifecycleError extends CrannError {
+    readonly storeName: string;
+    readonly entity: "store" | "agent";
+    constructor(storeName: string, entity: "store" | "agent");
+}
+/**
+ * Thrown when there's a connection issue.
+ */
+export declare class ConnectionError extends CrannError {
+    readonly storeName: string;
+    readonly reason?: string | undefined;
+    constructor(message: string, storeName: string, reason?: string | undefined);
+}
+/**
+ * Thrown when an action execution fails.
+ */
+export declare class ActionError extends CrannError {
+    readonly actionName: string;
+    readonly storeName: string;
+    readonly reason: string;
+    constructor(actionName: string, storeName: string, reason: string);
+}
+/**
+ * Thrown when action validation fails.
+ */
+export declare class ValidationError extends CrannError {
+    readonly actionName: string;
+    readonly storeName: string;
+    readonly reason: string;
+    constructor(actionName: string, storeName: string, reason: string);
+}
+/**
+ * Thrown when there's a storage key collision.
+ */
+export declare class StorageCollisionError extends CrannError {
+    readonly storeName: string;
+    constructor(storeName: string);
+}

package/dist/types/model/crann.model.d.ts

@@ -1,4 +1,4 @@
-import { AgentInfo, BrowserLocation } from "porter-source";
+import { AgentInfo, BrowserLocation } from "../transport";
 export declare const Partition: {
     Instance: "instance";
     Service: "service";

package/dist/types/react/__tests__/hooks.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * React Hooks Tests
+ *
+ * Tests for the Crann React integration hooks.
+ */
+export {};

package/dist/types/react/hooks.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Crann React Hooks Implementation
+ *
+ * Provides React hooks for connecting to and using a Crann store.
+ */
+import type { ConfigSchema, ValidatedConfig } from "../store/types";
+import type { CrannHooks, CreateCrannHooksOptions } from "./types";
+/**
+ * Creates a set of React hooks for a Crann store.
+ *
+ * This is the main entry point for React integration. Call once at module
+ * level with your config, then use the returned hooks in your components.
+ *
+ * @param config - Validated config from createConfig()
+ * @param options - Optional hook options
+ * @returns Object containing all Crann React hooks
+ *
+ * @example
+ * // hooks.ts
+ * import { createConfig } from 'crann';
+ * import { createCrannHooks } from 'crann/react';
+ *
+ * const config = createConfig({
+ *   name: 'myFeature',
+ *   count: { default: 0 },
+ *   actions: {
+ *     increment: { handler: async (ctx) => ctx.setState({ count: ctx.state.count + 1 }) },
+ *   },
+ * });
+ *
+ * export const { useCrannState, useCrannActions, useCrannReady } = createCrannHooks(config);
+ *
+ * // MyComponent.tsx
+ * function Counter() {
+ *   const count = useCrannState(s => s.count);
+ *   const { increment } = useCrannActions();
+ *   const isReady = useCrannReady();
+ *
+ *   if (!isReady) return <div>Loading...</div>;
+ *
+ *   return <button onClick={() => increment()}>Count: {count}</button>;
+ * }
+ */
+export declare function createCrannHooks<TConfig extends ConfigSchema>(config: ValidatedConfig<TConfig>, options?: CreateCrannHooksOptions): CrannHooks<TConfig>;

package/dist/types/react/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Crann React Integration
+ *
+ * Provides React hooks for connecting to and using a Crann store.
+ *
+ * @example
+ * import { createCrannHooks } from 'crann/react';
+ * import { config } from './config';
+ *
+ * export const { useCrannState, useCrannActions, useCrannReady } = createCrannHooks(config);
+ */
+export { createCrannHooks } from "./hooks";
+export type { CrannHooks, CreateCrannHooksOptions, UseCrannStateSelector, UseCrannStateTuple, } from "./types";

package/dist/types/react/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Crann React Integration Types
+ */
+import type { ConfigSchema, DerivedState, DerivedActions } from "../store/types";
+import type { AgentAPI } from "../agent/types";
+/**
+ * Return type of the useCrannState hook when using a selector.
+ */
+export type UseCrannStateSelector<TConfig extends ConfigSchema, TSelected> = TSelected;
+/**
+ * Return type of the useCrannState hook when using a key.
+ * Returns [value, setValue] tuple like useState.
+ */
+export type UseCrannStateTuple<TConfig extends ConfigSchema, K extends keyof DerivedState<TConfig>> = [
+    DerivedState<TConfig>[K],
+    (value: DerivedState<TConfig>[K]) => Promise<void>
+];
+/**
+ * Options for creating Crann hooks.
+ */
+export type CreateCrannHooksOptions = {
+    /** Enable debug logging */
+    debug?: boolean;
+};
+/**
+ * The hooks object returned by createCrannHooks.
+ */
+export interface CrannHooks<TConfig extends ConfigSchema> {
+    /**
+     * Hook to read state with a selector function.
+     * Re-renders only when selected value changes.
+     *
+     * @example
+     * const count = useCrannState(s => s.count);
+     */
+    useCrannState<TSelected>(selector: (state: DerivedState<TConfig>) => TSelected): TSelected;
+    /**
+     * Hook to read and write a specific state key.
+     * Returns [value, setValue] tuple like useState.
+     *
+     * @example
+     * const [count, setCount] = useCrannState('count');
+     */
+    useCrannState<K extends keyof DerivedState<TConfig>>(key: K): UseCrannStateTuple<TConfig, K>;
+    /**
+     * Hook to get typed action methods.
+     * Actions are stable references that won't cause re-renders.
+     *
+     * @example
+     * const { increment, fetchUser } = useCrannActions();
+     */
+    useCrannActions(): DerivedActions<TConfig>;
+    /**
+     * Hook to check connection status.
+     * Re-renders when connection status changes.
+     *
+     * @example
+     * const isReady = useCrannReady();
+     * if (!isReady) return <Loading />;
+     */
+    useCrannReady(): boolean;
+    /**
+     * Optional provider for dependency injection (useful for testing).
+     * Not required for normal usage.
+     */
+    CrannProvider: React.FC<{
+        agent?: AgentAPI<TConfig>;
+        children: React.ReactNode;
+    }>;
+    /**
+     * Get the current agent instance (for advanced usage).
+     */
+    useAgent(): AgentAPI<TConfig> | null;
+}

package/dist/types/rpc/adapter.d.ts

@@ -1,3 +1,3 @@
-import { source, connect } from "porter-source";
+import { source, connect } from "../transport";
 import { ActionDefinition, AnyConfig, DerivedState, SetStateFunction } from "../model/crann.model";
 export declare function createCrannRPCAdapter<TConfig extends AnyConfig>(stateGetter: () => DerivedState<TConfig>, actions: Record<string, ActionDefinition<DerivedState<TConfig>, any[], any>>, porter?: ReturnType<typeof source> | ReturnType<typeof connect>, setState?: SetStateFunction<DerivedState<TConfig>>): import("./types").RemoteCallable<Record<string, ActionDefinition<DerivedState<TConfig>, any[], any>>>;

package/dist/types/rpc/types.d.ts

@@ -1,4 +1,4 @@
-import { BrowserLocation } from "porter-source";
+import { BrowserLocation } from "../transport";
 export type MessageMap = {
     call: {
         id: string;

package/dist/types/store/ActionExecutor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ActionExecutor - Executes RPC actions
+ *
+ * Responsibilities:
+ * - Execute action handlers with context object
+ * - Validate action arguments
+ * - Handle errors
+ */
+import type { AgentInfo } from "../transport";
+import { ConfigSchema, ValidatedConfig, DerivedState } from "./types";
+export declare class ActionExecutor<TConfig extends ConfigSchema> {
+    private readonly config;
+    private readonly getState;
+    private readonly setState;
+    constructor(config: ValidatedConfig<TConfig>, getState: () => DerivedState<TConfig>, setState: (state: Partial<DerivedState<TConfig>>, agentId: string) => Promise<void>);
+    /**
+     * Execute an action by name.
+     *
+     * @param actionName - The name of the action to execute
+     * @param args - Arguments to pass to the action handler
+     * @param agentInfo - Info about the calling agent
+     * @returns The result of the action handler
+     * @throws {ActionError} If the action doesn't exist or fails
+     * @throws {ValidationError} If action validation fails
+     */
+    execute(actionName: string, args: unknown[], agentInfo: AgentInfo): Promise<unknown>;
+    /**
+     * Check if an action exists.
+     */
+    hasAction(actionName: string): boolean;
+    /**
+     * Get list of available action names.
+     */
+    getActionNames(): string[];
+}

package/dist/types/store/AgentRegistry.d.ts

@@ -0,0 +1,49 @@
+/**
+ * AgentRegistry - Tracks connected agents
+ *
+ * Responsibilities:
+ * - Maintain registry of connected agents
+ * - Provide query capabilities
+ * - Clean up on disconnect
+ */
+import type { AgentInfo } from "../transport";
+import { AgentConnectionInfo } from "./types";
+export declare class AgentRegistry {
+    private readonly agents;
+    /**
+     * Register a new agent connection.
+     */
+    add(agentInfo: AgentInfo): AgentConnectionInfo;
+    /**
+     * Unregister an agent.
+     */
+    remove(agentId: string): boolean;
+    /**
+     * Get agent info by ID.
+     */
+    get(agentId: string): AgentConnectionInfo | undefined;
+    /**
+     * Get all connected agents.
+     */
+    getAll(): AgentConnectionInfo[];
+    /**
+     * Query agents by criteria.
+     */
+    query(criteria: {
+        context?: string;
+        tabId?: number;
+        frameId?: number;
+    }): AgentConnectionInfo[];
+    /**
+     * Check if an agent is registered.
+     */
+    has(agentId: string): boolean;
+    /**
+     * Get the number of connected agents.
+     */
+    get size(): number;
+    /**
+     * Clear all agents.
+     */
+    clear(): void;
+}

package/dist/types/store/Persistence.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Persistence - Handles chrome.storage operations
+ *
+ * Responsibilities:
+ * - Hydrate state from storage on startup
+ * - Persist state changes to storage
+ * - Manage storage key structure: crann:{name}:v{version}:{key}
+ */
+import { ConfigSchema, ValidatedConfig, DerivedSharedState, StoreOptions } from "./types";
+export declare class Persistence<TConfig extends ConfigSchema> {
+    private readonly config;
+    private readonly options;
+    constructor(config: ValidatedConfig<TConfig>, options?: StoreOptions);
+    /**
+     * Build a storage key with the structured format.
+     * Format: crann:{name}:v{version}:{key}
+     */
+    private buildKey;
+    /**
+     * Parse a storage key to extract components.
+     */
+    private parseKey;
+    /**
+     * Get the metadata key for this store.
+     * Format: crann:{name}:__meta
+     */
+    private getMetaKey;
+    /**
+     * Hydrate state from chrome.storage.
+     * Only loads keys that exist in the current config.
+     */
+    hydrate(): Promise<Partial<DerivedSharedState<TConfig>>>;
+    /**
+     * Persist state changes to storage.
+     * Only persists keys with persist: 'local' or 'session'.
+     */
+    persist(state: Partial<DerivedSharedState<TConfig>>): Promise<void>;
+    /**
+     * Clear all persisted data for this store.
+     */
+    clearAll(): Promise<void>;
+    private updateMetadata;
+}
+/**
+ * Find and remove orphaned Crann data from storage.
+ *
+ * @example
+ * const removed = await clearOrphanedData({
+ *   keepStores: ['myFeature', 'otherStore'],
+ *   dryRun: true,
+ * });
+ */
+export declare function clearOrphanedData(options: {
+    keepStores: string[];
+    dryRun?: boolean;
+}): Promise<{
+    keys: string[];
+    count: number;
+}>;

package/dist/types/store/StateManager.d.ts

@@ -0,0 +1,65 @@
+/**
+ * StateManager - Handles in-memory state operations
+ *
+ * Responsibilities:
+ * - Maintain shared state and per-agent state
+ * - Handle state updates with change detection
+ * - Initialize default values from config
+ */
+import { ConfigSchema, ValidatedConfig, DerivedState, DerivedSharedState, DerivedAgentState } from "./types";
+import { Persistence } from "./Persistence";
+export declare class StateManager<TConfig extends ConfigSchema> {
+    private readonly config;
+    private readonly persistence;
+    private sharedState;
+    private readonly agentStates;
+    private readonly defaultSharedState;
+    private readonly defaultAgentState;
+    constructor(config: ValidatedConfig<TConfig>, persistence: Persistence<TConfig>);
+    /**
+     * Get the full derived state (shared only, from store perspective).
+     */
+    getState(): DerivedState<TConfig>;
+    /**
+     * Get shared state only.
+     */
+    getSharedState(): DerivedSharedState<TConfig>;
+    /**
+     * Get agent-scoped state for a specific agent.
+     */
+    getAgentState(agentId: string): DerivedAgentState<TConfig>;
+    /**
+     * Get full state for an agent (shared + agent-scoped).
+     */
+    getFullStateForAgent(agentId: string): DerivedState<TConfig>;
+    /**
+     * Update state, separating shared and agent-scoped changes.
+     * Returns the changes that were actually applied.
+     */
+    setState(state: Partial<DerivedState<TConfig>>, agentId?: string): {
+        sharedChanges: Partial<DerivedSharedState<TConfig>>;
+        agentChanges: Partial<DerivedAgentState<TConfig>>;
+    };
+    /**
+     * Update agent-scoped state only.
+     */
+    setAgentState(agentId: string, state: Partial<DerivedAgentState<TConfig>>): void;
+    /**
+     * Hydrate shared state from storage.
+     */
+    hydrateSharedState(state: Partial<DerivedSharedState<TConfig>>): void;
+    /**
+     * Initialize state for a new agent.
+     */
+    initializeAgentState(agentId: string): void;
+    /**
+     * Remove state for a disconnected agent.
+     */
+    removeAgentState(agentId: string): void;
+    /**
+     * Clear all state back to defaults.
+     */
+    clear(): void;
+    private buildDefaultSharedState;
+    private buildDefaultAgentState;
+}

package/dist/types/store/Store.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Crann v2 Store
+ *
+ * The central state hub that runs in the service worker.
+ * This is NOT a singleton - each call to createStore() returns a new instance.
+ */
+import type { BrowserLocation } from "../transport";
+import { ConfigSchema, ValidatedConfig, StoreOptions, DerivedState, DerivedSharedState, DerivedAgentState, StateChangeListener, AgentConnectionInfo } from "./types";
+export declare class Store<TConfig extends ConfigSchema> {
+    private readonly config;
+    private readonly options;
+    private readonly porter;
+    private readonly stateManager;
+    private readonly persistence;
+    private readonly agentRegistry;
+    private readonly actionExecutor;
+    private readonly stateChangeListeners;
+    private readonly agentConnectListeners;
+    private readonly agentDisconnectListeners;
+    private isDestroyed;
+    constructor(config: ValidatedConfig<TConfig>, options?: StoreOptions);
+    /**
+     * Get the current shared state (state visible to all agents).
+     *
+     * @returns A snapshot of the current shared state
+     * @throws {LifecycleError} If the store has been destroyed
+     *
+     * @example
+     * const state = store.getState();
+     * console.log(state.count);
+     */
+    getState(): DerivedState<TConfig>;
+    /**
+     * Get agent-scoped state for a specific agent.
+     *
+     * @param agentId - The unique identifier of the agent
+     * @returns The agent-scoped state for the specified agent
+     * @throws {LifecycleError} If the store has been destroyed
+     *
+     * @example
+     * store.onAgentConnect((agent) => {
+     *   const agentState = store.getAgentState(agent.id);
+     * });
+     */
+    getAgentState(agentId: string): DerivedAgentState<TConfig>;
+    /**
+     * Update shared state. Changes are persisted and broadcast to all agents.
+     *
+     * @param state - Partial state to merge with current shared state
+     * @throws {LifecycleError} If the store has been destroyed
+     *
+     * @example
+     * await store.setState({ count: 5 });
+     */
+    setState(state: Partial<DerivedSharedState<TConfig>>): Promise<void>;
+    /**
+     * Update state for a specific agent. Can include both shared and agent-scoped state.
+     *
+     * @param state - Partial state to merge
+     * @param agentId - The agent to update (for agent-scoped state)
+     * @throws {LifecycleError} If the store has been destroyed
+     *
+     * @example
+     * await store.setState({ count: 5, agentData: 'custom' }, agentId);
+     */
+    setState(state: Partial<DerivedState<TConfig>>, agentId: string): Promise<void>;
+    /**
+     * Update agent-scoped state for a specific agent.
+     *
+     * @param agentId - The unique identifier of the agent
+     * @param state - Partial agent-scoped state to merge
+     * @throws {LifecycleError} If the store has been destroyed
+     *
+     * @example
+     * await store.setAgentState(agentId, { agentData: 'custom' });
+     */
+    setAgentState(agentId: string, state: Partial<DerivedAgentState<TConfig>>): Promise<void>;
+    /**
+     * Clear all state back to defaults and remove persisted data.
+     *
+     * @throws {LifecycleError} If the store has been destroyed
+     *
+     * @example
+     * await store.clear();
+     */
+    clear(): Promise<void>;
+    /**
+     * Subscribe to state changes. Called whenever state is updated.
+     *
+     * @param listener - Callback receiving (state, changes, agent?)
+     * @returns Unsubscribe function
+     * @throws {LifecycleError} If the store has been destroyed
+     *
+     * @example
+     * const unsubscribe = store.subscribe((state, changes, agent) => {
+     *   console.log('State changed:', changes);
+     * });
+     * // Later: unsubscribe();
+     */
+    subscribe(listener: StateChangeListener<TConfig>): () => void;
+    /**
+     * Register callback for when an agent connects.
+     *
+     * @param callback - Called with agent connection info
+     * @returns Unsubscribe function
+     * @throws {LifecycleError} If the store has been destroyed
+     *
+     * @example
+     * store.onAgentConnect((agent) => {
+     *   console.log(`Agent ${agent.id} connected from tab ${agent.tabId}`);
+     * });
+     */
+    onAgentConnect(callback: (agent: AgentConnectionInfo) => void): () => void;
+    /**
+     * Register callback for when an agent disconnects.
+     *
+     * @param callback - Called with agent connection info
+     * @returns Unsubscribe function
+     * @throws {LifecycleError} If the store has been destroyed
+     *
+     * @example
+     * store.onAgentDisconnect((agent) => {
+     *   console.log(`Agent ${agent.id} disconnected`);
+     * });
+     */
+    onAgentDisconnect(callback: (agent: AgentConnectionInfo) => void): () => void;
+    /**
+     * Get all connected agents, optionally filtered by location.
+     *
+     * @param query - Optional filter by context, tabId, frameId
+     * @returns Array of connected agent info
+     * @throws {LifecycleError} If the store has been destroyed
+     *
+     * @example
+     * const allAgents = store.getAgents();
+     * const contentScripts = store.getAgents({ context: 'contentscript' });
+     * const tab42Agents = store.getAgents({ tabId: 42 });
+     */
+    getAgents(query?: Partial<BrowserLocation>): AgentConnectionInfo[];
+    /**
+     * Destroy the store and clean up all resources.
+     * After calling this, the store cannot be used. Use for testing or HMR cleanup.
+     *
+     * @param options.clearPersisted - If true, also clears persisted storage data
+     *
+     * @example
+     * // In tests
+     * afterEach(() => {
+     *   store.destroy({ clearPersisted: true });
+     * });
+     */
+    destroy(options?: {
+        clearPersisted?: boolean;
+    }): void;
+    private setupMessageHandlers;
+    private setupRpcHandlers;
+    private hydrate;
+    private notifyStateChange;
+    private assertNotDestroyed;
+}
+/**
+ * Create a new Crann store instance.
+ *
+ * This should be called in your service worker/background script.
+ * Each call creates a new, independent store instance (no singleton).
+ *
+ * @param config - Validated config from createConfig()
+ * @param options - Optional store options
+ * @param options.debug - Enable debug logging
+ * @param options.migrate - Migration function for schema version changes
+ * @returns A new Store instance
+ *
+ * @example
+ * // background.ts
+ * import { createConfig, createStore } from 'crann';
+ *
+ * const config = createConfig({
+ *   name: 'myFeature',
+ *   count: { default: 0, persist: 'local' },
+ * });
+ *
+ * const store = createStore(config, { debug: true });
+ *
+ * store.subscribe((state, changes) => {
+ *   console.log('State changed:', changes);
+ * });
+ */
+export declare function createStore<TConfig extends ConfigSchema>(config: ValidatedConfig<TConfig>, options?: StoreOptions): Store<TConfig>;

package/dist/types/store/__tests__/ActionExecutor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/store/__tests__/AgentRegistry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/store/__tests__/Persistence.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Persistence Tests
+ *
+ * Tests for the Persistence module which handles chrome.storage operations.
+ */
+export {};

package/dist/types/store/__tests__/StateManager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/store/__tests__/setup.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Jest setup for store tests
+ * Mocks browser extension APIs
+ */

package/dist/types/store/__tests__/types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/store/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Crann v2 Store Module
+ *
+ * This module provides the new Store implementation for v2.
+ */
+export { Store, createStore } from "./Store";
+export { createConfig } from "./types";
+export { clearOrphanedData } from "./Persistence";
+export type { ConfigSchema, ValidatedConfig, StateItemDefinition, ActionDefinition, ActionsDefinition, ActionContext, ActionHandler, DerivedState, DerivedSharedState, DerivedAgentState, DerivedActions, StateChanges, StateChangeListener, StoreOptions, AgentOptions, ConnectionStatus, AgentConnectionInfo, ScopeType, PersistType, } from "./types";
+export { Scope, Persist } from "./types";