@kitn.ai/ui 0.25.2 → 0.27.0

package/src/primitives/toast-store.ts

@@ -9,6 +9,14 @@
 // element, so it carries its own shadow root + the shared kit stylesheet — it's
 // viewport-positioned AND fully kit-styled, never a raw div.
 //
+// ADOPTS, else creates: `ensureMounted` first
+// looks for a connected `<kai-toast-region>` already in the document and binds
+// the store to it, so an app that placed its own region and also calls
+// `toast()` gets ONE region, not two overlapping ones. It creates a region only
+// when none exists. With two or more candidate regions the choice is genuinely
+// ambiguous — the first in document order wins, and a one-time console.warn
+// says so (decide loudly).
+//
 // SSR-safe: every DOM touch is guarded by `typeof document`. On the server,
 // raising a toast is an inert no-op (the store updates, nothing mounts).
 
@@ -156,21 +164,75 @@ function resolveDuration(item: Pick<ToastItem, 'duration' | 'action'>): number {
 }
 
 /**
- * Lazily create the single `<kai-toast-region>` host on `document.body` and
- * bind the store to its `toasts` property. Idempotent + SSR-safe. The element
- * upgrade (its `defineWebComponent` registration) happens when the elements
- * bundle loads; setting the property before/after upgrade both work because
+ * Lazily resolve the single `<kai-toast-region>` host for a target and bind the
+ * store to its `toasts` property. Idempotent + SSR-safe. The element upgrade
+ * (its `defineWebComponent` registration) happens when the elements bundle
+ * loads; setting the property before/after upgrade both work because
  * `customElement` reflects late-set properties.
+ *
+ * ADOPT-IF-PRESENT: a connected
+ * `<kai-toast-region>` already in the document (same `target`, not already
+ * claimed for another target) is adopted — the store binds to IT, and no
+ * second region mounts. Adoption respects the region's authored attributes
+ * (position/stack/…): config from `configureToasts()` is not stamped onto an
+ * adopted region here, though an explicit `configureToasts()` call still
+ * updates every region, adopted included. Binding the store REPLACES a
+ * `toasts` array the app set as data — after the first `toast()` call the
+ * imperative store owns the adopted region's list. Only when no candidate
+ * exists is a fresh region created on `document.body`. Two or more candidates
+ * for the same target are genuinely ambiguous: the first in document order
+ * wins, with a one-time console.warn (decide loudly).
+ *
+ * If an adopted (or created) region later leaves the DOM, the cache entry is
+ * dropped and the next call resolves fresh — adopt again if a region exists,
+ * else create — so a removed region never becomes a dead cache entry that
+ * swallows toasts.
  */
 // One region per distinct target (the `null` key = the global / viewport region).
 // Every region binds the SAME store proxy and filters to its own target, so a
 // toast routes to the region for its `target`.
 const regions = new Map<HTMLElement | null, HTMLElement>();
 
