@kanzo-tech/ai 0.1.0

package/dist/use-ai.d.ts

@@ -0,0 +1,170 @@
+import { Candidate } from './types.js';
+/**
+ * The continuation is meant to be appended verbatim. Two safety nets, and no character-level
+ * surgery — that mangled coincidental overlaps and was removed.
+ *
+ * 1. **The finished echo.** A model that restated the whole value before continuing gets that one
+ *    unambiguous prefix dropped.
+ * 2. **The echo still arriving**, which is the one you can see. `cleanGhost` runs on the
+ *    *accumulated* text once a frame, so while an echo is streaming in, `cont` is a strict prefix
+ *    of the value and rule 1 cannot fire yet — the field painted the sentence it already contained,
+ *    a second time, until the echo completed. Measured live on the Complete page: a value of
+ *    `Three hounds seen at the ford, in threes as they go` with a ghost reading `Three hou`.
+ *
+ *    So an unresolved echo renders as nothing. What it costs is a genuine continuation that happens
+ *    to begin with the value's own opening characters — hidden for the few frames until it diverges,
+ *    which is invisible next to painting the value twice.
+ */
+export declare function cleanGhost(base: string, cont: string): string;
+/**
+ * Where a request has got to. **One union for the engine and both hooks**, because a status plus a
+ * boolean is two spellings of one fact and they drift: this file carried three vocabularies at
+ * once, and the pair `status` + `loading` could not tell *never asked* from *asked, here they are*.
+ *
+ * `ready` means a run finished — with something or with nothing. An empty `ready` is the honest
+ * answer "the source had nothing", which a surface should say rather than sit blank.
+ */
+export type AiStatus = "idle" | "loading" | "ready" | "error";
+export interface AiStream<T> {
+    /**
+     * Open `source` and pull it to the end, handing every value to `each`. Return `false` from `each`
+     * to stop early — a budget, a match, whatever the consumer's rule is.
+     *
+     * **The engine owns the loop**, and that is the point of this shape. When it was `start` +
+     * `next` + `idle` every consumer wrote the same twenty lines and the same abort-race protocol —
+     * capture the signal, pull, check it twice — four times over, because `next()` read the *current*
+     * iterator and a superseded loop could otherwise steal a chunk from the run that replaced it.
+     * Here the controller is a local of this closure, so a superseded run cannot see the new one.
+     *
+     * Supersedes anything in flight. Resolves to what happened to **this** run: `ready`, `error`, or
+     * `idle` if it was cancelled or superseded. That return is why there is no `peek()`: a loop that
+     * outlives the render that started it used to read `error` from a stale closure — the value from
+     * before the failure — so it needed a second way in.
+     */
+    run: (source: (signal: AbortSignal) => AsyncIterable<T>, each: (value: T) => boolean | void) => Promise<AiStatus>;
+    /** Abort anything in flight and go back to idle, clearing any error. */
+    cancel: () => void;
+    /** Forget a finished answer. A live stream is untouched — there is nothing to forget yet. */
+    reset: () => void;
+    status: AiStatus;
+    error: string | null;
+}
+/** The shared engine: one iterator, one controller, one status. */
+export declare function useAiStream<T>(errorText?: string): AiStream<T>;
+/** Below this there is not enough text to continue, so no request is made. `Complete` reads it to
+ *  keep its ✨ from being a button that does nothing. */
+export declare const MIN_COMPLETE_LENGTH = 4;
+/**
+ * Why a request is being made. LSP 3.18's `InlineCompletionTriggerKind` minus the `Kind`, and it
+ * exists for the reason the spec has it: a source may reasonably answer an explicit ask with
+ * something longer and dearer than it answers a keystroke.
+ */
+export type InlineCompletionTrigger = "invoked" | "automatic";
+/**
+ * What the source is asked.
+ *
+ * **`position`, not just `value`.** A completion is offered *at the caret* — it was an append at
+ * the end of the value, which is why the ghost used to vanish the moment the caret was not there.
+ * LSP calls this a `range` and prefers a replacement over an insertion; ours is the degenerate
+ * range, an insertion point, because our fields hold prose and not code.
+ */
+export interface InlineCompletionRequest {
+    /** The whole field value. A source that only wants what comes before the caret slices it. */
+    value: string;
+    /** Where the continuation goes. */
+    position: number;
+    trigger: InlineCompletionTrigger;
+    signal?: AbortSignal;
+}
+export interface UseInlineCompletionOptions {
+    /** Streaming inline completion — yields continuation chunks; honour the `AbortSignal`. */
+    complete: (request: InlineCompletionRequest) => AsyncIterable<string>;
+    debounceMs?: number;
+    minLength?: number;
+}
+export interface InlineCompletion {
+    /**
+     * What is left to insert **at the caret**, empty when there is nothing.
+     *
+     * There is no `hasGhost`, for the reason `useSuggestions` returns `items` and no `hasItems`: a
+     * derived boolean beside the thing it is derived from is a second spelling of one fact.
+     */
+    ghost: string;
+    /** `ready` with an empty `ghost` is "asked, and the model had nothing to add". */
+    status: AiStatus;
+    error: string | null;
+    /**
+     * The field changed. Ask after a debounce — **unless the offer already on the table survives**,
+     * which is the whole reason this takes a caret.
+     */
+    setValue: (value: string, position?: number) => void;
+    /** Ask now, as `"invoked"` — the ✨ path. */
+    ask: (value: string, position?: number) => void;
+    /**
+     * Forget the offer, and stop anything in flight.
+     *
+     * **There is no `accept` and no `clear`.** `clear` was a second name bound to this same function.
+     * And `accept` returned the ghost for the caller to insert and then did exactly this — but the
+     * caller already holds `ghost` and already owns the value, so the return was unread by the only
+     * consumer there has ever been. **The hook offers; the caller accepts.**
+     */
+    dismiss: () => void;
+}
+/**
+ * Ghost-text completion that does NOT own the input value — the caller's field owns the text and
+ * performs the insertion; this only offers a continuation and forgets it on `dismiss`.
+ *
+ * ## The offer survives typing that agrees with it
+ *
+ * This is the difference a reader feels, and it is one rule: an offer made at `from` stays on the
+ * table while what has been typed since is a prefix of it, and the ghost is simply what is left.
+ * Type the word the model was going to write and the ghost shortens; **no request is made at all.**
+ *
+ * It threw the whole offer away on every keystroke and started a fresh debounce, so the fastest a
+ * suggestion could reappear was 350 ms plus a model. Smart Compose's budget is 60 ms at p90, and
+ * you cannot get there by asking again — you get there by not asking. LSP 3.18 spells the same rule
+ * `filterText` ("an inline completion is shown if the text to replace is a prefix of the filter
+ * text") and Monaco spells it `inlineSuggest.mode: "prefix"`.
+ */
+export declare function useInlineCompletion(options: UseInlineCompletionOptions): InlineCompletion;
+export interface UseSuggestionsOptions {
+    suggest: (signal?: AbortSignal) => AsyncIterable<Candidate>;
+    /** Current values — a candidate equal to one of these (case-insensitively) never appears. */
+    existing?: string[];
+    /**
+     * How many to take from the stream. A strip wraps, so this is a budget rather than a window:
+     * nothing refills when one is dismissed.
+     *
+     * @default 6
+     */
+    limit?: number;
+}
+export interface SuggestionsController {
+    items: Candidate[];
+    /** `ready` with no items means the source had nothing — not that its answer was consumed. */
+    status: AiStatus;
+    error: string | null;
+    /** Ask the source. A no-op unless idle: in flight, already answered, or failed, it does nothing
+     *  and `refresh` is the way through. */
+    ask: () => void;
+    /** Ask again from scratch, discarding what is shown. Also the retry after an error. */
+    refresh: () => void;
+    /** Abort in flight, and forget. */
+    cancel: () => void;
+    /**
+     * Drop one candidate, **by value**.
+     *
+     * By value and not by index: an index-addressed list forces every caller to keep a parallel
+     * lookup, and it is wrong the moment anything else mutates the array.
+     */
+    dismiss: (value: string) => void;
+}
+/**
+ * A streamed list of candidate values, deduped against what the field already holds.
+ *
+ * The engine is shared with `useInlineCompletion`; what is here is the part specific to a list:
+ * dedup, a budget, and the rule for when asking again is free. **No windowing and no refill loop**
+ * — those existed to keep exactly three rows alive inside a popover, and the popover is gone.
+ */
+export declare function useSuggestions(options: UseSuggestionsOptions): SuggestionsController;
+//# sourceMappingURL=use-ai.d.ts.map

