feat(store): expose reactive canUndo/canRedo getters on useTravelStore controls (#13)

* feat(store): expose reactive canUndo/canRedo getters on useTravelStore controls

`controls.canBack()` / `canForward()` read during render (e.g. the documented
`disabled={!controls.canBack()}` pattern) freeze under the React Compiler, which
memoises the method call on the stable `controls` reference. Expose `canUndo` /
`canRedo` as getters instead — like the existing `position` getter, property reads
are re-evaluated every render and stay reactive. `controls` keeps a stable identity
and the existing `canBack()` / `canForward()` methods are unchanged.

* fix(store): keep controls own-enumerable, add useTravel canUndo/canRedo + docs

Author: glowforever96

README.md

@@ -81,14 +81,11 @@ export function Counter() {
         Increment
       </button>
 
-      <button onClick={() => controls.back()} disabled={!controls.canBack()}>
+      <button onClick={() => controls.back()} disabled={!controls.canUndo}>
         Undo
       </button>
 
-      <button
-        onClick={() => controls.forward()}
-        disabled={!controls.canForward()}
-      >
+      <button onClick={() => controls.forward()} disabled={!controls.canRedo}>
         Redo
       </button>
 
@@ -157,8 +154,10 @@ Common tuple members:
 | `controls.go(position)`     | `(position: number) => void` | Jump to a specific history position                                         |
 | `controls.reset()`          | `() => void`                 | Reset to the initial state and clear history                                |
 | `controls.rebase()`         | `() => void`                 | Make the current state the new baseline and discard past and future history |
-| `controls.canBack()`        | `() => boolean`              | Whether undo is possible                                                    |
-| `controls.canForward()`     | `() => boolean`              | Whether redo is possible                                                    |
+| `controls.canBack()`        | `() => boolean`              | Imperative predicate — whether undo is possible (use in event handlers)     |
+| `controls.canForward()`     | `() => boolean`              | Imperative predicate — whether redo is possible (use in event handlers)     |
+| `controls.canUndo`          | `boolean`                    | Render-safe reactive flag — whether undo is possible (read during render)   |
+| `controls.canRedo`          | `boolean`                    | Render-safe reactive flag — whether redo is possible (read during render)   |
 
 When `autoArchive: false`, the controls also include:
 
@@ -167,6 +166,15 @@ When `autoArchive: false`, the controls also include:
 | `controls.archive()`    | `() => void`    | Commit the current working state as the next undo step |
 | `controls.canArchive()` | `() => boolean` | Whether there are unarchived changes                   |
 
+#### Checking undo/redo availability: getters vs methods
+
+`canUndo` / `canRedo` are reactive **getters** and `canBack()` / `canForward()` are **methods**. They report the same thing, but are meant for different contexts:
+
+- **During render** (e.g. `disabled={!controls.canUndo}`), use the `canUndo` / `canRedo` getters. They are re-read on every render, so they stay correct — including under the [React Compiler](https://react.dev/learn/react-compiler), which memoises method calls on the stable `controls` reference and would otherwise freeze `controls.canBack()` at its first-render value.
+- **In event handlers or outside render** (e.g. `onClick={() => controls.canBack() && controls.back()}`), the `canBack()` / `canForward()` methods are fine.
+
+The methods are kept for backward compatibility and imperative use; the getters are the render-safe form.
+
 ### `useTravelStore(travels)`
 
 Subscribes React to an existing immutable `Travels` instance without creating a new store.
@@ -198,7 +206,7 @@ export function Counter() {
       >
         Increment
       </button>
-      <button onClick={() => controls.back()} disabled={!controls.canBack()}>
+      <button onClick={() => controls.back()} disabled={!controls.canUndo}>
         Undo
       </button>
     </div>

src/index.ts

@@ -13,6 +13,14 @@ import { useSyncExternalStore } from 'use-sync-external-store/shim';
 
 export type { TravelPatches };
 
+/** Adds reactive `canUndo` / `canRedo` availability flags to a controls type. */
+type WithUndoRedoFlags<C> = C & {
+  /** Whether undo is possible. Render-safe reactive getter — read this during render. */
+  readonly canUndo: boolean;
+  /** Whether redo is possible. Render-safe reactive getter — read this during render. */
+  readonly canRedo: boolean;
+};
+
 type Result<
   S,
   F extends boolean,
@@ -21,9 +29,11 @@ type Result<
 > = [
   Value<S, F>,
   (updater: Updater<S>) => void,
-  A extends false
-    ? RebasableManualTravelsControls<S, F, P>
-    : RebasableTravelsControls<S, F, P>,
+  WithUndoRedoFlags<
+    A extends false
+      ? RebasableManualTravelsControls<S, F, P>
+      : RebasableTravelsControls<S, F, P>
+  >,
 ];
 
 type StoreControls<
@@ -35,6 +45,14 @@ type StoreControls<
   ? RebasableTravelsControls<S, F, P>
   : RebasableManualTravelsControls<S, F, P>;
 
+/** {@link StoreControls} plus reactive `canUndo` / `canRedo` flags. */
+type StoreControlsWithFlags<
+  S,
+  F extends boolean,
+  A extends boolean,
+  P extends PatchesOption = {},
+> = WithUndoRedoFlags<StoreControls<S, F, A, P>>;
+
 /**
  * Creates a component-scoped {@link Travels} instance with undo/redo support and returns its reactive API.
  *
@@ -54,7 +72,11 @@ type StoreControls<
  */
 export function useTravel<S, F extends boolean>(
   initialState: S
-): [Value<S, F>, (updater: Updater<S>) => void, RebasableTravelsControls<S, F>];
+): [
+  Value<S, F>,
+  (updater: Updater<S>) => void,
+  WithUndoRedoFlags<RebasableTravelsControls<S, F>>,
+];
 export function useTravel<
   S,
   F extends boolean,
@@ -68,7 +90,7 @@ export function useTravel<
 ): [
   Value<S, F>,
   (updater: Updater<S>) => void,
-  RebasableTravelsControls<S, F, P>,
+  WithUndoRedoFlags<RebasableTravelsControls<S, F, P>>,
 ];
 export function useTravel<
   S,
@@ -83,7 +105,7 @@ export function useTravel<
 ): [
   Value<S, F>,
   (updater: Updater<S>) => void,
-  RebasableManualTravelsControls<S, F, P>,
+  WithUndoRedoFlags<RebasableManualTravelsControls<S, F, P>>,
 ];
 export function useTravel<
   S,
@@ -191,6 +213,12 @@ export function useTravel<
       go: (position: number) => baseControls.go(position),
       canBack: () => baseControls.canBack(),
       canForward: () => baseControls.canForward(),
+      get canUndo() {
+        return baseControls.canBack();
+      },
+      get canRedo() {
+        return baseControls.canForward();
+      },
       rebase: () => baseControls.rebase(),
       // Always include archive and canArchive methods for compatibility
       // Even in autoArchive mode, archive() can be called (but will warn)
@@ -237,7 +265,11 @@ export function useTravelStore<
   P extends PatchesOption = {},
 >(
   travels: Travels<S, F, A, P>
-): [Value<S, F>, (updater: Updater<S>) => void, StoreControls<S, F, A, P>] {
+): [
+  Value<S, F>,
+  (updater: Updater<S>) => void,
+  StoreControlsWithFlags<S, F, A, P>,
+] {
   const isMutable = Boolean((travels as any)?.mutable);
 
   if (isMutable) {
@@ -254,9 +286,18 @@ export function useTravelStore<
     (updater: Updater<S>) => travels.setState(updater),
     [travels]
   );
-  const controls = useMemo<StoreControls<S, F, A, P>>(
-    () => travels.getControls(),
-    [travels]
-  );
+  const controls = useMemo<StoreControlsWithFlags<S, F, A, P>>(() => {
+    const base = travels.getControls();
+    // Copy the base's own descriptors (rather than Object.create / spread) so the existing
+    // methods stay own-enumerable, then add canUndo/canRedo as reactive getters.
+    return Object.defineProperties(
+      {},
+      {
+        ...Object.getOwnPropertyDescriptors(base),
+        canUndo: { get: () => base.canBack(), enumerable: true },
+        canRedo: { get: () => base.canForward(), enumerable: true },
+      }
+    ) as StoreControlsWithFlags<S, F, A, P>;
+  }, [travels]);
   return [state as Value<S, F>, setState, controls];
 }

test/use-travel-flags.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useTravel } from '../src/index';
+
+describe('useTravel canUndo / canRedo flags', () => {
+  it('exposes reactive canUndo / canRedo getters while keeping the methods', () => {
+    const { result } = renderHook(() => useTravel({ count: 0 }));
+
+    let [, setState, controls] = result.current;
+    expect(controls.canUndo).toBe(false);
+    expect(controls.canRedo).toBe(false);
+
+    act(() =>
+      setState((draft) => {
+        draft.count = 1;
+      })
+    );
+    [, setState, controls] = result.current;
+
+    expect(controls.canUndo).toBe(true);
+    expect(controls.canRedo).toBe(false);
+
+    expect(controls.canBack()).toBe(true);
+    expect(controls.canForward()).toBe(false);
+
+    act(() => controls.back());
+    [, , controls] = result.current;
+
+    expect(controls.canUndo).toBe(false);
+    expect(controls.canRedo).toBe(true);
+  });
+
+  it('keeps controls members own-enumerable (Object.keys / spread)', () => {
+    const { result } = renderHook(() => useTravel({ count: 0 }));
+    const [, , controls] = result.current;
+
+    const keys = Object.keys(controls);
+    for (const member of [
+      'position',
+      'getHistory',
+      'back',
+      'forward',
+      'reset',
+      'go',
+      'canBack',
+      'canForward',
+      'rebase',
+    ]) {
+      expect(keys).toContain(member);
+    }
+    expect(keys).toContain('canUndo');
+    expect(keys).toContain('canRedo');
+
+    const copy = { ...controls } as typeof controls;
+    expect(typeof copy.back).toBe('function');
+    expect(typeof copy.canBack).toBe('function');
+  });
+});

