qnce-engine 0.1.0 → 1.2.1

package/dist/ui/components/AutosaveIndicator.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutosaveIndicator = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const types_1 = require("../types");
+const react_2 = require("../../integrations/react");
+/**
+ * AutosaveIndicator Component
+ *
+ * Visual indicator showing autosave status with animated feedback,
+ * timestamp display, and customizable positioning.
+ *
+ * Features:
+ * - Real-time autosave status updates (idle, saving, saved, error)
+ * - Animated visual feedback with spinner and status icons
+ * - Configurable positioning (corners, inline)
+ * - Timestamp of last successful save
+ * - Auto-hide functionality
+ * - Accessible with proper ARIA labels
+ */
+const AutosaveIndicator = ({ engine, theme: customTheme, className = '', style, variant = 'detailed', position = 'inline', messages = {
+    idle: 'Auto-save ready',
+    saving: 'Saving...',
+    saved: 'Saved',
+    error: 'Save failed',
+    disabled: 'Autosave disabled'
+}, showTimestamp = true, autoHideDelay = 3000 }) => {
+    const { isEnabled, lastAutosave, isSaving } = (0, react_2.useAutosave)(engine);
+    const [visible, setVisible] = (0, react_1.useState)(true);
+    const [isAnimating, setIsAnimating] = (0, react_1.useState)(false);
+    const [lastSaveSuccessful, setLastSaveSuccessful] = (0, react_1.useState)(true);
+    // Determine status based on hook values
+    const status = (0, react_1.useMemo)(() => {
+        if (!isEnabled)
+            return 'disabled';
+        if (isSaving)
+            return 'saving';
+        if (lastAutosave && !isSaving) {
+            return lastSaveSuccessful ? 'saved' : 'error';
+        }
+        return 'idle';
+    }, [isEnabled, isSaving, lastAutosave, lastSaveSuccessful]);
+    // Merge custom theme with default theme
+    const theme = (0, react_1.useMemo)(() => ({
+        ...types_1.defaultTheme,
+        ...customTheme,
+        colors: { ...types_1.defaultTheme.colors, ...customTheme?.colors },
+        spacing: { ...types_1.defaultTheme.spacing, ...customTheme?.spacing },
+        borderRadius: { ...types_1.defaultTheme.borderRadius, ...customTheme?.borderRadius },
+        typography: {
+            ...types_1.defaultTheme.typography,
+            ...customTheme?.typography,
+            fontSize: { ...types_1.defaultTheme.typography.fontSize, ...customTheme?.typography?.fontSize },
+            fontWeight: { ...types_1.defaultTheme.typography.fontWeight, ...customTheme?.typography?.fontWeight }
+        },
+        shadows: { ...types_1.defaultTheme.shadows, ...customTheme?.shadows }
+    }), [customTheme]);
+    // Auto-hide logic for saved status
+    (0, react_1.useEffect)(() => {
+        setVisible(true);
+        if (status === 'saved' && autoHideDelay > 0) {
+            const hideTimer = setTimeout(() => {
+                setVisible(false);
+            }, autoHideDelay);
+            return () => clearTimeout(hideTimer);
+        }
+    }, [status, autoHideDelay]);
+    (0, react_1.useEffect)(() => {
+        setIsAnimating(isSaving);
+    }, [isSaving]);
+    // Position styles
+    const getPositionStyles = () => {
+        const basePositionStyle = {
+            position: position === 'inline' ? 'static' : 'fixed',
+            zIndex: 1000
+        };
+        switch (position) {
+            case 'top-left':
+                return { ...basePositionStyle, top: theme.spacing.md, left: theme.spacing.md };
+            case 'top-right':
+                return { ...basePositionStyle, top: theme.spacing.md, right: theme.spacing.md };
+            case 'bottom-left':
+                return { ...basePositionStyle, bottom: theme.spacing.md, left: theme.spacing.md };
+            case 'bottom-right':
+                return { ...basePositionStyle, bottom: theme.spacing.md, right: theme.spacing.md };
+            default:
+                return basePositionStyle;
+        }
+    };
+    // Status-based styling
+    const getStatusColor = (currentStatus) => {
+        switch (currentStatus) {
+            case 'saving':
+                return theme.colors.warning;
+            case 'saved':
+                return theme.colors.success;
+            case 'error':
+                return theme.colors.error;
+            default:
+                return theme.colors.secondary;
+        }
+    };
+    // Icons and indicators
+    const StatusIcon = ({ status }) => {
+        const iconStyle = {
+            fontSize: '16px',
+            lineHeight: 1,
+            color: getStatusColor(status)
+        };
+        switch (status) {
+            case 'saving':
+                return ((0, jsx_runtime_1.jsx)("span", { style: {
+                        ...iconStyle,
+                        animation: isAnimating ? 'spin 1s linear infinite' : 'none'
+                    }, children: "\u27F3" }));
+            case 'saved':
+                return (0, jsx_runtime_1.jsx)("span", { style: iconStyle, children: "\u2713" });
+            case 'error':
+                return (0, jsx_runtime_1.jsx)("span", { style: iconStyle, children: "\u2717" });
+            default:
+                return (0, jsx_runtime_1.jsx)("span", { style: iconStyle, children: "\u25CB" });
+        }
+    };
+    // Format timestamp
+    const formatTimestamp = (date) => {
+        if (!date)
+            return '';
+        return date.toLocaleTimeString([], { hour12: false, timeStyle: 'short' });
+    };
+    // Component styles
+    const containerStyle = {
+        display: visible ? 'flex' : 'none',
+        alignItems: 'center',
+        gap: theme.spacing.xs,
+        padding: variant === 'icon-only' ? theme.spacing.xs : theme.spacing.sm,
+        backgroundColor: theme.colors.surface,
+        border: `1px solid ${getStatusColor(status)}`,
+        borderRadius: theme.borderRadius.md,
+        boxShadow: theme.shadows.sm,
+        fontFamily: theme.typography.fontFamily,
+        fontSize: theme.typography.fontSize.sm,
+        color: theme.colors.text,
+        transition: 'all 0.2s ease-in-out',
+        opacity: visible ? 1 : 0,
+        transform: visible ? 'translateY(0)' : 'translateY(-10px)',
+        ...getPositionStyles(),
+        ...style
+    };
+    const textStyle = {
+        fontWeight: theme.typography.fontWeight.medium,
+        color: getStatusColor(status)
+    };
+    const timestampStyle = {
+        fontSize: theme.typography.fontSize.sm,
+        color: theme.colors.textSecondary,
+        fontWeight: theme.typography.fontWeight.normal,
+        opacity: 0.8
+    };
+    // Show disabled state when autosave is disabled, otherwise don't render
+    if (!isEnabled && status === 'disabled') {
+        // Render disabled state
+    }
+    else if (!isEnabled) {
+        return null;
+    }
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("style", { children: `
+          @keyframes spin {
+            from { transform: rotate(0deg); }
+            to { transform: rotate(360deg); }
+          }
+        ` }), (0, jsx_runtime_1.jsxs)("div", { className: `qnce-autosave-indicator qnce-autosave-${status} ${className}`, style: containerStyle, role: "status", "aria-live": "polite", "aria-label": `Autosave status: ${messages[status] ?? status}`, children: [(0, jsx_runtime_1.jsx)(StatusIcon, { status: status }), variant !== 'icon-only' && ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("span", { style: textStyle, children: messages[status] ?? status }), showTimestamp && lastAutosave && ((0, jsx_runtime_1.jsx)("span", { style: timestampStyle, children: formatTimestamp(lastAutosave) })), showTimestamp && !lastAutosave && ((0, jsx_runtime_1.jsx)("span", { style: timestampStyle, children: "Never" }))] }))] })] }));
+};
+exports.AutosaveIndicator = AutosaveIndicator;
+//# sourceMappingURL=AutosaveIndicator.js.map

