@octanejs/tanstack-hotkeys 0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @octanejs/tanstack-hotkeys
+
+Octane port of `@tanstack/react-hotkeys` — keyboard hotkeys, chord sequences,
+held-key tracking, and shortcut recording. Re-exports the framework-agnostic
+`@tanstack/hotkeys` core unchanged and implements the full hook surface
+(`useHotkey`, `useHotkeys`, `useHeldKeys`, `useHeldKeyCodes`, `useKeyHold`,
+`useHotkeySequence`, `useHotkeySequences`, `useHotkeyRecorder`,
+`useHotkeySequenceRecorder`, `useHotkeyRegistrations`) plus `HotkeysProvider`
+on Octane hooks, with store subscriptions via `@octanejs/tanstack-store`.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@octanejs/tanstack-hotkeys",
+  "version": "0.0.5",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "TanStack Hotkeys bindings for Octane — reuses the framework-agnostic @tanstack/hotkeys core with an Octane hook adapter.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/tanstack-hotkeys"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@tanstack/hotkeys": "0.8.0"
+  },
+  "peerDependencies": {
+    "@octanejs/tanstack-store": "0.0.10",
+    "octane": "0.1.16"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10",
+    "octane": "0.1.16",
+    "@octanejs/tanstack-store": "0.0.10"
+  },
+  "scripts": {
+    "test": "vitest run --project tanstack-hotkeys",
+    "typecheck": "tsrx-tsc --noEmit"
+  }
+}

package/src/HotkeysProvider.tsrx

@@ -0,0 +1,28 @@
+import { useMemo } from 'octane';
+import type { OctaneNode } from 'octane';
+import { HotkeysContext } from './context.ts';
+import type { HotkeysContextValue, HotkeysProviderOptions } from './context.ts';
+
+export interface HotkeysProviderProps {
+	children: OctaneNode;
+	defaultOptions?: HotkeysProviderOptions;
+}
+
+const DEFAULT_OPTIONS: HotkeysProviderOptions = {};
+
+// HotkeysProvider — provides shared default options for the hotkey hooks. It's
+// authored in .tsrx because it's a COMPONENT that renders a context Provider
+// with children (the binding's hooks stay plain TS).
+export function HotkeysProvider({
+	children,
+	defaultOptions = DEFAULT_OPTIONS,
+}: HotkeysProviderProps) @{
+	const contextValue: HotkeysContextValue = useMemo(
+		() => ({
+			defaultOptions,
+		}),
+		[defaultOptions],
+	);
+
+	<HotkeysContext.Provider value={contextValue}>{children}</HotkeysContext.Provider>
+}

package/src/HotkeysProvider.tsrx.d.ts

@@ -0,0 +1,12 @@
+// Type declaration for the .tsrx provider component (HotkeysProvider.tsrx).
+// It's a SPECIFIC module declaration (resolved by relative path), not an ambient
+// `declare module '*.tsrx'` — so it types only this module and doesn't pollute a
+// consumer's own .tsrx imports. The runtime resolves the real compiled .tsrx.
+import type { HotkeysProviderOptions } from './context';
+
+export interface HotkeysProviderProps {
+	children: unknown;
+	defaultOptions?: HotkeysProviderOptions;
+}
+
+export declare function HotkeysProvider(props: HotkeysProviderProps): unknown;

package/src/context.ts

