@adaas/a-frame 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaas/a-frame",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A-frame is index build engine for A-Concept ecosystem. It provides a way to build index structures for A-Concept basics",
   "license": "Apache-2.0",
   "author": {
@@ -16,7 +16,7 @@
     "url": "git+https://github.com/ADAAS-org/adaas-a-frame.git"
   },
   "bin": {
-    "a-frame": "./dist/index.cjs"
+    "a-frame": "./dist/cli.cjs"
   },
   "exports": {
     ".": {
@@ -55,6 +55,15 @@
       "import": "./dist/node/channel.mjs",
       "require": "./dist/node/channel.cjs"
     },
+    "./credentials": {
+      "browser": {
+        "types": "./dist/browser/credentials.d.mts",
+        "import": "./dist/browser/credentials.mjs"
+      },
+      "types": "./dist/node/credentials.d.ts",
+      "import": "./dist/node/credentials.mjs",
+      "require": "./dist/node/credentials.cjs"
+    },
     "./crypto": {
       "browser": {
         "types": "./dist/browser/crypto.d.mts",
@@ -82,6 +91,15 @@
       "import": "./dist/node/dynamic-feature.mjs",
       "require": "./dist/node/dynamic-feature.cjs"
     },
+    "./dynamic-content": {
+      "browser": {
+        "types": "./dist/browser/dynamic-content.d.mts",
+        "import": "./dist/browser/dynamic-content.mjs"
+      },
+      "types": "./dist/node/dynamic-content.d.ts",
+      "import": "./dist/node/dynamic-content.mjs",
+      "require": "./dist/node/dynamic-content.cjs"
+    },
     "./dynamic-structure": {
       "browser": {
         "types": "./dist/browser/dynamic-structure.d.mts",
@@ -127,6 +145,24 @@
       "import": "./dist/node/namespace.mjs",
       "require": "./dist/node/namespace.cjs"
     },
+    "./completion": {
+      "browser": {
+        "types": "./dist/browser/completion.d.mts",
+        "import": "./dist/browser/completion.mjs"
+      },
+      "types": "./dist/node/completion.d.ts",
+      "import": "./dist/node/completion.mjs",
+      "require": "./dist/node/completion.cjs"
+    },
+    "./segment": {
+      "browser": {
+        "types": "./dist/browser/segment.d.mts",
+        "import": "./dist/browser/segment.mjs"
+      },
+      "types": "./dist/node/segment.d.ts",
+      "import": "./dist/node/segment.mjs",
+      "require": "./dist/node/segment.cjs"
+    },
     "./storage": {
       "browser": {
         "types": "./dist/browser/storage.d.mts",
@@ -144,6 +180,24 @@
       "types": "./dist/node/vector.d.ts",
       "import": "./dist/node/vector.mjs",
       "require": "./dist/node/vector.cjs"
+    },
+    "./models": {
+      "browser": {
+        "types": "./dist/browser/models.d.mts",
+        "import": "./dist/browser/models.mjs"
+      },
+      "types": "./dist/node/models.d.ts",
+      "import": "./dist/node/models.mjs",
+      "require": "./dist/node/models.cjs"
+    },
+    "./schema": {
+      "browser": {
+        "types": "./dist/browser/schema.d.mts",
+        "import": "./dist/browser/schema.mjs"
+      },
+      "types": "./dist/node/schema.d.ts",
+      "import": "./dist/node/schema.mjs",
+      "require": "./dist/node/schema.cjs"
     }
   },
   "keywords": [
@@ -170,20 +224,34 @@
     "ext": "ts, js"
   },
   "scripts": {
-    "test": "jest --detectOpenHandles",
-    "test:browser": "jest --config jest.config.browser.ts --detectOpenHandles",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --detectOpenHandles",
+    "test:unit": "node --experimental-vm-modules node_modules/.bin/jest --config jest.config.unit.ts --detectOpenHandles",
+    "test:integration": "node --experimental-vm-modules node_modules/.bin/jest --config jest.config.integration.ts --detectOpenHandles",
+    "test:browser": "node --experimental-vm-modules node_modules/.bin/jest --config jest.config.browser.ts --detectOpenHandles",
+    "example:article": "node -r tsconfig-paths/register -r ts-node/register ./examples/article/main.ts",
+    "example:interaction": "node -r tsconfig-paths/register -r ts-node/register ./examples/interaction/main.ts",
+    "example:feature": "node -r tsconfig-paths/register -r ts-node/register ./examples/feature/main.ts",
+    "example:content-editor": "node -r tsconfig-paths/register -r ts-node/register ./examples/content-editor/server.ts",
+    "example:feature:backup": "node -r tsconfig-paths/register -r ts-node/register ./examples/feature/main.ts \"copy all .ts files to a backup folder and compress the result\"",
+    "example:feature:sync": "node -r tsconfig-paths/register -r ts-node/register ./examples/feature/main.ts \"scan two directories, find files that differ, and sync the newer versions to the target\"",
+    "example:feature:cleanup": "node -r tsconfig-paths/register -r ts-node/register ./examples/feature/main.ts \"find all log files older than 7 days and delete them\"",
+    "example:structure": "node -r tsconfig-paths/register -r ts-node/register ./examples/structure/main.ts",
+    "example:structure:saas": "node -r tsconfig-paths/register -r ts-node/register ./examples/structure/main.ts \"build a multi-tenant SaaS API with JWT auth and file uploads\"",
+    "example:structure:jobs": "node -r tsconfig-paths/register -r ts-node/register ./examples/structure/main.ts \"design a background job processing system with cron and email digests\"",
+    "example:structure:realtime": "node -r tsconfig-paths/register -r ts-node/register ./examples/structure/main.ts \"create a real-time notification service with WebSocket and rate limiting\"",
     "start": "nodemon ./tests/example-usage.ts",
     "start:test": "node -r tsconfig-paths/register -r ts-node/register ./index.ts",
-    "release": "npm run test && npm run build && git add . && git commit -m \"new version created :: $(cat package.json | grep version | head -1  | awk -F: '{ print $2 }'  | sed 's/[\",]//g')\" && npm version patch && npm publish --access public",
+    "release": "npm run test:unit && npm run build && git add . && git commit -m \"new version created :: $(cat package.json | grep version | head -1  | awk -F: '{ print $2 }'  | sed 's/[\",]//g')\" && npm version patch && npm publish --access public",
     "version": "echo git add .",
     "postversion": "git push --no-verify && git push --tags --no-verify && echo \"\n======Version Pushed Successfully=====\n\" ",
     "echo-version": "echo $npm_package_version",
     "build": "tsup --config tsup.config.ts"
   },
-  "dependencies": {
-    "@adaas/a-concept": "^0.3.15"
+  "peerDependencies": {
+    "@adaas/a-concept": "^0.3.16"
   },
   "devDependencies": {
+    "@adaas/a-concept": "^0.3.16",
     "@types/chai": "^4.3.14",
     "@types/jest": "^29.5.12",
     "@types/mocha": "^10.0.6",

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @adaas/a-frame — subpath-only public API.
+ *
+ * Import from named subpaths, not from this root entry:
+ *   import { A_Frame }               from '@adaas/a-frame/core';
+ *   import { A_FrameChannel }        from '@adaas/a-frame/channel';
+ *   import { A_FrameDynamicFeature } from '@adaas/a-frame/dynamic-feature';
+ *   import { A_FrameDynamicStructure,
+ *             A_FrameDynamicPatch }   from '@adaas/a-frame/dynamic-structure';
+ *   // … see package.json "exports" for all available subpaths
+ */
+
+export {};

package/src/lib/A-Frame/A-Frame.component.env-browser.ts

@@ -7,6 +7,7 @@ import { A_FrameIndex } from "../A-FrameIndex";
 import { A_FrameContext } from "./A-Frame.context";
 import { A_FrameLogger } from "../A-FrameLogger/A-FrameLogger.component.env-browser";
 import { A_FrameEnv } from "../A-FrameEnv/A-FrameEnv.fragment.env-browser";
+import { A_FrameBrowserChannel } from "../A-FrameChannel/A-FrameChannel.component.env-browser";
 
 
 
@@ -27,6 +28,7 @@ export class A_Frame extends A_FrameBase {
             { ctor: A_FrameStorageCodec, instance: new A_FrameStorageCodec() },
             { ctor: A_FrameBrowserStorageProvider, instance: A_FrameBrowserStorageProvider },
             { ctor: A_FrameLogger, instance: new A_FrameLogger() },
+            { ctor: A_FrameBrowserChannel, instance: A_FrameBrowserChannel },
         ];
     }
 
@@ -40,6 +42,14 @@ export class A_Frame extends A_FrameBase {
         // every package dep that isn't already in scope.
         this.package.forEach(({ ctor, instance }) => this.packDependency(scope, ctor, instance));
 
+        // Register the blobs singleton so it is always injectable via
+        // @A_Inject(A_FrameBrowserStorageBlobs).  This must happen here
+        // (not in A_FrameBrowserStorageProvider.onLoad) because the concept
+        // only loads A_Frame as a component — the provider is only a DI token.
+        if (!scope.resolve(A_FrameBrowserStorageBlobs)) {
+            scope.register(A_FrameBrowserStorageBlobs.instance);
+        }
+
         // A_FrameIndex needs to inherit the scope so its registry is visible
         // to all later resolutions (entities query it during load).
         if (!scope.resolve(A_FrameIndex)) {
@@ -67,10 +77,11 @@ export class A_Frame extends A_FrameBase {
         @A_Inject(A_FrameLogger) logger: A_FrameLogger,
         @A_Inject(A_FrameBrowserStorageBlobs) blobs: A_FrameBrowserStorageBlobs,
     ) {
-        if (!context.encryptionKey) {
+        if (!context.encryptionKey && !blobs?.hasBundleData) {
             logger.warn(
-                'A_Frame (browser): no encryption key on context — blobs cannot be decrypted. ' +
-                'Call A_FrameContext.setCredentials({...}) before concept.load().'
+                'A_Frame (browser): no encryption key and no pre-built bundle data. ' +
+                'Seed A_FrameBrowserStorageBlobs.fromBundle(bundle) before concept.load(), ' +
+                'or call A_FrameContext.setCredentials({...}) for live-session mode.'
             );
             return;
         }

package/src/lib/A-Frame/A-Frame.component.env-node.ts

@@ -10,6 +10,9 @@ import { A_FrameEnv } from "../A-FrameEnv/A-FrameEnv.fragment.env-node";
 import { A_FrameStorageCodec } from "../A-FrameStorage/A-FrameStorage.codec";
 import { A_FrameCrypto } from "../A-FrameCrypto/A-FrameCrypto.component.env-node";
 import { A_FrameLogger } from "../A-FrameLogger/A-FrameLogger.component.env-node";
+import { A_FrameCredentials } from "../A-FrameCredentials/A-FrameCredentials.entity";
+import { A_FrameComponentMapper } from "../A-FrameDynamicStructure/A-FrameComponentMapper.component";
+import { A_FrameMethodMapper } from "../A-FrameDynamicFeature/A-FrameMethodMapper.component";
 
 
 
@@ -18,20 +21,24 @@ export class A_Frame extends A_FrameBase {
     @A_Concept.Load()
     async injectDependencies(
     ) {
+        const scope = A_Context.root;
 
-        const index = new A_FrameIndex();
-        index.inherit(A_Context.root);
-
+        if (!scope.resolve(A_FrameIndex)) {
+            const index = new A_FrameIndex();
+            index.inherit(scope);
+            scope.register(index);
+        }
 
-        A_Context.root.register(index);
-        A_Context.root.register(new A_FrameEnv());
-        A_Context.root.register(new A_FrameStorageCodec());
-        A_Context.root.register(A_FrameNodeStorage)
-        A_Context.root.register(A_FrameNodeChannel);
-        A_Context.root.register(A_FrameCrypto)
-        A_Context.root.register(new A_FrameLogger());
-        A_Context.root.register(A_Frame);
-        A_Context.root.register(new A_FrameContext());
+        this.packDependency(scope, A_FrameEnv, new A_FrameEnv());
+        this.packDependency(scope, A_FrameStorageCodec, new A_FrameStorageCodec());
+        this.packDependency(scope, A_FrameNodeStorage, A_FrameNodeStorage);
+        this.packDependency(scope, A_FrameChannel, A_FrameNodeChannel);
+        this.packDependency(scope, A_FrameCrypto, A_FrameCrypto);
+        this.packDependency(scope, A_FrameLogger, new A_FrameLogger());
+        this.packDependency(scope, A_Frame, A_Frame);
+        this.packDependency(scope, A_FrameContext, new A_FrameContext());
+        this.packDependency(scope, A_FrameComponentMapper, A_FrameComponentMapper);
+        this.packDependency(scope, A_FrameMethodMapper, A_FrameMethodMapper);
     }
 
 
@@ -43,10 +50,31 @@ export class A_Frame extends A_FrameBase {
         @A_Inject(A_FrameContext) context: A_FrameContext,
         @A_Inject(A_FrameChannel) channel: A_FrameChannel,
         @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameLogger) logger: A_FrameLogger,
     ) {
-        // 1. Authenticate — required before any storage or embedding operations
-        const credentials = await channel.getCredentials();
-        context.setCredentials(credentials);
+        // 1. Authenticate — required before any storage or embedding operations.
+        //    If the server is unreachable (e.g. CLI invoked before server is up),
+        //    record the error in context and skip sync so the CLI can still run.
+        let credentialsRequest: Awaited<ReturnType<typeof channel.getCredentials>>;
+        try {
+            credentialsRequest = await channel.getCredentials();
+        } catch (err) {
+            logger.warn(
+                `A_Frame: could not reach the server to fetch credentials ` +
+                `(${err instanceof Error ? err.message : String(err)}). ` +
+                `Sync and embedding are disabled for this run.`
+            );
+            return;
+        }
+        context.setCredentials(credentialsRequest);
+
+        // Store credentials as a registered entity so they can be injected
+        // via @A_Inject(A_FrameCredentials) anywhere in the scope tree
+        if (credentialsRequest.response) {
+            const credentialsEntity = new A_FrameCredentials(credentialsRequest.response);
+            A_Context.root.register(credentialsEntity);
+        }
+
 
         const definedNameSpaces = index.listNamespaces();
         const definedDefinitions = index.listDefinitions();
@@ -54,6 +82,7 @@ export class A_Frame extends A_FrameBase {
         // 2. Hydrate all from storage in parallel.
         //    Storage load only calls fromJSON when hash AND aFrameServerVersion match,
         //    so items with a stale/missing cache remain un-embedded (isEmbed === false).
+
         await Promise.all([
             ...definedNameSpaces.map(ns => ns.load()),
             ...definedDefinitions.map(def => def.load()),
@@ -62,6 +91,7 @@ export class A_Frame extends A_FrameBase {
         // 3. Skip embedding API calls entirely when sync is disabled
         if (!env.A_FRAME_SYNC) return;
 
+
         // 4. Re-embed and persist items whose cache is missing or stale
         const namespacesNeedEmbed = definedNameSpaces.filter(ns => !ns.isEmbed
             || (ns.aFrameServerVersion !== context.serverVersion)

package/src/lib/A-Frame/A-Frame.context.ts

@@ -1,11 +1,12 @@
 import { A_Fragment } from "@adaas/a-concept"
 import { A_FrameChannelRequest } from "../A-FrameChannel/A-FrameChannelRequest.context";
 import { A_Frame_CredentialResponse } from "../A-FrameChannel/A-FrameChannel.types";
+import { A_FrameCredentials } from "../A-FrameCredentials/A-FrameCredentials.entity";
 
 
 export class A_FrameContext extends A_Fragment {
 
-    private credentials?: A_Frame_CredentialResponse;
+    private _credentials?: A_FrameCredentials;
 
 
     constructor() {
@@ -14,27 +15,27 @@ export class A_FrameContext extends A_Fragment {
 
 
     get encryptionKey(): string | undefined {
-        return this.credentials?.encryption_key;
+        return this._credentials?.encryptionKey;
     }
 
 
     get serverVersion(): string | undefined {
-        return this.credentials?.server_version;
+        return this._credentials?.serverVersion;
     }
 
 
     isAuthenticated(): boolean {
-        return !!this.credentials;
+        return !!this._credentials?.isAuthenticated;
     }
 
 
-    setCredentials(credentials: A_FrameChannelRequest<A_Frame_CredentialResponse>) {
-        if (credentials.error) {
-            this.credentials = undefined;
+    setCredentials(credentialsRequest: A_FrameChannelRequest<A_Frame_CredentialResponse>) {
+        if (credentialsRequest.error || !credentialsRequest.response) {
+            this._credentials = undefined;
             return;
         }
 
-        this.credentials = credentials.response || undefined;
+        this._credentials = new A_FrameCredentials(credentialsRequest.response);
     }
 
 }

package/src/lib/A-Frame/decorators/A-FrameDefine.decorator.ts

@@ -35,7 +35,7 @@ export function A_FrameDefineDecorator(
             default:
                 throw new A_FrameError(
                     A_FrameError.InvalidTarget,
-                    `@A_Frame.Define decorator cannot be applied to the target.`
+                    `@A_Frame.Define decorator cannot be applied to the target : ${A_CommonHelper.getComponentName(target)}. It can only be applied to classes or methods inheriting from allowed base classes.`
                 );
         }
         const namespace = config.namespace
@@ -63,7 +63,7 @@ export function A_FrameDefineDecorator(
                 source: source,
                 metadata: config.metadata,
                 type: A_FrameTargetType.METHOD,
-                namespace: namespace
+                namespace: namespace,
             }));
 
             return descriptor;
@@ -73,7 +73,7 @@ export function A_FrameDefineDecorator(
         if (!A_FrameTypeGuard.isAllowedTarget(target)) {
             throw new A_FrameError(
                 A_FrameError.InvalidTarget,
-                `@A_Frame.${componentType} decorator can only be applied to allowed targets.`
+                `@A_Frame.${componentType} decorator cannot be applied to the target : ${A_CommonHelper.getComponentName(target)}. It can only be applied to allowed targets.`
             );
         }
 
@@ -92,7 +92,7 @@ export function A_FrameDefineDecorator(
             source: source,
             metadata: config.metadata,
             type: componentType,
-            namespace: namespace
+            namespace: namespace,
         }));
 
         return target;

package/src/lib/A-FrameBundle/A-FrameBundle.builder.env-node.ts

@@ -1,60 +1,129 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { A_Component } from '@adaas/a-concept';
-import { A_FrameBundle } from './A-FrameBundle.types';
+import { A_FrameBundle, A_FrameBundleDefinitionRecord, A_FrameBundleNamespaceRecord } from './A-FrameBundle.types';
 import { A_FRAME_BUNDLE_VERSION } from './A-FrameBundle.constants';
 import { A_FrameStorageCodec } from '../A-FrameStorage/A-FrameStorage.codec';
+import { A_FrameCrypto } from '../A-FrameCrypto/A-FrameCrypto.component.env-node';
 import * as pkg from '../../../package.json';
 
 
 export interface A_FrameBundleBuilderOptions {
-    /** Source directory containing the encrypted `*.aframe` files (Node storage). */
-    storageDir: string;
+    /**
+     * Source directory containing the encrypted `*.aframe` files (Node storage).
+     * Defaults to `.aframe/` in the current working directory.
+     */
+    storageDir?: string;
     /** Server version to embed in the bundle metadata. */
     serverVersion: string;
+    /**
+     * AES-256-GCM encryption key used when the `.aframe` files were written.
+     * This is the `encryptionKey` returned by the A-Frame server credentials API.
+     * Required so the builder can decrypt the files and produce plain-JSON records.
+     */
+    encryptionKey: string;
 }
 
 
 /**
  * A_FrameBundleBuilder — Node-only build-time helper.
  *
- * Reads the encrypted `*.aframe` files produced by Node storage and packages
- * them into a single JSON (or generated TypeScript module) artifact that ships
- * with the browser bundle. The browser bootstrap then seeds these blobs into
- * `A_FrameBrowserStorageBlobs` so that read-only `definition.load()` /
- * `namespace.load()` calls work without a filesystem.
+ * Reads the encrypted `*.aframe` files produced by Node storage, decrypts them
+ * with the provided key, and packages the decoded definition/namespace records
+ * into a single JSON artifact that ships with the browser bundle.
+ *
+ * The output bundle stores plain records (no encryption). The browser bootstrap
+ * seeds these directly into `A_FrameBrowserStorageBlobs` so that definitions
+ * load without any server connection or encryption key.
+ *
+ * Usage:
+ * ```ts
+ * import { A_FrameBundleBuilder } from '@adaas/a-frame/bundle';
+ *
+ * const builder = new A_FrameBundleBuilder();
+ * const bundle = await builder.build({
+ *   storageDir: '.aframe',
+ *   serverVersion: '1.0.0',
+ *   encryptionKey: process.env.A_FRAME_ENCRYPTION_KEY!,
+ * });
+ * await builder.writeAuto(bundle, 'src/generated/a-frame-bundle.ts');
+ * ```
  */
 export class A_FrameBundleBuilder extends A_Component {
 
-    /** Read all `.aframe` files from a storage directory and serialise them. */
+    private codec = new A_FrameStorageCodec();
+
+    /** Read, decrypt and decode all `.aframe` files from a storage directory. */
     async build(opts: A_FrameBundleBuilderOptions): Promise<A_FrameBundle> {
-        const ext = A_FrameStorageCodec.fileExtension; // ".aframe"
-        const namespacesFile = `__namespaces${ext}`;
+        const storageDir = opts.storageDir ?? '.aframe';
+        const namespacesFile = this.codec.getNamespaceFileName();   // '.namespaces.aframe'
+        const defSuffix = `.definitions${A_FrameStorageCodec.fileExtension}`; // '.definitions.aframe'
 
         let entries: string[];
         try {
-            entries = await fs.readdir(opts.storageDir);
+            entries = await fs.readdir(storageDir);
         } catch (err: any) {
             if (err?.code === 'ENOENT') {
-                throw new Error(`A-Frame storage directory not found: ${opts.storageDir}`);
+                throw new Error(`A-Frame storage directory not found: ${path.resolve(storageDir)}`);
             }
             throw err;
         }
 
-        const aframeFiles = entries.filter(f => f.endsWith(ext));
+        // Accept both the namespace index and definition files
+        const aframeFiles = entries.filter(f => f === namespacesFile || f.endsWith(defSuffix));
 
-        let namespaces: string | null = null;
-        const definitions: Record<string, string> = {};
+        const records: Record<string, A_FrameBundleDefinitionRecord[]> = {};
+        const namespaceRecords: A_FrameBundleNamespaceRecord[] = [];
 
         for (const file of aframeFiles) {
-            const buf = await fs.readFile(path.join(opts.storageDir, file));
-            const b64 = buf.toString('base64');
+            const raw = await fs.readFile(path.join(storageDir, file));
+            let plain: Uint8Array;
+            try {
+                plain = await A_FrameCrypto.decryptBytes(new Uint8Array(raw), opts.encryptionKey);
+            } catch {
+                throw new Error(
+                    `Failed to decrypt "${file}". Ensure encryptionKey matches the key used when the files were written.`
+                );
+            }
 
             if (file === namespacesFile) {
-                namespaces = b64;
+                const decoded = this.codec.decodeNamespacePayload(plain);
+                for (const r of decoded) {
+                    namespaceRecords.push({
+                        aseid: r.aseid,
+                        hash: r.hash,
+                        name: r.name,
+                        description: r.description,
+                        metadata: r.metadata,
+                        embedding: Array.from(r.embedding ?? []),
+                        embeddedAt: r.embeddedAt,
+                        embeddingModel: r.embeddingModel,
+                        credentialId: r.credentialId,
+                        aFrameVersion: r.aFrameVersion,
+                        aFrameServerVersion: r.aFrameServerVersion,
+                    });
+                }
             } else {
-                const id = file.slice(0, -ext.length);
-                definitions[id] = b64;
+                // Strip '.definitions.aframe' suffix to recover the namespace id
+                const namespaceId = file.slice(0, -defSuffix.length);
+                const decoded = this.codec.decodePayload(plain);
+                records[namespaceId] = decoded.map(r => ({
+                    aseid: r.aseid,
+                    name: r.name,
+                    hash: r.hash,
+                    type: r.type,
+                    source: r.source,
+                    description: r.description,
+                    metadata: r.metadata,
+                    namespace: r.namespace,
+                    embedding: Array.from(r.embedding ?? []),
+                    date: r.date,
+                    model: r.model,
+                    credentialId: r.credentialId,
+                    aFrameVersion: r.aFrameVersion,
+                    aFrameServerVersion: r.aFrameServerVersion,
+                    aFrameMeta: r.aFrameMeta,
+                }));
             }
         }
 
@@ -63,8 +132,8 @@ export class A_FrameBundleBuilder extends A_Component {
             aFrameVersion: (pkg as any).version || '0.0.0',
             serverVersion: opts.serverVersion,
             builtAt: new Date().toISOString(),
-            namespaces,
-            definitions,
+            records,
+            namespaceRecords,
         };
     }
 
@@ -76,12 +145,12 @@ export class A_FrameBundleBuilder extends A_Component {
 
     /**
      * Emit a TypeScript module that exports the bundle as a typed constant.
-     * Useful for bundlers that prefer TS imports over JSON imports.
+     * Ideal for Vite/Webpack/esbuild projects that tree-shake TS imports.
      */
     async writeTS(bundle: A_FrameBundle, outFile: string): Promise<void> {
         const banner = '// AUTO-GENERATED by @adaas/a-frame — do not edit.\n';
         const body =
-            `import type { A_FrameBundle } from '@adaas/a-frame';\n\n` +
+            `import type { A_FrameBundle } from '@adaas/a-frame/bundle';\n\n` +
             `export const A_FRAME_BUNDLE: A_FrameBundle = ${JSON.stringify(bundle, null, 2)} as A_FrameBundle;\n`;
         await fs.mkdir(path.dirname(path.resolve(outFile)), { recursive: true });
         await fs.writeFile(outFile, banner + body);
@@ -93,3 +162,4 @@ export class A_FrameBundleBuilder extends A_Component {
         return this.writeJSON(bundle, outFile);
     }
 }
+

package/src/lib/A-FrameBundle/A-FrameBundle.constants.ts

@@ -1,5 +1,5 @@
 /** Current bundle format revision. Bumped on incompatible structural changes. */
-export const A_FRAME_BUNDLE_VERSION = 1;
+export const A_FRAME_BUNDLE_VERSION = 2;
 
 /** Default file name when none is provided to the CLI. */
 export const A_FRAME_BUNDLE_DEFAULT_FILENAME = 'a-frame-bundle.json';

package/src/lib/A-FrameBundle/A-FrameBundle.types.ts

@@ -1,16 +1,58 @@
+import type { A_FrameTargetType } from '../A-Frame/A-Frame.types';
+import type { DefinitionExtractedMeta } from '../A-FrameDefinition/A-FrameDefinition.types';
+
+/**
+ * JSON-serializable definition record (embedding stored as number[] instead of Float32Array).
+ */
+export interface A_FrameBundleDefinitionRecord {
+    aseid: string;
+    name: string;
+    hash: string;
+    type: A_FrameTargetType;
+    source?: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    namespace: string;
+    /** Float32 embedding serialized as a plain number array. */
+    embedding: number[];
+    date: string;
+    model: string;
+    credentialId: string;
+    aFrameVersion: string;
+    aFrameServerVersion: string;
+    aFrameMeta?: DefinitionExtractedMeta;
+}
+
+/**
+ * JSON-serializable namespace record (embedding as number[]).
+ */
+export interface A_FrameBundleNamespaceRecord {
+    aseid: string;
+    hash: string;
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    /** Float32 embedding serialized as a plain number array. */
+    embedding: number[];
+    embeddedAt: number;
+    embeddingModel?: string;
+    credentialId?: string;
+    aFrameVersion?: string;
+    aFrameServerVersion?: string;
+}
+
 /**
  * Serialized A-Frame bundle artifact.
  *
- * Built by `A_FrameBundleBuilder` from a Node storage directory at build time
- * (see CLI `--bundle <out>`). Loaded by `A_FrameBrowserStorageBlobs.seedFromBundle()`
- * at app startup in the browser.
+ * Built by `A_FrameBundleBuilder` from a Node storage directory at build time.
+ * Loaded by `A_FrameBrowserStorageBlobs.seedFromBundle()` at app startup in the
+ * browser — no server connection or encryption key required at runtime.
  *
- * Storage blobs are kept in their AES-256-GCM encrypted form — the consuming
- * browser app must obtain the encryption key out-of-band (typically by
- * authenticating against the A-Frame server with the user's token).
+ * The bundle stores decoded definition and namespace records in plain JSON so
+ * that the browser can hydrate embeddings without calling the A-Frame server.
  */
 export interface A_FrameBundle {
-    /** Bundle format version. Currently 1. */
+    /** Bundle format version. Currently 2. */
     bundleVersion: number;
     /** A-Frame client library version that produced the bundle. */
     aFrameVersion: string;
@@ -19,13 +61,12 @@ export interface A_FrameBundle {
     /** Build timestamp (ISO 8601). */
     builtAt: string;
     /**
-     * Base64-encoded contents of the `__namespaces.aframe` index file.
-     * `null` when no namespaces have been persisted yet.
+     * Decoded definition records grouped by namespace id.
+     * The `embedding` field contains the raw Float32 values as a plain number[].
      */
-    namespaces: string | null;
+    records: Record<string, A_FrameBundleDefinitionRecord[]>;
     /**
-     * Map of namespace id (file basename without extension) → base64-encoded
-     * contents of the corresponding `<namespace>.aframe` file.
+     * Decoded namespace records (from `__namespaces.aframe`).
      */
-    definitions: Record<string, string>;
+    namespaceRecords: A_FrameBundleNamespaceRecord[];
 }