+// Decide-loudly, once: ambiguity between 2+ candidate regions is warned about a
+// single time per page, not on every toast.
+let warnedAmbiguousRegions = false;
+
+/** Read a region element's `target` property (undefined pre-upgrade → null =
+ *  the global region). */
+function regionTarget(el: HTMLElement): HTMLElement | null {
+  return (el as unknown as { target?: HTMLElement }).target ?? null;
+}
+
 export function ensureMounted(target: HTMLElement | null = null): HTMLElement | undefined {
   if (typeof document === 'undefined') return undefined;
   const cached = regions.get(target);
   if (cached && cached.isConnected) return cached;
+  // The region this key resolved to left the DOM — drop the dead entry so it
+  // can never swallow toasts, and resolve fresh below.
+  if (cached) regions.delete(target);
+
+  // Adopt a region the app already placed. Regions this store already
+  // claimed for OTHER targets are not candidates.
+  const claimed = new Set(regions.values());
+  const candidates = Array.from(
+    document.querySelectorAll<HTMLElement>('kai-toast-region'),
+  ).filter((el) => el.isConnected && !claimed.has(el) && regionTarget(el) === target);
+  if (candidates.length > 1 && !warnedAmbiguousRegions) {
+    warnedAmbiguousRegions = true;
+    console.warn(
+      `[kitn] toast(): ${candidates.length} candidate <kai-toast-region> elements are in the ` +
+        'document; adopting the first in document order. Keep one region per target so the ' +
+        'imperative toast() API has an unambiguous home.',
+    );
+  }
+  const adopted = candidates[0];
+  if (adopted) {
+    (adopted as unknown as { toasts: ToastItem[] }).toasts = toasts as ToastItem[];
+    regions.set(target, adopted);
+    setMounted(true);
+    return adopted;
+  }
+
   const el = document.createElement('kai-toast-region') as HTMLElement;
   // Append FIRST so the element upgrades, THEN bind. Setting a property before
   // upgrade loses it: component-register resets every prop in the constructor on

package/src/primitives/url-scheme-policy.ts

@@ -0,0 +1,70 @@
+// src/primitives/url-scheme-policy.ts
+// The kit's one URL-scheme allow/deny policy, split out of card-routing.ts so it
+// has NO DOM dependency (`URL` is a global in both the browser and Node — the
+// rest of card-routing.ts uses HTMLElement/window/CustomEvent, which aren't).
+// That split matters beyond tidiness: this schema.ts (agent-tooling/construct)
+// runs under tsconfig.mcp.json's Node-only, no-DOM-lib pass (it's imported
+// transitively via mcp/tools/construct.ts), and importing anything from
+// card-routing.ts there drags its HTMLElement/window/Document/CustomEvent
+// references into that compile and breaks it — even though only isSafeUrl is
+// used. card-routing.ts re-exports everything here so its own public surface
+// (isSafeUrl/isScriptUrl, used by markdown.tsx/artifact.tsx/source.tsx) is
+// unchanged; this is a location split, not a second policy.
+
+const SAFE_SCHEMES = ['http:', 'https:', 'mailto:'];
+const SCRIPT_SCHEMES = ['javascript:', 'vbscript:'];
+
+/** The scheme the WHATWG parser reads out of `url`, resolved against a base so a
+ *  relative input inherits `http:`. `undefined` when it will not parse at all.
+ *
+ *  ONE parser for the two questions below, deliberately: the parsing is where
+ *  the subtlety lives (it strips embedded tabs/newlines and trims surrounding
+ *  whitespace before reading the scheme, so `java\nscript:` and
+ *  `  javascript:...  ` are both read as `javascript:` -- which a regex over the
+ *  raw string would miss). Two predicates over one parse cannot drift on that;
+ *  two hand-rolled parsers would. */
+function schemeOf(url: string): string | undefined {
+  try { return new URL(url, 'http://_invalid_base').protocol; } catch { return undefined; }
+}
+
+/** True when `url` is safe to put in an href / hand to `window.open` / an `<img src>`.
+ *
+ *  Exported so the MARKDOWN renderer, the ARTIFACT viewer and the construct
+ *  format's `widget.launcherIcon` reuse this exact guard rather than growing a
+ *  second scheme list that can drift from this one.
+ *
+ *  Resolving against a base is deliberate and is what makes it correct for
+ *  markdown: a relative or fragment link (`/docs`, `#section`, `./rel`) is
+ *  ordinary markdown, and resolving it inherits the base's `http:` so it
+ *  passes, while `javascript:`/`data:`/`vbscript:` keep their own protocol and
+ *  fail. It is correct for the artifact viewer for the same reason: a file with
+ *  no `src` to resolve against yields a bare relative path (`docs/report.pdf`),
+ *  which is a legitimate artifact address. Contrast `isRenderableLink` in
+ *  `primitives/link-preview.ts`, which takes NO base and so demands an absolute
+ *  http(s) URL: that is the right guard for a model-supplied citation -- a
+ *  reference to a page on the public web -- this one for markdown body links,
+ *  artifact file addresses, and a construct's launcher icon. */
+export function isSafeUrl(url: string): boolean {
+  const scheme = schemeOf(url);
+  return scheme !== undefined && SAFE_SCHEMES.includes(scheme);
+}
+
+/** True when navigating to `url` would EXECUTE it as script in the initiating
+ *  document's origin.
+ *
+ *  Strictly narrower than `!isSafeUrl(url)`, and not a competing policy: it
+ *  answers a different question, for the one sink where the allowlist is the
+ *  wrong tool. An `<iframe src>` legitimately takes `data:` and `blob:` (a
+ *  `data:` blob artifact is a documented `<kai-artifact>` use -- it is what
+ *  `displayUrl` exists for) and both get an OPAQUE origin in every modern
+ *  browser, so neither can reach the host page. `javascript:`/`vbscript:` are
+ *  the schemes that run in the EMBEDDER's origin, and they are the whole risk:
+ *  the default sandbox (no `allow-same-origin`) already makes the browser refuse
+ *  them, but a consumer who sets `allow-same-origin` turns a model-supplied
+ *  `src` into host-origin script execution. The artifact viewer used to suggest
+ *  that setting for "an artifact you trust"; it no longer does, and this guard
+ *  is what protects the consumers who took the old advice. */
+export function isScriptUrl(url: string): boolean {
+  const scheme = schemeOf(url);
+  return scheme !== undefined && SCRIPT_SCHEMES.includes(scheme);
+}

package/src/primitives/use-resize-observer.ts

@@ -10,3 +10,36 @@ export function observeContentHeight(el: Element, onHeight: (height: number) =>
   ro.observe(el);
   return () => ro.disconnect();
 }
+
+/** Observe an element's resizes but report the FULL rendered document height (not the
+ *  observed element's own content-box) — `document.body.scrollHeight`.
+ *
+ *  Used by the remote-card provider runtime to size the host iframe:
+ *  `observeContentHeight` reports the ResizeObserver content-box of
+ *  the observed root, which drops that root's OWN padding/border and any ancestor
+ *  (e.g. `<body>`) padding above it — the host then clips the bottom of the card by
+ *  exactly those lost pixels. `scrollHeight` is the full padding-box height as actually
+ *  rendered, so it stays correct no matter which element in the ancestor chain carries
+ *  the padding/border, including if the provider page's own styles change later —
+ *  reading contentRect off one fixed element, or hand-summing computed padding/border
+ *  off a fixed list of ancestors, would both need updating every time that chain does.
+ *
+ *  Deliberately `document.body.scrollHeight`, NOT `document.documentElement.scrollHeight`
+ *  (N1, task-10-report.md "Fix-wave re-review"): the CSSOM View spec special-cases the
+ *  scrollHeight of the ROOT element to be `max(viewport scrolling area, viewport
+ *  height)` — and the host sets the iframe's viewport FROM this very measurement
+ *  (`host-embed.ts` `sizeIframe`), so `documentElement.scrollHeight` can only grow for
+ *  the life of the frame: once the iframe is tall, the root's own scrollHeight is
+ *  floored at that height even after the card's content shrinks. `<body>` carries no
+ *  such floor — its scrollHeight is a plain padding-box measurement of body's own
+ *  content, so it shrinks along with the card. */
+export function observeDocumentHeight(el: Element, onHeight: (height: number) => void): () => void {
+  let last = -1;
+  const ro = new ResizeObserver(() => {
+    const doc = el.ownerDocument;
+    const h = doc?.body?.scrollHeight ?? doc?.documentElement?.scrollHeight ?? el.getBoundingClientRect().height;
+    if (last < 0 || Math.abs(h - last) > THRESHOLD) { last = h; onHeight(h); }
+  });
+  ro.observe(el);
+  return () => ro.disconnect();
+}

package/src/primitives/use-speech-recognition.ts

@@ -51,6 +51,14 @@ export interface SpeechRecognitionStartOptions {
   lang?: string;
   /** Called with each interim (non-final) transcript when `interim` is enabled. */
   onInterim?: (text: string) => void;
+  /**
+   * Called when the recognition session hits a runtime error (`recognition.onerror`),
+   * with the platform's error code (`network`, `not-allowed`, `no-speech`, ...) and a
+   * human-readable message. The session still ends through `onend`, so `start()` still
+   * resolves (with whatever text was captured before the error). Without this callback
+   * a runtime failure is invisible: the `error` signal is state, not a notification.
+   */
+  onError?: (error: string, message: string) => void;
 }
 
 /**
@@ -102,7 +110,10 @@ export function useSpeechRecognition(options: UseSpeechRecognitionOptions = {})
       };
 
       recognition.onerror = (event) => {
-        setError(event.error ?? 'Speech recognition error');
+        const code = event.error ?? 'unknown';
+        const message = `Speech recognition error: ${code}`;
+        setError(message);
+        opts.onError?.(code, message);
       };
 
       recognition.onend = () => {

package/src/primitives/use-stick-to-bottom.ts

@@ -17,14 +17,42 @@ export function useStickToBottom() {
 
   function scrollToBottom(behavior: ScrollBehavior = 'smooth') {
     if (!containerEl) return;
-    containerEl.scrollTo({ top: containerEl.scrollHeight, behavior });
+    if (typeof containerEl.scrollTo === 'function') {
+      containerEl.scrollTo({ top: containerEl.scrollHeight, behavior });
+    } else {
+      containerEl.scrollTop = containerEl.scrollHeight;
+    }
     shouldStick = true;
     setIsAtBottom(true);
   }
 
+  let pendingFrame: number | undefined;
+
+  /**
+   * `cancelAnimationFrame`, captured at SETUP -- not called bare at cleanup.
+   *
+   * Cleanup is not guaranteed to run while the page that mounted this
+   * primitive is still standing: a host can tear its DOM globals down first
+   * (`component-register`'s `disconnectedCallback` defers a microtask; a
+   * test environment deletes the globals synchronously right after
+   * detaching). A bare `cancelAnimationFrame` there throws, surfacing as an
+   * unhandled rejection that fails a run in which every test passed --
+   * see tests/components/teardown-without-dom-globals.test.tsx, and the
+   * same pattern in create-tween.ts.
+   *
+   * Guarded because "setup" here is the component body, and a server render
+   * executes component bodies too; Node has neither global.
+   */
+  const cancelFrame = typeof cancelAnimationFrame === 'function'
+    ? cancelAnimationFrame.bind(globalThis)
+    : () => {};
+
   function onNewContent() {
     if (shouldStick) {
-      requestAnimationFrame(() => scrollToBottom('instant'));
+      pendingFrame = requestAnimationFrame(() => {
+        pendingFrame = undefined;
+        scrollToBottom('instant');
+      });
     }
   }
 
@@ -36,6 +64,10 @@ export function useStickToBottom() {
     onCleanup(() => {
       el.removeEventListener('scroll', checkIfAtBottom);
       observer.disconnect();
+      if (pendingFrame !== undefined) {
+        cancelFrame(pendingFrame);
+        pendingFrame = undefined;
+      }
     });
   }
 

package/src/primitives/use-text-stream.ts

@@ -5,6 +5,19 @@ export interface UseTextStreamOptions {
   speed?: number;
   characterChunkSize?: number;
   fadeDuration?: number;
+  segmentDelay?: number;
+}
+
+/** Default fade-in duration for a given speed (ms) — shared with ResponseStream. */
+export function defaultFadeDuration(speed: number): number {
+  const s = Math.min(100, Math.max(1, speed));
+  return Math.round(1000 / Math.sqrt(s));
+}
+
+/** Default per-segment stagger for a given speed (ms) — shared with ResponseStream. */
+export function defaultSegmentDelay(speed: number): number {
+  const s = Math.min(100, Math.max(1, speed));
+  return Math.max(1, Math.round(100 / Math.sqrt(s)));
 }
 
 export interface TextStreamSegment {
@@ -23,6 +36,7 @@ export function useTextStream(options: UseTextStreamOptions) {
   let fullText = '';
   let charIndex = 0;
   let intervalId: ReturnType<typeof setInterval> | undefined;
+  let completeTimeoutId: ReturnType<typeof setTimeout> | undefined;
   let isPaused = false;
   let asyncIterator: AsyncIterator<string> | undefined;
 
@@ -31,6 +45,10 @@ export function useTextStream(options: UseTextStreamOptions) {
       clearInterval(intervalId);
       intervalId = undefined;
     }
+    if (completeTimeoutId !== undefined) {
+      clearTimeout(completeTimeoutId);
+      completeTimeoutId = undefined;
+    }
   }
 
   function typewriterTick() {
@@ -76,8 +94,21 @@ export function useTextStream(options: UseTextStreamOptions) {
         const words = source.split(/(\s+)/).filter(Boolean);
         setSegments(words.map((text, index) => ({ text, index })));
         setDisplayedText(source);
-        // isComplete fires after animation has time to play
-        // (segments count * delay per segment from ResponseStream)
+        // Completion announces after the staggered animation has had time to
+        // play: segments * per-segment delay + one fade duration — the promise
+        // the comment here used to make with no code behind it (nothing on this
+        // path ever called setIsComplete(true), so kai-complete never fired for
+        // a fade-mode string). A timer, not a synchronous write: the consumer
+        // attaches its kai-complete listener a beat after mount, and a
+        // same-tick fire races past it.
+        const segDelay = typeof options.segmentDelay === 'number'
+          ? Math.max(0, options.segmentDelay)
+          : defaultSegmentDelay(speed);
+        const fadeDur = options.fadeDuration ?? defaultFadeDuration(speed);
+        completeTimeoutId = setTimeout(() => {
+          completeTimeoutId = undefined;
+          setIsComplete(true);
+        }, words.length * segDelay + fadeDur);
       }
     } else {
       if (options.mode === 'typewriter') {

package/src/remote/provider-runtime.ts

@@ -14,7 +14,7 @@ import { createPacker, isCardWireFrame, type WireMessage } from './wire';
 import { assertOrigin, redactFrame } from './origin';
 import { negotiateVersion } from './version';
 import { hasPollutionKey } from './validate';
-import { observeContentHeight } from '../primitives/use-resize-observer';
+import { observeDocumentHeight } from '../primitives/use-resize-observer';
 import { validateAgainstSchema, type JsonSchema } from '../primitives/card-validate';
 
 /** A provider-side renderer for one card `type`. Renamed (was CardRenderer) per H-K
@@ -105,10 +105,13 @@ export function createCardBridge(options: CreateCardBridgeOptions): CardBridge {
   }
 
   function startObserver(): void {
-    // Tear down any existing observer so observeContentHeight's internal `last` baseline
+    // Tear down any existing observer so observeDocumentHeight's internal `last` baseline
     // re-initializes to -1 and the newly-mounted card always emits its initial height.
+    // observeDocumentHeight (not observeContentHeight) so the reported height covers
+    // the FULL rendered document — root's own padding/border AND the provider page's
+    // body padding above it — not just root's ResizeObserver content-box (D1).
     stopObserver?.(); stopObserver = null;
-    stopObserver = observeContentHeight(root, (height) => {
+    stopObserver = observeDocumentHeight(root, (height) => {
       if (!currentId) return;
       cardHost.emit({ kind: 'resize', cardId: currentId, height });
     });

package/src/schemas/index.ts

@@ -279,6 +279,7 @@ export {
 } from './tool-defs';
 export type {
   AnthropicToolDef,
+  CardRequireRule,
   CardToolInput,
   CardToolOptions,
   CardToolSource,