@astrale-os/shell-react 0.1.0

package/src/intents/send-intent.hook.ts

@@ -0,0 +1,111 @@
+import type { IntentMessage, IntentRegistry, Shell } from '@astrale-os/shell'
+
+/**
+ * useSendIntent (API §11) — a stable typed sender. Each call attaches a
+ * `correlationId`, subscribes for the matching `intentReply` on the origin channel
+ * BEFORE sending, then resolves with the reply's result. The promise also resolves
+ * (`void`) if the target window closes or this hook unmounts — a pending reply
+ * never strands.
+ */
+import { useCallback, useEffect, useRef } from 'react'
+
+import type { IntentPayload, IntentReply } from './envelope'
+
+import { useShell } from '../session/shell.hook'
+import { INTENT_REPLY, NOOP, intentMessage } from './envelope'
+
+/** The typed sender returned by {@link useSendIntent}. */
+export interface SendIntent {
+  <K extends keyof IntentRegistry>(
+    name: K,
+    payload: IntentPayload<K>,
+    /** `to`: `'parent'` (reserved) or a child windowId. Default: the parent, if any. */
+    opts?: { to?: 'parent' | string },
+  ): Promise<IntentReply<K> | void>
+}
+
+type Target =
+  | { readonly kind: 'parent' }
+  | { readonly kind: 'child'; readonly windowId: string }
+  | { readonly kind: 'invalid'; readonly reason: string }
+
+function resolveTarget(shell: Shell, to: string | undefined): Target {
+  if (to === undefined) {
+    return shell.parent !== null
+      ? { kind: 'parent' }
+      : { kind: 'invalid', reason: 'no target — pass opts.to (a child windowId) from a root shell' }
+  }
+  if (to === 'parent') {
+    return shell.parent !== null
+      ? { kind: 'parent' }
+      : { kind: 'invalid', reason: "opts.to 'parent' but this shell has no parent channel" }
+  }
+  return { kind: 'child', windowId: to }
+}
+
+export function useSendIntent(): SendIntent {
+  const shell = useShell()
+  // Unmount settlers for in-flight sends, so a pending reply resolves on teardown.
+  const pendingRef = useRef<Set<() => void>>(new Set())
+  useEffect(() => {
+    const pending = pendingRef.current
+    return () => {
+      for (const settle of pending) settle()
+      pending.clear()
+    }
+  }, [])
+
+  return useCallback(
+    <K extends keyof IntentRegistry>(
+      name: K,
+      payload: IntentPayload<K>,
+      opts?: { to?: 'parent' | string },
+    ): Promise<IntentReply<K> | void> => {
+      const target = resolveTarget(shell, opts?.to)
+      if (target.kind === 'invalid') {
+        return Promise.reject(new Error(`useSendIntent: ${target.reason}`))
+      }
+      const correlationId = crypto.randomUUID()
+      const message = intentMessage(name, payload, correlationId)
+      const pending = pendingRef.current
+
+      return new Promise<IntentReply<K> | void>((resolve) => {
+        let done = false
+        let offReply = NOOP
+        let offClose = NOOP
+        const onUnmount = (): void => settle(undefined)
+        function settle(value: IntentReply<K> | void): void {
+          if (done) return
+          done = true
+          offReply()
+          offClose()
+          pending.delete(onUnmount)
+          resolve(value)
+        }
+        const onReply = (m: IntentMessage): void => {
+          if (m.envelope.name !== INTENT_REPLY) return
+          const reply = m.envelope.payload as { correlationId: string; result: unknown }
+          if (reply.correlationId !== correlationId) return
+          settle(reply.result as IntentReply<K>)
+        }
+
+        pending.add(onUnmount)
+        if (target.kind === 'parent') {
+          const parent = shell.parent!
+          offReply = parent.on('intent', onReply)
+          parent.send(message)
+        } else {
+          const { windowId } = target
+          offReply = shell.children.on('intent', (wid, m) => {
+            if (wid === windowId) onReply(m)
+          })
+          offClose = shell.children.onClose((wid) => {
+            if (wid === windowId) settle(undefined)
+          })
+          shell.children.send(windowId, message)
+        }
+      })
+    },
+    [shell],
+  )
+}

package/src/navigation/adapters/adapter.ts

