@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/app/composables/useChartTickPlan.ts

@@ -0,0 +1,186 @@
+import type { MaybeRefOrGetter } from 'vue'
+import { computed, toValue } from 'vue'
+import { DISPLAY_LOCALE, parseReportingDay } from './formatting'
+
+// Calendar-aware tick planning for time-series charts. Picks tick positions +
+// label format based on the span:
+//   ≤ 10 days   → every day, "Mon 12"
+//   ≤ 35 days   → ~5 evenly-spaced ticks, "Jan 12"
+//   ≤ 120 days  → every ~2 weeks (aligned to data), "Jan 12"
+//   > 120 days  → first-of-month ticks, "Jan"; year suffix on Jan/first when span spans years
+// Extracted from ProGraphGsc / ProGraphAnalytics / GraphIndexing, which had
+// identical copies of this logic.
+
+export interface ChartTickPlan {
+  indices: number[]
+  format: (date: Date, i: number, firstYear: number) => string
+}
+
+export interface UseChartTickPlanOptions {
+  /** Reactive ISO date strings (one per data point). */
+  dates: MaybeRefOrGetter<string[]>
+  /** Cap on tick count for long spans (default 14 — thins to ~12 if exceeded). */
+  maxTicks?: number
+  /**
+   * Reactive plot-area width in px (wire `useElementSize` on the chart wrap).
+   * The span heuristics assume a desktop-width plot; when a width is known,
+   * ticks whose estimated labels would collide are dropped — first and last
+   * always stay, so the consumers' inward-anchored edge labels keep marking
+   * the window ends. Unknown (0/undefined, e.g. SSR before measurement)
+   * keeps the pure span plan.
+   */
+  width?: MaybeRefOrGetter<number | undefined>
+}
+
+// Ticks label reporting-day buckets ("YYYY-MM-DD"), not instants — force UTC so
+// the label never drifts with the viewer's timezone (cf. parseReportingDay, ADR-0082).
+const weekdayDayFmt = new Intl.DateTimeFormat(DISPLAY_LOCALE, { weekday: 'short', day: 'numeric', timeZone: 'UTC' })
+const monthDayFmt = new Intl.DateTimeFormat(DISPLAY_LOCALE, { month: 'short', day: 'numeric', timeZone: 'UTC' })
+const monthFmt = new Intl.DateTimeFormat(DISPLAY_LOCALE, { month: 'short', timeZone: 'UTC' })
+const monthYearFmt = new Intl.DateTimeFormat(DISPLAY_LOCALE, { month: 'short', year: '2-digit', timeZone: 'UTC' })
+
+// Axis labels render at 11px; ~6.5px per glyph over-estimates the real advance
+// slightly, so thinning leaves visible air instead of touching labels.
+const LABEL_GLYPH_PX = 6.5
+const MIN_LABEL_GAP_PX = 8
+
+/**
+ * Greedy left-to-right thinning: a tick survives only when its label clears the
+ * previously kept one. Every consumer anchors the first tick inward (start) and
+ * the last (end), so those labels claim their full width on the inner side;
+ * middle labels claim half a width each side. The final tick always renders —
+ * middle ticks yield to it when the two would collide.
+ */
+function fitTickIndices(
+  indices: number[],
+  labelWidth: (index: number) => number,
+  posOf: (index: number) => number,
+): number[] {
+  if (indices.length <= 2)
+    return indices.slice()
+  const fits = (a: number, b: number, aIsFirst: boolean, bIsLast: boolean): boolean => {
+    const aRight = posOf(a) + labelWidth(a) / (aIsFirst ? 1 : 2)
+    const bLeft = posOf(b) - labelWidth(b) / (bIsLast ? 1 : 2)
+    return bLeft - aRight >= MIN_LABEL_GAP_PX
+  }
+  const kept: number[] = [indices[0]!]
+  for (let k = 1; k < indices.length - 1; k++) {
+    const idx = indices[k]!
+    if (fits(kept.at(-1)!, idx, kept.length === 1, false))
+      kept.push(idx)
+  }
+  const last = indices.at(-1)!
+  while (kept.length > 1 && !fits(kept.at(-1)!, last, kept.length === 1, true))
+    kept.pop()
+  kept.push(last)
+  return kept
+}
+
+export function useChartTickPlan(opts: UseChartTickPlanOptions) {
+  const maxTicks = opts.maxTicks ?? 14
+
+  function spanPlan(dates: string[], len: number): ChartTickPlan {
+    if (len <= 1)
+      return { indices: [0], format: d => monthDayFmt.format(d) }
+    if (len <= 10)
+      return { indices: dates.map((_, i) => i), format: d => weekdayDayFmt.format(d) }
+    if (len <= 35) {
+      const step = Math.max(1, Math.ceil(len / 5))
+      const indices: number[] = []
+      for (let i = 0; i < len; i += step) indices.push(i)
+      if (indices.at(-1) !== len - 1)
+        indices.push(len - 1)
+      return { indices, format: d => monthDayFmt.format(d) }
+    }
+    if (len <= 120) {
+      // Anchor at index 0 (chart left edge) and step by 14 days. Earlier
+      // Monday-snap variant pushed the first tick rightward, leaving the
+      // leftmost label visually detached from the data start.
+      const indices: number[] = []
+      for (let i = 0; i < len; i += 14) indices.push(i)
+      return { indices, format: d => monthDayFmt.format(d) }
+    }
+
+    // Long span: first-of-month ticks.
+    const indices: number[] = []
+    let lastMonth = ''
+    for (let i = 0; i < len; i++) {
+      const m = dates[i]?.slice(0, 7) ?? ''
+      if (m !== lastMonth) {
+        indices.push(i)
+        lastMonth = m
+      }
+    }
+    if (indices.length < 2)
+      return { indices: [0, Math.floor(len / 2), len - 1], format: d => monthDayFmt.format(d) }
+    // Drop the first tick if the second is within 5 days — happens when the
+    // series starts late in a month and the next month's first-of-month tick
+    // would render right on top of it.
+    if (indices.length > 2 && indices[1]! - indices[0]! < 5)
+      indices.shift()
+
+    // Thin out at very long spans so the axis doesn't crowd.
+    if (indices.length > maxTicks) {
+      const keep = Math.ceil(indices.length / 12)
+      return {
+        indices: indices.filter((_, i) => i % keep === 0),
+        format: (d, i, firstYear) => (d.getUTCMonth() === 0 || i === 0) && d.getUTCFullYear() !== firstYear
+          ? monthYearFmt.format(d)
+          : monthFmt.format(d),
+      }
+    }
+    return {
+      indices,
+      format: (d, i, _firstYear) => (d.getUTCMonth() === 0 && i > 0) || (i === 0 && d.getUTCMonth() !== 0 && indices.length > 6)
+        ? monthYearFmt.format(d)
+        : monthFmt.format(d),
+    }
+  }
+
+  const tickPlan = computed<ChartTickPlan>(() => {
+    const dates = toValue(opts.dates)
+    const len = dates.length
+    const base = spanPlan(dates, len)
+
+    const width = toValue(opts.width)
+    if (!width || width <= 0 || len < 3 || base.indices.length <= 2)
+      return base
+
+    // Estimate each label's pixel width from the plan's own formatting so the
+    // pass tracks whichever branch ran. `i`/`firstYear` only steer the
+    // month-vs-monthYear choice — an estimate, not a render.
+    const firstYear = Number(dates[base.indices[0]!]?.slice(0, 4) ?? 0)
+    const labelWidth = (idx: number): number => {
+      const date = dates[idx]
+      if (!date)
+        return 0
+      const label = base.format(parseReportingDay(date), base.indices.indexOf(idx), firstYear)
+      return label.length * LABEL_GLYPH_PX
+    }
+    const posOf = (idx: number): number => idx / (len - 1) * width
+    return { indices: fitTickIndices(base.indices, labelWidth, posOf), format: base.format }
+  })
+
+  const firstTickYear = computed(() => {
+    const dates = toValue(opts.dates)
+    const first = tickPlan.value.indices[0]
+    // No ticks → `format` never runs, so a stable sentinel (not a clock read,
+    // which would risk an SSR≠client year boundary) is enough.
+    if (first == null || !dates[first])
+      return 0
+    return Number(dates[first]!.slice(0, 4))
+  })
+
+  /** Use as Unovis `tickFormat` for an x-axis indexed by row position. */
+  function tickFormat(d: number): string {
+    const dates = toValue(opts.dates)
+    const idx = Math.round(d)
+    const date = dates[idx]
+    if (!date)
+      return ''
+    const tickIdx = tickPlan.value.indices.indexOf(idx)
+    return tickPlan.value.format(parseReportingDay(date), tickIdx, firstTickYear.value)
+  }
+
+  return { tickPlan, firstTickYear, tickFormat }
+}

