@flamingo-stack/openframe-frontend-core 0.0.577 → 0.0.578-snapshot.20260831161155

package/src/components/ui/.ticket-status-config-row.md

@@ -1,14 +1,15 @@
-<!-- source-hash: af0402d9923c0e0c41315794a7eff4a9 -->
-A client-side React component that renders a single row in a ticket status configuration UI, supporting both system-defined and custom ticket statuses with drag-and-drop reordering, color picking, and delete controls.
+<!-- source-hash: manual -->
+A client-side React component that renders a single row in a ticket status configuration UI, supporting both system-defined and custom ticket statuses with reordering, color picking, and delete controls.
 
 ## Key Components
 
 ### `TicketStatusConfigRow`
 The primary exported component. Renders a row containing:
-- **Drag handle** — interactive for custom rows, decorative/disabled for system rows
-- **Name input** — editable for custom, read-only for system rows
-- **Color controls** — `ColorPresetSelect` and `ColorPickerInput` shown only for custom rows with color support
-- **Live preview** — `TicketStatusTag` reflecting current name and color
+- **Drag handle** — interactive for custom rows, decorative/disabled for system rows. The whole rail is rendered only while `useDragAndDropEnabled()` holds; on touch/narrow viewports it disappears and the `moveButtons` node (an up/down `SortableMoveButtons` pair handed in by `TicketStatusConfigList`) renders beside the delete button instead
+- **Name input** — editable for custom, read-only for system rows; carries a visible "Status Name" label (the rail, chip and controls offset below the label line to align with the field)
+- **Color controls** — `ColorPresetSelect` (labelled "Color") and `ColorPickerInput` shown only for custom rows with color support
+- **Live preview** — `TicketStatusTag` reflecting current name and color. Inline right on desktop (lg+); below the fields on tablet (own row, right-aligned) and mobile (beside the color select). System rows keep it beside the name everywhere
+- **Transparent background** — only the border outlines the row; the dragged row gets an opaque `bg-ods-bg` so it can travel over siblings
 - **Action button** — info tooltip icon for system rows; delete button (with optional disabled state tooltip) for custom rows
 
 ### `WithLeftTooltip` (internal)
@@ -22,7 +23,8 @@ The full props interface, key fields:
 | `variant` | `'system'` or `'custom'` — controls editability and available actions |
 | `statusKey` | Canonical key forwarded to `TicketStatusTag` |
 | `onColorChange` | Callback receiving `{ color, preset? }` |
-| `dragHandleProps` / `dragHandleAttributes` | From `@dnd-kit/core` for drag-and-drop |
+| `dragHandleProps` | `SortableDragHandleProps` from `useSortableItem` (spread whole onto the grip) |
+| `moveButtons` | Touch fallback node (`SortableRowRenderArgs.moveButtons`), rendered beside delete |
 | `deleteDisabledReason` | Shown as tooltip when delete is disabled |
 | `isDragging` | Applies visual feedback during drag |
 
@@ -46,9 +48,9 @@ import { TicketStatusConfigRow } from './ticket-status-config-row'
   onDelete={handleDelete}
   deleteDisabled={isOnlyStatus}
   deleteDisabledReason="At least one status is required"
-  dragHandleProps={listeners}
-  dragHandleAttributes={attributes}
+  dragHandleProps={dragHandleProps}
   isDragging={isDragging}
+  moveButtons={moveButtons}
 />
 
 // System row (read-only, no delete)

package/src/components/ui/input.tsx

@@ -14,6 +14,8 @@ export interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
   endAdornment?: ReactNode;
   /** Label text displayed above the input */
   label?: string;
