@kanzo-tech/ai 0.18.0 → 0.20.0

package/dist/engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine.js","sources":["../src/engine.ts"],"sourcesContent":["\"use client\";\n\n// The machinery behind `Assist`, and none of it is public. A field offers a **proposal** — text the\n// reader may take — and this file is everything about getting proposals out of a stream and keeping\n// them honest while the reader types: one engine, the inline continuation, and the candidate list.\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\n\n/** A value the model offers a field. LSP 3.18's `InlineCompletionItem`, as a field needs it. */\nexport interface Proposal {\n  text: string;\n  /**\n   * What taking it replaces, as `[from, to)` in the field's value: an empty range at the caret is a\n   * continuation, the whole value is a replacement. Absent for a new item in a list field (tags),\n   * where taking it adds rather than edits.\n   */\n  range?: [from: number, to: number];\n  /** Why the model offered it. Shown as the candidate's tooltip. */\n  rationale?: string;\n}\n\n/**\n * What happened to a proposal, for a host that learns from it (HAX G13). The lifecycle VS Code's\n * inline completions report, in one callback: it was **shown**, taken whole (**accepted**) or a word\n * at a time (**partial**), turned down by the reader (**rejected**: Esc, or a candidate's ✕), or\n * left to die because they typed something else (**ignored**).\n */\nexport interface AssistEvent {\n  kind: \"shown\" | \"accepted\" | \"partial\" | \"rejected\" | \"ignored\";\n  proposal: Proposal;\n  /** The field's accessible name — which field it was. */\n  field: string;\n}\n\n/** Where a request has got to. Internal: no surface exposes it, they draw from it. */\nexport type Status = \"idle\" | \"loading\" | \"ready\" | \"error\";\n\nconst message = (e: unknown, fallback: string) =>\n  e instanceof Error && e.message ? e.message : fallback;\n\n// ── The engine ───────────────────────────────────────────────────────────────\n\n/**\n * Open a source and pull it to the end, handing each value to `each`; `false` from `each` stops it.\n * A new run supersedes the one in flight, and resolves to what happened to **this** run, so a loop\n * that outlives its render never reads a stale status.\n */\nexport function useStream<T>(errorText: string) {\n  const [status, setStatus] = useState<Status>(\"idle\");\n  const [error, setError] = useState<string | null>(null);\n  const statusRef = useRef<Status>(\"idle\");\n  const ctrl = useRef<AbortController>(undefined);\n\n  const set = useCallback((s: Status, e: string | null = null) => {\n    statusRef.current = s;\n    setStatus(s);\n    setError(e);\n  }, []);\n\n  useEffect(() => () => ctrl.current?.abort(), []);\n\n  const run = useCallback(\n    (src: (signal: AbortSignal) => AsyncIterable<T>, each: (value: T) => boolean | void) => {\n      ctrl.current?.abort();\n      const c = new AbortController();\n      ctrl.current = c;\n      set(\"loading\");\n\n      return (async (): Promise<Status> => {\n        try {\n          for await (const value of src(c.signal)) {\n            if (c.signal.aborted) return \"idle\";\n            if (each(value) === false) {\n              c.abort();\n              break;\n            }\n          }\n        } catch (e) {\n          if (c.signal.aborted) return \"idle\";\n          set(\"error\", message(e, errorText));\n          return \"error\";\n        }\n        if (ctrl.current === c) set(\"ready\");\n        return \"ready\";\n      })();\n    },\n    [errorText, set],\n  );\n\n  const cancel = useCallback(() => {\n    ctrl.current?.abort();\n    set(\"idle\");\n  }, [set]);\n\n  const reset = useCallback(() => {\n    if (statusRef.current !== \"loading\") set(\"idle\");\n  }, [set]);\n\n  return useMemo(() => ({ run, cancel, reset, status, error }), [cancel, error, reset, run, status]);\n}\n\n/**\n * Run `paint` at most once a frame, and once more on `flush()`. A token stream arrives faster than\n * the display refreshes, so a `setState` per chunk renders work nobody sees.\n */\nfunction coalesce(paint: () => void) {\n  let frame: number | undefined;\n  let queued = false;\n  const run = () => {\n    queued = true;\n    if (frame !== undefined) return;\n    frame = requestAnimationFrame(() => {\n      frame = undefined;\n      queued = false;\n      paint();\n    });\n  };\n  const cancel = () => {\n    if (frame !== undefined) cancelAnimationFrame(frame);\n    frame = undefined;\n    queued = false;\n  };\n  const flush = () => {\n    const pending = queued;\n    cancel();\n    if (pending) paint();\n  };\n  return Object.assign(run, { flush, cancel });\n}\n\n/**\n * The continuation is appended verbatim, with one safety net: a model that restated the value\n * before continuing gets that prefix dropped, and an echo still arriving renders as nothing until it\n * diverges — painting the value twice is worse than a few frames of nothing.\n */\nexport function cleanGhost(base: string, cont: string): string {\n  const b = base.trimEnd();\n  if (!b || !cont) return cont;\n  const lower = { base: b.toLowerCase(), cont: cont.toLowerCase() };\n  if (lower.cont.startsWith(lower.base)) return cont.slice(b.length);\n  if (lower.base.startsWith(lower.cont)) return \"\";\n  return cont;\n}\n\n// ── The continuation: one offer at the caret, with alternatives ──────────────\n\n/** Below this there is not enough text to continue, so nothing is asked. */\nexport const MIN_CONTINUE_LENGTH = 4;\n\nexport type Trigger = \"invoked\" | \"automatic\";\n\nexport interface ContinuationRequest {\n  value: string;\n  position: number;\n  trigger: Trigger;\n  /** Continuations already offered at this point; an alternative must differ from them. */\n  avoid: string[];\n  signal: AbortSignal;\n}\n\ninterface Offer {\n  from: number;\n  text: string;\n  done: boolean;\n}\n\n/**\n * Ghost text that does not own the value: the field owns it and performs the insertion.\n *\n * **The offer survives typing that agrees with it.** An offer made at `from` stays on the table\n * while what was typed since is a prefix of it, and the ghost is what is left — no request at all.\n * That is LSP's `filterText` rule and the only way to Smart Compose's 60 ms budget: not asking.\n *\n * **Alternatives** are LSP's `Invoked` case: asking again at the same point appends a different\n * offer rather than replacing the one on the table, and `cycle` moves between them (Alt+] / Alt+[).\n */\nexport function useContinuation(options: {\n  source: (request: ContinuationRequest) => AsyncIterable<string>;\n  onEvent: (kind: AssistEvent[\"kind\"], proposal: Proposal) => void;\n  debounceMs?: number;\n}) {\n  const { run, cancel, status, error } = useStream<string>(\"Couldn’t complete\");\n  const [ghost, setGhost] = useState(\"\");\n  const opts = useRef(options);\n  opts.current = options;\n\n  const offers = useRef<Offer[]>([]);\n  const index = useRef(0);\n  const field = useRef({ value: \"\", position: 0 });\n  const timer = useRef<ReturnType<typeof setTimeout>>(undefined);\n  const shown = useRef<Offer | null>(null);\n\n  const current = () => offers.current[index.current] ?? null;\n\n  const rendered = useCallback((): string => {\n    const o = current();\n    if (!o) return \"\";\n    const { value, position } = field.current;\n    if (position < o.from) return \"\";\n    const typed = value.slice(o.from, position);\n    return o.text.startsWith(typed) ? o.text.slice(typed.length) : \"\";\n  }, []);\n\n  const alive = useCallback((): boolean => {\n    const o = current();\n    if (!o) return false;\n    const { value, position } = field.current;\n    if (position < o.from) return false;\n    const typed = value.slice(o.from, position);\n    // Typing ahead of a stream still arriving is not a mismatch yet: the next chunk may agree.\n    return o.text.startsWith(typed) || (!o.done && typed.startsWith(o.text));\n  }, []);\n\n  const proposal = (o: Offer): Proposal => ({ text: o.text, range: [o.from, o.from] });\n\n  const painter = useRef<ReturnType<typeof coalesce>>(undefined);\n  painter.current ??= coalesce(() => {\n    const next = rendered();\n    setGhost(next);\n    const o = current();\n    if (next && o && shown.current !== o) {\n      shown.current = o;\n      opts.current.onEvent(\"shown\", proposal(o));\n    }\n  });\n\n  /** Forget every offer. `why` is reported once, for the offer on screen. */\n  const drop = useCallback(\n    (why?: \"rejected\" | \"ignored\") => {\n      clearTimeout(timer.current);\n      painter.current?.cancel();\n      const o = current();\n      if (why && o && shown.current === o) opts.current.onEvent(why, proposal(o));\n      offers.current = [];\n      index.current = 0;\n      shown.current = null;\n      cancel();\n      setGhost(\"\");\n    },\n    [cancel],\n  );\n\n  const start = useCallback(\n    (value: string, position: number, trigger: Trigger) => {\n      const avoid = offers.current.filter((o) => o.from === position).map((o) => o.text);\n      const mine: Offer = { from: position, text: \"\", done: false };\n      offers.current = [...offers.current.filter((o) => o.from === position), mine];\n      index.current = offers.current.length - 1;\n      const base = value.slice(0, position);\n      let raw = \"\";\n      void run(\n        (signal) => opts.current.source({ value, position, trigger, avoid, signal }),\n        (chunk) => {\n          if (current() !== mine) return false;\n          raw += chunk;\n          mine.text = cleanGhost(base, raw);\n          painter.current?.();\n        },\n      ).then((outcome) => {\n        mine.done = true;\n        if (current() !== mine) return;\n        if (outcome === \"ready\") painter.current?.flush();\n        else painter.current?.cancel();\n      });\n    },\n    [run],\n  );\n\n  const short = (value: string) => value.trim().length < MIN_CONTINUE_LENGTH;\n\n  /** The field changed. Ask after a debounce — unless the offer on the table survives it. */\n  const setValue = useCallback(\n    (value: string, position = value.length) => {\n      field.current = { value, position };\n      if (alive()) {\n        setGhost(rendered());\n        return;\n      }\n      drop(\"ignored\");\n      if (short(value)) return;\n      timer.current = setTimeout(\n        () => start(value, position, \"automatic\"),\n        opts.current.debounceMs ?? 350,\n      );\n    },\n    [alive, drop, rendered, start],\n  );\n\n  /** Ask now — the ✨, and Alt+] past the last alternative. */\n  const ask = useCallback(\n    (value: string, position = value.length) => {\n      const same = field.current.value === value && field.current.position === position;\n      field.current = { value, position };\n      if (!same) drop(\"ignored\");\n      clearTimeout(timer.current);\n      if (short(value)) return;\n      start(value, position, \"invoked\");\n    },\n    [drop, start],\n  );\n\n  /** Move between alternatives; past the last one, ask for another. */\n  const cycle = useCallback(\n    (step: 1 | -1) => {\n      const next = index.current + step;\n      if (next < 0) return;\n      if (next >= offers.current.length) {\n        const { value, position } = field.current;\n        ask(value, position);\n        return;\n      }\n      index.current = next;\n      setGhost(rendered());\n      painter.current?.();\n    },\n    [ask, rendered],\n  );\n\n  const settle = useCallback(\n    (kind: \"accepted\" | \"partial\", text: string) => {\n      const o = current();\n      if (o) opts.current.onEvent(kind, { text, range: [field.current.position, field.current.position] });\n      if (kind === \"accepted\") {\n        offers.current = [];\n        index.current = 0;\n        shown.current = null;\n        clearTimeout(timer.current);\n        painter.current?.cancel();\n        cancel();\n        setGhost(\"\");\n      }\n    },\n    [cancel],\n  );\n\n  useEffect(\n    () => () => {\n      clearTimeout(timer.current);\n      painter.current?.cancel();\n    },\n    [],\n  );\n\n  return { ghost, status, error, setValue, ask, cycle, settle, dismiss: drop };\n}\n\n// ── The candidates: N whole values, deduped ──────────────────────────────────\n\nconst norm = (v: string) => v.trim().toLowerCase();\n\n/**\n * A streamed list of whole values, deduped against what the field already holds. A budget rather\n * than a window: nothing refills when one is taken or dismissed.\n */\nexport function useCandidates(options: {\n  source: (request: { existing: string[]; signal: AbortSignal }) => AsyncIterable<Proposal>;\n  existing: string[];\n  onEvent: (kind: AssistEvent[\"kind\"], proposal: Proposal) => void;\n  limit?: number;\n}) {\n  const { run, cancel: abort, reset, status, error } = useStream<Proposal>(\"Couldn’t load suggestions\");\n  const [items, setItems] = useState<Proposal[]>([]);\n  const shown = useRef<Proposal[]>([]);\n  const opts = useRef(options);\n  opts.current = options;\n\n  const put = useCallback((next: Proposal[]) => {\n    shown.current = next;\n    setItems(next);\n  }, []);\n\n  const refresh = useCallback(() => {\n    const { existing, limit = 6, source } = opts.current;\n    const seen = new Set(existing.map(norm).filter(Boolean));\n    const taken: Proposal[] = [];\n    put([]);\n    void run(\n      (signal) => source({ existing, signal }),\n      (item) => {\n        const key = norm(item.text);\n        if (!key || seen.has(key)) return true;\n        seen.add(key);\n        taken.push(item);\n        put([...taken]);\n        opts.current.onEvent(\"shown\", item);\n        return taken.length < limit;\n      },\n    );\n  }, [put, run]);\n\n  /** The ✨: a first set, a different set, or a retry — never inert, except while loading. */\n  const press = useCallback(() => {\n    if (status === \"loading\") return;\n    refresh();\n  }, [refresh, status]);\n\n  const remove = useCallback(\n    (text: string, kind: \"accepted\" | \"rejected\") => {\n      const key = norm(text);\n      const item = shown.current.find((p) => norm(p.text) === key);\n      if (item) opts.current.onEvent(kind, item);\n      const next = shown.current.filter((p) => norm(p.text) !== key);\n      put(next);\n      // Nothing left of an answer is not an answer with nothing in it.\n      if (next.length === 0) reset();\n    },\n    [put, reset],\n  );\n\n  const cancel = useCallback(() => {\n    abort();\n    put([]);\n  }, [abort, put]);\n\n  return { items, status, error, press, take: (t: string) => remove(t, \"accepted\"), dismiss: (t: string) => remove(t, \"rejected\"), cancel };\n}\n"],"names":[],"mappings":";;AAqCA;AAUO;AACL;AAME;AAEU;AAGZ;;AAAsB;AAAc;AAEpC;AAAY;;AAER;AACA;AACA;AAIE;AACE;AACE;AACA;AACE;AACA;AAAA;AACF;AACF;AAEA;AAEO;AAET;AACO;AACT;AACF;AACe;;AAIf;AACU;AAIV;AAA+C;AAGjD;AACF;AAMA;AACE;AAEA;AAEE;AAEE;AAEA;AACD;AAGD;AAES;AAOX;AAJE;AACA;AACa;AAGjB;AAOO;AACL;AACA;AACA;AACA;AAGF;AAKO;AA6BA;AAKL;AAGA;AAEA;AASE;AACA;AACA;AACA;AACA;AACA;AAA+D;AAI/D;AACA;AACA;AACA;AACA;AAEA;AAAsE;AAMxE;AACE;AACA;AACA;AACA;AAE2C;AAK7C;AAAa;;AAET;AAEA;AACA;AAKW;AACb;AACO;AAGK;AAEV;AAEA;AAEA;AACA;AACA;AAAK;AACwE;;AAEzE;AACA;AAEA;AACF;;AAGA;AAEsB;AACvB;AACH;AACI;AAMW;AAGb;AACE;AACA;AAAA;AAGF;AACgB;AAC0B;AACb;AAAA;AAE/B;AAC6B;AAInB;AAER;AAIA;AACgC;AAClC;AACY;AAIA;;AAEV;AACA;AACA;AACE;AACA;AACA;AAAA;AAEF;AAEA;AAAA;AACF;AACc;AAGD;;AAGX;AAQa;AAEf;AACO;AAGT;AAAA;;AAEI;AACiB;AACnB;AACA;AAIJ;AAIA;AAMO;AAML;AAIA;AAEA;AACE;AACa;AAIb;AAGA;AACK;AACoC;AAErC;AACA;AAKsB;AACxB;AAAA;AAMF;AACA;AAGa;AAEX;AAEA;AACA;AACA;AAEuB;AACzB;AACW;AAIX;AACM;AAGR;AACF;;;;;;;;"}
+{"version":3,"file":"engine.js","sources":["../src/engine.ts"],"sourcesContent":["\"use client\";\n\n// The machinery behind `Assist`, and none of it is public. A field offers a **proposal** — text the\n// reader may take — and this file is everything about getting proposals out of a stream and keeping\n// them honest while the reader types: one engine, the inline continuation, and the candidate list.\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\n\n/** A value the model offers a field. LSP 3.18's `InlineCompletionItem`, as a field needs it. */\nexport interface Proposal {\n  text: string;\n  /**\n   * What taking it replaces, as `[from, to)` in the field's value: an empty range at the caret is a\n   * continuation, the whole value is a replacement. Absent for a new item in a list field (tags),\n   * where taking it adds rather than edits.\n   */\n  range?: [from: number, to: number];\n  /** Why the model offered it. Shown as the candidate's tooltip. */\n  rationale?: string;\n}\n\n/**\n * What happened to a proposal, for a host that learns from it (HAX G13). The lifecycle VS Code's\n * inline completions report, in one callback: it was **shown**, taken whole (**accepted**) or a word\n * at a time (**partial**), turned down by the reader (**rejected**: Esc, or a candidate's ✕), or\n * left to die because they typed something else (**ignored**).\n */\nexport interface AssistEvent {\n  kind: \"shown\" | \"accepted\" | \"partial\" | \"rejected\" | \"ignored\";\n  proposal: Proposal;\n  /** The field's accessible name — which field it was. */\n  field: string;\n}\n\n/** Where a request has got to. Internal: no surface exposes it, they draw from it. */\nexport type Status = \"idle\" | \"loading\" | \"ready\" | \"error\";\n\n/** How long a stream may go without sending anything, the first chunk included. */\nconst SILENT_AFTER = 30_000;\n\n/** The one failure this package names: the model stopped sending without closing the stream. */\nexport class AiError extends Error {\n  override readonly name = \"AiError\";\n  constructor(\n    readonly code: \"ai/silent\",\n    message: string,\n    readonly data: { readonly after?: number } = {},\n    options?: ErrorOptions,\n  ) {\n    super(message, options);\n  }\n}\n\n/**\n * `pending`, unless `c` aborts first or nothing arrives within {@link SILENT_AFTER} — then `c` is\n * aborted with an `ai/silent` `AiError`, which this rejects with.\n */\nfunction heard<T>(pending: Promise<T>, c: AbortController): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    const settle = () => {\n      clearTimeout(timer);\n      c.signal.removeEventListener(\"abort\", aborted);\n    };\n    const aborted = () => {\n      settle();\n      reject(c.signal.reason);\n    };\n    const timer = setTimeout(\n      () => c.abort(new AiError(\"ai/silent\", `The model sent nothing for ${SILENT_AFTER} ms`, { after: SILENT_AFTER })),\n      SILENT_AFTER,\n    );\n    if (c.signal.aborted) return aborted();\n    c.signal.addEventListener(\"abort\", aborted);\n    pending.then(\n      (value) => {\n        settle();\n        resolve(value);\n      },\n      (e: unknown) => {\n        settle();\n        reject(e);\n      },\n    );\n  });\n}\n\n// ── The engine ───────────────────────────────────────────────────────────────\n\n/**\n * Open a source and pull it to the end, handing each value to `each`; `false` from `each` stops it.\n * A new run supersedes the one in flight, and resolves to what happened to **this** run, so a loop\n * that outlives its render never reads a stale status.\n */\nexport function useStream<T>() {\n  const [status, setStatus] = useState<Status>(\"idle\");\n  /** What the source threw, as thrown, while `status` is `\"error\"`. */\n  const [error, setError] = useState<unknown>(undefined);\n  const statusRef = useRef<Status>(\"idle\");\n  const ctrl = useRef<AbortController>(undefined);\n\n  const set = useCallback((s: Status, e?: unknown) => {\n    statusRef.current = s;\n    setStatus(s);\n    setError(e);\n  }, []);\n\n  useEffect(() => () => ctrl.current?.abort(), []);\n\n  const run = useCallback(\n    (src: (signal: AbortSignal) => AsyncIterable<T>, each: (value: T) => boolean | void) => {\n      ctrl.current?.abort();\n      const c = new AbortController();\n      ctrl.current = c;\n      set(\"loading\");\n\n      return (async (): Promise<Status> => {\n        try {\n          const it = src(c.signal)[Symbol.asyncIterator]();\n          for (;;) {\n            const res = await heard(it.next(), c);\n            if (c.signal.aborted) return \"idle\";\n            if (res.done) break;\n            if (each(res.value) === false) {\n              c.abort();\n              break;\n            }\n          }\n        } catch (e) {\n          // A cancellation is not a failure to report — the caller asked for it. Silence is.\n          if (c.signal.aborted && !(c.signal.reason instanceof AiError)) return \"idle\";\n          if (!c.signal.aborted) c.abort();\n          set(\"error\", e);\n          return \"error\";\n        }\n        if (ctrl.current === c) set(\"ready\");\n        return \"ready\";\n      })();\n    },\n    [set],\n  );\n\n  const cancel = useCallback(() => {\n    ctrl.current?.abort();\n    set(\"idle\");\n  }, [set]);\n\n  const reset = useCallback(() => {\n    if (statusRef.current !== \"loading\") set(\"idle\");\n  }, [set]);\n\n  return useMemo(() => ({ run, cancel, reset, status, error }), [cancel, error, reset, run, status]);\n}\n\n/**\n * Run `paint` at most once a frame, and once more on `flush()`. A token stream arrives faster than\n * the display refreshes, so a `setState` per chunk renders work nobody sees.\n */\nfunction coalesce(paint: () => void) {\n  let frame: number | undefined;\n  let queued = false;\n  const run = () => {\n    queued = true;\n    if (frame !== undefined) return;\n    frame = requestAnimationFrame(() => {\n      frame = undefined;\n      queued = false;\n      paint();\n    });\n  };\n  const cancel = () => {\n    if (frame !== undefined) cancelAnimationFrame(frame);\n    frame = undefined;\n    queued = false;\n  };\n  const flush = () => {\n    const pending = queued;\n    cancel();\n    if (pending) paint();\n  };\n  return Object.assign(run, { flush, cancel });\n}\n\n/**\n * The continuation is appended verbatim, with one safety net: a model that restated the value\n * before continuing gets that prefix dropped, and an echo still arriving renders as nothing until it\n * diverges — painting the value twice is worse than a few frames of nothing.\n */\nexport function cleanGhost(base: string, cont: string): string {\n  const b = base.trimEnd();\n  if (!b || !cont) return cont;\n  const lower = { base: b.toLowerCase(), cont: cont.toLowerCase() };\n  if (lower.cont.startsWith(lower.base)) return cont.slice(b.length);\n  if (lower.base.startsWith(lower.cont)) return \"\";\n  return cont;\n}\n\n// ── The continuation: one offer at the caret, with alternatives ──────────────\n\n/** Below this there is not enough text to continue, so nothing is asked. */\nexport const MIN_CONTINUE_LENGTH = 4;\n\nexport type Trigger = \"invoked\" | \"automatic\";\n\nexport interface ContinuationRequest {\n  value: string;\n  position: number;\n  trigger: Trigger;\n  /** Continuations already offered at this point; an alternative must differ from them. */\n  avoid: string[];\n  signal: AbortSignal;\n}\n\ninterface Offer {\n  from: number;\n  text: string;\n  done: boolean;\n}\n\n/**\n * Ghost text that does not own the value: the field owns it and performs the insertion.\n *\n * **The offer survives typing that agrees with it.** An offer made at `from` stays on the table\n * while what was typed since is a prefix of it, and the ghost is what is left — no request at all.\n * That is LSP's `filterText` rule and the only way to Smart Compose's 60 ms budget: not asking.\n *\n * **Alternatives** are LSP's `Invoked` case: asking again at the same point appends a different\n * offer rather than replacing the one on the table, and `cycle` moves between them (Alt+] / Alt+[).\n */\nexport function useContinuation(options: {\n  source: (request: ContinuationRequest) => AsyncIterable<string>;\n  onEvent: (kind: AssistEvent[\"kind\"], proposal: Proposal) => void;\n  debounceMs?: number;\n}) {\n  const { run, cancel, status, error } = useStream<string>();\n  const [ghost, setGhost] = useState(\"\");\n  const opts = useRef(options);\n  opts.current = options;\n\n  const offers = useRef<Offer[]>([]);\n  const index = useRef(0);\n  const field = useRef({ value: \"\", position: 0 });\n  const timer = useRef<ReturnType<typeof setTimeout>>(undefined);\n  const shown = useRef<Offer | null>(null);\n\n  const current = () => offers.current[index.current] ?? null;\n\n  const rendered = useCallback((): string => {\n    const o = current();\n    if (!o) return \"\";\n    const { value, position } = field.current;\n    if (position < o.from) return \"\";\n    const typed = value.slice(o.from, position);\n    return o.text.startsWith(typed) ? o.text.slice(typed.length) : \"\";\n  }, []);\n\n  const alive = useCallback((): boolean => {\n    const o = current();\n    if (!o) return false;\n    const { value, position } = field.current;\n    if (position < o.from) return false;\n    const typed = value.slice(o.from, position);\n    // Typing ahead of a stream still arriving is not a mismatch yet: the next chunk may agree.\n    return o.text.startsWith(typed) || (!o.done && typed.startsWith(o.text));\n  }, []);\n\n  const proposal = (o: Offer): Proposal => ({ text: o.text, range: [o.from, o.from] });\n\n  const painter = useRef<ReturnType<typeof coalesce>>(undefined);\n  painter.current ??= coalesce(() => {\n    const next = rendered();\n    setGhost(next);\n    const o = current();\n    if (next && o && shown.current !== o) {\n      shown.current = o;\n      opts.current.onEvent(\"shown\", proposal(o));\n    }\n  });\n\n  /** Forget every offer. `why` is reported once, for the offer on screen. */\n  const drop = useCallback(\n    (why?: \"rejected\" | \"ignored\") => {\n      clearTimeout(timer.current);\n      painter.current?.cancel();\n      const o = current();\n      if (why && o && shown.current === o) opts.current.onEvent(why, proposal(o));\n      offers.current = [];\n      index.current = 0;\n      shown.current = null;\n      cancel();\n      setGhost(\"\");\n    },\n    [cancel],\n  );\n\n  const start = useCallback(\n    (value: string, position: number, trigger: Trigger) => {\n      const avoid = offers.current.filter((o) => o.from === position).map((o) => o.text);\n      const mine: Offer = { from: position, text: \"\", done: false };\n      offers.current = [...offers.current.filter((o) => o.from === position), mine];\n      index.current = offers.current.length - 1;\n      const base = value.slice(0, position);\n      let raw = \"\";\n      void run(\n        (signal) => opts.current.source({ value, position, trigger, avoid, signal }),\n        (chunk) => {\n          if (current() !== mine) return false;\n          raw += chunk;\n          mine.text = cleanGhost(base, raw);\n          painter.current?.();\n        },\n      ).then((outcome) => {\n        mine.done = true;\n        if (current() !== mine) return;\n        if (outcome === \"ready\") return painter.current?.flush();\n        painter.current?.cancel();\n        // A failed stream's half a continuation is not an offer; the failure is `error`.\n        if (outcome === \"error\") {\n          mine.text = \"\";\n          setGhost(\"\");\n        }\n      });\n    },\n    [run],\n  );\n\n  const short = (value: string) => value.trim().length < MIN_CONTINUE_LENGTH;\n\n  /** The field changed. Ask after a debounce — unless the offer on the table survives it. */\n  const setValue = useCallback(\n    (value: string, position = value.length) => {\n      field.current = { value, position };\n      if (alive()) {\n        setGhost(rendered());\n        return;\n      }\n      drop(\"ignored\");\n      if (short(value)) return;\n      timer.current = setTimeout(\n        () => start(value, position, \"automatic\"),\n        opts.current.debounceMs ?? 350,\n      );\n    },\n    [alive, drop, rendered, start],\n  );\n\n  /** Ask now — the ✨, and Alt+] past the last alternative. */\n  const ask = useCallback(\n    (value: string, position = value.length) => {\n      const same = field.current.value === value && field.current.position === position;\n      field.current = { value, position };\n      if (!same) drop(\"ignored\");\n      clearTimeout(timer.current);\n      if (short(value)) return;\n      start(value, position, \"invoked\");\n    },\n    [drop, start],\n  );\n\n  /** Move between alternatives; past the last one, ask for another. */\n  const cycle = useCallback(\n    (step: 1 | -1) => {\n      const next = index.current + step;\n      if (next < 0) return;\n      if (next >= offers.current.length) {\n        const { value, position } = field.current;\n        ask(value, position);\n        return;\n      }\n      index.current = next;\n      setGhost(rendered());\n      painter.current?.();\n    },\n    [ask, rendered],\n  );\n\n  const settle = useCallback(\n    (kind: \"accepted\" | \"partial\", text: string) => {\n      const o = current();\n      if (o) opts.current.onEvent(kind, { text, range: [field.current.position, field.current.position] });\n      if (kind === \"accepted\") {\n        offers.current = [];\n        index.current = 0;\n        shown.current = null;\n        clearTimeout(timer.current);\n        painter.current?.cancel();\n        cancel();\n        setGhost(\"\");\n      }\n    },\n    [cancel],\n  );\n\n  useEffect(\n    () => () => {\n      clearTimeout(timer.current);\n      painter.current?.cancel();\n    },\n    [],\n  );\n\n  return { ghost, status, error, setValue, ask, cycle, settle, dismiss: drop };\n}\n\n// ── The candidates: N whole values, deduped ──────────────────────────────────\n\nconst norm = (v: string) => v.trim().toLowerCase();\n\n/**\n * A streamed list of whole values, deduped against what the field already holds. A budget rather\n * than a window: nothing refills when one is taken or dismissed.\n */\nexport function useCandidates(options: {\n  source: (request: { existing: string[]; signal: AbortSignal }) => AsyncIterable<Proposal>;\n  existing: string[];\n  onEvent: (kind: AssistEvent[\"kind\"], proposal: Proposal) => void;\n  limit?: number;\n}) {\n  const { run, cancel: abort, reset, status, error } = useStream<Proposal>();\n  const [items, setItems] = useState<Proposal[]>([]);\n  const shown = useRef<Proposal[]>([]);\n  const opts = useRef(options);\n  opts.current = options;\n\n  const put = useCallback((next: Proposal[]) => {\n    shown.current = next;\n    setItems(next);\n  }, []);\n\n  const refresh = useCallback(() => {\n    const { existing, limit = 6, source } = opts.current;\n    const seen = new Set(existing.map(norm).filter(Boolean));\n    const taken: Proposal[] = [];\n    put([]);\n    void run(\n      (signal) => source({ existing, signal }),\n      (item) => {\n        const key = norm(item.text);\n        if (!key || seen.has(key)) return true;\n        seen.add(key);\n        taken.push(item);\n        put([...taken]);\n        opts.current.onEvent(\"shown\", item);\n        return taken.length < limit;\n      },\n    );\n  }, [put, run]);\n\n  /** The ✨: a first set, a different set, or a retry — never inert, except while loading. */\n  const press = useCallback(() => {\n    if (status === \"loading\") return;\n    refresh();\n  }, [refresh, status]);\n\n  const remove = useCallback(\n    (text: string, kind: \"accepted\" | \"rejected\") => {\n      const key = norm(text);\n      const item = shown.current.find((p) => norm(p.text) === key);\n      if (item) opts.current.onEvent(kind, item);\n      const next = shown.current.filter((p) => norm(p.text) !== key);\n      put(next);\n      // Nothing left of an answer is not an answer with nothing in it.\n      if (next.length === 0) reset();\n    },\n    [put, reset],\n  );\n\n  const cancel = useCallback(() => {\n    abort();\n    put([]);\n  }, [abort, put]);\n\n  return { items, status, error, press, take: (t: string) => remove(t, \"accepted\"), dismiss: (t: string) => remove(t, \"rejected\"), cancel };\n}\n"],"names":[],"mappings":";;;;;AAsCA;AAGO;AAA4B;AAQ/B;AAPgB;AAEP;AAEA;AAKb;AAMA;AACE;AACE;AACE;AAC6C;AAG7C;AACsB;AAEV;AACoG;AAChH;AAEF;AACA;AACQ;AAEJ;AACa;AACf;AAEE;AACQ;AACV;AAAA;AAGN;AASO;AACL;AAOE;AAEU;AAGZ;;AAAsB;AAAc;AAEpC;AAAY;;AAER;AACA;AACA;AAIE;AACE;AACA;AACE;AACA;AACA;AACA;AACE;AACA;AAAA;AACF;AACF;AAGA;AAGO;AAET;AACO;AACT;AACF;AACI;;AAIJ;AACU;AAIV;AAA+C;AAGjD;AACF;AAMA;AACE;AAEA;AAEE;AAEE;AAEA;AACD;AAGD;AAES;AAOX;AAJE;AACA;AACa;AAGjB;AAOO;AACL;AACA;AACA;AACA;AAGF;AAKO;AA6BA;AAKL;AAGA;AAEA;AASE;AACA;AACA;AACA;AACA;AACA;AAA+D;AAI/D;AACA;AACA;AACA;AACA;AAEA;AAAsE;AAMxE;AACE;AACA;AACA;AACA;AAE2C;AAK7C;AAAa;;AAET;AAEA;AACA;AAKW;AACb;AACO;AAGK;AAEV;AAEA;AAEA;AACA;AACA;AAAK;AACwE;;AAEzE;AACA;AAEA;AACF;;AAGA;AACA;AACA;AAIa;AAAA;AAEd;AACH;AACI;AAMW;AAGb;AACE;AACA;AAAA;AAGF;AACgB;AAC0B;AACb;AAAA;AAE/B;AAC6B;AAInB;AAER;AAIA;AACgC;AAClC;AACY;AAIA;;AAEV;AACA;AACA;AACE;AACA;AACA;AAAA;AAEF;AAEA;AAAA;AACF;AACc;AAGD;;AAGX;AAQa;AAEf;AACO;AAGT;AAAA;;AAEI;AACiB;AACnB;AACA;AAIJ;AAIA;AAMO;AAML;AAIA;AAEA;AACE;AACa;AAIb;AAGA;AACK;AACoC;AAErC;AACA;AAKsB;AACxB;AAAA;AAMF;AACA;AAGa;AAEX;AAEA;AACA;AACA;AAEuB;AACzB;AACW;AAIX;AACM;AAGR;AACF;;;;;;;;;"}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { AssistProvider, Assist } from './assist.js';
 export type { AssistProviderProps, AssistProps, AssistTranslations } from './assist.js';
