@adaas/a-frame 0.0.22 → 0.0.23

package/src/lib/A-FrameStorage/A-FrameStorageOperation.context.ts

@@ -0,0 +1,59 @@
+import { A_Error, A_Fragment } from "@adaas/a-concept";
+
+
+export class A_FrameStorageOperation<
+    _ParamsType = any,
+    _ResultType = any
+> extends A_Fragment {
+
+    protected _result?: _ResultType;
+
+    protected _error?: A_Error;
+
+    protected _params!: _ParamsType;
+
+
+    constructor(
+        params: _ParamsType
+    ) {
+        super({ name: 'a-frame-storage-operation' });
+        this._params = params;
+    }
+
+
+    /**
+     * If the operation succeeded, this will contain the result data. If the operation failed, this will be undefined.
+     */
+    get result(): _ResultType | undefined {
+        return this._result;
+    }
+    /**
+     * If the operation failed, this will contain an error object with details about the failure. If the operation succeeded, this will be undefined.
+     */
+    get error(): A_Error | undefined {
+        return this._error;
+    }
+    /**
+     * Parameters used to execute the operation, e.g. definitionId and namespaceId for a saveDefinition operation.
+     */
+    get params(): _ParamsType {
+        return this._params;
+    }
+    /**
+     * Marks the operation as completed successfully with the given result. This will set the `result` property and leave `error` as undefined.
+     * 
+     * @param result 
+     */
+    complete(result: _ResultType): void {
+        this._result = result;
+    }
+    /**
+     * Marks the operation as failed with the given error. This will set the `error` property and leave `result` as undefined.
+     * 
+     * @param error 
+     */
+    fail(error: A_Error): void {
+        this._error = error;
+    }
+
+}

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

