@open-core/framework 1.0.4-beta.1 → 1.0.5-beta.2

package/dist/runtime/client/webview.service.d.ts

@@ -0,0 +1,14 @@
+import type { WebViewCapabilities, WebViewDefinition, WebViewFocusOptions, WebViewMessage } from '../../adapters/contracts/client/ui/webview/types';
+export declare class WebViewService {
+    private get bridge();
+    getCapabilities(): WebViewCapabilities;
+    create(definition: WebViewDefinition): void;
+    destroy(viewId: string): void;
+    exists(viewId: string): boolean;
+    show(viewId: string): void;
+    hide(viewId: string): void;
+    focus(viewId: string, options?: WebViewFocusOptions): void;
+    blur(viewId: string): void;
+    send(viewId: string, event: string, payload: unknown): void;
+    onMessage(handler: (message: WebViewMessage) => void | Promise<void>): () => void;
+}

package/dist/runtime/client/webview.service.js

@@ -0,0 +1,98 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { injectable } from 'tsyringe';
+import { coreLogger, LogDomain } from '../../kernel/logger';
+import { IClientWebViewBridge } from '../../adapters/contracts/client/ui/webview/IClientWebViewBridge';
+import { IClientRuntimeBridge } from './adapter/runtime-bridge';
+import { di } from './client-container';
+const webViewLogger = coreLogger.child('WebView', LogDomain.CLIENT);
+const FALLBACK_CAPABILITIES = {
+    supportsFocus: true,
+    supportsCursor: true,
+    supportsInputPassthrough: true,
+    supportsBidirectionalMessaging: true,
+    supportsExecute: false,
+    supportsHeadless: false,
+};
+function createFallbackBridge() {
+    const runtime = di.resolve(IClientRuntimeBridge);
+    const handlers = new Set();
+    let registered = false;
+    return {
+        getCapabilities: () => FALLBACK_CAPABILITIES,
+        create: () => { },
+        destroy: () => { },
+        exists: () => true,
+        show: () => { },
+        hide: () => { },
+        focus: (_viewId, options) => {
+            runtime.setWebViewFocus(true, options?.cursor ?? true);
+            runtime.setWebViewInputPassthrough(options?.inputPassthrough ?? false);
+        },
+        blur: () => runtime.setWebViewFocus(false, false),
+        send: (viewId, event, payload) => {
+            runtime.sendWebViewMessage(JSON.stringify({ __opencoreWebView: true, viewId, action: event, data: payload }));
+        },
+        onMessage: (handler) => {
+            if (!registered) {
+                registered = true;
+                runtime.registerWebViewCallback('__opencore:webview:message', async (data, cb) => {
+                    const message = data;
+                    for (const item of handlers)
+                        await item(message);
+                    cb({ ok: true });
+                });
+            }
+            handlers.add(handler);
+            return () => handlers.delete(handler);
+        },
+    };
+}
+let WebViewService = class WebViewService {
+    get bridge() {
+        if (di.isRegistered(IClientWebViewBridge)) {
+            return di.resolve(IClientWebViewBridge);
+        }
+        return createFallbackBridge();
+    }
+    getCapabilities() {
+        return this.bridge.getCapabilities();
+    }
+    create(definition) {
+        this.bridge.create(definition);
+        webViewLogger.debug('Created webview', { id: definition.id, url: definition.url });
+    }
+    destroy(viewId) {
+        this.bridge.destroy(viewId);
+        webViewLogger.debug('Destroyed webview', { id: viewId });
+    }
+    exists(viewId) {
+        return this.bridge.exists(viewId);
+    }
+    show(viewId) {
+        this.bridge.show(viewId);
+    }
+    hide(viewId) {
+        this.bridge.hide(viewId);
+    }
+    focus(viewId, options) {
+        this.bridge.focus(viewId, options);
+    }
+    blur(viewId) {
+        this.bridge.blur(viewId);
+    }
+    send(viewId, event, payload) {
+        this.bridge.send(viewId, event, payload);
+    }
+    onMessage(handler) {
+        return this.bridge.onMessage(handler);
+    }
+};
+WebViewService = __decorate([
+    injectable()
+], WebViewService);
+export { WebViewService };