+  /** Label scale forwarded to FieldWrapper ('large' = text-h4 for designs with body-scale field titles) */
+  labelVariant?: 'default' | 'large';
   /** Status message displayed below the input */
   error?: string;
   /** Color variant for the message: "error" (red), "warning" (yellow), "success" (green) or "muted" (grey).
@@ -37,6 +39,7 @@ const Input = forwardRef<HTMLInputElement, InputProps>(
       startAdornment,
       endAdornment,
       label,
+      labelVariant,
       error,
       errorVariant = 'error',
       loading = false,
@@ -75,7 +78,7 @@ const Input = forwardRef<HTMLInputElement, InputProps>(
         />
       );
       return label ? (
-        <FieldWrapper label={label} error={error} errorVariant={errorVariant}>
+        <FieldWrapper label={label} labelVariant={labelVariant} error={error} errorVariant={errorVariant}>
           {rangeInput}
         </FieldWrapper>
       ) : (
@@ -149,7 +152,7 @@ const Input = forwardRef<HTMLInputElement, InputProps>(
     );
 
     return (
-      <FieldWrapper label={label} error={error} errorVariant={errorVariant}>
+      <FieldWrapper label={label} labelVariant={labelVariant} error={error} errorVariant={errorVariant}>
         {content}
       </FieldWrapper>
     );

package/src/components/ui/textarea.tsx

@@ -10,6 +10,8 @@ export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElemen
   invalid?: boolean;
   /** Label text displayed above the textarea */
   label?: string;
+  /** Label scale forwarded to FieldWrapper ('large' = text-h4 for designs with body-scale field titles) */
+  labelVariant?: 'default' | 'large';
   /** Error message displayed below the textarea */
   error?: string;
   /** Element rendered at the right edge of the field (e.g. send icon). */
@@ -41,6 +43,7 @@ const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
       className,
       invalid = false,
       label,
+      labelVariant,
       error,
       endIcon,
       endIconAsButton = false,
