@adaas/a-frame 0.1.1 → 0.1.2

package/src/lib/A-FrameStorage/browser/A-FrameBrowserStorage.component.ts

@@ -229,6 +229,17 @@ export class A_FrameBrowserStorageProvider extends A_FrameStorage {
         @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
         @A_Inject(A_FrameBrowserStorageBlobs) blobs: A_FrameBrowserStorageBlobs,
     ): Promise<void> {
+        // ── 1. Check plain record store (pre-built bundle, no key needed) ───────
+        const plainRecords = blobs.plainStore.get(definition.namespace.id);
+        if (plainRecords?.length) {
+            const record = plainRecords.find(r => r.aseid === definition.aseid.toString());
+            if (record && record.hash === definition.hash) {
+                definition.fromJSON(record);
+                return;
+            }
+        }
+
+        // ── 2. Fall back to encrypted blob store (live session) ──────────────────
         if (!context.encryptionKey) return;
 
         const records = await this._loadDefinitionsFromMemory(
@@ -261,6 +272,16 @@ export class A_FrameBrowserStorageProvider extends A_FrameStorage {
         @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
         @A_Inject(A_FrameBrowserStorageBlobs) blobs: A_FrameBrowserStorageBlobs,
     ): Promise<void> {
+        // ── 1. Check plain record store (pre-built bundle, no key needed) ───────
+        if (blobs.plainNamespaceRecords?.length) {
+            const record = blobs.plainNamespaceRecords.find(r => r.aseid === namespace.aseid.toString());
+            if (record && record.hash === namespace.hash) {
+                namespace.fromJSON(record);
+                return;
+            }
+        }
+
+        // ── 2. Fall back to encrypted blob store (live session) ──────────────────
         if (!context.encryptionKey) return;
 
         const records = await this._loadNamespacesFromMemory(blobs, context.encryptionKey, codec);

package/src/lib/A-FrameStorage/browser/A-FrameBrowserStorageBlobs.context.ts

@@ -5,19 +5,8 @@
 
 import { A_Fragment } from "@adaas/a-concept";
 import type { A_FrameBundle } from "@adaas/a-frame/bundle";
-
-
-/** Browser-safe base64 → Uint8Array (uses globalThis.atob; falls back to Buffer in Node tests). */
-function decodeBase64(b64: string): Uint8Array {
-    if (typeof atob === 'function') {
-        const bin = atob(b64);
-        const out = new Uint8Array(bin.length);
-        for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
-        return out;
-    }
-    // Node fallback so the same fragment works in Jest/SSR.
-    return new Uint8Array(Buffer.from(b64, 'base64'));
-}
+import type { A_FrameDefinition_Serialized } from "../../A-FrameDefinition/A-FrameDefinition.types";
+import type { A_FrameNamespace_Serialized } from "../../A-FrameNamespace/A-FrameNamespace.types";
 
 
 export class A_FrameBrowserStorageBlobs extends A_Fragment {
@@ -48,30 +37,59 @@ export class A_FrameBrowserStorageBlobs extends A_Fragment {
         super({ name: 'a-frame-browser-storage-blobs' });
     }
 
-    /** namespace → encrypted definition bytes */
+    // ─── Encrypted blob store (live session writes) ───────────────────────────
+
+    /** namespace → encrypted definition bytes (written during live browser session) */
     readonly store = new Map<string, Uint8Array>();
 
     /** encrypted bytes for the namespace index (`__namespaces.aframe` equivalent) */
     namespaceBlob: Uint8Array | null = null;
 
+    // ─── Plain record store (populated from pre-built bundle) ─────────────────
+
+    /**
+     * namespace → decoded definition records loaded from a pre-built bundle.
+     * No encryption key needed — records are stored as plain JSON-friendly objects.
+     * Takes precedence over the encrypted `store` during load.
+     */
+    readonly plainStore = new Map<string, A_FrameDefinition_Serialized[]>();
+
+    /** Decoded namespace records from the bundle. */
+    plainNamespaceRecords: A_FrameNamespace_Serialized[] | null = null;
+
     /** Bundle metadata recorded at seed time, used by A_Frame to validate versions. */
     bundleMeta: { aFrameVersion: string; serverVersion: string; builtAt: string } | null = null;
 
+    /** Returns true when a pre-built bundle has been seeded into plainStore. */
+    get hasBundleData(): boolean {
+        return this.plainStore.size > 0 || (this.plainNamespaceRecords?.length ?? 0) > 0;
+    }
+
     /**
-     * Populate the store from a bundle artifact. Existing entries with the
-     * same namespace are overwritten; unrelated entries are preserved.
+     * Populate the plain record store from a bundle artifact.
+     * Existing entries with the same namespace are overwritten; unrelated entries preserved.
+     * No encryption key is required — the bundle stores decoded plain records.
      */
     seedFromBundle(bundle: A_FrameBundle): void {
-        if (bundle.namespaces) {
-            this.namespaceBlob = decodeBase64(bundle.namespaces);
+        for (const [ns, recs] of Object.entries(bundle.records ?? {})) {
+            this.plainStore.set(ns, recs.map(r => ({
+                ...r,
+                // JSON stores embedding as number[] — convert to Float32Array for in-memory use
+                embedding: r.embedding.length > 0 ? new Float32Array(r.embedding) : undefined,
+            } as A_FrameDefinition_Serialized)));
         }
-        for (const [id, b64] of Object.entries(bundle.definitions)) {
-            this.store.set(id, decodeBase64(b64));
+
+        if (bundle.namespaceRecords?.length) {
+            this.plainNamespaceRecords = bundle.namespaceRecords.map(r => ({
+                ...r,
+                embedding: r.embedding.length > 0 ? new Float32Array(r.embedding) : undefined,
+            } as A_FrameNamespace_Serialized));
         }
+
         this.bundleMeta = {
             aFrameVersion: bundle.aFrameVersion,
             serverVersion: bundle.serverVersion,
             builtAt: bundle.builtAt,
         };
     }
-}
+}

package/src/lib/A-FrameStorage/node/A-FrameNodeStorage.component.ts

@@ -41,6 +41,27 @@ export class A_FrameNodeStorage extends A_FrameStorage {
         }
     }
 
+    /**
+     * Resolves extra storage directories by expanding each comma-separated glob
+     * pattern in `pattern`.  Returns an empty array when `pattern` is blank or
+     * when no paths match.  Errors from unsupported patterns are swallowed so
+     * that a bad env value never breaks the application.
+     */
+    private async listExtraStorageDirs(pattern: string): Promise<string[]> {
+        if (!pattern) return [];
+        const dirs: string[] = [];
+        for (const p of pattern.split(',').map(s => s.trim()).filter(Boolean)) {
+            try {
+                for await (const match of fs.glob(p)) {
+                    dirs.push(match);
+                }
+            } catch {
+                // unsupported pattern or no matches — skip silently
+            }
+        }
+        return dirs;
+    }
+
     //---------------------------------------------------------------------------------------
     //--------------------------Definition Features Extensions-------------------------------
     //---------------------------------------------------------------------------------------
@@ -69,7 +90,7 @@ export class A_FrameNodeStorage extends A_FrameStorage {
         if (!incoming.embedding)
             throw new Error('Only definitions with embeddings can be saved to storage');
 
-        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace.id)));
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getDefinitionsFileName(namespace.id)));
         const existing: A_FrameDefinition_Serialized[] = rawBuf
             ? codec.decodePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
             : [];
