@plannotator/ui 0.22.0

package/shortcuts/plan-review/goalSetup.shortcuts.ts

@@ -0,0 +1,10 @@
+import { defineShortcutScope } from '../core';
+import { createShortcutScopeHook } from '../runtime';
+
+export const goalSetupShortcuts = defineShortcutScope({
+  id: 'goal-setup-surface',
+  title: 'Goal Setup',
+  shortcuts: {},
+});
+
+export const useGoalSetupShortcuts = createShortcutScopeHook(goalSetupShortcuts);

package/shortcuts/plan-review/imageAnnotator.shortcuts.ts

@@ -0,0 +1,42 @@
+import { defineShortcutScope } from '../core';
+import { createShortcutScopeHook } from '../runtime';
+
+export const imageAnnotatorShortcuts = defineShortcutScope({
+  id: 'image-annotator',
+  title: 'Image Annotator',
+  shortcuts: {
+    penTool: {
+      description: 'Pen tool',
+      bindings: ['1'],
+      section: 'Image Annotator',
+      displayOrder: 10,
+    },
+    arrowTool: {
+      description: 'Arrow tool',
+      bindings: ['2'],
+      section: 'Image Annotator',
+      displayOrder: 20,
+    },
+    circleTool: {
+      description: 'Circle tool',
+      bindings: ['3'],
+      section: 'Image Annotator',
+      displayOrder: 30,
+    },
+    undo: {
+      description: 'Undo',
+      bindings: ['Mod+Z'],
+      section: 'Image Annotator',
+      displayOrder: 40,
+    },
+    save: {
+      description: 'Save and close annotator',
+      bindings: ['Enter', 'Escape'],
+      section: 'Image Annotator',
+      hint: 'When the image name field is focused, Escape blurs it first and Enter confirms the name; both close the annotator otherwise.',
+      displayOrder: 50,
+    },
+  },
+});
+
+export const useImageAnnotatorShortcuts = createShortcutScopeHook(imageAnnotatorShortcuts);

package/shortcuts/plan-review/inputMethod.shortcuts.ts

@@ -0,0 +1,30 @@
+import { defineShortcutScope } from '../core';
+
+// Heads-up for future migrators: these bindings (`Alt hold`, `Alt Alt`) are
+// declarative metadata for the help modal and marketing docs. They do NOT
+// dispatch through `useShortcutScope`. `Alt Alt` works via
+// `useDoubleTapShortcuts`; `Alt hold` has no shared hook yet — it's wired
+// today by the bespoke `useInputMethodSwitch` hook in
+// `packages/editor/hooks/`. See the comment block above
+// `useDoubleTapShortcuts` in `packages/ui/shortcuts/runtime.ts`.
+
+export const inputMethodShortcuts = defineShortcutScope({
+  id: 'input-method',
+  title: 'Input Method',
+  shortcuts: {
+    temporarySwitch: {
+      description: 'Temporarily switch input method',
+      bindings: ['Alt hold'],
+      section: 'Input Method',
+      hint: 'Hold Alt to switch between Select and Pinpoint, then release to revert.',
+      displayOrder: 10,
+    },
+    toggleSwitch: {
+      description: 'Toggle input method',
+      bindings: ['Alt Alt'],
+      section: 'Input Method',
+      hint: 'Double-tap Alt to switch between Select and Pinpoint until you toggle again.',
+      displayOrder: 20,
+    },
+  },
+});

package/shortcuts/plan-review/sidebar.shortcuts.ts

@@ -0,0 +1,34 @@
+import { defineShortcutScope } from '../core';
+import { createShortcutScopeHook } from '../runtime';
+
+export const annotateSidebarShortcuts = defineShortcutScope({
+  id: 'annotate-sidebar',
+  title: 'Annotate Sidebar',
+  shortcuts: {
+    toggleContents: {
+      description: 'Toggle Contents sidebar',
+      bindings: ['Mod+B'],
+      section: 'Sidebar',
+      displayOrder: 10,
+      preventDefault: true,
+    },
+    toggleFiles: {
+      description: 'Toggle Files sidebar',
+      bindings: ['Mod+Shift+B'],
+      section: 'Sidebar',
+      hint: 'Available when the Files tab is shown.',
+      displayOrder: 20,
+      preventDefault: true,
+    },
+    toggleAgentTui: {
+      description: 'Toggle Agent TUI sidebar',
+      bindings: ['Shift Shift'],
+      section: 'Sidebar',
+      hint: 'Available when the Agent control is shown.',
+      displayOrder: 30,
+      preventDefault: true,
+    },
+  },
+});
+
+export const useAnnotateSidebarShortcuts = createShortcutScopeHook(annotateSidebarShortcuts);

