@plannotator/ui 0.30.0 → 0.32.0

package/hooks/useViewportEnvironment.ts

@@ -0,0 +1,350 @@
+import { useEffect, useMemo, useSyncExternalStore } from 'react';
+
+export interface VisualViewportSnapshot {
+  width: number;
+  height: number;
+  offsetTop: number;
+  offsetLeft: number;
+  scale: number;
+}
+
+export interface ViewportEnvironmentInput {
+  layoutWidth: number;
+  layoutHeight: number;
+  visualViewport?: VisualViewportSnapshot | null;
+}
+
+export interface ViewportEnvironment {
+  width: number;
+  height: number;
+  offsetTop: number;
+  offsetLeft: number;
+  keyboardInset: number;
+}
+
+export interface ViewportEdgeInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export interface VisibleViewportBounds {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+const ZERO_ENVIRONMENT: ViewportEnvironment = {
+  width: 0,
+  height: 0,
+  offsetTop: 0,
+  offsetLeft: 0,
+  keyboardInset: 0,
+};
+
+const ZERO_INSETS: ViewportEdgeInsets = {
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+};
+
+const VIEWPORT_PROPERTIES = [
+  '--pn-viewport-width',
+  '--pn-viewport-height',
+  '--pn-viewport-offset-top',
+  '--pn-viewport-offset-left',
+  '--pn-keyboard-inset',
+] as const;
+
+type ViewportProperty = (typeof VIEWPORT_PROPERTIES)[number];
+
+let subscriberCount = 0;
+let stopObserving: (() => void) | null = null;
+let currentEnvironment: ViewportEnvironment | null = null;
+const environmentListeners = new Set<() => void>();
+
+function finiteOr(value: number, fallback: number): number {
+  return Number.isFinite(value) ? value : fallback;
+}
+
+function positiveOr(value: number, fallback: number): number {
+  const finite = finiteOr(value, fallback);
+  return finite > 0 ? finite : fallback;
+}
+
+function rounded(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+/**
+ * Converts the visual viewport into application-stage geometry. Pinch zoom is
+ * intentionally represented by offsets only: reshaping the app while a user
+ * zooms and pans would fight accessibility zoom. At the normal scale, browser
+ * chrome and the software keyboard are allowed to reduce the usable stage.
+ */
+export function calculateViewportEnvironment({
+  layoutWidth,
+  layoutHeight,
+  visualViewport,
+}: ViewportEnvironmentInput): ViewportEnvironment {
+  const safeLayoutWidth = Math.max(0, finiteOr(layoutWidth, 0));
+  const safeLayoutHeight = Math.max(0, finiteOr(layoutHeight, 0));
+
+  if (!visualViewport) {
+    return {
+      width: rounded(safeLayoutWidth),
+      height: rounded(safeLayoutHeight),
+      offsetTop: 0,
+      offsetLeft: 0,
+      keyboardInset: 0,
+    };
+  }
+
+  const scale = positiveOr(visualViewport.scale, 1);
+  const offsetTop = Math.max(0, finiteOr(visualViewport.offsetTop, 0));
+  const offsetLeft = Math.max(0, finiteOr(visualViewport.offsetLeft, 0));
+  const isPinchZoomed = Math.abs(scale - 1) > 0.01;
+  if (isPinchZoomed) {
+    return {
+      width: rounded(safeLayoutWidth),
+      height: rounded(safeLayoutHeight),
+      offsetTop: rounded(offsetTop),
+      offsetLeft: rounded(offsetLeft),
+      keyboardInset: 0,
+    };
+  }
+
+  const scaledWidth = positiveOr(visualViewport.width, safeLayoutWidth);
+  const scaledHeight = positiveOr(visualViewport.height, safeLayoutHeight);
+  const availableWidth = Math.max(0, safeLayoutWidth - offsetLeft);
+  const availableHeight = Math.max(0, safeLayoutHeight - offsetTop);
+  const width = safeLayoutWidth > 0 ? Math.min(scaledWidth, availableWidth) : scaledWidth;
+  const height = safeLayoutHeight > 0 ? Math.min(scaledHeight, availableHeight) : scaledHeight;
+
+  return {
+    width: rounded(Math.max(0, width)),
+    height: rounded(Math.max(0, height)),
+    offsetTop: rounded(offsetTop),
+    offsetLeft: rounded(offsetLeft),
+    keyboardInset: rounded(Math.max(0, safeLayoutHeight - offsetTop - height)),
+  };
+}
+
+/**
+ * Converts the observed viewport into usable fixed-position bounds. Padding
+ * and safe-area insets are inputs so positioning remains deterministic and
+ * testable instead of reading CSS environment variables in every overlay.
+ */
+export function calculateVisibleViewportBounds(
+  environment: ViewportEnvironment,
+  edgePadding = 0,
+  insets: Partial<ViewportEdgeInsets> = ZERO_INSETS,
+): VisibleViewportBounds {
+  const padding = Math.max(0, finiteOr(edgePadding, 0));
+  const safeInsets = {
+    top: Math.max(0, finiteOr(insets.top ?? 0, 0)),
+    right: Math.max(0, finiteOr(insets.right ?? 0, 0)),
+    bottom: Math.max(0, finiteOr(insets.bottom ?? 0, 0)),
+    left: Math.max(0, finiteOr(insets.left ?? 0, 0)),
+  };
+  const left = environment.offsetLeft + padding + safeInsets.left;
+  const top = environment.offsetTop + padding + safeInsets.top;
+  const right = Math.max(
+    left,
+    environment.offsetLeft + environment.width - padding - safeInsets.right,
+  );
+  const bottom = Math.max(
+    top,
+    environment.offsetTop + environment.height - padding - safeInsets.bottom,
+  );
+
+  return {
+    top: rounded(top),
+    right: rounded(right),
+    bottom: rounded(bottom),
+    left: rounded(left),
+    width: rounded(Math.max(0, right - left)),
+    height: rounded(Math.max(0, bottom - top)),
+  };
+}
+
+export function shouldUseExpandedComposer({
+  bounds,
+  coarsePointer,
+}: {
+  bounds: VisibleViewportBounds;
+  coarsePointer: boolean;
+}): boolean {
+  return coarsePointer || bounds.width < 640 || bounds.height < 420;
+}
+
+/** Returns whether the device's primary pointing input is coarse. */
+export function hasPrimaryCoarsePointer(targetWindow?: Window): boolean {
+  const resolvedWindow = targetWindow ?? (typeof window === 'undefined' ? undefined : window);
+  if (!resolvedWindow?.matchMedia) return false;
+  return resolvedWindow.matchMedia('(pointer: coarse)').matches;
+}
+
+function readViewportEnvironment(targetWindow: Window): ViewportEnvironment {
+  const visualViewport = targetWindow.visualViewport;
+  return calculateViewportEnvironment({
+    layoutWidth: targetWindow.innerWidth,
+    layoutHeight: targetWindow.innerHeight,
+    visualViewport: visualViewport
+      ? {
+          width: visualViewport.width,
+          height: visualViewport.height,
+          offsetTop: visualViewport.offsetTop,
+          offsetLeft: visualViewport.offsetLeft,
+          scale: visualViewport.scale,
+        }
+      : null,
+  });
+}
+
+function environmentsEqual(
+  left: ViewportEnvironment | null,
+  right: ViewportEnvironment,
+): boolean {
+  return !!left
+    && left.width === right.width
+    && left.height === right.height
+    && left.offsetTop === right.offsetTop
+    && left.offsetLeft === right.offsetLeft
+    && left.keyboardInset === right.keyboardInset;
+}
+
+function getViewportEnvironmentSnapshot(): ViewportEnvironment {
+  if (currentEnvironment) return currentEnvironment;
+  if (typeof window === 'undefined') return ZERO_ENVIRONMENT;
+  currentEnvironment = readViewportEnvironment(window);
+  return currentEnvironment;
+}
+
+function cssValues(environment: ViewportEnvironment): Record<ViewportProperty, string> {
+  return {
+    '--pn-viewport-width': `${environment.width}px`,
+    '--pn-viewport-height': `${environment.height}px`,
+    '--pn-viewport-offset-top': `${environment.offsetTop}px`,
+    '--pn-viewport-offset-left': `${environment.offsetLeft}px`,
+    '--pn-keyboard-inset': `${environment.keyboardInset}px`,
+  };
+}
+
+function startViewportEnvironmentObserver(
+  targetWindow: Window,
+  targetDocument: Document,
+): () => void {
+  const rootStyle = targetDocument.documentElement.style;
+  const previousValues = new Map<ViewportProperty, string>();
+  const writtenValues = new Map<ViewportProperty, string>();
+  for (const property of VIEWPORT_PROPERTIES) {
+    previousValues.set(property, rootStyle.getPropertyValue(property));
+  }
+
+  let animationFrame: number | null = null;
+
+  const write = () => {
+    animationFrame = null;
+    const nextEnvironment = readViewportEnvironment(targetWindow);
+    const changed = !environmentsEqual(currentEnvironment, nextEnvironment);
+    currentEnvironment = nextEnvironment;
+    const nextValues = cssValues(nextEnvironment);
+    for (const property of VIEWPORT_PROPERTIES) {
+      const nextValue = nextValues[property];
+      if (writtenValues.get(property) === nextValue) continue;
+      rootStyle.setProperty(property, nextValue);
+      writtenValues.set(property, nextValue);
+    }
+    if (changed) environmentListeners.forEach(listener => listener());
+  };
+
+  const scheduleWrite = () => {
+    if (animationFrame !== null) return;
+    animationFrame = targetWindow.requestAnimationFrame(write);
+  };
+
+  const visualViewport = targetWindow.visualViewport;
+  targetWindow.addEventListener('resize', scheduleWrite);
+  targetWindow.addEventListener('orientationchange', scheduleWrite);
+  targetWindow.addEventListener('pageshow', scheduleWrite);
+  targetDocument.addEventListener('visibilitychange', scheduleWrite);
+  visualViewport?.addEventListener('resize', scheduleWrite);
+  visualViewport?.addEventListener('scroll', scheduleWrite);
+  write();
+
+  return () => {
+    targetWindow.removeEventListener('resize', scheduleWrite);
+    targetWindow.removeEventListener('orientationchange', scheduleWrite);
+    targetWindow.removeEventListener('pageshow', scheduleWrite);
+    targetDocument.removeEventListener('visibilitychange', scheduleWrite);
+    visualViewport?.removeEventListener('resize', scheduleWrite);
+    visualViewport?.removeEventListener('scroll', scheduleWrite);
+    if (animationFrame !== null) targetWindow.cancelAnimationFrame(animationFrame);
+
+    for (const property of VIEWPORT_PROPERTIES) {
+      const previousValue = previousValues.get(property) ?? '';
+      if (previousValue) rootStyle.setProperty(property, previousValue);
+      else rootStyle.removeProperty(property);
+    }
+  };
+}
+
+function acquireViewportEnvironment(): () => void {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return () => {};
+
+  subscriberCount += 1;
+  if (subscriberCount === 1) {
+    stopObserving = startViewportEnvironmentObserver(window, document);
+  }
+
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    subscriberCount = Math.max(0, subscriberCount - 1);
+    if (subscriberCount !== 0) return;
+    stopObserving?.();
+    stopObserving = null;
+    currentEnvironment = null;
+  };
+}
+
+function subscribeViewportEnvironment(listener: () => void): () => void {
+  environmentListeners.add(listener);
+  const release = acquireViewportEnvironment();
+  return () => {
+    environmentListeners.delete(listener);
+    release();
+  };
+}
+
+/**
+ * Keeps Plannotator's shared viewport CSS properties synchronized without
+ * putting high-frequency browser geometry into React state.
+ */
+export function useViewportEnvironment(): void {
+  useEffect(() => acquireViewportEnvironment(), []);
+}
+
+/**
+ * Reactive bounds for fixed overlays. It shares the root observer and its
+ * animation-frame coalescing, so composer consumers do not add parallel
+ * Visual Viewport listeners.
+ */
+export function useVisibleViewportBounds(edgePadding = 0): VisibleViewportBounds {
+  const environment = useSyncExternalStore(
+    subscribeViewportEnvironment,
+    getViewportEnvironmentSnapshot,
+    () => ZERO_ENVIRONMENT,
+  );
+  return useMemo(
+    () => calculateVisibleViewportBounds(environment, edgePadding),
+    [edgePadding, environment],
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
@@ -10,12 +10,14 @@
     "./components/goal-setup/*": "./components/goal-setup/*.tsx",
     "./components/ImageAnnotator": "./components/ImageAnnotator/index.tsx",
     "./components/html-viewer": "./components/html-viewer/index.ts",
+    "./components/html-viewer/bridge-script": "./components/html-viewer/bridge-script.ts",
     "./components/sidebar/*": "./components/sidebar/*.tsx",
     "./components/plan-diff/*": "./components/plan-diff/*.tsx",
     "./utils/*": "./utils/*.ts",
     "./lib/*": "./lib/*.ts",
     "./hooks/*": "./hooks/*.ts",
     "./shortcuts": "./shortcuts/index.ts",
+    "./webmcp": "./webmcp/index.ts",
     "./config": "./config/index.ts",
     "./configure": "./configure.ts",
     "./theme-modes": "./components/themeModes.tsx",
@@ -31,6 +33,7 @@
     "lib",
     "shortcuts",
     "utils",
+    "webmcp",
     "assets",
     "themes",
     "sprite_package_additional",
@@ -68,7 +71,7 @@
     "@lezer/highlight": "^1.2.3",
     "@pierre/diffs": "1.3.2",
     "@plannotator/atomic-editor": "^0.8.0",
-    "@plannotator/core": "0.23.0",
+    "@plannotator/core": "0.25.0",
     "@plannotator/markdown-editor": "^0.4.0",
     "@plannotator/web-highlighter": "^0.8.1",
     "@tanstack/react-table": "^8.21.3",

package/shortcuts/index.ts

@@ -2,12 +2,15 @@ export * from './core';
 export * from './runtime';
 
 // plan-review scopes
+export { annotationModeShortcuts, useAnnotationModeShortcuts } from './plan-review/annotationMode.shortcuts';
 export { annotationToolbarShortcuts, useAnnotationToolbarShortcuts } from './plan-review/annotationToolbar.shortcuts';
 export { annotationPanelShortcuts, useAnnotationPanelShortcuts } from './plan-review/annotationPanel.shortcuts';
 export { commentPopoverShortcuts } from './plan-review/commentPopover.shortcuts';
 export { imageAnnotatorShortcuts, useImageAnnotatorShortcuts } from './plan-review/imageAnnotator.shortcuts';
 export { inputMethodShortcuts } from './plan-review/inputMethod.shortcuts';
+export { htmlAnnotateShortcuts, useHtmlAnnotateShortcuts } from './plan-review/htmlAnnotate.shortcuts';
 export { viewerShortcuts, useViewerShortcuts } from './plan-review/viewer.shortcuts';
+export { documentViewShortcuts, useDocumentViewShortcuts } from './plan-review/documentView.shortcuts';
 export {
   describeVimSelectionAction,
   isVimSelectionActionId,

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

@@ -0,0 +1,91 @@
+import { defineShortcutScope } from '../core';
+import {
+  useShortcutScope,
+  type ShortcutHandlers,
+  type UseShortcutScopeOptions,
+} from '../runtime';
+
+// Shift+digit rather than mnemonic letters: bare letters are swallowed by
+// type-to-comment, bare digits by the label picker, Mod+digit by the browser's
+// tab switching, and Mod+Shift+3/4 by macOS screenshots. Follows the toolstrip
+// left to right.
+export const annotationModeShortcuts = defineShortcutScope({
+  id: 'annotation-mode',
+  title: 'Annotation Mode',
+  shortcuts: {
+    selectMarkupMode: {
+      description: 'Markup mode',
+      bindings: ['Shift+1'],
+      section: 'Annotations',
+      hint: 'Selecting text opens the annotation toolbar.',
+      preventDefault: true,
+      displayOrder: 1,
+    },
+    selectCommentMode: {
+      description: 'Comment mode',
+      bindings: ['Shift+2'],
+      section: 'Annotations',
+      hint: 'Selecting text opens the comment editor.',
+      preventDefault: true,
+      displayOrder: 2,
+    },
+    selectRedlineMode: {
+      description: 'Redline mode',
+      bindings: ['Shift+3'],
+      section: 'Annotations',
+      hint: 'Selecting text marks it for deletion.',
+      preventDefault: true,
+      displayOrder: 3,
+    },
+    selectQuickLabelMode: {
+      description: 'Label mode',
+      bindings: ['Shift+4'],
+      section: 'Annotations',
+      hint: 'Selecting text opens the quick label picker.',
+      preventDefault: true,
+      displayOrder: 4,
+    },
+  },
+});
+
+// --- Type-to-comment capture guard (#1244 follow-up) ---
+// Shift+1..4 produce printable characters (! @ # $). While a surface's
+// type-to-comment listener owns printable keys (a selection exists and the
+// annotation toolbar is open), those characters belong to the comment being
+// started: a mode shortcut firing there both eats the character and silently
+// re-arms the mode (Shift+3 arming Redline mid-thought). The toolbar
+// registers its capture here; the scope hook refuses to dispatch while any
+// capture is held.
+let typeToCommentCaptures = 0;
+
+/**
+ * Held by AnnotationToolbar for the lifetime of its type-to-comment keydown
+ * listener. Returns a release function; releasing more than once is safe.
+ */
+export function acquireTypeToCommentCapture(): () => void {
+  typeToCommentCaptures += 1;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    typeToCommentCaptures -= 1;
+  };
+}
+
+type AnnotationModeScope = typeof annotationModeShortcuts;
+type AnnotationModeOptions = Omit<UseShortcutScopeOptions<AnnotationModeScope>, 'scope'>;
+
+export function useAnnotationModeShortcuts(options: AnnotationModeOptions): void {
+  const guarded: ShortcutHandlers<AnnotationModeScope> = {};
+  for (const actionId of Object.keys(options.handlers) as Array<keyof typeof options.handlers>) {
+    const handler = options.handlers[actionId];
+    if (!handler) continue;
+    const config = typeof handler === 'function' ? { handle: handler } : handler;
+    guarded[actionId] = {
+      ...config,
+      when: (event: KeyboardEvent) =>
+        typeToCommentCaptures === 0 && (config.when ? config.when(event) : true),
+    };
+  }
+  useShortcutScope({ scope: annotationModeShortcuts, ...options, handlers: guarded });
+}

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

@@ -0,0 +1,26 @@
+import { defineShortcutScope } from '../core';
+import { createShortcutScopeHook } from '../runtime';
+
+/**
+ * Document-chrome view commands shared by plan review and annotate mode.
+ *
+ * Focus mode is the keyboard entry point to the same view state the document
+ * card's `Focus` control drives: both side panels collapse in one press and the
+ * previous arrangement comes back on the next one.
+ */
+export const documentViewShortcuts = defineShortcutScope({
+  id: 'document-view',
+  title: 'Document View',
+  shortcuts: {
+    toggleFocusMode: {
+      description: 'Toggle focus mode',
+      bindings: ['Mod+.'],
+      section: 'View',
+      hint: 'Collapses the Contents sidebar and the right-hand panel together; press again to restore whatever was open before.',
+      displayOrder: 10,
+      preventDefault: true,
+    },
+  },
+});
+
+export const useDocumentViewShortcuts = createShortcutScopeHook(documentViewShortcuts);

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

@@ -0,0 +1,24 @@
+import { defineShortcutScope } from '../core';
+import { createShortcutScopeHook } from '../runtime';
+
+// Interact/Annotate toggle for HTML and live-app annotate surfaces. The same
+// chord is mirrored inside the sandboxed iframe by the bridge (focus usually
+// lives in there on live apps) and forwarded to the parent, so it works
+// regardless of which document owns the keyboard. No bare-letter binding:
+// bare letters belong to type-to-comment and the page itself.
+export const htmlAnnotateShortcuts = defineShortcutScope({
+  id: 'html-annotate',
+  title: 'HTML Annotate',
+  shortcuts: {
+    toggleAnnotateMode: {
+      description: 'Toggle Interact / Annotate',
+      bindings: ['Mod+Shift+A'],
+      section: 'Annotations',
+      hint: 'On HTML and live app surfaces: arm annotation capture, or hand clicks back to the page. Esc also exits Annotate.',
+      preventDefault: true,
+      displayOrder: 0,
+    },
+  },
+});
+
+export const useHtmlAnnotateShortcuts = createShortcutScopeHook(htmlAnnotateShortcuts);