package/dist/runtime/core/entity.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Entity identifier format: `kind:id`
+ * @example 'player:1', 'vehicle:42', 'npc:spawn-1'
+ */
+export type EntityId = `${string}:${string | number}`;
+/**
+ * Entity metadata storage type.
+ */
+export type EntityMeta = Record<string, unknown>;
+/**
+ * Base entity class for all game entities.
+ *
+ * @remarks
+ * Provides common functionality for all entities in the game world:
+ * - Unique identification
+ * - State flags (active states like 'dead', 'frozen', etc.)
+ * - Metadata storage
+ * - Dimension/world support
+ *
+ * This class is platform-agnostic and should be extended by
+ * platform-specific entity implementations.
+ */
+export declare abstract class BaseEntity {
+    /**
+     * Unique identifier for this entity.
+     * Format: `kind:id` (e.g., 'player:1', 'vehicle:42')
+     */
+    readonly id: EntityId;
+    /**
+     * Entity kind extracted from the ID.
+     * @example 'player', 'vehicle', 'npc'
+     */
+    readonly kind: string;
+    /**
+     * Active state flags.
+     */
+    private state;
+    /**
+     * Transient metadata storage.
+     */
+    private meta;
+    /**
+     * Current dimension/world ID.
+     * 0 is the default shared world.
+     */
+    protected _dimension: number;
+    /**
+     * Stream distance for this entity.
+     * Determines how far away players can see this entity.
+     */
+    protected _streamDistance: number;
+    /**
+     * Creates a new entity.
+     * @param id - Unique entity identifier in format 'kind:id'
+     */
+    constructor(id: EntityId);
+    /**
+     * Adds a state flag to the entity.
+     * @param state - State identifier (e.g., 'dead', 'frozen', 'invisible')
+     */
+    add(state: string): void;
+    /**
+     * Checks if the entity has a state flag.
+     * @param key - State identifier to check
+     */
+    has(key: string): boolean;
+    /**
+     * Gets all active state flags.
+     * @returns Array of state identifiers
+     */
+    all(): string[];
+    /**
+     * Removes a state flag from the entity.
+     * @param key - State identifier to remove
+     */
+    delete(key: string): void;
+    /**
+     * Clears all state flags.
+     */
+    clearStates(): void;
+    /**
+     * Toggles a state flag.
+     * @param state - State identifier
+     * @param force - Optional force value (true = add, false = remove)
+     * @returns The new state (true if added, false if removed)
+     */
+    toggle(state: string, force?: boolean): boolean;
+    /**
+     * Sets a metadata value.
+     * @param key - Metadata key
+     * @param value - Value to store
+     */
+    setMeta<T = unknown>(key: string, value: T): void;
+    /**
+     * Gets a metadata value.
+     * @param key - Metadata key
+     * @returns The stored value or undefined
+     */
+    getMeta<T = unknown>(key: string): T | undefined;
+    /**
+     * Checks if a metadata key exists.
+     * @param key - Metadata key
+     */
+    hasMeta(key: string): boolean;
+    /**
+     * Deletes a metadata value.
+     * @param key - Metadata key
+     */
+    deleteMeta(key: string): void;
+    /**
+     * Gets all metadata.
+     * @returns Copy of the metadata object
+     */
+    getAllMeta(): EntityMeta;
+    /**
+     * Clears all metadata.
+     */
+    clearMeta(): void;
+    /**
+     * Gets the current dimension/world ID.
+     *
+     * @remarks
+     * Override this in platform-specific implementations to sync
+     * with the actual game engine dimension system.
+     */
+    get dimension(): number;
+    /**
+     * Sets the dimension/world ID.
+     *
+     * @remarks
+     * Override this in platform-specific implementations to sync
+     * with the actual game engine dimension system.
+     */
+    set dimension(value: number);
+    /**
+     * Gets the stream distance for this entity.
+     *
+     * @remarks
+     * Stream distance determines how far away players can see this entity.
+     * Not all platforms support custom stream distances.
+     */
+    get streamDistance(): number;
+    /**
+     * Sets the stream distance for this entity.
+     */
+    set streamDistance(value: number);
+    /**
+     * Creates a snapshot of the entity state.
+     * @returns Plain object with entity data
+     */
+    snapshot(): EntitySnapshot;
+    /**
+     * Restores entity state from a snapshot.
+     * @param snapshot - Snapshot to restore from
+     */
+    restore(snapshot: Partial<EntitySnapshot>): void;
+}
+/**
+ * Entity snapshot for serialization.
+ */
+export interface EntitySnapshot {
+    id: EntityId;
+    kind: string;
+    states: string[];
+    meta: EntityMeta;
+    dimension: number;
+    streamDistance: number;
+}

