@omercnet/paseo-shared-browser 1.2.2 → 2.0.0-next.249.1

package/client/browser-canvas-viewport-web.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { configureBrowserCanvasWebScrolling } from "./browser-canvas-viewport-web";
+
+describe("local web browser viewport overflow", () => {
+  it("enables both overflow axes on the same public scroll node, preserving Actual offsets", () => {
+    const node = {
+      style: { overflowX: "hidden", overflowY: "auto" },
+      scrollLeft: 300,
+      scrollTop: 150,
+    };
+    configureBrowserCanvasWebScrolling({ getScrollableNode: () => node }, "actual", true);
+    expect(node).toEqual({
+      style: { overflowX: "auto", overflowY: "auto" },
+      scrollLeft: 300,
+      scrollTop: 150,
+    });
+  });
+
+  it("hides overflow and resets both local offsets when returning to Fit", () => {
+    const node = {
+      style: { overflowX: "auto", overflowY: "auto" },
+      scrollLeft: 300,
+      scrollTop: 150,
+    };
+    configureBrowserCanvasWebScrolling({ getScrollableNode: () => node }, "fit", true);
+    expect(node).toEqual({
+      style: { overflowX: "hidden", overflowY: "hidden" },
+      scrollLeft: 0,
+      scrollTop: 0,
+    });
+  });
+
+  it("retains an Actual observation position when local panning is disabled", () => {
+    const node = {
+      style: { overflowX: "auto", overflowY: "auto" },
+      scrollLeft: 300,
+      scrollTop: 150,
+    };
+    configureBrowserCanvasWebScrolling({ getScrollableNode: () => node }, "actual", false);
+    expect(node).toEqual({
+      style: { overflowX: "hidden", overflowY: "hidden" },
+      scrollLeft: 300,
+      scrollTop: 150,
+    });
+  });
+
+  it("uses the documented native host fallback while preserving the handle receiver", () => {
+    const node = { style: { overflowX: "", overflowY: "" }, scrollLeft: 0, scrollTop: 0 };
+    const handle = {
+      node,
+      getScrollableNode: () => null,
+      getNativeScrollRef() {
+        return this.node;
+      },
+    };
+    configureBrowserCanvasWebScrolling(handle, "actual", true);
+    expect(node.style).toEqual({ overflowX: "auto", overflowY: "auto" });
+  });
+
+  it("ignores missing, disappearing and non-DOM platform refs without changing unrelated nodes", () => {
+    expect(() => configureBrowserCanvasWebScrolling(null, "actual", true)).not.toThrow();
+    expect(() =>
+      configureBrowserCanvasWebScrolling({ getScrollableNode: () => 42 }, "actual", true),
+    ).not.toThrow();
+    expect(() =>
+      configureBrowserCanvasWebScrolling(
+        {
+          getScrollableNode: () => {
+            throw new Error("Detached");
+          },
+        },
+        "actual",
+        true,
+      ),
+    ).not.toThrow();
+  });
+});

package/client/browser-canvas-viewport-web.ts

@@ -0,0 +1,63 @@
+/**
+ * Web-only overflow adapter for the public React Native ScrollView host. A single
+ * DOM scroll node keeps both native desktop scrollbars at the viewer's edges.
+ * Only local overflow/offsets are changed; child remote-input listeners are untouched.
+ */
+import type { BrowserCanvasDisplayMode } from "./browser-canvas-layout";
+
+interface WebScrollNode {
+  style: { overflowX: string; overflowY: string };
+  scrollLeft: number;
+  scrollTop: number;
+}
+
+export interface BrowserCanvasScrollHandle {
+  getScrollableNode?(): unknown;
+  getNativeScrollRef?(): unknown;
+}
+
+/**
+ * Apply public ScrollView's second overflow axis before paint. Fit resets both
+ * offsets without replacing children. An unavailable/non-web host is a no-op.
+ * Actual disabled panning retains its previous observation offset.
+ */
+export function configureBrowserCanvasWebScrolling(
+  handle: BrowserCanvasScrollHandle | null,
+  mode: BrowserCanvasDisplayMode,
+  localPanEnabled: boolean,
+): void {
+  if (!handle) return;
+  const node = readScrollNode(handle);
+  if (!node) return;
+
+  const overflow = mode === "actual" && localPanEnabled ? "auto" : "hidden";
+  node.style.overflowX = overflow;
+  node.style.overflowY = overflow;
+  if (mode === "fit") {
+    node.scrollLeft = 0;
+    node.scrollTop = 0;
+  }
+}
+
+/** Prefer the documented scrollable host; tolerate platform refs that expose only the native scroll ref. */
+function readScrollNode(handle: BrowserCanvasScrollHandle): WebScrollNode | null {
+  for (const read of [handle.getScrollableNode, handle.getNativeScrollRef]) {
+    if (!read) continue;
+    try {
+      const candidate: unknown = read.call(handle);
+      if (!candidate || typeof candidate !== "object") continue;
+      const node = candidate as Partial<WebScrollNode>;
+      if (
+        !node.style ||
+        typeof node.style.overflowX !== "string" ||
+        typeof node.style.overflowY !== "string"
+      )
+        continue;
+      if (typeof node.scrollLeft !== "number" || typeof node.scrollTop !== "number") continue;
+      return node as WebScrollNode;
+    } catch {
+      // A disappearing host must not break frame rendering or input cleanup.
+    }
+  }
+  return null;
+}

