@continuum-dev/session 0.1.0

package/lib/types.d.ts

@@ -0,0 +1,265 @@
+import type { ContinuitySnapshot, Interaction, DetachedValue, DetachedValuePolicy, ProposedValue, ViewportState, PendingIntent, Checkpoint, ViewDefinition, NodeValue, ActionRegistration, ActionHandler } from '@continuum/contract';
+import type { ReconciliationIssue, ReconciliationOptions, ReconciliationResolution, StateDiff } from '@continuum/runtime';
+/**
+ * Minimal storage adapter used by session persistence.
+ *
+ * Compatible with browser `localStorage`/`sessionStorage` and custom storage engines.
+ */
+export interface SessionPersistenceStorage {
+    /**
+     * Returns the stored string for a key, or null when absent.
+     */
+    getItem(key: string): string | null;
+    /**
+     * Writes a string value for a key.
+     */
+    setItem(key: string, value: string): void;
+    /**
+     * Removes a key from storage.
+     */
+    removeItem(key: string): void;
+}
+/**
+ * Configures automatic persistence and cross-tab synchronization.
+ */
+export interface SessionPersistenceOptions {
+    /**
+     * Backing storage implementation.
+     */
+    storage: SessionPersistenceStorage;
+    /**
+     * Storage key to write serialized session blobs under.
+     *
+     * Defaults to `continuum_session`.
+     */
+    key?: string;
+    /**
+     * Optional serialized payload byte limit.
+     *
+     * When exceeded, write is skipped and `onError` receives `size_limit`.
+     */
+    maxBytes?: number;
+    /**
+     * Optional callback for persistence failures.
+     */
+    onError?: (error: {
+        reason: 'size_limit' | 'storage_error';
+        key: string;
+        attemptedBytes?: number;
+        maxBytes?: number;
+        cause?: unknown;
+    }) => void;
+}
+/**
+ * Creates and configures session runtime behavior.
+ */
+export interface SessionOptions {
+    /**
+     * Clock source used for ids and timestamps.
+     *
+     * Defaults to `Date.now`.
+     */
+    clock?: () => number;
+    /**
+     * Maximum number of interaction events to retain.
+     */
+    maxEventLogSize?: number;
+    /**
+     * Maximum number of pending intents to retain.
+     */
+    maxPendingIntents?: number;
+    /**
+     * Maximum number of checkpoints to retain.
+     */
+    maxCheckpoints?: number;
+    /**
+     * Reconciliation options forwarded to `@continuum-dev/runtime`.
+     *
+     * `clock` is managed by session and intentionally omitted here.
+     */
+    reconciliation?: Omit<ReconciliationOptions, 'clock'>;
+    /**
+     * When true, validates `updateState` payloads against node constraints.
+     */
+    validateOnUpdate?: boolean;
+    /**
+     * Enables automatic persistence to storage.
+     */
+    persistence?: SessionPersistenceOptions;
+    /**
+     * Detached value retention policy applied on view pushes.
+     */
+    detachedValuePolicy?: DetachedValuePolicy;
+    /**
+     * Initial action handlers to pre-register at session creation.
+     */
+    actions?: Record<string, {
+        registration: ActionRegistration;
+        handler: ActionHandler;
+    }>;
+}
+/**
+ * Stateful session API for generative UI timelines.
+ */
+export interface Session {
+    /**
+     * Stable unique session identifier.
+     */
+    readonly sessionId: string;
+    /**
+     * True when session has been destroyed and no further operations are allowed.
+     */
+    readonly isDestroyed: boolean;
+    /**
+     * Returns the current combined view/data snapshot.
+     */
+    getSnapshot(): ContinuitySnapshot | null;
+    /**
+     * Returns reconciliation and validation issues collected so far.
+     */
+    getIssues(): ReconciliationIssue[];
+    /**
+     * Returns state diffs from the latest reconciliation.
+     */
+    getDiffs(): StateDiff[];
+    /**
+     * Returns per-node reconciliation decisions from the latest reconciliation.
+     */
+    getResolutions(): ReconciliationResolution[];
+    /**
+     * Pushes a new view and reconciles existing data against it.
+     */
+    pushView(view: ViewDefinition): void;
+    /**
+     * Appends a raw interaction event to the event log and applies its payload.
+     */
+    recordIntent(interaction: Omit<Interaction, 'interactionId' | 'timestamp' | 'sessionId' | 'viewVersion'>): void;
+    /**
+     * Convenience wrapper for `data-update` interactions.
+     */
+    updateState(nodeId: string, payload: unknown): void;
+    /**
+     * Returns viewport metadata for a node, if present.
+     */
+    getViewportState(nodeId: string): ViewportState | undefined;
+    /**
+     * Updates viewport metadata and notifies snapshot listeners.
+     */
+    updateViewportState(nodeId: string, state: ViewportState): void;
+    /**
+     * Returns the interaction timeline.
+     */
+    getEventLog(): Interaction[];
+    /**
+     * Queues an intent awaiting validation/cancellation.
+     */
+    submitIntent(intent: Omit<PendingIntent, 'intentId' | 'queuedAt' | 'status' | 'viewVersion'>): void;
+    /**
+     * Returns currently tracked pending intents.
+     */
+    getPendingIntents(): PendingIntent[];
+    /**
+     * Returns detached values preserved across incompatible view changes.
+     */
+    getDetachedValues(): Record<string, DetachedValue>;
+    /**
+     * Purges detached values either fully or by predicate.
+     */
+    purgeDetachedValues(filter?: (key: string, value: DetachedValue) => boolean): void;
+    /**
+     * Applies a value proposal immediately or stages it when current value is dirty.
+     */
+    proposeValue(nodeId: string, value: NodeValue, source?: string): void;
+    /**
+     * Accepts a staged proposal and applies it as a data update.
+     */
+    acceptProposal(nodeId: string): void;
+    /**
+     * Rejects and removes a staged proposal.
+     */
+    rejectProposal(nodeId: string): void;
+    /**
+     * Returns staged proposals keyed by node id.
+     */
+    getPendingProposals(): Record<string, ProposedValue>;
+    /**
+     * Marks a pending intent as validated.
+     */
+    validateIntent(intentId: string): boolean;
+    /**
+     * Marks a pending intent as cancelled.
+     */
+    cancelIntent(intentId: string): boolean;
+    /**
+     * Creates a manual checkpoint from current snapshot state.
+     */
+    checkpoint(): Checkpoint;
+    /**
+     * Restores view/data state from a specific checkpoint object.
+     */
+    restoreFromCheckpoint(checkpoint: Checkpoint): void;
+    /**
+     * Returns available checkpoints in chronological order.
+     */
+    getCheckpoints(): Checkpoint[];
+    /**
+     * Rewinds state to a checkpoint id and truncates checkpoint history after it.
+     */
+    rewind(checkpointId: string): void;
+    /**
+     * Clears active timeline state while preserving session id and configuration.
+     */
+    reset(): void;
+    /**
+     * Subscribes to snapshot updates.
+     *
+     * Returns an unsubscribe function.
+     */
+    onSnapshot(listener: (snapshot: ContinuitySnapshot | null) => void): () => void;
+    /**
+     * Subscribes to issue updates.
+     *
+     * Returns an unsubscribe function.
+     */
+    onIssues(listener: (issues: ReconciliationIssue[]) => void): () => void;
+    /**
+     * Serializes the complete session into a JSON-compatible blob.
+     */
+    serialize(): unknown;
+    /**
+     * Destroys the session and returns final issues observed before teardown.
+     */
+    destroy(): {
+        issues: ReconciliationIssue[];
+    };
+    /**
+     * Registers an action handler for an intent id.
+     */
+    registerAction(intentId: string, registration: ActionRegistration, handler: ActionHandler): void;
+    /**
+     * Removes a previously registered action handler.
+     */
+    unregisterAction(intentId: string): void;
+    /**
+     * Returns action registration metadata for all registered actions.
+     */
+    getRegisteredActions(): Record<string, ActionRegistration>;
+    /**
+     * Dispatches a registered action handler with current snapshot context.
+     */
+    dispatchAction(intentId: string, nodeId: string): void | Promise<void>;
+}
+/**
+ * Helper interface for dependency injection and test doubles.
+ */
+export interface SessionFactory {
+    /**
+     * Creates a fresh session.
+     */
+    createSession(options?: SessionOptions): Session;
+    /**
+     * Reconstructs a session from serialized data.
+     */
+    deserialize(data: unknown, options?: SessionOptions): Session;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

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

package/lib/types.js

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

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@continuum-dev/session",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Session lifecycle manager for the Continuum continuity runtime",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brytoncooper/cooper-continuum.git",
+    "directory": "packages/session"
+  },
+  "author": "CooperContinuum",
+  "keywords": [
+    "continuum",
+    "ai",
+    "ui",
+    "continuity",
+    "reconciliation",
+    "session",
+    "lifecycle"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "**/*.js",
+    "**/*.d.ts",
+    "**/*.d.ts.map",
+    "README.md",
+    "LICENSE*"
+  ],
+  "dependencies": {
+    "@continuum-dev/contract": "^0.1.0",
+    "@continuum-dev/runtime": "^0.1.0"
+  }
+}