package/dist/ui/components/AutosaveIndicator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutosaveIndicator.js","sourceRoot":"","sources":["../../../src/ui/components/AutosaveIndicator.tsx"],"names":[],"mappings":"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"}

package/dist/ui/components/UndoRedoControls.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import { UndoRedoControlsProps } from '../types';
+/**
+ * UndoRedoControls Component
+ *
+ * Provides accessible undo/redo buttons with real-time state updates,
+ * tooltips, keyboard support, and customizable theming.
+ *
+ * Features:
+ * - Real-time enable/disable based on undo/redo availability
+ * - Accessible with ARIA labels and keyboard navigation
+ * - Customizable themes and layouts
+ * - Integration with QNCE Engine undo/redo system
+ */
+export declare const UndoRedoControls: React.FC<UndoRedoControlsProps>;
+//# sourceMappingURL=UndoRedoControls.d.ts.map

package/dist/ui/components/UndoRedoControls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UndoRedoControls.d.ts","sourceRoot":"","sources":["../../../src/ui/components/UndoRedoControls.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAuC,MAAM,OAAO,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAA2B,MAAM,UAAU,CAAC;AAG1E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAqN5D,CAAC"}

package/dist/ui/components/UndoRedoControls.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UndoRedoControls = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const types_1 = require("../types");
+const react_2 = require("../../integrations/react");
+/**
+ * UndoRedoControls Component
+ *
+ * Provides accessible undo/redo buttons with real-time state updates,
+ * tooltips, keyboard support, and customizable theming.
+ *
+ * Features:
+ * - Real-time enable/disable based on undo/redo availability
+ * - Accessible with ARIA labels and keyboard navigation
+ * - Customizable themes and layouts
+ * - Integration with QNCE Engine undo/redo system
+ */
+const UndoRedoControls = ({ engine, theme: customTheme, className = '', style, disabled = false, showLabels = true, labels = { undo: 'Undo', redo: 'Redo' }, size = 'md', layout = 'horizontal', onUndo, onRedo }) => {
+    const { undo, redo, canUndo, canRedo, undoCount, redoCount } = (0, react_2.useUndoRedo)(engine);
+    // Merge custom theme with default theme
+    const theme = (0, react_1.useMemo)(() => ({
+        ...types_1.defaultTheme,
+        ...customTheme,
+        colors: { ...types_1.defaultTheme.colors, ...customTheme?.colors },
+        spacing: { ...types_1.defaultTheme.spacing, ...customTheme?.spacing },
+        borderRadius: { ...types_1.defaultTheme.borderRadius, ...customTheme?.borderRadius },
+        typography: {
+            ...types_1.defaultTheme.typography,
+            ...customTheme?.typography,
+            fontSize: { ...types_1.defaultTheme.typography.fontSize, ...customTheme?.typography?.fontSize },
+            fontWeight: { ...types_1.defaultTheme.typography.fontWeight, ...customTheme?.typography?.fontWeight }
+        },
+        shadows: { ...types_1.defaultTheme.shadows, ...customTheme?.shadows }
+    }), [customTheme]);
+    // Size configurations
+    const sizeConfig = {
+        sm: {
+            padding: `${theme.spacing.xs} ${theme.spacing.sm}`,
+            fontSize: theme.typography.fontSize.sm,
+            iconSize: '16px'
+        },
+        md: {
+            padding: `${theme.spacing.sm} ${theme.spacing.md}`,
+            fontSize: theme.typography.fontSize.md,
+            iconSize: '20px'
+        },
+        lg: {
+            padding: `${theme.spacing.md} ${theme.spacing.lg}`,
+            fontSize: theme.typography.fontSize.lg,
+            iconSize: '24px'
+        }
+    };
+    const currentSize = sizeConfig[size];
+    // Button styles
+    const buttonBaseStyle = {
+        fontFamily: theme.typography.fontFamily,
+        fontSize: currentSize.fontSize,
+        fontWeight: theme.typography.fontWeight.medium,
+        padding: currentSize.padding,
+        borderRadius: theme.borderRadius.md,
+        border: `1px solid ${theme.colors.primary}`,
+        backgroundColor: theme.colors.background,
+        color: theme.colors.primary,
+        cursor: 'pointer',
+        transition: 'all 0.2s ease-in-out',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: theme.spacing.xs,
+        boxShadow: theme.shadows.sm,
+        outline: 'none',
+        position: 'relative'
+    };
+    const buttonDisabledStyle = {
+        ...buttonBaseStyle,
+        backgroundColor: theme.colors.surface,
+        color: theme.colors.disabled,
+        borderColor: theme.colors.disabled,
+        cursor: 'not-allowed',
+        boxShadow: 'none'
+    };
+    const buttonHoverStyle = {
+        backgroundColor: theme.colors.primary,
+        color: theme.colors.background,
+        transform: 'translateY(-1px)',
+        boxShadow: theme.shadows.md
+    };
+    // Container styles
+    const containerStyle = {
+        display: 'flex',
+        flexDirection: layout === 'horizontal' ? 'row' : 'column',
+        gap: theme.spacing.sm,
+        alignItems: layout === 'horizontal' ? 'center' : 'stretch',
+        ...style
+    };
+    // Handle button actions
+    const handleUndo = async () => {
+        if (!disabled && canUndo) {
+            try {
+                const result = await undo();
+                onUndo?.(result);
+            }
+            catch (error) {
+                onUndo?.({ success: false, error: error instanceof Error ? error.message : 'Undo failed' });
+            }
+        }
+    };
+    const handleRedo = async () => {
+        if (!disabled && canRedo) {
+            try {
+                const result = await redo();
+                onRedo?.(result);
+            }
+            catch (error) {
+                onRedo?.({ success: false, error: error instanceof Error ? error.message : 'Redo failed' });
+            }
+        }
+    };
+    // Hover state management
+    const [undoHovered, setUndoHovered] = (0, react_1.useState)(false);
+    const [redoHovered, setRedoHovered] = (0, react_1.useState)(false);
+    // Icons (using Unicode symbols for simplicity - can be replaced with icon library)
+    const UndoIcon = () => ((0, jsx_runtime_1.jsx)("span", { style: { fontSize: currentSize.iconSize, lineHeight: 1 }, children: "\u21B6" }));
+    const RedoIcon = () => ((0, jsx_runtime_1.jsx)("span", { style: { fontSize: currentSize.iconSize, lineHeight: 1 }, children: "\u21B7" }));
+    return ((0, jsx_runtime_1.jsxs)("div", { className: `qnce-undo-redo-controls ${className}`, style: containerStyle, role: "group", "aria-label": "Undo and redo controls", children: [(0, jsx_runtime_1.jsxs)("button", { type: "button", onClick: handleUndo, disabled: disabled || !canUndo, style: {
+                    ...(disabled || !canUndo ? buttonDisabledStyle : buttonBaseStyle),
+                    ...(undoHovered && !disabled && canUndo ? buttonHoverStyle : {})
+                }, onMouseEnter: () => setUndoHovered(true), onMouseLeave: () => setUndoHovered(false), onFocus: () => setUndoHovered(true), onBlur: () => setUndoHovered(false), "aria-label": `${labels.undo}${undoCount > 0 ? ` (${undoCount} available)` : ''}`, title: `${labels.undo}${undoCount > 0 ? ` (${undoCount} available)` : ''}`, "aria-disabled": disabled || !canUndo, children: [(0, jsx_runtime_1.jsx)(UndoIcon, {}), showLabels && (0, jsx_runtime_1.jsx)("span", { children: labels.undo }), undoCount > 0 && ((0, jsx_runtime_1.jsxs)("span", { style: {
+                            fontSize: theme.typography.fontSize.sm,
+                            opacity: 0.8,
+                            fontWeight: theme.typography.fontWeight.normal
+                        }, children: ["(", undoCount, ")"] }))] }), (0, jsx_runtime_1.jsxs)("button", { type: "button", onClick: handleRedo, disabled: disabled || !canRedo, style: {
+                    ...(disabled || !canRedo ? buttonDisabledStyle : buttonBaseStyle),
+                    ...(redoHovered && !disabled && canRedo ? buttonHoverStyle : {})
+                }, onMouseEnter: () => setRedoHovered(true), onMouseLeave: () => setRedoHovered(false), onFocus: () => setRedoHovered(true), onBlur: () => setRedoHovered(false), "aria-label": `${labels.redo}${redoCount > 0 ? ` (${redoCount} available)` : ''}`, title: `${labels.redo}${redoCount > 0 ? ` (${redoCount} available)` : ''}`, "aria-disabled": disabled || !canRedo, children: [(0, jsx_runtime_1.jsx)(RedoIcon, {}), showLabels && (0, jsx_runtime_1.jsx)("span", { children: labels.redo }), redoCount > 0 && ((0, jsx_runtime_1.jsxs)("span", { style: {
+                            fontSize: theme.typography.fontSize.sm,
+                            opacity: 0.8,
+                            fontWeight: theme.typography.fontWeight.normal
+                        }, children: ["(", redoCount, ")"] }))] })] }));
+};
+exports.UndoRedoControls = UndoRedoControls;
+//# sourceMappingURL=UndoRedoControls.js.map