package/app/composables/useCloseOnNavigation.ts

@@ -0,0 +1,7 @@
+import type { WatchSource, WatchStopHandle } from 'vue'
+import { watch } from 'vue'
+
+/** Close persistent overlay state after a confirmed client route change. */
+export function useCloseOnNavigation(fullPath: WatchSource<string>, close: () => void): WatchStopHandle {
+  return watch(fullPath, close)
+}

package/app/composables/useConfirm.ts

@@ -0,0 +1,38 @@
+import { useOverlay } from '#imports'
+import UiConfirmDialog from '../components/element/UiConfirmDialog.vue'
+
+/** `danger` for an action that destroys or revokes; `default` for any other. */
+export type ConfirmTone = 'danger' | 'default'
+
+export interface ConfirmOptions {
+  /** A question that names the action and its object: "Disconnect Google?" */
+  readonly title: string
+  /** The consequence, in one or two short sentences. */
+  readonly description?: string
+  /** A verb for the action: "Disconnect", "Remove", "Delete". Never "OK". */
+  readonly confirmLabel: string
+  readonly cancelLabel?: string
+  readonly tone?: ConfirmTone
+}
+
+/**
+ * Ask before an action that is hard to undo.
+ *
+ * ```ts
+ * const confirm = useConfirm()
+ * if (!await confirm({ title: 'Remove teammate?', confirmLabel: 'Remove', tone: 'danger' }))
+ *   return
+ * ```
+ *
+ * Resolves `true` only for the confirm button. Cancel, Escape, and a click
+ * outside resolve `false`. Call it in `setup`; the returned function may run
+ * any time later. Needs `<UApp>`, which mounts Nuxt UI's overlay provider.
+ */
+export function useConfirm(): (options: ConfirmOptions) => Promise<boolean> {
+  const overlay = useOverlay()
+  // One overlay per question: `destroyOnClose` removes it after it leaves, so
+  // a page that asks many times holds no dialog it is not showing.
+  return options => overlay.create(UiConfirmDialog, { destroyOnClose: true })
+    .open({ ...options })
+    .then(result => result === true)
+}

