@aparte/svelte 0.23.0 → 0.25.0

package/README.md

@@ -4,6 +4,11 @@ The **Svelte AI chat component** of [aparté](https://github.com/apartejs/aparte
 `<AparteChat>` (Svelte 4 and 5) plus stores (`createAparteChat`, `createAparteClient`, `createConversationManager`) over the
 framework-agnostic web components in `@aparte/core`.
 
+On Svelte 5, import from **`@aparte/svelte/runes`**: the same chat written in runes — snippets,
+`bind:messages`, callback props, and `<AparteToolUI>` to draw a tool call with your own component.
+Tested in CI with Svelte 4 and 5, and in a SvelteKit 2 page rendered on the server and hydrated
+with no mismatch.
+
 **Svelte 4 and Svelte 5**, from the same source. The package ships its `.svelte` files
 under the `svelte` export condition, so **your** compiler builds them — how a Svelte
 component library is meant to be published, and the only arrangement that can serve two

package/dist/AparteChat.svelte

@@ -1,232 +1,306 @@
-<script>import { onMount, onDestroy, tick, createEventDispatcher } from "svelte";
-import { AparteChatHost, aparteGlobalConfig, isAwaitingReply, uuid } from "@aparte/core";
-export let id = void 0;
-export let messages = [];
-export let placeholder = "Type a message...";
-export let disabled = false;
-export let isTyping = false;
-export let typingText = void 0;
-export let submitOnEnter = true;
-export let layoutTransitionMs = 0;
-export let centerWhenEmpty = false;
-export let loading = false;
-let hostLoading = false;
-$: waiting = loading || hostLoading;
-let localeTick = 0;
-let unsubscribeLocale = null;
-const localeText = (_tick, cfg, key) => (cfg ?? aparteGlobalConfig).t(key);
-$: loadingText = localeText(localeTick, config, "loadingConversation");
-$: typingLabel = typingText ?? localeText(localeTick, config, "typing");
-export let overlayComposer = false;
-export let attachments = false;
-export let elicitation = true;
-let className = "";
-export { className as class };
-export let style = void 0;
-export let conversationId = null;
-export let config = void 0;
-export let onmessageSent = void 0;
-export let onaction = void 0;
-export let onmessagesChange = void 0;
-export let onmessageAppended = void 0;
-export let ontypingChange = void 0;
-export let onconversationCreated = void 0;
-const dispatch = createEventDispatcher();
-let hostId = "";
-let rootRef;
-let viewportRef;
-let composerRef;
-let internalMessages = [...messages];
-let typingActive = isTyping;
-let host = null;
-let teardown = null;
-const emitted = /* @__PURE__ */ new WeakSet();
-let lastProp = messages;
-$: if (messages !== lastProp) {
-  lastProp = messages;
-  if (!emitted.has(messages)) {
-    internalMessages = [...messages];
-    if (messages.length === 0) host?.clearRenderCache();
+<script lang="ts">
+  import { onMount, onDestroy, tick, createEventDispatcher } from 'svelte';
+  import { AparteChatHost, aparteGlobalConfig, isAwaitingReply, releaseDeferredHydration, type AparteChatHostBinding, type AparteConfig, type AparteChatImperativeApi, uuid } from '@aparte/core';
+  import type { AparteMessage, AparteSegment, AparteSendEventDetail, AparteActionEventDetail } from './types.js';
+
+  /**
+   * The host element's `id`, and therefore the `targetId` every event this chat
+   * dispatches carries. Generated when omitted — but it used to be generated and
+   * neither accepted nor exposed, which made `scopeToTargetId` unreachable from
+   * this component.
+   */
+  export let id: string | undefined = undefined;
+  export let messages: AparteMessage[] = [];
+  export let placeholder = 'Type a message...';
+  export let disabled = false;
+  export let isTyping = false;
+  export let typingText: string | undefined = undefined;
+  /** When false, Shift+Enter submits and a bare Enter inserts a newline. */
+  export let submitOnEnter = true;
+  /** Freeze viewport spacer recalculation for this many ms after a conv swap. */
+  export let layoutTransitionMs = 0;
+  /**
+   * Opt in to the "centered composer when empty" layout: the composer sits
+   * vertically centered with the `empty-state` slot above it while the list is
+   * empty, then slides to the bottom on the first message (~0.3s). Off by
+   * default — additive.
+   */
+  export let centerWhenEmpty = false;
+  /**
+   * The conversation is on its way: the viewport draws two skeleton turns, the empty
+   * state stays off and the composer is disabled until it lands. The conversation
+   * controller sets this itself while it fetches through your adapter's `loadFull()`;
+   * the prop is for a wait of your own. Off by default.
+   */
+  export let loading = false;
+  // The controller's wait (a conversation fetched through the adapter) OR the consumer's.
+  let hostLoading = false;
+  $: waiting = loading || hostLoading;
+  // Bumped on every config change: the labels below are locale text, and `$:` does not see the
+  // config — a language switch left them in the old language. Passing the tick is what makes
+  // the two statements re-run.
+  let localeTick = 0;
+  let unsubscribeLocale: (() => void) | null = null;
+  const localeText = (_tick: number, cfg: AparteConfig | undefined, key: 'loadingConversation' | 'typing'): string =>
+    (cfg ?? aparteGlobalConfig).t(key);
+  $: loadingText = localeText(localeTick, config, 'loadingConversation');
+  // The status line's word, from the locale like the rest of the chat, unless the prop says.
+  $: typingLabel = typingText ?? localeText(localeTick, config, 'typing');
+  /** Overlay the composer on the transcript: full-column scroll surface, edge-to-edge scrollbar, floating composer. Read when the viewport mounts. */
+  export let overlayComposer = false;
+  /**
+   * Add the file picker + chips strip to the default composer shell. **Off by
+   * default**, because the capability needs a host that consumes the files: an
+   * `AparteClient` inlines them per its `rawFileInject` option, but if you drive
+   * your own loop you must read `event.files` on `messageSent` — otherwise the file
+   * the user deliberately attached is dropped in silence. No effect when you fill
+   * the `composer` slot (drop `<aparte-composer-add-attachment>` and
+   * `<aparte-composer-attachments>` in it yourself).
+   */
+  export let attachments = false;
+  /**
+   * Render the `<aparte-elicitation>` presenter inside the host — on by default, as it
+   * is in `<aparte-chat>`: the built-in approval gate and `requestUserInput()` ask
+   * through it, and it renders nothing until something asks. Pass `false` when you
+   * mount a presenter of your own (`setElicitationPresenter`) or place the element
+   * yourself.
+   */
+  export let elicitation = true;
+  /** Extra class names for the root element (`[data-aparte-chat]`), merged after core's own. */
+  let className = '';
+  export { className as class };
+  /** Inline style for the root element (`[data-aparte-chat]`). */
+  export let style: string | undefined = undefined;
+  /** Active conversation id (loads/persists via the registered AparteConversationManager). */
+  export let conversationId: string | null = null;
+  /**
+   * Instance {@link AparteConfig} for this chat. When set, aparté components
+   * inside resolve THIS config instead of `aparteGlobalConfig`, so
+   * several independently-configured chats can coexist on one page. Omit for the
+   * global config. Read once when the host mounts.
+   */
+  export let config: AparteConfig | undefined = undefined;
+
+  /*
+   * Callback props, called with the payload itself, alongside the events below (#47).
+   * Svelte 5 documents `createEventDispatcher` as deprecated and recommends callback
+   * props; a Svelte 4 consumer keeps `on:` and sees nothing change, a Svelte 5 one
+   * never writes `on:` on a component. Both routes fire for the same occurrence, in
+   * this order: the callback, then the event.
+   */
+  /** User submitted a message from the composer — see `messageSent` below for the append rule. */
+  export let onmessageSent: ((detail: AparteSendEventDetail) => void) | undefined = undefined;
+  /** A custom bubble action (registerBubbleAction) was clicked. */
+  export let onaction: ((detail: AparteActionEventDetail) => void) | undefined = undefined;
+  /** Active path changed — the list to bind back to `messages`. */
+  export let onmessagesChange: ((messages: AparteMessage[]) => void) | undefined = undefined;
+  /** One message was appended. */
+  export let onmessageAppended: ((message: AparteMessage) => void) | undefined = undefined;
+  /** The typing/"thinking" indicator toggled. */
+  export let ontypingChange: ((typing: boolean) => void) | undefined = undefined;
+  /** The host created a conversation id (persistence). */
+  export let onconversationCreated: ((id: string) => void) | undefined = undefined;
+
+  const dispatch = createEventDispatcher<{
+    /**
+     * User submitted a message from the composer. It is **appended to the
+     * thread automatically** (optimistic UI) before this fires — do NOT add it
+     * again (uncontrolled → duplicates; controlled → mirror into your own
+     * `messages`). For side-effects: scroll, analytics, send.
+     */
+    messageSent: AparteSendEventDetail;
+    /** A custom bubble action (registerBubbleAction) was clicked — typed aparte-action. */
+    action: AparteActionEventDetail;
+    /** Active path changed (branch nav/edit/retry/streaming) — bind back to `messages`. */
+    messagesChange: AparteMessage[];
+    messageAppended: AparteMessage;
+    /** The typing/"thinking" indicator toggled (the host flips it off on the first streamed token). */
+    typingChange: boolean;
+    conversationCreated: string;
+  }>();
+
+  // Generated client-side in onMount (below): during SSR this stays empty so the
+  // server and first client render agree on the id — no hydration mismatch.
+  let hostId = '';
+
+  let rootRef: HTMLElement;
+  // The server render carries `defer-hydration` on the root, so core's elements leave the
+  // server's DOM alone until Svelte has it; onMount releases them. The client never draws it:
+  // a client-only render holds nothing, so a slot's component — whose onMount runs before the
+  // chat's — talks to live elements. A hydration may take the server's attribute off as it
+  // claims the root; the release does not wait for that either.
+  const serverRender = typeof window === 'undefined';
+  let viewportRef: HTMLElement;
+  let composerRef: HTMLElement;
+  let internalMessages: AparteMessage[] = [...messages];
+  let typingActive = isTyping;
+  let host: AparteChatHost | null = null;
+  let teardown: (() => void) | null = null;
+
+  // Parent push → internal list, unless it is the host's own report coming back: a parent
+  // that lands late hands back an EARLIER one, and applying it rolled the list back under the
+  // host's next write. The host tells them apart (`takeEcho`), so a list the parent restores
+  // later (a reopened conversation) is not mistaken for one.
+  let lastProp = messages;
+  $: if (messages !== lastProp) {
+    lastProp = messages;
+    if (!host?.takeEcho(messages)) {
+      internalMessages = [...messages];
+      if (messages.length === 0) host?.clearRenderCache();
+    }
   }
-}
-let lastTyping = isTyping;
-$: if (isTyping !== lastTyping) {
-  lastTyping = isTyping;
-  typingActive = isTyping;
-}
-let lastConv = conversationId;
-$: if (conversationId !== lastConv) {
-  lastConv = conversationId;
-  void host?.setConversationId(conversationId ?? null);
-}
-$: if (host && internalMessages) {
-  void tick().then(() => host?.syncBubbles());
-}
-function toggleAttr(el, name, on, value) {
-  if (on) el.setAttribute(name, value);
-  else el.removeAttribute(name);
-}
-$: if (viewportRef) toggleAttr(viewportRef, "loading", waiting, "");
-$: if (composerRef) {
-  composerRef.setAttribute("target", hostId);
-  composerRef.setAttribute("placeholder", placeholder);
-  toggleAttr(composerRef, "disabled", disabled || waiting, "");
-  toggleAttr(composerRef, "submit-on-enter", !submitOnEnter, "false");
-}
-function handleSend(event) {
-  viewportRef?.requestSmoothScroll?.();
-  const detail = event.detail;
-  onmessageSent?.(detail);
-  dispatch("messageSent", detail);
-}
-function handleAction(event) {
-  const detail = event.detail;
-  onaction?.(detail);
-  dispatch("action", detail);
-}
-onMount(() => {
-  unsubscribeLocale = (config ?? aparteGlobalConfig).subscribe(() => {
-    localeTick += 1;
+
+  // Controlled typing indicator (host may flip it off on the first token).
+  let lastTyping = isTyping;
+  $: if (isTyping !== lastTyping) { lastTyping = isTyping; typingActive = isTyping; }
+
+  // Conversation id changes (initial value loaded by the host on bind).
+  let lastConv = conversationId;
+  $: if (conversationId !== lastConv) {
+    lastConv = conversationId;
+    void host?.setConversationId(conversationId ?? null);
+  }
+
+  // Reconcile bubbles after the rendered list changes (host queries the DOM).
+  $: if (host && internalMessages) { void tick().then(() => host?.syncBubbles()); }
+
+  // Composer attributes set imperatively (like Angular's `[attr.x]`), because the
+  // attribute IS the state core's composer parts read. Svelte's custom-element
+  // binding assigns to *properties*; core gained the matching setters in 0.16.12
+  // (before that `placeholder`/`disabled` were getter-only and assigning threw), so
+  // this is now a direct write rather than a way around a crash.
+  function toggleAttr(el: HTMLElement, name: string, on: boolean, value: string) {
+    if (on) el.setAttribute(name, value); else el.removeAttribute(name);
+  }
+  // The viewport's `loading` too: Svelte 5 sets a template attribute as a PROPERTY when
+  // the element has one, and `''` through the setter reads as false — the attribute
+  // never appeared (Svelte 4 set the attribute; the svelte5 example caught the drift).
+  $: if (viewportRef) toggleAttr(viewportRef, 'loading', waiting, '');
+  $: if (composerRef) {
+    composerRef.setAttribute('target', hostId);
+    composerRef.setAttribute('placeholder', placeholder);
+    toggleAttr(composerRef, 'disabled', disabled || waiting, '');
+    toggleAttr(composerRef, 'submit-on-enter', !submitOnEnter, 'false');
+  }
+
+  function handleSend(event: Event) {
+    (viewportRef as unknown as { requestSmoothScroll?: () => void })?.requestSmoothScroll?.();
+    const detail = (event as CustomEvent<AparteSendEventDetail>).detail;
+    onmessageSent?.(detail);
+    dispatch('messageSent', detail);
+  }
+
+  // Custom bubble actions bubble to the root as `aparte-action` — dispatch typed.
+  function handleAction(event: Event) {
+    const detail = (event as CustomEvent<AparteActionEventDetail>).detail;
+    onaction?.(detail);
+    dispatch('action', detail);
+  }
+
+  onMount(() => {
+    // The elements a server render left waiting are upgraded first: the host talks to them.
+    releaseDeferredHydration(rootRef);
+    unsubscribeLocale = (config ?? aparteGlobalConfig).subscribe(() => { localeTick += 1; });
+    // A caller-supplied `id` wins, so `scopeToTargetId` has something to match.
+    hostId = id ?? `aparte-chat-${uuid()}`;
+    // Set the id imperatively (deterministic, like Angular's ngAfterViewInit) rather
+    // than waiting on a reactive re-render of `id={hostId}`; the composer target
+    // reactive block below picks up the same hostId.
+    if (rootRef) rootRef.id = hostId;
+    const binding: AparteChatHostBinding = {
+      hostId,
+      host: rootRef,
+      viewport: viewportRef,
+      getMessages: () => internalMessages,
+      setMessages: (m) => { internalMessages = m as AparteMessage[]; },
+      onMessagesChange: (m) => {
+        onmessagesChange?.(m as AparteMessage[]);
+        dispatch('messagesChange', m as AparteMessage[]);
+      },
+      onMessageAppended: (m) => { onmessageAppended?.(m as AparteMessage); dispatch('messageAppended', m as AparteMessage); },
+      onTypingChange: (t) => { typingActive = t; ontypingChange?.(t); dispatch('typingChange', t); },
+      onStreamingChange: () => { /* exposed via isStreaming() */ },
+      afterRender: (cb) => { void tick().then(cb); },
+      resetComposer: () => (composerRef as unknown as { reset?: () => void })?.reset?.(),
+      onLoadingChange: (on) => { hostLoading = on; },
+    };
+    host = new AparteChatHost(binding, {
+      layoutTransitionMs,
+      conversationId: conversationId ?? null,
+      onConversationCreated: (id) => { onconversationCreated?.(id); dispatch('conversationCreated', id); },
+      config,
+    });
+    teardown = host.bind();
+    host.syncBubbles();
+    rootRef?.addEventListener('aparte-action', handleAction);
   });
-  hostId = id ?? `aparte-chat-${uuid()}`;
-  if (rootRef) rootRef.id = hostId;
-  const binding = {
-    hostId,
-    host: rootRef,
-    viewport: viewportRef,
-    getMessages: () => internalMessages,
-    setMessages: (m) => {
-      internalMessages = m;
-    },
-    onMessagesChange: (m) => {
-      emitted.add(m);
-      onmessagesChange?.(m);
-      dispatch("messagesChange", m);
-    },
-    onMessageAppended: (m) => {
-      onmessageAppended?.(m);
-      dispatch("messageAppended", m);
-    },
-    onTypingChange: (t) => {
-      typingActive = t;
-      ontypingChange?.(t);
-      dispatch("typingChange", t);
-    },
-    onStreamingChange: () => {
-    },
-    afterRender: (cb) => {
-      void tick().then(cb);
-    },
-    resetComposer: () => composerRef?.reset?.(),
-    onLoadingChange: (on) => {
-      hostLoading = on;
-    }
-  };
-  host = new AparteChatHost(binding, {
-    layoutTransitionMs,
-    conversationId: conversationId ?? null,
-    onConversationCreated: (id2) => {
-      onconversationCreated?.(id2);
-      dispatch("conversationCreated", id2);
-    },
-    config
+
+  onDestroy(() => {
+    unsubscribeLocale?.();
+    unsubscribeLocale = null;
+    rootRef?.removeEventListener('aparte-action', handleAction);
+    teardown?.();
+    teardown = null;
+    host = null;
   });
-  teardown = host.bind();
-  host.syncBubbles();
-  rootRef?.addEventListener("aparte-action", handleAction);
-});
-onDestroy(() => {
-  unsubscribeLocale?.();
-  unsubscribeLocale = null;
-  rootRef?.removeEventListener("aparte-action", handleAction);
-  teardown?.();
-  teardown = null;
-  host = null;
-});
-export function appendMessage(m, options) {
-  host?.appendMessage(m, options);
-}
-export function updateMessage(id2, u) {
-  host?.updateMessage(id2, u);
-}
-export function updateLastMessage(content, options) {
-  host?.updateLastMessage(content, options);
-}
-export function addSegment(segment) {
-  host?.addSegment(segment);
-}
-export function updateSegment(segmentId, updates) {
-  host?.updateSegment(segmentId, updates);
-}
-export function removeSegment(segmentId) {
-  host?.removeSegment(segmentId);
-}
-export function appendToSegment(segmentId, content) {
-  host?.appendToSegment(segmentId, content);
-}
-export function getMessages() {
-  return host?.getMessages() ?? internalMessages;
-}
-export function clearMessages(options) {
-  host?.clearMessages(options);
-}
-export function addBranch(messageId) {
-  return host?.addBranch(messageId) ?? 0;
-}
-export function addSiblingOf(existingId, message) {
-  return host?.addSiblingOf(existingId, message) ?? null;
-}
-export function truncateFrom(messageId) {
-  host?.truncateFrom(messageId);
-}
-export function truncateResponsesAfter(userMessageId) {
-  host?.truncateResponsesAfter(userMessageId);
-}
-export function injectTokenStream(messageId, tokens) {
-  return host?.streamTokens(messageId, tokens) ?? Promise.resolve();
-}
-export function stopTokenStream() {
-  host?.stopTokenStream();
-}
-export function setConversationId(id2) {
-  return host?.setConversationId(id2) ?? Promise.resolve();
-}
-export function scrollToBottom() {
-  viewportRef?.scrollToBottom?.();
-}
-export function getViewport() {
-  return viewportRef ?? null;
-}
-export function focusInput() {
-  composerRef?.focus?.();
-}
-export function isStreaming() {
-  return host?.isStreaming ?? false;
-}
-function _assertImperativeParity() {
-  return {
-    appendMessage,
-    updateMessage,
-    updateLastMessage,
-    addSegment,
-    updateSegment,
-    removeSegment,
-    appendToSegment,
-    getMessages,
-    clearMessages,
-    addBranch,
-    addSiblingOf,
-    truncateFrom,
-    truncateResponsesAfter,
-    injectTokenStream,
-    stopTokenStream,
-    setConversationId,
-    scrollToBottom,
-    focusInput,
-    isStreaming,
-    getViewport
-  };
-}
+
+  // ── Imperative API (bind:this on the component) ──
+  export function appendMessage(m: AparteMessage, options?: { historical?: boolean }) { host?.appendMessage(m, options); }
+  export function updateMessage(id: string, u: Partial<AparteMessage>) { host?.updateMessage(id, u); }
+  export function updateLastMessage(content: string, options?: { append?: boolean }) {
+    host?.updateLastMessage(content, options);
+  }
+  export function addSegment(segment: AparteSegment) { host?.addSegment(segment); }
+  export function updateSegment(segmentId: string, updates: Partial<AparteSegment>) {
+    host?.updateSegment(segmentId, updates);
+  }
+  export function removeSegment(segmentId: string) { host?.removeSegment(segmentId); }
+  export function appendToSegment(segmentId: string, content: string) {
+    host?.appendToSegment(segmentId, content);
+  }
+  export function getMessages(): AparteMessage[] { return host?.getMessages() ?? internalMessages; }
+  export function clearMessages(options?: { revokeAttachments?: boolean }) { host?.clearMessages(options); }
+  export function addBranch(messageId: string): number { return host?.addBranch(messageId) ?? 0; }
+  export function addSiblingOf(existingId: string, message: AparteMessage): string | null {
+    return host?.addSiblingOf(existingId, message) ?? null;
+  }
+  export function truncateFrom(messageId: string) { host?.truncateFrom(messageId); }
+  export function truncateResponsesAfter(userMessageId: string) {
+    host?.truncateResponsesAfter(userMessageId);
+  }
+  export function injectTokenStream(messageId: string, tokens: AsyncIterable<string>): Promise<void> {
+    return host?.streamTokens(messageId, tokens) ?? Promise.resolve();
+  }
+  export function stopTokenStream() { host?.stopTokenStream(); }
+  export function setConversationId(id: string | null): Promise<void> {
+    return host?.setConversationId(id) ?? Promise.resolve();
+  }
+  export function scrollToBottom() {
+    (viewportRef as unknown as { scrollToBottom?: () => void })?.scrollToBottom?.();
+  }
+  /**
+   * The `<aparte-chat-viewport>` element — for custom scroll handling, an
+   * IntersectionObserver, etc. Same `getViewport()` accessor on all four
+   * wrappers.
+   */
+  export function getViewport(): HTMLElement | null { return viewportRef ?? null; }
+  export function focusInput() {
+    (composerRef as unknown as { focus?: () => void })?.focus?.();
+  }
+  export function isStreaming(): boolean { return host?.isStreaming ?? false; }
+
+  // Compile-time parity check: Svelte 4 can't generic-annotate `export function`s,
+  // so this never-called factory type-checks that the exported surface matches the
+  // canonical AparteChatImperativeApi. A dropped/mistyped method is a build error.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  function _assertImperativeParity(): AparteChatImperativeApi {
+    return {
+      appendMessage, updateMessage, updateLastMessage, addSegment, updateSegment, removeSegment,
+      appendToSegment, getMessages, clearMessages, addBranch, addSiblingOf, truncateFrom,
+      truncateResponsesAfter, injectTokenStream, stopTokenStream, setConversationId,
+      scrollToBottom, focusInput, isStreaming, getViewport,
+    };
+  }
 </script>
 
 <div
@@ -234,6 +308,7 @@ function _assertImperativeParity() {
   class:aparte-chat-container--auto-center={centerWhenEmpty}
   {style}
   data-aparte-chat
+  {...(serverRender ? { 'defer-hydration': '' } : {})}
   {...(overlayComposer ? { 'overlay-composer': '' } : {})}
   data-aparte-empty={centerWhenEmpty && internalMessages.length === 0 && !waiting ? '' : null}
   id={hostId}