@adaas/a-frame 0.0.22 → 0.1.1

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

@@ -0,0 +1,321 @@
+import { A_Dependency, A_Fragment, A_Scope, ASEID } from "@adaas/a-concept";
+import { A_FrameVector } from "../A-FrameVector/A-FrameVector.entity";
+import { A_FrameNamespace } from "../A-FrameNamespace/A-FrameNamespace.entity";
+import { A_FrameDefinition_SearchResult, A_FrameSearchOptions } from "./A-FrameIndex.types";
+import { A_FrameDefinition } from "../A-FrameDefinition";
+import { A_FRAME_DEFAULT_NAMESPACE_KEY } from "../A-FrameNamespace/A-FrameNamespace.constants";
+
+
+
+export class A_FrameIndex extends A_Fragment {
+
+    private static _instance: A_FrameIndex;
+
+    static get instance(): A_FrameIndex {
+        if (!A_FrameIndex._instance) {
+            A_FrameIndex._instance = new A_FrameIndex();
+        }
+        return A_FrameIndex._instance;
+    }
+
+    static get indexSize(): number {
+        return A_FrameIndex.instance.indexSize;
+    }
+
+    // ------------------------------------------------------------------------------------
+    // --------------------Static Access to Instance Methods-------------------------------
+    // ------------------------------------------------------------------------------------
+    static inherit(scope: A_Scope) {
+        A_FrameIndex.instance.inherit(scope);
+    }
+    static addDefinition(def: A_FrameDefinition): void {
+        A_FrameIndex.instance.addDefinition(def);
+    }
+    static getDefinition(nameOrHash: string): A_FrameDefinition | undefined {
+        return A_FrameIndex.instance.getDefinition(nameOrHash);
+    }
+    static listDefinitions(filter: {
+        namespace?: string | A_FrameNamespace
+    }): A_FrameDefinition[] {
+        return A_FrameIndex.instance.listDefinitions(filter);
+    }
+    static removeDefinition(def: A_FrameDefinition): void {
+        A_FrameIndex.instance.removeDefinition(def);
+    }
+    static addNamespace(namespace: A_FrameNamespace): void {
+        A_FrameIndex.instance.addNamespace(namespace);
+    }
+    static getDefaultNamespace(): A_FrameNamespace {
+        return A_FrameIndex.instance.getDefaultNamespace();
+    }
+    static getNamespace(nameOrASEID: string | ASEID): A_FrameNamespace | undefined {
+        return A_FrameIndex.instance.getNamespace(nameOrASEID);
+    }
+    static listNamespaces(): A_FrameNamespace[] {
+        return A_FrameIndex.instance.listNamespaces();
+    }
+    static removeNamespace(namespace: A_FrameNamespace): void {
+        A_FrameIndex.instance.removeNamespace(namespace);
+    }
+    static search(
+        vector: A_FrameVector,
+        options: A_FrameSearchOptions = {},
+    ): A_FrameDefinition_SearchResult[] {
+        return A_FrameIndex.instance.search(vector, options);
+    }
+
+    // -------------------------------------------------------------------------------------
+    // ------------------------------ Instance State --------------------------------------
+    // -------------------------------------------------------------------------------------
+
+    private definitions: Map<string, A_FrameDefinition> = new Map();
+
+    private namespaces: Map<string, A_FrameNamespace> = new Map();
+
+    private _index!: {
+
+        namespaceToDefinitions: WeakMap<A_FrameNamespace, Set<A_FrameDefinition>>,
+
+        definitionToNamespace: WeakMap<A_FrameDefinition, A_FrameNamespace>,
+    };
+    /**
+     * Scope where all definitions and namespaces are registered as dependencies, allowing for lookup by ASEID or constructor reference.
+     */
+    private scope!: A_Scope
+
+
+    constructor() {
+        if (A_FrameIndex._instance)
+            return A_FrameIndex._instance;
+
+        super({ name: 'A_FrameIndex' });
+
+        this.scope = new A_Scope({ name: 'A_FrameIndexScope' });
+    }
+
+    /** Number of loaded records */
+    get indexSize(): number {
+        return this.definitions.size;
+    }
+
+
+    // static searchByText(
+    //     query: string,
+    //     channel: A_FrameChannel,
+    //     options: A_FrameSearchOptions = {},
+    // ): Promise<A_FrameDefinition_SearchResult[]> {
+    //     return A_FrameIndex.instance.searchByText(query, channel, options);
+    // }
+
+
+    // ------------------------------------------------------------------------------------
+    // ------------------------------ Instance Methods ------------------------------------
+    // ------------------------------------------------------------------------------------
+    inherit(scope: A_Scope) {
+        this.scope.inherit(scope);
+    }
+
+    addDefinition(def: A_FrameDefinition): void {
+        this.scope.register(def);
+
+        const existingNamespace = this.namespaces.get(def.namespace.id);
+        if (!existingNamespace) {
+            this.addNamespace(def.namespace);
+        }
+
+        this.definitions.set(def.id, def);
+    }
+
+    getDefinition(name: string): A_FrameDefinition | undefined {
+        // Then try name lookup
+        for (const def of this.definitions.values()) {
+            if (def.name === name) {
+                return def;
+            }
+        }
+
+        return undefined;
+    }
+
+    listDefinitions(filter: {
+        namespace?: string | A_FrameNamespace
+    } = {}): A_FrameDefinition[] {
+        const namespaceName = filter.namespace
+            ? typeof filter.namespace === 'string'
+                ? ASEID.isASEID(filter.namespace)
+                    ? new ASEID(filter.namespace).id
+                    : filter.namespace
+                : filter.namespace.id
+            : undefined;
+
+        return [...this.definitions.values()].filter(r => !namespaceName || r.namespace.name === namespaceName);
+    }
+
+    removeDefinition(def: A_FrameDefinition): void {
+        this.scope.deregister(def);
+    }
+
+    addNamespace(namespace: A_FrameNamespace): void {
+        this.scope.register(namespace);
+
+        this.namespaces.set(namespace.id, namespace);
+    }
+
+    getNamespace(nameOrASEID: string | ASEID): A_FrameNamespace | undefined {
+        const targetKey = typeof nameOrASEID === 'string'
+            ? ASEID.isASEID(nameOrASEID)
+                ? new ASEID(nameOrASEID).id
+                : nameOrASEID
+            : nameOrASEID.id;
+
+        return this.namespaces.get(targetKey);
+    }
+
+    getDefaultNamespace(): A_FrameNamespace {
+        // Ensure default namespace always exists
+        let defaultNamespace = this.getNamespace(A_FRAME_DEFAULT_NAMESPACE_KEY);
+        if (!defaultNamespace) {
+            defaultNamespace = new A_FrameNamespace({
+                name: A_FRAME_DEFAULT_NAMESPACE_KEY,
+            });
+            this.addNamespace(defaultNamespace);
+        }
+        return defaultNamespace;
+    }
+
+    listNamespaces(): A_FrameNamespace[] {
+        return [...this.namespaces.values()];
+    }
+
+    removeNamespace(namespace: A_FrameNamespace): void {
+        this.scope.deregister(namespace);
+        this.namespaces.delete(namespace.id);
+    }
+
+
+    /**
+     * Search by a pre-computed embedding vector (cosine similarity).
+     */
+    search(
+        vector: A_FrameVector,
+        options: A_FrameSearchOptions = {},
+    ): A_FrameDefinition_SearchResult[] {
+
+        const { topK = 10, namespace, minScore = 0 } = options;
+
+        const pool = namespace
+            ? [...this.definitions.values()].filter(r => r.namespace.id === namespace)
+            : [...this.definitions.values()];
+
+        const scored = pool.map(r => ({
+            record: r,
+            score: this.cosineSimilarity(vector, r.vector),
+        }));
+
+        return scored
+            .filter(s => s.score >= minScore)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK)
+            .map(({ record: r, score }) => ({
+                record: r,
+                score,
+            }));
+    }
+
+    // protected cosineSimilarity(vectorA: A_FrameVector, vectorB?: A_FrameVector): number {
+    //     const a = vectorA.values ?? new Float32Array();
+    //     const b = vectorB?.values ?? new Float32Array();
+
+    //     if (a.length !== b.length) {
+    //         throw new Error(`A_FrameIndex: dimension mismatch ${a.length} vs ${b.length}`);
+    //     }
+    //     let dot = 0, normA = 0, normB = 0;
+    //     for (let i = 0; i < a.length; i++) {
+    //         dot += a[i] * b[i];
+    //         normA += a[i] * a[i];
+    //         normB += b[i] * b[i];
+    //     }
+    //     const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    //     return denom === 0 ? 0 : dot / denom;
+    // }
+
+    cosineSimilarity(
+        a: A_FrameVector,
+        b?: A_FrameVector
+    ): number {
+        if (!b) return 0
+
+        const dot = a.dot(b)
+        const mag = a.magnitude() * b.magnitude()
+        return mag === 0 ? 0 : dot / mag
+    }
+
+    euclideanDistance(
+        a: A_FrameVector,
+        b: A_FrameVector
+    ): number {
+        this.assertSameLength(a, b)
+
+        let sum = 0
+        for (let i = 0; i < a.length; i++) {
+            const diff = a.values[i] - b.values[i]
+            sum += diff * diff
+        }
+        return Math.sqrt(sum)
+    }
+
+    nearest(
+        query: A_FrameVector,
+        vectors: readonly A_FrameVector[],
+        limit = 1
+    ): A_FrameVector[] {
+        return [...vectors]
+            .map(v => ({
+                vector: v,
+                score: this.cosineSimilarity(query, v),
+            }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit)
+            .map(r => r.vector)
+    }
+
+    rank(
+        query: A_FrameVector,
+        vectors: readonly A_FrameVector[]
+    ): Array<{ vector: A_FrameVector; score: number }> {
+        return vectors
+            .map(v => ({
+                vector: v,
+                score: this.cosineSimilarity(query, v),
+            }))
+            .sort((a, b) => b.score - a.score)
+    }
+
+    private assertSameLength(
+        a: A_FrameVector,
+        b: A_FrameVector
+    ) {
+        if (a.length !== b.length) {
+            throw new Error(
+                `Embedding dimension mismatch: ${a.length} vs ${b.length}`
+            )
+        }
+    }
+
+
+
+    /**
+     * Search by plain text — sends the query to the embed server via channel first.
+     */
+    // async searchByText(
+    //     query: string,
+    //     channel: A_FrameChannel,
+    //     options: A_FrameSearchOptions = {},
+    // ): Promise<A_FrameDefinition_SearchResult[]> {
+    //     this.assertLoaded();
+    //     const resp = await channel.embed(query);
+    //     const queryEmbedding = new Float32Array(resp.data[0].embedding);
+    //     return this.search(queryEmbedding, options);
+    // }
+
+}

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