package/dist/use-ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai.d.ts","sourceRoot":"","sources":["../src/use-ai.ts"],"names":[],"mappings":"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"}

package/dist/use-ai.js

@@ -0,0 +1,186 @@
+"use client";
+import { useState as W, useRef as C, useCallback as l, useEffect as R, useMemo as A } from "react";
+function N(r, e) {
+  const u = r.trimEnd();
+  if (!u || !e) return e;
+  const s = { base: u.toLowerCase(), cont: e.toLowerCase() };
+  return s.cont.startsWith(s.base) ? e.slice(u.length) : s.base.startsWith(s.cont) ? "" : e;
+}
+const G = (r, e) => r instanceof Error && r.message ? r.message : e;
+function q(r = "Something went wrong") {
+  const [e, u] = W("idle"), [s, g] = W(null), E = C("idle"), h = C(void 0), k = C(r);
+  k.current = r;
+  const n = l((i, o = null) => {
+    E.current = i, u(i), g(o);
+  }, []);
+  R(() => () => {
+    var i;
+    return (i = h.current) == null ? void 0 : i.abort();
+  }, []);
+  const v = l(
+    (i, o) => {
+      var d;
+      (d = h.current) == null || d.abort();
+      const a = new AbortController();
+      return h.current = a, n("loading"), (async () => {
+        let x;
+        try {
+          x = i(a.signal)[Symbol.asyncIterator]();
+        } catch (m) {
+          return n("error", G(m, k.current)), "error";
+        }
+        for (; ; ) {
+          let m;
+          try {
+            m = await x.next();
+          } catch (p) {
+            return a.signal.aborted ? "idle" : (n("error", G(p, k.current)), "error");
+          }
+          if (a.signal.aborted) return "idle";
+          if (m.done) break;
+          if (o(m.value) === !1) {
+            a.abort();
+            break;
+          }
+        }
+        return n("ready"), "ready";
+      })();
+    },
+    [n]
+  ), f = l(() => {
+    var i;
+    (i = h.current) == null || i.abort(), n("idle");
+  }, [n]), b = l(() => {
+    E.current !== "loading" && n("idle");
+  }, [n]);
+  return A(
+    () => ({ run: v, cancel: f, reset: b, status: e, error: s }),
+    [f, s, b, v, e]
+  );
+}
+function _(r) {
+  let e, u = !1;
+  const s = () => {
+    u = !0, e === void 0 && (e = requestAnimationFrame(() => {
+      e = void 0, u = !1, r();
+    }));
+  };
+  return s.flush = () => {
+    const g = u;
+    s.cancel(), g && r();
+  }, s.cancel = () => {
+    e !== void 0 && cancelAnimationFrame(e), e = void 0, u = !1;
+  }, s;
+}
+const B = 4;
+function O(r) {
+  const { run: e, cancel: u, status: s, error: g } = q("Couldn’t complete"), [E, h] = W(""), k = C(r);
+  k.current = r;
+  const n = C(null), v = C({ value: "", position: 0 }), f = C(void 0), b = l(() => {
+    const t = n.current;
+    if (!t) return "";
+    const { value: c, position: y } = v.current;
+    if (y < t.from) return "";
+    const w = c.slice(t.from, y);
+    return t.text.startsWith(w) ? t.text.slice(w.length) : "";
+  }, []), i = l(() => {
+    const t = n.current;
+    if (!t) return !1;
+    const { value: c, position: y } = v.current;
+    if (y < t.from) return !1;
+    const w = c.slice(t.from, y);
+    return t.text.startsWith(w) || !t.done && w.startsWith(t.text);
+  }, []), o = C(void 0);
+  o.current ?? (o.current = _(() => h(b())));
+  const a = l(() => {
+    var t;
+    clearTimeout(f.current), (t = o.current) == null || t.cancel(), n.current = null, u(), h("");
+  }, [u]), d = l(
+    (t, c, y) => {
+      const w = { from: c, text: "", done: !1 };
+      n.current = w;
+      const F = t.slice(0, c);
+      let I = "";
+      e(
+        (S) => k.current.complete({ value: t, position: c, trigger: y, signal: S }),
+        (S) => {
+          var L;
+          if (n.current !== w) return !1;
+          I += S, w.text = N(F, I), (L = o.current) == null || L.call(o);
+        }
+      ).then((S) => {
+        var L, M;
+        n.current === w && (w.done = !0, S === "ready" ? (L = o.current) == null || L.flush() : (M = o.current) == null || M.cancel());
+      });
+    },
+    [e]
+  ), x = (t) => t.trim().length < (k.current.minLength ?? B), m = l(
+    (t, c = t.length) => {
+      if (v.current = { value: t, position: c }, i()) {
+        h(b());
+        return;
+      }
+      a(), !x(t) && (f.current = setTimeout(
+        () => d(t, c, "automatic"),
+        k.current.debounceMs ?? 350
+      ));
+    },
+    [i, a, b, d]
+  ), p = l(
+    (t, c = t.length) => {
+      v.current = { value: t, position: c }, a(), !x(t) && d(t, c, "invoked");
+    },
+    [a, d]
+  );
+  return R(
+    () => () => {
+      var t;
+      clearTimeout(f.current), (t = o.current) == null || t.cancel();
+    },
+    []
+  ), A(
+    () => ({ ghost: E, status: s, error: g, setValue: m, ask: p, dismiss: a }),
+    [p, a, g, E, m, s]
+  );
+}
+const T = (r) => r.trim().toLowerCase();
+function P(r) {
+  const { run: e, cancel: u, reset: s, status: g, error: E } = q(
+    "Couldn’t load suggestions"
+  ), [h, k] = W([]), n = C([]), v = C(r);
+  v.current = r;
+  const f = l((d) => {
+    n.current = d, k(d);
+  }, []), b = l(() => {
+    const { existing: d = [], limit: x = 6, suggest: m } = v.current, p = new Set(d.map(T).filter(Boolean)), t = [];
+    f([]), e(
+      (c) => m(c),
+      (c) => {
+        const y = T(c.value);
+        return !y || p.has(y) ? !0 : (p.add(y), t.push(c), f([...t]), t.length < x);
+      }
+    );
+  }, [f, e]), i = l(() => {
+    g === "idle" && b();
+  }, [b, g]), o = l(() => {
+    u(), f([]);
+  }, [u, f]), a = l(
+    (d) => {
+      const x = T(d), m = n.current.filter((p) => T(p.value) !== x);
+      f(m), m.length === 0 && s();
+    },
+    [f, s]
+  );
+  return A(
+    () => ({ items: h, status: g, error: E, ask: i, refresh: b, cancel: o, dismiss: a }),
+    [i, o, a, E, h, b, g]
+  );
+}
+export {
+  B as MIN_COMPLETE_LENGTH,
+  N as cleanGhost,
+  q as useAiStream,
+  O as useInlineCompletion,
+  P as useSuggestions
+};
+//# sourceMappingURL=use-ai.js.map