@@ -0,0 +1,26 @@
+import { createContext, useContext } from 'octane';
+import type { HotkeyRecorderOptions, HotkeySequenceRecorderOptions } from '@tanstack/hotkeys';
+import type { UseHotkeyOptions } from './useHotkey';
+import type { UseHotkeySequenceOptions } from './useHotkeySequence';
+
+export interface HotkeysProviderOptions {
+	hotkey?: Partial<UseHotkeyOptions>;
+	hotkeyRecorder?: Partial<HotkeyRecorderOptions>;
+	hotkeySequence?: Partial<UseHotkeySequenceOptions>;
+	hotkeySequenceRecorder?: Partial<HotkeySequenceRecorderOptions>;
+}
+
+export interface HotkeysContextValue {
+	defaultOptions: HotkeysProviderOptions;
+}
+
+export const HotkeysContext = createContext<HotkeysContextValue | null>(null);
+
+export function useHotkeysContext() {
+	return useContext(HotkeysContext);
+}
+
+export function useDefaultHotkeysOptions() {
+	const context = useContext(HotkeysContext);
+	return context?.defaultOptions ?? {};
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// Octane port of @tanstack/react-hotkeys@0.10.0 — thin hook wrappers over the
+// framework-agnostic @tanstack/hotkeys core, mirroring the upstream module
+// layout (src/index.ts).
+
+// Re-export everything from the core package
+export * from '@tanstack/hotkeys';
+
+// provider
+export { HotkeysProvider } from './HotkeysProvider.tsrx';
+export type { HotkeysProviderProps } from './HotkeysProvider.tsrx';
+export { useHotkeysContext, useDefaultHotkeysOptions } from './context';
+export type { HotkeysProviderOptions } from './context';
+
+// Octane-specific exports (upstream: "React-specific exports")
+export * from './useHotkey';
+export * from './useHotkeys';
+export * from './useHeldKeys';
+export * from './useHeldKeyCodes';
+export * from './useKeyHold';
+export * from './useHotkeySequence';
+export * from './useHotkeySequences';
+export * from './useHotkeyRecorder';
+export * from './useHotkeyRegistrations';
+export * from './useHotkeySequenceRecorder';

package/src/internal.ts

@@ -0,0 +1,31 @@
+import { useSelector } from '@octanejs/tanstack-store';
+
+// Slot mechanics for the binding's plain-`.ts` hooks. The octane compiler
+// wraps custom-hook CALLS made from compiled `.tsrx`/`.tsx` modules in
+// `withSlot`, but calls made from plain `.ts` modules (this binding's hooks
+// composing `useSelector` from @octanejs/tanstack-store) are not wrapped —
+// so a hook that composes `useSelector` more than once must hand each call
+// site its own slot symbol. `useSelector` reads the slot off its last
+// argument; the public overloads don't declare it, hence the cast here.
+
+type SelectionSource<T> = {
+	get: () => T;
+	subscribe: (listener: (value: T) => void) => {
+		unsubscribe: () => void;
+	};
+};
+
+export function useSelectorSlot<TSource, TSelected>(
+	source: SelectionSource<TSource>,
+	selector: (snapshot: TSource) => TSelected,
+	slot: symbol,
+): TSelected {
+	return (
+		useSelector as (
+			source: SelectionSource<TSource>,
+			selector: (snapshot: TSource) => TSelected,
+			options: undefined,
+			slot: symbol,
+		) => TSelected
+	)(source, selector, undefined, slot);
+}

package/src/useHeldKeyCodes.ts

@@ -0,0 +1,35 @@
+import { getKeyStateTracker } from '@tanstack/hotkeys';
+import { useSelectorSlot } from './internal';
+
+const heldKeyCodesSlot = Symbol.for('@octanejs/tanstack-hotkeys:useHeldKeyCodes');
+
+/**
+ * Octane hook that returns a map of currently held key names to their physical `event.code` values.
+ *
+ * This is useful for debugging which physical key was pressed (e.g. distinguishing
+ * left vs right Shift via "ShiftLeft" / "ShiftRight").
+ *
+ * @returns Record mapping normalized key names to their `event.code` values
+ *
+ * @example
+ * ```tsx
+ * function KeyDebugDisplay() {
+ *   const heldKeys = useHeldKeys()
+ *   const heldCodes = useHeldKeyCodes()
+ *
+ *   return (
+ *     <div>
+ *       {heldKeys.map((key) => (
+ *         <kbd key={key}>
+ *           {key} <small>{heldCodes[key]}</small>
+ *         </kbd>
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useHeldKeyCodes(): Record<string, string> {
+	const tracker = getKeyStateTracker();
+	return useSelectorSlot(tracker.store, (state) => state.heldCodes, heldKeyCodesSlot);
+}

package/src/useHeldKeys.ts

@@ -0,0 +1,31 @@
+import { getKeyStateTracker } from '@tanstack/hotkeys';
+import { useSelectorSlot } from './internal';
+
+const heldKeysSlot = Symbol.for('@octanejs/tanstack-hotkeys:useHeldKeys');
+
+/**
+ * Octane hook that returns an array of currently held keyboard keys.
+ *
+ * This hook uses `useSelector` from `@octanejs/tanstack-store` to subscribe
+ * to the global KeyStateTracker and updates whenever keys are pressed
+ * or released.
+ *
+ * @returns Array of currently held key names
+ *
+ * @example
+ * ```tsx
+ * function KeyDisplay() {
+ *   const heldKeys = useHeldKeys()
+ *
+ *   return (
+ *     <div>
+ *       Currently pressed: {heldKeys.join(' + ') || 'None'}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useHeldKeys(): Array<string> {
+	const tracker = getKeyStateTracker();
+	return useSelectorSlot(tracker.store, (state) => state.heldKeys, heldKeysSlot);
+}

package/src/useHotkey.ts

@@ -0,0 +1,145 @@
+import { useEffect, useRef } from 'octane';
+import { detectPlatform, getHotkeyManager, normalizeRegisterableHotkey } from '@tanstack/hotkeys';
+import { useDefaultHotkeysOptions } from './context';
+import { isRef } from './utils';
+import type { RefObjectLike } from './utils';
+import type {
+	HotkeyCallback,
+	HotkeyOptions,
+	HotkeyRegistrationHandle,
+	RegisterableHotkey,
+} from '@tanstack/hotkeys';
+
+export interface UseHotkeyOptions extends Omit<HotkeyOptions, 'target'> {
+	/**
+	 * The DOM element to attach the event listener to.
+	 * Can be a ref object, direct DOM element, or null.
+	 * Defaults to document.
+	 */
+	target?: RefObjectLike<HTMLElement | null> | HTMLElement | Document | Window | null;
+}
+
+/**
+ * Octane hook for registering a keyboard hotkey.
+ *
+ * Uses the singleton HotkeyManager for efficient event handling.
+ * The callback receives both the keyboard event and a context object
+ * containing the hotkey string and parsed hotkey.
+ *
+ * This hook syncs the callback and options on every render to avoid
+ * stale closures. This means callbacks that reference component state will
+ * always have access to the latest values.
+ *
+ * @param hotkey - The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object (supports `mod` for cross-platform)
+ * @param callback - The function to call when the hotkey is pressed
+ * @param options - Options for the hotkey behavior. `enabled: false` keeps the registration (visible in devtools)
+ *   and only suppresses firing; the hook updates the existing handle instead of unregistering.
+ *
+ * @example
+ * ```tsx
+ * function SaveButton() {
+ *   const [count, setCount] = useState(0)
+ *
+ *   // Callback always has access to latest count value
+ *   useHotkey('Mod+S', (event, { hotkey }) => {
+ *     console.log(`Save triggered, count is ${count}`)
+ *     handleSave()
+ *   })
+ *
+ *   return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
+ * }
+ * ```
+ */
+export function useHotkey(
+	hotkey: RegisterableHotkey,
+	callback: HotkeyCallback,
+	options: UseHotkeyOptions = {},
+): void {
+	const mergedOptions = {
+		...useDefaultHotkeysOptions().hotkey,
+		...options,
+	} as UseHotkeyOptions;
+
+	const manager = getHotkeyManager();
+
+	// Stable ref for registration handle
+	const registrationRef = useRef<HotkeyRegistrationHandle | null>(null);
+
+	// Refs to capture current values for use in effect without adding dependencies
+	const callbackRef = useRef(callback);
+	const optionsRef = useRef(mergedOptions);
+	const managerRef = useRef(manager);
+
+	// Update refs on every render
+	callbackRef.current = callback;
+	optionsRef.current = mergedOptions;
+	managerRef.current = manager;
+
+	// Track previous target and hotkey to detect changes requiring re-registration
+	const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null);
+	const prevHotkeyRef = useRef<string | null>(null);
+
+	// Normalize to hotkey string
+	const platform = mergedOptions.platform ?? detectPlatform();
+	const hotkeyString = normalizeRegisterableHotkey(hotkey, platform);
+
+	// Extract options without target (target is handled separately)
+	const { target: _target, ...optionsWithoutTarget } = mergedOptions;
+
+	useEffect(() => {
+		// Resolve target inside the effect so refs are already attached after mount
+		const resolvedTarget = isRef(optionsRef.current.target)
+			? optionsRef.current.target.current
+			: (optionsRef.current.target ?? (typeof document !== 'undefined' ? document : null));
+
+		// Skip if no valid target (SSR or ref still null)
+		if (!resolvedTarget) {
+			if (registrationRef.current?.isActive) {
+				registrationRef.current.unregister();
+				registrationRef.current = null;
+			}
+			prevTargetRef.current = null;
+			prevHotkeyRef.current = null;
+			return;
+		}
+
+		// Check if we need to re-register (target or hotkey changed)
+		const targetChanged =
+			prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget;
+		const hotkeyChanged = prevHotkeyRef.current !== null && prevHotkeyRef.current !== hotkeyString;
+
+		// If we have an active registration and target/hotkey changed, unregister first
+		if (registrationRef.current?.isActive && (targetChanged || hotkeyChanged)) {
+			registrationRef.current.unregister();
+			registrationRef.current = null;
+		}
+
+		// Register if needed (no active registration)
+		// Use refs to access current values without adding them to dependencies
+		if (!registrationRef.current || !registrationRef.current.isActive) {
+			registrationRef.current = managerRef.current.register(hotkeyString, callbackRef.current, {
+				...optionsRef.current,
+				target: resolvedTarget,
+			});
+		}
+
+		// Update tracking refs
+		prevTargetRef.current = resolvedTarget;
+		prevHotkeyRef.current = hotkeyString;
+
+		// Cleanup on unmount
+		return () => {
+			if (registrationRef.current?.isActive) {
+				registrationRef.current.unregister();
+				registrationRef.current = null;
+			}
+		};
+	}, [hotkeyString]);
+
+	// Sync callback and options on EVERY render (outside useEffect)
+	// This avoids stale closures - the callback always has access to latest state
+	if (registrationRef.current?.isActive) {
+		registrationRef.current.callback = callback;
+		registrationRef.current.setOptions(optionsWithoutTarget);
+	}
+}