@@ -0,0 +1,63 @@
+import { A_Component, A_Container, A_Entity, A_Fragment, A_TYPES__Component_Constructor, A_TYPES__Container_Constructor, A_TYPES__Entity_Constructor, A_TYPES__Fragment_Constructor, A_TYPES__Required } from "@adaas/a-concept"
+import { A_FrameTargetType } from "../A-Frame/A-Frame.types"
+import { A_FrameNamespace } from "../A-FrameNamespace"
+import { A_FrameDefinition } from "../A-FrameDefinition"
+
+
+
+export type A_FrameIndexTarget = A_TYPES__Container_Constructor
+    | A_TYPES__Entity_Constructor
+    | A_TYPES__Component_Constructor
+    | A_TYPES__Fragment_Constructor
+
+
+// ---------------------------------------------------------------------------
+// ------------- A-Frame Index Configurations Meta Types----------------------
+// ---------------------------------------------------------------------------
+
+export type A_FrameMetaDefinition<T extends Record<string, any> = {}> = {
+    name: string,
+    hash: string,
+    source: string,
+    type: A_FrameTargetType,
+    namespace?: string | A_FrameNamespace,
+    description?: string,
+    metadata?: T,
+    examples?: string[]
+}
+
+
+export type A_FrameIndexMetaType = {
+    namespaces: string,
+    descriptions: string,
+    type: string,
+    name: string,
+    methods: Map<string, A_FrameIndexMetaMethodMeta>
+}
+
+
+export type A_FrameIndexMetaMethodMeta = {
+    name: string,
+    description?: string,
+    methodName: string
+}
+
+
+// ---------------------------------------------------------------------------
+// ------------- A-Frame Runtime Search Types --------------------------------
+// ---------------------------------------------------------------------------
+
+export type A_FrameSearchOptions = {
+    /** Maximum number of results; default 10 */
+    topK?: number
+    /** Restrict search to a single namespace; undefined = all */
+    namespace?: string
+    /** Minimum cosine similarity score (0–1); default 0 */
+    minScore?: number
+}
+
+
+export type A_FrameDefinition_SearchResult = {
+    record: A_FrameDefinition,
+    score: number
+}

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