package/client/browser-canvas-viewport.tsx

@@ -0,0 +1,152 @@
+/**
+ * Stable local scroll container for browser frames and their input overlay.
+ * Wrappers and children never change identity when Fit/Actual changes, preserving
+ * decoded frame slots and refs. Only Actual enables local scrolling. The parent
+ * cancels active remote input before changing geometry and owns overlay authority.
+ */
+import { type ReactNode, type Ref, useLayoutEffect, useRef } from "react";
+import {
+  type LayoutChangeEvent,
+  Platform,
+  ScrollView,
+  type StyleProp,
+  StyleSheet,
+  View,
+  type ViewStyle,
+} from "react-native";
+import type { FrameSize } from "../shared/browser";
+import type { BrowserCanvasDisplayMode } from "./browser-canvas-layout";
+import { configureBrowserCanvasWebScrolling } from "./browser-canvas-viewport-web";
+
+export interface BrowserCanvasViewportProps {
+  children: ReactNode;
+  /** Frame wrapper from getBrowserCanvasLayout, measured in local logical pixels. */
+  contentSize: FrameSize;
+  mode?: BrowserCanvasDisplayMode;
+  /** Desktop permits local scrollbars; native observation permits pan, remote control does not. */
+  localPanEnabled: boolean;
+  onLayout(event: LayoutChangeEvent): void;
+  style?: StyleProp<ViewStyle>;
+  viewportRef?: Ref<View>;
+  contentRef?: Ref<View>;
+}
+
+const styles = StyleSheet.create({
+  viewport: { flex: 1, minWidth: 0, minHeight: 0, overflow: "hidden" },
+  scroll: { flex: 1 },
+  horizontalContent: { height: "100%" },
+  vertical: { height: "100%" },
+  content: { position: "relative" },
+});
+
+/** Keep the frame coordinate origin inside the scrolling content, rather than the clipped viewport. */
+export function BrowserCanvasViewport({
+  children,
+  contentSize,
+  mode = "fit",
+  localPanEnabled,
+  onLayout,
+  style,
+  viewportRef,
+  contentRef,
+}: BrowserCanvasViewportProps) {
+  const horizontalRef = useRef<ScrollView>(null);
+  const verticalRef = useRef<ScrollView>(null);
+  const actual = mode === "actual";
+  const scrollEnabled = actual && localPanEnabled;
+  const web = Platform.OS === "web";
+  // Center a fitting Actual frame in the scrollport, not a spacer sized from
+  // the outer pane. A scrollbar on one axis must not create overflow on the
+  // other. Minimums keep overflowing frames reachable from origin zero.
+  const actualContent = {
+    flexGrow: 1,
+    alignItems: "center" as const,
+    justifyContent: "center" as const,
+  };
+
+  useLayoutEffect(() => {
+    if (web) {
+      configureBrowserCanvasWebScrolling(horizontalRef.current, mode, localPanEnabled);
+      return;
+    }
+    if (actual) return;
+    // Reset local offsets without remounting either frame-buffer layer. A hidden
+    // Actual offset must not shift Fit's overlay away from its displayed pixels.
+    horizontalRef.current?.scrollTo({ x: 0, y: 0, animated: false });
+    verticalRef.current?.scrollTo({ x: 0, y: 0, animated: false });
+  }, [actual, mode, localPanEnabled, web, contentSize.width, contentSize.height]);
+
+  const content = (
+    <View ref={contentRef} style={[styles.content, contentSize]}>
+      {children}
+    </View>
+  );
+
+  if (web) {
+    return (
+      <View ref={viewportRef} style={[styles.viewport, style]} onLayout={onLayout}>
+        <ScrollView
+          ref={horizontalRef}
+          style={styles.scroll}
+          contentContainerStyle={
+            actual
+              ? [
+                  actualContent,
+                  {
+                    minWidth: contentSize.width,
+                    minHeight: contentSize.height,
+                  },
+                ]
+              : contentSize
+          }
+          scrollEnabled={scrollEnabled}
+          showsHorizontalScrollIndicator={scrollEnabled}
+          showsVerticalScrollIndicator={scrollEnabled}
+          keyboardShouldPersistTaps="always"
+          removeClippedSubviews={false}
+        >
+          {content}
+        </ScrollView>
+      </View>
+    );
+  }
+
+  return (
+    <View ref={viewportRef} style={[styles.viewport, style]} onLayout={onLayout}>
+      <ScrollView
+        ref={horizontalRef}
+        horizontal
+        style={styles.scroll}
+        contentContainerStyle={
+          actual
+            ? [styles.horizontalContent, actualContent, { minWidth: contentSize.width }]
+            : [styles.horizontalContent, { width: contentSize.width }]
+        }
+        scrollEnabled={scrollEnabled}
+        showsHorizontalScrollIndicator={scrollEnabled}
+        nestedScrollEnabled
+        directionalLockEnabled={false}
+        keyboardShouldPersistTaps="always"
+        removeClippedSubviews={false}
+      >
+        <ScrollView
+          ref={verticalRef}
+          style={[styles.vertical, { width: contentSize.width }]}
+          contentContainerStyle={
+            actual
+              ? [actualContent, { minHeight: contentSize.height }]
+              : { height: contentSize.height }
+          }
+          scrollEnabled={scrollEnabled}
+          showsVerticalScrollIndicator={scrollEnabled}
+          nestedScrollEnabled
+          directionalLockEnabled={false}
+          keyboardShouldPersistTaps="always"
+          removeClippedSubviews={false}
+        >
+          {content}
+        </ScrollView>
+      </ScrollView>
+    </View>
+  );
+}

