handler-playable-sdk 0.2.7 → 0.3.2

package/dist/index.d.ts

@@ -1,3 +1,389 @@
+import { O as ObjectCentricConfig } from './loader-object-centric-C1QteFfG.js';
+export { g as applyDefaults, c as loadAllObjectConfigs, a as loadComponentSchemas, d as loadEngineConfig, e as loadGamePromptConfig, l as loadObjectCentricConfig, b as loadObjectConfig, f as loadSceneConfig, t as toLegacyFormat, v as validateObjectConfig } from './loader-object-centric-C1QteFfG.js';
+
+declare global {
+    interface Window {
+        cachedContainerSize?: {
+            width: number;
+            height: number;
+        };
+    }
+}
+declare function setBootstrapDependencies(deps: {
+    initGame: any;
+    CustomAssets: any;
+    updateScreenState: any;
+    globalResponsiveMultipliers: any;
+    layout: any;
+    clearResponsiveElements: any;
+}): void;
+/**
+ * Bootstrap the Handler game
+ */
+declare const bootstrap: () => Promise<void>;
+
+/**
+ * Device Presets for Preview System
+ *
+ * Real device resolutions organized by category.
+ * The preview system will scale-to-fit these within the browser window.
+ */
+interface DevicePreset {
+    id: string;
+    label: string;
+    width: number;
+    height: number;
+    category: DeviceCategory;
+    ratio: string;
+    mraidScale?: number;
+}
+type DeviceCategory = 'iphone' | 'android' | 'tablet' | 'playable' | 'social';
+interface DeviceGroup {
+    category: DeviceCategory;
+    label: string;
+    devices: DevicePreset[];
+}
+declare const devicePresets: DevicePreset[];
+declare const deviceGroups: DeviceGroup[];
+declare const defaultPreset: DevicePreset;
+declare function getPresetById(id: string): DevicePreset;
+declare function getPresetsByCategory(category: DeviceCategory): DevicePreset[];
+
+/**
+ * Preview Shell
+ * Google Ads & Meta Style Preview System.
+ * Uses CSS transform scaling for device frame preview,
+ * and emits resize events so PIXI can reflow reliably.
+ */
+
+interface PreviewOptions {
+    defaultDevice?: string;
+    onDeviceChange?: (preset: DevicePreset) => void;
+    onRefresh?: () => void;
+    onRestart?: () => void;
+}
+declare class PreviewShell {
+    private container;
+    private previewContainer;
+    private singleStage;
+    private compareStage;
+    private frameDragger;
+    private frameWrapper;
+    private deviceFrame;
+    private gameContainer;
+    private currentPreset;
+    private isLandscape;
+    private autoScale;
+    private userScaleMultiplier;
+    private options;
+    private viewMode;
+    private lastSinglePresetId;
+    private comparePresets;
+    private activeCompareId;
+    private compareViewports;
+    private resizeObserver;
+    private rafFitHandle;
+    private ignoreNextWindowResize;
+    private frameDragOffsetX;
+    private frameDragOffsetY;
+    private frameDragActive;
+    private frameDragStartX;
+    private frameDragStartY;
+    private frameDragOriginX;
+    private frameDragOriginY;
+    private consolePanel;
+    private consoleMessages;
+    private isConsoleOpen;
+    private debugPanel;
+    private hasInitialFit;
+    private isMounted;
+    private isInitialized;
+    private gameReady;
+    private resizeListenersDisabled;
+    private compareSnapshotTimer;
+    constructor(options?: PreviewOptions);
+    mount(target?: HTMLElement): void;
+    destroy(): void;
+    getGameContainer(): HTMLElement;
+    getScreen(): {
+        width: number;
+        height: number;
+    };
+    getEffectivePreset(): DevicePreset;
+    notifyGameLoaded(): void;
+    notifyGameDestroyed(): void;
+    private disableResizeListeners;
+    private enableResizeListeners;
+    refresh(): void;
+    setDevice(deviceId: string, opts?: {
+        suppressCallback?: boolean;
+    }): void;
+    private createShell;
+    private setupEventListeners;
+    private applyDeviceFrameStyles;
+    private setupObserversAndListeners;
+    private onWindowResize;
+    private scheduleFit;
+    private applyPresetDimensions;
+    private fitToScreen;
+    private applyTransform;
+    private applyFrameDrag;
+    private setupFrameDragging;
+    private onFrameDragMove;
+    private onFrameDragEnd;
+    private adjustUserZoom;
+    private toggleRotation;
+    private emitScreenChange;
+    private safeStringify;
+    private setupConsoleInterceptor;
+    private appendConsoleMessage;
+    private escapeHtml;
+    private toggleConsole;
+    private clearConsole;
+    private setupCompareViewports;
+    private setViewMode;
+    private updateViewToggleUI;
+    private activateCompareViewport;
+    private applyCompareDimensions;
+    private fitCompareGhosts;
+    private captureCompareSnapshot;
+    private refreshCompareSnapshots;
+    private startCompareSnapshots;
+    private stopCompareSnapshots;
+    private getFitBounds;
+    private mustQuery;
+}
+declare function createPreviewShell(options?: PreviewOptions): PreviewShell;
+
+declare class DebugPanel {
+    private debugOverlay;
+    private isDebugOpen;
+    private selectedObjectId;
+    private configViewer;
+    private container;
+    private objectAutoApplyTimer;
+    private objectDebugRaf;
+    private objectBoundsGfx;
+    private objectAnchorGfx;
+    private highlightObject;
+    private highlightAnchor;
+    private sceneObjectsPanel;
+    private sceneEditPanel;
+    private sceneToolsPanel;
+    private customizeSettingsPanel;
+    private libraryPanel;
+    private batchAiPanel;
+    private brandDnaPanel;
+    private activeTab;
+    initialize(container: HTMLElement): void;
+    selectObject(objectId: string): void;
+    getDebugOverlayHTML(): string;
+    setupDebugEventListeners(): void;
+    private updateWorkbenchTabs;
+    toggleDebug(force?: boolean): void;
+    private applyAssetChange;
+    private resetAsset;
+    updateDebugBadge(): void;
+    private setupDebugInputListeners;
+    private setupPanelLayout;
+    private saveWorkbenchState;
+    private loadWorkbenchState;
+    private setupCollapsiblePanels;
+    private handleObjectSelect;
+    private nudgeSelectedObject;
+    private startObjectVisuals;
+    private stopObjectVisuals;
+    private shouldRunObjectVisuals;
+    private updateObjectVisuals;
+    private getSelectedInstanceId;
+    private getDisplayObjectById;
+    private getSelectedObjectConfig;
+    private getConfigAnchorWorldPoint;
+    private getScreenSize;
+    private ensureBoundsGfx;
+    private ensureAnchorGfx;
+    private drawBounds;
+    private drawAnchor;
+    private clearBounds;
+    private clearAnchor;
+    private clearObjectVisuals;
+    private updateObjectInfo;
+    private scheduleObjectAutoApply;
+    private setupRangeInput;
+    private getNestedValue;
+    private setNestedValue;
+    private resetDebugConfig;
+    private applyDebugConfig;
+    private exportDebugConfig;
+    private loadObjectConfig;
+    private fillConfigViewer;
+    private copyConfigValues;
+    private applyObjectConfig;
+    private applyCustomizeSettings;
+    private shouldUseOffsetPosition;
+}
+
+/**
+ * Preview Live-Edit Bridge (SDK)
+ *
+ * Provides the window hooks used by preview panels + hot-reload systems.
+ * This is intentionally small and defensive: it does not assume any specific
+ * GameObject implementation beyond "getDisplayObject" or common PIXI fields.
+ */
+type LiveEditBridge = {
+    /** Apply a full object config (usually after reloading from disk) */
+    applyObjectConfig: (objectId: string, nextConfig: any) => Promise<void>;
+    /** Rebuild lookup tables used by panels */
+    rebuildIndexes: () => void;
+};
+type SetupLiveEditBridgeOptions = {
+    getConfig: () => any;
+    gameObjectManager: any;
+    assets?: any;
+    onObjectConfigApplied?: (objectId: string, nextConfig: any, instanceIds: string[]) => void;
+};
+/**
+ * Setup the live-edit bridge.
+ *
+ * Call this after you have a loaded config and an initialized gameObjectManager.
+ */
+declare function setupLiveEditBridge(options: SetupLiveEditBridgeOptions): LiveEditBridge;
+
+/**
+ * Hot-Reload System for Object-Centric Config
+ *
+ * Enables live config editing during development.
+ * Edit your config JSON files and see changes instantly!
+ */
+interface HotReloadWatcher {
+    watch(configPath: string, callback: (event: ConfigChangeEvent) => void): void;
+    unwatch(configPath: string): void;
+    stop(): void;
+}
+interface ConfigChangeEvent {
+    type: 'object' | 'component' | 'engine' | 'scene';
+    path: string;
+    objectId?: string;
+    componentName?: string;
+}
+interface ReloadStrategy {
+    shouldFullReload(event: ConfigChangeEvent): boolean;
+    getAffectedObjects(event: ConfigChangeEvent): string[];
+}
+/**
+ * Determines reload strategy based on config change type
+ */
+declare class DefaultReloadStrategy implements ReloadStrategy {
+    shouldFullReload(event: ConfigChangeEvent): boolean;
+    getAffectedObjects(event: ConfigChangeEvent): string[];
+}
+/**
+ * File watcher for config hot-reload
+ */
+declare class ConfigWatcher implements HotReloadWatcher {
+    private pollingInterval;
+    private fileHashes;
+    private callbacks;
+    private intervalMs;
+    constructor(intervalMs?: number);
+    watch(configPath: string, callback: (event: ConfigChangeEvent) => void): void;
+    private checkAllFiles;
+    private determineEventType;
+    private hashString;
+    unwatch(configPath: string): void;
+    stop(): void;
+}
+/**
+ * Diff utility for comparing configs
+ */
+declare function diffConfigs(oldConfig: any, newConfig: any): string[];
+/**
+ * Rehydrate object with new config
+ */
+declare function rehydrateObject(objectId: string, oldConfig: any, newConfig: any, schemas: Map<string, any>): any;
+
+interface HotReloadDependencies {
+    activeConfig: ObjectCentricConfig;
+    setActiveConfig: (config: ObjectCentricConfig) => void;
+    gameObjectManager: any;
+    CustomAssets: any;
+    audioSystem: any;
+    setAudioSystem: (audioSystem: any) => void;
+    liveEditBridge: any;
+    createAudioSystem: (config: ObjectCentricConfig) => any;
+}
+/**
+ * Setup hot reload for config files.
+ *
+ * SDK-owned plumbing so demo projects only provide dependencies.
+ */
+declare function setupHotReload(deps: HotReloadDependencies): void;
+
+/**
+ * Config Override System
+ *
+ * Allows preview panel to override config values at runtime.
+ * Changes are applied immediately and can be:
+ * - persisted across restarts (in-memory, via window)
+ * - exported (diff/patch/json) via ConfigExport
+ *
+ * NOTE:
+ * In a pure-browser environment we cannot write back to disk.
+ * "Apply (real changes)" should be implemented via an optional dev-server endpoint
+ * (e.g. Vite plugin) that receives exported patches and writes config files.
+ */
+interface ConfigOverride {
+    objectId?: string;
+    path: string;
+    value: any;
+}
+interface ConfigChange {
+    objectId?: string;
+    path: string;
+    oldValue: any;
+    newValue: any;
+    ts: number;
+}
+interface ConfigOverrideOptions {
+    silent?: boolean;
+    persist?: boolean;
+}
+/**
+ * Apply a config override
+ */
+declare function applyConfigOverride(override: ConfigOverride, options?: ConfigOverrideOptions): void;
+/**
+ * Apply multiple config overrides
+ */
+declare function applyConfigOverrides(overrides: ConfigOverride[], options?: ConfigOverrideOptions): void;
+/**
+ * Clear all config overrides
+ */
+declare function clearConfigOverrides(): void;
+/**
+ * Get all active overrides
+ */
+declare function getConfigOverrides(): ConfigOverride[];
+/**
+ * SDK-facing manager used by ConfigExport.
+ * Kept minimal to avoid forcing consumers into a specific persistence strategy.
+ */
+declare const configOverrideManager: {
+    getCurrentConfig(): any | null;
+    getChanges(): ConfigChange[];
+    clearChanges(): void;
+};
+
+/**
+ * Base Layer - Lottie Instance
+ *
+ * Provides isolated lottie-web instance for base layer.
+ * Prevents conflicts with student layer's lottie instance.
+ *
+ * DO NOT EDIT - Base Layer
+ */
+declare const baseLottie: any;
+
 declare global {
     const mraid: any;
     const dapi: any;
@@ -26,7 +412,7 @@ type InitOptions = {
 declare const Handler: {
     init(options?: InitOptions, callback?: (w: number, h: number) => void): void;
     getRoot(): HTMLElement;
-    readonly version: any;
+    readonly version: string;
     readonly maxWidth: number;
     readonly maxHeight: number;
     readonly isLandscape: boolean;
@@ -48,4 +434,4 @@ declare const Handler: {
     resize(width?: number, height?: number): void;
 };
 
-export { Handler, Handler as default };
+export { type ConfigChange, type ConfigChangeEvent, type ConfigOverride, type ConfigOverrideOptions, ConfigWatcher, DebugPanel, DefaultReloadStrategy, type DeviceCategory, type DeviceGroup, type DevicePreset, Handler, type HotReloadDependencies, type HotReloadWatcher, type LiveEditBridge, ObjectCentricConfig, type PreviewOptions, PreviewShell, type ReloadStrategy, type SetupLiveEditBridgeOptions, applyConfigOverride, applyConfigOverrides, baseLottie, bootstrap, clearConfigOverrides, configOverrideManager, createPreviewShell, Handler as default, defaultPreset, deviceGroups, devicePresets, diffConfigs, getConfigOverrides, getPresetById, getPresetsByCategory, rehydrateObject, setBootstrapDependencies, setupHotReload, setupLiveEditBridge };