package/src/useHotkeyRecorder.ts

@@ -0,0 +1,108 @@
+import { useEffect, useRef } from 'octane';
+import { HotkeyRecorder } from '@tanstack/hotkeys';
+import { useDefaultHotkeysOptions } from './context';
+import { useSelectorSlot } from './internal';
+import type { Hotkey, HotkeyRecorderOptions } from '@tanstack/hotkeys';
+
+const isRecordingSlot = Symbol.for('@octanejs/tanstack-hotkeys:useHotkeyRecorder:isRecording');
+const recordedHotkeySlot = Symbol.for(
+	'@octanejs/tanstack-hotkeys:useHotkeyRecorder:recordedHotkey',
+);
+
+// Upstream export name kept verbatim ("React"-prefixed) so ports from
+// @tanstack/react-hotkeys only need to change the import specifier.
+export interface ReactHotkeyRecorder {
+	/** Whether recording is currently active */
+	isRecording: boolean;
+	/** The currently recorded hotkey (for live preview) */
+	recordedHotkey: Hotkey | null;
+	/** Start recording a new hotkey */
+	startRecording: () => void;
+	/** Stop recording (same as cancel) */
+	stopRecording: () => void;
+	/** Cancel recording without saving */
+	cancelRecording: () => void;
+}
+
+/**
+ * Octane hook for recording keyboard shortcuts.
+ *
+ * This hook provides a thin wrapper around the framework-agnostic `HotkeyRecorder`
+ * class, managing all the complexity of capturing keyboard events, converting them
+ * to hotkey strings, and handling edge cases like Escape to cancel or Backspace/Delete
+ * to clear.
+ *
+ * @param options - Configuration options for the recorder
+ * @returns An object with recording state and control functions
+ *
+ * @example
+ * ```tsx
+ * function ShortcutSettings() {
+ *   const [shortcut, setShortcut] = useState<Hotkey>('Mod+S')
+ *
+ *   const recorder = useHotkeyRecorder({
+ *     onRecord: (hotkey) => {
+ *       setShortcut(hotkey)
+ *     },
+ *     onCancel: () => {
+ *       console.log('Recording cancelled')
+ *     },
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={recorder.startRecording}>
+ *         {recorder.isRecording ? 'Recording...' : 'Edit Shortcut'}
+ *       </button>
+ *       {recorder.recordedHotkey && (
+ *         <div>Recording: {recorder.recordedHotkey}</div>
+ *       )}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useHotkeyRecorder(options: HotkeyRecorderOptions): ReactHotkeyRecorder {
+	const mergedOptions = {
+		...useDefaultHotkeysOptions().hotkeyRecorder,
+		...options,
+	} as HotkeyRecorderOptions;
+
+	const recorderRef = useRef<HotkeyRecorder | null>(null);
+
+	// Create recorder instance once
+	if (!recorderRef.current) {
+		recorderRef.current = new HotkeyRecorder(mergedOptions);
+	}
+
+	// Sync options on every render (same pattern as useHotkey)
+	// This ensures callbacks always have access to latest values
+	recorderRef.current.setOptions(mergedOptions);
+
+	// Subscribe to recorder state using useSelector (same pattern as useHeldKeys)
+	const isRecording = useSelectorSlot(
+		recorderRef.current.store,
+		(state) => state.isRecording,
+		isRecordingSlot,
+	);
+	const recordedHotkey = useSelectorSlot(
+		recorderRef.current.store,
+		(state) => state.recordedHotkey,
+		recordedHotkeySlot,
+	);
+
+	// Cleanup on unmount
+	useEffect(() => {
+		return () => {
+			recorderRef.current?.destroy();
+		};
+	}, []);
+
+	return {
+		isRecording,
+		recordedHotkey,
+		startRecording: () => recorderRef.current?.start(),
+		stopRecording: () => recorderRef.current?.stop(),
+		cancelRecording: () => recorderRef.current?.cancel(),
+	};
+}

package/src/useHotkeyRegistrations.ts

@@ -0,0 +1,67 @@
+import { getHotkeyManager, getSequenceManager, toHotkeyRegistrationView } from '@tanstack/hotkeys';
+import type { HotkeyRegistrationView, SequenceRegistrationView } from '@tanstack/hotkeys';
+import { useSelectorSlot } from './internal';
+
+const hotkeysSlot = Symbol.for('@octanejs/tanstack-hotkeys:useHotkeyRegistrations:hotkeys');
+const sequencesSlot = Symbol.for('@octanejs/tanstack-hotkeys:useHotkeyRegistrations:sequences');
+
+/**
+ * Return type for useHotkeyRegistrations.
+ */
+export interface HotkeyRegistrationsResult {
+	/** All registered hotkeys (public view, no callbacks) */
+	hotkeys: Array<HotkeyRegistrationView>;
+	/** All registered sequences */
+	sequences: Array<SequenceRegistrationView>;
+}
+
+/**
+ * Octane hook that reactively reads all hotkey and sequence registrations
+ * from the singleton managers.
+ *
+ * This is a standalone hook that does NOT require the HotkeysProvider.
+ * It subscribes to both HotkeyManager and SequenceManager stores and
+ * re-renders when registrations change.
+ *
+ * @returns Object with `hotkeys` and `sequences` arrays
+ *
+ * @example
+ * ```tsx
+ * function ShortcutPalette() {
+ *   const { hotkeys, sequences } = useHotkeyRegistrations()
+ *
+ *   return (
+ *     <ul>
+ *       {hotkeys.map((reg) => (
+ *         <li key={reg.id}>
+ *           {reg.options.meta?.name ?? reg.hotkey}
+ *         </li>
+ *       ))}
+ *       {sequences.map((reg) => (
+ *         <li key={reg.id}>
+ *           {reg.options.meta?.name ?? reg.sequence.join(' ')}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ * ```
+ */
+export function useHotkeyRegistrations(): HotkeyRegistrationsResult {
+	const hotkeyManager = getHotkeyManager();
+	const sequenceManager = getSequenceManager();
+
+	const hotkeys = useSelectorSlot(
+		hotkeyManager.registrations,
+		(state) => Array.from(state.values()).map(toHotkeyRegistrationView),
+		hotkeysSlot,
+	);
+
+	const sequences = useSelectorSlot(
+		sequenceManager.registrations,
+		(state) => Array.from(state.values()),
+		sequencesSlot,
+	);
+
+	return { hotkeys, sequences };
+}