@@ -0,0 +1,3 @@
+export * from './A-FrameIndex.context';
+export * from './A-FrameIndex.types';
+// export * from './A-FrameIndex.constants';

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

@@ -0,0 +1,3 @@
+export * from './A-FrameIndex.context';
+export * from './A-FrameIndex.types';
+// export * from './A-FrameIndex.constants';

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

@@ -0,0 +1,99 @@
+import { A_FrameLoggerBase } from "./A-FrameLogger.component";
+import {
+    A_FrameLogEntry,
+    A_FrameLogLevelType,
+    A_FrameLoggerConfig,
+    A_FrameProgressBar,
+} from "./A-FrameLogger.types";
+import {
+    A_FRAME_BROWSER_CSS,
+    A_FRAME_LOG_DEFAULTS,
+    A_FrameLogIcon,
+} from "./A-FrameLogger.constants";
+
+
+/**
+ * A_FrameLogger — Browser environment.
+ *
+ * Renders to the DevTools console using `%c` CSS styling. Progress is shown
+ * via throttled console lines (no in-place redraw available in the browser).
+ */
+export class A_FrameLogger extends A_FrameLoggerBase {
+
+    constructor(config: A_FrameLoggerConfig = {}) {
+        super(config);
+    }
+
+    protected write(entry: A_FrameLogEntry): void {
+        const icon = A_FrameLogIcon[entry.level];
+        const css = A_FRAME_BROWSER_CSS[entry.level];
+        const fn: (...args: unknown[]) => void =
+            entry.level === 'error' ? console.error
+                : entry.level === 'warn' ? console.warn
+                    : console.log;
+
+        if (entry.metadata && Object.keys(entry.metadata).length > 0) {
+            fn(`%c${icon} ${entry.message}`, css, entry.metadata);
+        } else {
+            fn(`%c${icon} ${entry.message}`, css);
+        }
+    }
+
+    section(title: string): void {
+        console.log(`%c┄ ${title} ┄`, 'color: #06b; font-weight: bold; padding: 2px 0;');
+    }
+
+    divider(): void {
+        console.log('%c────────────────────────────────────────', 'color: #aaa;');
+    }
+
+    summary(title: string = A_FRAME_LOG_DEFAULTS.summaryTitle): void {
+        this.section(title);
+        const obj: Record<string, number | string> = {};
+        for (const [k, v] of this.counters) obj[k] = v;
+        obj.elapsed = this.elapsed();
+        // console.table is universally supported and renders much nicer than
+        // line-by-line in the browser DevTools.
+        console.table(obj);
+        this.divider();
+    }
+
+    // ─── Progress bar ────────────────────────────────────────────────────────
+
+    progress(label: string, total: number): A_FrameProgressBar {
+        const start = Date.now();
+        let current = 0;
+        let lastLabel = '';
+        let lastEmit = 0;
+
+        const emit = (force = false, status?: 'done' | 'fail') => {
+            const now = Date.now();
+            if (!force && now - lastEmit < A_FRAME_LOG_DEFAULTS.progressThrottleMs) return;
+            lastEmit = now;
+
+            const pct = total > 0 ? Math.min(100, Math.round((current / total) * 100)) : 100;
+            const tail = lastLabel ? ` — ${lastLabel}` : '';
+
+            if (status === 'done') {
+                console.log(
+                    `%c✔ ${label} ${current}/${total} (${pct}%)%c — ${((now - start) / 1000).toFixed(2)}s`,
+                    A_FRAME_BROWSER_CSS.success,
+                    'color: #888;',
+                );
+            } else if (status === 'fail') {
+                console.log(`%c✖ ${label} FAILED at ${current}/${total}`, A_FRAME_BROWSER_CSS.error);
+            } else {
+                console.log(`%c⟳ ${label} ${current}/${total} (${pct}%)${tail}`, A_FRAME_BROWSER_CSS.info);
+            }
+        };
+
+        emit(true);
+
+        return {
+            tick: (l?: string) => { current = Math.min(total, current + 1); if (l) lastLabel = l; emit(); },
+            succeed: (l?: string) => { if (l) lastLabel = l; current = total; emit(true, 'done'); },
+            fail: (l?: string) => { if (l) lastLabel = l; emit(true, 'fail'); },
+            update: (n: number, l?: string) => { current = Math.min(total, Math.max(0, n)); if (l) lastLabel = l; emit(); },
+        };
+    }
+}

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

