@adaas/a-frame 0.0.22 → 0.0.23

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

@@ -0,0 +1,187 @@
+import { A_CommonHelper, A_Context, A_Entity, A_Scope, A_TYPES__A_DependencyInjectable } from "@adaas/a-concept";
+import { A_FrameDynamicStructure_Init, A_FrameDynamicStructure_Serialized, A_FrameDynamicStructureEventNames, A_FrameDynamicStructureListener, A_FrameDynamicStructureResolvedComponent } from "./A-FrameDynamicStructure.types";
+import { A_FrameDynamicStructureFeatures } from "./A-FrameDynamicStructure.constants";
+import { A_FrameDynamicPatch } from "../A-FrameDynamicPatch/A-FrameDynamicPatch.entity";
+import { A_FrameDynamicStructureError } from "./A-FrameDynamicStructure.error";
+
+
+
+export class A_FrameDynamicStructure extends A_Entity<A_FrameDynamicStructure_Init, A_FrameDynamicStructure_Serialized> {
+    
+    static get concept(): string {
+        return 'a-frame';
+    }
+
+    // ── Identity ────────────────────────────────────────────────────────────────
+    prompt!: string;
+    createdAt!: number;
+
+    // ── Config ──────────────────────────────────────────────────────────────────
+    private model!: string;
+    private context!: string;
+    private metaHint!: string;
+    private includeBases!: string[];
+    private excludeBases!: string[];
+    private enabledComponents!: string[];
+    // ── State ───────────────────────────────────────────────────────────────────
+    private _components!: A_FrameDynamicStructureResolvedComponent[]
+    private _history!: A_FrameDynamicPatch[]
+    private _version = 0;
+
+    private listeners!: Map<string, Set<A_FrameDynamicStructureListener>>;
+
+    fromNew(options: A_FrameDynamicStructure_Init) {
+        this.createdAt = Date.now();
+
+        this._components = [];
+        this._history = [];
+        this._version = 0;
+
+        this.listeners = new Map();
+
+        this.prompt = options.prompt;
+        this.model = options.model;
+        this.context = options.context ?? 'generic';
+        this.metaHint = options.metaHint ?? '';
+        this.includeBases = (options.includeBases || []).map((b) => typeof b === 'string' ? b : A_CommonHelper.getComponentName(b));
+        this.excludeBases = (options.excludeBases || []).map((b) => typeof b === 'string' ? b : A_CommonHelper.getComponentName(b));
+        this.enabledComponents = (options.enabledComponents || []).map((b) => typeof b === 'string' ? b : A_CommonHelper.getComponentName(b));
+    }
+
+    // ── Public read-only accessors ───────────────────────────────────────────────
+
+    /** The current resolved component list (output of the last generate or patch). */
+    get components(): ReadonlyArray<A_FrameDynamicStructureResolvedComponent> {
+        return this._components;
+    }
+
+    /** Immutable patch history. */
+    get history(): ReadonlyArray<A_FrameDynamicPatch> {
+        return this._history;
+    }
+
+    /** Current schema version (increments with each patch). */
+    get version(): number {
+        return this._version;
+    }
+
+
+    // ── Main pipeline ────────────────────────────────────────────────────────────
+
+    /**
+     * Run the full generation pipeline:
+     *   content generation → structure mapping → encode → patch
+     *
+     * @returns The resolved component list.
+     */
+    async generate(): Promise<void> {
+        // const context = new A_FrameDynamicStructureOperation();
+
+        // const executionScope = new A_Scope({
+        //     name: 'a-frame-dynamic-structure-generate',
+        //     fragments: [context],
+        // })
+        //     .inherit(A_Context.scope(this));
+
+        // try {
+
+        //     await this.call(A_FrameDynamicStructureFeatures.Generate, executionScope);
+
+        //     executionScope.destroy();
+
+        //     return context;
+
+        // } catch (err) {
+        //     executionScope.destroy();
+        //     throw new A_FrameDynamicStructureError({
+        //         title: A_FrameDynamicStructureError.GenerationFailed,
+        //         description: `Failed to generate structure: ${err instanceof Error ? err.message : String(err)}`,
+        //     });
+        // }
+    }
+
+
+    async patch(prompt: string): Promise<void> {
+        this._version++;
+
+    }
+
+    /**
+     * Restore the component list to a specific version from history.
+     * Creates a new patch entry so the revert itself is tracked.
+     */
+    revertTo(version: number): this {
+        // this._currentVersion = version;
+
+        return this;
+    }
+
+    // ── Serialisation ─────────────────────────────────────────────────────────────
+
+    // /**
+    //  * Encode the complete DynamicStructure state to an opaque base64 string.
+    //  * Suitable for storage, transport, or embedding in another system.
+    //  */
+    // serialize(): string {
+    //     const payload: SerializedDynamicStructure = {
+    //         id: this.id,
+    //         version: this._version,
+    //         prompt: this.prompt,
+    //         components: [...this._components],
+    //         history: this._history.map(({ version, timestamp, reason }) => ({
+    //             version,
+    //             timestamp,
+    //             reason,
+    //         })),
+    //     };
+    //     return encode(payload);
+    // }
+
+    // /**
+    //  * Decode a serialised string back to its raw payload.
+    //  * Note: this is a static factory that returns the data only —
+    //  * it does not reconstruct a live DynamicStructure instance.
+    //  *
+    //  * To reconstruct a live instance, create a new DynamicStructure and
+    //  * call .patch() with the decoded components.
+    //  */
+    // static deserialize(encoded: string): SerializedDynamicStructure {
+    //     return decode<SerializedDynamicStructure>(encoded);
+    // }
+
+    toJSON(): A_FrameDynamicStructure_Serialized {
+        return {
+            ...super.toJSON(),
+            name: this.prompt,
+            description: `DynamicStructure with ${this._components.length} components and ${this._history.length} patches`,
+            metadata: {
+                model: this.model,
+                context: this.context,
+                metaHint: this.metaHint,
+                includeBases: this.includeBases,
+                excludeBases: this.excludeBases,
+                enabledComponents: this.enabledComponents,
+                createdAt: this.createdAt,
+            },
+            history: this._history.map(item => item.toJSON()),
+        }
+    }
+
+    // ── Internals ──────────────────────────────────────────────────────────────
+    subscribe(feature: A_FrameDynamicStructureEventNames, listener: A_FrameDynamicStructureListener): void {
+        if (!this.listeners.has(feature)) {
+            this.listeners.set(feature, new Set());
+        }
+        this.listeners.get(feature)!.add(listener);
+    }
+
+    unsubscribe(feature: A_FrameDynamicStructureEventNames, listener: A_FrameDynamicStructureListener): void {
+        this.listeners.get(feature)?.delete(listener);
+    }
+
+
+    emit(stage: A_FrameDynamicStructureEventNames, context: any): void {
+        this.listeners.get(stage)?.forEach(listener => listener(context));
+    }
+
+}

