@flamingo-stack/openframe-frontend-core 0.0.579-1952.5335.1 → 0.0.579

package/src/components/chat/utils/approval-display.ts

@@ -4,20 +4,65 @@
  *
  * There are three such paths and they must agree: the NATS kernel (live chunks),
  * the SSE kernel, and the history replay that rebuilds a dialog after a reload.
- * When the rule lived only in the live kernel, a card could render inline while
- * streaming and then move into the escalation treatment on the next page load —
- * same card, two behaviors.
+ * When the rule lived only in the live kernel, a Product Guide card rendered
+ * inline while streaming and then moved into the escalation treatment on the
+ * next page load — same card, two behaviors, and its buttons pointed at the
+ * wrong backend once it moved.
+ *
+ * The rule itself: a card is gated on approval TIER (`displayApprovalTypes`,
+ * the agent's own privilege model) UNLESS it came from the Product Guide, whose
+ * proposals are typed by TOOL and are resolved through the hub's confirm route.
+ * A hub proposal has no tier to gate on, so tier-gating one means escalating it
+ * to a human who has no way to act on it.
  */
 
+import type { GuideOrigin } from '../../../chat-protocol/events';
+import { GUIDE_ORIGIN, isGuideOrigin } from '../../../chat-protocol/events';
+import type { MessageSegment } from '../types/message.types';
+
+/** Anything carrying the optional `origin` marker: a stream event, or the
+ *  `data` of a rendered segment. */
+interface OriginBearing {
+  origin?: GuideOrigin | string;
+}
+
+/** True when this approval was minted by the Product Guide (the hub) rather
+ *  than by the agent's own tool-approval tiering. */
+export function isGuideApproval(source: OriginBearing | null | undefined): boolean {
+  return isGuideOrigin(source);
+}
+
+/** The marker to stamp onto a built segment, or undefined for agent approvals.
+ *  Keeps `origin` out of segment data unless it means something. */
+export function guideApprovalOrigin(source: OriginBearing | null | undefined): GuideOrigin | undefined {
+  return isGuideApproval(source) ? GUIDE_ORIGIN : undefined;
+}
+
 /**
  * Does this approval render inline in its turn (true), or take the consumer's
  * escalation treatment (false)?
  *
- * A card is gated on approval TIER (`displayApprovalTypes`, the agent's own
- * privilege model). `undefined` means "no tier gate configured" and every
- * approval displays — the pre-existing history-replay default, preserved here
- * so both kernels can share one predicate.
+ * `displayApprovalTypes` undefined means "no tier gate configured" and every
+ * agent approval displays — the pre-existing history-replay default, preserved
+ * here so both kernels can share one predicate.
  */
-export function approvalDisplaysInline(approvalType: string, displayApprovalTypes?: readonly string[]): boolean {
+export function approvalDisplaysInline(
+  source: OriginBearing | null | undefined,
+  approvalType: string,
+  displayApprovalTypes?: readonly string[],
+): boolean {
+  if (isGuideApproval(source)) return true;
   return !displayApprovalTypes || displayApprovalTypes.includes(approvalType);
 }
+
+/**
+ * True for a rendered segment that holds a Product Guide card (single or batch).
+ *
+ * Consumers use it to keep such a card in the message flow, where the hub's own
+ * chat puts it, instead of lifting it into their sticky pending-approvals
+ * footer — and to route its buttons to the hub rather than to the agent.
+ */
+export function isGuideApprovalSegment(segment: MessageSegment): boolean {
+  if (segment.type !== 'approval_request' && segment.type !== 'approval_batch') return false;
+  return isGuideApproval(segment.data);
+}

package/src/components/chat/utils/extract-incomplete-message-state.ts

@@ -136,6 +136,7 @@ export function extractIncompleteMessageState(
       //   backend has already abandoned.
       case 'text':
       case 'thinking':
+      case 'guide':
       case 'ask':
       case 'ticket_escalated':
       case 'ticket_event':

package/src/components/chat/utils/index.ts

@@ -16,7 +16,12 @@ export {
 
 // Where an approval card renders — one rule for both live kernels, the history
 // replay, and hosts that sort cards between their own footer and the flow.
-export { approvalDisplaysInline } from './approval-display';
+export {
+  isGuideApproval,
+  guideApprovalOrigin,
+  approvalDisplaysInline,
+  isGuideApprovalSegment,
+} from './approval-display';
 
 // Historical message processing
 export {

package/src/components/chat/utils/message-segment-accumulator.ts

@@ -155,6 +155,22 @@ export class MessageSegmentAccumulator {
     return this.getSegments();
   }
 
+  /**
+   * Append guide text to the current message.
+   * If the last segment is guide, append to it; otherwise start a new guide segment.
+   */
+  appendGuide(text: string): MessageSegment[] {
+    const lastSegment = this.segments[this.segments.length - 1];
+
+    if (lastSegment && lastSegment.type === 'guide') {
+      this.segments[this.segments.length - 1] = { type: 'guide', text: lastSegment.text + text };
+    } else {
+      this.segments.push({ type: 'guide', text });
+    }
+
+    return this.getSegments();
+  }
+
   /**
    * Add a clarification (ask) card. Unlike the three delta streams an ask
    * arrives whole in one chunk, so it is always a NEW segment — never merged
@@ -309,11 +325,15 @@ export class MessageSegmentAccumulator {
     status: ChatApprovalStatus = 'pending',
     /** Structured label/value rows. The card prefers them over `explanation`
      *  (see `ApprovalRequestData.fields`). Optional because the agent's own
-     *  approvals carry prose. */
+     *  approvals carry prose; a Product Guide card is almost entirely fields —
+     *  dropping them here left it as a bare title. */
     fields?: ApprovalRequestField[],
+    /** Where the card came from; `'guide'` keeps it inline (see
+     *  `ApprovalRequestData.origin`). */
+    origin?: 'guide',
   ): MessageSegment[] {
     this.segments.push(
-      this.buildApprovalRequestSegment(requestId, { command, explanation, approvalType, fields }, status),
+      this.buildApprovalRequestSegment(requestId, { command, explanation, approvalType, fields, origin }, status),
     );
     return this.getSegments();
   }
@@ -324,7 +344,7 @@ export class MessageSegmentAccumulator {
    * Three paths produce these: `addApprovalRequest` (live stream and replay),
    * `flushPendingApprovals` (tracked-but-unresolved after a history replay) and
    * `processApprovalResult` (a result arriving for a tracked request). They used
-   * to hand-write the object each, which is how `fields` reached
+   * to hand-write the object each, which is how `fields` and `origin` reached
    * the card down one path and not the others — the same proposal rendering as a
    * bare title, or losing the marker that routes its buttons to the hub.
    */
@@ -341,6 +361,7 @@ export class MessageSegmentAccumulator {
         requestId,
         approvalType: approval.approvalType,
         ...(approval.fields && approval.fields.length > 0 ? { fields: approval.fields } : {}),
+        ...(approval.origin ? { origin: approval.origin } : {}),
       },
       status,
       onApprove: this.callbacks.onApprove,
@@ -368,6 +389,9 @@ export class MessageSegmentAccumulator {
     status: ChatApprovalStatus = 'pending',
     executions?: Record<string, ApprovalBatchExecutionState>,
     resolvedByName?: string | null,
+    /** Where the batch came from; `'guide'` keeps it inline and routes it to
+     *  the hub, exactly as for a single card (see `ApprovalBatchData.origin`). */
+    origin?: 'guide',
   ): MessageSegment[] {
     const existingIndex = this.segments.findIndex(
       (s): s is ApprovalBatchSegment => s.type === 'approval_batch' && s.data.approvalRequestId === approvalRequestId,
@@ -376,6 +400,9 @@ export class MessageSegmentAccumulator {
     if (existingIndex !== -1) {
       const existing = this.segments[existingIndex] as ApprovalBatchSegment;
       const mergedExecutions = executions ?? existing.data.executions;
+      // An upsert must not strip the marker: the flip to `approved` comes from
+      // a later event that carries no origin of its own.
+      const mergedOrigin = origin ?? existing.data.origin;
       this.segments[existingIndex] = {
         ...existing,
         data: {
@@ -383,6 +410,7 @@ export class MessageSegmentAccumulator {
           approvalType,
           toolCalls,
           ...(mergedExecutions ? { executions: mergedExecutions } : {}),
+          ...(mergedOrigin ? { origin: mergedOrigin } : {}),
         },
         status,
         resolvedByName: resolvedByName ?? existing.resolvedByName,
@@ -399,6 +427,7 @@ export class MessageSegmentAccumulator {
         approvalType,
         toolCalls,
         ...(executions ? { executions } : {}),
+        ...(origin ? { origin } : {}),
       },
       status,
       resolvedByName,
@@ -656,6 +685,9 @@ export class MessageSegmentAccumulator {
         case 'thinking':
           if (segment.text) this.appendThinking(segment.text);
           break;
+        case 'guide':
+          if (segment.text) this.appendGuide(segment.text);
+          break;
         case 'ask':
           this.addAsk(segment.question, segment.options);
           break;
@@ -671,6 +703,7 @@ export class MessageSegmentAccumulator {
             data.approvalType || '',
             status,
             data.fields,
+            data.origin,
           );
           break;
         }
@@ -683,6 +716,7 @@ export class MessageSegmentAccumulator {
             status,
             data.executions,
             resolvedByName,
+            data.origin,
           );
           break;
         }

package/src/components/chat/utils/process-historical-messages.ts

@@ -33,7 +33,7 @@ import {
 } from '../../../chat-protocol/events';
 // One normalizer for ask rows, shared with the live decoder — history and the
 // stream must agree on which options are usable.
-import { normalizeAskOptions } from '../../../chat-protocol/nats-decoder';
+import { guideFrameEvent, normalizeAskOptions } from '../../../chat-protocol/nats-decoder';
 import { applyApprovalStatusToSegment } from '../stream/message-mutations';
 import {
   MESSAGE_TYPE,
@@ -47,7 +47,7 @@ import {
   type MessageData,
   type MessageOwner,
 } from '../types';
-import { approvalDisplaysInline } from './approval-display';
+import { approvalDisplaysInline, guideApprovalOrigin } from './approval-display';
 import { type MessageSegmentAccumulator, createMessageSegmentAccumulator } from './message-segment-accumulator';
 import { getCommandText } from './tool-call-helpers';
 
@@ -121,6 +121,22 @@ export function decodeHistoricalMessageData(data: MessageData): ChatStreamEvent
       }
       return null;
 
+    // Two persisted shapes, mirroring the live `GUIDE` chunk: the answer body
+    // (`text`) and a Product Guide frame the agent re-streamed (`payload`,
+    // persisted so a card survives a reload). Decoded through the SAME
+    // `guideFrameEvent` the live path uses — a second mapping here would let
+    // history and realtime disagree about the same bytes.
+    case MESSAGE_TYPE.GUIDE: {
+      if ('text' in data && data.text) {
+        return { type: 'guide-delta', text: data.text };
+      }
+      const payload = 'payload' in data ? data.payload : undefined;
+      if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+        return guideFrameEvent(payload);
+      }
+      return null;
+    }
+
     // Same completeness gate as the live decoder (`decodeNatsChunk`): a
     // persisted row without a question or without options is not a card the
     // user can answer, so it replays as nothing rather than as empty chrome.
@@ -381,6 +397,10 @@ function applyHistoryEvent(
       accumulator.appendThinking(event.text);
       break;
 
+    case 'guide-delta':
+      accumulator.appendGuide(event.text);
+      break;
+
     // Mirror of the live path: the intro sentence replays as answer text in
     // front of the card, so a reloaded thread reads exactly like the stream did.
     case 'ask':
@@ -397,13 +417,23 @@ function applyHistoryEvent(
       const toolCalls = event.toolCalls;
       const isBatch = !!toolCalls && toolCalls.length > 0;
       // Same rule the live kernels use — a card must not change where it
-      // renders just because the page was reloaded and it came back through
-      // history instead of the stream.
-      if (approvalDisplaysInline(approvalType, displayApprovalTypes)) {
+      // renders (or which backend its buttons hit) just because the page was
+      // reloaded and it came back through history instead of the stream.
+      const guideOrigin = guideApprovalOrigin(event);
+
+      if (approvalDisplaysInline(event, approvalType, displayApprovalTypes)) {
         if (isBatch) {
           const status = (approvalStatuses[event.requestId] as ChatApprovalStatus) || 'pending';
           if (batchApprovalsEnabled) {
-            accumulator.addApprovalBatch(event.requestId, approvalType, toolCalls, status, undefined, undefined);
+            accumulator.addApprovalBatch(
+              event.requestId,
+              approvalType,
+              toolCalls,
+              status,
+              undefined,
+              undefined,
+              guideOrigin,
+            );
           } else {
             // Flag OFF — unfold batch into N legacy approval cards (same id).
             for (const call of toolCalls) {
@@ -415,6 +445,7 @@ function applyHistoryEvent(
                 approvalType,
                 status,
                 undefined,
+                guideOrigin,
               );
             }
           }
@@ -428,7 +459,12 @@ function applyHistoryEvent(
           // and honor `approvalStatuses`.
           const resolvedStatus = approvalStatuses[event.requestId] as ChatApprovalStatus | undefined;
           const isResolved = resolvedStatus === 'approved' || resolvedStatus === 'rejected';
-          if (isResolved) {
+          // A guide card is added inline even while pending. The tracked path
+          // below ends in `flushPendingApprovals`, whose segments the consumer
+          // lifts into a sticky footer — that is the treatment for the
+          // consumer's OWN approvals, and it is not how the hub's chat renders
+          // a proposal (nor where its preamble expects it).
+          if (guideOrigin || isResolved) {
             accumulator.addApprovalRequest(
               event.requestId,
               event.command || '',
@@ -436,6 +472,7 @@ function applyHistoryEvent(
               approvalType,
               resolvedStatus ?? 'pending',
               event.fields,
+              guideOrigin,
             );
           } else {
             accumulator.trackApprovalRequest(event.requestId, {

package/src/components/chat/utils/resolve-fetched-card-href.ts

@@ -11,7 +11,7 @@
  *     (`title` / `url` / `targetPlatform` / `sourceRepo`). `resolveSourceRowCTA`
  *     then routes that `externalUrl` through the host's `composeContentUrl`
  *     seam and the card is clickable.
- *   - **Mingo / NATS transport** (`messageData: [{ type: 'TEXT', text }]`)
+ *   - **Mingo / NATS transport** (`messageData: [{ type: 'GUIDE' | 'TEXT', text }]`)
  *     — the body carries bare `[card://type:id]` markers and NOTHING else.
  *     `chat-message-enhanced.tsx` synthesizes a minimal `{ type, id, title: id,
  *     url: null }` ref so fetch-mode cards can still self-fetch their row, but

package/src/components/features/board/.board.md

@@ -15,6 +15,7 @@ Kanban-style drag-and-drop board built on Pragmatic drag and drop, managing mult
 - **Nothing moves during a drag** — The dragged card stays put and fades; the landing place is a line. No margins open, no slots close, so the lane's height cannot wander and an edge flip costs one span instead of a relayout plus a card render
 - **One aim, one preview** — Where the drop points is resolved once, in the board's monitor, and handed down (`drop-aim.ts`). Each card used to work it out from its own hover events, which only ever answers for a card the pointer is physically over — so the preview vanished the moment the pointer left the lanes, even though the drop would still have landed. The board's answer is compared before it is stored, so a pointer moving inside one card does not re-render anything
 - **Cross-column guards** — `dropDisabled` and `allowedFromColumns` are enforced by each target's `canDrop`, so an invalid drop is never accepted and nothing has to be reverted
+- **No DnD on touch** — `useDragAndDropEnabled()` gates the whole board: on touch/narrow viewports (`(pointer: fine) and (hover: hover) and (min-width: 800px)` fails) every column is forced `dragDisabled`/`dropDisabled`, so nothing registers a draggable or a target — the HTML5 drag events Pragmatic builds on never fire under touch anyway. Card moves there go through the ticket itself, not the board
 - **Optimistic view** — The board renders `applyPendingMove(columns, pendingMove)` from the drop until the host's answer arrives (`pending-move.ts`), so the move is on screen instantly and the host's data replaces an identical picture. "Landed" is judged per kind of move: across lanes, arriving in the new lane once the old one has let go (a server may re-sort the lane, so the exact index would never come); within one lane, the exact slot. Weaker tests (a fresh `columns` array, the card leaving its old index) fire on a lane's own poll and snap the card back mid-flight. A 2s timeout is the backstop for a host that never applies the change
 - **Dragged card** — The card under the pointer is the browser's own native drag image (a styled DOM clone via `setCustomNativeDragPreview`), so the browser moves it — over its own chrome included — and carrying a card re-renders nothing and cannot freeze at the viewport edge. On drop, a portal copy takes over for one 160ms FLIP glide from the release point into the slot the move just opened, then hands over to the real card (hidden under it via `LandingCardContext` for exactly that long)
 - **Keyboard move** — Space on a focused card lifts it; the arrows walk it (up/down through slots, left/right through lanes, skipping any that will not take it); space or enter drops it; escape puts it back. Lift-and-place rather than one-press-one-move, because on a board every press would otherwise be its own write to the server. The lifted card feeds the same aim a pointer drag does, and the drop line is scrolled into view on every step — arrow keys bring no auto-scroll of their own. Keys are handled on the board, not the card: once a card is lifted they belong to the move rather than to whatever holds focus. Rules live in `aim.ts`, pure and unit-tested

package/src/components/features/board/board.tsx

@@ -5,6 +5,7 @@ import { monitorForElements } from '@atlaskit/pragmatic-drag-and-drop/element/ad
 import { preventUnhandled } from '@atlaskit/pragmatic-drag-and-drop/utils/prevent-unhandled';
 import { Fragment, useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
 import { createPortal } from 'react-dom';
+import { useDragAndDropEnabled } from '../../../hooks/ui/use-drag-and-drop-enabled';
 import { useHorizontalScrollbar } from '../../../hooks/ui/use-horizontal-scrollbar';
 import { useIsomorphicLayoutEffect } from '../../../hooks/ui/use-isomorphic-layout-effect';
 import { autoScrollBothWays } from '../../../utils/auto-scroll-ancestors';
@@ -169,7 +170,16 @@ export function Board({
   // Publishing it from an effect instead committed one whole frame with the card
   // still held in its pending position after the host had already caught up.
   const pendingMove = reportedMove && !hasMoveSettled(columns, reportedMove) ? reportedMove : null;
-  const view = useMemo(() => (pendingMove ? applyPendingMove(columns, pendingMove) : columns), [columns, pendingMove]);
+  // On touch/narrow viewports no card is draggable and no lane is a drop
+  // target: the HTML5 drag events Pragmatic builds on never fire under touch,
+  // so instead of shipping a drag that half-works, none is initialized at all.
+  // Card moves there go through the ticket itself (its dialog), not the board.
+  const dragAndDropEnabled = useDragAndDropEnabled();
+  const view = useMemo(() => {
+    const base = pendingMove ? applyPendingMove(columns, pendingMove) : columns;
+    if (dragAndDropEnabled) return base;
+    return base.map(column => ({ ...column, dragDisabled: true, dropDisabled: true }));
+  }, [columns, pendingMove, dragAndDropEnabled]);
   // EVERYTHING downstream reads `view`, never `columns`: it is what is on
   // screen, so it is also what a drag, a keyboard move and a drop are about.
   // `columns` is only ever consulted to ask whether the host has caught up.

package/src/components/features/sortable-list/.sortable-list.md

@@ -1,13 +1,14 @@
 <!-- source-hash: manual -->
 A vertical list whose items are reordered by dragging a handle, built on Pragmatic drag and drop.
+**The one sortable-list implementation in the stack** — every ordered list (schedule scripts,
+ticket statuses, AI quick actions via `TicketStatusConfigList`) runs on it; `@dnd-kit` is gone.
 
-> **Currently unused.** It was written for the ordered lists — schedule scripts, ticket statuses,
-> AI quick actions — and those have since gone back to `@dnd-kit` (`TicketStatusConfigList`), whose
-> pointer sensors work under touch where the HTML5 drag-and-drop API this is built on does not.
-> Kept, not deleted: it is a complete and general implementation, and the ticket board next door
-> still runs on the same library. Reach for `TicketStatusConfigList` for a new ordered list; reach
-> for this one only if you specifically need what it does differently — slot geometry with
-> hysteresis, a FLIP drop animation, and auto-scroll through every scrollable ancestor.
+The HTML5 drag-and-drop API this is built on does not fire under touch — which is why those lists
+once went back to `@dnd-kit`. The answer now is not a second library: on touch/narrow viewports
+(`useDragAndDropEnabled()` is `false`) **no drag is initialized at all**, and each row renders an
+explicit up/down `SortableMoveButtons` pair instead of its handle. Explicit buttons because on
+touch nothing else survives contact with the page: a drag fights scrolling, long-press fights the
+context menu.
 
 Deliberately **not** the ticket board, which moves cards between columns and needs a different
 model.
@@ -17,21 +18,26 @@ model.
 | Export | Description |
 |---|---|
 | `SortableList` | The container. Owns the geometry, the drag monitor and the live region |
-| `useSortableItem` | Registers one item: gives back `itemRef`, `dragHandleProps` and `isDragging` |
+| `useSortableItem` | Registers one item: gives back `itemRef`, `dragHandleProps`, `isDragging` and `dragAndDropEnabled` |
+| `SortableMoveButtons` | The touch fallback: a joined up/down pair, disabled at the ends, announcing through the list's live region |
 | `SLOT_STICKINESS` | The dead band around a slot boundary, as a share of one slot's travel |
 
 ## Usage
 
 ```tsx
 <SortableList onReorder={move} getItemLabel={i => rows[i].name} className="flex flex-col gap-6">
-  {rows.map(row => <Row key={row.id} row={row} />)}
+  {rows.map((row, i) => <Row key={row.id} row={row} index={i} count={rows.length} />)}
 </SortableList>
 
-function Row({ row }) {
-  const { itemRef, dragHandleProps, isDragging } = useSortableItem()
+function Row({ row, index, count }) {
+  const { itemRef, dragHandleProps, isDragging, dragAndDropEnabled } = useSortableItem()
   return (
     <div ref={itemRef} className={isDragging ? 'border-ods-accent shadow-lg' : 'border-ods-border'}>
-      <button type="button" {...dragHandleProps} aria-label="Reorder…"><DraggerIcon /></button>
+      {dragAndDropEnabled ? (
+        <button type="button" {...dragHandleProps} aria-label="Reorder…"><DraggerIcon /></button>
+      ) : (
+        <SortableMoveButtons index={index} count={count} label={row.name} />
+      )}
       …
     </div>
   )
@@ -76,6 +82,11 @@ function Row({ row }) {
   moves the list and the pointer together and nothing goes stale.
 - **Keyboard.** Pragmatic drag and drop ships none, so `dragHandleProps` carries Arrow Up / Arrow
   Down — one press, one move. The list announces every move through its own live region.
+- **Input gating.** `useDragAndDropEnabled()` — `(pointer: fine) and (hover: hover) and
+  (min-width: 800px)` — decides whether any drag exists. `false` (touch, narrow windows, and SSR /
+  first render) skips every Pragmatic registration; `SortableMoveButtons` go through the same
+  `reorder` as a drop, so the announcement and the `onReorder` contract are identical on every
+  input. The consumer `disabled` prop still switches everything off, buttons included.
 
 ## Source
 

package/src/components/features/sortable-list/index.ts

@@ -1,3 +1,4 @@
 export { SLOT_STICKINESS } from './slot-geometry';
 export { SortableList, type SortableListProps } from './sortable-list';
-export { type SortableItem, useSortableItem } from './use-sortable-item';
+export { SortableMoveButtons, type SortableMoveButtonsProps } from './sortable-move-buttons';
+export { type SortableDragHandleProps, type SortableItem, useSortableItem } from './use-sortable-item';

package/src/components/features/sortable-list/sortable-list.tsx

@@ -14,6 +14,7 @@ import {
   useRef,
   useState,
 } from 'react';
+import { useDragAndDropEnabled } from '../../../hooks/ui/use-drag-and-drop-enabled';
 import { useIsomorphicLayoutEffect } from '../../../hooks/ui/use-isomorphic-layout-effect';
 import { autoScrollAncestors, autoScrollBothWays } from '../../../utils/auto-scroll-ancestors';
 import { type DragSlots, measureSlots, resolveSlot, shiftFor } from './slot-geometry';
@@ -30,8 +31,15 @@ const EASING = 'cubic-bezier(0.2, 0, 0, 1)';
 interface SortableListContextValue {
   /** Distinguishes this list's drags from any other list's on the page. */
   dragType: string;
+  /** The consumer's `disabled` prop: everything off, move buttons included. */
   disabled: boolean;
-  /** Reorders the list. Used by the drop AND by a handle's arrow keys. */
+  /**
+   * The input-type gate (`useDragAndDropEnabled`): `false` on touch/narrow
+   * viewports, where no drag is registered and rows render explicit
+   * `SortableMoveButtons` instead of a handle.
+   */
+  dragAndDropEnabled: boolean;
+  /** Reorders the list. Used by the drop, a handle's arrow keys AND the move buttons. */
   reorder: (from: number, to: number) => void;
   /** Every registered item, in DOM order. */
   readItems: () => HTMLElement[];
@@ -82,6 +90,9 @@ export interface SortableListProps {
  */
 export function SortableList({ onReorder, getItemLabel, disabled = false, className, children }: SortableListProps) {
   const listRef = useRef<HTMLDivElement>(null);
+  // False on touch/narrow viewports: no drag is initialized anywhere in the
+  // list, and rows fall back to explicit move buttons.
+  const dragAndDropEnabled = useDragAndDropEnabled();
   // Stable across renders and never rendered, so there is no hydration to
   // mismatch — unlike keying a drag on a random per-item id.
   const dragType = useId();
@@ -126,7 +137,7 @@ export function SortableList({ onReorder, getItemLabel, disabled = false, classN
 
   useEffect(() => {
     const list = listRef.current;
-    if (!list) return undefined;
+    if (!list || disabled || !dragAndDropEnabled) return undefined;
 
     /** Alive for one drag; this effect body is its whole scope. */
     let drag: (DragSlots & { items: HTMLElement[]; to: number; startY: number }) | null = null;
@@ -218,7 +229,7 @@ export function SortableList({ onReorder, getItemLabel, disabled = false, classN
         },
       }),
     );
-  }, [dragType, readItems, reorder]);
+  }, [dragType, disabled, dragAndDropEnabled, readItems, reorder]);
 
   // Runs after the commit that carries BOTH the reorder and the tick above, so
   // the DOM is already in its final order — which is why `onReorder` never has
@@ -267,8 +278,8 @@ export function SortableList({ onReorder, getItemLabel, disabled = false, classN
   );
 
   const context = useMemo<SortableListContextValue>(
-    () => ({ dragType, disabled, reorder, readItems }),
-    [dragType, disabled, reorder, readItems],
+    () => ({ dragType, disabled, dragAndDropEnabled, reorder, readItems }),
+    [dragType, disabled, dragAndDropEnabled, reorder, readItems],
   );
 
   return (

package/src/components/features/sortable-list/sortable-move-buttons.tsx

@@ -0,0 +1,81 @@
+'use client';
+
+import { useRef } from 'react';
+import { cn } from '../../../utils/cn';
+import { Arrow01DownIcon } from '../../icons-v2-generated/arrows/arrow-01-down-icon';
+import { Arrow01UpIcon } from '../../icons-v2-generated/arrows/arrow-01-up-icon';
+import { Button } from '../../ui/button';
+import { useSortableListContext } from './sortable-list';
+
+export interface SortableMoveButtonsProps {
+  /** The row's current position — the caller renders the rows, so it knows. */
+  index: number;
+  /** How many rows the list has; the down button is disabled on the last one. */
+  count: number;
+  /** Names the row in the buttons' accessible labels, e.g. "On Hold". */
+  label?: string;
+  className?: string;
+}
+
+/**
+ * The touch replacement for a drag handle: an up/down pair rendered by a row of
+ * a {@link SortableList} when `dragAndDropEnabled` is `false` (see
+ * `useSortableItem`). Explicit buttons because on touch nothing else survives
+ * contact with the page: a drag fights scrolling, long-press fights the context
+ * menu, and the HTML5 drag events behind Pragmatic never fire at all.
+ *
+ * Moves go through the list's `reorder`, so they hit the same `onReorder`
+ * callback and the same live region as a drop or a handle's arrow keys.
+ *
+ * One joined pair per the design: outer corners rounded, a single hairline
+ * between the halves, each half disabled at its end of the list.
+ */
+export function SortableMoveButtons({ index, count, label, className }: SortableMoveButtonsProps) {
+  const { disabled, reorder } = useSortableListContext();
+  const upRef = useRef<HTMLButtonElement>(null);
+  const downRef = useRef<HTMLButtonElement>(null);
+
+  const move = (step: -1 | 1) => {
+    const to = index + step;
+    if (to < 0 || to >= count) return;
+    reorder(index, to);
+    // The row this pair sits in keeps its DOM nodes, but the pressed half may
+    // come back disabled (the row reached an end) — hand focus to the other
+    // half so a keyboard user is not dropped to the page body.
+    requestAnimationFrame(() => {
+      if (step === -1 && to === 0) downRef.current?.focus();
+      if (step === 1 && to === count - 1) upRef.current?.focus();
+    });
+  };
+
+  const subject = label ?? 'item';
+
+  return (
+    <div className={cn('inline-flex shrink-0', className)}>
+      <Button
+        ref={upRef}
+        type="button"
+        variant="outline"
+        size="icon"
+        aria-label={`Move ${subject} up`}
+        disabled={disabled || index <= 0}
+        onClick={() => move(-1)}
+        className="rounded-r-none border-r-0"
+      >
+        <Arrow01UpIcon />
+      </Button>
+      <Button
+        ref={downRef}
+        type="button"
+        variant="outline"
+        size="icon"
+        aria-label={`Move ${subject} down`}
+        disabled={disabled || index >= count - 1}
+        onClick={() => move(1)}
+        className="rounded-l-none"
+      >
+        <Arrow01DownIcon />
+      </Button>
+    </div>
+  );
+}