package/app/composables/useEdgeFade.ts

@@ -0,0 +1,37 @@
+import type { Ref } from 'vue'
+import { useEventListener, useResizeObserver } from '@vueuse/core'
+import { onMounted, ref } from 'vue'
+
+/**
+ * Edge-fade affordance for a horizontal scroller: reports which side still has
+ * content off-screen. Bind the result to `data-fade-start` / `data-fade-end` on
+ * an element carrying the `.ui-edge-fade` class (`css/global.css`), which masks
+ * only the side that can scroll. The flags clear when the content fits, so a
+ * wide viewport never masks.
+ *
+ * Shared by `UiTabs` and the `ProDataToolbar` metric row, so every scrolling
+ * strip in the product fades the same way.
+ */
+export function useEdgeFade(el: Ref<HTMLElement | undefined | null>, onResize?: () => void) {
+  const fadeStart = ref(false)
+  const fadeEnd = ref(false)
+
+  function update() {
+    const node = el.value
+    if (!node)
+      return
+    fadeStart.value = node.scrollLeft > 1
+    fadeEnd.value = Math.ceil(node.scrollLeft + node.clientWidth) < node.scrollWidth - 1
+  }
+
+  onMounted(() => {
+    useEventListener(el, 'scroll', update, { passive: true })
+    useResizeObserver(el, () => {
+      update()
+      onResize?.()
+    })
+    update()
+  })
+
+  return { fadeStart, fadeEnd, update }
+}

package/app/composables/useEject.ts