package/src/useHotkeySequence.ts

@@ -0,0 +1,163 @@
+import { useEffect, useRef } from 'octane';
+import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys';
+import { useDefaultHotkeysOptions } from './context';
+import { isRef } from './utils';
+import type { RefObjectLike } from './utils';
+import type {
+	HotkeyCallback,
+	HotkeyCallbackContext,
+	HotkeySequence,
+	SequenceOptions,
+	SequenceRegistrationHandle,
+} from '@tanstack/hotkeys';
+
+export interface UseHotkeySequenceOptions extends Omit<SequenceOptions, 'target'> {
+	/**
+	 * The DOM element to attach the event listener to.
+	 * Can be a ref object, direct DOM element, or null.
+	 * Defaults to document.
+	 */
+	target?: RefObjectLike<HTMLElement | null> | HTMLElement | Document | Window | null;
+}
+
+/**
+ * Octane hook for registering a keyboard shortcut sequence (Vim-style).
+ *
+ * This hook allows you to register multi-key sequences like 'g g' or 'd d'
+ * that trigger when the full sequence is pressed within a timeout.
+ *
+ * Each step may include modifiers. You can chain the same modifier across
+ * steps (e.g. `Shift+R` then `Shift+T`). Modifier-only keydown events (Shift,
+ * Control, Alt, or Meta pressed alone) are ignored while matching—they do not
+ * advance the sequence or reset progress.
+ *
+ * @param sequence - Array of hotkey strings that form the sequence
+ * @param callback - Function to call when the sequence is completed
+ * @param options - Options for the sequence behavior. `enabled: false` keeps the registration (visible in devtools)
+ *   and only suppresses firing; the hook updates the existing handle instead of unregistering.
+ *
+ * @example
+ * ```tsx
+ * function VimEditor() {
+ *   // 'g g' to go to top
+ *   useHotkeySequence(['G', 'G'], () => {
+ *     scrollToTop()
+ *   })
+ *
+ *   // 'd i w' to delete inner word
+ *   useHotkeySequence(['D', 'I', 'W'], () => {
+ *     deleteInnerWord()
+ *   }, { timeout: 500 })
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+export function useHotkeySequence(
+	sequence: HotkeySequence,
+	callback: HotkeyCallback,
+	options: UseHotkeySequenceOptions = {},
+): void {
+	const mergedOptions = {
+		...useDefaultHotkeysOptions().hotkeySequence,
+		...options,
+	} as UseHotkeySequenceOptions;
+
+	const manager = getSequenceManager();
+
+	// Stable ref for registration handle
+	const registrationRef = useRef<SequenceRegistrationHandle | null>(null);
+
+	// Refs to capture current values for use in effect without adding dependencies
+	const callbackRef = useRef(callback);
+	const optionsRef = useRef(mergedOptions);
+	const managerRef = useRef(manager);
+	const sequenceRef = useRef(sequence);
+
+	// Update refs on every render
+	callbackRef.current = callback;
+	optionsRef.current = mergedOptions;
+	managerRef.current = manager;
+	sequenceRef.current = sequence;
+
+	// Track previous target and sequence to detect changes requiring re-registration
+	const prevTargetRef = useRef<HTMLElement | Document | Window | null>(null);
+	const prevSequenceRef = useRef<string | null>(null);
+
+	// Normalize to hotkey sequence string (join with spaces)
+	const hotkeySequenceString = formatHotkeySequence(sequence);
+
+	// Extract options without target (target is handled separately)
+	const { target: _target, ...optionsWithoutTarget } = mergedOptions;
+
+	useEffect(() => {
+		if (sequenceRef.current.length === 0) {
+			if (registrationRef.current?.isActive) {
+				registrationRef.current.unregister();
+				registrationRef.current = null;
+			}
+			prevTargetRef.current = null;
+			prevSequenceRef.current = null;
+			return;
+		}
+
+		// Resolve target inside the effect so refs are already attached after mount
+		const resolvedTarget = isRef(optionsRef.current.target)
+			? optionsRef.current.target.current
+			: (optionsRef.current.target ?? (typeof document !== 'undefined' ? document : null));
+
+		// Skip if no valid target (SSR or ref still null)
+		if (!resolvedTarget) {
+			if (registrationRef.current?.isActive) {
+				registrationRef.current.unregister();
+				registrationRef.current = null;
+			}
+			prevTargetRef.current = null;
+			prevSequenceRef.current = null;
+			return;
+		}
+
+		// Check if we need to re-register (target or sequence changed)
+		const targetChanged =
+			prevTargetRef.current !== null && prevTargetRef.current !== resolvedTarget;
+		const sequenceChanged =
+			prevSequenceRef.current !== null && prevSequenceRef.current !== hotkeySequenceString;
+
+		// If we have an active registration and target/sequence changed, unregister first
+		if (registrationRef.current?.isActive && (targetChanged || sequenceChanged)) {
+			registrationRef.current.unregister();
+			registrationRef.current = null;
+		}
+
+		// Register if needed (no active registration)
+		if (!registrationRef.current || !registrationRef.current.isActive) {
+			registrationRef.current = managerRef.current.register(
+				sequenceRef.current,
+				(event, context) => callbackRef.current(event, context),
+				{
+					...optionsRef.current,
+					target: resolvedTarget,
+				},
+			);
+		}
+
+		// Update tracking refs
+		prevTargetRef.current = resolvedTarget;
+		prevSequenceRef.current = hotkeySequenceString;
+
+		// Cleanup on unmount
+		return () => {
+			if (registrationRef.current?.isActive) {
+				registrationRef.current.unregister();
+				registrationRef.current = null;
+			}
+		};
+	}, [hotkeySequenceString]);
+
+	// Sync callback and options on EVERY render (outside useEffect)
+	if (registrationRef.current?.isActive) {
+		registrationRef.current.callback = (event: KeyboardEvent, context: HotkeyCallbackContext) =>
+			callbackRef.current(event, context);
+		registrationRef.current.setOptions(optionsWithoutTarget);
+	}
+}

package/src/useHotkeySequenceRecorder.ts

@@ -0,0 +1,79 @@
+import { useEffect, useRef } from 'octane';
+import { HotkeySequenceRecorder } from '@tanstack/hotkeys';
+import { useDefaultHotkeysOptions } from './context';
+import { useSelectorSlot } from './internal';
+import type { HotkeySequence, HotkeySequenceRecorderOptions } from '@tanstack/hotkeys';
+
+const isRecordingSlot = Symbol.for(
+	'@octanejs/tanstack-hotkeys:useHotkeySequenceRecorder:isRecording',
+);
+const stepsSlot = Symbol.for('@octanejs/tanstack-hotkeys:useHotkeySequenceRecorder:steps');
+const recordedSequenceSlot = Symbol.for(
+	'@octanejs/tanstack-hotkeys:useHotkeySequenceRecorder:recordedSequence',
+);
+
+// Upstream export name kept verbatim ("React"-prefixed) so ports from
+// @tanstack/react-hotkeys only need to change the import specifier.
+export interface ReactHotkeySequenceRecorder {
+	/** Whether recording is currently active */
+	isRecording: boolean;
+	/** Chords captured in the current session */
+	steps: HotkeySequence;
+	/** Last committed sequence */
+	recordedSequence: HotkeySequence | null;
+	startRecording: () => void;
+	stopRecording: () => void;
+	cancelRecording: () => void;
+	/** Commit current steps (no-op if empty) */
+	commitRecording: () => void;
+}
+
+/**
+ * Octane hook for recording multi-chord sequences (Vim-style shortcuts).
+ *
+ * @param options - Configuration options for the hotkey sequence recorder
+ */
+export function useHotkeySequenceRecorder(
+	options: HotkeySequenceRecorderOptions,
+): ReactHotkeySequenceRecorder {
+	const mergedOptions = {
+		...useDefaultHotkeysOptions().hotkeySequenceRecorder,
+		...options,
+	} as HotkeySequenceRecorderOptions;
+
+	const recorderRef = useRef<HotkeySequenceRecorder | null>(null);
+
+	if (!recorderRef.current) {
+		recorderRef.current = new HotkeySequenceRecorder(mergedOptions);
+	}
+
+	recorderRef.current.setOptions(mergedOptions);
+
+	const isRecording = useSelectorSlot(
+		recorderRef.current.store,
+		(state) => state.isRecording,
+		isRecordingSlot,
+	);
+	const steps = useSelectorSlot(recorderRef.current.store, (state) => state.steps, stepsSlot);
+	const recordedSequence = useSelectorSlot(
+		recorderRef.current.store,
+		(state) => state.recordedSequence,
+		recordedSequenceSlot,
+	);
+
+	useEffect(() => {
+		return () => {
+			recorderRef.current?.destroy();
+		};
+	}, []);
+
+	return {
+		isRecording,
+		steps,
+		recordedSequence,
+		startRecording: () => recorderRef.current?.start(),
+		stopRecording: () => recorderRef.current?.stop(),
+		cancelRecording: () => recorderRef.current?.cancel(),
+		commitRecording: () => recorderRef.current?.commit(),
+	};
+}