package/dist/ui/components/UndoRedoControls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UndoRedoControls.js","sourceRoot":"","sources":["../../../src/ui/components/UndoRedoControls.tsx"],"names":[],"mappings":"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"}

package/dist/ui/hooks/useKeyboardShortcuts.d.ts

@@ -0,0 +1,22 @@
+import { KeyboardShortcutsConfig } from '../types';
+import { QNCEEngine } from '../../engine/core';
+/**
+ * useKeyboardShortcuts Hook
+ *
+ * Provides keyboard shortcuts for common QNCE operations like undo/redo and autosave.
+ *
+ * Features:
+ * - Configurable key bindings
+ * - Support for modifier keys (Ctrl, Alt, Shift, Meta)
+ * - Automatic cleanup on unmount
+ * - Prevention of default browser behavior
+ * - Accessibility-friendly implementation
+ *
+ * Default shortcuts:
+ * - Ctrl+Z / Cmd+Z: Undo
+ * - Ctrl+Y / Cmd+Y / Ctrl+Shift+Z: Redo
+ * - Ctrl+S / Cmd+S: Manual autosave
+ * - Ctrl+R / Cmd+R: Reset narrative (disabled by default)
+ */
+export declare function useKeyboardShortcuts(engine: QNCEEngine, config?: KeyboardShortcutsConfig): void;
+//# sourceMappingURL=useKeyboardShortcuts.d.ts.map