@@ -0,0 +1,312 @@
+import { A_Caller, A_Concept, A_Feature, A_Inject, A_Scope } from "@adaas/a-concept";
+import { A_FrameStorageFeatures } from "../A-FrameStorage.constants";
+import { A_FrameStorage } from "../A-FrameStorage.component";
+import { A_FrameEnv } from "../../A-FrameEnv/A-FrameEnv.fragment.env-browser";
+import { A_FrameStorageOperation } from "../A-FrameStorageOperation.context";
+import {
+    A_FrameStorageDestroyDefinitionsOperation,
+    A_FrameStorageDestroyNamespacesOperation,
+    A_FrameStorageLoadDefinitionsOperation,
+    A_FrameStorageLoadNamespacesOperation,
+    A_FrameStorageSaveDefinitionOperation,
+    A_FrameStorageSaveNamespaceOperation,
+} from "../A-FrameStorage.types";
+import { A_FrameCrypto } from "../../A-FrameCrypto/A-FrameCrypto.component.env-browser";
+import { A_FrameDefinition_Serialized } from "../../A-FrameDefinition/A-FrameDefinition.types";
+import { A_FrameNamespace_Serialized } from "../../A-FrameNamespace/A-FrameNamespace.types";
+import { A_FrameBrowserStorageBlobs } from "./A-FrameBrowserStorageBlobs.context";
+import { A_FrameStorageCodec } from "../A-FrameStorage.codec";
+import { A_FrameContext } from "../../A-Frame/A-Frame.context";
+import { A_FrameStorageError } from "../A-FrameStorage.error";
+import { A_FrameDefinition } from "../../A-FrameDefinition";
+import { A_FrameDefinitionFeatures } from "../../A-FrameDefinition/A-FrameDefinition.constants";
+import { A_FrameNamespace } from "../../A-FrameNamespace";
+import { A_FrameNamespaceFeatures } from "../../A-FrameNamespace/A-FrameNamespace.constants";
+
+
+/**
+ * A_FrameBrowserStorageProvider — Browser environment
+ *
+ * Stores encrypted definition and namespace records entirely in memory.
+ * Pre-built .aframe index files should be injected at bundle startup via
+ * A_FrameBrowserStorageProvider.loadBlob() so that read-only access works
+ * without any network or filesystem calls.
+ *
+ * Example (Vite):
+ *   import mathBin from './embed-index/math.aframe?arraybuffer';
+ *   A_FrameBrowserStorageProvider.loadBlob('math', new Uint8Array(mathBin));
+ */
+export class A_FrameBrowserStorageProvider extends A_FrameStorage {
+
+    @A_Concept.Load()
+    onLoad(
+        @A_Inject(A_Scope) scope: A_Scope,
+        @A_Inject(A_FrameBrowserStorageBlobs) blobs?: A_FrameBrowserStorageBlobs,
+    ) {
+        if (!blobs) {
+            scope.register(A_FrameBrowserStorageBlobs.instance);
+        }
+    }
+
+
+    // ---------------------------------------------------------------------------------------
+    //--------------------------Storage Features Extensions----------------------------------
+    //---------------------------------------------------------------------------------------
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.SaveDefinitions,
+        scope: [A_FrameStorage],
+    })
+    async saveDefinitionsToMemory(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) operation: A_FrameStorageSaveDefinitionOperation,
+        @A_Inject(A_FrameContext) global: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameBrowserStorageBlobs) blobs: A_FrameBrowserStorageBlobs,
+    ): Promise<void> {
+        const records = operation.params.records;
+        const namespace = records[0].namespace;
+
+        const existing = await this._loadDefinitionsFromMemory(blobs.store, namespace, global.encryptionKey!, codec);
+
+        const merged = new Map<string, A_FrameDefinition_Serialized>();
+        for (const r of existing) merged.set(r.aseid, r);
+        for (const d of records) merged.set(d.aseid.toString(), d);
+
+        const payload = codec.encodePayload(Array.from(merged.values()));
+        blobs.store.set(namespace, await A_FrameCrypto.encryptBytes(payload, global.encryptionKey!));
+
+        operation.complete({ saved: records.length });
+    }
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.LoadDefinitions,
+        scope: [A_FrameStorage],
+    })
+    async loadDefinitionsFromMemory(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) operation: A_FrameStorageLoadDefinitionsOperation,
+        @A_Inject(A_FrameContext) global: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameBrowserStorageBlobs) blobs: A_FrameBrowserStorageBlobs,
+    ): Promise<void> {
+        const namespace = operation.params.namespaceId;
+        const records = await this._loadDefinitionsFromMemory(blobs.store, namespace, global.encryptionKey!, codec);
+        operation.complete({ records });
+    }
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.DestroyDefinitions,
+        scope: [A_FrameStorage],
+    })
+    async destroyDefinitionsFromMemory(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) operation: A_FrameStorageDestroyDefinitionsOperation,
+        @A_Inject(A_FrameContext) global: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameBrowserStorageBlobs) blobs: A_FrameBrowserStorageBlobs,
+    ): Promise<void> {
+        const namespace = operation.params.namespaceId;
+        const definitionId = operation.params.definitionId;
+
+        const existing = await this._loadDefinitionsFromMemory(blobs.store, namespace, global.encryptionKey!, codec);
+        const filtered = existing.filter(r => r.aseid !== definitionId);
+
+        const payload = codec.encodePayload(filtered);
+        blobs.store.set(namespace, await A_FrameCrypto.encryptBytes(payload, global.encryptionKey!));
+
+        operation.complete({ records: filtered });
+    }
+
+
+    // ---------------------------------------------------------------------------------------
+    //--------------------------Namespace Features Extensions--------------------------------
+    //---------------------------------------------------------------------------------------
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.SaveNamespaces,
+        scope: [A_FrameStorage],
+    })
+    async saveNamespacesToMemory(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) operation: A_FrameStorageSaveNamespaceOperation,
+        @A_Inject(A_FrameContext) global: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameBrowserStorageBlobs) blobs: A_FrameBrowserStorageBlobs,
+    ): Promise<void> {
+        const records = operation.params.records;
+
+        const existing = await this._loadNamespacesFromMemory(blobs, global.encryptionKey!, codec);
+
+        const merged = new Map<string, A_FrameNamespace_Serialized>();
+        for (const r of existing) merged.set(r.aseid, r);
+        for (const d of records) merged.set(d.aseid.toString(), d);
+
+        const payload = codec.encodeNamespacePayload(Array.from(merged.values()));
+        blobs.namespaceBlob = await A_FrameCrypto.encryptBytes(payload, global.encryptionKey!);
+
+        operation.complete({ success: true });
+    }
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.LoadNamespaces,
+        scope: [A_FrameStorage],
+    })
+    async loadNamespacesFromMemory(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) operation: A_FrameStorageLoadNamespacesOperation,
+        @A_Inject(A_FrameContext) global: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameBrowserStorageBlobs) blobs: A_FrameBrowserStorageBlobs,
+    ): Promise<void> {
+        const ids = operation.params.namespaces;
+        const records = await this._loadNamespacesFromMemory(blobs, global.encryptionKey!, codec);
+
+        operation.complete({
+            records: ids ? records.filter(r => ids.includes(r.name)) : records
+        });
+    }
+
+    @A_Feature.Extend({
+        name: A_FrameStorageFeatures.DestroyNamespaces,
+        scope: [A_FrameStorage],
+    })
+    async destroyNamespacesFromMemory(
+        @A_Inject(A_FrameEnv) env: A_FrameEnv,
+        @A_Inject(A_FrameStorageOperation) operation: A_FrameStorageDestroyNamespacesOperation,
+        @A_Inject(A_FrameContext) global: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameBrowserStorageBlobs) blobs: A_FrameBrowserStorageBlobs,
+    ): Promise<void> {
+        const ids = operation.params.namespaces;
+
+        const existing = await this._loadNamespacesFromMemory(blobs, global.encryptionKey!, codec);
+        const filtered = existing.filter(r => !ids.includes(r.aseid));
+
+        const payload = codec.encodeNamespacePayload(filtered);
+        blobs.namespaceBlob = await A_FrameCrypto.encryptBytes(payload, global.encryptionKey!);
+
+        // Drop definition blobs for destroyed namespaces
+        try {
+            for (const id of ids) {
+                blobs.store.delete(id);
+            }
+            operation.complete({ success: true });
+        } catch (error) {
+            operation.fail(new A_FrameStorageError({
+                title: A_FrameStorageError.DestroyNamespacesFailed,
+                description: `Failed to destroy namespace records.`,
+            }));
+            operation.complete({ success: false });
+        }
+    }
+
+
+    // ---------------------------------------------------------------------------------------
+    //--------------------------Definition Entity-level Extensions---------------------------
+    //---------------------------------------------------------------------------------------
+
+    /**
+     * Hydrate a single A_FrameDefinition from the in-memory bundle blobs.
+     *
+     * Mirrors the Node `loadDefinitionFromDisk` extension. Looks up the
+     * namespace's encrypted blob in the singleton blob store, decrypts and
+     * decodes it, then calls `definition.fromJSON(record)` only when the
+     * stored hash and server version match the live entity.
+     *
+     * No-op when:
+     *   - no blob has been seeded for the namespace
+     *   - decryption fails (wrong key / corrupted blob)
+     *   - the record is absent or stale
+     */
+    @A_Feature.Extend({
+        name: A_FrameDefinitionFeatures.Load,
+        scope: [A_FrameDefinition],
+    })
+    async loadDefinitionFromBlobs(
+        @A_Inject(A_Caller) definition: A_FrameDefinition,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameBrowserStorageBlobs) blobs: A_FrameBrowserStorageBlobs,
+    ): Promise<void> {
+        if (!context.encryptionKey) return;
+
+        const records = await this._loadDefinitionsFromMemory(
+            blobs.store, definition.namespace.id, context.encryptionKey, codec
+        );
+        if (records.length === 0) return;
+
+        const record = records.find(r => r.aseid === definition.aseid.toString());
+        if (
+            record &&
+            record.hash === definition.hash &&
+            record.aFrameServerVersion === context.serverVersion
+        ) {
+            definition.fromJSON(record);
+        }
+    }
+
+
+    // ---------------------------------------------------------------------------------------
+    //--------------------------Namespace Entity-level Extensions----------------------------
+    //---------------------------------------------------------------------------------------
+
+    @A_Feature.Extend({
+        name: A_FrameNamespaceFeatures.Load,
+        scope: [A_FrameNamespace],
+    })
+    async loadNamespaceFromBlobs(
+        @A_Inject(A_Caller) namespace: A_FrameNamespace,
+        @A_Inject(A_FrameContext) context: A_FrameContext,
+        @A_Inject(A_FrameStorageCodec) codec: A_FrameStorageCodec,
+        @A_Inject(A_FrameBrowserStorageBlobs) blobs: A_FrameBrowserStorageBlobs,
+    ): Promise<void> {
+        if (!context.encryptionKey) return;
+
+        const records = await this._loadNamespacesFromMemory(blobs, context.encryptionKey, codec);
+        if (records.length === 0) return;
+
+        const record = records.find(r => r.aseid === namespace.aseid.toString());
+        if (
+            record &&
+            record.hash === namespace.hash &&
+            record.aFrameServerVersion === context.serverVersion
+        ) {
+            namespace.fromJSON(record);
+        }
+    }
+
+
+    // ─── Internal helpers ──────────────────────────────────────────────────────
+
+    private async _loadDefinitionsFromMemory(
+        store: Map<string, Uint8Array>,
+        namespace: string,
+        encryptionKey: string,
+        codec: A_FrameStorageCodec,
+    ): Promise<A_FrameDefinition_Serialized[]> {
+        const blob = store.get(namespace);
+        if (!blob) return [];
+        try {
+            const plain = await A_FrameCrypto.decryptBytes(blob, encryptionKey);
+            return codec.decodePayload(plain);
+        } catch {
+            return [];
+        }
+    }
+
+    private async _loadNamespacesFromMemory(
+        blobs: A_FrameBrowserStorageBlobs,
+        encryptionKey: string,
+        codec: A_FrameStorageCodec,
+    ): Promise<A_FrameNamespace_Serialized[]> {
+        const blob = blobs.namespaceBlob;
+        if (!blob) return [];
+        try {
+            const plain = await A_FrameCrypto.decryptBytes(blob, encryptionKey);
+            return codec.decodeNamespacePayload(plain);
+        } catch {
+            return [];
+        }
+    }
+}

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

