@workerdeck/ui 0.9.0 → 0.12.0

package/src/components/prompt-area/use-prompt-area.ts

@@ -17,6 +17,7 @@ import {
   plainTextToSegments,
   segmentsEqual,
   resolveChip,
+  resolveText,
   removeChipAtIndex,
   revertChipAtIndex,
   replaceTextRange,
@@ -929,6 +930,25 @@ export function usePromptArea({
       if (!activeTrigger) return
 
       const segments = readSegmentsFromDOM()
+
+      // Text-resolved suggestions leave before any chip machinery runs: there
+      // is no chip, so there is nothing for the chip-click editing path or the
+      // onChipAdd callback below to be about.
+      const asText = activeTrigger.config.insertAsText?.(suggestion)
+      if (asText !== undefined) {
+        const inserted = resolveText(segments, activeTrigger, asText)
+        events.pushUndo(segments)
+        onChange(inserted.segments)
+        renderSegmentsToDOM(inserted.segments)
+        const editor = editorRef.current
+        if (editor) setCursorAtOffset(editor, inserted.cursorOffset)
+        dismissTrigger()
+        setTimeout(() => {
+          editorRef.current?.focus()
+        }, 0)
+        return
+      }
+
       const displayText = activeTrigger.config.onSelect?.(suggestion) ?? suggestion.label
 
       const chipData = {

package/src/components/ui/CodeBlock.tsx

@@ -7,17 +7,55 @@ export interface CodeBlockProps {
   /** Header label, e.g. a language or "Parameters". */
   label?: ReactNode
   copyable?: boolean
+  /**
+   * `'panel'` (default) is the framed card: border, header strip, rounded.
+   * `'plain'` is the terminal treatment — the label is a dim line, the code a
+   * flat band, and copy is a character. For surfaces where a box around every
+   * payload is more chrome than content (the transcript's `lines` variant).
+   *
+   * A prop rather than a read of the transcript's variant context: this is a
+   * `ui/` primitive and has no business knowing what a transcript is. The agent
+   * component that renders it does.
+   */
+  variant?: 'panel' | 'plain'
   className?: string
 }
 
 /** Plain (unhighlighted) code panel for structured data like tool inputs. Markdown code
  * inside assistant responses is highlighted by <Response> instead. */
-export function CodeBlock({ code, label, copyable = true, className }: CodeBlockProps) {
+export function CodeBlock({
+  code,
+  label,
+  copyable = true,
+  variant = 'panel',
+  className,
+}: CodeBlockProps) {
+  const plain = variant === 'plain'
+  const header = label !== undefined || copyable
+
+  if (plain) {
+    return (
+      <div data-slot='code-block' data-variant='plain' className={cn('min-w-0', className)}>
+        {header ? (
+          <div className='flex items-baseline justify-between gap-2'>
+            <span className='truncate text-label leading-5 text-fg-4'>{label}</span>
+            {copyable ? (
+              <CopyButton glyph value={code} className='size-5 shrink-0 rounded-sm' />
+            ) : null}
+          </div>
+        ) : null}
+        <pre className='max-h-64 overflow-auto bg-code-bg px-2 font-mono text-label leading-5 whitespace-pre-wrap text-fg-2'>
+          {code}
+        </pre>
+      </div>
+    )
+  }
+
   return (
     <div
       data-slot='code-block'
       className={cn('overflow-hidden rounded-md border border-border bg-code-bg', className)}>
-      {label !== undefined || copyable ? (
+      {header ? (
         <div className='flex h-8 items-center justify-between border-b border-border px-2.5'>
           <span className='font-mono text-label text-fg-3'>{label}</span>
           {copyable ? <CopyButton value={code} /> : null}

package/src/components/ui/CopyButton.tsx

@@ -1,13 +1,24 @@
 import { useState } from 'react'
 import { Check, Copy } from 'lucide-react'
 import { Button, type ButtonProps } from './Button.tsx'
+import { copyText } from '../../lib/clipboard.ts'
 import { cn } from '../../lib/utils.ts'
 
 export interface CopyButtonProps extends Omit<ButtonProps, 'onClick' | 'children'> {
   value: string
+  /** Draw the state as characters (`⧉` / `✓`) rather than line-art icons — for
+   * terminal-styled surfaces, where an SVG reads as another app's button. */
+  glyph?: boolean
 }
 
-export function CopyButton({ value, className, variant = 'ghost', size = 'icon-sm', ...props }: CopyButtonProps) {
+export function CopyButton({
+  value,
+  glyph,
+  className,
+  variant = 'ghost',
+  size = 'icon-sm',
+  ...props
+}: CopyButtonProps) {
   const [copied, setCopied] = useState(false)
   return (
     <Button
@@ -16,13 +27,27 @@ export function CopyButton({ value, className, variant = 'ghost', size = 'icon-s
       aria-label='Copy'
       className={cn('text-fg-3', className)}
       onClick={() => {
-        void navigator.clipboard.writeText(value).then(() => {
+        // Through `copyText`, which falls back for insecure origins — the
+        // dashboard on a LAN address has no `navigator.clipboard` at all, and
+        // reaching straight for `.writeText` there throws.
+        void copyText(value).then((ok) => {
+          // Only tick when it really copied: a check mark over an empty
+          // clipboard is worse than no feedback.
+          if (!ok) return
           setCopied(true)
           setTimeout(() => setCopied(false), 1500)
         })
       }}
       {...props}>
-      {copied ? <Check className='size-3.5 text-success' /> : <Copy className='size-3.5' />}
+      {glyph ? (
+        <span className={cn('font-mono text-body-sm leading-5', copied && 'text-success')}>
+          {copied ? '✓' : '⧉'}
+        </span>
+      ) : copied ? (
+        <Check className='size-3.5 text-success' />
+      ) : (
+        <Copy className='size-3.5' />
+      )}
     </Button>
   )
 }

package/src/components/ui/Dialog.tsx

@@ -0,0 +1,92 @@
+import { type FunctionComponent } from 'react'
+import { Dialog as DialogPrimitive } from '@base-ui/react/dialog'
+import { X } from 'lucide-react'
+import { cn } from '../../lib/utils.ts'
+
+export const Dialog = DialogPrimitive.Root
+export const DialogTrigger = DialogPrimitive.Trigger
+export const DialogClose = DialogPrimitive.Close
+
+/**
+ * A dismissible panel, sized for reading rather than confirming — the web
+ * counterpart of the iOS app's detail sheets (context, usage, session info, MCP).
+ *
+ * Taller than {@link AlertDialogContent} and scrollable inside, because these
+ * carry lists whose length is the engine's business, not the layout's.
+ */
+export const DialogContent: FunctionComponent<
+  DialogPrimitive.Popup.Props & { size?: 'sm' | 'md' | 'lg' }
+> = ({ className, children, size = 'md', ...props }) => (
+  <DialogPrimitive.Portal>
+    <DialogPrimitive.Backdrop
+      className={cn(
+        'fixed inset-0 z-70 bg-black/40 backdrop-blur-[1px]',
+        'transition-opacity duration-(--motion-base)',
+        'data-starting-style:opacity-0 data-ending-style:opacity-0',
+      )}
+    />
+    <DialogPrimitive.Popup
+      data-slot='dialog-content'
+      className={cn(
+        'fixed top-1/2 left-1/2 z-70 flex max-h-[min(42rem,calc(100dvh-3rem))] -translate-x-1/2 -translate-y-1/2 flex-col',
+        size === 'sm' && 'w-[min(24rem,calc(100vw-2rem))]',
+        size === 'md' && 'w-[min(32rem,calc(100vw-2rem))]',
+        size === 'lg' && 'w-[min(46rem,calc(100vw-2rem))]',
+        'rounded-lg border border-border bg-surface shadow-(--shadow-lg) outline-none',
+        'transition-[opacity,transform] duration-(--motion-base)',
+        'data-starting-style:scale-95 data-starting-style:opacity-0',
+        'data-ending-style:scale-95 data-ending-style:opacity-0',
+        className,
+      )}
+      {...props}>
+      {children}
+    </DialogPrimitive.Popup>
+  </DialogPrimitive.Portal>
+)
+
+/** Title row with the close button, pinned above the scrolling body. */
+export const DialogHeader: FunctionComponent<{
+  title: string
+  description?: string
+  /** Rendered between the title and the close button. */
+  actions?: React.ReactNode
+}> = ({ title, description, actions }) => (
+  <div className='flex items-start gap-2 border-b border-border px-4 py-3'>
+    <div className='min-w-0 flex-1'>
+      <DialogPrimitive.Title className='truncate text-body-sm font-semibold text-text'>
+        {title}
+      </DialogPrimitive.Title>
+      {description ? (
+        <DialogPrimitive.Description className='mt-0.5 text-label text-fg-4'>
+          {description}
+        </DialogPrimitive.Description>
+      ) : null}
+    </div>
+    {actions}
+    <DialogPrimitive.Close
+      aria-label='Close'
+      className='-mr-1 flex size-6 shrink-0 items-center justify-center rounded-md text-fg-3 transition-colors outline-none hover:bg-surface-hover hover:text-fg-1'>
+      <X className='size-3.5' />
+    </DialogPrimitive.Close>
+  </div>
+)
+
+/** The scrolling region under the header. */
+export const DialogBody: FunctionComponent<React.HTMLAttributes<HTMLDivElement>> = ({
+  className,
+  ...props
+}) => <div className={cn('min-h-0 flex-1 overflow-y-auto p-4', className)} {...props} />
+
+/** A label/value row — the shape every one of these panels is mostly made of. */
+export const DialogRow: FunctionComponent<{
+  label: string
+  children: React.ReactNode
+  mono?: boolean
+}> = ({ label, children, mono }) => (
+  <div className='flex items-baseline justify-between gap-4 py-1.5'>
+    <span className='shrink-0 text-label text-fg-3'>{label}</span>
+    <span className={cn('min-w-0 truncate text-right text-body-sm text-fg-1', mono && 'font-mono text-label')}>
+      {children}
+    </span>
+  </div>
+)

package/src/components/ui/Menu.tsx

@@ -0,0 +1,55 @@
+import { type FunctionComponent } from 'react'
+import { Menu as MenuPrimitive } from '@base-ui/react/menu'
+import { cn } from '../../lib/utils.ts'
+
+export const Menu = MenuPrimitive.Root
+export const MenuTrigger = MenuPrimitive.Trigger
+
+export const MenuContent: FunctionComponent<
+  MenuPrimitive.Popup.Props &
+    Pick<MenuPrimitive.Positioner.Props, 'align' | 'side' | 'sideOffset'>
+> = ({ className, align = 'end', side = 'bottom', sideOffset = 6, ...props }) => (
+  <MenuPrimitive.Portal>
+    <MenuPrimitive.Positioner
+      align={align}
+      side={side}
+      sideOffset={sideOffset}
+      className='isolate z-60 outline-none'>
+      <MenuPrimitive.Popup
+        data-slot='menu-content'
+        className={cn(
+          'min-w-48 rounded-md border border-border bg-surface p-1 text-fg-1 shadow-(--shadow-lg) outline-none',
+          'transition-[opacity,transform] duration-(--motion-base)',
+          'data-starting-style:scale-95 data-starting-style:opacity-0',
+          'data-ending-style:scale-95 data-ending-style:opacity-0',
+          className,
+        )}
+        {...props}
+      />
+    </MenuPrimitive.Positioner>
+  </MenuPrimitive.Portal>
+)
+
+export const MenuItem: FunctionComponent<MenuPrimitive.Item.Props & { destructive?: boolean }> = ({
+  className,
+  destructive,
+  ...props
+}) => (
+  <MenuPrimitive.Item
+    data-slot='menu-item'
+    className={cn(
+      'flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1.5 text-body-sm outline-none select-none',
+      'data-highlighted:bg-surface-hover',
+      destructive ? 'text-danger' : 'text-text',
+      className,
+    )}
+    {...props}
+  />
+)
+
+export const MenuSeparator: FunctionComponent<MenuPrimitive.Separator.Props> = ({
+  className,
+  ...props
+}) => (
+  <MenuPrimitive.Separator className={cn('my-1 h-px bg-border', className)} {...props} />
+)

package/src/components/ui/Splitter.tsx

@@ -0,0 +1,133 @@
+import {
+  useCallback,
+  useRef,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type PointerEvent as ReactPointerEvent,
+} from 'react'
+import { cn } from '../../lib/utils.ts'
+
+export interface SplitterProps {
+  /**
+   * ARIA's sense of the word: a `vertical` splitter is a vertical bar between
+   * two side-by-side panes, and it resizes a **width**. A `horizontal` one sits
+   * between stacked panes and resizes a **height**.
+   */
+  orientation: 'vertical' | 'horizontal'
+  /** Current size of the pane this splitter controls, in pixels. */
+  value: number
+  onValueChange: (value: number) => void
+  min: number
+  max: number
+  /** Keyboard step. */
+  step?: number
+  /** Set when dragging the splitter *away* from the origin should shrink the
+   * controlled pane — i.e. the pane is on the right or the bottom. */
+  inverted?: boolean
+  /** Required: "Resize" alone does not say which of two splitters this is. */
+  'aria-label': string
+  className?: string
+}
+
+/**
+ * A draggable pane divider.
+ *
+ * Hand-rolled rather than depended on: `@base-ui/react` ships no splitter, the
+ * behaviour is a hundred lines of pointer events, and this repo's instinct at
+ * this layer is to own it (the composer is vendored for the same reason).
+ *
+ * Pointer capture is what makes it survive a fast drag — without it the pointer
+ * leaves the 5px bar within a frame and the moves go to whatever is underneath,
+ * which for this layout is an iframe-free but still selection-happy code pane.
+ * The drag origin is captured on pointerdown and every move is measured against
+ * it, so the pane cannot drift relative to the cursor over a long drag the way
+ * per-move deltas do once clamping is involved.
+ *
+ * Keyboard-operable and announced as a separator, because a pane you can only
+ * size by dragging is a pane some people cannot size.
+ */
+export function Splitter({
+  orientation,
+  value,
+  onValueChange,
+  min,
+  max,
+  step = 16,
+  inverted,
+  'aria-label': label,
+  className,
+}: SplitterProps) {
+  const drag = useRef<{ origin: number; start: number } | null>(null)
+  const vertical = orientation === 'vertical'
+
+  const clamp = useCallback((next: number) => Math.min(max, Math.max(min, next)), [min, max])
+
+  const onPointerDown = (event: ReactPointerEvent<HTMLDivElement>) => {
+    // Secondary buttons open context menus; they are not drags.
+    if (event.button !== 0) return
+    event.preventDefault()
+    event.currentTarget.setPointerCapture(event.pointerId)
+    drag.current = { origin: vertical ? event.clientX : event.clientY, start: value }
+  }
+
+  const onPointerMove = (event: ReactPointerEvent<HTMLDivElement>) => {
+    const state = drag.current
+    if (!state) return
+    const delta = (vertical ? event.clientX : event.clientY) - state.origin
+    onValueChange(clamp(state.start + (inverted ? -delta : delta)))
+  }
+
+  const endDrag = (event: ReactPointerEvent<HTMLDivElement>) => {
+    if (!drag.current) return
+    drag.current = null
+    if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+      event.currentTarget.releasePointerCapture(event.pointerId)
+    }
+  }
+
+  const onKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    // The arrows that move *along* this splitter's axis of travel; the other
+    // pair is left to the page, which is what a separator should do with them.
+    const grow = vertical ? 'ArrowRight' : 'ArrowDown'
+    const shrink = vertical ? 'ArrowLeft' : 'ArrowUp'
+    const direction = inverted ? -1 : 1
+    if (event.key === grow) onValueChange(clamp(value + step * direction))
+    else if (event.key === shrink) onValueChange(clamp(value - step * direction))
+    else if (event.key === 'Home') onValueChange(min)
+    else if (event.key === 'End') onValueChange(max)
+    else return
+    event.preventDefault()
+  }
+
+  return (
+    <div
+      data-slot='splitter'
+      role='separator'
+      tabIndex={0}
+      aria-label={label}
+      aria-orientation={orientation}
+      aria-valuenow={Math.round(value)}
+      aria-valuemin={min}
+      aria-valuemax={max}
+      onPointerDown={onPointerDown}
+      onPointerMove={onPointerMove}
+      onPointerUp={endDrag}
+      onPointerCancel={endDrag}
+      onKeyDown={onKeyDown}
+      className={cn(
+        // A 1px line that reads as a border, with a larger invisible grab area
+        // around it — a hairline is an honest divider and a cruel target.
+        'group relative shrink-0 touch-none bg-border transition-colors',
+        'hover:bg-border-strong focus-visible:bg-accent focus-visible:outline-none',
+        vertical ? 'w-px cursor-col-resize' : 'h-px cursor-row-resize',
+        className,
+      )}>
+      <span
+        aria-hidden
+        className={cn(
+          'absolute',
+          vertical ? '-inset-x-[3px] inset-y-0' : '-inset-y-[3px] inset-x-0',
+        )}
+      />
+    </div>
+  )
+}

package/src/components/ui/Tooltip.tsx

@@ -1,4 +1,4 @@
-import { type FunctionComponent, type ReactNode } from 'react'
+import { type FunctionComponent, type ReactElement, type ReactNode } from 'react'
 import { Tooltip as TooltipPrimitive } from '@base-ui/react/tooltip'
 import { cn } from '../../lib/utils.ts'
 
@@ -21,14 +21,31 @@ export const TooltipContent: FunctionComponent<
   </TooltipPrimitive.Portal>
 )
 
-/** Convenience wrapper: <Tip content="..."><Button/></Tip> */
-export function Tip({ content, children }: { content: ReactNode; children: ReactNode }) {
+/**
+ * Convenience wrapper: `<Tip content="..."><Button/></Tip>`.
+ *
+ * Pass `render` when the trigger must *be* an element you already have — a tab, a
+ * row — rather than something wrapped in a span. The default span is fine beside
+ * a button but would break any layout that styles its own children (a flex tab
+ * strip gets an extra box between the container and its items).
+ */
+export function Tip({
+  content,
+  render,
+  side,
+  children,
+}: {
+  content: ReactNode
+  render?: ReactElement
+  side?: 'top' | 'right' | 'bottom' | 'left'
+  children?: ReactNode
+}) {
   return (
     <TooltipPrimitive.Root>
-      <TooltipPrimitive.Trigger render={<span className='inline-flex' />}>
+      <TooltipPrimitive.Trigger render={render ?? <span className='inline-flex' />}>
         {children}
       </TooltipPrimitive.Trigger>
-      <TooltipContent>{content}</TooltipContent>
+      <TooltipContent side={side}>{content}</TooltipContent>
     </TooltipPrimitive.Root>
   )
 }

package/src/format.ts

@@ -0,0 +1,11 @@
+/**
+ * The formatting helpers, on their own entry point.
+ *
+ * `src/index.ts` pulls in React and every component with it; a host that renders
+ * session readings *outside* React — the VS Code extension host drawing them in
+ * the window status bar, say — needs the numbers spelled the same way without
+ * paying for that. These functions are pure and dependency-free, so the subpath
+ * costs nothing and keeps one truth for what "45.2k" and "2h 10m" mean.
+ */
+export * from './lib/format.ts'
+export * from './lib/status.ts'

package/src/index.ts

@@ -20,11 +20,28 @@ export {
   AlertDialogTitle,
   AlertDialogTrigger,
 } from './components/ui/AlertDialog.tsx'
+export {
+  Menu,
+  MenuContent,
+  MenuItem,
+  MenuSeparator,
+  MenuTrigger,
+} from './components/ui/Menu.tsx'
+export {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogHeader,
+  DialogRow,
+  DialogTrigger,
+} from './components/ui/Dialog.tsx'
 export { Tip, TooltipContent, TooltipProvider } from './components/ui/Tooltip.tsx'
 export { Toaster, toast } from './components/ui/Sonner.tsx'
 export { CopyButton, type CopyButtonProps } from './components/ui/CopyButton.tsx'
 export { Spinner } from './components/ui/Spinner.tsx'
 export { CodeBlock, type CodeBlockProps } from './components/ui/CodeBlock.tsx'
+export { Splitter, type SplitterProps } from './components/ui/Splitter.tsx'
 export { ProgressRing, type ProgressRingProps } from './components/ui/ProgressRing.tsx'
 // Prompt input (vendored just-marketing/prompt-area, themed to these tokens)
 export {
@@ -47,7 +64,16 @@ export {
 } from './components/prompt-area/index.ts'
 
 // Agent-control components
-export { SessionPanel, type SessionPanelProps } from './components/agent/SessionPanel.tsx'
+export {
+  SessionPanel,
+  type SessionControls,
+  type SessionPanelProps,
+  type SessionSurfacePanel,
+  type SessionVitals,
+} from './components/agent/SessionPanel.tsx'
+// The workspace layout and its Monaco editor live at `@workerdeck/ui/workspace`
+// — deliberately unreachable from here, so importing this entry never drags
+// Monaco into the bundle. See `src/workspace.ts`.
 export { Transcript, type TranscriptProps } from './components/agent/Transcript.tsx'
 export {
   Conversation,
@@ -56,6 +82,14 @@ export {
   type ConversationProps,
 } from './components/agent/Conversation.tsx'
 export { Message, MessageContent, type MessageProps } from './components/agent/Message.tsx'
+export {
+  TranscriptDensityProvider,
+  TranscriptVariantProvider,
+  useTranscriptDensity,
+  useTranscriptVariant,
+  type TranscriptDensity,
+  type TranscriptVariant,
+} from './components/agent/transcript-variant.tsx'
 export { Response, type ResponseProps } from './components/agent/Response.tsx'
 export { Reasoning, type ReasoningProps } from './components/agent/Reasoning.tsx'
 export { Loader } from './components/agent/Loader.tsx'
@@ -69,31 +103,62 @@ export {
   type QuestionPromptProps,
   type QuestionBehaviorMeta,
 } from './components/agent/QuestionPrompt.tsx'
-export { Composer, type ComposerProps } from './components/agent/Composer.tsx'
+export {
+  Composer,
+  skillPrompt,
+  type ComposerFileMatch,
+  type ComposerHandle,
+  type ComposerProps,
+} from './components/agent/Composer.tsx'
 export { ModelSelect, type ModelSelectProps } from './components/agent/ModelSelect.tsx'
 export {
   PERMISSION_MODES,
   PermissionModeSelect,
+  permissionModeChoices,
+  permissionModeMeta,
+  type PermissionModeChoice,
   type PermissionModeMeta,
   type PermissionModeSelectProps,
 } from './components/agent/PermissionModeSelect.tsx'
 export { StatusBar, type StatusBarProps } from './components/agent/StatusBar.tsx'
+export { ContextDialog, type ContextDialogProps } from './components/agent/ContextDialog.tsx'
+export { UsageDialog, type UsageDialogProps } from './components/agent/UsageDialog.tsx'
+export {
+  SessionInfoDialog,
+  type SessionInfoDialogProps,
+} from './components/agent/SessionInfoDialog.tsx'
+export { McpDialog, type McpDialogProps } from './components/agent/McpDialog.tsx'
+export { SkillsDialog, type SkillsDialogProps } from './components/agent/SkillsDialog.tsx'
+export { HostFilesDialog, type HostFilesDialogProps } from './components/agent/HostFilesDialog.tsx'
 export {
   SessionList,
   SessionListItem,
   type SessionListItemProps,
   type SessionListProps,
 } from './components/agent/SessionList.tsx'
+export { SessionBrowser, type SessionBrowserProps } from './components/agent/SessionBrowser.tsx'
+export {
+  SessionEmptyState,
+  type SessionEmptyStateProps,
+} from './components/agent/SessionEmptyState.tsx'
+export { PromptTokenText } from './components/agent/PromptTokenText.tsx'
 export { STATUS_META } from './components/agent/status.ts'
 
 // Utilities
 export { cn } from './lib/utils.ts'
+export { copyText } from './lib/clipboard.ts'
+export { isMutatingTool, toolIcon } from './lib/tool-icon.ts'
 export {
+  formatAgoPrecise,
   formatBytes,
   formatCost,
   formatCountdown,
   formatDuration,
+  formatRateLimitWindow,
+  formatRateLimitWindowLong,
   formatRelativeTime,
   formatTokens,
+  friendlyModel,
+  rateLimitWindowSeconds,
   toolInputPreview,
 } from './lib/format.ts'

package/src/lib/clipboard.ts

@@ -0,0 +1,56 @@
+/**
+ * Copy text to the clipboard, on origins where the modern API does not exist.
+ *
+ * `navigator.clipboard` is gated on a **secure context**: HTTPS, or localhost.
+ * A WorkerDeck dashboard reached the way it is meant to be reached — plain HTTP
+ * on a LAN address, from a laptop or a phone — is neither, so `navigator.clipboard`
+ * is `undefined` there and touching `.writeText` throws outright. That is the
+ * normal deployment, not an edge case, which is why this falls back rather than
+ * feature-detecting into a disabled button.
+ *
+ * The fallback is `document.execCommand('copy')` over an off-screen textarea.
+ * It is deprecated and it is also the only thing that works here; every browser
+ * still implements it. Returns whether the text actually landed, so a caller can
+ * avoid claiming success it did not have.
+ */
+export async function copyText(value: string): Promise<boolean> {
+  // Optional-chained, not `in`-checked: on an insecure origin the property is
+  // absent entirely, and some embedded webviews expose a `clipboard` object
+  // whose `writeText` rejects. Both end up in the fallback.
+  try {
+    if (navigator.clipboard?.writeText) {
+      await navigator.clipboard.writeText(value)
+      return true
+    }
+  } catch {
+    // Permission denied, or a webview that lied about having the API.
+  }
+  return legacyCopy(value)
+}
+
+function legacyCopy(value: string): boolean {
+  if (typeof document === 'undefined') return false
+  const textarea = document.createElement('textarea')
+  textarea.value = value
+  // Off-screen rather than hidden: `display: none` and `visibility: hidden`
+  // elements cannot hold a selection, so the copy would silently do nothing.
+  // `readOnly` keeps the mobile keyboard from appearing for the instant it exists.
+  textarea.setAttribute('readonly', '')
+  textarea.style.position = 'fixed'
+  textarea.style.top = '-9999px'
+  textarea.style.opacity = '0'
+  document.body.appendChild(textarea)
+  // Preserve where the user was: selecting steals the current selection, and on
+  // a text field mid-edit that is visible and annoying.
+  const previous = document.activeElement
+  try {
+    textarea.select()
+    textarea.setSelectionRange(0, value.length)
+    return document.execCommand('copy')
+  } catch {
+    return false
+  } finally {
+    document.body.removeChild(textarea)
+    if (previous instanceof HTMLElement) previous.focus()
+  }
+}