package/client/browser-capture-cadence.test.ts

@@ -0,0 +1,9 @@
+import { expect, it } from "vitest";
+import { browserCaptureInterval } from "./browser-capture-cadence";
+
+it("keeps idle/hover polling bounded and only accelerates actual ready input", () => {
+  expect(browserCaptureInterval("ready", false)).toBe(250);
+  expect(browserCaptureInterval("ready", true)).toBe(100);
+  expect(browserCaptureInterval("starting", true)).toBe(1_500);
+  expect(browserCaptureInterval(undefined, false)).toBe(1_500);
+});

package/client/browser-capture-cadence.ts

@@ -0,0 +1,6 @@
+/** Single-flight capture cadence; active input improves playback without changing image quality. */
+export function browserCaptureInterval(status: string | undefined, activeInput: boolean): number {
+  if (status !== "ready") return 1_500;
+  if (activeInput) return 100;
+  return 250;
+}

package/client/browser-capture-density-controls.tsx

@@ -0,0 +1,75 @@
+/** Controller-only physical capture density, independent of CSS resolution and emulation. */
+import type { PluginHostProps } from "@getpaseo/plugin/client";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+import { canUseCaptureDensity } from "../shared/browser";
+import { MAX_VIEWPORT } from "../shared/viewport-limits";
+import type { CaptureDensityMode } from "./browser-auto-capture-density";
+
+interface Props {
+  theme: PluginHostProps["theme"];
+  density: number;
+  mode: CaptureDensityMode;
+  viewport: { width: number; height: number } | null;
+  disabled: boolean;
+  onChange(value: CaptureDensityMode): void;
+}
+const styles = StyleSheet.create({
+  group: { gap: 8 },
+  heading: { fontSize: 11, fontWeight: "600" },
+  choice: { minHeight: 44, padding: 12, borderWidth: 1, borderRadius: 8 },
+  label: { fontSize: 13, fontWeight: "600" },
+  detail: { fontSize: 11 },
+});
+
+/** Selection reflects actual state, including a preset whose density was changed independently. */
+export function BrowserCaptureDensityControls(props: Props) {
+  const colors = props.theme.colors;
+  return (
+    <View style={styles.group}>
+      <Text style={[styles.heading, { color: colors.foregroundMuted }]}>Capture density</Text>
+      {(["auto", 1, 2] as const).map((density) => {
+        const supported =
+          props.viewport !== null &&
+          (density === "auto" || canUseCaptureDensity(props.viewport, density));
+        const disabled = props.disabled || !supported;
+        const selected = props.mode === density;
+        let label = `${density}×`;
+        if (density === "auto") {
+          label = selected ? `Auto (${props.density}×)` : "Auto";
+        }
+        return (
+          <Pressable
+            key={density}
+            accessibilityRole="button"
+            accessibilityLabel={`Capture density: ${label}`}
+            accessibilityState={{ selected, disabled }}
+            disabled={disabled}
+            onPress={() => {
+              if (!disabled) props.onChange(density);
+            }}
+            style={({ pressed }) => [
+              styles.choice,
+              {
+                borderColor: selected ? colors.accent : colors.border,
+                backgroundColor: selected ? colors.surface2 : colors.surface1,
+                opacity: disabled ? 0.45 : pressed ? 0.72 : 1,
+              },
+            ]}
+          >
+            <Text style={[styles.label, { color: colors.foreground }]}>{label}</Text>
+          </Pressable>
+        );
+      })}
+      <Text style={[styles.detail, { color: colors.foregroundMuted }]}>
+        Auto matches the displayed size and screen density up to 2× while controlling. Higher
+        density uses more bandwidth.
+      </Text>
+      {props.viewport && !canUseCaptureDensity(props.viewport, 2) ? (
+        <Text style={[styles.detail, { color: colors.foregroundMuted }]}>
+          2× requires a page width of {Math.floor(MAX_VIEWPORT.width / 2)} or less and a height of{" "}
+          {Math.floor(MAX_VIEWPORT.height / 2)} or less.
+        </Text>
+      ) : null}
+    </View>
+  );
+}

