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

package/dist/runtime/client/decorators/onTick.js

@@ -0,0 +1,26 @@
+import { METADATA_KEYS } from '../system/metadata-client.keys';
+/**
+ * Registers a method to be executed on every client frame.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds tick handlers to the
+ * client tick loop.
+ *
+ * Tick handlers should be lightweight and non-blocking.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class HudController {
+ *   @Client.Tick()
+ *   updateHud() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function onTick() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.TICK, {}, target, propertyKey);
+    };
+}

package/dist/runtime/client/decorators/onView.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Registers a method as a WebView callback handler.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the decorated method
+ * to the active WebView runtime callback.
+ *
+ * @param eventName - Callback name.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class SettingsController {
+ *   @Client.onView('settings:save')
+ *   saveSettings(payload: unknown) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function OnView(eventName: string): (target: any, propertyKey: string) => void;

package/dist/runtime/client/decorators/onView.js

@@ -0,0 +1,26 @@
+import { METADATA_KEYS } from '../system/metadata-client.keys';
+/**
+ * Registers a method as a WebView callback handler.
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the decorated method
+ * to the active WebView runtime callback.
+ *
+ * @param eventName - Callback name.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class SettingsController {
+ *   @Client.onView('settings:save')
+ *   saveSettings(payload: unknown) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function OnView(eventName) {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.VIEW, { eventName }, target, propertyKey);
+    };
+}

package/dist/runtime/client/decorators/resourceLifecycle.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Registers a method to be called when the current resource starts (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * resource lifecycle events.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class LifecycleController {
+ *   @Client.OnResourceStart()
+ *   onStart() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function OnResourceStart(): (target: any, propertyKey: string) => void;
+/**
+ * Registers a method to be called when the current resource is stopping (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * resource lifecycle events.
+ *
+ * Use this for cleanup operations.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class LifecycleController {
+ *   @Client.OnResourceStop()
+ *   onStop() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function OnResourceStop(): (target: any, propertyKey: string) => void;

package/dist/runtime/client/decorators/resourceLifecycle.js

@@ -0,0 +1,49 @@
+import { METADATA_KEYS } from '../system/metadata-client.keys';
+/**
+ * Registers a method to be called when the current resource starts (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * resource lifecycle events.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class LifecycleController {
+ *   @Client.OnResourceStart()
+ *   onStart() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function OnResourceStart() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.RESOURCE_START, {}, target, propertyKey);
+    };
+}
+/**
+ * Registers a method to be called when the current resource is stopping (client-side).
+ *
+ * @remarks
+ * This decorator only stores metadata. During bootstrap, the framework binds the method to the
+ * resource lifecycle events.
+ *
+ * Use this for cleanup operations.
+ *
+ * @example
+ * ```ts
+ * @Client.Controller()
+ * export class LifecycleController {
+ *   @Client.OnResourceStop()
+ *   onStop() {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export function OnResourceStop() {
+    return (target, propertyKey) => {
+        Reflect.defineMetadata(METADATA_KEYS.RESOURCE_STOP, {}, target, propertyKey);
+    };
+}

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

@@ -0,0 +1,5 @@
+export * from './api';
+export * from './adapter';
+export { Client, createClientRuntime } from './client-api-runtime';
+export type { ClientApi } from './client-api-runtime';
+export type { ClientPluginApi, OpenCoreClientPlugin, PluginInstallContext as ClientPluginInstallContext, } from './library/plugin';

package/dist/runtime/client/index.js

@@ -0,0 +1,3 @@
+export * from './api';
+export * from './adapter';
+export { Client, createClientRuntime } from './client-api-runtime';

package/dist/runtime/client/library/create-client-library.d.ts

@@ -0,0 +1,13 @@
+import { OpenCoreClientLibrary } from '../../core/library/types';
+/**
+ * Creates a client-side OpenCore library wrapper.
+ *
+ * @remarks
+ * - Internal events use the local in-memory library bus.
+ * - `emitServer` sends a namespaced net event to server following
+ *   `opencore:<libName>:<eventName>` (or custom namespace).
+ * - For request/response patterns, prefer RPC.
+ */
+export declare function createClientLibrary(name: string, opts?: {
+    namespace?: string;
+}): OpenCoreClientLibrary;

package/dist/runtime/client/library/create-client-library.js