@@ -0,0 +1,13 @@
+/**
+ * The nav persistence port (API §8.1). The pluggable seam a `NavScope` mirrors its
+ * location through. `href` is the URL-form probe `<Link>` needs: present → an
+ * `<a href>` (cmd/ctrl-click falls through); absent → `role="link"`.
+ */
+import type { SerializedLocation } from '../history'
+
+export interface NavAdapter {
+  read(): SerializedLocation | null
+  write(loc: SerializedLocation, opts: { replace: boolean }): void
+  subscribe(onExternalChange: () => void): () => void
+  href?(loc: SerializedLocation): string
+}

package/src/navigation/adapters/memory.adapter.ts

@@ -0,0 +1,22 @@
+/**
+ * memoryAdapter (API §8.1) — the default scope backing: holds one location in a
+ * closure (per-pane state, no URL form → Link renders `role="link"`).
+ */
+import type { SerializedLocation } from '../history'
+import type { NavAdapter } from './adapter'
+
+/** In-memory adapter — the default scope backing (per-pane state, no URL). */
+export function memoryAdapter(initial?: SerializedLocation): NavAdapter {
+  let current: SerializedLocation | null = initial ?? null
+  const listeners = new Set<() => void>()
+  return {
+    read: () => current,
+    write: (loc) => {
+      current = loc
+    },
+    subscribe: (cb) => {
+      listeners.add(cb)
+      return () => listeners.delete(cb)
+    },
+  }
+}

package/src/navigation/adapters/url.adapter.ts

@@ -0,0 +1,61 @@
+/**
+ * urlAdapter (API §8.1) — the History-API adapter: mirrors the location into the
+ * query string (URL form → `<a href>`), owning the nav query keys (`param`,
+ * `view`, the location's `params`).
+ */
+import type { SerializedLocation } from '../history'
+import type { NavAdapter } from './adapter'
+
+const VIEW_KEY = 'view'
+
+/** History-API adapter — the location lives in the query string. */
+export function urlAdapter(opts?: { param?: string }): NavAdapter {
+  const param = opts?.param ?? 'node'
+  const hasWindow = (): boolean => typeof window !== 'undefined'
+
+  const build = (loc: SerializedLocation): string => {
+    const url = new URL(window.location.href)
+    const sp = new URLSearchParams()
+    sp.set(param, loc.node)
+    if (loc.view !== undefined) sp.set(VIEW_KEY, loc.view)
+    for (const [k, v] of Object.entries(loc.params ?? {})) {
+      if (k !== param && k !== VIEW_KEY) sp.set(k, v)
+    }
+    url.search = sp.toString()
+    return `${url.pathname}${url.search}${url.hash}`
+  }
+
+  return {
+    read() {
+      if (!hasWindow()) return null
+      const sp = new URL(window.location.href).searchParams
+      const node = sp.get(param)
+      if (node === null) return null
+      const view = sp.get(VIEW_KEY) ?? undefined
+      const params: Record<string, string> = {}
+      for (const [k, v] of sp) {
+        if (k !== param && k !== VIEW_KEY) params[k] = v
+      }
+      return {
+        node,
+        ...(view !== undefined ? { view } : {}),
+        ...(Object.keys(params).length > 0 ? { params } : {}),
+      }
+    },
+    write(loc, { replace }) {
+      if (!hasWindow()) return
+      const href = build(loc)
+      if (replace) window.history.replaceState(null, '', href)
+      else window.history.pushState(null, '', href)
+    },
+    subscribe(cb) {
+      if (!hasWindow()) return () => undefined
+      const handler = (): void => cb()
+      window.addEventListener('popstate', handler)
+      return () => window.removeEventListener('popstate', handler)
+    },
+    href(loc) {
+      return hasWindow() ? build(loc) : loc.node
+    },
+  }
+}

package/src/navigation/history.ts