@@ -0,0 +1,129 @@
+import { A_FrameLoggerBase } from "./A-FrameLogger.component";
+import {
+    A_FrameLogEntry,
+    A_FrameLogLevelType,
+    A_FrameLoggerConfig,
+    A_FrameProgressBar,
+} from "./A-FrameLogger.types";
+import {
+    A_FRAME_ANSI,
+    A_FRAME_LOG_DEFAULTS,
+    A_FrameLogIcon,
+} from "./A-FrameLogger.constants";
+
+
+/** Map a level → ANSI colour code for its leading icon. */
+const ICON_COLOR: Record<A_FrameLogLevelType, string> = {
+    debug: A_FRAME_ANSI.gray,
+    info: A_FRAME_ANSI.cyan,
+    success: A_FRAME_ANSI.green,
+    warn: A_FRAME_ANSI.yellow,
+    error: A_FRAME_ANSI.red,
+};
+
+
+/**
+ * A_FrameLogger — Node.js environment.
+ *
+ * Renders to stdout with ANSI colour codes and inline progress bars when
+ * stdout is a TTY. Falls back to plain text otherwise (CI, log files).
+ */
+export class A_FrameLogger extends A_FrameLoggerBase {
+
+    private readonly useColor: boolean;
+
+    constructor(config: A_FrameLoggerConfig = {}) {
+        super(config);
+        this.useColor = config.color ?? !!(process.stdout && process.stdout.isTTY);
+    }
+
+    private c(code: string, str: string): string {
+        return this.useColor ? `${code}${str}${A_FRAME_ANSI.reset}` : str;
+    }
+
+    protected write(entry: A_FrameLogEntry): void {
+        const icon = this.c(ICON_COLOR[entry.level], A_FrameLogIcon[entry.level]);
+        const line = `${icon} ${entry.message}`;
+        if (entry.level === 'error') console.error(line);
+        else if (entry.level === 'warn') console.warn(line);
+        else console.log(line);
+
+        if (entry.metadata && Object.keys(entry.metadata).length > 0) {
+            console.log(this.c(A_FRAME_ANSI.gray, `   ${JSON.stringify(entry.metadata)}`));
+        }
+    }
+
+    section(title: string): void {
+        const line = '─'.repeat(Math.max(2, 60 - title.length - 4));
+        const heading = `┄ ${title} ${line}`;
+        console.log('\n' + this.c(A_FRAME_ANSI.bold + A_FRAME_ANSI.cyan, heading));
+    }
+
+    divider(): void {
+        console.log(this.c(A_FRAME_ANSI.gray, '─'.repeat(60)));
+    }
+
+    summary(title: string = A_FRAME_LOG_DEFAULTS.summaryTitle): void {
+        this.section(title);
+        const keys = [...this.counters.keys()];
+        const pad = keys.reduce((m, k) => Math.max(m, k.length), 'elapsed'.length);
+        for (const key of keys) {
+            console.log(`  ${this.c(A_FRAME_ANSI.gray, key.padEnd(pad))}  ${this.c(A_FRAME_ANSI.bold, String(this.counters.get(key)))}`);
+        }
+        console.log(`  ${this.c(A_FRAME_ANSI.gray, 'elapsed'.padEnd(pad))}  ${this.c(A_FRAME_ANSI.bold, this.elapsed())}`);
+        this.divider();
+    }
+
+    // ─── Progress bar ────────────────────────────────────────────────────────
+
+    progress(label: string, total: number): A_FrameProgressBar {
+        const isTTY = this.useColor; // colour ⟺ TTY by default
+        const width = A_FRAME_LOG_DEFAULTS.progressBarWidth;
+        const start = Date.now();
+
+        let current = 0;
+        let lastLabel = '';
+
+        const render = (status?: 'done' | 'fail') => {
+            if (total === 0) {
+                if (status === 'done') console.log(`${this.c(A_FRAME_ANSI.green, '✔')} ${label} (0/0)`);
+                return;
+            }
+            const pct = Math.min(1, current / total);
+            const filled = Math.round(pct * width);
+
+            if (isTTY) {
+                const bar =
+                    this.c(A_FRAME_ANSI.green, '█'.repeat(filled)) +
+                    this.c(A_FRAME_ANSI.gray, '░'.repeat(width - filled));
+                const head = status === 'done' ? this.c(A_FRAME_ANSI.green, '✔')
+                    : status === 'fail' ? this.c(A_FRAME_ANSI.red, '✖')
+                        : this.c(A_FRAME_ANSI.cyan, '⟳');
+                const tail = lastLabel ? this.c(A_FRAME_ANSI.dim, ` — ${lastLabel}`) : '';
+                process.stdout.write(`\r\x1b[2K${head} ${label} ${bar} ${current}/${total} (${(pct * 100).toFixed(0)}%)${tail}`);
+                if (status) process.stdout.write('\n');
+            } else {
+                if (status === 'done') {
+                    console.log(`[${label}] done ${current}/${total} in ${((Date.now() - start) / 1000).toFixed(2)}s`);
+                } else if (status === 'fail') {
+                    console.log(`[${label}] FAILED at ${current}/${total}`);
+                } else {
+                    // Throttle: only print at 10% boundaries when not on a TTY
+                    const step = Math.max(1, Math.floor(total / 10));
+                    if (current === total || current % step === 0) {
+                        console.log(`[${label}] ${current}/${total}${lastLabel ? ` — ${lastLabel}` : ''}`);
+                    }
+                }
+            }
+        };
+
+        render();
+
+        return {
+            tick: (l?: string) => { current = Math.min(total, current + 1); if (l) lastLabel = l; render(); },
+            succeed: (l?: string) => { if (l) lastLabel = l; current = total; render('done'); },
+            fail: (l?: string) => { if (l) lastLabel = l; render('fail'); },
+            update: (n: number, l?: string) => { current = Math.min(total, Math.max(0, n)); if (l) lastLabel = l; render(); },
+        };
+    }
+}