@kibee/renderer-three 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,278 @@
+import { DockPositionConfig } from '@kibee/contracts';
+import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+
+type BeeVisualState = "idle" | "guiding" | "thinking" | "celebrating";
+type BeeAssetVariant = "hero" | "runtime";
+type BeeQualityTier = "auto" | "high" | "balanced" | "low";
+type BeeMotionMode = "auto" | "full" | "reduced";
+
+type BeeDockPosition = DockPositionConfig;
+type BeeDockVariant = "hive";
+/** undock: classic wake behavior. assist-panel: emit kibee-assist-toggle, stay docked. */
+type BeeDockClickBehavior = "undock" | "assist-panel";
+interface MoveToOptions {
+    duration?: number;
+    offsetX?: number;
+    offsetY?: number;
+}
+/** Which edge of the tooltip box holds the notch toward the bee */
+type TooltipArrowEdge = "left" | "right" | "top" | "bottom";
+interface SpeakOptions {
+    x?: number;
+    y?: number;
+    maxWidth?: number;
+    /** When x/y are set, positions the speech notch on this side of the bubble */
+    arrowEdge?: TooltipArrowEdge;
+    /** Called when user clicks the Previous button. Omit or set null to hide the button. */
+    onPrev?: (() => void) | null;
+    /** Called when user clicks the Next button. Omit or set null to hide the button. */
+    onNext?: (() => void) | null;
+    /** Step label shown between the nav buttons, e.g. "2 / 5" */
+    stepLabel?: string;
+}
+interface DockMotionOptions {
+    hideDock?: boolean;
+}
+interface ThreeBeeRendererOptions {
+    assetUrl?: string;
+    assetVariant?: BeeAssetVariant;
+    qualityTier?: BeeQualityTier;
+    enableShadows?: boolean;
+    motionMode?: BeeMotionMode;
+    dockEnabled?: boolean;
+    dockPosition?: BeeDockPosition;
+    dockSize?: number;
+    dockVariant?: BeeDockVariant;
+    dockClickBehavior?: BeeDockClickBehavior;
+    /**
+     * When false, skip reading/writing `kibee:dock_pos` in localStorage (e.g. browser extensions
+     * on third-party origins should not inherit or pollute saved dock positions).
+     * @default true
+     */
+    restorePersistedDockPosition?: boolean;
+}
+/** Options for `ThreeBeeRenderer#setCustomDockPosition`. */
+type SetCustomDockPositionOptions = {
+    /** When false, do not persist to localStorage. @default true */
+    persist?: boolean;
+};
+type BeeActionChoice = "honey" | "sting";
+interface BeeActionHandler {
+    (choice: BeeActionChoice): void;
+}
+interface PromptOptions {
+    placeholder?: string;
+}
+interface BeeRenderer {
+    mount(container?: HTMLElement): Promise<void>;
+    moveTo(x: number, y: number, options?: MoveToOptions): Promise<void>;
+    dock(options?: DockMotionOptions): Promise<void>;
+    undock(options?: DockMotionOptions): Promise<void>;
+    isDocked(): boolean;
+    setState(state: BeeVisualState): void;
+    speak(message: string, options?: SpeakOptions): void;
+    /** Inline 1-2 line note prompt; resolves to the note string, "" if user pressed Save with empty input, or null if they skipped. */
+    prompt(message: string, options?: PromptOptions): Promise<string | null>;
+    hideMessage(): void;
+    showActions(handler: BeeActionHandler): void;
+    hideActions(): void;
+    resize(): void;
+    setDockClickBehavior(mode: BeeDockClickBehavior): void;
+    getDockScreenPosition(): {
+        x: number;
+        y: number;
+    };
+    /** Current bee viewport coords + dock state. Used by host UIs to anchor
+     *  panels / context capture without subscribing to kibee-bee-move. */
+    getBeePosition(): {
+        x: number;
+        y: number;
+        docked: boolean;
+    };
+    destroy(): void;
+}
+
+declare class ThreeBeeRenderer implements BeeRenderer {
+    private options;
+    private root;
+    private canvasWrap;
+    private tooltip;
+    private hoverZone;
+    private dockButton;
+    private scene;
+    private camera;
+    private renderer;
+    private beeGroup;
+    private visualRig;
+    private mixer;
+    private actions;
+    private activeActionName;
+    private runtimeWings;
+    private mounted;
+    /** Deduplicates concurrent mount() calls (React Strict Mode, double init, etc.) */
+    private mountPromise;
+    private disposed;
+    private animationFrameId;
+    private clock;
+    private state;
+    private currentX;
+    private currentY;
+    private currentFacing;
+    private docked;
+    private dockVisible;
+    private hoveringHome;
+    private reducedMotion;
+    private renderingAvailable;
+    private idleTween;
+    private celebrateTween;
+    private tooltipPulseTimer;
+    private tooltipMessage;
+    private actionHandler;
+    private dockClickBehavior;
+    private autoDockTimer;
+    private customDockPos;
+    private radialButtons;
+    private isDragging;
+    private dragStartX;
+    private dragStartY;
+    private dragMoved;
+    /** Pointer went down while docked — used to distinguish dock tap vs drag-out */
+    private dragArmedFromDock;
+    private hideButtonsTimer;
+    private panelOpen;
+    /** When false, constructor skips LS restore and setCustomDockPosition skips LS writes by default. */
+    private readonly restorePersistedDockPosition;
+    private tooltipText;
+    private tooltipNav;
+    private navPrevBtn;
+    private navLabel;
+    private navNextBtn;
+    private tooltipHasNav;
+    private tooltipPrompt;
+    private tooltipPromptInput;
+    private tooltipPromptSaveBtn;
+    private tooltipPromptSkipBtn;
+    private tooltipPromptHint;
+    private tooltipPromptActive;
+    private readonly tooltipPromptMaxLen;
+    constructor(options?: ThreeBeeRendererOptions);
+    mount(container?: HTMLElement): Promise<void>;
+    private performMount;
+    moveTo(x: number, y: number, options?: MoveToOptions): Promise<void>;
+    dock(): Promise<void>;
+    private resetAutoDockTimer;
+    private clearAutoDockTimer;
+    undock(options?: DockMotionOptions): Promise<void>;
+    isDocked(): boolean;
+    setState(state: BeeVisualState): void;
+    speak(message: string, options?: SpeakOptions): void;
+    hideMessage(): void;
+    /**
+     * Show an inline 1-2 line prompt inside the bee's speech bubble. Used by
+     * the bookmark + issue chips to capture a short note before saving.
+     * Resolves to the user's note (trimmed) or null if they skipped / dismissed.
+     */
+    prompt(message: string, options?: {
+        placeholder?: string;
+    }): Promise<string | null>;
+    /** Swap the prompt's bottom-left hint between the keyboard hint (when empty)
+     *  and a tabular char counter (once the user starts typing). */
+    private updatePromptHint;
+    private inferTooltipArrowEdgeForPlacedTooltip;
+    showActions(handler: BeeActionHandler): void;
+    hideActions(): void;
+    resize(): void;
+    setDockClickBehavior(mode: BeeDockClickBehavior): void;
+    destroy(): void;
+    private createRoot;
+    private createScene;
+    private createCamera;
+    private createRenderer;
+    private createLights;
+    private loadBeeModel;
+    private createFallbackBee;
+    private initializeDockedHome;
+    private startRenderLoop;
+    private updateBeeScreenPosition;
+    /**
+     * Notify any listeners (the assist panel, debugging overlays) where the
+     * bee currently sits in viewport coords. Throttled to ~60fps via the
+     * existing render loop — every callsite that moves the bee already calls
+     * updateBeeScreenPosition, so this rides along with no extra timer.
+     */
+    private publishBeePosition;
+    /** Public position read for callers that prefer pull over event subscription. */
+    getBeePosition(): {
+        x: number;
+        y: number;
+        docked: boolean;
+    };
+    private startIdleMotion;
+    private startThinkingMotion;
+    private startCelebrateMotion;
+    private stopStateTweens;
+    private positionTooltipNearBee;
+    /**
+     * Compute viewport-aware radial positions for radial action buttons and the
+     * tooltip. All returned coordinates are CSS `left`/`top` pixel values.
+     * The tooltip's `top` value is the *rendered center Y* (because CSS applies
+     * `transform: translate(0, -50%)` to the tooltip element).
+     */
+    private computeRadialLayout;
+    private showRadialButtons;
+    private hideRadialButtons;
+    private positionHoverZone;
+    private startTooltipPulse;
+    private clearTooltipPulse;
+    private handleBeeHoverEnter;
+    private handleBeeHoverLeave;
+    private scheduleHideButtons;
+    private clearHideButtonsTimer;
+    /** Instant undock used when the user drags the bee off the dock / launcher */
+    private fastUndockForDrag;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private handleResize;
+    private handleVisibilityChange;
+    private handlePanelOpen;
+    private handlePanelClose;
+    private handleDockClick;
+    private updateDockAria;
+    private shouldReduceMotion;
+    private resolvePixelRatioCap;
+    private playClipForState;
+    private getClipTimeScale;
+    private applyFacing;
+    private applyHomeFacing;
+    private syncDockState;
+    private isDockEnabled;
+    setCustomDockPosition(x: number, y: number, opts?: SetCustomDockPositionOptions): void;
+    /**
+     * Snap the docked bee and dock chrome to the current `getDockCenter()` without a full resize.
+     * Use after `setCustomDockPosition` when the dock target moves (e.g. scroll-linked layout).
+     */
+    refreshDockedBeeAfterDockMove(): void;
+    private getDockCenter;
+    private presetToCenter;
+    private resolveInlineCenter;
+    /** Returns true when the dock sits on the right half of the viewport */
+    private isDockOnRight;
+    /** Returns true when the dock sits on the bottom half of the viewport */
+    private isDockOnBottom;
+    private resolveDockCSSVars;
+    private getWakeHoverPosition;
+    getDockScreenPosition(): {
+        x: number;
+        y: number;
+    };
+    private getDockSize;
+    private getActiveScale;
+    private getDockedScale;
+    private getHomeHoverScale;
+    private disposeSceneObjects;
+}
+
+declare function applyLegacyBeeMaterialCompat(gltf: GLTF): Promise<void>;
+
+export { type BeeActionChoice, type BeeActionHandler, type BeeAssetVariant, type BeeDockClickBehavior, type BeeDockPosition, type BeeDockVariant, type BeeMotionMode, type BeeQualityTier, type BeeRenderer, type BeeVisualState, type DockMotionOptions, type MoveToOptions, type PromptOptions, type SetCustomDockPositionOptions, type SpeakOptions, ThreeBeeRenderer, type ThreeBeeRendererOptions, type TooltipArrowEdge, applyLegacyBeeMaterialCompat };