package/shortcuts/plan-review/viewer.shortcuts.ts

@@ -0,0 +1,24 @@
+import { defineShortcutScope } from '../core';
+import { createShortcutScopeHook } from '../runtime';
+
+export const viewerShortcuts = defineShortcutScope({
+  id: 'viewer',
+  title: 'Viewer',
+  shortcuts: {
+    copySelection: {
+      description: 'Copy selected text',
+      bindings: ['Mod+C'],
+      section: 'Annotations',
+      displayOrder: 25,
+    },
+    closeLightbox: {
+      description: 'Close image lightbox',
+      bindings: ['Escape'],
+      section: 'Annotations',
+      hint: 'Available while an image is open in the lightbox.',
+      displayOrder: 70,
+    },
+  },
+});
+
+export const useViewerShortcuts = createShortcutScopeHook(viewerShortcuts);

package/shortcuts/runtime.ts

@@ -0,0 +1,259 @@
+import { useEffect, useRef } from 'react';
+import type { ShortcutDefinition, ShortcutScopeDefinition } from './core';
+import { matchesKeyName, matchesShortcutBinding, parseDoubleTapBinding } from './core';
+
+type ShortcutActionId<TScope extends ShortcutScopeDefinition<any>> = keyof TScope['shortcuts'] & string;
+
+export interface ShortcutHandlerConfig {
+  when?: (event: KeyboardEvent) => boolean;
+  handle: (event: KeyboardEvent) => void;
+}
+
+export type ShortcutHandler = ((event: KeyboardEvent) => void) | ShortcutHandlerConfig;
+
+export type ShortcutHandlers<TScope extends ShortcutScopeDefinition<any>> = Partial<
+  Record<ShortcutActionId<TScope>, ShortcutHandler>
+>;
+
+type ShortcutEventTarget = 'window' | 'document' | EventTarget | null;
+
+export interface UseShortcutScopeOptions<TScope extends ShortcutScopeDefinition<any>> {
+  scope: TScope;
+  handlers: ShortcutHandlers<TScope>;
+  target?: ShortcutEventTarget;
+  stopOnMatch?: boolean;
+}
+
+function normalizeShortcutHandler(handler: ShortcutHandler): ShortcutHandlerConfig {
+  if (typeof handler === 'function') {
+    return { handle: handler };
+  }
+
+  return handler;
+}
+
+// TODO(migration): no cross-scope arbitration. When two scopes bind the
+// same key (e.g. `Escape` in both an outer editor scope and an inner
+// dialog scope), both `useShortcutScope` listeners fire on a single
+// keypress. Add `if (event.defaultPrevented) return false;` at the top
+// of this function once shortcut definitions consistently set
+// `preventDefault: true` (or once we flip the default). Until then,
+// callers must guard with `when` to prevent double-handling.
+export function dispatchShortcutEvent<TScope extends ShortcutScopeDefinition<any>>(
+  scope: TScope,
+  handlers: ShortcutHandlers<TScope>,
+  event: KeyboardEvent,
+  options?: { stopOnMatch?: boolean },
+): boolean {
+  const stopOnMatch = options?.stopOnMatch ?? true;
+  let handled = false;
+
+  for (const [actionId, shortcut] of Object.entries(scope.shortcuts) as Array<[
+    ShortcutActionId<TScope>,
+    ShortcutDefinition,
+  ]>) {
+    const handler = handlers[actionId];
+    if (!handler) continue;
+    if (!shortcut.bindings.some(binding => matchesShortcutBinding(event, binding))) continue;
+
+    const { when, handle } = normalizeShortcutHandler(handler);
+    if (when && !when(event)) continue;
+
+    if (shortcut.preventDefault) {
+      event.preventDefault();
+    }
+
+    handle(event);
+    handled = true;
+
+    if (stopOnMatch) {
+      return true;
+    }
+  }
+
+  return handled;
+}
+
+function getEventTarget(target: ShortcutEventTarget): EventTarget | null {
+  if (target === 'window') {
+    return typeof window === 'undefined' ? null : window;
+  }
+  if (target === 'document') {
+    return typeof document === 'undefined' ? null : document;
+  }
+  return target;
+}
+
+export function useShortcutScope<TScope extends ShortcutScopeDefinition<any>>({
+  scope,
+  handlers,
+  target = 'window',
+  stopOnMatch = true,
+}: UseShortcutScopeOptions<TScope>) {
+  const handlersRef = useRef(handlers);
+
+  useEffect(() => {
+    handlersRef.current = handlers;
+  }, [handlers]);
+
+  useEffect(() => {
+    const eventTarget = getEventTarget(target);
+    if (!eventTarget || !('addEventListener' in eventTarget)) return;
+
+    const handleKeyDown = (event: Event) => {
+      dispatchShortcutEvent(scope, handlersRef.current, event as KeyboardEvent, { stopOnMatch });
+    };
+
+    eventTarget.addEventListener('keydown', handleKeyDown as EventListener);
+    return () => {
+      eventTarget.removeEventListener('keydown', handleKeyDown as EventListener);
+    };
+  }, [scope, stopOnMatch, target]);
+}
+
+export function createShortcutScopeHook<TScope extends ShortcutScopeDefinition<any>>(scope: TScope) {
+  return function useScopedShortcutScope(options: Omit<UseShortcutScopeOptions<TScope>, 'scope'>) {
+    useShortcutScope({ scope, ...options });
+  };
+}
+
+// --- Multi-press shortcut support ---
+//
+// `useShortcutScope` only dispatches single-press bindings — anything with
+// whitespace (e.g. `"Alt Alt"`) or the `hold` token (e.g. `"Alt hold"`)
+// short-circuits in `matchesShortcutBinding`. Multi-press bindings need a
+// dedicated hook that knows their semantics:
+//
+//   - Double-tap → `useDoubleTapShortcuts` below.
+//   - Hold       → no shared hook yet; wire by hand in the consuming
+//                  component until one is built. The `Alt hold` binding in
+//                  `inputMethodShortcuts` is currently driven by the
+//                  bespoke `useInputMethodSwitch` hook in the plan editor.
+//
+// TODO: when the App.tsx migration starts touching hold semantics, add a
+// `useHoldShortcuts` here paired with a `parseHoldBinding` in core.ts so the
+// registry-driven path actually fires.
+
+// --- Double-tap shortcut support ---
+
+export type DoubleTapHandlers<TScope extends ShortcutScopeDefinition<any>> = Partial<
+  Record<ShortcutActionId<TScope>, ShortcutHandler>
+>;
+
+export interface UseDoubleTapShortcutsOptions<TScope extends ShortcutScopeDefinition<any>> {
+  scope: TScope;
+  handlers: DoubleTapHandlers<TScope>;
+  /** Max gap between two key releases to count as a double-tap (default: 300ms). */
+  window?: number;
+}
+
+/**
+ * Hook for handling double-tap shortcuts (bindings like `"Alt Alt"`).
+ *
+ * Double-tap is detected on keyup: if the same key is released twice
+ * within `window` ms, the handler fires. Regular (keydown) bindings
+ * in the same scope are ignored — use `useShortcutScope` for those.
+ */
+export function useDoubleTapShortcuts<TScope extends ShortcutScopeDefinition<any>>({
+  scope,
+  handlers,
+  window: tapWindow = 300,
+}: UseDoubleTapShortcutsOptions<TScope>) {
+  const handlersRef = useRef(handlers);
+  useEffect(() => { handlersRef.current = handlers; }, [handlers]);
+
+  useEffect(() => {
+    // Pre-parse which actions have double-tap bindings
+    const doubleTapActions: Array<{ actionId: ShortcutActionId<TScope>; keyName: string; preventDefault: boolean }> = [];
+    for (const [actionId, shortcut] of Object.entries(scope.shortcuts) as Array<[
+      ShortcutActionId<TScope>,
+      ShortcutDefinition,
+    ]>) {
+      for (const binding of shortcut.bindings) {
+        const keyName = parseDoubleTapBinding(binding);
+        if (keyName) {
+          doubleTapActions.push({ actionId, keyName, preventDefault: shortcut.preventDefault === true });
+        }
+      }
+    }
+
+    if (doubleTapActions.length === 0) return;
+
+    // Track last keyup timestamp per key
+    const lastKeyUp = new Map<string, number>();
+    // A tap only counts when the key went down and came up ALONE. Without this,
+    // any two releases of (say) Shift within the window fire the action: typing
+    // two capitalized words, extending a selection with two Shift+Clicks, or
+    // pressing a Mod+Shift+<key> chord twice. cleanPress marks a press as solo
+    // until any other key or pointer interaction intervenes.
+    const cleanPress = new Map<string, boolean>();
+    const MODIFIER_KEYS = ['Meta', 'Control', 'Alt', 'Shift'];
+
+    const invalidateSequence = () => {
+      cleanPress.clear();
+      lastKeyUp.clear();
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      let tracked = false;
+      for (const { keyName } of doubleTapActions) {
+        if (matchesKeyName(event, keyName)) {
+          tracked = true;
+          if (!event.repeat) cleanPress.set(keyName, true);
+        }
+      }
+      // Any non-tracked keydown breaks both the current press and the sequence.
+      if (!tracked) invalidateSequence();
+    };
+
+    const handleKeyUp = (event: KeyboardEvent) => {
+      for (const { actionId, keyName, preventDefault } of doubleTapActions) {
+        if (!matchesKeyName(event, keyName)) continue;
+
+        // Release with another modifier still held (Mod+Shift+B) or after a
+        // non-solo press: not a tap, and it resets the sequence.
+        const otherModifierHeld = MODIFIER_KEYS.some(
+          (m) => m !== keyName && event.getModifierState(m),
+        );
+        if (otherModifierHeld || cleanPress.get(keyName) !== true) {
+          lastKeyUp.delete(keyName);
+          cleanPress.delete(keyName);
+          continue;
+        }
+        cleanPress.delete(keyName); // release consumes the press
+
+        const handler = handlersRef.current[actionId];
+        if (!handler) continue;
+
+        const { when, handle } = normalizeShortcutHandler(handler);
+        if (when && !when(event)) continue;
+
+        const now = Date.now();
+        const prev = lastKeyUp.get(keyName) ?? 0;
+        if (now - prev < tapWindow) {
+          if (preventDefault) event.preventDefault();
+          handle(event);
+          lastKeyUp.set(keyName, 0); // reset so triple-tap doesn't re-fire
+        } else {
+          lastKeyUp.set(keyName, now);
+        }
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown, true);
+    window.addEventListener('keyup', handleKeyUp);
+    // Pointer interaction mid-press (Shift+Click selection) breaks the tap.
+    window.addEventListener('mousedown', invalidateSequence, true);
+    return () => {
+      window.removeEventListener('keydown', handleKeyDown, true);
+      window.removeEventListener('keyup', handleKeyUp);
+      window.removeEventListener('mousedown', invalidateSequence, true);
+    };
+  }, [scope, tapWindow]);
+}
+
+export function createDoubleTapShortcutsHook<TScope extends ShortcutScopeDefinition<any>>(scope: TScope) {
+  return function useScopedDoubleTap(options: Omit<UseDoubleTapShortcutsOptions<TScope>, 'scope'>) {
+    useDoubleTapShortcuts({ scope, ...options });
+  };
+}

package/sprite_package_additional/index.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Sprite Animation</title>
+    <style>
+      body {
+        display: flex;
+        justify-content: center;
+        align-items: center;
+        height: 100vh;
+        background-color: #f0f0f0;
+        margin: 0;
+      }
+      .animation {
+        width: 176px;
+        height: 96px;
+        background: url("sprite.png") left center;
+        animation: play 5s steps(24) infinite;
+        /* image-rendering: pixelated; */ /* Uncomment if resizing up */
+      }
+
+      @keyframes play {
+        to {
+          background-position: -4224px 0;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <div class="animation"></div>
+  </body>
+</html>

package/sprite_package_new/index.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Sprite Animation</title>
+    <style>
+      body {
+        display: flex;
+        justify-content: center;
+        align-items: center;
+        height: 100vh;
+        background-color: #f0f0f0;
+        margin: 0;
+      }
+      .animation {
+        width: 96px;
+        height: 96px;
+        background: url("sprite.png") left center;
+        animation: play 3s steps(12) infinite;
+        /* image-rendering: pixelated; */ /* Uncomment if resizing up */
+      }
+
+      @keyframes play {
+        to {
+          background-position: -1152px 0;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <div class="animation"></div>
+  </body>
+</html>

package/sprite_package_pulluphang/index.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Sprite Animation</title>
+    <style>
+      body {
+        display: flex;
+        justify-content: center;
+        align-items: center;
+        height: 100vh;
+        background-color: #f0f0f0;
+        margin: 0;
+      }
+      .animation {
+        width: 96px;
+        height: 96px;
+        background: url("sprite.png") left center;
+        animation: play 3s steps(24) infinite;
+        /* image-rendering: pixelated; */ /* Uncomment if resizing up */
+      }
+
+      @keyframes play {
+        to {
+          background-position: -2304px 0;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <div class="animation"></div>
+  </body>
+</html>