@@ -0,0 +1,69 @@
+import type { ComputedRef, MaybeRefOrGetter } from 'vue'
+import type { RouteLocationRaw } from 'vue-router'
+import type { ChatEntityRef, EjectChat, EjectLink, EjectMcp } from '../components/element/eject-menu'
+import { computed, toValue } from 'vue'
+
+/**
+ * Schema-shaped description of a queryable surface.
+ *
+ * VISION principle 5: every feature is defined by a typed schema before it ships a UI.
+ * `useEject` is the spine that turns that schema into the eject payloads
+ * (MCP call, AI chat, API schema link) so consumers don't hand-roll each one.
+ * It builds no cURL payload. DESIGN "Portable by default" allows one, because
+ * the public documented REST API is live at `/docs/api/openapi.json`.
+ *
+ * The composable is dumb plumbing. It does no fetching, no auth resolution, no
+ * runtime config reading; the caller passes the schema reference and the
+ * entity/filter context. The result feeds directly into `<UiEjectMenu />` props.
+ */
+export interface EjectQuery {
+  /** MCP tool name. Required for MCP + AI chat ejection. */
+  tool: string
+  /** Tool arguments, serialised as MCP `arguments` on copy. */
+  args?: Record<string, unknown>
+  /** Deep-link target for AI chat ejection (path + optional query base). */
+  chatTo?: RouteLocationRaw
+  /** Entity ID seeded into chat deep links — build via `chatEntity.*`. */
+  entity?: ChatEntityRef
+  /** Filter state seeded into chat deep links. */
+  filter?: Record<string, unknown>
+  /** Question seed text for chat. */
+  seed?: string
+  /** Schema doc link. */
+  schemaTo?: RouteLocationRaw
+  /** Custom schema link label. */
+  schemaLabel?: string
+}
+
+export interface EjectPayloads {
+  mcp: ComputedRef<EjectMcp | undefined>
+  chat: ComputedRef<EjectChat | undefined>
+  schema: ComputedRef<EjectLink | undefined>
+}
+
+export function useEject(query: MaybeRefOrGetter<EjectQuery>): EjectPayloads {
+  const q = computed(() => toValue(query))
+
+  return {
+    mcp: computed(() =>
+      q.value.tool
+        ? { tool: q.value.tool, args: q.value.args }
+        : undefined,
+    ),
+    chat: computed(() =>
+      q.value.chatTo
+        ? {
+            to: q.value.chatTo,
+            entity: q.value.entity,
+            filter: q.value.filter,
+            seed: q.value.seed,
+          }
+        : undefined,
+    ),
+    schema: computed(() =>
+      q.value.schemaTo
+        ? { to: q.value.schemaTo, label: q.value.schemaLabel }
+        : undefined,
+    ),
+  }
+}

package/app/composables/useEntranceMotion.ts

@@ -0,0 +1,22 @@
+import type { ComputedRef, MaybeRefOrGetter } from 'vue'
+import type { EntrancePreset } from '../../shared/motion'
+import { useReducedMotion } from 'motion-v'
+import { tryUseNuxtApp } from 'nuxt/app'
+import { computed, toValue } from 'vue'
+import { entranceProps } from '../../shared/motion'
+
+/**
+ * motion-v entrance props for an `<m.*>` root, with content visible by default.
+ *
+ * The server cannot read `prefers-reduced-motion`, and Vue keeps server styles
+ * through hydration. An entrance bound on the server therefore ships the hidden
+ * `initial` frame, and a reduced-motion reader never sees the content. So the
+ * server render and the hydration pass bind nothing. Only an element the client
+ * mounts after hydration animates in.
+ */
+export function useEntranceMotion(preset: EntrancePreset, enabled: MaybeRefOrGetter<boolean> = true): ComputedRef<ReturnType<typeof entranceProps>> {
+  const reduced = useReducedMotion()
+  const nuxtApp = tryUseNuxtApp()
+  const renderedOnServer = import.meta.server || Boolean(nuxtApp?.ssrContext) || Boolean(nuxtApp?.isHydrating)
+  return computed(() => toValue(enabled) && !renderedOnServer ? entranceProps(preset, reduced.value) : {})
+}

package/app/composables/useFaviconBacking.ts