package/client/browser-chrome.tsx

@@ -0,0 +1,234 @@
+/** Public themed panel controls and notices. Leaves own only focus/hover styling, never browser authority. */
+import type { PluginWorkspacePanelProps } from "@getpaseo/plugin/client";
+import { Icon, TextInput } from "@getpaseo/plugin/client/react-native";
+import { type ReactNode, useCallback, useState } from "react";
+import {
+  ActivityIndicator,
+  Pressable,
+  type StyleProp,
+  Text,
+  type TextInputProps,
+  type TextStyle,
+  View,
+  type ViewStyle,
+} from "react-native";
+import { ControlButton, type ControlButtonStyles } from "./browser-control-button";
+import { setBrowserControlTooltip } from "./browser-control-tooltip-web";
+import { DIMENSION } from "./browser-panel-styles";
+
+type Theme = PluginWorkspacePanelProps["theme"];
+
+export { ControlButton } from "./browser-control-button";
+
+interface FieldStyles {
+  field: TextStyle;
+  fieldFocused: TextStyle;
+  fieldDisabled: TextStyle;
+}
+
+interface ErrorNoticeStyles extends ControlButtonStyles {
+  errorRow: ViewStyle;
+  errorText: TextStyle;
+}
+
+interface CanvasPlaceholderStyles {
+  canvasState: ViewStyle;
+  canvasTitle: TextStyle;
+  canvasDetail: TextStyle;
+}
+
+interface ChromeIconButtonStyles {
+  chromeIconButton: ViewStyle;
+  chromeIconButtonHovered: ViewStyle;
+  chromeIconButtonPressed: ViewStyle;
+  chromeIconButtonDisabled: ViewStyle;
+}
+
+/** Themed button leaf using public SDK/RN primitives. */
+export function ChromeIconButton({
+  styles,
+  theme,
+  label,
+  icon,
+  iconNode,
+  selected = false,
+  expanded,
+  disabled = false,
+  onPress,
+}: {
+  styles: ChromeIconButtonStyles;
+  theme: Theme;
+  label: string;
+  icon: string;
+  iconNode?: ReactNode;
+  expanded?: boolean;
+  selected?: boolean;
+  disabled?: boolean;
+  onPress(): void;
+}) {
+  const [hovered, setHovered] = useState(false);
+  const tooltipRef = useCallback((node: unknown) => setBrowserControlTooltip(node, label), [label]);
+  return (
+    <Pressable
+      ref={tooltipRef}
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      accessibilityState={{ disabled, selected, ...(expanded === undefined ? {} : { expanded }) }}
+      disabled={disabled}
+      onHoverIn={() => setHovered(true)}
+      onHoverOut={() => setHovered(false)}
+      onPress={onPress}
+      style={({ pressed }) => [
+        styles.chromeIconButton,
+        hovered ? styles.chromeIconButtonHovered : null,
+        pressed ? styles.chromeIconButtonPressed : null,
+        disabled ? styles.chromeIconButtonDisabled : null,
+      ]}
+    >
+      {iconNode ?? (
+        <Icon
+          name={icon}
+          size={16}
+          color={selected ? theme.colors.accent : theme.colors.foregroundMuted}
+        />
+      )}
+    </Pressable>
+  );
+}
+
+interface FieldProps {
+  styles: FieldStyles;
+  theme: Theme;
+  value: string;
+  accessibilityLabel: string;
+  placeholder?: string;
+  editable?: boolean;
+  /** Read-only information can stay legible without implying it is editable. */
+  dimWhenReadOnly?: boolean;
+  maxLength?: number;
+  keyboardType?: TextInputProps["keyboardType"];
+  inputMode?: TextInputProps["inputMode"];
+  returnKeyType?: TextInputProps["returnKeyType"];
+  selectTextOnFocus?: boolean;
+  style?: StyleProp<TextStyle>;
+  onChangeText(value: string): void;
+  onSubmit?(): void;
+  onFocus?(): void;
+  onBlur?(): void;
+}
+
+/** Themed panel field leaf using public SDK/RN primitives. */
+export function Field({
+  styles,
+  theme,
+  value,
+  accessibilityLabel,
+  placeholder,
+  editable = true,
+  dimWhenReadOnly = true,
+  maxLength,
+  keyboardType,
+  inputMode,
+  returnKeyType,
+  selectTextOnFocus,
+  style,
+  onChangeText,
+  onSubmit,
+  onFocus,
+  onBlur,
+}: FieldProps) {
+  const [focused, setFocused] = useState(false);
+  return (
+    <TextInput
+      accessibilityLabel={accessibilityLabel}
+      autoCapitalize="none"
+      autoCorrect={false}
+      spellCheck={false}
+      editable={editable}
+      keyboardType={keyboardType}
+      inputMode={inputMode}
+      maxLength={maxLength}
+      onBlur={() => {
+        setFocused(false);
+        onBlur?.();
+      }}
+      onChangeText={onChangeText}
+      onFocus={() => {
+        setFocused(true);
+        onFocus?.();
+      }}
+      onSubmitEditing={onSubmit}
+      placeholder={placeholder}
+      placeholderTextColor={theme.colors.foregroundMuted}
+      returnKeyType={returnKeyType}
+      selectionColor={theme.colors.accent}
+      selectTextOnFocus={selectTextOnFocus}
+      style={[
+        styles.field,
+        style,
+        focused ? styles.fieldFocused : null,
+        !editable && dimWhenReadOnly ? styles.fieldDisabled : null,
+      ]}
+      value={value}
+    />
+  );
+}
+
+/** Themed panel errornotice leaf using public SDK/RN primitives. */
+export function ErrorNotice({
+  styles,
+  theme,
+  message,
+  action,
+  onAction,
+  actionDisabled = false,
+}: {
+  styles: ErrorNoticeStyles;
+  theme: Theme;
+  message: string;
+  action?: string | undefined;
+  onAction?: (() => void) | undefined;
+  actionDisabled?: boolean;
+}) {
+  return (
+    <View accessibilityRole="alert" style={styles.errorRow}>
+      <Icon name="CircleAlert" size={DIMENSION.icon} color={theme.colors.statusDanger} />
+      <Text style={styles.errorText}>{message}</Text>
+      {action && onAction ? (
+        <ControlButton
+          styles={styles}
+          theme={theme}
+          label={action}
+          disabled={actionDisabled}
+          onPress={onAction}
+        />
+      ) : null}
+    </View>
+  );
+}
+
+/** Themed panel canvasplaceholder leaf using public SDK/RN primitives. */
+export function CanvasPlaceholder({
+  styles,
+  theme,
+  title,
+  detail,
+  loading = false,
+  children,
+}: {
+  styles: CanvasPlaceholderStyles;
+  theme: Theme;
+  title: string;
+  detail: string;
+  loading?: boolean;
+  children?: ReactNode;
+}) {
+  return (
+    <View style={styles.canvasState}>
+      {loading ? <ActivityIndicator color={theme.colors.accent} /> : null}
+      <Text style={styles.canvasTitle}>{title}</Text>
+      <Text style={styles.canvasDetail}>{detail}</Text>
+      {children}
+    </View>
+  );
+}