package/src/useHotkeySequences.ts

@@ -0,0 +1,187 @@
+import { useEffect, useRef } from 'octane';
+import { formatHotkeySequence, getSequenceManager } from '@tanstack/hotkeys';
+import { useDefaultHotkeysOptions } from './context';
+import { isRef } from './utils';
+import type { UseHotkeySequenceOptions } from './useHotkeySequence';
+import type { HotkeyCallback, HotkeySequence, SequenceRegistrationHandle } from '@tanstack/hotkeys';
+
+/**
+ * A single sequence definition for use with `useHotkeySequences`.
+ */
+export interface UseHotkeySequenceDefinition {
+	/** Array of hotkey strings that form the sequence */
+	sequence: HotkeySequence;
+	/** The function to call when the sequence is completed */
+	callback: HotkeyCallback;
+	/** Per-sequence options (merged on top of commonOptions) */
+	options?: UseHotkeySequenceOptions;
+}
+
+/**
+ * Octane hook for registering multiple keyboard shortcut sequences at once (Vim-style).
+ *
+ * Uses the singleton SequenceManager. Accepts a dynamic array of definitions so you can
+ * register variable-length lists.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * Callbacks and options are synced on every render to avoid stale closures.
+ *
+ * Definitions with an empty `sequence` are skipped (no registration).
+ *
+ * @param definitions - Array of sequence definitions to register
+ * @param commonOptions - Shared options applied to all sequences (overridden by per-definition options).
+ *   Per-row `enabled: false` still registers that sequence: `SequenceManager` suppresses execution only (the row
+ *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
+ *   via `setOptions` (no unregister/re-register churn).
+ *
+ * @example
+ * ```tsx
+ * function VimPalette() {
+ *   useHotkeySequences([
+ *     { sequence: ['G', 'G'], callback: () => scrollToTop() },
+ *     { sequence: ['D', 'D'], callback: () => deleteLine() },
+ *     { sequence: ['C', 'I', 'W'], callback: () => changeInnerWord(), options: { timeout: 500 } },
+ *   ])
+ * }
+ * ```
+ */
+export function useHotkeySequences(
+	definitions: Array<UseHotkeySequenceDefinition>,
+	commonOptions: UseHotkeySequenceOptions = {},
+): void {
+	type RegistrationRecord = {
+		handle: SequenceRegistrationHandle;
+		target: Document | HTMLElement | Window;
+	};
+
+	const defaultOptions = useDefaultHotkeysOptions().hotkeySequence;
+	const manager = getSequenceManager();
+
+	const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map());
+	const definitionsRef = useRef(definitions);
+	const sequenceStringsRef = useRef<Array<string>>([]);
+	const commonOptionsRef = useRef(commonOptions);
+	const defaultOptionsRef = useRef(defaultOptions);
+	const managerRef = useRef(manager);
+
+	const sequenceStrings = definitions.map((def) => formatHotkeySequence(def.sequence));
+
+	definitionsRef.current = definitions;
+	sequenceStringsRef.current = sequenceStrings;
+	commonOptionsRef.current = commonOptions;
+	defaultOptionsRef.current = defaultOptions;
+	managerRef.current = manager;
+
+	useEffect(() => {
+		const prevRegistrations = registrationsRef.current;
+		const nextRegistrations = new Map<string, RegistrationRecord>();
+
+		const rows: Array<{
+			registrationKey: string;
+			def: (typeof definitionsRef.current)[number];
+			seq: HotkeySequence;
+			seqStr: string;
+			mergedOptions: UseHotkeySequenceOptions;
+			resolvedTarget: Document | HTMLElement | Window;
+		}> = [];
+
+		for (let i = 0; i < definitionsRef.current.length; i++) {
+			const def = definitionsRef.current[i]!;
+			const seqStr = sequenceStringsRef.current[i]!;
+			const seq = def.sequence;
+			if (seq.length === 0) {
+				continue;
+			}
+
+			const mergedOptions = {
+				...defaultOptionsRef.current,
+				...commonOptionsRef.current,
+				...def.options,
+			} as UseHotkeySequenceOptions;
+
+			const resolvedTarget = isRef(mergedOptions.target)
+				? mergedOptions.target.current
+				: (mergedOptions.target ?? (typeof document !== 'undefined' ? document : null));
+
+			if (!resolvedTarget) {
+				continue;
+			}
+
+			const registrationKey = `${i}:${seqStr}`;
+			rows.push({
+				registrationKey,
+				def,
+				seq,
+				seqStr,
+				mergedOptions,
+				resolvedTarget,
+			});
+		}
+
+		const nextKeys = new Set(rows.map((r) => r.registrationKey));
+
+		for (const [key, record] of prevRegistrations) {
+			if (!nextKeys.has(key) && record.handle.isActive) {
+				record.handle.unregister();
+			}
+		}
+
+		for (const row of rows) {
+			const { registrationKey, def, seq, mergedOptions, resolvedTarget } = row;
+
+			const existing = prevRegistrations.get(registrationKey);
+			if (existing?.handle.isActive && existing.target === resolvedTarget) {
+				nextRegistrations.set(registrationKey, existing);
+				continue;
+			}
+
+			if (existing?.handle.isActive) {
+				existing.handle.unregister();
+			}
+
+			const handle = managerRef.current.register(seq, def.callback, {
+				...mergedOptions,
+				target: resolvedTarget,
+			});
+			nextRegistrations.set(registrationKey, {
+				handle,
+				target: resolvedTarget,
+			});
+		}
+
+		registrationsRef.current = nextRegistrations;
+		// Upstream passes NO dependency array (sync registrations after every
+		// render). Octane infers omitted arrays, so `null` spells that out.
+	}, null);
+
+	useEffect(() => {
+		return () => {
+			for (const { handle } of registrationsRef.current.values()) {
+				if (handle.isActive) {
+					handle.unregister();
+				}
+			}
+			registrationsRef.current = new Map();
+		};
+	}, []);
+
+	for (let i = 0; i < definitions.length; i++) {
+		const def = definitions[i]!;
+		const seqStr = sequenceStrings[i]!;
+		const registrationKey = `${i}:${seqStr}`;
+		const handle = registrationsRef.current.get(registrationKey)?.handle;
+
+		if (handle?.isActive && def.sequence.length > 0) {
+			handle.callback = def.callback;
+			const mergedOptions = {
+				...defaultOptions,
+				...commonOptions,
+				...def.options,
+			} as UseHotkeySequenceOptions;
+			const { target: _target, ...optionsWithoutTarget } = mergedOptions;
+			handle.setOptions(optionsWithoutTarget);
+		}
+	}
+}