test/use-travel-store.test.ts

@@ -46,6 +46,64 @@ describe('useTravelStore', () => {
     expect(controls.getHistory()).toEqual(travels.getHistory());
   });
 
+  it('exposes reactive canUndo/canRedo getters while keeping controls stable', () => {
+    const travels = new Travels({ count: 0 });
+
+    const { result } = renderHook(() => useTravelStore(travels));
+
+    const [, setState, controlsBefore] = result.current;
+    expect(controlsBefore.canUndo).toBe(false);
+    expect(controlsBefore.canRedo).toBe(false);
+
+    act(() =>
+      setState((draft) => {
+        draft.count = 1;
+      })
+    );
+
+    const [, , controlsAfter] = result.current;
+
+    expect(controlsAfter).toBe(controlsBefore);
+    expect(controlsAfter.canUndo).toBe(true);
+    expect(controlsAfter.canRedo).toBe(false);
+    expect(controlsAfter.canBack()).toBe(true);
+
+    act(() => controlsAfter.back());
+    const [, , controlsAfterUndo] = result.current;
+
+    expect(controlsAfterUndo.canUndo).toBe(false);
+    expect(controlsAfterUndo.canRedo).toBe(true);
+  });
+
+  it('keeps existing controls members own-enumerable (Object.keys / spread)', () => {
+    const travels = new Travels({ count: 0 });
+
+    const { result } = renderHook(() => useTravelStore(travels));
+    const [, , controls] = result.current;
+
+    const keys = Object.keys(controls);
+    for (const member of [
+      'position',
+      'getHistory',
+      'back',
+      'forward',
+      'reset',
+      'go',
+      'canBack',
+      'canForward',
+      'rebase',
+    ]) {
+      expect(keys).toContain(member);
+    }
+    expect(keys).toContain('canUndo');
+    expect(keys).toContain('canRedo');
+
+    const copy = { ...controls } as typeof controls;
+    expect(typeof copy.back).toBe('function');
+    expect(typeof copy.canBack).toBe('function');
+    expect(copy.canUndo).toBe(false);
+  });
+
   it('exposes manual archive controls when autoArchive is disabled', () => {
     const travels = new Travels(
       { todos: [] as string[] },