@@ -0,0 +1,164 @@
+import { computed, onMounted, ref, watch } from 'vue'
+import { useColorMode } from '#imports'
+
+/**
+ * Adaptive favicon backing. Many real favicons (zhead's dark triangle, GitHub's
+ * octocat, Vercel's near-black square) carry no usable contrast against one of the
+ * two dashboard themes and visually vanish. Rather than blanket every favicon with
+ * a light tile (which would needlessly flatten brand-colour favicons), we sample
+ * each favicon's dominant luminance once and only add a tile in the theme where it
+ * would otherwise disappear.
+ *
+ * Sampling requires a canvas read, so the favicon MUST be same-origin — UiFavicon
+ * serves it through `/api/favicon` for exactly this reason. A cross-origin image
+ * taints the canvas and `getImageData` throws; we treat that as `unknown` (no
+ * backing) so the component still renders, just without the adaptive remedy.
+ */
+export type FaviconTone = 'dark' | 'light' | 'neutral' | 'unknown'
+export type FaviconBacking = 'light' | 'dark' | 'none'
+
+// Dominant luminance below DARK reads as "dark ink/fill" (needs a light tile on
+// dark themes); above LIGHT reads as "light ink" (needs a dark tile on light
+// themes). The wide neutral band keeps colourful favicons (Stripe, Cloudflare,
+// npm) untouched on both themes.
+const DARK = 0.22
+const LIGHT = 0.8
+
+// Per-domain memo: sample at most once per domain per session and persist
+// across sessions to avoid a backing flash.
+//
+// The persisted half now EXPIRES, because a domain's classification is no
+// longer stable for all time. `/api/favicon` used to answer from Google's copy,
+// which never changed; it now serves the mark the Crawl captured, so a Site
+// that rebrands from a dark glyph to a light one changes which tile it needs.
+// Without an expiry a returning viewer would keep the wrong backing for good,
+// and a stored tone is only a flash-avoidance optimisation, never a fact worth
+// defending.
+const memo = new Map<string, FaviconTone>()
+const LS_KEY = 'ui-favicon-tone-v2'
+const MEMO_TTL_MS = 7 * 24 * 60 * 60 * 1000
+interface StoredMemo { at: number, tones: Record<string, FaviconTone> }
+let hydrated = false
+
+function hydrate() {
+  if (hydrated || !import.meta.client)
+    return
+  hydrated = true
+  try {
+    const stored = JSON.parse(localStorage.getItem(LS_KEY) ?? 'null') as StoredMemo | null
+    if (!stored || Date.now() - stored.at >= MEMO_TTL_MS)
+      return
+    for (const [k, v] of Object.entries(stored.tones)) memo.set(k, v)
+  }
+  catch {
+    // Corrupt cache is not worth surfacing; fall back to re-sampling.
+  }
+}
+
+function persist() {
+  if (!import.meta.client)
+    return
+  try {
+    localStorage.setItem(LS_KEY, JSON.stringify({ at: Date.now(), tones: Object.fromEntries(memo) } satisfies StoredMemo))
+  }
+  catch {
+    // Storage full / disabled — sampling still works, just not cached cross-session.
+  }
+}
+
+function classifyTone(img: HTMLImageElement): FaviconTone {
+  const n = 32
+  const canvas = document.createElement('canvas')
+  canvas.width = n
+  canvas.height = n
+  const ctx = canvas.getContext('2d', { willReadFrequently: true })
+  if (!ctx)
+    return 'unknown'
+  ctx.drawImage(img, 0, 0, n, n)
+
+  let data: Uint8ClampedArray
+  try {
+    data = ctx.getImageData(0, 0, n, n).data
+  }
+  catch {
+    return 'unknown' // tainted canvas (cross-origin favicon)
+  }
+
+  // Mean relative luminance over the visible ink, weighted by alpha so soft
+  // edges don't drag a solid glyph toward neutral.
+  let lumSum = 0
+  let alphaSum = 0
+  for (let i = 0; i < data.length; i += 4) {
+    const a = data[i + 3] ?? 0
+    if (a < 16)
+      continue
+    const r = data[i] ?? 0
+    const g = data[i + 1] ?? 0
+    const b = data[i + 2] ?? 0
+    const l = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255
+    lumSum += l * a
+    alphaSum += a
+  }
+  if (alphaSum === 0)
+    return 'unknown' // fully transparent / empty
+  const meanLum = lumSum / alphaSum
+  if (meanLum < DARK)
+    return 'dark'
+  if (meanLum > LIGHT)
+    return 'light'
+  return 'neutral'
+}
+
+export function useFaviconBacking(domain: () => string) {
+  // Start 'unknown' on both server and first client render so SSR HTML and
+  // hydration agree; only read the cross-session cache after mount. Otherwise a
+  // cached tone would diverge from the server's 'unknown' → favicon-tile
+  // hydration mismatch.
+  const tone = ref<FaviconTone>('unknown')
+  onMounted(() => {
+    hydrate()
+    tone.value = memo.get(domain()) ?? 'unknown'
+  })
+  watch(domain, d => (tone.value = memo.get(d) ?? 'unknown'))
+
+  /**
+   * Classify the favicon `image` and remember the result for its domain.
+   *
+   * Takes the element, never a `load` event. A cached favicon is `complete`
+   * before hydration, so no `load` event fires and the caller samples it after
+   * mount instead.
+   */
+  function sample(image: HTMLImageElement) {
+    const key = domain()
+    const cached = memo.get(key)
+    if (cached) {
+      tone.value = cached
+      return
+    }
+    // An image the browser has not decoded carries no pixels. Sampling it would
+    // remember a blank canvas as this domain's tone for the whole session.
+    if (!image.naturalWidth || !image.naturalHeight)
+      return
+    const t = classifyTone(image)
+    memo.set(key, t)
+    persist()
+    tone.value = t
+  }
+
+  const colorMode = useColorMode()
+  const backing = computed<FaviconBacking>(() => {
+    const isDark = colorMode.value === 'dark'
+    // We only ever add the tile in the theme where the favicon would vanish; in
+    // the other theme its native contrast is fine, so we leave it bare and keep
+    // any brand colour. The tile uses `bg-inverted`, which resolves to the right
+    // shade automatically: white on dark themes, dark on light themes — i.e.
+    // exactly the surface a vanishing favicon needs in the theme we apply it.
+    if (tone.value === 'dark')
+      return isDark ? 'light' : 'none'
+    if (tone.value === 'light')
+      return isDark ? 'none' : 'dark'
+    return 'none'
+  })
+
+  return { backing, sample }
+}