package/src/useHotkeys.ts

@@ -0,0 +1,186 @@
+import { useEffect, useRef } from 'octane';
+import { detectPlatform, getHotkeyManager, normalizeRegisterableHotkey } from '@tanstack/hotkeys';
+import { useDefaultHotkeysOptions } from './context';
+import { isRef } from './utils';
+import type { UseHotkeyOptions } from './useHotkey';
+import type {
+	Hotkey,
+	HotkeyCallback,
+	HotkeyRegistrationHandle,
+	RegisterableHotkey,
+} from '@tanstack/hotkeys';
+
+/**
+ * A single hotkey definition for use with `useHotkeys`.
+ */
+export interface UseHotkeyDefinition {
+	/** The hotkey string (e.g., 'Mod+S', 'Escape') or RawHotkey object */
+	hotkey: RegisterableHotkey;
+	/** The function to call when the hotkey is pressed */
+	callback: HotkeyCallback;
+	/** Per-hotkey options (merged on top of commonOptions) */
+	options?: UseHotkeyOptions;
+}
+
+/**
+ * Octane hook for registering multiple keyboard hotkeys at once.
+ *
+ * Uses the singleton HotkeyManager for efficient event handling.
+ * Accepts a dynamic array of hotkey definitions, making it safe to use
+ * with variable-length lists.
+ *
+ * Options are merged in this order:
+ * HotkeysProvider defaults < commonOptions < per-definition options
+ *
+ * Callbacks and options are synced on every render to avoid stale closures.
+ *
+ * @param hotkeys - Array of hotkey definitions to register
+ * @param commonOptions - Shared options applied to all hotkeys (overridden by per-definition options).
+ *   Per-row `enabled: false` still registers that hotkey: `HotkeyManager` suppresses execution only (the row
+ *   stays in the store and appears in TanStack Hotkeys devtools). Toggling `enabled` updates the existing handle
+ *   via `setOptions` (no unregister/re-register churn).
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   useHotkeys([
+ *     { hotkey: 'Mod+S', callback: () => save() },
+ *     { hotkey: 'Mod+Z', callback: () => undo() },
+ *     { hotkey: 'Escape', callback: () => close() },
+ *   ])
+ * }
+ * ```
+ */
+export function useHotkeys(
+	hotkeys: Array<UseHotkeyDefinition>,
+	commonOptions: UseHotkeyOptions = {},
+): void {
+	type RegistrationRecord = {
+		handle: HotkeyRegistrationHandle;
+		target: Document | HTMLElement | Window;
+	};
+
+	const defaultOptions = useDefaultHotkeysOptions().hotkey;
+	const manager = getHotkeyManager();
+	const platform = commonOptions.platform ?? defaultOptions?.platform ?? detectPlatform();
+
+	const registrationsRef = useRef<Map<string, RegistrationRecord>>(new Map());
+	const hotkeysRef = useRef(hotkeys);
+	const hotkeyStringsRef = useRef<Array<Hotkey>>([]);
+	const commonOptionsRef = useRef(commonOptions);
+	const defaultOptionsRef = useRef(defaultOptions);
+	const managerRef = useRef(manager);
+
+	const hotkeyStrings = hotkeys.map((def) => normalizeRegisterableHotkey(def.hotkey, platform));
+
+	hotkeysRef.current = hotkeys;
+	hotkeyStringsRef.current = hotkeyStrings;
+	commonOptionsRef.current = commonOptions;
+	defaultOptionsRef.current = defaultOptions;
+	managerRef.current = manager;
+
+	useEffect(() => {
+		const prevRegistrations = registrationsRef.current;
+		const nextRegistrations = new Map<string, RegistrationRecord>();
+
+		const rows: Array<{
+			registrationKey: string;
+			def: (typeof hotkeysRef.current)[number];
+			hotkeyStr: Hotkey;
+			mergedOptions: UseHotkeyOptions;
+			resolvedTarget: Document | HTMLElement | Window;
+		}> = [];
+
+		for (let i = 0; i < hotkeysRef.current.length; i++) {
+			const def = hotkeysRef.current[i]!;
+			const hotkeyStr = hotkeyStringsRef.current[i]!;
+			const mergedOptions = {
+				...defaultOptionsRef.current,
+				...commonOptionsRef.current,
+				...def.options,
+			} as UseHotkeyOptions;
+
+			const resolvedTarget = isRef(mergedOptions.target)
+				? mergedOptions.target.current
+				: (mergedOptions.target ?? (typeof document !== 'undefined' ? document : null));
+
+			if (!resolvedTarget) {
+				continue;
+			}
+
+			const registrationKey = `${i}:${hotkeyStr}`;
+			rows.push({
+				registrationKey,
+				def,
+				hotkeyStr,
+				mergedOptions,
+				resolvedTarget,
+			});
+		}
+
+		const nextKeys = new Set(rows.map((r) => r.registrationKey));
+
+		for (const [key, record] of prevRegistrations) {
+			if (!nextKeys.has(key) && record.handle.isActive) {
+				record.handle.unregister();
+			}
+		}
+
+		for (const row of rows) {
+			const { registrationKey, def, hotkeyStr, mergedOptions, resolvedTarget } = row;
+
+			const existing = prevRegistrations.get(registrationKey);
+			if (existing?.handle.isActive && existing.target === resolvedTarget) {
+				nextRegistrations.set(registrationKey, existing);
+				continue;
+			}
+
+			if (existing?.handle.isActive) {
+				existing.handle.unregister();
+			}
+
+			const handle = managerRef.current.register(hotkeyStr, def.callback, {
+				...mergedOptions,
+				target: resolvedTarget,
+			});
+			nextRegistrations.set(registrationKey, {
+				handle,
+				target: resolvedTarget,
+			});
+		}
+
+		registrationsRef.current = nextRegistrations;
+		// Upstream passes NO dependency array (sync registrations after every
+		// render). Octane infers omitted arrays, so `null` spells that out.
+	}, null);
+
+	useEffect(() => {
+		return () => {
+			for (const { handle } of registrationsRef.current.values()) {
+				if (handle.isActive) {
+					handle.unregister();
+				}
+			}
+			registrationsRef.current = new Map();
+		};
+	}, []);
+
+	// Sync callbacks and options on EVERY render (outside useEffect)
+	for (let i = 0; i < hotkeys.length; i++) {
+		const def = hotkeys[i]!;
+		const hotkeyStr = hotkeyStrings[i]!;
+		const registrationKey = `${i}:${hotkeyStr}`;
+		const handle = registrationsRef.current.get(registrationKey)?.handle;
+
+		if (handle?.isActive) {
+			handle.callback = def.callback;
+			const mergedOptions = {
+				...defaultOptions,
+				...commonOptions,
+				...def.options,
+			} as UseHotkeyOptions;
+			const { target: _target, ...optionsWithoutTarget } = mergedOptions;
+			handle.setOptions(optionsWithoutTarget);
+		}
+	}
+}