@@ -0,0 +1,53 @@
+import { EventsAPI } from '../../../adapters/contracts/transport/events.api';
+import { di } from '../client-container';
+import { coreLogger } from '../../../kernel/logger';
+import { buildLibraryEventId, createLibraryBase, createLibraryConfigAccessor, } from '../../core/library';
+import { emitLibraryEvent } from '../bus/library-event.bus';
+/**
+ * Creates a client-side OpenCore library wrapper.
+ *
+ * @remarks
+ * - Internal events use the local in-memory library bus.
+ * - `emitServer` sends a namespaced net event to server following
+ *   `opencore:<libName>:<eventName>` (or custom namespace).
+ * - For request/response patterns, prefer RPC.
+ */
+export function createClientLibrary(name, opts) {
+    const base = createLibraryBase(name, opts);
+    const logger = coreLogger.client(`Library:${base.name}`);
+    const emitInternal = base.emit;
+    const events = di.isRegistered(EventsAPI)
+        ? di.resolve(EventsAPI)
+        : null;
+    return {
+        ...base,
+        side: 'client',
+        emit(eventName, payload) {
+            emitInternal(eventName, payload);
+            const eventId = buildLibraryEventId(base.name, eventName);
+            const envelope = {
+                payload,
+                meta: {
+                    libraryName: base.name,
+                    eventName,
+                    eventId,
+                    namespace: base.namespace,
+                    side: 'client',
+                },
+            };
+            emitLibraryEvent(eventId, envelope);
+        },
+        emitServer(eventName, payload) {
+            if (!events) {
+                throw new Error('[OpenCore] Client events transport is not registered.');
+            }
+            events.emit(base.buildEventName(eventName), payload);
+        },
+        getLogger() {
+            return logger;
+        },
+        getConfig() {
+            return createLibraryConfigAccessor(base.namespace);
+        },
+    };
+}

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

@@ -0,0 +1,4 @@
+export { createClientLibrary } from './create-client-library';
+export { buildLibraryEventId } from '../../core/library';
+export type { ClientPluginApi, OpenCoreClientPlugin, PluginInstallContext as ClientPluginInstallContext, } from './plugin';
+export type { LibraryEventEnvelope, LibraryEventId, LibraryEventName, LibraryEventMetadata, LibraryName, LibraryNamespace, OpenCoreClientLibrary, OpenCoreLibraryBase, OpenCoreLibraryConfigAccessor, } from '../../core/library/types';

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

@@ -0,0 +1,2 @@
+export { createClientLibrary } from './create-client-library';
+export { buildLibraryEventId } from '../../core/library';

package/dist/runtime/client/library/plugin/client-plugin-api.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Empty interface for module augmentation.
+ */
+export interface ClientPluginApi {
+}

package/dist/runtime/client/library/plugin/index.d.ts

@@ -0,0 +1,4 @@
+export * from './client-plugin-api';
+export * from './plugin-context';
+export * from './plugin.interface';
+export * from './plugin-registry';

package/dist/runtime/client/library/plugin/index.js

@@ -0,0 +1,4 @@
+export * from './client-plugin-api';
+export * from './plugin-context';
+export * from './plugin.interface';
+export * from './plugin-registry';

package/dist/runtime/client/library/plugin/install-client-plugins.d.ts

@@ -0,0 +1,3 @@
+import type { ClientInitOptions } from '../../client-runtime';
+import type { OpenCoreClientPlugin } from './plugin.interface';
+export declare function installClientPlugins(plugins: OpenCoreClientPlugin[], options: ClientInitOptions): Promise<void>;

package/dist/runtime/client/library/plugin/install-client-plugins.js

@@ -0,0 +1,35 @@
+import { di } from '../../client-container';
+import { Client } from '../../client-api-runtime';
+import { PluginRegistry } from './plugin-registry';
+function createConfigAccessor(options) {
+    const runtimeOptions = {
+        mode: options.mode ?? 'CORE',
+    };
+    return {
+        get(key) {
+            const segments = key.split('.').filter(Boolean);
+            let current = runtimeOptions;
+            for (const segment of segments) {
+                if (typeof current !== 'object' || current === null) {
+                    return undefined;
+                }
+                current = current[segment];
+            }
+            return current;
+        },
+    };
+}
+export async function installClientPlugins(plugins, options) {
+    if (plugins.length === 0)
+        return;
+    const registry = new PluginRegistry();
+    await registry.installAll(plugins, {
+        client: Client,
+        di: {
+            register(token, value) {
+                di.registerInstance(token, value);
+            },
+        },
+        config: createConfigAccessor(options),
+    });
+}

package/dist/runtime/client/library/plugin/plugin-context.d.ts

@@ -0,0 +1,10 @@
+import type { ClientApi } from '../../client-api-runtime';
+export interface PluginInstallContext {
+    readonly client: ClientApi;
+    readonly di: {
+        register(token: any, value: any): void;
+    };
+    readonly config: {
+        get<T = any>(key: string): T | undefined;
+    };
+}

package/dist/runtime/client/library/plugin/plugin-registry.d.ts

@@ -0,0 +1,6 @@
+import type { PluginInstallContext } from './plugin-context';
+import type { OpenCoreClientPlugin } from './plugin.interface';
+export declare class PluginRegistry {
+    private readonly installed;
+    installAll(plugins: OpenCoreClientPlugin[], ctx: PluginInstallContext): Promise<void>;
+}

package/dist/runtime/client/library/plugin/plugin-registry.js

@@ -0,0 +1,12 @@
+export class PluginRegistry {
+    installed = new Map();
+    async installAll(plugins, ctx) {
+        for (const plugin of plugins) {
+            if (this.installed.has(plugin.name)) {
+                throw new Error(`Plugin "${plugin.name}" already installed`);
+            }
+            await plugin.install(ctx);
+            this.installed.set(plugin.name, plugin);
+        }
+    }
+}