@@ -0,0 +1,170 @@
+/**
+ * The per-scope history model (API §8.2) — a framework-free entries+cursor stack
+ * with a version counter for `useSyncExternalStore`, its serialized entry shape
+ * (`SerializedLocation`/`NavSnapshot` + equality/clone), and the seed precedence.
+ * Source of truth for back/forward; the adapter is a projection sink around it.
+ */
+
+/** The serializable projection persisted in history / URLs / snapshots. */
+export interface SerializedLocation {
+  node: string
+  view?: string
+  params?: Record<string, string>
+}
+
+/** A versioned history snapshot — round-trips through `NavScope.restore`. */
+export interface NavSnapshot {
+  v: 1
+  entries: SerializedLocation[]
+  cursor: number
+}
+
+/** Structural equality of two serialized locations (node + view + params). */
+export function sameLocation(a: SerializedLocation, b: SerializedLocation): boolean {
+  return a.node === b.node && a.view === b.view && sameParams(a.params, b.params)
+}
+
+function sameParams(a?: Record<string, string>, b?: Record<string, string>): boolean {
+  if (a === b) return true
+  const ak = a ? Object.keys(a) : []
+  const bk = b ? Object.keys(b) : []
+  if (ak.length !== bk.length) return false
+  return ak.every((k) => a?.[k] === b?.[k])
+}
+
+/** A deep-enough clone for a serialized entry (params copied). */
+export function cloneLocation(loc: SerializedLocation): SerializedLocation {
+  return {
+    node: loc.node,
+    ...(loc.view !== undefined ? { view: loc.view } : {}),
+    ...(loc.params !== undefined ? { params: { ...loc.params } } : {}),
+  }
+}
+
+export class NavHistory {
+  private entries: SerializedLocation[]
+  private cursor: number
+  private version = 0
+  private readonly listeners = new Set<() => void>()
+
+  constructor(entries: SerializedLocation[], cursor: number) {
+    this.entries = entries
+    this.cursor = cursor
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  getVersion(): number {
+    return this.version
+  }
+
+  get current(): SerializedLocation | null {
+    return this.entries[this.cursor] ?? null
+  }
+
+  get canBack(): boolean {
+    return this.cursor > 0
+  }
+
+  get canForward(): boolean {
+    return this.cursor >= 0 && this.cursor < this.entries.length - 1
+  }
+
+  snapshot(): NavSnapshot {
+    return { v: 1, entries: this.entries.map(cloneLocation), cursor: this.cursor }
+  }
+
+  /** Push (or replace the current entry with) a location. No-op on same location. */
+  push(loc: SerializedLocation, replace: boolean): boolean {
+    const cur = this.current
+    if (cur !== null && sameLocation(cur, loc)) return false
+    if (replace && cur !== null) {
+      this.entries = [...this.entries]
+      this.entries[this.cursor] = loc
+    } else {
+      this.entries = [...this.entries.slice(0, this.cursor + 1), loc]
+      this.cursor = this.entries.length - 1
+    }
+    this.emit()
+    return true
+  }
+
+  back(): boolean {
+    if (!this.canBack) return false
+    this.cursor--
+    this.emit()
+    return true
+  }
+
+  forward(): boolean {
+    if (!this.canForward) return false
+    this.cursor++
+    this.emit()
+    return true
+  }
+
+  /**
+   * Reconcile an externally-observed location (browser back/forward, URL edit):
+   * step the cursor when it matches an adjacent entry, else push it fresh.
+   */
+  syncExternal(loc: SerializedLocation): boolean {
+    const cur = this.current
+    if (cur !== null && sameLocation(cur, loc)) return false
+    const back = this.entries[this.cursor - 1]
+    if (back !== undefined && sameLocation(back, loc)) {
+      this.cursor--
+      this.emit()
+      return true
+    }
+    const fwd = this.entries[this.cursor + 1]
+    if (fwd !== undefined && sameLocation(fwd, loc)) {
+      this.cursor++
+      this.emit()
+      return true
+    }
+    return this.push(loc, false)
+  }
+
+  /** Replace the whole stack (restore revalidation prune). */
+  reset(entries: SerializedLocation[], cursor: number): void {
+    this.entries = entries
+    this.cursor = cursor
+    this.emit()
+  }
+
+  private emit(): void {
+    this.version++
+    for (const listener of this.listeners) listener()
+  }
+}
+
+/**
+ * Seed the initial entries+cursor from the three sources, in precedence order:
+ * a `restore` snapshot (revalidated later against the memory), then the
+ * adapter's current read, then `initial`; empty (idle) when none yields one.
+ * A live adapter read that disagrees with a restored cursor is appended as the
+ * current entry (a deep link overrides the saved position but keeps its back
+ * history).
+ */
+export function seedEntries(
+  fromAdapter: SerializedLocation | null,
+  restore: { entries: SerializedLocation[]; cursor: number } | undefined,
+  initialSerialized: SerializedLocation | null,
+): { entries: SerializedLocation[]; cursor: number } {
+  if (restore !== undefined && restore.entries.length > 0) {
+    const entries = restore.entries.map(cloneLocation)
+    let cursor = Math.min(Math.max(restore.cursor, 0), entries.length - 1)
+    if (fromAdapter !== null && !sameLocation(fromAdapter, entries[cursor])) {
+      entries.splice(cursor + 1)
+      entries.push(cloneLocation(fromAdapter))
+      cursor = entries.length - 1
+    }
+    return { entries, cursor }
+  }
+  if (fromAdapter !== null) return { entries: [cloneLocation(fromAdapter)], cursor: 0 }
+  if (initialSerialized !== null) return { entries: [initialSerialized], cursor: 0 }
+  return { entries: [], cursor: -1 }
+}

package/src/navigation/hooks/ancestors.hook.ts

@@ -0,0 +1,71 @@
+import type { PathLike } from '@astrale-os/kernel-client/graph'
+import type { LiveResult, ShapeInput } from '@astrale-os/kernel-client/store'
+
+/**
+ * useAncestors (API §8.2) — the live, inclusive root-first ancestor chain of a
+ * node (a move re-renders it). Defaults to the nearest scope's location node;
+ * passing a node/path makes it usable outside a scope. Drops any masked ancestor.
+ */
+import { useMemo } from 'react'
+
+import type { ReadState } from '../../graph/memory/read/envelope'
+import type { Node } from '../location'
+
+import { idleReadState } from '../../graph/memory/read/idle'
+import { useMemory } from '../../graph/memory/scope'
+import { chainPaths, pathHint, pathOf } from '../location'
+import { useHistoryVersion, useOptionalNavCtx, useMemoryShape } from '../scope.context'
+import { serializeTarget } from '../snapshot'
+
+/**
+ * The root-first ancestor chain (inclusive of the node itself), live: a move
+ * re-renders it. `node` defaults to the nearest scope's location node; passing a
+ * node/path makes it usable outside a scope. The chain drops any ancestor whose
+ * record is masked/absent.
+ */
+export function useAncestors(
+  node?: Node | PathLike,
+): ReadState & { readonly chain: readonly Node[] } {
+  const memory = useMemory()
+  const ctx = useOptionalNavCtx()
+  useHistoryVersion(ctx?.history ?? null)
+
+  const baseRef =
+    node !== undefined ? serializeTarget(node).node : (ctx?.history.current?.node ?? null)
+  const baseResult = useMemoryShape(memory, baseRef)
+  const basePath = baseResult?.node ? pathOf(baseResult.node) : pathHint(baseRef ?? '')
+
+  const paths = useMemo(() => (basePath !== '' ? chainPaths(basePath) : EMPTY_PATHS), [basePath])
+  const shape = useMemo<ShapeInput | null>(
+    () => (basePath !== '' ? (q) => q.from(...chainPaths(basePath)) : null),
+    [basePath],
+  )
+  const chainResult = useMemoryShape(memory, shape)
+  const chain = useMemo<readonly Node[]>(() => {
+    if (chainResult === null) return EMPTY_CHAIN
+    const byPath = new Map<string, Node>()
+    for (const n of chainResult.roots) byPath.set(pathOf(n), n)
+    const out: Node[] = []
+    for (const p of paths) {
+      const hit = byPath.get(p)
+      if (hit !== undefined) out.push(hit)
+    }
+    return out
+  }, [paths, chainResult])
+
+  return { ...readStateOf(chainResult), chain }
+}
+
+const EMPTY_PATHS: readonly string[] = Object.freeze([])
+const EMPTY_CHAIN: readonly Node[] = Object.freeze([])
+
+function readStateOf(result: LiveResult | null): ReadState {
+  if (result === null) return idleReadState()
+  return {
+    pending: result.pending,
+    error: result.error,
+    live: result.live,
+    seq: result.seq,
+    refetch: result.refetch,
+  }
+}

package/src/navigation/hooks/location.hook.ts

@@ -0,0 +1,21 @@
+/**
+ * useLocation (API §8.2) — the nearest scope's live, id-anchored location (live
+ * path/node, missing flag). Throws outside any {@link NavScope}.
+ */
+import { useMemo } from 'react'
+
+import type { NavLocation } from '../location'
+
+import { buildLocation, useSettled } from '../location'
+import { useHistoryVersion, useNavCtx, useMemoryShape } from '../scope.context'
+
+/** The nearest scope's live location. Throws outside any {@link NavScope}. */
+export function useLocation(): NavLocation {
+  const ctx = useNavCtx()
+  useHistoryVersion(ctx.history)
+  const entry = ctx.history.current
+  const shape = entry?.node ?? null
+  const result = useMemoryShape(ctx.memory, shape)
+  const settled = useSettled(result, shape)
+  return useMemo(() => buildLocation(entry, result, settled), [entry, result, settled])
+}

package/src/navigation/hooks/navigate.hook.ts

@@ -0,0 +1,43 @@
+/**
+ * useNavigate (API §8.2) — the nearest scope's imperative navigation surface
+ * (back/forward/up + live canBack/canForward, wrapped in transitions). A
+ * per-consumer handle that delegates to the scope's ONE stable callable.
+ */
+import { useMemo } from 'react'
+
+import type { MutableNavigate, NavCtx, Navigate } from '../scope.context'
+
+import { useHistoryVersion, useNavCtx } from '../scope.context'
+
+/** The nearest scope's imperative navigation surface. Throws outside a scope. */
+export function useNavigate(): Navigate {
+  return useNavigateHandle(useNavCtx())
+}
+
+/**
+ * A per-consumer navigate handle with fresh `canBack`/`canForward`, delegating to
+ * the scope's ONE stable callable. Render-pure: it never mutates the shared
+ * callable during render (a concurrent render could otherwise read flags from a
+ * newer history version than its own snapshot). The wrapper's identity changes
+ * only when navigation availability changes.
+ */
+export function useNavigateHandle(ctx: NavCtx): Navigate {
+  useHistoryVersion(ctx.history)
+  const canBack = ctx.history.canBack
+  const canForward = ctx.history.canForward
+  return useMemo(
+    () => wrapNavigate(ctx.navigate, canBack, canForward),
+    [ctx.navigate, canBack, canForward],
+  )
+}
+
+function wrapNavigate(base: MutableNavigate, canBack: boolean, canForward: boolean): Navigate {
+  const fn = ((to: Parameters<Navigate>[0], opts?: Parameters<Navigate>[1]) =>
+    base(to, opts)) as MutableNavigate
+  fn.back = base.back
+  fn.forward = base.forward
+  fn.up = base.up
+  fn.canBack = canBack
+  fn.canForward = canForward
+  return fn
+}

package/src/navigation/hooks/scope.hook.ts

@@ -0,0 +1,34 @@
+/**
+ * useNavScope (API §8.2) — the nearest scope, for chrome/persistence: the live
+ * location, a `snapshot()` handle, and the imperative navigate. Throws outside a
+ * scope.
+ */
+import { useCallback, useMemo } from 'react'
+
+import type { NavSnapshot } from '../history'
+import type { NavLocation } from '../location'
+import type { Navigate } from '../scope.context'
+
+import { buildLocation, useSettled } from '../location'
+import { useNavCtx, useMemoryShape } from '../scope.context'
+import { useNavigateHandle } from './navigate.hook'
+
+/** The nearest scope, for chrome/persistence (API §8.2). */
+export interface NavScopeHandle {
+  readonly location: NavLocation
+  snapshot(): NavSnapshot
+  navigate: Navigate
+}
+
+/** The nearest scope, for chrome/persistence (API §8.2). Throws outside a scope. */
+export function useNavScope(): NavScopeHandle {
+  const ctx = useNavCtx()
+  const navigate = useNavigateHandle(ctx)
+  const entry = ctx.history.current
+  const shape = entry?.node ?? null
+  const result = useMemoryShape(ctx.memory, shape)
+  const settled = useSettled(result, shape)
+  const location = useMemo(() => buildLocation(entry, result, settled), [entry, result, settled])
+  const snapshot = useCallback(() => ctx.history.snapshot(), [ctx.history])
+  return { location, snapshot, navigate }
+}

package/src/navigation/index.ts

@@ -0,0 +1,17 @@
+// navigation — API §8 (NavScope, useLocation, useNavigate, Link, useAncestors,
+// useNavScope, adapters). See SHELL_REACT_API.md.
+export { NavScope } from './scope.context'
+export type { MissingPolicy, NavScopeProps, Navigate } from './scope.context'
+export { useLocation } from './hooks/location.hook'
+export { useNavigate } from './hooks/navigate.hook'
+export { useAncestors } from './hooks/ancestors.hook'
+export { useNavScope } from './hooks/scope.hook'
+export type { NavScopeHandle } from './hooks/scope.hook'
+export { Link } from './link'
+export type { LinkProps } from './link'
+export { memoryAdapter } from './adapters/memory.adapter'
+export { urlAdapter } from './adapters/url.adapter'
+export type { NavAdapter } from './adapters/adapter'
+export type { NavLocation } from './location'
+export type { NavSnapshot, SerializedLocation } from './history'
+export type { NavTarget } from './snapshot'

package/src/navigation/link.tsx

@@ -0,0 +1,110 @@
+import type {
+  AnchorHTMLAttributes,
+  FocusEvent,
+  KeyboardEvent,
+  MouseEvent,
+  PointerEvent,
+  ReactElement,
+  ReactNode,
+} from 'react'
+
+/**
+ * Link (API §8.2) — navigates the nearest scope. Renders `<a href>` when the
+ * scope's adapter exposes a URL form (cmd/ctrl/middle-click then falls through
+ * to the browser), else an href-less `<a role="link">` with identical behavior.
+ * Default prefetch `'intent'` warms the target shape on hover/pointer-down/focus.
+ */
+import { useCallback, useEffect } from 'react'
+
+import type { NavTarget } from './snapshot'
+
+import { useNavCtx } from './scope.context'
+import { serializeTarget } from './snapshot'
+
+export interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  to: NavTarget
+  replace?: boolean
+  /** Warm the target shape ahead of navigation. Default `'intent'`. */
+  prefetch?: 'intent' | 'render' | false
+  children: ReactNode
+}
+
+export function Link(props: LinkProps): ReactElement {
+  const {
+    to,
+    replace,
+    prefetch = 'intent',
+    children,
+    onClick,
+    onPointerEnter,
+    onPointerDown,
+    onFocus,
+    onKeyDown,
+    ...rest
+  } = props
+  const ctx = useNavCtx()
+  const target = serializeTarget(to)
+  const href = ctx.adapter.href?.(target)
+  const nodeRef = target.node
+
+  const preload = useCallback(() => {
+    void ctx.memory?.preload(nodeRef)
+  }, [ctx.memory, nodeRef])
+
+  useEffect(() => {
+    if (prefetch === 'render') preload()
+  }, [prefetch, preload])
+
+  const intent = useCallback(() => {
+    if (prefetch === 'intent') preload()
+  }, [prefetch, preload])
+
+  const go = useCallback(() => ctx.navigate(to, { replace }), [ctx, to, replace])
+
+  const handleClick = (e: MouseEvent<HTMLAnchorElement>): void => {
+    onClick?.(e)
+    if (e.defaultPrevented) return
+    const modified = e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0
+    if (href !== undefined && modified) return // let the browser open it (new tab / window)
+    e.preventDefault()
+    go()
+  }
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLAnchorElement>): void => {
+    onKeyDown?.(e)
+    if (e.defaultPrevented || href !== undefined) return // a real anchor handles Enter itself
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      go()
+    }
+  }
+
+  const handlePointerEnter = (e: PointerEvent<HTMLAnchorElement>): void => {
+    onPointerEnter?.(e)
+    intent()
+  }
+  const handlePointerDown = (e: PointerEvent<HTMLAnchorElement>): void => {
+    onPointerDown?.(e)
+    intent()
+  }
+  const handleFocus = (e: FocusEvent<HTMLAnchorElement>): void => {
+    onFocus?.(e)
+    intent()
+  }
+
+  const linkRole = href !== undefined ? { href } : { role: 'link', tabIndex: rest.tabIndex ?? 0 }
+
+  return (
+    <a
+      {...rest}
+      {...linkRole}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      onPointerEnter={handlePointerEnter}
+      onPointerDown={handlePointerDown}
+      onFocus={handleFocus}
+    >
+      {children}
+    </a>
+  )
+}