@workerdeck/ui 0.9.0 → 0.12.0

package/src/components/agent/UsageDialog.tsx

@@ -0,0 +1,168 @@
+import { useEffect, useState } from 'react'
+import type { ProfileEngine, RateLimitInfo } from '@workerdeck/protocol'
+import { RotateCcw } from 'lucide-react'
+import { Badge } from '../ui/Badge.tsx'
+import { Dialog, DialogBody, DialogContent, DialogHeader } from '../ui/Dialog.tsx'
+import { cn } from '../../lib/utils.ts'
+import {
+  formatAgoPrecise,
+  formatCost,
+  formatCountdown,
+  formatRateLimitWindowLong,
+  rateLimitWindowSeconds,
+} from '../../lib/format.ts'
+
+export interface UsageDialogProps {
+  /** Windows in reading order — session, weekly, then per-model weeklies. */
+  rateLimits: Array<{ key: string; info: RateLimitInfo }>
+  /** claude.ai plan behind the windows ('max', 'pro', …), when there is one. */
+  subscriptionType?: string
+  engine: ProfileEngine
+  totalCostUsd: number
+  /** Local receipt time of the last window update. `rate_limit` events are one
+   * per turn at best, so a stale reading is normal and worth saying out loud. */
+  updatedAt?: number
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}
+
+/** Ticking clock — the countdowns and the pace markers both move with it, and a
+ * minute is the finest resolution either of them prints. */
+function useMinuteClock(open: boolean): number {
+  const [now, setNow] = useState(() => Date.now())
+  useEffect(() => {
+    if (!open) return
+    setNow(Date.now())
+    const timer = setInterval(() => setNow(Date.now()), 60_000)
+    return () => clearInterval(timer)
+  }, [open])
+  return now
+}
+
+const usageTint = (pct: number) => (pct >= 90 ? 'bg-danger' : pct >= 70 ? 'bg-warning' : 'bg-accent')
+
+/**
+ * The plan's rate-limit windows, spelled out: how much of each is used, how that
+ * compares to the pace that would spend the window exactly, and when it resets.
+ *
+ * The pace marker is the point. A bar alone says "17% used", which is only
+ * alarming or reassuring once you know how far into the week you are — so every
+ * window draws a tick at the elapsed share of its duration. Left of the tick is
+ * under budget, right of it is ahead of it. The duration comes from the window
+ * key (5h, 7d) because the CLI reports a reset time and a percentage and never a
+ * duration; a window whose key doesn't say gets no marker rather than a guessed one.
+ */
+export function UsageDialog({
+  rateLimits,
+  subscriptionType,
+  engine,
+  totalCostUsd,
+  updatedAt,
+  open,
+  onOpenChange,
+}: UsageDialogProps) {
+  const now = useMinuteClock(open)
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader
+          title='Usage'
+          description={engine === 'claude' ? 'Claude Code' : engine}
+          actions={
+            // The CLI reports a tier ('max'), never the multiplier a
+            // subscription page shows — so this says "Max" and stops there.
+            subscriptionType ? (
+              <Badge variant='accent' className='mt-0.5 shrink-0 capitalize'>
+                {subscriptionType}
+              </Badge>
+            ) : null
+          }
+        />
+        <DialogBody>
+          {rateLimits.length === 0 ? (
+            <p className='py-6 text-center text-body-sm text-fg-4'>
+              {engine === 'claude'
+                ? 'This session reports no plan windows — API-key sessions have none, and a subscription session reports them once a turn has run.'
+                : `Plan windows are a claude.ai subscription thing; this session runs on the ${engine} engine.`}
+            </p>
+          ) : (
+            <div className='flex flex-col gap-5'>
+              {rateLimits.map(({ key, info }) => (
+                <UsageWindow key={key} windowKey={key} info={info} now={now} />
+              ))}
+            </div>
+          )}
+          <div className='mt-5 flex items-baseline justify-between gap-4 border-t border-border pt-3'>
+            <span className='text-label text-fg-3'>This session has cost</span>
+            <span className='font-mono text-body-sm text-fg-1'>{formatCost(totalCostUsd)}</span>
+          </div>
+          {updatedAt ? (
+            <p className='mt-2 text-label text-fg-4'>Updated {formatAgoPrecise(updatedAt, now)}</p>
+          ) : null}
+        </DialogBody>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+function UsageWindow({
+  windowKey,
+  info,
+  now,
+}: {
+  windowKey: string
+  info: RateLimitInfo
+  now: number
+}) {
+  const utilization = info.utilization ?? 0
+  const resetsAtMs = info.resetsAt !== undefined ? info.resetsAt * 1000 : undefined
+  // Share of the window already elapsed — where usage *would* be if it were
+  // spent evenly. Needs both a duration (from the key) and a reset time.
+  const duration = rateLimitWindowSeconds(windowKey)
+  const remaining = resetsAtMs !== undefined ? (resetsAtMs - now) / 1000 : undefined
+  const pace =
+    duration !== undefined && remaining !== undefined && remaining > 0 && remaining < duration
+      ? (duration - remaining) / duration
+      : undefined
+  return (
+    <div>
+      <div className='flex items-baseline justify-between gap-3'>
+        <span className='truncate text-body-sm text-fg-1'>
+          {formatRateLimitWindowLong(windowKey)}
+        </span>
+        <span
+          className={cn(
+            'shrink-0 font-mono text-body-sm font-medium',
+            info.status === 'rejected' ? 'text-danger' : 'text-fg-1',
+          )}>
+          {utilization.toFixed(0)}% used
+        </span>
+      </div>
+      <div className='relative mt-2 h-2 rounded-full bg-border'>
+        <div
+          className={cn('h-full rounded-full', usageTint(utilization))}
+          // A floor, so a barely-touched window still shows a mark instead of
+          // reading as missing data.
+          style={{ width: `${Math.min(100, Math.max(2, utilization))}%` }}
+        />
+        {pace !== undefined ? (
+          <span
+            aria-hidden
+            title='Spent evenly, usage would be here by now'
+            className='absolute -top-1 h-4 w-0.5 -translate-x-1/2 rounded-full bg-fg-1'
+            style={{ left: `${Math.min(100, Math.max(0, pace * 100))}%` }}
+          />
+        ) : null}
+      </div>
+      <div className='mt-1.5 flex items-center gap-3 text-label text-fg-4'>
+        {resetsAtMs !== undefined ? (
+          <span className='inline-flex items-center gap-1'>
+            <RotateCcw className='size-3' /> Resets in {formatCountdown(resetsAtMs, now)}
+          </span>
+        ) : null}
+        {info.isUsingOverage ? <span className='text-warning'>overage</span> : null}
+        {info.status === 'rejected' ? <span className='text-danger'>limit reached</span> : null}
+      </div>
+    </div>
+  )
+}

package/src/components/agent/line-prompt.tsx

@@ -0,0 +1,249 @@
+import { useEffect, useRef, type ReactNode } from 'react'
+import { cn } from '../../lib/utils.ts'
+import { Response } from './Response.tsx'
+import { LineGlyph } from './transcript-variant.tsx'
+
+/**
+ * The parts a terminal-shaped prompt is built from.
+ *
+ * The `lines` transcript answers a question the `cards` one does not have to:
+ * an approval and a question are *interactive*, so "no boxes" has to be paid for
+ * by something else carrying the affordance. That something is the keyboard —
+ * a roving `❯` marker, numbered rows, and a hint line — which is what a terminal
+ * would do anyway, and what makes the prompt answerable without reaching for the
+ * mouse in a dock where the rows are two lines tall.
+ *
+ * Everything here indents to the same gutter as every other line item, so an
+ * approval reads as one more row in the run rather than a dialog dropped on top
+ * of it.
+ */
+
+/** The left inset that lines up body text with a `LineGlyph`'d row above it. */
+export const LINE_INDENT = 'pl-[calc(0.875rem+0.5rem)]'
+
+export type LineChoice = {
+  key: string
+  label: string
+  description?: string
+  /**
+   * Rendered under the row, outside the button — a preview, an input. The caller
+   * decides when it exists (focused, checked); a button may not contain one.
+   */
+  detail?: ReactNode
+  /**
+   * Present → the row carries a selection state and draws it. `marker` says in
+   * which idiom: a checkbox for a multi-select, a radio for a one-of. Absent →
+   * the row is an action (allow, deny), which has no state to show.
+   */
+  checked?: boolean
+  marker?: 'check' | 'radio'
+  danger?: boolean
+}
+
+/** The two-state glyph pairs, in the character forms a terminal would use. */
+const MARKERS = {
+  check: ['[ ]', '[x]'],
+  radio: ['( )', '(•)'],
+} as const
+
+export interface LineOptionListProps {
+  options: LineChoice[]
+  /** Roving index: the one row that is tab-reachable and wears the marker. */
+  focused: number
+  onFocus: (index: number) => void
+  onChoose: (index: number) => void
+  /**
+   * Own the DOM focus, moving it with the roving index. False while something
+   * else inside the prompt holds it (a reason input, another question's list) —
+   * two lists both chasing `focused` would tear the caret back and forth.
+   */
+  active?: boolean
+  label: string
+  className?: string
+}
+
+/**
+ * A keyboard-first list of choices as line items: `↑`/`↓` move, `1`–`9` pick
+ * directly, `Enter`/`Space` take the focused one (the button does that itself).
+ */
+export function LineOptionList({
+  options,
+  focused,
+  onFocus,
+  onChoose,
+  active = true,
+  label,
+  className,
+}: LineOptionListProps) {
+  const refs = useRef<Array<HTMLButtonElement | null>>([])
+
+  useEffect(() => {
+    if (active) refs.current[focused]?.focus()
+  }, [active, focused])
+
+  const move = (delta: number) => {
+    if (options.length > 0) onFocus((focused + delta + options.length) % options.length)
+  }
+
+  return (
+    <div
+      role='group'
+      aria-label={label}
+      className={cn('flex flex-col', className)}
+      onKeyDown={(event) => {
+        if (event.key === 'ArrowDown') {
+          move(1)
+          event.preventDefault()
+          return
+        }
+        if (event.key === 'ArrowUp') {
+          move(-1)
+          event.preventDefault()
+          return
+        }
+        // Digits are the whole point of numbering the rows — but only up to the
+        // rows that exist, so `9` on a three-option prompt stays a no-op rather
+        // than a silent miss.
+        const digit = Number(event.key)
+        if (Number.isInteger(digit) && digit >= 1 && digit <= Math.min(options.length, 9)) {
+          onFocus(digit - 1)
+          onChoose(digit - 1)
+          event.preventDefault()
+        }
+      }}>
+      {options.map((option, index) => {
+        const isFocused = index === focused
+        return (
+          <div key={option.key} className='flex flex-col'>
+            <button
+              ref={(element) => {
+                refs.current[index] = element
+              }}
+              type='button'
+              tabIndex={isFocused ? 0 : -1}
+              aria-pressed={option.checked}
+              onFocus={() => onFocus(index)}
+              onClick={() => onChoose(index)}
+              className={cn(
+                'flex w-full items-baseline gap-2 text-left outline-none',
+                isFocused ? 'bg-surface-hover' : 'hover:bg-surface-hover/60',
+              )}>
+              <LineGlyph className={isFocused ? 'text-accent' : undefined}>
+                {isFocused ? '❯' : ' '}
+              </LineGlyph>
+              <span className='shrink-0 font-mono text-label leading-5 text-fg-4'>{index + 1}</span>
+              {option.checked !== undefined ? (
+                <span
+                  className={cn(
+                    'shrink-0 font-mono text-label leading-5',
+                    option.checked ? 'text-accent' : 'text-fg-4',
+                  )}>
+                  {MARKERS[option.marker ?? 'check'][option.checked ? 1 : 0]}
+                </span>
+              ) : null}
+              <span
+                className={cn(
+                  'min-w-0 flex-1 text-body-sm leading-5',
+                  option.danger ? 'text-danger' : 'text-fg-1',
+                )}>
+                {option.label}
+                {option.description ? (
+                  <span className='text-fg-4'> — {option.description}</span>
+                ) : null}
+              </span>
+            </button>
+            {option.detail ? <div className={LINE_INDENT}>{option.detail}</div> : null}
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+/** The dim key legend under a prompt. Separated by `·`, like a status line. */
+export function LineHint({ children }: { children: ReactNode }) {
+  return (
+    <div className={cn(LINE_INDENT, 'text-label leading-5 text-fg-4')}>{children}</div>
+  )
+}
+
+/** A single-line text field in the terminal idiom: a caret glyph and a rule,
+ * no box. `Enter` commits, `Escape` backs out — the caller says what those mean. */
+export function LineInput({
+  value,
+  onChange,
+  onSubmit,
+  onCancel,
+  placeholder,
+}: {
+  value: string
+  onChange: (value: string) => void
+  onSubmit: () => void
+  onCancel: () => void
+  placeholder?: string
+}) {
+  return (
+    <div className='flex items-baseline gap-2'>
+      <LineGlyph className='text-accent'>›</LineGlyph>
+      <input
+        autoFocus
+        value={value}
+        placeholder={placeholder}
+        onChange={(event) => onChange(event.target.value)}
+        onKeyDown={(event) => {
+          if (event.key === 'Enter') {
+            event.preventDefault()
+            onSubmit()
+          }
+          if (event.key === 'Escape') {
+            // The prompt's own Escape means "deny"/"dismiss"; inside the field it
+            // only closes the field, so it must not travel further.
+            event.stopPropagation()
+            onCancel()
+          }
+        }}
+        className='min-w-0 flex-1 border-b border-border bg-transparent text-body-sm leading-5 text-fg-1 outline-none placeholder:text-fg-4 focus:border-accent'
+      />
+    </div>
+  )
+}
+
+/**
+ * A payload in the terminal idiom: a dim label line over a **highlighted** band.
+ *
+ * Highlighting goes through `Response` — the markdown renderer already carries
+ * shiki, so wrapping the text in a fence costs no new dependency, no second
+ * highlighter and no second theme to keep in sync, and it inherits the terminal
+ * flattening plus the hover copy/download the renderer draws for every code
+ * block. Text with no language still goes through it, as an unlabelled fence:
+ * same band, same grid, no grammar guessed.
+ */
+export function LinePayload({
+  code,
+  label,
+  language,
+  className,
+}: {
+  code: string
+  label: string
+  language?: string
+  className?: string
+}) {
+  return (
+    <div className={cn('min-w-0', className)}>
+      <span className='block truncate text-label leading-5 text-fg-4'>{label}</span>
+      <Response>{fence(code, language)}</Response>
+    </div>
+  )
+}
+
+/**
+ * Wrap text as a markdown code fence, with a fence long enough to survive the
+ * content: a payload containing ``` would otherwise close the block early and
+ * spill the rest of it into the transcript as markdown.
+ */
+export function fence(code: string, language?: string): string {
+  const longest = Math.max(0, ...[...code.matchAll(/`+/g)].map((match) => match[0].length))
+  const ticks = '`'.repeat(Math.max(3, longest + 1))
+  return `${ticks}${language ?? ''}\n${code}\n${ticks}`
+}

package/src/components/agent/pulse.tsx

@@ -0,0 +1,60 @@
+import { useEffect, useState } from 'react'
+
+/**
+ * The brand mark's pulse, as characters — the working marker every surface in the
+ * transcript animates.
+ *
+ * These are the mark's own four states (`docs/assets/BRAND.md`, "The loading
+ * state"): a dot, an outline, a semi and a full diamond, built in the SVG from
+ * two shapes rather than four drawings. 150ms each, so one cycle is the 0.6s
+ * clock the marker pulses on in `icon-loading.svg` — the same rhythm, in the
+ * medium a transcript row actually has.
+ *
+ * BRAND.md's caveat applies and is satisfied here: `U+25C6/7/8` are East-Asian
+ * *ambiguous width*, so they can render double-width in a terminal under an
+ * East-Asian locale and shift every line with them. They are safe wherever the
+ * glyph is centred in a fixed-width box, which is what `LineGlyph` is. Anything
+ * writing to a real terminal must use the ASCII set instead.
+ */
+export const PULSE_FRAMES = ['⋄', '◇', '◈', '◆'] as const
+export const PULSE_MS = 150
+
+/**
+ * The resting state. Stopping the animation lands on the complete mark rather
+ * than on a half-drawn frame — the same property that makes the SVG's
+ * `prefers-reduced-motion` free (see BRAND.md: `translateY(0)` *is* the mark).
+ */
+export const PULSE_REST = PULSE_FRAMES[PULSE_FRAMES.length - 1]
+
+/** The OS-level "stop moving things" setting. A spinner is decoration — the word
+ * beside it carries the meaning — so honouring this costs nothing. */
+export function usePrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(false)
+  useEffect(() => {
+    const query = window.matchMedia?.('(prefers-reduced-motion: reduce)')
+    if (!query) return
+    setReduced(query.matches)
+    const onChange = () => setReduced(query.matches)
+    query.addEventListener('change', onChange)
+    return () => query.removeEventListener('change', onChange)
+  }, [])
+  return reduced
+}
+
+/**
+ * The current pulse frame, ticking while `animated`. Callers mount this only
+ * while something is actually in flight, so nothing here runs on an idle
+ * session; with reduced motion, or when not animating, it holds at rest.
+ */
+export function usePulse(animated: boolean): string {
+  const reduced = usePrefersReducedMotion()
+  const running = animated && !reduced
+  const [frame, setFrame] = useState(0)
+  useEffect(() => {
+    if (!running) return
+    const timer = setInterval(() => setFrame((f) => f + 1), PULSE_MS)
+    return () => clearInterval(timer)
+  }, [running])
+  if (!running) return PULSE_REST
+  return PULSE_FRAMES[frame % PULSE_FRAMES.length]!
+}

package/src/components/agent/transcript-variant.tsx

@@ -0,0 +1,123 @@
+import { createContext, useContext, type ReactNode } from 'react'
+import { cn } from '../../lib/utils.ts'
+
+/**
+ * How the transcript draws a turn.
+ *
+ * - `cards` — the chat convention: bubbles, bordered tool cards, generous gaps.
+ *   Right for a wide dashboard where the transcript is the page.
+ * - `lines` — one full-width line item per event, transparent, hover-highlit,
+ *   with a glyph in a fixed left gutter. Right where vertical space is the
+ *   scarce resource (a VS Code dock) and the terminal is the reference UX:
+ *   nothing is boxed, the content and its marker carry the comprehension.
+ *
+ * A context rather than a prop chain because every row component needs it and
+ * only the transcript root knows it — and because `Message`/`ToolCallCard` are
+ * exported on their own, so an embedder composing them by hand gets the right
+ * treatment for free.
+ */
+export type TranscriptVariant = 'cards' | 'lines'
+
+const VariantContext = createContext<TranscriptVariant>('cards')
+
+export function TranscriptVariantProvider({
+  value,
+  children,
+}: {
+  value: TranscriptVariant
+  children: ReactNode
+}) {
+  return <VariantContext.Provider value={value}>{children}</VariantContext.Provider>
+}
+
+export function useTranscriptVariant(): TranscriptVariant {
+  return useContext(VariantContext)
+}
+
+/** True in `lines`, for the many `cond ? a : b` reads in the row components. */
+export function useLines(): boolean {
+  return useTranscriptVariant() === 'lines'
+}
+
+/**
+ * How much room the transcript gives each row.
+ *
+ * - `comfortable` — a blank line between messages, which is what the Claude Code
+ *   CLI does and what the `lines` variant is trying to read like. The default:
+ *   a transcript is prose before it is a table.
+ * - `compact` — rows tight against each other, for a dock where every line of
+ *   vertical space is contested.
+ *
+ * Separate from the variant, and deliberately: they answer different questions.
+ * The variant decides *how a row is drawn* (boxed or not) and follows from the
+ * surface; density decides *how much air is around it* and is a preference the
+ * reader holds. Coupling them would mean a dock could not be roomy and a
+ * dashboard could not be dense.
+ */
+export type TranscriptDensity = 'comfortable' | 'compact'
+
+const DensityContext = createContext<TranscriptDensity>('comfortable')
+
+export function TranscriptDensityProvider({
+  value,
+  children,
+}: {
+  value: TranscriptDensity
+  children: ReactNode
+}) {
+  return <DensityContext.Provider value={value}>{children}</DensityContext.Provider>
+}
+
+export function useTranscriptDensity(): TranscriptDensity {
+  return useContext(DensityContext)
+}
+
+/**
+ * The gap between two rows, per variant and density — the whole of the density
+ * feature, since it is the only vertical spacing between rows that exists.
+ *
+ * `className` goes on the **measured** wrapper (see `Transcript`), so the gap is
+ * part of each row's measured height and no pixel constant is load-bearing.
+ * `px` is fed to `estimateSize` alone, where being approximate is the contract:
+ * it sets the scrollbar's length before rows mount and is replaced by a real
+ * measurement the moment one does.
+ *
+ * `lines` + `compact` is the only combination with no gap at all: there the
+ * row's own `py-0.5` is the entire separation, which is what makes it compact.
+ */
+export const ROW_GAP: Record<
+  TranscriptVariant,
+  Record<TranscriptDensity, { className?: string; px: number }>
+> = {
+  cards: {
+    comfortable: { className: 'pt-4', px: 16 },
+    compact: { className: 'pt-2', px: 8 },
+  },
+  lines: {
+    // 16px on top of the row's own 4px of `py-0.5` is one 20px line — the blank
+    // line the CLI leaves, arrived at from the line height rather than picked.
+    comfortable: { className: 'pt-4', px: 16 },
+    compact: { px: 0 },
+  },
+}
+
+/**
+ * The left gutter of a line item: one glyph, fixed width, so every row's text
+ * starts on the same column no matter which kind of event it is. Decorative —
+ * the row's own text says what it is.
+ */
+export function LineGlyph({ children, className }: { children: ReactNode; className?: string }) {
+  return (
+    <span
+      aria-hidden
+      className={cn(
+        'w-3.5 shrink-0 select-none text-center font-mono text-label leading-5 text-fg-4',
+        className,
+      )}>
+      {children}
+    </span>
+  )
+}
+
+/** Body text metrics for a line item — tighter than the card variant's. */
+export const LINE_TEXT = 'text-body-sm leading-5'

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

@@ -288,6 +288,59 @@ export function resolveChip(
   return { segments: merged, cursorOffset }
 }
 
+/**
+ * Replaces the active trigger's range with **plain text** instead of a chip.
+ *
+ * The sibling of {@link resolveChip}, for suggestions that are a typing aid
+ * rather than a token: what lands in the document is ordinary editable text the
+ * user is expected to finish and change, and it must not look or behave like a
+ * resolved chip — no immutability, no trigger character, nothing for a consumer
+ * to parse back out. The caret is left at the end of the inserted text so typing
+ * continues from there.
+ */
+export function resolveText(
+  segments: Segment[],
+  activeTrigger: ActiveTrigger,
+  text: string,
+): { segments: Segment[]; cursorOffset: number } {
+  const triggerStart = activeTrigger.startOffset
+  const triggerEnd = triggerStart + 1 + activeTrigger.query.length // +1 for trigger char
+
+  const newSegments: Segment[] = []
+  let offset = 0
+  let cursorOffset = triggerStart + text.length
+
+  for (const seg of segments) {
+    if (seg.type === 'chip') {
+      const chipEnd = offset + `${seg.trigger}${seg.displayText}`.length
+      // A trigger range can never overlap a chip — chips are atomic — so a chip
+      // is either wholly before or wholly after, and is kept either way.
+      if (chipEnd <= triggerStart || offset >= triggerEnd) newSegments.push(seg)
+      offset = chipEnd
+      continue
+    }
+    const textStart = offset
+    const textEnd = offset + seg.text.length
+    if (textEnd <= triggerStart || textStart >= triggerEnd) {
+      newSegments.push(seg)
+    } else {
+      const before = seg.text.slice(0, Math.max(0, triggerStart - textStart))
+      const after = seg.text.slice(Math.min(seg.text.length, triggerEnd - textStart))
+      if (before) newSegments.push({ type: 'text', text: before })
+      newSegments.push({ type: 'text', text })
+      if (after) newSegments.push({ type: 'text', text: after })
+    }
+    offset = textEnd
+  }
+
+  const merged = mergeAdjacentTextSegments(newSegments)
+  // Clamp: a trigger detected against a stale document could otherwise leave the
+  // caret past the end, which renders as no caret at all.
+  const total = segmentsToPlainText(merged).length
+  if (cursorOffset > total) cursorOffset = total
+  return { segments: merged, cursorOffset }
+}
+
 // ---------------------------------------------------------------------------
 // Chip removal
 // ---------------------------------------------------------------------------

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

@@ -103,6 +103,21 @@ export type TriggerConfig = {
    * Return the display text for the chip, or void to use `suggestion.label`.
    */
   onSelect?: (suggestion: TriggerSuggestion) => string | void
+  /**
+   * For 'dropdown' mode: opt a suggestion out of becoming a chip.
+   *
+   * Return a string and the trigger's range is replaced with that **plain,
+   * editable text** — the trigger character included — with the caret left at
+   * its end. Return undefined and the suggestion resolves to a chip as usual,
+   * so one dropdown can mix both kinds.
+   *
+   * For suggestions that are a typing aid rather than a token: something the
+   * user is meant to finish and edit, where a chip would falsely promise the
+   * host parses it back out. Takes precedence over `onSelect`, which is not
+   * called for a text-resolved suggestion (there is no chip to label), and
+   * `onChipAdd` does not fire either.
+   */
+  insertAsText?: (suggestion: TriggerSuggestion) => string | undefined
   /**
    * For 'callback' and 'launch' modes: called when the trigger is activated.
    * Receives the full input text and cursor position. For 'launch' it fires on