package/src/lib/A-FrameDynamicStructure/A-FrameDynamicStructure.error.ts

@@ -0,0 +1,13 @@
+import { A_Error } from "@adaas/a-concept";
+
+
+export class A_FrameDynamicStructureError extends A_Error {
+
+    static readonly InvalidPatch = 'InvalidPatch';
+    static readonly VersionMismatch = 'VersionMismatch';
+    static readonly ComponentNotFound = 'ComponentNotFound';
+    static readonly InvalidOperation = 'InvalidOperation';
+
+    static readonly GenerationFailed = 'GenerationFailed';
+   
+}

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

@@ -0,0 +1,128 @@
+import { A_Component, A_Container, A_Fragment, A_TYPES__Ctor, A_TYPES__Entity_Serialized } from "@adaas/a-concept";
+import { A_FrameDynamicPatch_Serialized } from "../A-FrameDynamicPatch/A-FrameDynamicPatch.types";
+import { A_FrameDynamicStructureEvents, A_FrameDynamicStructureFeatures } from "./A-FrameDynamicStructure.constants";
+import { A_FrameDynamicStructureOperation } from "./A-FrameDynamicStructureOperation.context";
+
+
+export type DynamicStructureDefaultBasesNames = 'A_Component' | 'A_Container' | 'A_Fragment';
+export type BaseClassName = DynamicStructureDefaultBasesNames | A_TYPES__Ctor<A_Component | A_Fragment | A_Container>;
+
+
+export type A_FrameDynamicStructure_Init = {
+    /** The goal / initial prompt driving structure generation */
+    prompt: string;
+
+    /** Which model to use for content generation */
+    model: string;
+
+    /** Only include components whose base class is in this list (empty = allow all) */
+    includeBases?: Array<BaseClassName | A_TYPES__Ctor<A_Component | A_Fragment | A_Container>>;
+
+    /** Exclude components whose base class is in this list */
+    excludeBases?: Array<string | A_TYPES__Ctor<A_Component | A_Fragment | A_Container>>;
+
+    /** Explicit list of component names to enable (subset of registry) */
+    enabledComponents?: Array<string | A_TYPES__Ctor<A_Component | A_Fragment | A_Container>>;
+
+    /** Rendering context hint passed to content generator */
+    context?: string;
+
+    /** Free-form hint about required prop types (forwarded to content generator) */
+    metaHint?: string;
+};
+
+export type A_FrameDynamicStructure_Serialized = {
+    name: string;
+    description?: string;
+    metadata?: Record<string, any>;
+    history: Array<A_FrameDynamicPatch_Serialized>;
+} & A_TYPES__Entity_Serialized
+
+
+export type A_FrameDynamicStructureListener = (context: A_FrameDynamicStructureOperation) => void;
+
+
+export type A_FrameDynamicStructureResolvedComponent<P extends Record<string, any> = Record<string, any>> = {
+    component: string;
+    score: number;
+    meta: P
+}
+
+export type A_FrameDynamicStructureFeatureNames = typeof A_FrameDynamicStructureFeatures[keyof typeof A_FrameDynamicStructureFeatures];
+
+
+export type A_FrameDynamicStructureEventNames = typeof A_FrameDynamicStructureEvents[keyof typeof A_FrameDynamicStructureEvents];
+
+
+export type A_FrameDynamicStructureDefinitionEntity = {
+    /**
+     * The prompt is the text that describes the element (component, container, fragment or entity) that is needed in the structure based on input prompt
+     * 
+     * 
+     * e.g. "A component that allows to search for something", "A container that runs a web server", "A fragment that stores user settings", "An entity that represents a user session", etc.
+     * 
+     * [!] Note, prompt should also contain the name of the element if it's possible, to make it easier to understand and use in the structure generation.
+     */
+    prompt: string;
+
+    /**
+     * The string set of params that is necessary to the particular element (component, container, fragment or entity) that is needed in the structure based on input prompt.
+     * Those parameters should be presented in the string manner and then mapped to the actual params in the structure generation process, to make it easier to understand and use in the structure generation.
+     * 
+     * e.g. "props: {query: string, resultsCount: number}", "constructorParams: {port: number}", "state: {isLoggedIn: boolean}", "ASEID", etc. or simply text: "Stores user with id=12345 and name=John Doe" if it's hard to define the params in a structured way.
+     * 
+     * [!] Params are applicable only for stateful components like Fragment, or Entity. Since components are stateless they can only rely on params in their methods received by @A_Inject(SomeFragment) someFragment: SomeFragment, where SomeFragment has state defined by params. And also for containers, since they can have constructor params and also rely on params of their components and fragments. 
+     * 
+     *  
+     */
+    params?: string
+}
+
+
+export type A_FrameDynamicStructureDefinition = {
+    /**
+     * A set of containers that the structure is needed based on input prompt
+     *  
+     * Where container is an instance of inherited class from A_Container that should be running independently and may have own components, fragments and entities.
+     * 
+     * e.g. HTTPServerContainer, WebWorker, AppContainer, etc.
+     * 
+     * [!] Note: should be presented only if initial query allows to have a container, and should be included only if necessary.
+     * 
+     */
+    containers: Array<A_FrameDynamicStructureDefinitionEntity & {
+        components: Array<A_FrameDynamicStructureDefinitionEntity>;
+        fragments: Array<A_FrameDynamicStructureDefinitionEntity>;
+        entities: Array<A_FrameDynamicStructureDefinitionEntity>;
+    }>;
+    /**
+     * A set of components that the structure is needed based on input prompt
+     * 
+     * Where Component is a constructor class from A_Component that allows to define something that is stateless, has methods and features and can be injected as a dependency in other components, fragments or containers.
+     * 
+     * e.g. SearchComponent, SettingsComponent, ButtonComponent, SectionComponent, etc.  
+     * 
+     * [!] Note: should be presented only if initial query allows to have a component, and should be included only if necessary.
+     */
+    components: Array<A_FrameDynamicStructureDefinitionEntity>;
+    /**
+     * A set of Context Fragments that the structure is needed based on input prompt
+     * 
+     * Where Fragment is an instance of inherited class from A_Fragment that allows to define something that has state and can be injected as a dependency in other components, fragments or containers.
+     * 
+     * e.g.  Settings, State, Store, etc.
+     * 
+     * [!] Note: should be presented only if initial query allows to have a fragment, and should be included only if necessary.
+     */
+    fragments: Array<A_FrameDynamicStructureDefinitionEntity>;
+    /**
+     * A set of Entities that the structure is needed based on input prompt
+     * 
+     * Where Entity is a A_Entity or a constructor of A_Entity that allows to define something that has ID(ASEID) and can be injected as a dependency in other components, fragments or containers.
+     * 
+     * e.g.  Session, User, Conversation, etc.
+     * 
+     * [!] Note: should be presented only if initial query allows to have an entity, and should be included only if necessary.
+     */
+    entities: Array<A_FrameDynamicStructureDefinitionEntity>;
+}

