panelui-native 0.63.0 → 0.66.1

package/src/components/context-menu/index.tsx

@@ -4,7 +4,8 @@
  * A `Menu` hangs off a control that exists to be pressed: a ⋯ button, a toolbar
  * item, something whose whole job is to open the menu. A context menu has no
  * such control. The target is the content itself — a message, a note, a photo,
- * a row — and the actions are reached by pressing and holding it.
+ * a row — and the actions are reached by holding it, by a named accessibility
+ * action, or from the keyboard.
  *
  * ```tsx
  * <ContextMenu>
@@ -31,9 +32,9 @@
  * them. The panel is `Menu`'s panel, which is `Popover`'s, so `presentation`,
  * submenus and edge-flipping all arrive already working.
  *
- * What this component owns is the two things a menu opened on content needs and
- * a menu opened from a button does not: the long press, and where the panel
- * goes.
+ * What this component owns is what a menu opened on content needs and a menu
+ * opened from a button does not: alternate invocation paths, and where the
+ * panel goes.
  *
  * ## Anchored to the finger, not to the target
  *
@@ -73,7 +74,11 @@ import {
   type ReactElement,
   type ReactNode,
 } from 'react';
-import { View, type ViewProps } from 'react-native';
+import {
+  View,
+  type AccessibilityActionInfo,
+  type ViewProps,
+} from 'react-native';
 import { Gesture, GestureDetector } from 'react-native-gesture-handler';
 import Animated, {
   FadeOut,
@@ -95,6 +100,12 @@ import {
 import { usePopoverAnchor } from '../popover';
 import { cn } from '../../utils/cn';
 import { selectionTick } from '../../utils/haptics';
+import {
+  contextMenuAccessibilityInvocation,
+  contextMenuKeyInvocation,
+  type ContextMenuInvocation,
+  type ContextMenuKeyDownEvent,
+} from './context-menu-invocation';
 
 /**
  * How long the target is held before the menu opens.
@@ -260,7 +271,7 @@ function ContextMenuRoot({ children, ...props }: ContextMenuProps) {
 /** Which rectangle the panel is placed against. */
 export type ContextMenuAnchor = 'point' | 'target';
 
-export interface ContextMenuTriggerProps extends Omit<ViewProps, 'children'> {
+export interface ContextMenuTriggerProps extends Omit<ViewProps, 'children' | 'onKeyDown'> {
   /**
    * Classes on the wrapper the content sits in, which lays out like any other
    * view — it does not shrink to its child, because the things held are usually
@@ -280,7 +291,8 @@ export interface ContextMenuTriggerProps extends Omit<ViewProps, 'children'> {
    * Point is the default because a context menu's target is usually large, and
    * the middle of a whole message is not where the press was. Reach for
    * `target` when the target is small and list-shaped and the panel should read
-   * as lining up with it.
+   * as lining up with it. Keyboard and accessibility opens always use the target
+   * bounds, because those modalities have no pointer coordinate.
    */
   anchor?: ContextMenuAnchor;
   /** How long the hold has to last, in milliseconds. 350 by default. */
@@ -310,10 +322,17 @@ export interface ContextMenuTriggerProps extends Omit<ViewProps, 'children'> {
   haptics?: boolean;
   /** Nothing opens the menu, and the short press stops firing too. */
   disabled?: boolean;
+  /**
+   * Called first for keyboard events. Prevent the event to keep ContextMenu
+   * from handling it. Context Menu and Shift+F10 open the menu; Enter and Space
+   * mirror the trigger's accessible activation.
+   */
+  onKeyDown?: (event: ContextMenuKeyDownEvent) => void;
 }
 
 /**
- * Wraps the content and opens the menu when it is held.
+ * Wraps the content and opens the menu when held, through accessibility
+ * actions, or from the keyboard.
  *
  * The wrapper is a plain view and lays out like one, stretching as a view does
  * rather than shrinking to its child. That is the opposite of what a tooltip's
@@ -334,6 +353,14 @@ function ContextMenuTrigger({
   onPress,
   haptics = false,
   disabled = false,
+  accessible,
+  accessibilityActions,
+  onAccessibilityAction,
+  accessibilityRole,
+  accessibilityState,
+  focusable,
+  tabIndex,
+  onKeyDown,
   ...props
 }: ContextMenuTriggerProps) {
   const { setOpen, anchorTo } = usePopoverAnchor('ContextMenu.Trigger');
@@ -359,8 +386,8 @@ function ContextMenuTrigger({
    * The target is measured either way, because the preview draws at that rect
    * whatever the panel is placed against.
    */
-  const openAt = useCallback(
-    (x: number, y: number) => {
+  const open = useCallback(
+    (point?: { x: number; y: number }) => {
       // Ticked here rather than in the gesture callback so it fires once the
       // hold has been accepted, which is the moment there is something to
       // confirm — and on the same side of the bridge as the opening.
@@ -382,8 +409,8 @@ function ContextMenuTrigger({
          */
         const grown = hasPreview ? (PREVIEW_SCALE - 1) / 2 : 0;
         anchorTo(
-          against === 'point'
-            ? { x, y, width: 0, height: 0 }
+          against === 'point' && point
+            ? { ...point, width: 0, height: 0 }
             : {
                 x: mx - width * grown,
                 y: my - height * grown,
@@ -397,6 +424,63 @@ function ContextMenuTrigger({
     [against, anchorTo, setOpen, haptics, setTarget, setContent, children, hasPreview]
   );
 
+  const openAt = useCallback((x: number, y: number) => open({ x, y }), [open]);
+  // Keyboard and accessibility actions have no pointer coordinate to honour.
+  // The measured target is the only real location they can anchor against.
+  const openFromTarget = useCallback(() => open(), [open]);
+
+  const invoke = useCallback(
+    (invocation: ContextMenuInvocation) => {
+      if (invocation === 'menu') openFromTarget();
+      else onPress?.();
+    },
+    [onPress, openFromTarget]
+  );
+
+  const triggerActions = useMemo<readonly AccessibilityActionInfo[] | undefined>(() => {
+    if (disabled) return undefined;
+    const reserved = new Set(['activate', 'showMenu']);
+    return [
+      { name: 'activate' },
+      { name: 'showMenu', label: 'Show menu' },
+      ...(accessibilityActions ?? []).filter(({ name }) => !reserved.has(name)),
+    ];
+  }, [accessibilityActions, disabled]);
+
+  const handleAccessibilityAction = useCallback<
+    NonNullable<ViewProps['onAccessibilityAction']>
+  >(
+    (event) => {
+      const actionName = event.nativeEvent.actionName;
+      const invocation = contextMenuAccessibilityInvocation(actionName, !!onPress, disabled);
+      if (invocation) {
+        invoke(invocation);
+        return;
+      }
+      // Reserved actions cannot bypass a disabled trigger through a consumer
+      // handler, while unrelated custom actions still compose normally.
+      if (actionName === 'activate' || actionName === 'showMenu') return;
+      onAccessibilityAction?.(event);
+    },
+    [disabled, invoke, onAccessibilityAction, onPress]
+  );
+
+  const handleKeyDown = useCallback(
+    (event: ContextMenuKeyDownEvent) => {
+      onKeyDown?.(event);
+      if (event.isDefaultPrevented()) return;
+      const invocation = contextMenuKeyInvocation(event.nativeEvent, !!onPress, disabled);
+      if (!invocation) return;
+      event.preventDefault();
+      invoke(invocation);
+    },
+    [disabled, invoke, onKeyDown, onPress]
+  );
+
+  // React Native exposes key events at runtime (and in its generated types),
+  // while its compatibility ViewProps declaration does not yet list them.
+  const keyboardProps = { onKeyDown: handleKeyDown } as ViewProps;
+
   const gesture = useMemo(() => {
     /*
      * The hold and the tap are given to the recogniser as alternatives, so it
@@ -432,7 +516,23 @@ function ContextMenuTrigger({
         a view that only groups children is otherwise flattened away — and a
         flattened view cannot be measured, which `anchor="target"` needs.
       */}
-      <View ref={ref} collapsable={false} className={className} {...props}>
+      <View
+        ref={ref}
+        collapsable={false}
+        accessible={accessible ?? true}
+        accessibilityRole={accessibilityRole ?? 'button'}
+        accessibilityState={{
+          ...accessibilityState,
+          disabled: disabled || accessibilityState?.disabled,
+        }}
+        accessibilityActions={triggerActions}
+        onAccessibilityAction={handleAccessibilityAction}
+        focusable={focusable ?? !disabled}
+        tabIndex={tabIndex ?? (disabled ? -1 : 0)}
+        className={className}
+        {...keyboardProps}
+        {...props}
+      >
         {children}
       </View>
     </GestureDetector>

package/src/components/dialog/index.tsx

@@ -13,7 +13,7 @@ import {
 import { Pressable, View, type ViewProps } from 'react-native';
 import Animated, { FadeIn, FadeOut, ZoomIn } from 'react-native-reanimated';
 import { tv, type VariantProps } from 'tailwind-variants';
-import { Portal } from '../../primitives/portal';
+import { ModalPortal } from '../../primitives/portal';
 import { Scrim } from '../../primitives/scrim';
 import { Text, type TextProps, textChildren } from '../../primitives/text';
 import { useBackHandler } from '../../hooks/use-back-handler';
@@ -89,6 +89,9 @@ export interface DialogContentProps extends ViewProps {
    * Frost the screen behind the dialog instead of dimming it. Uses `expo-blur`
    * when installed and falls back to the dim when it is not, so it is safe to
    * pass either way.
+   *
+   * Someone who has Reduce Transparency switched on gets an opaque
+   * backdrop instead, which is the whole point of the setting.
    */
   blur?: boolean;
   children?: ReactNode;
@@ -111,7 +114,7 @@ function DialogContent({
   if (!open) return null;
 
   return (
-    <Portal>
+    <ModalPortal>
       {/* Portal content mounts under PortalHost, outside this provider's
           subtree — re-provide the context so Dialog.Close etc. keep working. */}
       <DialogContext.Provider value={context}>
@@ -142,7 +145,7 @@ function DialogContent({
           </Animated.View>
         </Animated.View>
       </DialogContext.Provider>
-    </Portal>
+    </ModalPortal>
   );
 }
 

package/src/components/drawer/index.tsx

@@ -84,7 +84,7 @@ import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { tv } from 'tailwind-variants';
 import { useCSSVariable } from 'uniwind';
 import { XIcon } from '../../icons';
-import { Portal } from '../../primitives/portal';
+import { ModalPortal } from '../../primitives/portal';
 import { Scrim } from '../../primitives/scrim';
 import { Text, textChildren } from '../../primitives/text';
 import { useBackHandler } from '../../hooks/use-back-handler';
@@ -285,6 +285,9 @@ export interface DrawerContentProps extends ViewProps {
   /**
    * Frost the screen behind the drawer instead of dimming it. Needs the
    * optional `expo-blur`; without it this dims, rather than failing.
+   *
+   * Someone who has Reduce Transparency switched on gets an opaque
+   * backdrop instead, which is the whole point of the setting.
    */
   blur?: boolean;
   children?: ReactNode;
@@ -458,7 +461,7 @@ function DrawerContent({
   };
 
   return (
-    <Portal>
+    <ModalPortal>
       {/* Portal content mounts under PortalHost, outside this provider's
           subtree — re-provide the context so Drawer.Close keeps working. */}
       <DrawerContext.Provider value={{ open, setOpen }}>
@@ -561,7 +564,7 @@ function DrawerContent({
           </View>
         </DirectionContext.Provider>
       </DrawerContext.Provider>
-    </Portal>
+    </ModalPortal>
   );
 }
 

package/src/components/fab/index.tsx

@@ -129,7 +129,10 @@ const fabVariants = tv({
       primary: { root: 'bg-primary', label: 'text-primary-foreground' },
       secondary: { root: 'bg-secondary', label: 'text-secondary-foreground' },
       surface: { root: 'border border-border bg-popover', label: 'text-foreground' },
-      destructive: { root: 'bg-destructive', label: 'text-white' },
+      destructive: {
+        root: 'bg-destructive',
+        label: 'text-destructive-solid-foreground',
+      },
     },
     disabled: {
       true: { root: 'opacity-[0.64] shadow-none' },
@@ -158,8 +161,9 @@ export type FabSize = NonNullable<FabVariantProps['size']>;
 export type FabVariant = NonNullable<FabVariantProps['variant']>;
 
 /** The theme token each variant's icon reads against. */
-const CONTENT_COLOR_VAR: Record<Exclude<FabVariant, 'destructive'>, string> = {
+const CONTENT_COLOR_VAR: Record<FabVariant, string> = {
   primary: '--color-primary-foreground',
+  destructive: '--color-destructive-solid-foreground',
   secondary: '--color-secondary-foreground',
   surface: '--color-foreground',
 };
@@ -234,17 +238,9 @@ const FabRoot = forwardRef<View, FabProps>(
       disabled,
     });
 
-    const themed = useCSSVariable(
-      CONTENT_COLOR_VAR[
-        variant === 'destructive' ? 'primary' : (variant ?? 'primary')
-      ]
-    );
+    const themed = useCSSVariable(CONTENT_COLOR_VAR[variant ?? 'primary']);
     const contentColor =
-      variant === 'destructive'
-        ? '#ffffff'
-        : typeof themed === 'string'
-          ? themed
-          : undefined;
+      typeof themed === 'string' ? themed : undefined;
 
     const handlePress = useCallback(() => {
       if (haptics) selectionTick();

package/src/components/field/index.tsx

@@ -18,7 +18,12 @@
  *     <Field.Title>Marketing emails</Field.Title>
  *     <Field.Description>Product updates, at most weekly.</Field.Description>
  *   </Field.Content>
- *   <Switch value={subscribed} onValueChange={setSubscribed} />
+ *   <Switch
+ *     value={subscribed}
+ *     onValueChange={setSubscribed}
+ *     accessibilityLabel="Marketing emails"
+ *     accessibilityHint="Product updates, at most weekly."
+ *   />
  * </Field>
  * ```
  */