@@ -0,0 +1,77 @@
+// ─── In-memory blob store (singleton Fragment) ────────────────────────────────
+//
+// A_Component is stateless — persistent session state lives in a Fragment
+// singleton that survives across per-call execution scopes.
+
+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'));
+}
+
+
+export class A_FrameBrowserStorageBlobs extends A_Fragment {
+
+    private static _instance: A_FrameBrowserStorageBlobs | undefined;
+
+    static get instance(): A_FrameBrowserStorageBlobs {
+        if (!A_FrameBrowserStorageBlobs._instance) {
+            A_FrameBrowserStorageBlobs._instance = new A_FrameBrowserStorageBlobs();
+        }
+        return A_FrameBrowserStorageBlobs._instance;
+    }
+
+    /**
+     * Build a singleton blobs store seeded from a prebuilt bundle.
+     * Convenience for browser bootstrap.
+     */
+    static fromBundle(bundle: A_FrameBundle): A_FrameBrowserStorageBlobs {
+        const blobs = A_FrameBrowserStorageBlobs.instance;
+        blobs.seedFromBundle(bundle);
+        return blobs;
+    }
+
+    constructor() {
+        if (A_FrameBrowserStorageBlobs._instance)
+            return A_FrameBrowserStorageBlobs._instance;
+
+        super({ name: 'a-frame-browser-storage-blobs' });
+    }
+
+    /** namespace → encrypted definition bytes */
+    readonly store = new Map<string, Uint8Array>();
+
+    /** encrypted bytes for the namespace index (`__namespaces.aframe` equivalent) */
+    namespaceBlob: Uint8Array | null = null;
+
+    /** Bundle metadata recorded at seed time, used by A_Frame to validate versions. */
+    bundleMeta: { aFrameVersion: string; serverVersion: string; builtAt: string } | null = null;
+
+    /**
+     * Populate the store from a bundle artifact. Existing entries with the
+     * same namespace are overwritten; unrelated entries are preserved.
+     */
+    seedFromBundle(bundle: A_FrameBundle): void {
+        if (bundle.namespaces) {
+            this.namespaceBlob = decodeBase64(bundle.namespaces);
+        }
+        for (const [id, b64] of Object.entries(bundle.definitions)) {
+            this.store.set(id, decodeBase64(b64));
+        }
+        this.bundleMeta = {
+            aFrameVersion: bundle.aFrameVersion,
+            serverVersion: bundle.serverVersion,
+            builtAt: bundle.builtAt,
+        };
+    }
+}

package/src/lib/A-FrameStorage/index.browser.ts

@@ -0,0 +1,11 @@
+
+
+export * from './A-FrameStorage.component';
+export * from './A-FrameStorage.codec';
+export * from './A-FrameStorageOperation.context';
+export * from './A-FrameStorage.error';
+export * from './A-FrameStorage.types';
+export * from './A-FrameStorage.constants';
+
+export * from './browser/A-FrameBrowserStorage.component';
+export * from './browser/A-FrameBrowserStorageBlobs.context';

package/src/lib/A-FrameStorage/index.ts

@@ -0,0 +1,10 @@
+
+
+export * from './A-FrameStorage.component';
+export * from './A-FrameStorage.codec';
+export * from './A-FrameStorageOperation.context';
+export * from './A-FrameStorage.error';
+export * from './A-FrameStorage.types';
+export * from './A-FrameStorage.constants';
+
+export * from './node/A-FrameNodeStorage.component';