@@ -83,7 +104,7 @@ export class A_FrameNodeStorage extends A_FrameStorage {
         const encrypted = await aFrameCrypto.encryptBytes(payload, context.encryptionKey!);
 
         await fs.mkdir(env.A_FRAME_STORAGE_DIR, { recursive: true });
-        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace.id)), encrypted);
+        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getDefinitionsFileName(namespace.id)), encrypted);
     }
     /**
      * Load a single definition from local file storage. This is called as part of A_FrameDefinition.load() when using the local file storage provider. It reads the namespace file, finds the record for the requested definition, and if found and hash matches, populates the definition with the stored data.
@@ -99,23 +120,32 @@ export class A_FrameNodeStorage extends A_FrameStorage {
         @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
         @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
     ): Promise<void> {
-        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(definition.namespace.id)));
-        if (!rawBuf) return;
-
-        const plain = await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!);
-        const records = codec.decodePayload(plain);
-
-        const record = records.find(r => r.aseid === definition.aseid.toString());
-
-        if (
-            record &&
-            record.hash === definition.hash &&
-            record.aFrameServerVersion === context.serverVersion
-        ) {
-            definition.fromJSON(record);
+        // 1. Try primary storage dir
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getDefinitionsFileName(definition.namespace.id)));
+        if (rawBuf) {
+            const plain = await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!);
+            const record = codec.decodePayload(plain).find(r => r.aseid === definition.aseid.toString());
+            if (record && record.hash === definition.hash && record.aFrameServerVersion === context.serverVersion) {
+                definition.fromJSON(record);
+                return;
+            }
         }
 
-
+        // 2. Scan extra storage directories discovered via A_FRAME_STORAGE_PATTERN
+        for (const dir of await this.listExtraStorageDirs(env.A_FRAME_STORAGE_PATTERN)) {
+            const extraBuf = await this.tryReadFile(path.join(dir, codec.getDefinitionsFileName(definition.namespace.id)));
+            if (!extraBuf) continue;
+            try {
+                const plain = await aFrameCrypto.decryptBytes(new Uint8Array(extraBuf), context.encryptionKey!);
+                const record = codec.decodePayload(plain).find(r => r.aseid === definition.aseid.toString());
+                if (record && record.hash === definition.hash && record.aFrameServerVersion === context.serverVersion) {
+                    definition.fromJSON(record);
+                    return;
+                }
+            } catch {
+                // skip unreadable extra storage
+            }
+        }
     }
     /**
      * Delete a single definition from local file storage. This is called as part of A_FrameDefinition.destroy() when using the local file storage provider. It reads the namespace file, removes the record for the requested definition, and writes back the encrypted file.
@@ -137,7 +167,7 @@ export class A_FrameNodeStorage extends A_FrameStorage {
         @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
 
     ): Promise<void> {
-        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(definition.namespace.id)));
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getDefinitionsFileName(definition.namespace.id)));
         if (!rawBuf) return;
 
         const plain = await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!);
@@ -149,7 +179,7 @@ export class A_FrameNodeStorage extends A_FrameStorage {
         const encrypted = await aFrameCrypto.encryptBytes(payload, context.encryptionKey!);
 
         await fs.mkdir(env.A_FRAME_STORAGE_DIR, { recursive: true });
-        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(definition.namespace.id)), encrypted);
+        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getDefinitionsFileName(definition.namespace.id)), encrypted);
     }
 
     // ---------------------------------------------------------------------------------------
@@ -198,20 +228,31 @@ export class A_FrameNodeStorage extends A_FrameStorage {
         @A_Inject(A_FrameCrypto) aFrameCrypto: A_FrameCrypto,
         @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
     ): Promise<void> {
+        // 1. Try primary storage dir
         const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getNamespaceFileName()));
-        if (!rawBuf) return;
-
-        const plain = await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!);
-        const records = codec.decodeNamespacePayload(plain);
-
-        const record = records.find(r => r.aseid === namespace.aseid.toString());
+        if (rawBuf) {
+            const plain = await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!);
+            const record = codec.decodeNamespacePayload(plain).find(r => r.aseid === namespace.aseid.toString());
+            if (record && record.hash === namespace.hash && record.aFrameServerVersion === context.serverVersion) {
+                namespace.fromJSON(record);
+                return;
+            }
+        }
 
-        if (
-            record &&
-            record.hash === namespace.hash &&
-            record.aFrameServerVersion === context.serverVersion
-        ) {
-            namespace.fromJSON(record);
+        // 2. Scan extra storage directories discovered via A_FRAME_STORAGE_PATTERN
+        for (const dir of await this.listExtraStorageDirs(env.A_FRAME_STORAGE_PATTERN)) {
+            const extraBuf = await this.tryReadFile(path.join(dir, codec.getNamespaceFileName()));
+            if (!extraBuf) continue;
+            try {
+                const plain = await aFrameCrypto.decryptBytes(new Uint8Array(extraBuf), context.encryptionKey!);
+                const record = codec.decodeNamespacePayload(plain).find(r => r.aseid === namespace.aseid.toString());
+                if (record && record.hash === namespace.hash && record.aFrameServerVersion === context.serverVersion) {
+                    namespace.fromJSON(record);
+                    return;
+                }
+            } catch {
+                // skip unreadable extra storage
+            }
         }
     }
 
@@ -244,7 +285,7 @@ export class A_FrameNodeStorage extends A_FrameStorage {
          * 2. Then drop definitions file related to the namespace.
          */
         try {
-            await fs.unlink(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace.id)));
+            await fs.unlink(path.join(env.A_FRAME_STORAGE_DIR, codec.getDefinitionsFileName(namespace.id)));
         } catch {
             // no-op if file doesn't exist
         }