package/app/composables/useGridCols.ts

@@ -0,0 +1,39 @@
+import type { ComputedRef, Ref } from 'vue'
+import { computed } from 'vue'
+
+export interface GridColsOptions {
+  /**
+   * Lets each metric column shrink to this width, so the label column keeps
+   * `minLabelWidth`. Without it, metric columns stay at their fixed width.
+   */
+  minColWidth?: string
+  /** The narrowest the label column gets once metric columns can shrink. Default `8rem`. */
+  minLabelWidth?: string
+}
+
+function buildGridCols(colCount: number, options: GridColsOptions = {}): string {
+  if (colCount <= 0)
+    colCount = 1
+
+  const colWidth = colCount <= 2 ? '200px' : '160px'
+  const track = options.minColWidth ? `minmax(${options.minColWidth}, ${colWidth})` : colWidth
+  const label = options.minColWidth ? `minmax(${options.minLabelWidth ?? '8rem'}, 1fr)` : '1fr'
+
+  const middle = colCount === 1
+    ? track
+    : Array.from({ length: colCount }).fill(track).join(' 8px ')
+
+  return `48px ${label} ${middle} 60px`
+}
+
+export function useGridCols(
+  columnCount: Ref<number> | ComputedRef<number>,
+  fallbackClass?: Ref<string | false | undefined> | ComputedRef<string | false | undefined>,
+  options?: GridColsOptions,
+): ComputedRef<string> {
+  return computed(() => {
+    if (fallbackClass?.value)
+      return fallbackClass.value
+    return buildGridCols(columnCount.value, options)
+  })
+}

package/app/composables/useIssueOverlay.ts

@@ -0,0 +1,43 @@
+import { useState } from 'nuxt/app'
+
+/**
+ * useIssueOverlay — the layer-agnostic trigger for the in-place issue detail
+ * (Q1, 2026-06). Feature-page related-work strips open a single issue's act-surface
+ * modal without navigating to the board; only the strip's "View all" navigates.
+ *
+ * Why it lives in design-system, not pro-actions: ADR-0042 forbids feature
+ * layers (pro-perf / pro-gsc / pro-dataforseo) from importing pro-actions
+ * runtime. So the trigger is a generic `useState` channel here (which every
+ * layer may import), and pro-actions owns the host (`ProIssueOverlayHost`) that
+ * reads this state and renders the actual `ProActionRow` modal. The action
+ * is carried opaquely (`unknown`) so design-system never learns the BoardAction
+ * shape — the host casts it back.
+ */
+
+export interface IssueOverlayRequest {
+  /** The full board action (opaque here; the pro-actions host casts it). */
+  action: unknown
+  siteId: string
+  /** Cross-site label when opened from the portfolio surface. */
+  siteName?: string
+  /** Bare host (no scheme) for the Work Prompt / MCP call — omitted falls back to "my site". */
+  siteHost?: string
+  /** Query keys the modal invalidates on a mutation (the caller's related read). */
+  invalidateKeys?: string[]
+  /** Bumped per open so the host re-triggers even for the same action. */
+  nonce: number
+}
+
+/** The shared overlay channel — read by the host, written by `open`. */
+export function useIssueOverlayState() {
+  return useState<IssueOverlayRequest | null>('pro:issue-overlay', () => null)
+}
+
+export function useIssueOverlay() {
+  const state = useIssueOverlayState()
+  return {
+    open(req: { action: unknown, siteId: string, siteName?: string, siteHost?: string, invalidateKeys?: string[] }) {
+      state.value = { ...req, nonce: (state.value?.nonce ?? 0) + 1 }
+    },
+  }
+}