hyperstack-react 0.4.2 → 0.5.0

package/dist/index.js

@@ -7075,6 +7075,31 @@ class FrameProcessor {
             ? DEFAULT_MAX_ENTRIES_PER_VIEW
             : config.maxEntriesPerView;
         this.flushIntervalMs = config.flushIntervalMs ?? 0;
+        this.schemas = config.schemas;
+    }
+    getSchema(viewPath) {
+        const schemas = this.schemas;
+        if (!schemas)
+            return null;
+        const entityName = viewPath.split('/')[0];
+        if (typeof entityName !== 'string' || entityName.length === 0)
+            return null;
+        const entityKey = entityName;
+        return schemas[entityKey] ?? null;
+    }
+    validateEntity(viewPath, data) {
+        const schema = this.getSchema(viewPath);
+        if (!schema)
+            return true;
+        const result = schema.safeParse(data);
+        if (!result.success) {
+            console.warn('[Hyperstack] Frame validation failed:', {
+                view: viewPath,
+                error: result.error,
+            });
+            return false;
+        }
+        return true;
     }
     handleFrame(frame) {
         if (this.flushIntervalMs === 0) {
@@ -7170,6 +7195,9 @@ class FrameProcessor {
     handleSnapshotFrameWithoutEnforce(frame) {
         const viewPath = frame.entity;
         for (const entity of frame.data) {
+            if (!this.validateEntity(viewPath, entity.data)) {
+                continue;
+            }
             const previousValue = this.storage.get(viewPath, entity.key);
             this.storage.set(viewPath, entity.key, entity.data);
             this.storage.notifyUpdate(viewPath, entity.key, {
@@ -7190,6 +7218,9 @@ class FrameProcessor {
         switch (frame.op) {
             case 'create':
             case 'upsert':
+                if (!this.validateEntity(viewPath, frame.data)) {
+                    break;
+                }
                 this.storage.set(viewPath, frame.key, frame.data);
                 this.storage.notifyUpdate(viewPath, frame.key, {
                     type: 'upsert',
@@ -7204,6 +7235,9 @@ class FrameProcessor {
                 const merged = existing
                     ? deepMergeWithAppend$1(existing, frame.data, appendPaths)
                     : frame.data;
+                if (!this.validateEntity(viewPath, merged)) {
+                    break;
+                }
                 this.storage.set(viewPath, frame.key, merged);
                 this.storage.notifyUpdate(viewPath, frame.key, {
                     type: 'patch',
@@ -7692,7 +7726,8 @@ function createUpdateStream(storage, subscriptionRegistry, subscription, keyFilt
         },
     };
 }
-function createEntityStream(storage, subscriptionRegistry, subscription, keyFilter) {
+function createEntityStream(storage, subscriptionRegistry, subscription, options, keyFilter) {
+    const schema = options?.schema;
     return {
         [Symbol.asyncIterator]() {
             const queue = [];
@@ -7708,16 +7743,27 @@ function createEntityStream(storage, subscriptionRegistry, subscription, keyFilt
                 if (update.type === 'deleted')
                     return;
                 const entity = (update.type === 'created' ? update.data : update.after);
+                let output;
+                if (schema) {
+                    const parsed = schema.safeParse(entity);
+                    if (!parsed.success) {
+                        return;
+                    }
+                    output = parsed.data;
+                }
+                else {
+                    output = entity;
+                }
                 if (waitingResolve) {
                     const resolve = waitingResolve;
                     waitingResolve = null;
-                    resolve({ value: entity, done: false });
+                    resolve({ value: output, done: false });
                 }
                 else {
                     if (queue.length >= MAX_QUEUE_SIZE) {
                         queue.shift();
                     }
-                    queue.push(entity);
+                    queue.push(output);
                 }
             };
             const start = () => {
@@ -7730,7 +7776,7 @@ function createEntityStream(storage, subscriptionRegistry, subscription, keyFilt
                 unsubscribeRegistry?.();
             };
             start();
-            return {
+            const iterator = {
                 async next() {
                     if (done) {
                         return { value: undefined, done: true };
@@ -7752,6 +7798,7 @@ function createEntityStream(storage, subscriptionRegistry, subscription, keyFilt
                     throw error;
                 },
             };
+            return iterator;
         },
     };
 }
@@ -7823,13 +7870,16 @@ function createRichUpdateStream(storage, subscriptionRegistry, subscription, key
 function createTypedStateView(viewDef, storage, subscriptionRegistry) {
     return {
         use(key, options) {
-            return createEntityStream(storage, subscriptionRegistry, { view: viewDef.view, key, ...options }, key);
+            const { schema: _schema, ...subscriptionOptions } = options ?? {};
+            return createEntityStream(storage, subscriptionRegistry, { view: viewDef.view, key, ...subscriptionOptions }, options, key);
         },
         watch(key, options) {
-            return createUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key, ...options }, key);
+            const { schema: _schema, ...subscriptionOptions } = options ?? {};
+            return createUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key, ...subscriptionOptions }, key);
         },
         watchRich(key, options) {
-            return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key, ...options }, key);
+            const { schema: _schema, ...subscriptionOptions } = options ?? {};
+            return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key, ...subscriptionOptions }, key);
         },
         async get(key) {
             return storage.get(viewDef.view, key);
@@ -7842,13 +7892,16 @@ function createTypedStateView(viewDef, storage, subscriptionRegistry) {
 function createTypedListView(viewDef, storage, subscriptionRegistry) {
     return {
         use(options) {
-            return createEntityStream(storage, subscriptionRegistry, { view: viewDef.view, ...options });
+            const { schema: _schema, ...subscriptionOptions } = options ?? {};
+            return createEntityStream(storage, subscriptionRegistry, { view: viewDef.view, ...subscriptionOptions }, options);
         },
         watch(options) {
-            return createUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...options });
+            const { schema: _schema, ...subscriptionOptions } = options ?? {};
+            return createUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...subscriptionOptions });
         },
         watchRich(options) {
-            return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...options });
+            const { schema: _schema, ...subscriptionOptions } = options ?? {};
+            return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...subscriptionOptions });
         },
         async get() {
             return storage.getAll(viewDef.view);
@@ -7876,39 +7929,335 @@ function createTypedViews(stack, storage, subscriptionRegistry) {
     return views;
 }
 
+/**
+ * PDA (Program Derived Address) derivation utilities.
+ *
+ * Implements Solana's PDA derivation algorithm without depending on @solana/web3.js.
+ */
+// Base58 alphabet (Bitcoin/Solana style)
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+/**
+ * Decode base58 string to Uint8Array.
+ */
+function decodeBase58(str) {
+    if (str.length === 0) {
+        return new Uint8Array(0);
+    }
+    const bytes = [0];
+    for (const char of str) {
+        const value = BASE58_ALPHABET.indexOf(char);
+        if (value === -1) {
+            throw new Error('Invalid base58 character: ' + char);
+        }
+        let carry = value;
+        for (let i = 0; i < bytes.length; i++) {
+            carry += (bytes[i] ?? 0) * 58;
+            bytes[i] = carry & 0xff;
+            carry >>= 8;
+        }
+        while (carry > 0) {
+            bytes.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    // Add leading zeros for each leading '1' in input
+    for (const char of str) {
+        if (char !== '1')
+            break;
+        bytes.push(0);
+    }
+    return new Uint8Array(bytes.reverse());
+}
+/**
+ * Encode Uint8Array to base58 string.
+ */
+function encodeBase58(bytes) {
+    if (bytes.length === 0) {
+        return '';
+    }
+    const digits = [0];
+    for (const byte of bytes) {
+        let carry = byte;
+        for (let i = 0; i < digits.length; i++) {
+            carry += (digits[i] ?? 0) << 8;
+            digits[i] = carry % 58;
+            carry = (carry / 58) | 0;
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = (carry / 58) | 0;
+        }
+    }
+    // Add leading zeros for each leading 0 byte in input
+    for (const byte of bytes) {
+        if (byte !== 0)
+            break;
+        digits.push(0);
+    }
+    return digits.reverse().map(d => BASE58_ALPHABET[d]).join('');
+}
+/**
+ * SHA-256 hash function (synchronous, Node.js).
+ */
+function sha256Sync(data) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { createHash } = require('crypto');
+    return new Uint8Array(createHash('sha256').update(Buffer.from(data)).digest());
+}
+/**
+ * SHA-256 hash function (async, works in browser and Node.js).
+ */
+async function sha256Async(data) {
+    if (typeof globalThis !== 'undefined' && globalThis.crypto && globalThis.crypto.subtle) {
+        // Create a copy of the data to ensure we have an ArrayBuffer
+        const copy = new Uint8Array(data);
+        const hashBuffer = await globalThis.crypto.subtle.digest('SHA-256', copy);
+        return new Uint8Array(hashBuffer);
+    }
+    return sha256Sync(data);
+}
+/**
+ * PDA marker bytes appended to seeds before hashing.
+ */
+const PDA_MARKER = new TextEncoder().encode('ProgramDerivedAddress');
+/**
+ * Build the hash input buffer for PDA derivation.
+ */
+function buildPdaBuffer(seeds, programIdBytes, bump) {
+    const totalLength = seeds.reduce((sum, s) => sum + s.length, 0)
+        + 1 // bump
+        + 32 // programId
+        + PDA_MARKER.length;
+    const buffer = new Uint8Array(totalLength);
+    let offset = 0;
+    // Copy seeds
+    for (const seed of seeds) {
+        buffer.set(seed, offset);
+        offset += seed.length;
+    }
+    // Add bump seed
+    buffer[offset++] = bump;
+    // Add program ID
+    buffer.set(programIdBytes, offset);
+    offset += 32;
+    // Add PDA marker
+    buffer.set(PDA_MARKER, offset);
+    return buffer;
+}
+/**
+ * Validate seeds before PDA derivation.
+ */
+function validateSeeds(seeds) {
+    if (seeds.length > 16) {
+        throw new Error('Maximum of 16 seeds allowed');
+    }
+    for (let i = 0; i < seeds.length; i++) {
+        const seed = seeds[i];
+        if (seed && seed.length > 32) {
+            throw new Error('Seed ' + i + ' exceeds maximum length of 32 bytes');
+        }
+    }
+}
+/**
+ * Derives a Program-Derived Address (PDA) from seeds and program ID.
+ *
+ * Algorithm:
+ * 1. For bump = 255 down to 0:
+ *    a. Concatenate: seeds + [bump] + programId + "ProgramDerivedAddress"
+ *    b. SHA-256 hash the concatenation
+ *    c. If result is off the ed25519 curve, return it
+ * 2. If no valid PDA found after 256 attempts, throw error
+ *
+ * @param seeds - Array of seed buffers (max 32 bytes each, max 16 seeds)
+ * @param programId - The program ID (base58 string)
+ * @returns Tuple of [derivedAddress (base58), bumpSeed]
+ */
+async function findProgramAddress(seeds, programId) {
+    validateSeeds(seeds);
+    const programIdBytes = decodeBase58(programId);
+    if (programIdBytes.length !== 32) {
+        throw new Error('Program ID must be 32 bytes');
+    }
+    // Try bump seeds from 255 down to 0
+    for (let bump = 255; bump >= 0; bump--) {
+        const buffer = buildPdaBuffer(seeds, programIdBytes, bump);
+        const hash = await sha256Async(buffer);
+        {
+            return [encodeBase58(hash), bump];
+        }
+    }
+    throw new Error('Unable to find a valid PDA');
+}
+/**
+ * Synchronous version of findProgramAddress.
+ * Uses synchronous SHA-256 (Node.js crypto module).
+ */
+function findProgramAddressSync(seeds, programId) {
+    validateSeeds(seeds);
+    const programIdBytes = decodeBase58(programId);
+    if (programIdBytes.length !== 32) {
+        throw new Error('Program ID must be 32 bytes');
+    }
+    // Try bump seeds from 255 down to 0
+    for (let bump = 255; bump >= 0; bump--) {
+        const buffer = buildPdaBuffer(seeds, programIdBytes, bump);
+        const hash = sha256Sync(buffer);
+        {
+            return [encodeBase58(hash), bump];
+        }
+    }
+    throw new Error('Unable to find a valid PDA');
+}
+/**
+ * Creates a seed buffer from various input types.
+ *
+ * @param value - The value to convert to a seed
+ * @returns Uint8Array suitable for PDA derivation
+ */
+function createSeed(value) {
+    if (value instanceof Uint8Array) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        return new TextEncoder().encode(value);
+    }
+    if (typeof value === 'bigint') {
+        // Convert bigint to 8-byte buffer (u64 little-endian)
+        const buffer = new Uint8Array(8);
+        let n = value;
+        for (let i = 0; i < 8; i++) {
+            buffer[i] = Number(n & BigInt(0xff));
+            n >>= BigInt(8);
+        }
+        return buffer;
+    }
+    if (typeof value === 'number') {
+        // Assume u64
+        return createSeed(BigInt(value));
+    }
+    throw new Error('Cannot create seed from value');
+}
+/**
+ * Creates a public key seed from a base58-encoded address.
+ *
+ * @param address - Base58-encoded public key
+ * @returns 32-byte Uint8Array
+ */
+function createPublicKeySeed(address) {
+    const decoded = decodeBase58(address);
+    if (decoded.length !== 32) {
+        throw new Error('Invalid public key length: expected 32, got ' + decoded.length);
+    }
+    return decoded;
+}
+
+/**
+ * Topologically sort accounts so that dependencies (accountRef) are resolved first.
+ * Non-PDA accounts come first, then PDAs in dependency order.
+ */
+function sortAccountsByDependency(accountMetas) {
+    // Separate non-PDA and PDA accounts
+    const nonPda = [];
+    const pda = [];
+    for (const meta of accountMetas) {
+        if (meta.category === 'pda') {
+            pda.push(meta);
+        }
+        else {
+            nonPda.push(meta);
+        }
+    }
+    // Build dependency graph for PDAs
+    const pdaDeps = new Map();
+    for (const meta of pda) {
+        const deps = new Set();
+        if (meta.pdaConfig) {
+            for (const seed of meta.pdaConfig.seeds) {
+                if (seed.type === 'accountRef') {
+                    deps.add(seed.accountName);
+                }
+            }
+        }
+        pdaDeps.set(meta.name, deps);
+    }
+    // Topological sort PDAs
+    const sortedPda = [];
+    const visited = new Set();
+    const visiting = new Set();
+    function visit(name) {
+        if (visited.has(name))
+            return;
+        if (visiting.has(name)) {
+            throw new Error('Circular dependency in PDA accounts: ' + name);
+        }
+        const meta = pda.find(m => m.name === name);
+        if (!meta)
+            return; // Not a PDA, skip
+        visiting.add(name);
+        const deps = pdaDeps.get(name) || new Set();
+        for (const dep of deps) {
+            // Only visit if dep is also a PDA
+            if (pda.some(m => m.name === dep)) {
+                visit(dep);
+            }
+        }
+        visiting.delete(name);
+        visited.add(name);
+        sortedPda.push(meta);
+    }
+    for (const meta of pda) {
+        visit(meta.name);
+    }
+    return [...nonPda, ...sortedPda];
+}
 /**
  * Resolves instruction accounts by categorizing and deriving addresses.
  *
+ * Resolution order:
+ * 1. Non-PDA accounts (signer, known, userProvided) are resolved first
+ * 2. PDA accounts are resolved in dependency order (accounts they reference come first)
+ *
  * @param accountMetas - Account metadata from the instruction definition
- * @param args - Instruction arguments (used for PDA derivation)
- * @param options - Resolution options including wallet and user-provided accounts
+ * @param args - Instruction arguments (used for PDA derivation with argRef seeds)
+ * @param options - Resolution options including wallet, user-provided accounts, and programId
  * @returns Resolved accounts and any missing required accounts
  */
 function resolveAccounts(accountMetas, args, options) {
-    const resolved = [];
+    // Sort accounts by dependency
+    const sorted = sortAccountsByDependency(accountMetas);
+    // Track resolved accounts for PDA accountRef lookups
+    const resolvedMap = {};
     const missing = [];
-    for (const meta of accountMetas) {
-        const resolvedAccount = resolveSingleAccount(meta, args, options);
+    for (const meta of sorted) {
+        const resolvedAccount = resolveSingleAccount(meta, args, options, resolvedMap);
         if (resolvedAccount) {
-            resolved.push(resolvedAccount);
+            resolvedMap[meta.name] = resolvedAccount;
         }
         else if (!meta.isOptional) {
             missing.push(meta.name);
         }
     }
+    // Return accounts in original order (as defined in accountMetas)
+    const orderedAccounts = [];
+    for (const meta of accountMetas) {
+        const resolved = resolvedMap[meta.name];
+        if (resolved) {
+            orderedAccounts.push(resolved);
+        }
+    }
     return {
-        accounts: resolved,
+        accounts: orderedAccounts,
         missingUserAccounts: missing,
     };
 }
-function resolveSingleAccount(meta, args, options) {
+function resolveSingleAccount(meta, args, options, resolvedMap) {
     switch (meta.category) {
         case 'signer':
             return resolveSignerAccount(meta, options.wallet);
         case 'known':
             return resolveKnownAccount(meta);
         case 'pda':
-            return resolvePdaAccount(meta);
+            return resolvePdaAccount(meta, args, resolvedMap, options.programId);
         case 'userProvided':
             return resolveUserProvidedAccount(meta, options.accounts);
         default:
@@ -7937,15 +8286,51 @@ function resolveKnownAccount(meta) {
         isWritable: meta.isWritable,
     };
 }
-function resolvePdaAccount(meta, args) {
+function resolvePdaAccount(meta, args, resolvedMap, programId) {
     if (!meta.pdaConfig) {
         return null;
     }
-    // PDA derivation will be implemented in pda.ts
-    // For now, return a placeholder that will be resolved later
+    // Determine which program to derive against
+    const pdaProgramId = meta.pdaConfig.programId || programId;
+    if (!pdaProgramId) {
+        throw new Error('Cannot derive PDA for "' + meta.name + '": no programId specified. ' +
+            'Either set pdaConfig.programId or pass programId in options.');
+    }
+    // Build seeds array
+    const seeds = [];
+    for (const seed of meta.pdaConfig.seeds) {
+        switch (seed.type) {
+            case 'literal':
+                seeds.push(createSeed(seed.value));
+                break;
+            case 'argRef': {
+                const argValue = args[seed.argName];
+                if (argValue === undefined) {
+                    throw new Error('PDA seed references missing argument: ' + seed.argName +
+                        ' (for account "' + meta.name + '")');
+                }
+                seeds.push(createSeed(argValue));
+                break;
+            }
+            case 'accountRef': {
+                const refAccount = resolvedMap[seed.accountName];
+                if (!refAccount) {
+                    throw new Error('PDA seed references unresolved account: ' + seed.accountName +
+                        ' (for account "' + meta.name + '")');
+                }
+                // Account addresses are 32 bytes
+                seeds.push(decodeBase58(refAccount.address));
+                break;
+            }
+            default:
+                throw new Error('Unknown seed type');
+        }
+    }
+    // Derive the PDA
+    const [derivedAddress] = findProgramAddressSync(seeds, pdaProgramId);
     return {
         name: meta.name,
-        address: '', // Will be derived
+        address: derivedAddress,
         isSigner: meta.isSigner,
         isWritable: meta.isWritable,
     };
@@ -7970,86 +8355,10 @@ function resolveUserProvidedAccount(meta, accounts) {
  */
 function validateAccountResolution(result) {
     if (result.missingUserAccounts.length > 0) {
-        throw new Error(`Missing required accounts: ${result.missingUserAccounts.join(', ')}`);
+        throw new Error('Missing required accounts: ' + result.missingUserAccounts.join(', '));
     }
 }
 
-/**
- * Derives a Program-Derived Address (PDA) from seeds and program ID.
- *
- * This function implements PDA derivation using the Solana algorithm:
- * 1. Concatenate all seeds
- * 2. Hash with SHA-256
- * 3. Check if result is off-curve (valid PDA)
- *
- * Note: This is a placeholder implementation. In production, you would use
- * the actual Solana web3.js library's PDA derivation.
- *
- * @param seeds - Array of seed buffers
- * @param programId - The program ID (as base58 string)
- * @returns The derived PDA address (base58 string)
- */
-async function derivePda(seeds, programId) {
-    // In production, this would use:
-    // PublicKey.findProgramAddressSync(seeds, new PublicKey(programId))
-    // For now, return a placeholder that will be replaced with actual implementation
-    const combined = Buffer.concat(seeds);
-    // Simulate PDA derivation (this is NOT the actual algorithm)
-    const hash = await simulateHash(combined);
-    // Return base58-encoded address
-    return bs58Encode(hash);
-}
-/**
- * Creates a seed buffer from various input types.
- *
- * @param value - The value to convert to a seed
- * @returns Buffer suitable for PDA derivation
- */
-function createSeed(value) {
-    if (Buffer.isBuffer(value)) {
-        return value;
-    }
-    if (value instanceof Uint8Array) {
-        return Buffer.from(value);
-    }
-    if (typeof value === 'string') {
-        return Buffer.from(value, 'utf-8');
-    }
-    if (typeof value === 'bigint') {
-        // Convert bigint to 8-byte buffer (u64)
-        const buffer = Buffer.alloc(8);
-        buffer.writeBigUInt64LE(value);
-        return buffer;
-    }
-    throw new Error(`Cannot create seed from type: ${typeof value}`);
-}
-/**
- * Creates a public key seed from a base58-encoded address.
- *
- * @param address - Base58-encoded public key
- * @returns 32-byte buffer
- */
-function createPublicKeySeed(address) {
-    // In production, decode base58 to 32-byte buffer
-    // For now, return placeholder
-    return Buffer.alloc(32);
-}
-async function simulateHash(data) {
-    // In production, use actual SHA-256
-    // This is a placeholder
-    if (typeof crypto !== 'undefined' && crypto.subtle) {
-        const hashBuffer = await crypto.subtle.digest('SHA-256', data);
-        return Buffer.from(hashBuffer);
-    }
-    // Fallback for Node.js
-    return Buffer.alloc(32, 0);
-}
-function bs58Encode(buffer) {
-    // In production, use actual base58 encoding
-    // This is a placeholder
-    return 'P' + buffer.toString('hex').slice(0, 31);
-}
-
 /**
  * Borsh-compatible instruction data serializer.
  *
@@ -8140,6 +8449,7 @@ function serializePrimitive(value, type) {
             strLen.writeUInt32LE(strBytes.length, 0);
             return Buffer.concat([strLen, strBytes]);
         case 'pubkey':
+            // Public key is 32 bytes
             // In production, decode base58 to 32 bytes
             return Buffer.alloc(32, 0);
         default:
@@ -8192,7 +8502,7 @@ async function waitForConfirmation(signature, level = 'confirmed', timeout = 600
     }
     throw new Error(`Transaction confirmation timeout after ${timeout}ms`);
 }
-async function checkTransactionStatus(signature) {
+async function checkTransactionStatus(_signature) {
     // In production, query the Solana RPC
     return {
         err: null,
@@ -8308,6 +8618,7 @@ async function executeInstruction(handler, args, options = {}) {
     const resolutionOptions = {
         accounts: options.accounts,
         wallet: options.wallet,
+        programId: handler.programId, // Pass programId for PDA derivation
     };
     const resolution = resolveAccounts(handler.accounts, args, resolutionOptions);
     validateAccountResolution(resolution);
@@ -8373,6 +8684,7 @@ class HyperStack {
         this.processor = new FrameProcessor(this.storage, {
             maxEntriesPerView: options.maxEntriesPerView,
             flushIntervalMs: options.flushIntervalMs,
+            schemas: options.validateFrames ? this.stack.schemas : undefined,
         });
         this.connection = new ConnectionManager({
             websocketUrl: url,
@@ -8410,6 +8722,7 @@ class HyperStack {
             autoReconnect: options?.autoReconnect,
             reconnectIntervals: options?.reconnectIntervals,
             maxReconnectAttempts: options?.maxReconnectAttempts,
+            validateFrames: options?.validateFrames,
         };
         const client = new HyperStack(url, internalOptions);
         if (options?.autoReconnect !== false) {
@@ -8634,6 +8947,16 @@ const HyperstackContext = React.createContext(null);
 function HyperstackProvider({ children, fallback = null, ...config }) {
     const clientsRef = React.useRef(new Map());
     const connectingRef = React.useRef(new Map());
+    const clientChangeListenersRef = React.useRef(new Set());
+    const notifyClientChange = React.useCallback(() => {
+        clientChangeListenersRef.current.forEach(cb => { cb(); });
+    }, []);
+    const subscribeToClientChanges = React.useCallback((callback) => {
+        clientChangeListenersRef.current.add(callback);
+        return () => {
+            clientChangeListenersRef.current.delete(callback);
+        };
+    }, []);
     const getOrCreateClient = React.useCallback(async (stack, urlOverride) => {
         const cacheKey = urlOverride ? `${stack.name}:${urlOverride}` : stack.name;
         const existing = clientsRef.current.get(cacheKey);
@@ -8663,14 +8986,20 @@ function HyperstackProvider({ children, fallback = null, ...config }) {
                 disconnect: () => client.disconnect()
             });
             connectingRef.current.delete(cacheKey);
+            notifyClientChange();
             return client;
         });
         connectingRef.current.set(cacheKey, connectionPromise);
         return connectionPromise;
-    }, [config.autoConnect, config.reconnectIntervals, config.maxReconnectAttempts, config.maxEntriesPerView]);
+    }, [config.autoConnect, config.reconnectIntervals, config.maxReconnectAttempts, config.maxEntriesPerView, notifyClientChange]);
     const getClient = React.useCallback((stack) => {
-        if (!stack)
+        if (!stack) {
+            if (clientsRef.current.size === 1) {
+                const firstEntry = clientsRef.current.values().next().value;
+                return firstEntry ? firstEntry.client : null;
+            }
             return null;
+        }
         const entry = clientsRef.current.get(stack.name);
         return entry ? entry.client : null;
     }, []);
@@ -8686,6 +9015,7 @@ function HyperstackProvider({ children, fallback = null, ...config }) {
     const value = {
         getOrCreateClient,
         getClient,
+        subscribeToClientChanges,
         config,
     };
     return (React.createElement(HyperstackContext.Provider, { value: value }, children));
@@ -8698,13 +9028,38 @@ function useHyperstackContext() {
     return context;
 }
 function useConnectionState(stack) {
-    const { getClient } = useHyperstackContext();
-    const client = stack ? getClient(stack) : null;
-    return React.useSyncExternalStore((callback) => {
-        if (!client)
-            return () => { };
-        return client.onConnectionStateChange(callback);
-    }, () => client?.connectionState ?? 'disconnected');
+    const { getClient, subscribeToClientChanges } = useHyperstackContext();
+    const [state, setState] = React.useState(() => {
+        const client = getClient(stack);
+        return client?.connectionState ?? 'disconnected';
+    });
+    const unsubscribeRef = React.useRef(undefined);
+    React.useEffect(() => {
+        let mounted = true;
+        const setupClientSubscription = () => {
+            unsubscribeRef.current?.();
+            unsubscribeRef.current = undefined;
+            const client = getClient(stack);
+            if (client && mounted) {
+                setState(client.connectionState);
+                unsubscribeRef.current = client.onConnectionStateChange((newState) => {
+                    if (mounted)
+                        setState(newState);
+                });
+            }
+            else if (mounted) {
+                setState('disconnected');
+            }
+        };
+        const unsubscribeFromClientChanges = subscribeToClientChanges(setupClientSubscription);
+        setupClientSubscription();
+        return () => {
+            mounted = false;
+            unsubscribeFromClientChanges();
+            unsubscribeRef.current?.();
+        };
+    }, [getClient, subscribeToClientChanges, stack]);
+    return state;
 }
 function useView(stack, viewPath) {
     const { getClient } = useHyperstackContext();
@@ -8756,6 +9111,7 @@ function useStateView(viewDef, client, key, options) {
     const cachedSnapshotRef = React.useRef(undefined);
     const keyString = key ? Object.values(key)[0] : undefined;
     const enabled = options?.enabled !== false;
+    const schema = options?.schema;
     React.useEffect(() => {
         if (!enabled || !clientRef.current)
             return undefined;
@@ -8810,12 +9166,14 @@ function useStateView(viewDef, client, key, options) {
         const entity = keyString
             ? clientRef.current.store.get(viewDef.view, keyString)
             : clientRef.current.store.getAll(viewDef.view)[0];
-        // Cache the result to return stable reference for useSyncExternalStore
-        if (entity !== cachedSnapshotRef.current) {
-            cachedSnapshotRef.current = entity;
+        const validated = entity && schema
+            ? (schema.safeParse(entity).success ? entity : undefined)
+            : entity;
+        if (validated !== cachedSnapshotRef.current) {
+            cachedSnapshotRef.current = validated;
         }
         return cachedSnapshotRef.current;
-    }, [viewDef.view, keyString, client]);
+    }, [viewDef.view, keyString, schema, client]);
     const data = React.useSyncExternalStore(subscribe, getSnapshot);
     React.useEffect(() => {
         if (data !== undefined && isLoading) {
@@ -8842,6 +9200,7 @@ function useListView(viewDef, client, params, options) {
     const whereJson = params?.where ? JSON.stringify(params.where) : undefined;
     const filtersJson = params?.filters ? JSON.stringify(params.filters) : undefined;
     const limit = params?.limit;
+    const schema = params?.schema;
     React.useEffect(() => {
         if (!enabled || !clientRef.current)
             return undefined;
@@ -8932,16 +9291,18 @@ function useListView(viewDef, client, params, options) {
                 });
             });
         }
+        if (schema) {
+            items = items.filter((item) => schema.safeParse(item).success);
+        }
         if (limit) {
             items = items.slice(0, limit);
         }
         const result = items;
-        // Cache the result - only update if data actually changed
         if (!shallowArrayEqual(cachedSnapshotRef.current, result)) {
             cachedSnapshotRef.current = result;
         }
         return cachedSnapshotRef.current;
-    }, [viewDef.view, whereJson, limit, client]);
+    }, [viewDef.view, whereJson, limit, schema, client]);
     const data = React.useSyncExternalStore(subscribe, getSnapshot);
     React.useEffect(() => {
         if (data !== undefined && isLoading) {
@@ -9040,6 +9401,7 @@ function useHyperstack(stack, options) {
     const [client, setClient] = React.useState(getClient(stack));
     const [isLoading, setIsLoading] = React.useState(!client);
     const [error, setError] = React.useState(null);
+    const [connectionState, setConnectionState] = React.useState(() => client?.connectionState ?? 'disconnected');
     React.useEffect(() => {
         const existingClient = getClient(stack);
         if (existingClient && !urlOverride) {
@@ -9059,6 +9421,17 @@ function useHyperstack(stack, options) {
             setIsLoading(false);
         });
     }, [stack, getOrCreateClient, getClient, urlOverride]);
+    React.useEffect(() => {
+        if (!client) {
+            setConnectionState('disconnected');
+            return;
+        }
+        setConnectionState(client.connectionState);
+        const unsubscribe = client.onConnectionStateChange((state) => {
+            setConnectionState(state);
+        });
+        return unsubscribe;
+    }, [client]);
     const views = React.useMemo(() => {
         const result = {};
         for (const [viewName, viewGroup] of Object.entries(stack.views)) {
@@ -9095,6 +9468,8 @@ function useHyperstack(stack, options) {
         instructions: instructions,
         zustandStore: client?.store?.store,
         client: client,
+        connectionState,
+        isConnected: connectionState === 'connected',
         isLoading,
         error
     };
@@ -9113,7 +9488,7 @@ exports.ZustandAdapter = ZustandAdapter;
 exports.createInstructionExecutor = createInstructionExecutor;
 exports.createPublicKeySeed = createPublicKeySeed;
 exports.createSeed = createSeed;
-exports.derivePda = derivePda;
+exports.derivePda = findProgramAddress;
 exports.executeInstruction = executeInstruction;
 exports.formatProgramError = formatProgramError;
 exports.isSnapshotFrame = isSnapshotFrame;