@@ -26,6 +31,7 @@ import {
   createContext,
   forwardRef,
   useContext,
+  useId,
   useMemo,
   type ReactNode,
 } from 'react';
@@ -73,14 +79,22 @@ interface FieldState {
   invalid: boolean;
   disabled: boolean;
   required: boolean;
+  relationshipIds: string[];
 }
 
 const FieldContext = createContext<FieldState>({
   invalid: false,
   disabled: false,
   required: false,
+  relationshipIds: [],
 });
 
+/** Android can announce the label, help and error text rendered beside a control. */
+export function useFieldLabelledBy(): string[] | undefined {
+  const { relationshipIds } = useContext(FieldContext);
+  return relationshipIds.length > 0 ? relationshipIds : undefined;
+}
+
 export interface FieldProps extends ViewProps {
   className?: string;
   /** `horizontal` puts a label beside the control instead of above it. */
@@ -107,9 +121,19 @@ const FieldRoot = forwardRef<View, FieldProps>(
     ref
   ) => {
     const { root } = fieldVariants({ orientation, disabled });
+    const id = useId().replace(/:/g, '');
+    const labelId = `panelui-field-${id}-label`;
+    const titleId = `panelui-field-${id}-title`;
+    const descriptionId = `panelui-field-${id}-description`;
+    const errorId = `panelui-field-${id}-error`;
     const state = useMemo(
-      () => ({ invalid, disabled, required }),
-      [invalid, disabled, required]
+      () => ({
+        invalid,
+        disabled,
+        required,
+        relationshipIds: [labelId, titleId, descriptionId, errorId],
+      }),
+      [invalid, disabled, required, labelId, titleId, descriptionId, errorId]
     );
 
     return (
@@ -145,7 +169,7 @@ FieldContent.displayName = 'Field.Content';
 export interface FieldLabelProps extends LabelProps {}
 
 const FieldLabel = forwardRef<View, FieldLabelProps>(
-  ({ isRequired, isInvalid, isDisabled, ...props }, ref) => {
+  ({ isRequired, isInvalid, isDisabled, nativeID, ...props }, ref) => {
     const ctx = useContext(FieldContext);
     return (
       <Label
@@ -153,6 +177,7 @@ const FieldLabel = forwardRef<View, FieldLabelProps>(
         isRequired={isRequired ?? ctx.required}
         isInvalid={isInvalid ?? ctx.invalid}
         isDisabled={isDisabled ?? ctx.disabled}
+        nativeID={nativeID ?? ctx.relationshipIds[0]}
         {...props}
       />
     );
@@ -165,10 +190,17 @@ export interface FieldDescriptionProps extends TextProps {
 }
 
 const FieldDescription = forwardRef<RNText, FieldDescriptionProps>(
-  ({ className, ...props }, ref) => {
-    const { disabled } = useContext(FieldContext);
+  ({ className, nativeID, ...props }, ref) => {
+    const { disabled, relationshipIds } = useContext(FieldContext);
     const { description } = fieldVariants({ disabled });
-    return <Text ref={ref} className={description({ className })} {...props} />;
+    return (
+      <Text
+        ref={ref}
+        nativeID={nativeID ?? relationshipIds[2]}
+        className={description({ className })}
+        {...props}
+      />
+    );
   }
 );
 FieldDescription.displayName = 'Field.Description';
@@ -186,7 +218,8 @@ export interface FieldErrorProps extends Omit<ViewProps, 'children'> {
 }
 
 const FieldError = forwardRef<View, FieldErrorProps>(
-  ({ className, errors, children, ...props }, ref) => {
+  ({ className, errors, children, nativeID, ...props }, ref) => {
+    const { relationshipIds } = useContext(FieldContext);
     const messages = useMemo(() => {
       if (!errors) return null;
       const seen = new Set<string>();
@@ -213,6 +246,7 @@ const FieldError = forwardRef<View, FieldErrorProps>(
         // accessibilityRole list has no alert, the ARIA-aligned one does.
         role="alert"
         accessibilityLiveRegion="polite"
+        nativeID={nativeID ?? relationshipIds[3]}
         className={error({ className })}
         {...props}
       >
@@ -307,9 +341,17 @@ export interface FieldTitleProps extends TextProps {
 }
 
 const FieldTitle = forwardRef<RNText, FieldTitleProps>(
-  ({ className, ...props }, ref) => {
+  ({ className, nativeID, ...props }, ref) => {
     const { title } = fieldVariants();
-    return <Text ref={ref} className={title({ className })} {...props} />;
+    const { relationshipIds } = useContext(FieldContext);
+    return (
+      <Text
+        ref={ref}
+        nativeID={nativeID ?? relationshipIds[1]}
+        className={title({ className })}
+        {...props}
+      />
+    );
   }
 );
 FieldTitle.displayName = 'Field.Title';

package/src/components/flow/flow-accessibility.ts

@@ -0,0 +1,123 @@
+import type { FlowConnection, FlowNodePosition } from '.';
+import type { FlowRect } from './flow-paths';
+
+export const FLOW_MOVE_ACTIONS = [
+  { name: 'flow-move-up', label: 'Move up', dx: 0, dy: -1 },
+  { name: 'flow-move-right', label: 'Move right', dx: 1, dy: 0 },
+  { name: 'flow-move-down', label: 'Move down', dx: 0, dy: 1 },
+  { name: 'flow-move-left', label: 'Move left', dx: -1, dy: 0 },
+] as const;
+
+export const FLOW_DELETE_ACTION = { name: 'flow-delete', label: 'Delete node' } as const;
+
+export interface FlowAccessibilityNode {
+  id: string;
+  label: string;
+}
+
+export interface FlowAccessibilityHandle {
+  key: string;
+  node: string;
+  id: string;
+  label: string;
+  type: 'source' | 'target' | 'both';
+}
+
+export interface FlowConnectionAction {
+  name: string;
+  label: string;
+  connection: FlowConnection;
+}
+
+/** Opaque, collision-free name for the native accessibility action map. */
+export function flowConnectionActionName(
+  source: { node: string; handle?: string },
+  target: { node: string; handle?: string }
+): string {
+  return `flow-connect:${JSON.stringify([source, target])}`;
+}
+
+/** Keep pointer and assistive-technology movement inside the same group bounds. */
+export function clampNodePosition(
+  rect: FlowRect,
+  bounds: FlowRect | undefined,
+  position: FlowNodePosition
+): FlowNodePosition {
+  'worklet';
+  if (!bounds) return position;
+
+  return {
+    x: Math.min(Math.max(position.x, bounds.x), bounds.x + bounds.width - rect.width),
+    y: Math.min(Math.max(position.y, bounds.y), bounds.y + bounds.height - rect.height),
+  };
+}
+
+export function moveNodePosition(
+  rect: FlowRect,
+  bounds: FlowRect | undefined,
+  actionName: string,
+  step: number
+): FlowNodePosition | undefined {
+  const action = FLOW_MOVE_ACTIONS.find((entry) => entry.name === actionName);
+  if (!action) return undefined;
+
+  return clampNodePosition(rect, bounds, {
+    x: rect.x + action.dx * Math.max(1, step),
+    y: rect.y + action.dy * Math.max(1, step),
+  });
+}
+
+/** Build connection choices from the same registered nodes and handles used by drag hit-testing. */
+export function getFlowConnectionActions(
+  sourceNode: string,
+  nodes: FlowAccessibilityNode[],
+  handles: FlowAccessibilityHandle[]
+): FlowConnectionAction[] {
+  const sources = handles.filter(
+    (handle) => handle.node === sourceNode && handle.type !== 'target'
+  );
+  if (sources.length === 0) return [];
+
+  const actions: FlowConnectionAction[] = [];
+  for (const source of sources) {
+    for (const targetNode of nodes) {
+      if (targetNode.id === sourceNode) continue;
+      const targets = handles.filter(
+        (handle) => handle.node === targetNode.id && handle.type !== 'source'
+      );
+
+      if (targets.length === 0) {
+        actions.push({
+          name: flowConnectionActionName(
+            { node: source.node, handle: source.id },
+            { node: targetNode.id }
+          ),
+          label: `Connect ${source.label} to ${targetNode.label}`,
+          connection: {
+            source: sourceNode,
+            sourceHandle: source.id,
+            target: targetNode.id,
+          },
+        });
+        continue;
+      }
+
+      for (const target of targets) {
+        actions.push({
+          name: flowConnectionActionName(
+            { node: source.node, handle: source.id },
+            { node: target.node, handle: target.id }
+          ),
+          label: `Connect ${source.label} to ${targetNode.label}, ${target.label}`,
+          connection: {
+            source: sourceNode,
+            sourceHandle: source.id,
+            target: target.node,
+            targetHandle: target.id,
+          },
+        });
+      }
+    }
+  }
+  return actions;
+}

package/src/components/flow/flow-identifiers.ts

@@ -0,0 +1,98 @@
+const FLOW_TOKEN_PREFIX = 'panelui-flow:';
+
+export interface FlowEndpoint {
+  node: string;
+  handle?: string;
+}
+
+export type FlowEndpointReference = string | FlowEndpoint;
+
+type EncodedReference = ['legacy', string] | ['endpoint', string] | ['endpoint', string, string];
+
+function encodedReference(reference: FlowEndpointReference): EncodedReference {
+  if (typeof reference === 'string') return ['legacy', reference];
+  return reference.handle === undefined
+    ? ['endpoint', reference.node]
+    : ['endpoint', reference.node, reference.handle];
+}
+
+function decodedReference(value: unknown): FlowEndpointReference | undefined {
+  if (!Array.isArray(value)) return undefined;
+  if (value.length === 2 && value[0] === 'legacy' && typeof value[1] === 'string') {
+    return value[1];
+  }
+  if (
+    (value.length === 2 || value.length === 3) &&
+    value[0] === 'endpoint' &&
+    typeof value[1] === 'string' &&
+    (value.length === 2 || typeof value[2] === 'string')
+  ) {
+    return value.length === 2 ? { node: value[1] } : { node: value[1], handle: value[2] };
+  }
+  return undefined;
+}
+
+function decodeToken(token: string): unknown[] | undefined {
+  if (!token.startsWith(FLOW_TOKEN_PREFIX)) return undefined;
+  try {
+    const value: unknown = JSON.parse(token.slice(FLOW_TOKEN_PREFIX.length));
+    return Array.isArray(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Opaque identity for a registered handle. Node and handle text remain untouched. */
+export function encodeFlowHandleKey(node: string, handle: string): string {
+  return FLOW_TOKEN_PREFIX + JSON.stringify(['handle', node, handle]);
+}
+
+export function decodeFlowHandleKey(token: string): FlowEndpoint | undefined {
+  const value = decodeToken(token);
+  if (
+    value?.length !== 3 ||
+    value[0] !== 'handle' ||
+    typeof value[1] !== 'string' ||
+    typeof value[2] !== 'string'
+  ) {
+    return undefined;
+  }
+  return { node: value[1], handle: value[2] };
+}
+
+/** Opaque identity for an edge registration or accessibility connection action. */
+export function encodeFlowEdgeKey(
+  from: FlowEndpointReference,
+  to: FlowEndpointReference
+): string {
+  return FLOW_TOKEN_PREFIX + JSON.stringify(['edge', encodedReference(from), encodedReference(to)]);
+}
+
+export function decodeFlowEdgeKey(
+  token: string
+): { from: FlowEndpointReference; to: FlowEndpointReference } | undefined {
+  const value = decodeToken(token);
+  if (value?.length !== 3 || value[0] !== 'edge') return undefined;
+  const from = decodedReference(value[1]);
+  const to = decodedReference(value[2]);
+  return from === undefined || to === undefined ? undefined : { from, to };
+}
+
+/**
+ * Resolve a public endpoint without splitting its identifiers. Exact node ids
+ * win; legacy `node.handle` text is accepted only when it names one registered
+ * handle. Structured endpoints cover the otherwise ambiguous case.
+ */
+export function resolveFlowEndpoint(
+  reference: FlowEndpointReference,
+  nodes: readonly string[],
+  handles: readonly { node: string; id: string }[]
+): FlowEndpoint {
+  if (typeof reference !== 'string') return reference;
+  if (nodes.includes(reference)) return { node: reference };
+
+  const matches = handles.filter((handle) => `${handle.node}.${handle.id}` === reference);
+  return matches.length === 1
+    ? { node: matches[0]!.node, handle: matches[0]!.id }
+    : { node: reference };
+}