package/dist/ui/hooks/useKeyboardShortcuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useKeyboardShortcuts.d.ts","sourceRoot":"","sources":["../../../src/ui/hooks/useKeyboardShortcuts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,MAAM,GAAE,uBAA4B,GACnC,IAAI,CA2JN"}

package/dist/ui/hooks/useKeyboardShortcuts.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useKeyboardShortcuts = useKeyboardShortcuts;
+const react_1 = require("react");
+/**
+ * useKeyboardShortcuts Hook
+ *
+ * Provides keyboard shortcuts for common QNCE operations like undo/redo and autosave.
+ *
+ * Features:
+ * - Configurable key bindings
+ * - Support for modifier keys (Ctrl, Alt, Shift, Meta)
+ * - Automatic cleanup on unmount
+ * - Prevention of default browser behavior
+ * - Accessibility-friendly implementation
+ *
+ * Default shortcuts:
+ * - Ctrl+Z / Cmd+Z: Undo
+ * - Ctrl+Y / Cmd+Y / Ctrl+Shift+Z: Redo
+ * - Ctrl+S / Cmd+S: Manual autosave
+ * - Ctrl+R / Cmd+R: Reset narrative (disabled by default)
+ */
+function useKeyboardShortcuts(engine, config = {}) {
+    const { enabled = true, bindings = {
+        undo: ['ctrl+z', 'cmd+z'],
+        redo: ['ctrl+y', 'cmd+y', 'ctrl+shift+z'],
+        save: ['ctrl+s', 'cmd+s'],
+        reset: [] // Disabled by default for safety
+    }, preventDefault = true, target = document } = config;
+    // Parse key combination string into components
+    const parseKeyCombo = (0, react_1.useCallback)((combo) => {
+        const parts = combo.toLowerCase().split('+');
+        const key = parts[parts.length - 1];
+        const modifiers = parts.slice(0, -1);
+        return {
+            key,
+            ctrl: modifiers.includes('ctrl'),
+            alt: modifiers.includes('alt'),
+            shift: modifiers.includes('shift'),
+            meta: modifiers.includes('cmd') || modifiers.includes('meta')
+        };
+    }, []);
+    // Check if a keyboard event matches a key combination
+    const matchesKeyCombo = (0, react_1.useCallback)((event, combo) => {
+        const parsed = parseKeyCombo(combo);
+        return (event.key.toLowerCase() === parsed.key &&
+            event.ctrlKey === parsed.ctrl &&
+            event.altKey === parsed.alt &&
+            event.shiftKey === parsed.shift &&
+            event.metaKey === parsed.meta);
+    }, [parseKeyCombo]);
+    // Handle keyboard events
+    const handleKeyDown = (0, react_1.useCallback)((event) => {
+        const keyboardEvent = event;
+        if (!enabled || !engine)
+            return;
+        // Skip if user is typing in an input field
+        const activeElement = document.activeElement;
+        if (activeElement && (activeElement.tagName === 'INPUT' ||
+            activeElement.tagName === 'TEXTAREA' ||
+            activeElement.tagName === 'SELECT' ||
+            activeElement.getAttribute('contenteditable') === 'true')) {
+            return;
+        }
+        let handled = false;
+        // Check undo shortcuts
+        for (const combo of bindings.undo || []) {
+            if (matchesKeyCombo(keyboardEvent, combo)) {
+                if (engine.canUndo()) {
+                    try {
+                        engine.undo();
+                    }
+                    catch (error) {
+                        console.error('[QNCE] Undo failed:', error);
+                    }
+                    handled = true;
+                    break;
+                }
+            }
+        }
+        // Check redo shortcuts
+        if (!handled) {
+            for (const combo of bindings.redo || []) {
+                if (matchesKeyCombo(keyboardEvent, combo)) {
+                    if (engine.canRedo()) {
+                        try {
+                            engine.redo();
+                        }
+                        catch (error) {
+                            console.error('[QNCE] Redo failed:', error);
+                        }
+                        handled = true;
+                        break;
+                    }
+                }
+            }
+        }
+        // Check autosave shortcuts
+        if (!handled) {
+            for (const combo of bindings.save || []) {
+                if (matchesKeyCombo(keyboardEvent, combo)) {
+                    engine.manualAutosave().catch((error) => {
+                        console.warn('[QNCE] Manual autosave failed:', error.message);
+                    });
+                    handled = true;
+                    break;
+                }
+            }
+        }
+        // Check reset shortcuts (if enabled)
+        if (!handled && bindings.reset && bindings.reset.length > 0) {
+            for (const combo of bindings.reset) {
+                if (matchesKeyCombo(keyboardEvent, combo)) {
+                    // Add confirmation for reset to prevent accidental data loss
+                    if (window.confirm('Are you sure you want to reset the narrative? This will lose all progress.')) {
+                        try {
+                            engine.resetNarrative();
+                        }
+                        catch (error) {
+                            console.error('[QNCE] Reset failed:', error);
+                        }
+                        handled = true;
+                        break;
+                    }
+                }
+            }
+        }
+        // Prevent default browser behavior if we handled the event
+        if (handled && preventDefault) {
+            keyboardEvent.preventDefault();
+            keyboardEvent.stopPropagation();
+        }
+    }, [enabled, engine, bindings, matchesKeyCombo, preventDefault]);
+    // Set up keyboard event listeners
+    (0, react_1.useEffect)(() => {
+        if (!enabled || !target)
+            return;
+        const currentTarget = target;
+        currentTarget.addEventListener('keydown', handleKeyDown);
+        return () => {
+            currentTarget.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [enabled, target, handleKeyDown]);
+    // Log active shortcuts for debugging (development only)
+    (0, react_1.useEffect)(() => {
+        if (!enabled || process.env.NODE_ENV === 'production')
+            return;
+        const shortcuts = [];
+        if (bindings.undo?.length)
+            shortcuts.push(`Undo: ${bindings.undo.join(', ')}`);
+        if (bindings.redo?.length)
+            shortcuts.push(`Redo: ${bindings.redo.join(', ')}`);
+        if (bindings.save?.length)
+            shortcuts.push(`Save: ${bindings.save.join(', ')}`);
+        if (bindings.reset?.length)
+            shortcuts.push(`Reset: ${bindings.reset.join(', ')}`);
+        if (shortcuts.length > 0) {
+            console.log('[QNCE] Active keyboard shortcuts:', shortcuts.join(' | '));
+        }
+    }, [enabled, bindings]);
+}
+//# sourceMappingURL=useKeyboardShortcuts.js.map

package/dist/ui/hooks/useKeyboardShortcuts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useKeyboardShortcuts.js","sourceRoot":"","sources":["../../../src/ui/hooks/useKeyboardShortcuts.ts"],"names":[],"mappings":"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"}

package/dist/ui/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * QNCE Engine UI Components
+ * Sprint 3.6: Ready-to-use React components for narrative applications
+ */
+export { UndoRedoControls } from './components/UndoRedoControls';
+export { AutosaveIndicator } from './components/AutosaveIndicator';
+export { useKeyboardShortcuts } from './hooks/useKeyboardShortcuts';
+export type { UndoRedoControlsProps, AutosaveIndicatorProps, KeyboardShortcutsConfig, QNCETheme } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/ui/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,SAAS,EACV,MAAM,SAAS,CAAC"}

package/dist/ui/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * QNCE Engine UI Components
+ * Sprint 3.6: Ready-to-use React components for narrative applications
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useKeyboardShortcuts = exports.AutosaveIndicator = exports.UndoRedoControls = void 0;
+var UndoRedoControls_1 = require("./components/UndoRedoControls");
+Object.defineProperty(exports, "UndoRedoControls", { enumerable: true, get: function () { return UndoRedoControls_1.UndoRedoControls; } });
+var AutosaveIndicator_1 = require("./components/AutosaveIndicator");
+Object.defineProperty(exports, "AutosaveIndicator", { enumerable: true, get: function () { return AutosaveIndicator_1.AutosaveIndicator; } });
+var useKeyboardShortcuts_1 = require("./hooks/useKeyboardShortcuts");
+Object.defineProperty(exports, "useKeyboardShortcuts", { enumerable: true, get: function () { return useKeyboardShortcuts_1.useKeyboardShortcuts; } });
+//# sourceMappingURL=index.js.map

package/dist/ui/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,kEAAiE;AAAxD,oHAAA,gBAAgB,OAAA;AACzB,oEAAmE;AAA1D,sHAAA,iBAAiB,OAAA;AAC1B,qEAAoE;AAA3D,4HAAA,oBAAoB,OAAA"}