package/dist/use-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-ai.js","sources":["../src/use-ai.ts"],"sourcesContent":["\"use client\";\n\n// Headless AI-assist engine — the streaming machinery behind inline ghost completion (`Complete`,\n// via `useInlineCompletion`) and a candidate strip (`Suggest`, via `useSuggestions`). Domain-free\n// and source-agnostic: a consumer passes a function returning an async iterable and cancels it\n// with an `AbortSignal`. It imports nothing of `@codemirror/*` — `CodeEditor` has no completion\n// prop and never had one, and this package must not grow one, because `ui/editor` importing from\n// here would make `ui` depend on `ai` and `ai` already depends on `ui`.\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport type { Candidate } from \"./types.js\";\n\n/**\n * The continuation is meant to be appended verbatim. Two safety nets, and no character-level\n * surgery — that mangled coincidental overlaps and was removed.\n *\n * 1. **The finished echo.** A model that restated the whole value before continuing gets that one\n *    unambiguous prefix dropped.\n * 2. **The echo still arriving**, which is the one you can see. `cleanGhost` runs on the\n *    *accumulated* text once a frame, so while an echo is streaming in, `cont` is a strict prefix\n *    of the value and rule 1 cannot fire yet — the field painted the sentence it already contained,\n *    a second time, until the echo completed. Measured live on the Complete page: a value of\n *    `Three hounds seen at the ford, in threes as they go` with a ghost reading `Three hou`.\n *\n *    So an unresolved echo renders as nothing. What it costs is a genuine continuation that happens\n *    to begin with the value's own opening characters — hidden for the few frames until it diverges,\n *    which is invisible next to painting the value twice.\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\nconst message = (e: unknown, fallback: string) =>\n  e instanceof Error && e.message ? e.message : fallback;\n\n/**\n * Where a request has got to. **One union for the engine and both hooks**, because a status plus a\n * boolean is two spellings of one fact and they drift: this file carried three vocabularies at\n * once, and the pair `status` + `loading` could not tell *never asked* from *asked, here they are*.\n *\n * `ready` means a run finished — with something or with nothing. An empty `ready` is the honest\n * answer \"the source had nothing\", which a surface should say rather than sit blank.\n */\nexport type AiStatus = \"idle\" | \"loading\" | \"ready\" | \"error\";\n\nexport interface AiStream<T> {\n  /**\n   * Open `source` and pull it to the end, handing every value to `each`. Return `false` from `each`\n   * to stop early — a budget, a match, whatever the consumer's rule is.\n   *\n   * **The engine owns the loop**, and that is the point of this shape. When it was `start` +\n   * `next` + `idle` every consumer wrote the same twenty lines and the same abort-race protocol —\n   * capture the signal, pull, check it twice — four times over, because `next()` read the *current*\n   * iterator and a superseded loop could otherwise steal a chunk from the run that replaced it.\n   * Here the controller is a local of this closure, so a superseded run cannot see the new one.\n   *\n   * Supersedes anything in flight. Resolves to what happened to **this** run: `ready`, `error`, or\n   * `idle` if it was cancelled or superseded. That return is why there is no `peek()`: a loop that\n   * outlives the render that started it used to read `error` from a stale closure — the value from\n   * before the failure — so it needed a second way in.\n   */\n  run: (\n    source: (signal: AbortSignal) => AsyncIterable<T>,\n    each: (value: T) => boolean | void,\n  ) => Promise<AiStatus>;\n  /** Abort anything in flight and go back to idle, clearing any error. */\n  cancel: () => void;\n  /** Forget a finished answer. A live stream is untouched — there is nothing to forget yet. */\n  reset: () => void;\n  status: AiStatus;\n  error: string | null;\n}\n\n/** The shared engine: one iterator, one controller, one status. */\nexport function useAiStream<T>(errorText = \"Something went wrong\"): AiStream<T> {\n  const [status, setStatus] = useState<AiStatus>(\"idle\");\n  const [error, setError] = useState<string | null>(null);\n\n  // Beside the state, and read only where a decision is synchronous (`reset`). Anything a surface\n  // renders has to be state: this was a ref first, and the strip stayed on whatever status it\n  // happened to paint with.\n  const statusRef = useRef<AiStatus>(\"idle\");\n  const ctrl = useRef<AbortController>(undefined);\n  const errRef = useRef(errorText);\n  errRef.current = errorText;\n\n  const set = useCallback((s: AiStatus, 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<AiStatus> => {\n        let it: AsyncIterator<T>;\n        try {\n          it = src(c.signal)[Symbol.asyncIterator]();\n        } catch (e) {\n          set(\"error\", message(e, errRef.current));\n          return \"error\";\n        }\n        for (;;) {\n          let res: IteratorResult<T>;\n          try {\n            res = await it.next();\n          } catch (e) {\n            // A throw on the way out is not a failure to report — the caller asked for it.\n            if (c.signal.aborted) return \"idle\";\n            set(\"error\", message(e, errRef.current));\n            return \"error\";\n          }\n          if (c.signal.aborted) return \"idle\";\n          if (res.done) break;\n          if (each(res.value) === false) {\n            // Enough. The source is told, because it is the one holding the socket.\n            c.abort();\n            break;\n          }\n        }\n        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(\n    () => ({ run, cancel, reset, status, error }),\n    [cancel, error, reset, run, status],\n  );\n}\n\n// ── frame coalescing ─────────────────────────────────────────────────────────\n\ninterface Coalesced {\n  (): void;\n  flush: () => void;\n  cancel: () => void;\n}\n\n/**\n * Run `paint` at most once a frame, and once more on `flush()` so the last chunk is never the one\n * that got dropped. `requestAnimationFrame` rather than a millisecond interval because the thing\n * being matched is the display, and because a hidden tab stops firing it — which is the correct\n * behaviour for a paint nobody is looking at.\n *\n * It throttles a **call**, not a value. Carrying the pending value meant a superseded run could\n * flush a string the newer one had already replaced; a repaint that derives what to show from the\n * current offer cannot be stale, so there is nothing to guard.\n */\nfunction coalesce(paint: () => void): Coalesced {\n  let frame: number | undefined;\n  let queued = false;\n\n  const run: Coalesced = () => {\n    queued = true;\n    if (frame !== undefined) return;\n    frame = requestAnimationFrame(() => {\n      frame = undefined;\n      queued = false;\n      paint();\n    });\n  };\n\n  run.flush = () => {\n    const pending = queued;\n    run.cancel();\n    if (pending) paint();\n  };\n\n  run.cancel = () => {\n    if (frame !== undefined) cancelAnimationFrame(frame);\n    frame = undefined;\n    queued = false;\n  };\n\n  return run;\n}\n\n// ── useInlineCompletion — inline continuation (bring your own input) ─────────\n\n/** Below this there is not enough text to continue, so no request is made. `Complete` reads it to\n *  keep its ✨ from being a button that does nothing. */\nexport const MIN_COMPLETE_LENGTH = 4;\n\n/**\n * Why a request is being made. LSP 3.18's `InlineCompletionTriggerKind` minus the `Kind`, and it\n * exists for the reason the spec has it: a source may reasonably answer an explicit ask with\n * something longer and dearer than it answers a keystroke.\n */\nexport type InlineCompletionTrigger = \"invoked\" | \"automatic\";\n\n/**\n * What the source is asked.\n *\n * **`position`, not just `value`.** A completion is offered *at the caret* — it was an append at\n * the end of the value, which is why the ghost used to vanish the moment the caret was not there.\n * LSP calls this a `range` and prefers a replacement over an insertion; ours is the degenerate\n * range, an insertion point, because our fields hold prose and not code.\n */\nexport interface InlineCompletionRequest {\n  /** The whole field value. A source that only wants what comes before the caret slices it. */\n  value: string;\n  /** Where the continuation goes. */\n  position: number;\n  trigger: InlineCompletionTrigger;\n  signal?: AbortSignal;\n}\n\nexport interface UseInlineCompletionOptions {\n  /** Streaming inline completion — yields continuation chunks; honour the `AbortSignal`. */\n  complete: (request: InlineCompletionRequest) => AsyncIterable<string>;\n  debounceMs?: number;\n  minLength?: number;\n}\n\nexport interface InlineCompletion {\n  /**\n   * What is left to insert **at the caret**, empty when there is nothing.\n   *\n   * There is no `hasGhost`, for the reason `useSuggestions` returns `items` and no `hasItems`: a\n   * derived boolean beside the thing it is derived from is a second spelling of one fact.\n   */\n  ghost: string;\n  /** `ready` with an empty `ghost` is \"asked, and the model had nothing to add\". */\n  status: AiStatus;\n  error: string | null;\n  /**\n   * The field changed. Ask after a debounce — **unless the offer already on the table survives**,\n   * which is the whole reason this takes a caret.\n   */\n  setValue: (value: string, position?: number) => void;\n  /** Ask now, as `\"invoked\"` — the ✨ path. */\n  ask: (value: string, position?: number) => void;\n  /**\n   * Forget the offer, and stop anything in flight.\n   *\n   * **There is no `accept` and no `clear`.** `clear` was a second name bound to this same function.\n   * And `accept` returned the ghost for the caller to insert and then did exactly this — but the\n   * caller already holds `ghost` and already owns the value, so the return was unread by the only\n   * consumer there has ever been. **The hook offers; the caller accepts.**\n   */\n  dismiss: () => void;\n}\n\n/** An offer on the table: a continuation, and the point in the value it was made at. */\ninterface Offer {\n  from: number;\n  /** Everything received so far, with the echo rule already applied. */\n  text: string;\n  /** The stream ended, so a `typed` longer than `text` is a mismatch rather than a wait. */\n  done: boolean;\n}\n\n/**\n * Ghost-text completion that does NOT own the input value — the caller's field owns the text and\n * performs the insertion; this only offers a continuation and forgets it on `dismiss`.\n *\n * ## The offer survives typing that agrees with it\n *\n * This is the difference a reader feels, and it is one rule: an offer made at `from` stays on the\n * table while what has been typed since is a prefix of it, and the ghost is simply what is left.\n * Type the word the model was going to write and the ghost shortens; **no request is made at all.**\n *\n * It threw the whole offer away on every keystroke and started a fresh debounce, so the fastest a\n * suggestion could reappear was 350 ms plus a model. Smart Compose's budget is 60 ms at p90, and\n * you cannot get there by asking again — you get there by not asking. LSP 3.18 spells the same rule\n * `filterText` (\"an inline completion is shown if the text to replace is a prefix of the filter\n * text\") and Monaco spells it `inlineSuggest.mode: \"prefix\"`.\n */\nexport function useInlineCompletion(options: UseInlineCompletionOptions): InlineCompletion {\n  const { run, cancel, status, error } = useAiStream<string>(\"Couldn’t complete\");\n  const [ghost, setGhost] = useState(\"\");\n\n  const opts = useRef(options);\n  opts.current = options;\n\n  const offer = useRef<Offer | null>(null);\n  /** The field as of the last thing the caller told us. `rendered` is a function of this. */\n  const field = useRef({ value: \"\", position: 0 });\n  const askTimer = useRef<ReturnType<typeof setTimeout>>(undefined);\n\n  /** What is on offer at the caret right now — \"\" when nothing is, which is not the same as dead. */\n  const rendered = useCallback((): string => {\n    const o = offer.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  /** Is the offer still about the text in the field? */\n  const alive = useCallback((): boolean => {\n    const o = offer.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    // A `typed` longer than what has arrived is only a mismatch once the stream has ended: mid-flight\n    // it is the reader typing ahead of the model, and the next chunk may well agree with them.\n    return o.text.startsWith(typed) || (!o.done && typed.startsWith(o.text));\n  }, []);\n\n  const painter = useRef<Coalesced>(undefined);\n  painter.current ??= coalesce(() => setGhost(rendered()));\n\n  const drop = useCallback(() => {\n    clearTimeout(askTimer.current);\n    painter.current?.cancel();\n    offer.current = null;\n    cancel();\n    setGhost(\"\");\n  }, [cancel]);\n\n  // The write is coalesced to a frame rather than done per chunk: a token stream arrives faster than\n  // the display refreshes, so a `setState` per chunk renders work nobody sees. keasy's Ask panel hit\n  // this and grew its own `rafPending` guard around the same loop.\n  const start = useCallback(\n    (value: string, position: number, trigger: InlineCompletionTrigger) => {\n      const mine: Offer = { from: position, text: \"\", done: false };\n      offer.current = mine;\n      const base = value.slice(0, position);\n      let raw = \"\";\n      void run(\n        (signal) => opts.current.complete({ value, position, trigger, signal }),\n        (chunk) => {\n          // Superseded or dismissed: stop pulling rather than write into somebody else's offer.\n          if (offer.current !== mine) return false;\n          raw += chunk;\n          mine.text = cleanGhost(base, raw);\n          painter.current?.();\n        },\n      ).then((outcome) => {\n        if (offer.current !== mine) return;\n        mine.done = true;\n        if (outcome === \"ready\") painter.current?.flush();\n        else painter.current?.cancel();\n      });\n    },\n    [run],\n  );\n\n  const short = (value: string) =>\n    value.trim().length < (opts.current.minLength ?? MIN_COMPLETE_LENGTH);\n\n  const setValue = useCallback(\n    (value: string, position = value.length) => {\n      field.current = { value, position };\n      if (alive()) {\n        // The offer covers this keystroke. Repaint and ask nothing — this is the whole feature.\n        setGhost(rendered());\n        return;\n      }\n      drop();\n      if (short(value)) return;\n      askTimer.current = setTimeout(\n        () => start(value, position, \"automatic\"),\n        opts.current.debounceMs ?? 350,\n      );\n    },\n    [alive, drop, rendered, start],\n  );\n\n  const ask = useCallback(\n    (value: string, position = value.length) => {\n      field.current = { value, position };\n      drop();\n      if (short(value)) return;\n      start(value, position, \"invoked\");\n    },\n    [drop, start],\n  );\n\n  useEffect(\n    () => () => {\n      clearTimeout(askTimer.current);\n      painter.current?.cancel();\n    },\n    [],\n  );\n\n  return useMemo(\n    () => ({ ghost, status, error, setValue, ask, dismiss: drop }),\n    [ask, drop, error, ghost, setValue, status],\n  );\n}\n\n// ── useSuggestions — a deduped candidate strip ───────────────────────────────\n\n/** Case-insensitive key for deduping suggestion values. */\nconst norm = (v: string) => v.trim().toLowerCase();\n\nexport interface UseSuggestionsOptions {\n  suggest: (signal?: AbortSignal) => AsyncIterable<Candidate>;\n  /** Current values — a candidate equal to one of these (case-insensitively) never appears. */\n  existing?: string[];\n  /**\n   * How many to take from the stream. A strip wraps, so this is a budget rather than a window:\n   * nothing refills when one is dismissed.\n   *\n   * @default 6\n   */\n  limit?: number;\n}\n\nexport interface SuggestionsController {\n  items: Candidate[];\n  /** `ready` with no items means the source had nothing — not that its answer was consumed. */\n  status: AiStatus;\n  error: string | null;\n  /** Ask the source. A no-op unless idle: in flight, already answered, or failed, it does nothing\n   *  and `refresh` is the way through. */\n  ask: () => void;\n  /** Ask again from scratch, discarding what is shown. Also the retry after an error. */\n  refresh: () => void;\n  /** Abort in flight, and forget. */\n  cancel: () => void;\n  /**\n   * Drop one candidate, **by value**.\n   *\n   * By value and not by index: an index-addressed list forces every caller to keep a parallel\n   * lookup, and it is wrong the moment anything else mutates the array.\n   */\n  dismiss: (value: string) => void;\n}\n\n/**\n * A streamed list of candidate values, deduped against what the field already holds.\n *\n * The engine is shared with `useInlineCompletion`; what is here is the part specific to a list:\n * dedup, a budget, and the rule for when asking again is free. **No windowing and no refill loop**\n * — those existed to keep exactly three rows alive inside a popover, and the popover is gone.\n */\nexport function useSuggestions(options: UseSuggestionsOptions): SuggestionsController {\n  const { run, cancel: abort, reset, status, error } = useAiStream<Candidate>(\n    \"Couldn’t load suggestions\",\n  );\n  const [items, setItems] = useState<Candidate[]>([]);\n  // A ref beside the state so `dismiss` can filter what is on screen *now* without taking `items`\n  // as a dependency — which would hand every consumer a new callback on every render.\n  const shown = useRef<Candidate[]>([]);\n\n  const opts = useRef(options);\n  opts.current = options;\n\n  const put = useCallback((next: Candidate[]) => {\n    shown.current = next;\n    setItems(next);\n  }, []);\n\n  const refresh = useCallback(() => {\n    const { existing = [], limit = 6, suggest } = opts.current;\n    const seen = new Set(existing.map(norm).filter(Boolean));\n    const taken: Candidate[] = [];\n    put([]);\n    void run(\n      (signal) => suggest(signal),\n      (item) => {\n        const key = norm(item.value);\n        if (!key || seen.has(key)) return true;\n        seen.add(key);\n        taken.push(item);\n        put([...taken]);\n        return taken.length < limit;\n      },\n    );\n  }, [put, run]);\n\n  // Gated on the status alone, and that one line replaced an `asked` ref that latched forever:\n  // take every candidate and the ✨ became a button that did nothing, because \"has been asked\" is\n  // not the question. The question is whether anything is in flight or on screen, and the status\n  // answers it — `dismiss` puts it back to idle when nothing is left of the answer.\n  const ask = useCallback(() => {\n    if (status !== \"idle\") return;\n    refresh();\n  }, [refresh, status]);\n\n  const cancel = useCallback(() => {\n    abort();\n    put([]);\n  }, [abort, put]);\n\n  const dismiss = useCallback(\n    (value: string) => {\n      const key = norm(value);\n      const next = shown.current.filter((item) => norm(item.value) !== key);\n      put(next);\n      // Nothing left of an answer is not the same as an answer with nothing in it. This is what\n      // keeps a strip from saying \"Nothing to suggest.\" at the reader who just took the last one.\n      if (next.length === 0) reset();\n    },\n    [put, reset],\n  );\n\n  return useMemo(\n    () => ({ items, status, error, ask, refresh, cancel, dismiss }),\n    [ask, cancel, dismiss, error, items, refresh, status],\n  );\n}\n"],"names":[],"mappings":";;AA4BO;AACL;AACA;AACA;AACA;AAGF;AAEA;AA0CO;AACL;AASA;AAEA;AACE;AAEU;AAGZ;;AAAsB;AAAc;AAEpC;AAAY;;AAER;AACA;AACA;AAIE;AACA;AACE;AAAuC;AAEvC;AACO;AAET;AACE;AACA;AACE;AAAe;AAGf;AAEO;AAET;AACA;AACA;AAEE;AACA;AAAA;AACF;AAEF;AACO;AACT;AACF;AACI;;AAIJ;AACU;AAIV;AAA+C;AAGjD;AAAO;AACgC;AACH;AAEtC;AAoBA;AACE;AAGA;AAEE;AAEE;AAEA;AACD;AAGH;AACE;AACA;AACa;AAIb;AAES;AAIb;AAMO;AAuFA;AACL;AAIA;AAEA;AAOE;AACA;AACA;AACA;AACA;AACA;AAA+D;AAK/D;AACA;AACA;AACA;AACA;AAGA;AAAsE;AAIxE;AAEA;;AACE;AAIW;AAMC;AAEV;AACA;AACA;AACA;AACA;AAAK;AACmE;;AAGpE;AACA;AAEA;AACF;;AAEA;AAGsB;AACvB;AACH;AACI;AAMW;AAGb;AAEE;AACA;AAAA;AAGF;AACmB;AACuB;AACb;AAAA;AAE/B;AAC6B;AAGnB;AAIR;AACgC;AAClC;AACY;AAGd;AAAA;;AAEI;AACiB;AACnB;AACA;AAGK;;AAEqC;AAE9C;AAKA;AA2CO;AACL;AAAqD;AACnD;AAQF;AAEA;AACE;AACa;AAIb;AAGA;AACK;AACuB;AAExB;AACA;AAIsB;AACxB;AAAA;AASF;AACA;AAIA;AACM;AAGQ;AAEZ;AAEA;AAGuB;AACzB;AACW;AAGb;AAAO;;AAE+C;AAExD;;;;;;;;"}

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@kanzo-tech/ai",
+  "version": "0.1.0",
+  "description": "Kanzo AI surfaces — the transcript, the composer, a model's reasoning and the calls it makes, plus the field affordances that stream into a value. Sibling of @kanzo-tech/ui, not part of it: a Message has a role and one of the roles is `assistant`, which is domain knowledge the generic vocabulary does not carry.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./markdown": {
+      "types": "./dist/markdown.d.ts",
+      "import": "./dist/markdown.js"
+    },
+    "./package.json": "./package.json",
+    "./styles.css": "./dist/styles.css"
+  },
+  "//peers": "Everything on the root barrel draws with @kanzo-tech/ui's parts and Ark's machines, so both are required peers rather than dependencies — two copies of Ark would mean two portals and two focus traps. streamdown is the one OPTIONAL peer, and it is why ./markdown exists: it measures 495 kB minified and 128 kB brotli on its own, against a 20 kB budget for the whole root barrel, so a host that renders plain text must not pay for a markdown parser. Same door as @kanzo-tech/ui/editor and @kanzo-tech/graph/duckdb.",
+  "peerDependencies": {
+    "@ark-ui/react": "^5.37.2",
+    "lucide-react": ">=1",
+    "react": ">=19",
+    "react-dom": ">=19",
+    "streamdown": ">=2",
+    "@kanzo-tech/ui": "0.1.0"
+  },
+  "dependencies": {
+    "tailwind-variants": "^3.2.2"
+  },
+  "devDependencies": {
+    "@ark-ui/react": "^5.37.2",
+    "@tailwindcss/cli": "4",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^29.1.1",
+    "lucide-react": "^1.23.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "rollup-plugin-preserve-directives": "^0.4.0",
+    "streamdown": "^2.5.0",
+    "tailwindcss": "4",
+    "@kanzo-tech/ui": "0.1.0",
+    "@kanzo-tech/theme": "0.1.0"
+  },
+  "//size-limit": "First measurement taken at the split, so this budget is a change detector from day one rather than a number inherited from somewhere. The four AI-assist modules that moved here cost @kanzo-tech/ui's root barrel about 4 kB when they arrived (38 -> 42 kB, recorded in that package's own note); the barrel is rebaselined down by the same move.",
+  "size-limit": [
+    {
+      "name": "root barrel (JS)",
+      "path": "dist/index.js",
+      "limit": "20 kB",
+      "ignore": [
+        "react",
+        "react-dom",
+        "react/jsx-runtime",
+        "@ark-ui/react",
+        "@kanzo-tech/ui",
+        "lucide-react",
+        "tailwind-variants"
+      ]
+    },
+    {
+      "name": "markdown subpath (JS)",
+      "path": "dist/markdown.js",
+      "limit": "3 kB",
+      "ignore": [
+        "react",
+        "react-dom",
+        "react/jsx-runtime",
+        "@ark-ui/react",
+        "@kanzo-tech/ui",
+        "lucide-react",
+        "tailwind-variants",
+        "streamdown"
+      ]
+    }
+  ],
+  "peerDependenciesMeta": {
+    "streamdown": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kanzo-Tech/ui.git",
+    "directory": "packages/ai"
+  },
+  "homepage": "https://kanzo-tech.github.io/ui",
+  "bugs": {
+    "url": "https://github.com/Kanzo-Tech/ui/issues"
+  },
+  "scripts": {
+    "build": "vite build && pnpm build:css",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "size": "size-limit",
+    "build:css": "tailwindcss -i src/styles.css -o dist/styles.css --minify"
+  }
+}