package/src/lib/A-FrameDynamicStructure/A-FrameDynamicStructureOperation.context.ts

@@ -0,0 +1,32 @@
+import { A_Fragment } from "@adaas/a-concept"
+
+
+export class A_FrameDynamicStructureOperation<
+    _InputParams = any,
+> extends A_Fragment {
+
+    protected _meta: Map<string, any> = new Map();
+
+    constructor(
+        params: _InputParams = {} as _InputParams
+    ) {
+        super({ name: 'a-frame-dynamic-structure-operation-context' });
+        this._meta.set('params', params);
+
+    }
+
+    get params(): _InputParams {
+        return this._meta.get('params');
+    }
+
+
+    get(key: string) {
+        return this._meta.get(key);
+    }
+
+
+    set(key: string, value: any) {
+        this._meta.set(key, value);
+    }
+
+}

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

@@ -0,0 +1,5 @@
+export * from './A-FrameDynamicStructure.constants';
+export * from './A-FrameDynamicStructure.entity';
+export * from './A-FrameDynamicStructure.types';
+export * from './A-FrameDynamicStructure.error';
+// export * from './A-FrameDynamicStructureO';

package/src/lib/A-FrameEnv/A-FrameEnv.fragment.env-browser.ts

@@ -0,0 +1,31 @@
+import { A_Fragment } from "@adaas/a-concept";
+import * as pkg from '../../../package.json';
+import { IA_FrameEnv } from "./A-FrameEnv.types";
+
+
+
+/**
+ * This class tailored from browser environment and it is used to get the env variables from the global scope and make them available for the A_FrameTask to use them in the task execution.
+ */
+export class A_FrameEnv extends A_Fragment implements IA_FrameEnv {
+
+    get A_FRAME_TOKEN() {
+        return (window as any).A_FRAME_TOKEN || '';
+    }
+
+    get A_FRAME_SERVER_URL() {
+        return (window as any).A_FRAME_SERVER_URL || 'http://localhost:3000';
+    }
+
+    get A_FRAME_VERSION() {
+        return pkg.version || '0.0.1';
+    }
+
+    get A_FRAME_SERVER_API_KEY() {
+        return (window as any).A_FRAME_SERVER_API_KEY || '';
+    }
+
+    get A_FRAME_STORAGE_DIR() {
+        return (window as any).A_FRAME_STORAGE_DIR || '.aframestr';
+    }
+}