@@ -271,7 +312,7 @@ export class A_FrameNodeStorage extends A_FrameStorage {
         const records = operation.params.records;
         const namespace = records[0].namespace;
 
-        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace)));
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getDefinitionsFileName(namespace)));
         const existing: A_FrameDefinition_Serialized[] = rawBuf
             ? codec.decodePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
             : [];
@@ -285,7 +326,7 @@ export class A_FrameNodeStorage extends A_FrameStorage {
         const encrypted = await aFrameCrypto.encryptBytes(payload, context.encryptionKey!);
 
         await fs.mkdir(env.A_FRAME_STORAGE_DIR, { recursive: true });
-        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace)), encrypted);
+        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getDefinitionsFileName(namespace)), encrypted);
 
         operation.complete({
             saved: records.length
@@ -305,13 +346,33 @@ export class A_FrameNodeStorage extends A_FrameStorage {
     ): Promise<void> {
         const namespace = operation.params.namespaceId;
 
-        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace)));
-        const records: A_FrameDefinition_Serialized[] = rawBuf
+        // 1. Primary storage
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getDefinitionsFileName(namespace)));
+        const primaryRecords: A_FrameDefinition_Serialized[] = rawBuf
             ? codec.decodePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
             : [];
 
+        // 2. Merge extra storage directories (read-only; primary records take precedence)
+        const merged = new Map<string, A_FrameDefinition_Serialized>();
+        for (const r of primaryRecords) merged.set(r.hash, r);
+
+        for (const dir of await this.listExtraStorageDirs(env.A_FRAME_STORAGE_PATTERN)) {
+            const extraBuf = await this.tryReadFile(path.join(dir, codec.getDefinitionsFileName(namespace)));
+            if (!extraBuf) continue;
+            try {
+                const extraRecords = codec.decodePayload(
+                    await aFrameCrypto.decryptBytes(new Uint8Array(extraBuf), context.encryptionKey!)
+                );
+                for (const r of extraRecords) {
+                    if (!merged.has(r.hash)) merged.set(r.hash, r);
+                }
+            } catch {
+                // skip unreadable extra storage
+            }
+        }
+
         operation.complete({
-            records
+            records: Array.from(merged.values())
         });
     }
 