@@ -66,7 +69,7 @@ const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
     // border/bg/hover all live on the textarea itself.
     if (!hasAdornment) {
       return (
-        <FieldWrapper label={label} error={error}>
+        <FieldWrapper label={label} labelVariant={labelVariant} error={error}>
           <textarea
             className={cn(
               'flex min-h-[96px] w-full rounded-[6px] border p-3',
@@ -214,7 +217,7 @@ const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
     );
 
     return (
-      <FieldWrapper label={label} error={error}>
+      <FieldWrapper label={label} labelVariant={labelVariant} error={error}>
         {content}
       </FieldWrapper>
     );

package/src/components/ui/ticket-status-config-row.tsx

@@ -1,13 +1,16 @@
 'use client';
 
-import type { DraggableAttributes, DraggableSyntheticListeners } from '@dnd-kit/core';
+import { type ReactNode, useId } from 'react';
+import { useDragAndDropEnabled } from '../../hooks/ui/use-drag-and-drop-enabled';
 import { cn } from '../../utils/cn';
+import type { SortableDragHandleProps } from '../features/sortable-list/use-sortable-item';
 import { DraggerIcon } from '../icons-v2-generated/interface/dragger-icon';
 import { TrashIcon } from '../icons-v2-generated/interface/trash-icon';
 import { InfoCircleIcon } from '../icons-v2-generated/signs-and-symbols/info-circle-icon';
 import { Button } from './button';
 import { ColorPresetSelect, ColorPickerInput } from './color-preset-select';
 import { Input } from './input';
+import { Label } from './label';
 import type { TagProps } from './tag';
 import { TicketStatusTag } from './ticket-status-tag';
 import { TouchFriendlyTooltip } from './touch-friendly-tooltip';
@@ -31,9 +34,14 @@ export interface TicketStatusConfigRowProps {
   onDelete?: () => void;
   deleteDisabled?: boolean;
   deleteDisabledReason?: string;
-  dragHandleProps?: DraggableSyntheticListeners;
-  dragHandleAttributes?: DraggableAttributes;
+  /** From `useSortableItem` (via `TicketStatusConfigList`'s render args). */
+  dragHandleProps?: SortableDragHandleProps;
   isDragging?: boolean;
+  /**
+   * The touch replacement for the drag handle (`SortableRowRenderArgs.moveButtons`).
+   * Rendered beside the delete button; the drag rail is hidden on touch anyway.
+   */
+  moveButtons?: ReactNode;
 }
 
 export function TicketStatusConfigRow({
@@ -50,9 +58,13 @@ export function TicketStatusConfigRow({
   deleteDisabled,
   deleteDisabledReason,
   dragHandleProps,
-  dragHandleAttributes,
   isDragging,
+  moveButtons,
 }: TicketStatusConfigRowProps) {
+  // Standalone system rows render outside any SortableList, so the row answers
+  // "is there a drag rail at all?" itself — same media gate the list uses.
+  const dragAndDropEnabled = useDragAndDropEnabled();
+  const nameInputId = useId();
   const isSystem = variant === 'system';
   const isCustomColor = !isSystem && presetKey === undefined;
   const previewColor = isSystem ? undefined : color;
@@ -60,101 +72,181 @@ export function TicketStatusConfigRow({
   // Custom rows render as filled pills (no border); system rows take the
   // page-configured variant (outline/primary). text-h5 already uppercases.
   const previewVariant: SystemTagVariant | undefined = systemTagVariant ?? (isSystem ? undefined : 'primary');
-  const colClass = 'min-w-0 grow basis-[calc(50%-6px)] md:basis-0';
+
+  // The fields carry a visible label, so everything that sits beside the
+  // 44/48px field row (rail, chip, controls) drops below the label line by
+  // exactly its height: the h4 line + the label's mb-1.
+  const fieldRowOffset = 'mt-[calc(var(--font-line-space-h4-body)+0.25rem)]';
+
+  const chip = (
+    <TicketStatusTag
+      status={statusKey}
+      label={name || ' '}
+      color={previewColor}
+      variant={previewVariant}
+      showIcon={isSystem}
+      className="max-w-full"
+    />
+  );
 
   return (
     <div
       className={cn(
-        'flex w-full items-start gap-3 rounded-md border border-ods-border bg-ods-card md:gap-[var(--spacing-system-m)]',
+        // Transparent background — only the border outlines the row.
+        'flex w-full items-start gap-3 rounded-md border border-ods-border md:gap-[var(--spacing-system-m)]',
         'p-[var(--spacing-system-m)]',
-        isDragging && 'opacity-70 shadow-lg',
+        // The dragged row travels over its siblings, so it needs an opaque back.
+        isDragging && 'bg-ods-bg opacity-70 shadow-lg',
       )}
     >
-      <div className="flex h-11 w-8 shrink-0 items-center justify-center text-ods-text-secondary md:h-12">
-        {isSystem ? (
-          <DraggerIcon size={24} aria-hidden className="opacity-40" />
-        ) : (
-          <button
-            type="button"
-            aria-label="Drag to reorder"
-            className="flex size-6 cursor-grab items-center justify-center rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-ods-focus active:cursor-grabbing"
-            {...dragHandleAttributes}
-            {...dragHandleProps}
-          >
-            <DraggerIcon size={24} />
-          </button>
-        )}
-      </div>
+      {dragAndDropEnabled && (
+        <div
+          className={cn(
+            'flex h-11 w-8 shrink-0 items-center justify-center text-ods-text-secondary md:h-12',
+            fieldRowOffset,
+          )}
+        >
+          {isSystem ? (
+            <DraggerIcon size={24} aria-hidden className="opacity-40" />
+          ) : (
+            <button
+              type="button"
+              aria-label="Drag to reorder"
+              className="flex size-6 cursor-grab items-center justify-center rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-ods-focus active:cursor-grabbing"
+              {...dragHandleProps}
+            >
+              <DraggerIcon size={24} />
+            </button>
+          )}
+        </div>
+      )}
 
-      <div className="flex min-w-0 flex-1 flex-wrap items-start gap-x-3 gap-y-4 md:flex-nowrap md:gap-[var(--spacing-system-m)]">
-        <div className={cn('flex flex-col gap-[var(--spacing-system-xxs)]', colClass)}>
+      {/* Every row spans the same equal column slots — two on tablet
+          (name + color for custom, name + chip for system), four on desktop
+          (name, color, a reserved slot, chip zone) with invisible spacers
+          standing in for the cells a row doesn't use — so the name field is one
+          width on every row and the columns align across the whole list.
+          The trailing controls are a WRAP ITEM (ordered per breakpoint), not a
+          full-height sibling column, so the lower rows span the full card width
+          and the chip pins to the card's right edge on tablet/mobile. */}
+      <div
+        className={cn(
+          'min-w-0 flex-1 items-start gap-x-3 gap-y-[var(--spacing-system-m)] md:gap-x-[var(--spacing-system-m)]',
+          isSystem
+            ? 'flex flex-wrap'
+            : // Mobile custom rows are a strict two-column grid, per the mock:
+              // fields (name / color / hex, all one width) on the left, the
+              // controls and the chip stacked in the right column. From md up
+              // the same children flow as a wrapping flex row.
+              'grid grid-cols-[minmax(0,1fr)_auto] md:flex md:flex-wrap',
+        )}
+      >
+        {/* System rows keep the chip beside the name on every width, so the name
+            shares its row. */}
+        <div className="order-1 flex min-w-0 grow basis-0 flex-col gap-[var(--spacing-system-xxs)]">
+          <Label variant="large" htmlFor={nameInputId}>
+            Status Name
+          </Label>
           <Input
+            id={nameInputId}
             value={name}
             onChange={e => onNameChange?.(e.target.value)}
             disabled={isSystem}
             readOnly={isSystem}
-            aria-label="Status name"
             maxLength={50}
           />
         </div>
 
         {showColorPicker ? (
-          <div className={cn('flex', colClass)}>
+          <div className="order-3 flex min-w-0 grow basis-full flex-col gap-[var(--spacing-system-xxs)] md:order-2 md:basis-0">
+            <Label variant="large">Color</Label>
             <ColorPresetSelect value={color} presetKey={presetKey} onChange={onColorChange} />
+            {/* Custom hex: a second field row inside the Color column, directly
+                under the select (per design). */}
+            {isCustomColor && (
+              <div className="mt-[var(--spacing-system-xxs)] flex min-w-0">
+                <ColorPickerInput value={color} onChange={next => onColorChange({ color: next, preset: undefined })} />
+              </div>
+            )}
           </div>
         ) : (
-          <div aria-hidden className={cn('hidden md:block', colClass)} />
+          <div aria-hidden className="hidden min-w-0 grow basis-0 lg:order-2 lg:block" />
         )}
 
-        {showColorPicker && isCustomColor ? (
-          <div className={cn('flex', colClass)}>
-            <ColorPickerInput value={color} onChange={next => onColorChange({ color: next, preset: undefined })} />
+        {/* Reserved desktop column slot (the mock's "No activity Indicator" zone). */}
+        <div aria-hidden className="hidden min-w-0 grow basis-0 lg:order-3 lg:block" />
+
+        {isSystem ? (
+          <div
+            className={cn(
+              'order-2 flex h-11 min-w-0 grow basis-0 items-center justify-end md:h-12 lg:order-4',
+              fieldRowOffset,
+            )}
+          >
+            {chip}
           </div>
         ) : (
-          <div aria-hidden className={cn('hidden md:block', colClass)} />
+          <>
+            {/* Desktop (lg+): the chip rides the first row, in its own column
+                before the controls. */}
+            <div
+              className={cn(
+                'hidden h-12 min-w-0 grow basis-0 items-center justify-end lg:order-4 lg:flex',
+                fieldRowOffset,
+              )}
+            >
+              {chip}
+            </div>
+            {/* Tablet: the chip takes a full row of its own, pinned to the
+                card's right edge (the controls above no longer narrow it). */}
+            <div className="hidden min-w-0 basis-full items-center justify-end md:order-4 md:flex lg:hidden">
+              {chip}
+            </div>
+            {/* Mobile: the chip fills the second grid column beside the color
+                field, left-aligned with the controls above it. */}
+            <div className={cn('order-4 flex h-11 min-w-0 items-center md:hidden', fieldRowOffset)}>{chip}</div>
+          </>
         )}
 
-        <div className={cn('flex h-11 items-center justify-start md:h-12 md:justify-end', colClass)}>
-          <TicketStatusTag
-            status={statusKey}
-            label={name || ' '}
-            color={previewColor}
-            variant={previewVariant}
-            showIcon={isSystem}
-            className="max-w-full"
-          />
+        <div
+          className={cn(
+            'flex h-11 shrink-0 items-center justify-end gap-[var(--spacing-system-s)] md:h-12 lg:order-5',
+            isSystem ? 'order-3' : 'order-2 md:order-3',
+            fieldRowOffset,
+          )}
+        >
+          {!isSystem && moveButtons}
+          {isSystem ? (
+            <div className="flex w-11 justify-center md:w-12">
+              <TouchFriendlyTooltip content={systemTooltip}>
+                <button
+                  type="button"
+                  aria-label={systemTooltip ?? 'System status'}
+                  className="flex size-6 items-center justify-center text-ods-text-secondary outline-none focus-visible:ring-2 focus-visible:ring-ods-focus"
+                >
+                  <InfoCircleIcon size={24} />
+                </button>
+              </TouchFriendlyTooltip>
+            </div>
+          ) : (
+            <TouchFriendlyTooltip content={deleteDisabled ? deleteDisabledReason : undefined}>
+              <span className="inline-flex">
+                <Button
+                  type="button"
+                  variant="outline"
+                  size="icon"
+                  aria-label="Delete status"
+                  disabled={deleteDisabled}
+                  onClick={deleteDisabled ? undefined : onDelete}
+                  className={cn('size-11 md:size-12', deleteDisabled && 'pointer-events-none')}
+                >
+                  <TrashIcon className="text-ods-error" />
+                </Button>
+              </span>
+            </TouchFriendlyTooltip>
+          )}
         </div>
       </div>
-
-      <div className="flex h-11 w-12 shrink-0 items-center justify-center md:h-12">
-        {isSystem ? (
-          <TouchFriendlyTooltip content={systemTooltip}>
-            <button
-              type="button"
-              aria-label={systemTooltip ?? 'System status'}
-              className="flex size-6 items-center justify-center text-ods-text-secondary outline-none focus-visible:ring-2 focus-visible:ring-ods-focus"
-            >
-              <InfoCircleIcon size={24} />
-            </button>
-          </TouchFriendlyTooltip>
-        ) : (
-          <TouchFriendlyTooltip content={deleteDisabled ? deleteDisabledReason : undefined}>
-            <span className="inline-flex">
-              <Button
-                type="button"
-                variant="outline"
-                size="icon"
-                aria-label="Delete status"
-                disabled={deleteDisabled}
-                onClick={deleteDisabled ? undefined : onDelete}
-                className={cn('size-11 md:size-12', deleteDisabled && 'pointer-events-none')}
-              >
-                <TrashIcon className="text-ods-error" />
-              </Button>
-            </span>
-          </TouchFriendlyTooltip>
-        )}
-      </div>
     </div>
   );
 }

package/src/hooks/ui/.index.md

@@ -8,6 +8,7 @@ Barrel export file for the UI hooks library, re-exporting all custom React hooks
 | `useAutoLimitTags` | Limits visible tags based on container width |
 | `useDebounce` | Delays value updates by a specified duration |
 | `useDeferredError` | Defers error state for async workflows |
+| `useDragAndDropEnabled` | Whether DnD is initialized at all — fine pointer + hover + 800px, else touch fallbacks |
 | `useFocusTrap` | Traps keyboard focus within a DOM subtree |
 | `useHeaderHeight` | Tracks the application header's pixel height |
 | `useHorizontalScrollbar` | Detects and manages horizontal scrollbar presence |

package/src/hooks/ui/.use-drag-and-drop-enabled.md

@@ -0,0 +1,32 @@
+<!-- source-hash: manual -->
+The one rule for whether drag-and-drop is initialized anywhere in the UI. `SortableList` and
+`Board` consume it themselves, so hosts get correct touch behavior without wiring anything.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `useDragAndDropEnabled` | Hook | `true` only when `(pointer: fine) and (hover: hover) and (min-width: 800px)` matches |
+| `DRAG_AND_DROP_MEDIA_QUERY` | Const | The query itself, composed from `breakpoints.md` — no new breakpoint |
+
+## Why pointer type AND breakpoint
+
+- A breakpoint alone fails on tablets: an iPad in landscape is 1024-1366px wide and would pass any
+  sane `min-width` — exactly the case being excluded, because the HTML5 drag-and-drop API Pragmatic
+  builds on does not fire under touch.
+- `pointer: coarse` alone fails the other way: a touchscreen laptop with a trackpad reports
+  `pointer: fine` and should keep DnD, but in a narrow window its lists collapse to the mobile
+  layout where a drag handle is out of place.
+- No `'ontouchstart' in window`, no UA sniffing: the first is true on touch laptops, the second is
+  neither accurate nor reactive. A media query re-evaluates live when a mouse is attached or the
+  window resizes.
+
+## SSR
+
+Returns `false` during SSR and the first client render (`useMediaQuery` is still `undefined`):
+DnD off means no dead drag handle in server HTML, and the layout effect settles the real answer
+before first paint, so a desktop user never sees the touch fallback flash.
+
+## Source
+
+[`use-drag-and-drop-enabled.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-drag-and-drop-enabled.ts)

package/src/hooks/ui/index.ts

@@ -2,6 +2,7 @@
 export * from './use-auto-limit-tags';
 export * from './use-debounce';
 export * from './use-deferred-error';
+export * from './use-drag-and-drop-enabled';
 export * from './use-focus-trap';
 export * from './use-header-height';
 export * from './use-horizontal-scrollbar';

package/src/hooks/ui/use-drag-and-drop-enabled.ts

@@ -0,0 +1,37 @@
+'use client';
+
+import { breakpoints, useMediaQuery } from './use-media-query';
+
+/**
+ * The one rule for whether drag-and-drop is initialized at all.
+ *
+ * Pointer type AND breakpoint, never either alone:
+ * - A breakpoint alone fails on tablets: an iPad in landscape is 1024-1366px
+ *   wide and would pass any sane `min-width` — exactly the case being excluded,
+ *   because the HTML5 drag-and-drop API Pragmatic builds on does not fire under
+ *   touch.
+ * - `pointer: coarse` alone fails the other way: a touchscreen laptop with a
+ *   trackpad reports `pointer: fine` and should keep DnD, but in a narrow
+ *   window its lists collapse to the mobile layout where a drag handle is out
+ *   of place.
+ * - No `'ontouchstart' in window`, no UA sniffing: the first is true on touch
+ *   laptops, the second is neither accurate nor reactive. A media query
+ *   re-evaluates live when a mouse is attached or the window resizes.
+ *
+ * `breakpoints.md` (800px) is the existing tablet step — no new breakpoint.
+ */
+export const DRAG_AND_DROP_MEDIA_QUERY = `(pointer: fine) and (hover: hover) and ${breakpoints.md}`;
+
+/**
+ * Whether drag-and-drop should be available on this device/viewport.
+ *
+ * `false` on touch/narrow screens — there the reordering surfaces render
+ * explicit controls (`SortableMoveButtons`) instead of a drag handle, and no
+ * DnD is initialized at all. Also `false` during SSR and the first client
+ * render (`useMediaQuery` is still `undefined`): defaulting to "off" renders
+ * no dead drag handle, and the underlying layout effect settles the real
+ * answer before first paint, so a desktop user never sees the fallback flash.
+ */
+export function useDragAndDropEnabled(): boolean {
+  return useMediaQuery(DRAG_AND_DROP_MEDIA_QUERY) ?? false;
+}

package/src/hooks/ui/use-media-query.ts

@@ -1,6 +1,7 @@
 'use client';
 
-import { useLayoutEffect, useState } from 'react';
+import { useState } from 'react';
+import { useIsomorphicLayoutEffect } from './use-isomorphic-layout-effect';
 
 /**
  * Hook to check if a media query matches
@@ -10,7 +11,7 @@ import { useLayoutEffect, useState } from 'react';
 export function useMediaQuery(query: string): boolean | undefined {
   const [matches, setMatches] = useState<boolean | undefined>(undefined);
 
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     const matchMedia = window.matchMedia(query);
 
     const handleChange = () => {

package/src/utils/.content-href.md

@@ -15,7 +15,7 @@ Unified content-href authority for all embeddable surfaces — resolves content
 
 ### Functions
 
-- **`makeComposeContentUrl(opts)`** — Factory that builds the embedder's `composeContentUrl`. Resolution order: explicit `overrides` → hosted in-app route → verbatim `externalUrl` → hub-origin fallback.
+- **`makeComposeContentUrl(opts)`** — Factory that builds the embedder's `composeContentUrl`. Resolution order: explicit `overrides` → hosted in-app route → verbatim `externalUrl` → hub-origin fallback. Only the `overrides` branch returns `hostOverride: true`; fetch-mode chat cards rank that above the fetched row's own url (`pickFetchedCardHref`), and everything else below it.
 - **`buildDefaultHref(basePath, slug)`** — Fallback href when no `composeContentUrl` is wired (single-platform embedders).
 - **`resolveContentHref(composeContentUrl, args)`** — Ternary helper used by catalog/detail views: delegates to `composeContentUrl` when wired, otherwise calls `buildDefaultHref`.
 

package/src/utils/__tests__/content-href.test.ts

@@ -188,6 +188,9 @@ describe('makeComposeContentUrl (unified single-object seam)', () => {
     expect(c({ type: 'product_release', identifier: 'v2', externalUrl: `${HUB}/releases/v2` })).toEqual({
       href: '/custom/v2',
       targetPlatform: 'openframe',
+      // Only this branch is flagged — fetch-mode cards rank it above the
+      // fetched row's own url (`pickFetchedCardHref`).
+      hostOverride: true,
     });
   });
 

package/src/utils/content-href.ts

@@ -112,10 +112,34 @@ export interface ContentHrefOptions {
   overrides?: Record<string, (identifier: string) => { href: string; targetPlatform: string | null }>;
 }
 
+/** What the seam resolves a content reference to. */
+export interface ComposedContentUrl {
+  href: string;
+  targetPlatform: string | null;
+  /**
+   * Set ONLY when the href came from the host's EXPLICIT per-type `overrides`
+   * entry — i.e. the host stated where this type lives in ITS app, rather than
+   * the composer falling through to a hosted-suffix or `<origin>/<type>/<id>`
+   * synthesis.
+   *
+   * The distinction is load-bearing for fetch-mode chat cards whose fetched row
+   * already carries a destination (`refHydratedEntry`'s `item.url`, minted by
+   * the CONTENT HOST for its OWN surface). That url must beat a synthesized
+   * guess, but must NOT beat a host that has explicitly re-homed the type:
+   * a HubSpot ticket's `item.url` is the hub's `/tickets?ticket=…`, which in an
+   * embedder that serves the same ticket at `/help-center/tickets` silently
+   * resolves against the embedder's own unrelated `/tickets` route.
+   *
+   * Optional and absent by default, so a hand-written composer (the hub's
+   * cross-platform one) keeps the pre-existing "row url wins" behavior.
+   */
+  hostOverride?: boolean;
+}
+
 /** The unified `composeContentUrl` seam shape on `ChatRuntime`. ALWAYS returns
  *  a tuple (never null) — the seam type is non-nullable and callers read
  *  `.href` unconditionally. */
-export type ComposeContentUrl = (input: ComposeContentUrlInput) => { href: string; targetPlatform: string | null };
+export type ComposeContentUrl = (input: ComposeContentUrlInput) => ComposedContentUrl;
 
 /**
  * Owning platform of a content row, from the hydrated junction the list APIs
@@ -162,7 +186,8 @@ function lastPathSegment(url: string): string | null {
  * Build the embedder's `composeContentUrl` for the unified seam.
  *
  * Resolution order (the merged rule used by BOTH page views and chat cards):
- *   1. `overrides[type]` — explicit per-type href.
+ *   1. `overrides[type]` — explicit per-type href, returned with
+ *      `hostOverride: true` (the only branch that sets it).
  *   2. `hostedTypes.has(type)` → relative `/<suffix>/<slug>` (in-app, soft-nav).
  *      Chat rows carry the hub URL not the slug, so the slug is recovered from
  *      `externalUrl`; page views pass the slug as `identifier`.
@@ -184,7 +209,9 @@ export function makeComposeContentUrl(opts: ContentHrefOptions): ComposeContentU
     const type = canonicalContentRefType(rawType);
     const override =
       opts.overrides && Object.prototype.hasOwnProperty.call(opts.overrides, type) ? opts.overrides[type] : undefined;
-    if (override) return override(identifier);
+    // Flagged as an explicit host decision — see `ComposedContentUrl.hostOverride`
+    // for why a fetch-mode card has to tell this apart from the branches below.
+    if (override) return { ...override(identifier), hostOverride: true };
 
     const seg = (Object.prototype.hasOwnProperty.call(suffixes, type) ? suffixes[type] : undefined) ?? type;
 

package/src/utils/index.ts

@@ -340,6 +340,7 @@ export {
   buildDefaultHref,
   type ContentHrefOptions,
   type ComposeContentUrl,
+  type ComposedContentUrl,
 } from './content-href';
 
 // Invisible bot-protection signals (honeypot + timing) — pure + server-safe so