+export { AiError } from './engine.js';
 export type { AssistEvent, Proposal } from './engine.js';
 export { Chat } from './chat.js';
 export type { ChatProps, ChatToolRenderers, ChatTranslations } from './chat.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACxF,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAChF,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAChF,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -1,10 +1,12 @@
-import { Assist as s, AssistProvider as t } from "./assist.js";
-import { Chat as f } from "./chat.js";
-import { useChat as m } from "@ai-sdk/react";
+import { Assist as t, AssistProvider as s } from "./assist.js";
+import { AiError as f } from "./engine.js";
+import { Chat as m } from "./chat.js";
+import { useChat as x } from "@ai-sdk/react";
 export {
-  s as Assist,
-  t as AssistProvider,
-  f as Chat,
-  m as useChat
+  f as AiError,
+  t as Assist,
+  s as AssistProvider,
+  m as Chat,
+  x as useChat
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;"}

package/dist/proposals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proposals.d.ts","sourceRoot":"","sources":["../src/proposals.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,aAAa,EAAkC,MAAM,iBAAiB,CAAC;AACrF,OAAO,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEjE,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAgBD,+CAA+C;AAC/C,wBAAgB,YAAY,CAC1B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,UAAU,EACjB,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,mBAAmB,GAC/D,aAAa,CAAC,MAAM,CAAC,CAWvB;AAcD;;;GAGG;AACH,wBAAuB,UAAU,CAC/B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,UAAU,EACjB,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,IAAI,EAAE,OAAO,CAAC;CACf,GACA,aAAa,CAAC,QAAQ,CAAC,CAgBzB"}
+{"version":3,"file":"proposals.d.ts","sourceRoot":"","sources":["../src/proposals.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,aAAa,EAAkC,MAAM,iBAAiB,CAAC;AACrF,OAAO,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEjE,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA+BD,+CAA+C;AAC/C,wBAAuB,YAAY,CACjC,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,UAAU,EACjB,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,mBAAmB,GAC/D,aAAa,CAAC,MAAM,CAAC,CAcvB;AAcD;;;GAGG;AACH,wBAAuB,UAAU,CAC/B,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,UAAU,EACjB,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,IAAI,EAAE,OAAO,CAAC;CACf,GACA,aAAa,CAAC,QAAQ,CAAC,CAmBzB"}

package/dist/proposals.js

@@ -1,4 +1,4 @@
-import { streamText as u, Output as p, jsonSchema as h } from "@kanzo-tech/llm";
+import { streamText as p, Output as h, jsonSchema as f } from "@kanzo-tech/llm";
 const m = (e) => [
   `Field: ${e.name || "(unnamed)"}`,
   e.description && `Field description: ${e.description}`,
@@ -6,26 +6,36 @@ const m = (e) => [
   e.context && `Form context:
 ${e.context}`
 ].filter(Boolean).join(`
-`), d = `You complete text inside a form field, like an editor's inline completion.
+`), g = `You complete text inside a form field, like an editor's inline completion.
 Reply with ONLY the text to insert at <caret/>: no quotes, no commentary, never repeat text that is already there.
 Keep the language, tone and format of the existing text. Stop at a natural point: the end of the sentence for an automatic suggestion; up to a short paragraph when explicitly asked.`;
-function y(e, i, { value: t, position: o, trigger: s, avoid: r, signal: a }) {
-  const l = `${t.slice(0, o)}<caret/>${t.slice(o)}`, c = r.length ? `
+function d() {
+  let e;
+  return {
+    onError: ({ error: n }) => void (e ?? (e = { error: n })),
+    rethrow: () => {
+      if (e) throw e.error;
+    }
+  };
+}
+async function* E(e, n, { value: t, position: o, trigger: c, avoid: a, signal: i }) {
+  const u = `${t.slice(0, o)}<caret/>${t.slice(o)}`, s = a.length ? `
 Offer something different from these earlier suggestions:
-${r.map((n) => `- ${n.trim()}`).join(`
-`)}` : "";
-  return u({
+${a.map((r) => `- ${r.trim()}`).join(`
+`)}` : "", l = d();
+  yield* p({
     model: e,
-    system: d,
-    prompt: `${m(i)}
-Request: ${s}${c}
+    system: g,
+    prompt: `${m(n)}
+Request: ${c}${s}
 
 Text:
-${l}`,
-    abortSignal: a
-  }).textStream;
+${u}`,
+    abortSignal: i,
+    onError: l.onError
+  }).textStream, l.rethrow();
 }
-const f = h({
+const y = f({
   type: "object",
   properties: {
     value: { type: "string", description: "The whole value, exactly as it would be entered." },
@@ -33,24 +43,26 @@ const f = h({
   },
   required: ["value", "rationale"],
   additionalProperties: !1
-}), g = "You suggest values for a form field. Each value must be complete and ready to enter as-is, in the language of the form.";
-async function* x(e, i, { value: t, existing: o, signal: s, count: r, list: a }) {
-  const l = a ? `Current items: ${o.length ? o.join(", ") : "(none)"}
+}), $ = "You suggest values for a form field. Each value must be complete and ready to enter as-is, in the language of the form.";
+async function* w(e, n, { value: t, existing: o, signal: c, count: a, list: i }) {
+  const u = i ? `Current items: ${o.length ? o.join(", ") : "(none)"}
 Suggest NEW items, not already present.` : `Current value: ${t || "(empty)"}
-Suggest alternatives to replace it${t ? ", different from it" : ""}.`, c = u({
+Suggest alternatives to replace it${t ? ", different from it" : ""}.`, s = d(), l = p({
     model: e,
-    system: g,
-    prompt: `${m(i)}
-${l}
-Give ${r}.`,
-    output: p.array({ element: f }),
-    abortSignal: s
+    onError: s.onError,
+    system: $,
+    prompt: `${m(n)}
+${u}
+Give ${a}.`,
+    output: h.array({ element: y }),
+    abortSignal: c
   });
-  for await (const n of c.elementStream)
-    yield a ? { text: n.value, rationale: n.rationale } : { text: n.value, rationale: n.rationale, range: [0, t.length] };
+  for await (const r of l.elementStream)
+    yield i ? { text: r.value, rationale: r.rationale } : { text: r.value, rationale: r.rationale, range: [0, t.length] };
+  s.rethrow();
 }
 export {
-  x as candidates,
-  y as continuation
+  w as candidates,
+  E as continuation
 };
 //# sourceMappingURL=proposals.js.map

package/dist/proposals.js.map

@@ -1 +1 @@
-{"version":3,"file":"proposals.js","sources":["../src/proposals.ts"],"sourcesContent":["// What a field asks the model, written once. A host names the model and, at most, a sentence of\n// instructions; the field describes itself through its accessible name and description, which is\n// what a person filling it in reads too.\n\nimport { type LanguageModel, Output, jsonSchema, streamText } from \"@kanzo-tech/llm\";\nimport type { ContinuationRequest, Proposal } from \"./engine.js\";\n\n/** What the model is told about the field it is filling. */\nexport interface FieldBrief {\n  /** The accessible name — the label a person reads. */\n  name: string;\n  /** The accessible description — the helper text under it. */\n  description?: string;\n  /** The host's own instruction for this field (`<Assist instructions>`). */\n  instructions?: string;\n  /** What the rest of the form says (`<AssistProvider context>`). */\n  context?: string;\n}\n\nconst brief = (field: FieldBrief) =>\n  [\n    `Field: ${field.name || \"(unnamed)\"}`,\n    field.description && `Field description: ${field.description}`,\n    field.instructions && `Instructions: ${field.instructions}`,\n    field.context && `Form context:\\n${field.context}`,\n  ]\n    .filter(Boolean)\n    .join(\"\\n\");\n\nconst CONTINUE = `You complete text inside a form field, like an editor's inline completion.\nReply with ONLY the text to insert at <caret/>: no quotes, no commentary, never repeat text that is already there.\nKeep the language, tone and format of the existing text. Stop at a natural point: the end of the sentence for an automatic suggestion; up to a short paragraph when explicitly asked.`;\n\n/** One continuation at the caret, streamed. */\nexport function continuation(\n  model: LanguageModel,\n  field: FieldBrief,\n  { value, position, trigger, avoid, signal }: ContinuationRequest,\n): AsyncIterable<string> {\n  const text = `${value.slice(0, position)}<caret/>${value.slice(position)}`;\n  const differ = avoid.length\n    ? `\\nOffer something different from these earlier suggestions:\\n${avoid.map((a) => `- ${a.trim()}`).join(\"\\n\")}`\n    : \"\";\n  return streamText({\n    model,\n    system: CONTINUE,\n    prompt: `${brief(field)}\\nRequest: ${trigger}${differ}\\n\\nText:\\n${text}`,\n    abortSignal: signal,\n  }).textStream;\n}\n\nconst CANDIDATE = jsonSchema<{ value: string; rationale: string }>({\n  type: \"object\",\n  properties: {\n    value: { type: \"string\", description: \"The whole value, exactly as it would be entered.\" },\n    rationale: { type: \"string\", description: \"Why it fits, in one short sentence.\" },\n  },\n  required: [\"value\", \"rationale\"],\n  additionalProperties: false,\n});\n\nconst CANDIDATES = `You suggest values for a form field. Each value must be complete and ready to enter as-is, in the language of the form.`;\n\n/**\n * Whole values for the field, each arriving as soon as it is complete (`elementStream`), so the\n * first candidate is on screen while the model writes the rest.\n */\nexport async function* candidates(\n  model: LanguageModel,\n  field: FieldBrief,\n  { value, existing, signal, count, list }: {\n    value: string;\n    existing: string[];\n    signal: AbortSignal;\n    count: number;\n    /** The field holds a list (tags): a candidate is one more item, not a replacement. */\n    list: boolean;\n  },\n): AsyncIterable<Proposal> {\n  const holds = list\n    ? `Current items: ${existing.length ? existing.join(\", \") : \"(none)\"}\\nSuggest NEW items, not already present.`\n    : `Current value: ${value || \"(empty)\"}\\nSuggest alternatives to replace it${value ? \", different from it\" : \"\"}.`;\n  const result = streamText({\n    model,\n    system: CANDIDATES,\n    prompt: `${brief(field)}\\n${holds}\\nGive ${count}.`,\n    output: Output.array({ element: CANDIDATE }),\n    abortSignal: signal,\n  });\n  for await (const item of result.elementStream) {\n    yield list\n      ? { text: item.value, rationale: item.rationale }\n      : { text: item.value, rationale: item.rationale, range: [0, value.length] };\n  }\n}\n"],"names":["brief","field","CONTINUE","continuation","model","value","position","trigger","avoid","signal","text","differ","a","streamText","CANDIDATE","jsonSchema","CANDIDATES","candidates","existing","count","list","holds","result","Output","item"],"mappings":";AAmBA,MAAMA,IAAQ,CAACC,MACb;AAAA,EACE,UAAUA,EAAM,QAAQ,WAAW;AAAA,EACnCA,EAAM,eAAe,sBAAsBA,EAAM,WAAW;AAAA,EAC5DA,EAAM,gBAAgB,iBAAiBA,EAAM,YAAY;AAAA,EACzDA,EAAM,WAAW;AAAA,EAAkBA,EAAM,OAAO;AAClD,EACG,OAAO,OAAO,EACd,KAAK;AAAA,CAAI,GAERC,IAAW;AAAA;AAAA;AAKV,SAASC,EACdC,GACAH,GACA,EAAE,OAAAI,GAAO,UAAAC,GAAU,SAAAC,GAAS,OAAAC,GAAO,QAAAC,KACZ;AACvB,QAAMC,IAAO,GAAGL,EAAM,MAAM,GAAGC,CAAQ,CAAC,WAAWD,EAAM,MAAMC,CAAQ,CAAC,IAClEK,IAASH,EAAM,SACjB;AAAA;AAAA,EAAgEA,EAAM,IAAI,CAACI,MAAM,KAAKA,EAAE,KAAA,CAAM,EAAE,EAAE,KAAK;AAAA,CAAI,CAAC,KAC5G;AACJ,SAAOC,EAAW;AAAA,IAChB,OAAAT;AAAA,IACA,QAAQF;AAAA,IACR,QAAQ,GAAGF,EAAMC,CAAK,CAAC;AAAA,WAAcM,CAAO,GAAGI,CAAM;AAAA;AAAA;AAAA,EAAcD,CAAI;AAAA,IACvE,aAAaD;AAAA,EAAA,CACd,EAAE;AACL;AAEA,MAAMK,IAAYC,EAAiD;AAAA,EACjE,MAAM;AAAA,EACN,YAAY;AAAA,IACV,OAAO,EAAE,MAAM,UAAU,aAAa,mDAAA;AAAA,IACtC,WAAW,EAAE,MAAM,UAAU,aAAa,sCAAA;AAAA,EAAsC;AAAA,EAElF,UAAU,CAAC,SAAS,WAAW;AAAA,EAC/B,sBAAsB;AACxB,CAAC,GAEKC,IAAa;AAMnB,gBAAuBC,EACrBb,GACAH,GACA,EAAE,OAAAI,GAAO,UAAAa,GAAU,QAAAT,GAAQ,OAAAU,GAAO,MAAAC,KAQT;AACzB,QAAMC,IAAQD,IACV,kBAAkBF,EAAS,SAASA,EAAS,KAAK,IAAI,IAAI,QAAQ;AAAA,2CAClE,kBAAkBb,KAAS,SAAS;AAAA,oCAAuCA,IAAQ,wBAAwB,EAAE,KAC3GiB,IAAST,EAAW;AAAA,IACxB,OAAAT;AAAA,IACA,QAAQY;AAAA,IACR,QAAQ,GAAGhB,EAAMC,CAAK,CAAC;AAAA,EAAKoB,CAAK;AAAA,OAAUF,CAAK;AAAA,IAChD,QAAQI,EAAO,MAAM,EAAE,SAAST,GAAW;AAAA,IAC3C,aAAaL;AAAA,EAAA,CACd;AACD,mBAAiBe,KAAQF,EAAO;AAC9B,UAAMF,IACF,EAAE,MAAMI,EAAK,OAAO,WAAWA,EAAK,cACpC,EAAE,MAAMA,EAAK,OAAO,WAAWA,EAAK,WAAW,OAAO,CAAC,GAAGnB,EAAM,MAAM,EAAA;AAE9E;"}
+{"version":3,"file":"proposals.js","sources":["../src/proposals.ts"],"sourcesContent":["// What a field asks the model, written once. A host names the model and, at most, a sentence of\n// instructions; the field describes itself through its accessible name and description, which is\n// what a person filling it in reads too.\n\nimport { type LanguageModel, Output, jsonSchema, streamText } from \"@kanzo-tech/llm\";\nimport type { ContinuationRequest, Proposal } from \"./engine.js\";\n\n/** What the model is told about the field it is filling. */\nexport interface FieldBrief {\n  /** The accessible name — the label a person reads. */\n  name: string;\n  /** The accessible description — the helper text under it. */\n  description?: string;\n  /** The host's own instruction for this field (`<Assist instructions>`). */\n  instructions?: string;\n  /** What the rest of the form says (`<AssistProvider context>`). */\n  context?: string;\n}\n\nconst brief = (field: FieldBrief) =>\n  [\n    `Field: ${field.name || \"(unnamed)\"}`,\n    field.description && `Field description: ${field.description}`,\n    field.instructions && `Instructions: ${field.instructions}`,\n    field.context && `Form context:\\n${field.context}`,\n  ]\n    .filter(Boolean)\n    .join(\"\\n\");\n\nconst CONTINUE = `You complete text inside a form field, like an editor's inline completion.\nReply with ONLY the text to insert at <caret/>: no quotes, no commentary, never repeat text that is already there.\nKeep the language, tone and format of the existing text. Stop at a natural point: the end of the sentence for an automatic suggestion; up to a short paragraph when explicitly asked.`;\n\n/**\n * The AI SDK reports a failed stream to `onError` and then ends the stream as if it had finished, so\n * a refused or broken call would read as a model with nothing to say. This keeps what was reported\n * and throws it, whole, once the stream ends.\n */\nfunction failures() {\n  let failed: { error: unknown } | undefined;\n  return {\n    onError: ({ error }: { error: unknown }) => void (failed ??= { error }),\n    rethrow: () => {\n      if (failed) throw failed.error;\n    },\n  };\n}\n\n/** One continuation at the caret, streamed. */\nexport async function* continuation(\n  model: LanguageModel,\n  field: FieldBrief,\n  { value, position, trigger, avoid, signal }: ContinuationRequest,\n): AsyncIterable<string> {\n  const text = `${value.slice(0, position)}<caret/>${value.slice(position)}`;\n  const differ = avoid.length\n    ? `\\nOffer something different from these earlier suggestions:\\n${avoid.map((a) => `- ${a.trim()}`).join(\"\\n\")}`\n    : \"\";\n  const reported = failures();\n  yield* streamText({\n    model,\n    system: CONTINUE,\n    prompt: `${brief(field)}\\nRequest: ${trigger}${differ}\\n\\nText:\\n${text}`,\n    abortSignal: signal,\n    onError: reported.onError,\n  }).textStream;\n  reported.rethrow();\n}\n\nconst CANDIDATE = jsonSchema<{ value: string; rationale: string }>({\n  type: \"object\",\n  properties: {\n    value: { type: \"string\", description: \"The whole value, exactly as it would be entered.\" },\n    rationale: { type: \"string\", description: \"Why it fits, in one short sentence.\" },\n  },\n  required: [\"value\", \"rationale\"],\n  additionalProperties: false,\n});\n\nconst CANDIDATES = `You suggest values for a form field. Each value must be complete and ready to enter as-is, in the language of the form.`;\n\n/**\n * Whole values for the field, each arriving as soon as it is complete (`elementStream`), so the\n * first candidate is on screen while the model writes the rest.\n */\nexport async function* candidates(\n  model: LanguageModel,\n  field: FieldBrief,\n  { value, existing, signal, count, list }: {\n    value: string;\n    existing: string[];\n    signal: AbortSignal;\n    count: number;\n    /** The field holds a list (tags): a candidate is one more item, not a replacement. */\n    list: boolean;\n  },\n): AsyncIterable<Proposal> {\n  const holds = list\n    ? `Current items: ${existing.length ? existing.join(\", \") : \"(none)\"}\\nSuggest NEW items, not already present.`\n    : `Current value: ${value || \"(empty)\"}\\nSuggest alternatives to replace it${value ? \", different from it\" : \"\"}.`;\n  const reported = failures();\n  const result = streamText({\n    model,\n    onError: reported.onError,\n    system: CANDIDATES,\n    prompt: `${brief(field)}\\n${holds}\\nGive ${count}.`,\n    output: Output.array({ element: CANDIDATE }),\n    abortSignal: signal,\n  });\n  for await (const item of result.elementStream) {\n    yield list\n      ? { text: item.value, rationale: item.rationale }\n      : { text: item.value, rationale: item.rationale, range: [0, value.length] };\n  }\n  reported.rethrow();\n}\n"],"names":["brief","field","CONTINUE","failures","failed","error","continuation","model","value","position","trigger","avoid","signal","text","differ","a","reported","streamText","CANDIDATE","jsonSchema","CANDIDATES","candidates","existing","count","list","holds","result","Output","item"],"mappings":";AAmBA,MAAMA,IAAQ,CAACC,MACb;AAAA,EACE,UAAUA,EAAM,QAAQ,WAAW;AAAA,EACnCA,EAAM,eAAe,sBAAsBA,EAAM,WAAW;AAAA,EAC5DA,EAAM,gBAAgB,iBAAiBA,EAAM,YAAY;AAAA,EACzDA,EAAM,WAAW;AAAA,EAAkBA,EAAM,OAAO;AAClD,EACG,OAAO,OAAO,EACd,KAAK;AAAA,CAAI,GAERC,IAAW;AAAA;AAAA;AASjB,SAASC,IAAW;AAClB,MAAIC;AACJ,SAAO;AAAA,IACL,SAAS,CAAC,EAAE,OAAAC,EAAA,MAAgC,MAAMD,UAAW,EAAE,OAAAC;IAC/D,SAAS,MAAM;AACb,UAAID,SAAcA,EAAO;AAAA,IAC3B;AAAA,EAAA;AAEJ;AAGA,gBAAuBE,EACrBC,GACAN,GACA,EAAE,OAAAO,GAAO,UAAAC,GAAU,SAAAC,GAAS,OAAAC,GAAO,QAAAC,KACZ;AACvB,QAAMC,IAAO,GAAGL,EAAM,MAAM,GAAGC,CAAQ,CAAC,WAAWD,EAAM,MAAMC,CAAQ,CAAC,IAClEK,IAASH,EAAM,SACjB;AAAA;AAAA,EAAgEA,EAAM,IAAI,CAACI,MAAM,KAAKA,EAAE,KAAA,CAAM,EAAE,EAAE,KAAK;AAAA,CAAI,CAAC,KAC5G,IACEC,IAAWb,EAAA;AACjB,SAAOc,EAAW;AAAA,IAChB,OAAAV;AAAA,IACA,QAAQL;AAAA,IACR,QAAQ,GAAGF,EAAMC,CAAK,CAAC;AAAA,WAAcS,CAAO,GAAGI,CAAM;AAAA;AAAA;AAAA,EAAcD,CAAI;AAAA,IACvE,aAAaD;AAAA,IACb,SAASI,EAAS;AAAA,EAAA,CACnB,EAAE,YACHA,EAAS,QAAA;AACX;AAEA,MAAME,IAAYC,EAAiD;AAAA,EACjE,MAAM;AAAA,EACN,YAAY;AAAA,IACV,OAAO,EAAE,MAAM,UAAU,aAAa,mDAAA;AAAA,IACtC,WAAW,EAAE,MAAM,UAAU,aAAa,sCAAA;AAAA,EAAsC;AAAA,EAElF,UAAU,CAAC,SAAS,WAAW;AAAA,EAC/B,sBAAsB;AACxB,CAAC,GAEKC,IAAa;AAMnB,gBAAuBC,EACrBd,GACAN,GACA,EAAE,OAAAO,GAAO,UAAAc,GAAU,QAAAV,GAAQ,OAAAW,GAAO,MAAAC,KAQT;AACzB,QAAMC,IAAQD,IACV,kBAAkBF,EAAS,SAASA,EAAS,KAAK,IAAI,IAAI,QAAQ;AAAA,2CAClE,kBAAkBd,KAAS,SAAS;AAAA,oCAAuCA,IAAQ,wBAAwB,EAAE,KAC3GQ,IAAWb,EAAA,GACXuB,IAAST,EAAW;AAAA,IACxB,OAAAV;AAAA,IACA,SAASS,EAAS;AAAA,IAClB,QAAQI;AAAA,IACR,QAAQ,GAAGpB,EAAMC,CAAK,CAAC;AAAA,EAAKwB,CAAK;AAAA,OAAUF,CAAK;AAAA,IAChD,QAAQI,EAAO,MAAM,EAAE,SAAST,GAAW;AAAA,IAC3C,aAAaN;AAAA,EAAA,CACd;AACD,mBAAiBgB,KAAQF,EAAO;AAC9B,UAAMF,IACF,EAAE,MAAMI,EAAK,OAAO,WAAWA,EAAK,cACpC,EAAE,MAAMA,EAAK,OAAO,WAAWA,EAAK,WAAW,OAAO,CAAC,GAAGpB,EAAM,MAAM,EAAA;AAE5E,EAAAQ,EAAS,QAAA;AACX;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kanzo-tech/ai",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Kanzo AI surfaces — a field the model helps fill (Assist) and a conversation with one (Chat), over the AI SDK through @kanzo-tech/llm. Sibling of @kanzo-tech/ui, not part of it.",
   "type": "module",
   "license": "MIT",
@@ -30,12 +30,12 @@
     "lucide-react": ">=1",
     "react": ">=19",
     "react-dom": ">=19",
-    "@kanzo-tech/ui": "0.18.0"
+    "@kanzo-tech/ui": "0.20.0"
   },
   "dependencies": {
     "streamdown": "^2.5.0",
     "tailwind-variants": "^3.2.2",
-    "@kanzo-tech/llm": "0.18.0"
+    "@kanzo-tech/llm": "0.20.0"
   },
   "devDependencies": {
     "@ai-sdk/react": "^4.0.129",
@@ -51,8 +51,8 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "rollup-plugin-preserve-directives": "^0.4.0",
-    "@kanzo-tech/theme": "0.18.0",
-    "@kanzo-tech/ui": "0.18.0"
+    "@kanzo-tech/theme": "0.20.0",
+    "@kanzo-tech/ui": "0.20.0"
   },
   "//size-limit": "The root barrel, measured without the peers and dependencies a host already has. Assist and Chat tree-shake apart: a host that only assists fields does not ship the transcript, and the markdown parser comes with Chat alone.",
   "size-limit": [