@@ -332,7 +393,7 @@ export class A_FrameNodeStorage extends A_FrameStorage {
         const namespace = operation.params.namespaceId;
         const definitionId = operation.params.definitionId;
 
-        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace)));
+        const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getDefinitionsFileName(namespace)));
         const records: A_FrameDefinition_Serialized[] = rawBuf
             ? codec.decodePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
             : [];
@@ -343,7 +404,7 @@ export class A_FrameNodeStorage extends A_FrameStorage {
         const encrypted = await aFrameCrypto.encryptBytes(payload, context.encryptionKey!);
 
         await fs.mkdir(env.A_FRAME_STORAGE_DIR, { recursive: true });
-        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(namespace)), encrypted);
+        await fs.writeFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getDefinitionsFileName(namespace)), encrypted);
 
         operation.complete({
             records: filtered
@@ -400,13 +461,34 @@ export class A_FrameNodeStorage extends A_FrameStorage {
     ): Promise<void> {
         const ids = operation.params.namespaces;
 
+        // 1. Primary storage
         const rawBuf = await this.tryReadFile(path.join(env.A_FRAME_STORAGE_DIR, codec.getNamespaceFileName()));
-        const records: A_FrameNamespace_Serialized[] = rawBuf
+        const primaryRecords: A_FrameNamespace_Serialized[] = rawBuf
             ? codec.decodeNamespacePayload(await aFrameCrypto.decryptBytes(new Uint8Array(rawBuf), context.encryptionKey!))
             : [];
 
+        // 2. Merge extra storage directories (read-only; primary records take precedence)
+        const merged = new Map<string, A_FrameNamespace_Serialized>();
+        for (const r of primaryRecords) merged.set(r.aseid, r);
+
+        for (const dir of await this.listExtraStorageDirs(env.A_FRAME_STORAGE_PATTERN)) {
+            const extraBuf = await this.tryReadFile(path.join(dir, codec.getNamespaceFileName()));
+            if (!extraBuf) continue;
+            try {
+                const extraRecords = codec.decodeNamespacePayload(
+                    await aFrameCrypto.decryptBytes(new Uint8Array(extraBuf), context.encryptionKey!)
+                );
+                for (const r of extraRecords) {
+                    if (!merged.has(r.aseid)) merged.set(r.aseid, r);
+                }
+            } catch {
+                // skip unreadable extra storage
+            }
+        }
+
+        const allRecords = Array.from(merged.values());
         operation.complete({
-            records: ids ? records.filter(r => ids.includes(r.name)) : records
+            records: ids ? allRecords.filter(r => ids.includes(r.name)) : allRecords
         });
     }
 
@@ -443,7 +525,7 @@ export class A_FrameNodeStorage extends A_FrameStorage {
          */
         try {
             for (const id of ids) {
-                await fs.unlink(path.join(env.A_FRAME_STORAGE_DIR, codec.getFileName(id)));
+                await fs.unlink(path.join(env.A_FRAME_STORAGE_DIR, codec.getDefinitionsFileName(id)));
             }
             operation.complete({
                 success: true

package/src/lib/A-FrameVector/A-FrameVector.entity.ts

@@ -15,10 +15,23 @@ export class A_FrameVector extends A_Entity {
             : new Float32Array(values)
     }
 
+    get dimensions(): number {
+        return this.values.length
+    }
+
     get length(): number {
         return this.values.length
     }
 
+
+    isEqualTo(vector: A_FrameVector): boolean {
+        if (this.length !== vector.length) return false;
+        for (let i = 0; i < this.length; i++) {
+            if (this.values[i] !== vector.values[i]) return false;
+        }
+        return true;
+    }
+
     magnitude(): number {
         let sum = 0
         for (let i = 0; i < this.values.length; i++) {
@@ -49,6 +62,17 @@ export class A_FrameVector extends A_Entity {
         return sum
     }
 
+    /**
+     * Returns the cosine similarity between this vector and `other` (range −1 to 1).
+     * Vectors with zero magnitude return 0.
+     */
+    cosineSimilarity(other: A_FrameVector): number {
+        const magA = this.magnitude();
+        const magB = other.magnitude();
+        if (magA === 0 || magB === 0) return 0;
+        return this.normalize().dot(other.normalize());
+    }
+
     private assertSameLength(other: A_FrameVector) {
         if (this.length !== other.length) {
             throw new Error(