package/dist/index.d.ts

@@ -0,0 +1,278 @@
+import { DockPositionConfig } from '@kibee/contracts';
+import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+
+type BeeVisualState = "idle" | "guiding" | "thinking" | "celebrating";
+type BeeAssetVariant = "hero" | "runtime";
+type BeeQualityTier = "auto" | "high" | "balanced" | "low";
+type BeeMotionMode = "auto" | "full" | "reduced";
+
+type BeeDockPosition = DockPositionConfig;
+type BeeDockVariant = "hive";
+/** undock: classic wake behavior. assist-panel: emit kibee-assist-toggle, stay docked. */
+type BeeDockClickBehavior = "undock" | "assist-panel";
+interface MoveToOptions {
+    duration?: number;
+    offsetX?: number;
+    offsetY?: number;
+}
+/** Which edge of the tooltip box holds the notch toward the bee */
+type TooltipArrowEdge = "left" | "right" | "top" | "bottom";
+interface SpeakOptions {
+    x?: number;
+    y?: number;
+    maxWidth?: number;
+    /** When x/y are set, positions the speech notch on this side of the bubble */
+    arrowEdge?: TooltipArrowEdge;
+    /** Called when user clicks the Previous button. Omit or set null to hide the button. */
+    onPrev?: (() => void) | null;
+    /** Called when user clicks the Next button. Omit or set null to hide the button. */
+    onNext?: (() => void) | null;
+    /** Step label shown between the nav buttons, e.g. "2 / 5" */
+    stepLabel?: string;
+}
+interface DockMotionOptions {
+    hideDock?: boolean;
+}
+interface ThreeBeeRendererOptions {
+    assetUrl?: string;
+    assetVariant?: BeeAssetVariant;
+    qualityTier?: BeeQualityTier;
+    enableShadows?: boolean;
+    motionMode?: BeeMotionMode;
+    dockEnabled?: boolean;
+    dockPosition?: BeeDockPosition;
+    dockSize?: number;
+    dockVariant?: BeeDockVariant;
+    dockClickBehavior?: BeeDockClickBehavior;
+    /**
+     * When false, skip reading/writing `kibee:dock_pos` in localStorage (e.g. browser extensions
+     * on third-party origins should not inherit or pollute saved dock positions).
+     * @default true
+     */
+    restorePersistedDockPosition?: boolean;
+}
+/** Options for `ThreeBeeRenderer#setCustomDockPosition`. */
+type SetCustomDockPositionOptions = {
+    /** When false, do not persist to localStorage. @default true */
+    persist?: boolean;
+};
+type BeeActionChoice = "honey" | "sting";
+interface BeeActionHandler {
+    (choice: BeeActionChoice): void;
+}
+interface PromptOptions {
+    placeholder?: string;
+}
+interface BeeRenderer {
+    mount(container?: HTMLElement): Promise<void>;
+    moveTo(x: number, y: number, options?: MoveToOptions): Promise<void>;
+    dock(options?: DockMotionOptions): Promise<void>;
+    undock(options?: DockMotionOptions): Promise<void>;
+    isDocked(): boolean;
+    setState(state: BeeVisualState): void;
+    speak(message: string, options?: SpeakOptions): void;
+    /** Inline 1-2 line note prompt; resolves to the note string, "" if user pressed Save with empty input, or null if they skipped. */
+    prompt(message: string, options?: PromptOptions): Promise<string | null>;
+    hideMessage(): void;
+    showActions(handler: BeeActionHandler): void;
+    hideActions(): void;
+    resize(): void;
+    setDockClickBehavior(mode: BeeDockClickBehavior): void;
+    getDockScreenPosition(): {
+        x: number;
+        y: number;
+    };
+    /** Current bee viewport coords + dock state. Used by host UIs to anchor
+     *  panels / context capture without subscribing to kibee-bee-move. */
+    getBeePosition(): {
+        x: number;
+        y: number;
+        docked: boolean;
+    };
+    destroy(): void;
+}
+
+declare class ThreeBeeRenderer implements BeeRenderer {
+    private options;
+    private root;
+    private canvasWrap;
+    private tooltip;
+    private hoverZone;
+    private dockButton;
+    private scene;
+    private camera;
+    private renderer;
+    private beeGroup;
+    private visualRig;
+    private mixer;
+    private actions;
+    private activeActionName;
+    private runtimeWings;
+    private mounted;
+    /** Deduplicates concurrent mount() calls (React Strict Mode, double init, etc.) */
+    private mountPromise;
+    private disposed;
+    private animationFrameId;
+    private clock;
+    private state;
+    private currentX;
+    private currentY;
+    private currentFacing;
+    private docked;
+    private dockVisible;
+    private hoveringHome;
+    private reducedMotion;
+    private renderingAvailable;
+    private idleTween;
+    private celebrateTween;
+    private tooltipPulseTimer;
+    private tooltipMessage;
+    private actionHandler;
+    private dockClickBehavior;
+    private autoDockTimer;
+    private customDockPos;
+    private radialButtons;
+    private isDragging;
+    private dragStartX;
+    private dragStartY;
+    private dragMoved;
+    /** Pointer went down while docked — used to distinguish dock tap vs drag-out */
+    private dragArmedFromDock;
+    private hideButtonsTimer;
+    private panelOpen;
+    /** When false, constructor skips LS restore and setCustomDockPosition skips LS writes by default. */
+    private readonly restorePersistedDockPosition;
+    private tooltipText;
+    private tooltipNav;
+    private navPrevBtn;
+    private navLabel;
+    private navNextBtn;
+    private tooltipHasNav;
+    private tooltipPrompt;
+    private tooltipPromptInput;
+    private tooltipPromptSaveBtn;
+    private tooltipPromptSkipBtn;
+    private tooltipPromptHint;
+    private tooltipPromptActive;
+    private readonly tooltipPromptMaxLen;
+    constructor(options?: ThreeBeeRendererOptions);
+    mount(container?: HTMLElement): Promise<void>;
+    private performMount;
+    moveTo(x: number, y: number, options?: MoveToOptions): Promise<void>;
+    dock(): Promise<void>;
+    private resetAutoDockTimer;
+    private clearAutoDockTimer;
+    undock(options?: DockMotionOptions): Promise<void>;
+    isDocked(): boolean;
+    setState(state: BeeVisualState): void;
+    speak(message: string, options?: SpeakOptions): void;
+    hideMessage(): void;
+    /**
+     * Show an inline 1-2 line prompt inside the bee's speech bubble. Used by
+     * the bookmark + issue chips to capture a short note before saving.
+     * Resolves to the user's note (trimmed) or null if they skipped / dismissed.
+     */
+    prompt(message: string, options?: {
+        placeholder?: string;
+    }): Promise<string | null>;
+    /** Swap the prompt's bottom-left hint between the keyboard hint (when empty)
+     *  and a tabular char counter (once the user starts typing). */
+    private updatePromptHint;
+    private inferTooltipArrowEdgeForPlacedTooltip;
+    showActions(handler: BeeActionHandler): void;
+    hideActions(): void;
+    resize(): void;
+    setDockClickBehavior(mode: BeeDockClickBehavior): void;
+    destroy(): void;
+    private createRoot;
+    private createScene;
+    private createCamera;
+    private createRenderer;
+    private createLights;
+    private loadBeeModel;
+    private createFallbackBee;
+    private initializeDockedHome;
+    private startRenderLoop;
+    private updateBeeScreenPosition;
+    /**
+     * Notify any listeners (the assist panel, debugging overlays) where the
+     * bee currently sits in viewport coords. Throttled to ~60fps via the
+     * existing render loop — every callsite that moves the bee already calls
+     * updateBeeScreenPosition, so this rides along with no extra timer.
+     */
+    private publishBeePosition;
+    /** Public position read for callers that prefer pull over event subscription. */
+    getBeePosition(): {
+        x: number;
+        y: number;
+        docked: boolean;
+    };
+    private startIdleMotion;
+    private startThinkingMotion;
+    private startCelebrateMotion;
+    private stopStateTweens;
+    private positionTooltipNearBee;
+    /**
+     * Compute viewport-aware radial positions for radial action buttons and the
+     * tooltip. All returned coordinates are CSS `left`/`top` pixel values.
+     * The tooltip's `top` value is the *rendered center Y* (because CSS applies
+     * `transform: translate(0, -50%)` to the tooltip element).
+     */
+    private computeRadialLayout;
+    private showRadialButtons;
+    private hideRadialButtons;
+    private positionHoverZone;
+    private startTooltipPulse;
+    private clearTooltipPulse;
+    private handleBeeHoverEnter;
+    private handleBeeHoverLeave;
+    private scheduleHideButtons;
+    private clearHideButtonsTimer;
+    /** Instant undock used when the user drags the bee off the dock / launcher */
+    private fastUndockForDrag;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private handleResize;
+    private handleVisibilityChange;
+    private handlePanelOpen;
+    private handlePanelClose;
+    private handleDockClick;
+    private updateDockAria;
+    private shouldReduceMotion;
+    private resolvePixelRatioCap;
+    private playClipForState;
+    private getClipTimeScale;
+    private applyFacing;
+    private applyHomeFacing;
+    private syncDockState;
+    private isDockEnabled;
+    setCustomDockPosition(x: number, y: number, opts?: SetCustomDockPositionOptions): void;
+    /**
+     * Snap the docked bee and dock chrome to the current `getDockCenter()` without a full resize.
+     * Use after `setCustomDockPosition` when the dock target moves (e.g. scroll-linked layout).
+     */
+    refreshDockedBeeAfterDockMove(): void;
+    private getDockCenter;
+    private presetToCenter;
+    private resolveInlineCenter;
+    /** Returns true when the dock sits on the right half of the viewport */
+    private isDockOnRight;
+    /** Returns true when the dock sits on the bottom half of the viewport */
+    private isDockOnBottom;
+    private resolveDockCSSVars;
+    private getWakeHoverPosition;
+    getDockScreenPosition(): {
+        x: number;
+        y: number;
+    };
+    private getDockSize;
+    private getActiveScale;
+    private getDockedScale;
+    private getHomeHoverScale;
+    private disposeSceneObjects;
+}
+
+declare function applyLegacyBeeMaterialCompat(gltf: GLTF): Promise<void>;
+
+export { type BeeActionChoice, type BeeActionHandler, type BeeAssetVariant, type BeeDockClickBehavior, type BeeDockPosition, type BeeDockVariant, type BeeMotionMode, type BeeQualityTier, type BeeRenderer, type BeeVisualState, type DockMotionOptions, type MoveToOptions, type PromptOptions, type SetCustomDockPositionOptions, type SpeakOptions, ThreeBeeRenderer, type ThreeBeeRendererOptions, type TooltipArrowEdge, applyLegacyBeeMaterialCompat };