package/src/useKeyHold.ts

@@ -0,0 +1,39 @@
+import { getKeyStateTracker } from '@tanstack/hotkeys';
+import type { IndividualKey } from '@tanstack/hotkeys';
+import { useSelectorSlot } from './internal';
+
+const keyHoldSlot = Symbol.for('@octanejs/tanstack-hotkeys:useKeyHold');
+
+/**
+ * Octane hook that returns whether a specific key is currently being held.
+ *
+ * This hook uses `useSelector` from `@octanejs/tanstack-store` to subscribe
+ * to the global KeyStateTracker and uses a selector to determine if
+ * the specified key is held.
+ *
+ * @param key - The key to check (e.g., 'Shift', 'Control', 'A')
+ * @returns True if the key is currently held down
+ *
+ * @example
+ * ```tsx
+ * function ShiftIndicator() {
+ *   const isShiftHeld = useKeyHold('Shift')
+ *
+ *   return (
+ *     <div style={{ opacity: isShiftHeld ? 1 : 0.5 }}>
+ *       {isShiftHeld ? 'Shift is pressed!' : 'Press Shift'}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useKeyHold(key: IndividualKey): boolean {
+	const tracker = getKeyStateTracker();
+	const normalizedKey = key.toLowerCase();
+
+	return useSelectorSlot(
+		tracker.store,
+		(state) => state.heldKeys.some((heldKey) => heldKey.toLowerCase() === normalizedKey),
+		keyHoldSlot,
+	);
+}

package/src/utils.ts

@@ -0,0 +1,14 @@
+/**
+ * A React-19-style ref object shape (Octane refs are ordinary objects with a
+ * mutable `current`).
+ */
+export interface RefObjectLike<T> {
+	current: T;
+}
+
+/**
+ * Type guard to check if a value is a ref-like object.
+ */
+export function isRef(value: unknown): value is RefObjectLike<HTMLElement | null> {
+	return value !== null && typeof value === 'object' && 'current' in value;
+}