package/src/lib/A-FrameEnv/A-FrameEnv.fragment.env-node.ts

@@ -0,0 +1,39 @@
+import { A_Fragment } from "@adaas/a-concept";
+import * as pkg from '../../../package.json';
+import { IA_FrameEnv } from "./A-FrameEnv.types";
+
+
+export class A_FrameEnv extends A_Fragment implements IA_FrameEnv {
+
+    get A_FRAME_FILE_EXTENSION() {
+        return '.aframe';
+    }
+
+    get A_FRAME_NAMESPACES_BIN() {
+        return `__namespaces${this.A_FRAME_FILE_EXTENSION}`;
+    }
+
+    get A_FRAME_SYNC() {
+        return process.env.A_FRAME_SYNC === 'false' ? false : true;
+    }
+
+    get A_FRAME_TOKEN() {
+        return process.env.A_FRAME_TOKEN || '';
+    }
+
+    get A_FRAME_SERVER_URL() {
+        return process.env.A_FRAME_SERVER_URL || 'http://localhost:3663';
+    }
+
+    get A_FRAME_SERVER_API_KEY() {
+        return process.env.A_FRAME_SERVER_API_KEY || '';
+    }
+
+    get A_FRAME_STORAGE_DIR() {
+        return process.env.A_FRAME_STORAGE_DIR || '.aframestr';
+    }
+
+    get A_FRAME_VERSION() {
+        return pkg.version || '0.0.1';
+    }
+}

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

@@ -0,0 +1,7 @@
+export interface IA_FrameEnv {
+    A_FRAME_TOKEN: string;
+    A_FRAME_SERVER_URL: string;
+    A_FRAME_SERVER_API_KEY: string;
+    A_FRAME_STORAGE_DIR: string;
+    A_FRAME_VERSION: string;
+}

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

@@ -0,0 +1 @@
+export * from './A-FrameEnv.fragment.env-browser';

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

@@ -0,0 +1 @@
+export * from './A-FrameEnv.fragment.env-node';