@kitn.ai/ui 0.16.0 → 0.18.0

package/src/components/voice-input.tsx

@@ -1,43 +1,126 @@
-import { splitProps, Show, For, createSignal } from 'solid-js';
+import { splitProps, Show, For, createSignal, createEffect, on } from 'solid-js';
 import { cn } from '../utils/cn';
 import { Button } from '../ui/button';
 import { Tooltip } from '../ui/tooltip';
 import { useVoiceRecorder } from '../primitives/use-voice-recorder';
+import { useSpeechRecognition } from '../primitives/use-speech-recognition';
+
+/** Imperative handle exposed via `controllerRef` — surfaces the recorder's latent
+ *  start/stop so the `<kai-voice-input>` facade can forward them as instance
+ *  methods (push-to-talk). Both run the SAME getUserMedia → blob → transcription
+ *  path as clicking the mic, so manual + programmatic emit identically. */
+export interface VoiceInputController {
+  /** Begin recording programmatically (same path as clicking the mic). */
+  start(): void;
+  /** Stop the in-progress recording (produces the blob → onTranscribe). */
+  stop(): void;
+}
 
 export interface VoiceInputProps {
   onTranscribe: (audio: Blob) => Promise<string>;
   onTranscription: (text: string) => void;
   disabled?: boolean;
   class?: string;
+  /** Host supplied a `transcribe` callback. When true the MediaRecorder →
+   *  onTranscribe path runs. When false the component prefers native
+   *  SpeechRecognition (capable browsers), falling back to record-only. */
+  hasTranscribe?: boolean;
+  /** BCP-47 language tag for native recognition (e.g. `en-US`). */
+  lang?: string;
+  /** Emit live partial transcripts via `onInterim` (native path only). */
+  interim?: boolean;
+  /** Live partial transcript from native recognition (when `interim`). */
+  onInterim?: (text: string) => void;
+  /** Fires whenever recording starts or stops. Guarded against the spurious
+   *  initial `false` — only true transitions emit (the facade maps this to
+   *  kai-recording-change). */
+  onRecordingChange?: (recording: boolean) => void;
+  /** Receive the imperative controller once mounted. The `<kai-voice-input>`
+   *  facade forwards these as element methods (start/stop). */
+  controllerRef?: (controller: VoiceInputController) => void;
 }
 
 export function VoiceInput(props: VoiceInputProps) {
   const [local] = splitProps(props, ['onTranscribe', 'onTranscription', 'disabled', 'class']);
   const { isRecording, start, stop } = useVoiceRecorder();
+  const speech = useSpeechRecognition({ interim: props.interim });
   const [isProcessing, setIsProcessing] = createSignal(false);
 
+  // Path selection (§6): a `transcribe` callback always wins (MediaRecorder →
+  // host transcriber). Otherwise prefer native SpeechRecognition when the browser
+  // supports it. The unsupported-no-callback case falls through to recording the
+  // blob (→ onTranscribe → kai-audio-captured) with no text.
+  const useNative = () => !props.hasTranscribe && speech.isSupported;
+
   const label = () =>
-    isProcessing() ? 'Transcribing...' : isRecording() ? 'Stop recording' : 'Voice input';
+    isProcessing() ? 'Transcribing...' : isActive() ? 'Stop recording' : 'Voice input';
 
-  async function handleClick() {
-    if (isRecording()) {
-      stop();
-    } else {
+  const isActive = () => (useNative() ? speech.isListening() : isRecording());
+
+  // Native path: SpeechRecognition resolves with the final transcript when it
+  // ends (click again or controller.stop()). Final text → onTranscription.
+  async function beginRecognition() {
+    try {
+      const text = await speech.start({
+        lang: props.lang,
+        onInterim: props.interim ? (t) => props.onInterim?.(t) : undefined,
+      });
+      if (text.trim()) local.onTranscription(text.trim());
+    } catch {
+      /* surfaced via speech.error; the mic returns to idle */
+    }
+  }
+
+  // Begin recording, then run transcription once the blob resolves. Shared by the
+  // mic click and the imperative start() so both flows emit identically. start()
+  // resolves its Blob when the recorder stops (click again or controller.stop()).
+  async function beginRecording() {
+    try {
+      const blob = await start();
+      setIsProcessing(true);
       try {
-        const blob = await start();
-        setIsProcessing(true);
-        try {
-          const text = await local.onTranscribe(blob);
-          if (text.trim()) local.onTranscription(text.trim());
-        } finally {
-          setIsProcessing(false);
-        }
-      } catch {
+        const text = await local.onTranscribe(blob);
+        if (text.trim()) local.onTranscription(text.trim());
+      } finally {
         setIsProcessing(false);
       }
+    } catch {
+      setIsProcessing(false);
     }
   }
 
+  // Drive whichever path is active (§6: start/stop must follow the live path).
+  function begin() {
+    if (useNative()) void beginRecognition();
+    else void beginRecording();
+  }
+  function end() {
+    if (useNative()) speech.stop();
+    else stop();
+  }
+
+  async function handleClick() {
+    if (isActive()) end();
+    else begin();
+  }
+
+  // Emit recording transitions to the host. `on(..., { defer: true })` skips the
+  // initial mount value (a spurious {recording:false}) — only real start/stop
+  // transitions fire. Drives BOTH manual (click) and programmatic (start/stop)
+  // since they all flip the active path's signal (MediaRecorder or recognition).
+  createEffect(on(isActive, (recording) => {
+    props.onRecordingChange?.(recording);
+  }, { defer: true }));
+
+  // Imperative controller (Pattern C): hand the facade a start/stop handle.
+  // start() runs the active path; stop() ends the in-progress session (resolving
+  // the active path's promise). Guard start() so a double-start while already
+  // active is a no-op (matches the click toggle).
+  props.controllerRef?.({
+    start: () => { if (!isActive()) begin(); },
+    stop: () => end(),
+  });
+
   // Mic icon (not recording)
   const MicIcon = () => (
     <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
@@ -65,7 +148,7 @@ export function VoiceInput(props: VoiceInputProps) {
   return (
     <div class={cn('relative inline-flex items-center justify-center', local.class)}>
       {/* Animated pulse rings when recording */}
-      <Show when={isRecording()}>
+      <Show when={isActive()}>
         <For each={[0, 1, 2]}>
           {(index) => (
             <div
@@ -88,16 +171,16 @@ export function VoiceInput(props: VoiceInputProps) {
           disabled={local.disabled || isProcessing()}
           class={cn(
             'relative z-10 rounded-full transition-all duration-300',
-            isRecording() && 'bg-destructive text-white hover:bg-destructive/80',
+            isActive() && 'bg-destructive text-white hover:bg-destructive/80',
           )}
         >
           <Show when={isProcessing()}>
             <Spinner />
           </Show>
-          <Show when={!isProcessing() && isRecording()}>
+          <Show when={!isProcessing() && isActive()}>
             <StopIcon />
           </Show>
-          <Show when={!isProcessing() && !isRecording()}>
+          <Show when={!isProcessing() && !isActive()}>
             <MicIcon />
           </Show>
         </Button>

package/src/components/voice-output.tsx

@@ -0,0 +1,202 @@
+import { splitProps, Show, createSignal, createEffect, on, onCleanup } from 'solid-js';
+import { cn } from '../utils/cn';
+import { Button } from '../ui/button';
+import { Tooltip } from '../ui/tooltip';
+
+/** Imperative handle exposed via `controllerRef` — surfaces the playback controls
+ *  so the `<kai-voice-output>` facade can forward them as instance methods. Both
+ *  the native (speechSynthesis) and model (synthesize → Audio) paths run through
+ *  these, so manual clicks and programmatic calls behave identically. */
+export interface VoiceOutputController {
+  /** Speak the current `text` (native by default, model if `synthesize` is set). */
+  speak(): void;
+  /** Pause playback (resumable). */
+  pause(): void;
+  /** Resume paused playback. */
+  resume(): void;
+  /** Stop playback and reset. */
+  stop(): void;
+}
+
+export interface VoiceOutputProps {
+  /** The utterance to read aloud. */
+  text: string;
+  /** Speak automatically when `text` is set/changed. */
+  autoplay?: boolean;
+  /** TTS model seam: given text, return an audio Blob to play. When set, the
+   *  native speechSynthesis path is bypassed. Mirrors VoiceInput's `onTranscribe`. */
+  onSynthesize?: (text: string) => Promise<Blob>;
+  /** Fires whenever playback starts or stops. */
+  onSpeakingChange?: (speaking: boolean) => void;
+  /** Fires once the model path resolves audio (model path only). */
+  onSynthesized?: (blob: Blob) => void;
+  disabled?: boolean;
+  class?: string;
+  /** Receive the imperative controller once mounted. The `<kai-voice-output>`
+   *  facade forwards these as element methods (speak/pause/resume/stop). */
+  controllerRef?: (controller: VoiceOutputController) => void;
+}
+
+/** True when the browser exposes the Web Speech synthesis API. */
+function hasSpeechSynthesis(): boolean {
+  return typeof window !== 'undefined' && 'speechSynthesis' in window;
+}
+
+export function VoiceOutput(props: VoiceOutputProps) {
+  const [local] = splitProps(props, ['text', 'disabled', 'class']);
+  const [isSpeaking, setIsSpeaking] = createSignal(false);
+  const [isLoading, setIsLoading] = createSignal(false);
+
+  // The model path plays through one reused <Audio>; the native path drives
+  // speechSynthesis. Only one is live at a time (branch on onSynthesize).
+  let audio: HTMLAudioElement | undefined;
+  let objectUrl: string | undefined;
+  let utterance: SpeechSynthesisUtterance | undefined;
+
+  // No way to speak at all → render disabled. A model seam OR native synthesis
+  // is enough; absent both, the control is inert (see the facade/spec).
+  const capable = () => !!props.onSynthesize || hasSpeechSynthesis();
+
+  const label = () =>
+    isLoading() ? 'Synthesizing...' : isSpeaking() ? 'Stop' : 'Read aloud';
+
+  function revokeUrl() {
+    if (objectUrl) {
+      URL.revokeObjectURL(objectUrl);
+      objectUrl = undefined;
+    }
+  }
+
+  // Native path: speechSynthesis.speak(new SpeechSynthesisUtterance(text)).
+  function speakNative() {
+    if (!hasSpeechSynthesis() || !local.text) return;
+    window.speechSynthesis.cancel();
+    utterance = new SpeechSynthesisUtterance(local.text);
+    utterance.onend = () => setIsSpeaking(false);
+    utterance.onerror = () => setIsSpeaking(false);
+    setIsSpeaking(true);
+    window.speechSynthesis.speak(utterance);
+  }
+
+  // Model path: await onSynthesize(text) → play the Blob via an <Audio>.
+  async function speakModel() {
+    if (!props.onSynthesize || !local.text) return;
+    setIsLoading(true);
+    try {
+      const blob = await props.onSynthesize(local.text);
+      props.onSynthesized?.(blob);
+      revokeUrl();
+      objectUrl = URL.createObjectURL(blob);
+      audio ??= new Audio();
+      audio.src = objectUrl;
+      audio.onended = () => setIsSpeaking(false);
+      audio.onerror = () => setIsSpeaking(false);
+      setIsSpeaking(true);
+      await audio.play();
+    } catch {
+      setIsSpeaking(false);
+    } finally {
+      setIsLoading(false);
+    }
+  }
+
+  function speak() {
+    if (props.onSynthesize) void speakModel();
+    else speakNative();
+  }
+
+  function stop() {
+    if (props.onSynthesize) {
+      if (audio) {
+        audio.pause();
+        audio.currentTime = 0;
+      }
+    } else if (hasSpeechSynthesis()) {
+      window.speechSynthesis.cancel();
+    }
+    setIsSpeaking(false);
+  }
+
+  function pause() {
+    if (props.onSynthesize) audio?.pause();
+    else if (hasSpeechSynthesis()) window.speechSynthesis.pause();
+  }
+
+  function resume() {
+    if (props.onSynthesize) void audio?.play();
+    else if (hasSpeechSynthesis()) window.speechSynthesis.resume();
+  }
+
+  function handleClick() {
+    if (isSpeaking()) stop();
+    else speak();
+  }
+
+  // Emit speaking transitions to the host. `defer: true` skips the spurious
+  // initial `false` — only real start/stop transitions fire.
+  createEffect(on(isSpeaking, (speaking) => {
+    props.onSpeakingChange?.(speaking);
+  }, { defer: true }));
+
+  // Autoplay: speak when text first arrives / changes (defer skips the mount
+  // value so an empty seed doesn't speak).
+  createEffect(on(() => local.text, (text) => {
+    if (props.autoplay && text) speak();
+  }, { defer: true }));
+
+  props.controllerRef?.({ speak, pause, resume, stop });
+
+  onCleanup(() => {
+    stop();
+    revokeUrl();
+  });
+
+  // Speaker icon (idle)
+  const SpeakerIcon = () => (
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <polygon points="11 5 6 9 2 9 2 15 6 15 11 19 11 5" />
+      <path d="M19.07 4.93a10 10 0 010 14.14M15.54 8.46a5 5 0 010 7.07" />
+    </svg>
+  );
+
+  // Square stop icon (speaking)
+  const StopIcon = () => (
+    <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor">
+      <rect x="4" y="4" width="16" height="16" rx="2" />
+    </svg>
+  );
+
+  // Spinner (model synthesis in flight)
+  const Spinner = () => (
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="animate-spin">
+      <path d="M21 12a9 9 0 11-6.219-8.56" />
+    </svg>
+  );
+
+  return (
+    <div class={cn('relative inline-flex items-center justify-center', local.class)}>
+      <Tooltip content={label()}>
+        <Button
+          part="button"
+          variant="ghost"
+          size="icon-sm"
+          aria-label={label()}
+          aria-pressed={isSpeaking()}
+          onClick={handleClick}
+          disabled={local.disabled || !capable() || isLoading()}
+          class={cn('relative z-10 rounded-full transition-all duration-300')}
+        >
+          <Show when={isLoading()}>
+            <Spinner />
+          </Show>
+          <Show when={!isLoading() && isSpeaking()}>
+            <StopIcon />
+          </Show>
+          <Show when={!isLoading() && !isSpeaking()}>
+            <SpeakerIcon />
+          </Show>
+        </Button>
+      </Tooltip>
+    </div>
+  );
+}

package/src/elements/agent-card.tsx

@@ -0,0 +1,67 @@
+import { defineWebComponent } from './define';
+import { AgentCard, type AgentStatus } from '../ui/agent-card';
+
+interface Props extends Record<string, unknown> {
+  /** The agent's name — the primary label. Attribute: `name`. */
+  name?: string;
+  /** Selected / focused state: highlighted border + surface. Attribute: `active`. */
+  active?: boolean;
+  /** Raise a prominent "Needs you" pill plus a glowing amber edge — the
+   *  attention-routing signal that pulls focus to this agent. Attribute:
+   *  `needs-attention`. */
+  needsAttention?: boolean;
+  /** Run status — a JS PROPERTY (object), not an attribute. Shape:
+   *  `{ tone, label?, pulse? }`, where `tone` is one of `working` | `idle` |
+   *  `done` | `error` | `blocked` (maps to the kit's tool hues), `label` is an
+   *  optional short string beside the dot, and `pulse` animates the dot. Set it
+   *  with `el.status = { tone: 'working', label: 'Working', pulse: true }`. */
+  status?: AgentStatus;
+}
+
+/** Events fired by `<kai-agent-card>`. */
+interface Events {
+  /** The card was activated — clicked, or Enter / Space while focused. Promote
+   *  this agent back to focus. */
+  'kai-activate': void;
+  /** The trailing "..." kebab was clicked. The consumer opens its own menu; the
+   *  card only surfaces the affordance (the click does not also activate the card). */
+  'kai-menu': void;
+}
+
+/**
+ * `<kai-agent-card>` — the compact glanceable card for one agent in a multi-agent
+ * workspace. The agent name with a leading tone-colored status dot, an optional
+ * "Needs you" attention treatment, an `active` (selected) state, and a trailing
+ * "..." overflow button.
+ *
+ * Set `status` as a JS property (it's an object); `name` is a string attribute and
+ * `active` / `needs-attention` are boolean attributes. Listen for `kai-activate`
+ * (promote to focus) and `kai-menu` (open your own per-agent menu).
+ *
+ * ```html
+ * <kai-agent-card name="Refactor bot" active></kai-agent-card>
+ * <script type="module">
+ *   import '@kitn.ai/ui/elements';
+ *   const card = document.querySelector('kai-agent-card');
+ *   card.status = { tone: 'working', label: 'Working', pulse: true };
+ *   card.addEventListener('kai-activate', () => focusAgent());
+ *   card.addEventListener('kai-menu', () => openMenu());
+ * </script>
+ * ```
+ * Recolor the status dot via `::part(status)` and the kebab via `::part(menu)`.
+ */
+defineWebComponent<Props, Events>('kai-agent-card', {
+  name: undefined,
+  active: undefined,
+  needsAttention: undefined,
+  status: undefined,
+}, (props, { dispatch, flag }) => (
+  <AgentCard
+    name={(props.name as string) ?? ''}
+    active={flag('active')}
+    needsAttention={flag('needsAttention')}
+    status={(props.status as AgentStatus) ?? { tone: 'idle' }}
+    onActivate={() => dispatch('kai-activate')}
+    onMenu={() => dispatch('kai-menu')}
+  />
+));

package/src/elements/artifact.tsx

@@ -1,14 +1,19 @@
 import { createSignal, onMount, onCleanup } from 'solid-js';
 import { defineWebComponent } from './define';
-import { Artifact, type ArtifactFile, type ArtifactTab } from '../components/artifact';
+import { Artifact, type ArtifactController, type ArtifactFile, type ArtifactTab } from '../components/artifact';
 
 interface Props extends Record<string, unknown> {
   /** URL the preview iframe frames. Consumer-controlled. */
   src?: string;
   /** Files for the Code tab tree + each file's preview `url`. Set as a JS property (array). */
   files: ArtifactFile[];
-  /** Active tab: `preview` (default) or `code`. */
+  /** Controlled active tab: `preview` or `code`. When set, the artifact follows it
+   *  (re-asserted on change). Leave unset for an uncontrolled tab (see `defaultTab`). */
   tab?: ArtifactTab;
+  /** Uncontrolled INITIAL tab (used only when `tab` is unset). Default `preview`.
+   *  Seeds the starting tab; the user can then switch freely without the consumer
+   *  re-asserting a controlled `tab`. */
+  defaultTab?: ArtifactTab;
   /** Selected file path — syncs the tree highlight, Code source, and preview. */
   activeFile?: string;
   /** iframe `sandbox` override. Secure default `allow-scripts allow-forms` (NOT `allow-same-origin`). */
@@ -35,6 +40,11 @@ interface Props extends Record<string, unknown> {
   standalone?: boolean;
   /** Show the address but make it read-only (visible, nav-tracking, non-editable). */
   readonlyPath?: boolean;
+  /** Friendly address shown in the path field instead of the real current url
+   *  (read-only, non-navigable). Use when the framed url is not consumer-facing
+   *  (e.g. a `data:` blob) so a clean address shows instead of leaking it. Scalar
+   *  string: set as the `display-url` attribute or the `displayUrl` property. */
+  displayUrl?: string;
 }
 
 interface Events extends Record<string, unknown> {
@@ -59,7 +69,8 @@ interface Events extends Record<string, unknown> {
 defineWebComponent<Props, Events>('kai-artifact', {
   src: undefined,
   files: [],
-  tab: 'preview',
+  tab: undefined,
+  defaultTab: undefined,
   activeFile: undefined,
   sandbox: 'allow-scripts allow-forms',
   iframeTitle: undefined,
@@ -73,9 +84,44 @@ defineWebComponent<Props, Events>('kai-artifact', {
   noTabs: false,
   standalone: false,
   readonlyPath: false,
-}, (props, { element, dispatch, flag }) => {
+  displayUrl: undefined,
+}, (props, { element, dispatch, flag, expose }) => {
   const [maximized, setMaximized] = createSignal(flag('maximized'));
 
+  // ── Imperative API (instance methods on the host) ──────────────────────────
+  // Pattern C: the Artifact component owns the history stack + tab/file/maximize
+  // state and hands up a controller; the facade captures it and exposes delegating
+  // methods. Every internal handler still fires its event (navigate → kai-navigate;
+  // selectFile → kai-file-select; maximize/restore → kai-maximize-change). Names are
+  // collision-checked against the props: openExternal (not openInTab — a prop),
+  // maximize/restore (not maximized — a prop), navigate/selectFile (not src/activeFile
+  // — props); NO tab-switching method (tab is a prop → switch via `el.tab`).
+  let controller: ArtifactController | undefined;
+  expose({
+    /** Go back in the artifact's own history stack (no-op when there's no prior entry). */
+    back: () => controller?.back(),
+    /** Go forward in the history stack (no-op when there's no forward entry). */
+    forward: () => controller?.forward(),
+    /** Force-reload the current preview url (also re-renders an inline PDF). */
+    reload: () => controller?.reload(),
+    /** Navigate to the `src` home url (no-op when there's no `src`). */
+    home: () => controller?.home(),
+    /** Push + load a url in the preview — the path-field submit path (fires kai-navigate). */
+    navigate: (url: string) => controller?.navigate(url),
+    /** Select a file by path: highlights the tree, shows its source, navigates the
+     *  preview (fires kai-file-select + kai-navigate). Named selectFile to avoid the
+     *  `activeFile` prop. */
+    selectFile: (path: string) => controller?.selectFile(path),
+    /** Open the current url in a new browser tab (no-op when there's no concrete url).
+     *  Named openExternal, NOT openInTab — that's a prop (toolbar button visibility). */
+    openExternal: () => controller?.openExternal(),
+    /** Enter the maximized view-state (fires kai-maximize-change{maximized:true}).
+     *  Named maximize, NOT maximized — that's a prop. */
+    maximize: () => controller?.maximize(),
+    /** Exit the maximized view-state (fires kai-maximize-change{maximized:false}). */
+    restore: () => controller?.restore(),
+  });
+
   const onMaximizeChange = (next: boolean) => {
     setMaximized(next);
     // 1) The PROTOCOL intent — raw, bubbling + composed (NOT via dispatch()).
@@ -113,6 +159,7 @@ defineWebComponent<Props, Events>('kai-artifact', {
           src={props.src}
           files={props.files}
           tab={props.tab}
+          defaultTab={props.defaultTab}
           activeFile={props.activeFile}
           sandbox={props.sandbox}
           iframeTitle={props.iframeTitle}
@@ -126,10 +173,12 @@ defineWebComponent<Props, Events>('kai-artifact', {
           showTabs={!flag('noTabs')}
           standalone={flag('standalone')}
           readonlyPath={flag('readonlyPath')}
+          displayUrl={props.displayUrl}
           onMaximizeChange={onMaximizeChange}
           onNavigate={(url) => dispatch('kai-navigate', { url })}
           onTabChange={(tab) => dispatch('kai-tab-change', { tab })}
           onFileSelect={(path) => dispatch('kai-file-select', { path })}
+          controllerRef={(c) => (controller = c)}
         />
       </div>
     </>

package/src/elements/attachments.tsx

@@ -118,6 +118,7 @@ defineWebComponent<Props, Events>('kai-attachments', {
                       }
                     >
                       <img
+                        part="preview"
                         src={item.url}
                         alt={getAttachmentLabel(item)}
                         class="block max-h-64 max-w-xs rounded object-contain"

package/src/elements/autoloader.ts

@@ -0,0 +1,89 @@
+// The kai-* autoloader (opt-in, additive — the Web Awesome model).
+//
+// Include this ONE module (via a CDN/static `<script type="module">` tag) and it
+// watches the DOM for undefined kai-* elements and dynamically imports each
+// element's module on demand — so a page that only uses <kai-chat> never downloads
+// the others. The register-all bundle (@kitn.ai/ui/elements) stays the default;
+// this is the delivery for NO-BUILD / CDN / static-served pages.
+//
+// IMPORTANT — this is a CDN / static-file pattern (it resolves sibling element
+// modules relative to its own URL). It is NOT importable through a bundler: Vite /
+// webpack relocate `import.meta.url` away from the element files and cannot analyze
+// the dynamic import, so it 404s. In a BUNDLED app use per-element imports
+// (`import '@kitn.ai/ui/elements/<el>'`) or the register-all bundle. (Advanced: host
+// dist/elements/ yourself and call setAutoloaderBasePath('<url>/') before use.)
+//
+// Tag → module is resolved through the generated manifest (filenames don't always
+// equal the tag, and some modules register more than one tag), and modules are
+// fetched relative to THIS module's URL.
+import manifest from './element-manifest.json';
+
+const tagToModule: Record<string, string> = manifest.tags;
+const inFlight = new Set<string>();
+
+// Base = the directory of this module. Computed via string ops on import.meta.url
+// (NOT `new URL('./x', import.meta.url)`, which Vite rewrites into a static-asset
+// glob that resolves to undefined at runtime).
+const BASE = import.meta.url.slice(0, import.meta.url.lastIndexOf('/') + 1);
+
+/** Override where element modules are fetched from (e.g. a CDN). Call before use. */
+let baseOverride: string | null = null;
+export function setAutoloaderBasePath(path: string): void {
+  baseOverride = path.endsWith('/') ? path : path + '/';
+}
+
+async function register(tag: string): Promise<void> {
+  if (customElements.get(tag) || inFlight.has(tag)) return;
+  const file = tagToModule[tag];
+  if (!file) return; // not one of ours
+  inFlight.add(tag);
+  try {
+    await import(/* @vite-ignore */ `${baseOverride ?? BASE}${file}.js`);
+  } catch (err) {
+    inFlight.delete(tag);
+    warnOnce(tag, err);
+  }
+}
+
+// One actionable warning per session (the failure is almost always "imported
+// through a bundler" — see the header note), instead of a silent per-tag error.
+let warned = false;
+function warnOnce(tag: string, err: unknown): void {
+  if (warned) return;
+  warned = true;
+  const msg = (err as { message?: string })?.message ?? String(err);
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[kai-autoloader] could not load "${tag}" (${msg}). The autoloader is a CDN / ` +
+      `static-file tool — load it from a <script type="module" src=".../@kitn.ai/ui/dist/elements/autoloader.js">. ` +
+      `It is NOT importable through a bundler. In a bundled app, register elements with per-element imports ` +
+      `(import '@kitn.ai/ui/elements/<el>') or the register-all bundle (import '@kitn.ai/ui/elements'). To drive ` +
+      `the autoloader from a bundler, host dist/elements/ and call setAutoloaderBasePath('<url>/') before use.`,
+  );
+}
+
+function discover(root: ParentNode | Element): void {
+  const tags = new Set<string>();
+  const self = (root as Element).tagName?.toLowerCase?.();
+  if (self && self in tagToModule && !customElements.get(self)) tags.add(self);
+  root.querySelectorAll?.(':not(:defined)').forEach((el) => {
+    const t = el.tagName.toLowerCase();
+    if (t in tagToModule) tags.add(t);
+  });
+  tags.forEach(register);
+}
+
+/** Start watching `root` (default: the whole document) for undefined kai-* elements. */
+export function startAutoloader(root: ParentNode = document): void {
+  discover(root as Element);
+  new MutationObserver((mutations) => {
+    for (const m of mutations)
+      for (const node of m.addedNodes)
+        if (node.nodeType === 1) discover(node as Element);
+  }).observe(document.documentElement, { childList: true, subtree: true });
+}
+
+// Self-start on import (the <script type="module"> use case). Deferred to a
+// microtask so a consumer that calls setAutoloaderBasePath() right after importing
+// (the advanced bundler-from-CDN path) takes effect before the first discovery pass.
+if (typeof document !== 'undefined') queueMicrotask(() => startAutoloader());