package/dist/runtime/client/library/plugin/plugin.interface.d.ts

@@ -0,0 +1,11 @@
+import type { PluginInstallContext } from './plugin-context';
+export interface OpenCoreClientPlugin {
+    /**
+     * Unique plugin name.
+     */
+    readonly name: string;
+    /**
+     * Called during Client.init().
+     */
+    install(ctx: PluginInstallContext): void | Promise<void>;
+}

package/dist/runtime/client/services/appearance.service.d.ts

@@ -0,0 +1,132 @@
+import { IGtaPedAppearanceBridge } from '../../../adapters/contracts/client/IGtaPedAppearanceBridge';
+import { IHasher } from '../../../adapters/contracts/IHasher';
+import { AppearanceValidationResult, PlayerAppearance } from '../../../kernel/shared';
+/**
+ * Client-side appearance management service.
+ *
+ * @remarks
+ * Handles applying and retrieving ped appearance data on the client.
+ * Uses adapters for FiveM native abstraction, enabling testability.
+ *
+ * This service is typically called in response to server events
+ * after the server has validated the appearance data.
+ *
+ * @example
+ * ```typescript
+ * // Apply appearance from server-validated data
+ * await appearanceService.applyAppearance(PlayerPedId(), validatedAppearance)
+ *
+ * // Get current appearance for saving
+ * const currentAppearance = await appearanceService.getAppearance(PlayerPedId())
+ * ```
+ */
+export declare class AppearanceService {
+    private pedAdapter;
+    private hasher;
+    constructor(pedAdapter: IGtaPedAppearanceBridge, hasher: IHasher);
+    /**
+     * Applies a complete appearance to a ped.
+     *
+     * @remarks
+     * The order of application is important:
+     * 1. HeadBlend (required before overlays/features)
+     * 2. Face features
+     * 3. Components
+     * 4. Props
+     * 5. Head overlays with colors
+     * 6. Hair color
+     * 7. Eye color
+     * 8. Tattoos
+     *
+     * @param ped - Ped entity handle
+     * @param appearance - Appearance data to apply
+     */
+    applyAppearance(ped: number, appearance: PlayerAppearance): Promise<void>;
+    /**
+     * Retrieves the current appearance of a ped.
+     *
+     * @remarks
+     * Only retrieves components and props as other data (headBlend, overlays, etc.)
+     * cannot be read back from the game.
+     *
+     * @param ped - Ped entity handle
+     * @returns Partial appearance data (components and props only)
+     */
+    getAppearance(ped: number): Promise<PlayerAppearance>;
+    /**
+     * Gets the number of available drawable variations for a component.
+     *
+     * @param ped - Ped entity handle
+     * @param componentId - Component ID (0-11)
+     * @returns Number of available drawables
+     */
+    getNumComponentDrawables(ped: number, componentId: number): number;
+    /**
+     * Gets the number of available texture variations for a component drawable.
+     *
+     * @param ped - Ped entity handle
+     * @param componentId - Component ID (0-11)
+     * @param drawable - Drawable index
+     * @returns Number of available textures
+     */
+    getNumComponentTextures(ped: number, componentId: number, drawable: number): number;
+    /**
+     * Gets the number of available drawable variations for a prop.
+     *
+     * @param ped - Ped entity handle
+     * @param propId - Prop ID (0-7)
+     * @returns Number of available drawables
+     */
+    getNumPropDrawables(ped: number, propId: number): number;
+    /**
+     * Gets the number of available texture variations for a prop drawable.
+     *
+     * @param ped - Ped entity handle
+     * @param propId - Prop ID (0-7)
+     * @param drawable - Drawable index
+     * @returns Number of available textures
+     */
+    getNumPropTextures(ped: number, propId: number, drawable: number): number;
+    /**
+     * Gets the number of available overlay variations.
+     *
+     * @param overlayId - Overlay ID (0-12)
+     * @returns Number of available variations
+     */
+    getNumOverlayValues(overlayId: number): number;
+    /**
+     * Gets the number of available hair colors.
+     *
+     * @returns Number of hair colors
+     */
+    getNumHairColors(): number;
+    /**
+     * Gets the number of available makeup colors.
+     *
+     * @returns Number of makeup colors
+     */
+    getNumMakeupColors(): number;
+    /**
+     * Validates appearance data structure.
+     *
+     * @remarks
+     * This is a client-side validation for data integrity.
+     * Server-side validation should always be performed for security.
+     *
+     * @param appearance - Appearance data to validate
+     * @returns Validation result with errors if any
+     */
+    validateAppearance(appearance: Partial<PlayerAppearance>): AppearanceValidationResult;
+    /**
+     * Sets the ped to default component variation.
+     *
+     * @param ped - Ped entity handle
+     */
+    setDefaultAppearance(ped: number): void;
+    /**
+     * Clears all tattoos from a ped.
+     *
+     * @param ped - Ped entity handle
+     */
+    clearTattoos(ped: number): void;
+}