package/dist/runtime/core/entity.js

@@ -0,0 +1,232 @@
+/**
+ * Base entity class for all game entities.
+ *
+ * @remarks
+ * Provides common functionality for all entities in the game world:
+ * - Unique identification
+ * - State flags (active states like 'dead', 'frozen', etc.)
+ * - Metadata storage
+ * - Dimension/world support
+ *
+ * This class is platform-agnostic and should be extended by
+ * platform-specific entity implementations.
+ */
+export class BaseEntity {
+    /**
+     * Unique identifier for this entity.
+     * Format: `kind:id` (e.g., 'player:1', 'vehicle:42')
+     */
+    id;
+    /**
+     * Entity kind extracted from the ID.
+     * @example 'player', 'vehicle', 'npc'
+     */
+    kind;
+    /**
+     * Active state flags.
+     */
+    state = new Set();
+    /**
+     * Transient metadata storage.
+     */
+    meta = {};
+    /**
+     * Current dimension/world ID.
+     * 0 is the default shared world.
+     */
+    _dimension = 0;
+    /**
+     * Stream distance for this entity.
+     * Determines how far away players can see this entity.
+     */
+    _streamDistance = 100;
+    /**
+     * Creates a new entity.
+     * @param id - Unique entity identifier in format 'kind:id'
+     */
+    constructor(id) {
+        this.id = id;
+        this.kind = id.split(':')[0];
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // State Management
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Adds a state flag to the entity.
+     * @param state - State identifier (e.g., 'dead', 'frozen', 'invisible')
+     */
+    add(state) {
+        this.state.add(state);
+    }
+    /**
+     * Checks if the entity has a state flag.
+     * @param key - State identifier to check
+     */
+    has(key) {
+        return this.state.has(key);
+    }
+    /**
+     * Gets all active state flags.
+     * @returns Array of state identifiers
+     */
+    all() {
+        return Array.from(this.state);
+    }
+    /**
+     * Removes a state flag from the entity.
+     * @param key - State identifier to remove
+     */
+    delete(key) {
+        this.state.delete(key);
+    }
+    /**
+     * Clears all state flags.
+     */
+    clearStates() {
+        this.state.clear();
+    }
+    /**
+     * Toggles a state flag.
+     * @param state - State identifier
+     * @param force - Optional force value (true = add, false = remove)
+     * @returns The new state (true if added, false if removed)
+     */
+    toggle(state, force) {
+        if (force !== undefined) {
+            force ? this.add(state) : this.delete(state);
+            return force;
+        }
+        if (this.has(state)) {
+            this.delete(state);
+            return false;
+        }
+        this.add(state);
+        return true;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Metadata Management
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Sets a metadata value.
+     * @param key - Metadata key
+     * @param value - Value to store
+     */
+    setMeta(key, value) {
+        this.meta[key] = value;
+    }
+    /**
+     * Gets a metadata value.
+     * @param key - Metadata key
+     * @returns The stored value or undefined
+     */
+    getMeta(key) {
+        return this.meta[key];
+    }
+    /**
+     * Checks if a metadata key exists.
+     * @param key - Metadata key
+     */
+    hasMeta(key) {
+        return key in this.meta;
+    }
+    /**
+     * Deletes a metadata value.
+     * @param key - Metadata key
+     */
+    deleteMeta(key) {
+        delete this.meta[key];
+    }
+    /**
+     * Gets all metadata.
+     * @returns Copy of the metadata object
+     */
+    getAllMeta() {
+        return { ...this.meta };
+    }
+    /**
+     * Clears all metadata.
+     */
+    clearMeta() {
+        this.meta = {};
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Dimension/World Support
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Gets the current dimension/world ID.
+     *
+     * @remarks
+     * Override this in platform-specific implementations to sync
+     * with the actual game engine dimension system.
+     */
+    get dimension() {
+        return this._dimension;
+    }
+    /**
+     * Sets the dimension/world ID.
+     *
+     * @remarks
+     * Override this in platform-specific implementations to sync
+     * with the actual game engine dimension system.
+     */
+    set dimension(value) {
+        this._dimension = value;
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Stream Distance
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Gets the stream distance for this entity.
+     *
+     * @remarks
+     * Stream distance determines how far away players can see this entity.
+     * Not all platforms support custom stream distances.
+     */
+    get streamDistance() {
+        return this._streamDistance;
+    }
+    /**
+     * Sets the stream distance for this entity.
+     */
+    set streamDistance(value) {
+        this._streamDistance = Math.max(0, value);
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Serialization
+    // ─────────────────────────────────────────────────────────────────
+    /**
+     * Creates a snapshot of the entity state.
+     * @returns Plain object with entity data
+     */
+    snapshot() {
+        return {
+            id: this.id,
+            kind: this.kind,
+            states: this.all(),
+            meta: this.getAllMeta(),
+            dimension: this._dimension,
+            streamDistance: this._streamDistance,
+        };
+    }
+    /**
+     * Restores entity state from a snapshot.
+     * @param snapshot - Snapshot to restore from
+     */
+    restore(snapshot) {
+        if (snapshot.states) {
+            this.clearStates();
+            for (const s of snapshot.states) {
+                this.add(s);
+            }
+        }
+        if (snapshot.meta) {
+            this.meta = { ...snapshot.meta };
+        }
+        if (snapshot.dimension !== undefined) {
+            this._dimension = snapshot.dimension;
+        }
+        if (snapshot.streamDistance !== undefined) {
+            this._streamDistance = snapshot.streamDistance;
+        }
+    }
+}

package/dist/runtime/core/index.d.ts

@@ -0,0 +1,5 @@
+export * from './entity';
+export * from './library';
+export * from './spatial';
+export * from './world';
+export * from './nativehandle';

package/dist/runtime/core/index.js

@@ -0,0 +1,5 @@
+export * from './entity';
+export * from './library';
+export * from './spatial';
+export * from './world';
+export * from './nativehandle';

package/dist/runtime/core/library/create-library-base.d.ts

@@ -0,0 +1,15 @@
+import { OpenCoreLibraryBase } from './types';
+/**
+ * Creates the shared base API for an OpenCore library.
+ *
+ * @remarks
+ * The base contains only library-local events (internal bus) and namespaced
+ * event-name building. External bridge behavior is added by server/client wrappers.
+ */
+export declare function createLibraryBase(name: string, opts?: {
+    namespace?: string;
+}): OpenCoreLibraryBase;
+/**
+ * Backwards-compatible alias.
+ */
+export declare const createLibraryCore: typeof createLibraryBase;

package/dist/runtime/core/library/create-library-base.js

@@ -0,0 +1,27 @@
+import { createLibraryBus } from './library-bus';
+/**
+ * Creates the shared base API for an OpenCore library.
+ *
+ * @remarks
+ * The base contains only library-local events (internal bus) and namespaced
+ * event-name building. External bridge behavior is added by server/client wrappers.
+ */
+export function createLibraryBase(name, opts) {
+    const bus = createLibraryBus();
+    const namespace = opts?.namespace ?? `opencore:${name}`;
+    return {
+        name,
+        namespace,
+        on: bus.on,
+        once: bus.once,
+        off: bus.off,
+        emit: bus.emit,
+        buildEventName(eventName) {
+            return `${namespace}:${eventName}`;
+        },
+    };
+}
+/**
+ * Backwards-compatible alias.
+ */
+export const createLibraryCore = createLibraryBase;

package/dist/runtime/core/library/index.d.ts

@@ -0,0 +1,5 @@
+export { createLibraryBase, createLibraryCore } from './create-library-base';
+export { buildLibraryEventId } from './library-event-id';
+export { createLibraryBus } from './library-bus';
+export { createLibraryConfigAccessor } from './library-config';
+export type { LibraryEventEnvelope, LibraryEventId, LibraryBus, LibraryEventHandler, LibraryEventName, LibraryEventMetadata, LibraryName, LibraryNamespace, OpenCoreClientLibrary, OpenCoreLibraryBase, OpenCoreLibraryConfigAccessor, OpenCoreServerLibrary, } from './types';

package/dist/runtime/core/library/index.js

@@ -0,0 +1,4 @@
+export { createLibraryBase, createLibraryCore } from './create-library-base';
+export { buildLibraryEventId } from './library-event-id';
+export { createLibraryBus } from './library-bus';
+export { createLibraryConfigAccessor } from './library-config';

package/dist/runtime/core/library/library-bus.d.ts

@@ -0,0 +1,9 @@
+import { LibraryBus } from './types';
+/**
+ * Creates a lightweight library-local event bus.
+ *
+ * @remarks
+ * This is a pure TypeScript event bus intended for internal library events.
+ * It does not use FiveM, network events, or Node core modules.
+ */
+export declare function createLibraryBus(): LibraryBus;

package/dist/runtime/core/library/library-bus.js

@@ -0,0 +1,46 @@
+/**
+ * Creates a lightweight library-local event bus.
+ *
+ * @remarks
+ * This is a pure TypeScript event bus intended for internal library events.
+ * It does not use FiveM, network events, or Node core modules.
+ */
+export function createLibraryBus() {
+    const handlers = new Map();
+    const on = (event, handler) => {
+        const eventHandlers = handlers.get(event) ?? new Set();
+        eventHandlers.add(handler);
+        handlers.set(event, eventHandlers);
+    };
+    const off = (event, handler) => {
+        const eventHandlers = handlers.get(event);
+        if (!eventHandlers)
+            return;
+        eventHandlers.delete(handler);
+        if (eventHandlers.size === 0) {
+            handlers.delete(event);
+        }
+    };
+    const once = (event, handler) => {
+        const onceHandler = (payload) => {
+            off(event, onceHandler);
+            const typedHandler = handler;
+            typedHandler(payload);
+        };
+        on(event, onceHandler);
+    };
+    const emit = (event, payload) => {
+        const eventHandlers = handlers.get(event);
+        if (!eventHandlers || eventHandlers.size === 0)
+            return;
+        for (const handler of [...eventHandlers]) {
+            handler(payload);
+        }
+    };
+    return {
+        on,
+        once,
+        off,
+        emit,
+    };
+}

package/dist/runtime/core/library/library-config.d.ts

@@ -0,0 +1,10 @@
+import { OpenCoreLibraryConfigAccessor } from './types';
+type LibraryConfigStore = Record<string, Record<string, unknown>>;
+declare global {
+    var __OPENCORE_LIBRARY_CONFIG__: LibraryConfigStore | undefined;
+}
+/**
+ * Creates a namespaced config accessor for library wrappers.
+ */
+export declare function createLibraryConfigAccessor<TConfig = Record<string, unknown>>(namespace: string): OpenCoreLibraryConfigAccessor<TConfig>;
+export {};

package/dist/runtime/core/library/library-config.js

@@ -0,0 +1,12 @@
+/**
+ * Creates a namespaced config accessor for library wrappers.
+ */
+export function createLibraryConfigAccessor(namespace) {
+    return {
+        namespace,
+        get(key) {
+            const configSource = globalThis.__OPENCORE_LIBRARY_CONFIG__?.[namespace];
+            return configSource?.[key];
+        },
+    };
+}

package/dist/runtime/core/library/library-event-id.d.ts

@@ -0,0 +1,8 @@
+import { LibraryEventId, LibraryEventName, LibraryName } from './types';
+/**
+ * Builds a deterministic library event identifier.
+ *
+ * @example
+ * `characters:session:created`
+ */
+export declare function buildLibraryEventId(libraryName: LibraryName, eventName: LibraryEventName): LibraryEventId;

package/dist/runtime/core/library/library-event-id.js

@@ -0,0 +1,9 @@
+/**
+ * Builds a deterministic library event identifier.
+ *
+ * @example
+ * `characters:session:created`
+ */
+export function buildLibraryEventId(libraryName, eventName) {
+    return `${libraryName}:${eventName}`;
+}