@aparte/svelte 0.24.0 → 0.26.0

package/dist/runes/AparteChat.svelte

@@ -0,0 +1,304 @@
+<script lang="ts">
+  import { onMount, tick, untrack } from 'svelte';
+  import { AparteChatHost, aparteGlobalConfig, isAwaitingReply, releaseDeferredHydration, type AparteChatHostBinding, type AparteChatImperativeApi } from '@aparte/core';
+  import type { AparteMessage, AparteSegment, AparteSendEventDetail, AparteActionEventDetail } from '../types.js';
+  import type { AparteChatProps } from './types.js';
+
+  /*
+   * The Svelte 5 chat: the same host, the same markup and the same rules as the
+   * Svelte-4-syntax component, written the way a Svelte 5 app writes components —
+   * `$props`, a bindable `messages`, snippets for the five places for your own markup,
+   * callback props for every event. The orchestration (streaming, branches, the
+   * conversation controller) is core's `AparteChatHost`, bound once on mount.
+   */
+  let {
+    id,
+    messages = $bindable([]),
+    placeholder = 'Type a message...',
+    disabled = false,
+    isTyping = false,
+    typingText,
+    submitOnEnter = true,
+    layoutTransitionMs = 0,
+    centerWhenEmpty = false,
+    loading = false,
+    overlayComposer = false,
+    attachments = false,
+    elicitation = true,
+    class: className = '',
+    style,
+    conversationId = null,
+    config,
+    emptyState,
+    aboveComposer,
+    composer,
+    toolbar,
+    bubble,
+    onmessageSent,
+    onaction,
+    onmessagesChange,
+    onmessageAppended,
+    ontypingChange,
+    onconversationCreated,
+  }: AparteChatProps = $props();
+
+  // A caller-supplied id wins, so `scopeToTargetId` has something to match; otherwise one
+  // that the server render and the browser agree on.
+  const uid = $props.id();
+  const hostId = untrack(() => id) ?? `aparte-chat-${uid}`;
+
+  let rootRef: HTMLElement | undefined = $state();
+  // 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 | undefined = $state();
+  let composerRef: HTMLElement | undefined = $state();
+  let host: AparteChatHost | null = null;
+
+  // The list the transcript draws. Raw, not deep state: the host replaces it whole, and a
+  // proxy around the messages would be handed to core on every read.
+  let internalMessages = $state.raw<AparteMessage[]>(untrack(() => [...messages]));
+  let typingActive = $state(untrack(() => isTyping));
+  // The controller's wait (a conversation fetched through the adapter), or the caller's.
+  let hostLoading = $state(false);
+  const waiting = $derived(loading || hostLoading);
+
+  // Bumped on every config change: the two labels below are locale text.
+  let localeTick = $state(0);
+  const loadingText = $derived.by(() => { void localeTick; return (config ?? aparteGlobalConfig).t('loadingConversation'); });
+  const typingLabel = $derived.by(() => { void localeTick; return typingText ?? (config ?? aparteGlobalConfig).t('typing'); });
+
+  // A parent write to `messages` reaches the transcript — a reassignment, or a push / splice on
+  // a bound $state array — unless it is the host's own emit coming back, current or stale:
+  // applying it rolled back what a non-emitting call (appendMessage) had added since.
+  //
+  // The reports the parent has not handed back yet, oldest first — the rule core's host applies
+  // for the other wrappers (`takeEcho`), here by value AND ids: what comes back is a proxy of the
+  // emitted list — the chat's own in a bare chat, the parent's under `bind:` or when the parent
+  // writes it back into a deep $state (a new proxy each time: Svelte keeps no cache) — and a
+  // proxy the parent mutated in place keeps its identity, not its ids. A report that comes back,
+  // however late, is taken with every older one; any other value is the parent's word and clears
+  // them, so a list the parent restores later (a reopened conversation, an undo) is applied.
+  let pendingEchoes: Array<{ values: object[]; ids: string[] }> = [];
+  const sameIds = (a: readonly (string | undefined)[], b: readonly (string | undefined)[]) =>
+    a.length === b.length && a.every((id, i) => id === b[i]);
+  function takeEcho(value: object, ids: readonly (string | undefined)[]): boolean {
+    const i = pendingEchoes.findIndex((p) => p.values.includes(value) && sameIds(ids, p.ids));
+    if (i < 0) { pendingEchoes = []; return false; }
+    pendingEchoes.splice(0, i + 1);
+    return true;
+  }
+  let lastProp = untrack(() => messages);
+  $effect.pre(() => {
+    const next = messages;
+    // Read every index: a push, a splice or an index write re-runs this, not only a reassignment.
+    const items = [...next];
+    untrack(() => {
+      const ids = items.map((m) => m?.id);
+      if (takeEcho(next, ids)) { lastProp = next; return; }
+      if (next === lastProp && sameIds(ids, internalMessages.map((m) => m.id))) return;
+      lastProp = next;
+      internalMessages = items;
+      if (items.length === 0) host?.clearRenderCache();
+    });
+  });
+
+  // A waiting line the caller drives (the host may turn it off on the first token).
+  let lastTyping = untrack(() => isTyping);
+  $effect.pre(() => {
+    if (isTyping === lastTyping) return;
+    lastTyping = isTyping;
+    typingActive = isTyping;
+  });
+
+  // The conversation id drives the host; the initial one is handed over at bind.
+  let lastConv = untrack(() => conversationId);
+  $effect(() => {
+    const next = conversationId;
+    if (next === lastConv) return;
+    lastConv = next;
+    untrack(() => { void host?.setConversationId(next ?? null); });
+  });
+
+  // The bubbles are rendered by this template; the host reconciles them after each change.
+  $effect(() => {
+    void internalMessages;
+    untrack(() => { if (host) void tick().then(() => host?.syncBubbles()); });
+  });
+
+  // The composer's and the viewport's state are attributes core's elements read. Svelte 5
+  // sets a template attribute as a PROPERTY when the element has one, and `''` through a
+  // boolean setter reads as false, so presence attributes are written here explicitly.
+  function toggleAttr(el: HTMLElement, name: string, on: boolean, value: string) {
+    if (on) el.setAttribute(name, value); else el.removeAttribute(name);
+  }
+  $effect(() => { if (viewportRef) toggleAttr(viewportRef, 'loading', waiting, ''); });
+  $effect(() => {
+    if (!composerRef) return;
+    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?.();
+    onmessageSent?.((event as CustomEvent<AparteSendEventDetail>).detail);
+  }
+
+  // Custom bubble actions bubble to the root as `aparte-action`.
+  function handleAction(event: Event) {
+    onaction?.((event as CustomEvent<AparteActionEventDetail>).detail);
+  }
+
+  onMount(() => {
+    // The elements a server render left waiting are upgraded first: the host talks to them.
+    releaseDeferredHydration(rootRef);
+    const unsubscribeLocale = (config ?? aparteGlobalConfig).subscribe(() => { localeTick += 1; });
+    const binding: AparteChatHostBinding = {
+      hostId,
+      host: rootRef!,
+      viewport: viewportRef ?? null,
+      getMessages: () => internalMessages,
+      setMessages: (m) => { internalMessages = m as AparteMessage[]; },
+      onMessagesChange: (m) => {
+        const list = m as AparteMessage[];
+        const report = { values: [list as object], ids: list.map((x) => x.id) };
+        pendingEchoes.push(report);
+        if (pendingEchoes.length > 64) pendingEchoes.shift();
+        messages = list;
+        onmessagesChange?.(list);
+        // What the effect above will read back — read AFTER the callback, so a write-back made
+        // in it (`onmessagesChange={(m) => (msgs = m)}`) is the proxy recorded, not the one it
+        // replaced. A write-back after an await lands later, as the parent's own word.
+        const stored = untrack(() => messages);
+        report.values.push(stored);
+        lastProp = stored;
+      },
+      onMessageAppended: (m) => { onmessageAppended?.(m as AparteMessage); },
+      onTypingChange: (t) => { typingActive = t; ontypingChange?.(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: (createdId) => { onconversationCreated?.(createdId); },
+      config,
+    });
+    const unbind = host.bind();
+    host.syncBubbles();
+    rootRef?.addEventListener('aparte-action', handleAction);
+    return () => {
+      unsubscribeLocale();
+      rootRef?.removeEventListener('aparte-action', handleAction);
+      unbind();
+      host = null;
+    };
+  });
+
+  // ── Imperative API (bind:this) ──
+  export function appendMessage(m: AparteMessage, options?: { historical?: boolean }) { host?.appendMessage(m, options); }
+  export function updateMessage(messageId: string, u: Partial<AparteMessage>) { host?.updateMessage(messageId, 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(next: string | null): Promise<void> { return host?.setConversationId(next) ?? Promise.resolve(); }
+  export function scrollToBottom() { (viewportRef as unknown as { scrollToBottom?: () => void })?.scrollToBottom?.(); }
+  /** The `<aparte-chat-viewport>` element — the same 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 with the canonical API: a dropped or 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
+  class="aparte-chat-container {className}"
+  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}
+  bind:this={rootRef}
+>
+  <aparte-chat-viewport bind:this={viewportRef} framework-managed="">
+    {#if waiting}
+      <div class="aparte-viewport-loading" aria-hidden="true">
+        <span class="aparte-skeleton aparte-skeleton--rect aparte-viewport-loading__user"></span>
+        <span class="aparte-skeleton aparte-skeleton--text"></span>
+        <span class="aparte-skeleton aparte-skeleton--text"></span>
+        <span class="aparte-skeleton aparte-skeleton--text"></span>
+        <span class="aparte-skeleton aparte-skeleton--text aparte-viewport-loading__last"></span>
+      </div>
+      <span class="aparte-viewport-loading-status aparte-sr-only" role="status">{loadingText}</span>
+    {/if}
+    {#if internalMessages.length === 0 && !waiting}
+      {@render emptyState?.()}
+    {/if}
+    {#each internalMessages as m (m.id)}
+      {#if bubble}
+        {@render bubble(m)}
+      {:else}
+        <aparte-chat-bubble
+          message-id={m.id}
+          data-role={m.role}
+          data-kind={m.compaction ? 'compaction' : undefined}
+          timestamp={m.timestamp}
+          content={m.content}
+          streaming={isAwaitingReply(m) ? '' : null}></aparte-chat-bubble>
+      {/if}
+    {/each}
+    <aparte-chat-status visible={typingActive ? '' : null} text={typingLabel}></aparte-chat-status>
+  </aparte-chat-viewport>
+
+  {#if elicitation}<aparte-elicitation></aparte-elicitation>{/if}
+
+  {@render aboveComposer?.()}
+
+  <aparte-composer bind:this={composerRef} onaparte-send={handleSend}>
+    {#if composer}
+      {@render composer()}
+    {:else}
+      <div class="aparte-composer-shell">
+        {#if attachments}<aparte-composer-attachments></aparte-composer-attachments>{/if}
+        <div class="aparte-composer-row">
+          {#if attachments}<aparte-composer-add-attachment></aparte-composer-add-attachment>{/if}
+          <aparte-composer-input></aparte-composer-input>
+          <aparte-composer-send></aparte-composer-send>
+        </div>
+        {#if toolbar}
+          <aparte-composer-toolbar>{@render toolbar()}</aparte-composer-toolbar>
+        {/if}
+      </div>
+    {/if}
+  </aparte-composer>
+</div>

package/dist/runes/AparteChat.svelte.d.ts

@@ -0,0 +1,32 @@
+import type { AparteMessage, AparteSegment } from '../types.js';
+import type { AparteChatProps } from './types.js';
+declare const AparteChat: import("svelte").Component<AparteChatProps, {
+    appendMessage: (m: AparteMessage, options?: {
+        historical?: boolean;
+    }) => void;
+    updateMessage: (messageId: string, u: Partial<AparteMessage>) => void;
+    updateLastMessage: (content: string, options?: {
+        append?: boolean;
+    }) => void;
+    addSegment: (segment: AparteSegment) => void;
+    updateSegment: (segmentId: string, updates: Partial<AparteSegment>) => void;
+    removeSegment: (segmentId: string) => void;
+    appendToSegment: (segmentId: string, content: string) => void;
+    getMessages: () => AparteMessage[];
+    clearMessages: (options?: {
+        revokeAttachments?: boolean;
+    }) => void;
+    addBranch: (messageId: string) => number;
+    addSiblingOf: (existingId: string, message: AparteMessage) => string | null;
+    truncateFrom: (messageId: string) => void;
+    truncateResponsesAfter: (userMessageId: string) => void;
+    injectTokenStream: (messageId: string, tokens: AsyncIterable<string>) => Promise<void>;
+    stopTokenStream: () => void;
+    setConversationId: (next: string | null) => Promise<void>;
+    scrollToBottom: () => void;
+    getViewport: () => HTMLElement | null;
+    focusInput: () => void;
+    isStreaming: () => boolean;
+}, "messages">;
+type AparteChat = ReturnType<typeof AparteChat>;
+export default AparteChat;

package/dist/runes/AparteSegmentUI.svelte

@@ -0,0 +1,35 @@
+<script lang="ts" generics="T extends AparteSegmentBase">
+  /**
+   * Your own Svelte component for a segment type — one your stream emits, or a built-in such
+   * as `code`. Mounted into each segment like `<AparteToolUI>`; taking the last declaration off
+   * a built-in type gives it back to core's renderer.
+   */
+  import { getAllContexts, untrack, type Snippet } from 'svelte';
+  import { defineMountedSegmentRenderer, overrideSegmentRenderer } from '@aparte/core';
+  import type { AparteConfig, AparteSegmentBase } from '@aparte/core';
+  import { mountSnippet } from './mount-snippet.svelte.js';
+
+  let {
+    type,
+    config,
+    children,
+  }: {
+    /** The segment `type` this draws. */
+    type: T['type'];
+    /** The config to declare it on. Defaults to the global one. */
+    config?: AparteConfig;
+    /** What to draw for one segment, handed its latest state. */
+    children: Snippet<[T]>;
+  } = $props();
+
+  const context = getAllContexts();
+
+  $effect(() => {
+    const segmentType = type;
+    const target = config;
+    return untrack(() => {
+      const renderer = defineMountedSegmentRenderer<T>(segmentType, (host, segment) => mountSnippet(host, () => children, segment, context));
+      return target ? overrideSegmentRenderer(renderer, target) : overrideSegmentRenderer(renderer);
+    });
+  });
+</script>

package/dist/runes/AparteSegmentUI.svelte.d.ts

@@ -0,0 +1,38 @@
+/**
+   * Your own Svelte component for a segment type — one your stream emits, or a built-in such
+   * as `code`. Mounted into each segment like `<AparteToolUI>`; taking the last declaration off
+   * a built-in type gives it back to core's renderer.
+   */
+import { type Snippet } from 'svelte';
+import type { AparteConfig, AparteSegmentBase } from '@aparte/core';
+declare function $$render<T extends AparteSegmentBase>(): {
+    props: {
+        /** The segment `type` this draws. */
+        type: T["type"];
+        /** The config to declare it on. Defaults to the global one. */
+        config?: AparteConfig;
+        /** What to draw for one segment, handed its latest state. */
+        children: Snippet<[T]>;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends AparteSegmentBase> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends AparteSegmentBase>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends AparteSegmentBase>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const AparteSegmentUI: $$IsomorphicComponent;
+type AparteSegmentUI<T extends AparteSegmentBase> = InstanceType<typeof AparteSegmentUI<T>>;
+export default AparteSegmentUI;

package/dist/runes/AparteToolUI.svelte

@@ -0,0 +1,44 @@
+<script lang="ts" generics="I = unknown, R = unknown">
+  /**
+   * Your own Svelte component in a tool call.
+   *
+   * `<AparteToolUI name="get_weather">{#snippet children(tool)}<WeatherCard {tool} />{/snippet}</AparteToolUI>`
+   * draws every `get_weather` call with your snippet for as long as it is mounted, and gives the
+   * calls back to core's row when it unmounts. The snippet is mounted with the contexts of where
+   * you put the declaration, so `getContext` reads what your app set there.
+   *
+   * Underneath it is core's `overrideToolRenderer` + `defineMountedToolRenderer`. Nothing is
+   * declared in a server render (`$effect` runs in the browser only); the cards are drawn there.
+   */
+  import { getAllContexts, untrack, type Snippet } from 'svelte';
+  import { aparteGlobalConfig, defineMountedToolRenderer } from '@aparte/core';
+  import type { AparteConfig, AparteToolCallView, AparteToolMatcher } from '@aparte/core';
+  import { mountSnippet } from './mount-snippet.svelte.js';
+
+  let {
+    name,
+    config,
+    children,
+  }: {
+    /** The tool this draws: a name, a `RegExp`, or `'*'` for every tool. */
+    name: AparteToolMatcher;
+    /** The config to declare it on. Defaults to the global one. */
+    config?: AparteConfig;
+    /** What to draw for one call: its id, name, input, status, result and the rest. */
+    children: Snippet<[AparteToolCallView<I, R>]>;
+  } = $props();
+
+  // Readable only while the component initialises.
+  const context = getAllContexts();
+  // The matcher by its text: a `RegExp` literal in a template is a new object on every render.
+  const key = $derived(typeof name === 'string' ? name : String(name));
+
+  $effect(() => {
+    void key;
+    const target = config ?? aparteGlobalConfig;
+    return untrack(() => target.overrideToolRenderer(
+      name,
+      defineMountedToolRenderer((host, view) => mountSnippet(host, () => children as Snippet<[AparteToolCallView]>, view, context)),
+    ));
+  });
+</script>

package/dist/runes/AparteToolUI.svelte.d.ts

@@ -0,0 +1,44 @@
+/**
+   * Your own Svelte component in a tool call.
+   *
+   * `<AparteToolUI name="get_weather">{#snippet children(tool)}<WeatherCard {tool} />{/snippet}</AparteToolUI>`
+   * draws every `get_weather` call with your snippet for as long as it is mounted, and gives the
+   * calls back to core's row when it unmounts. The snippet is mounted with the contexts of where
+   * you put the declaration, so `getContext` reads what your app set there.
+   *
+   * Underneath it is core's `overrideToolRenderer` + `defineMountedToolRenderer`. Nothing is
+   * declared in a server render (`$effect` runs in the browser only); the cards are drawn there.
+   */
+import { type Snippet } from 'svelte';
+import type { AparteConfig, AparteToolCallView, AparteToolMatcher } from '@aparte/core';
+declare function $$render<I = unknown, R = unknown>(): {
+    props: {
+        /** The tool this draws: a name, a `RegExp`, or `'*'` for every tool. */
+        name: AparteToolMatcher;
+        /** The config to declare it on. Defaults to the global one. */
+        config?: AparteConfig;
+        /** What to draw for one call: its id, name, input, status, result and the rest. */
+        children: Snippet<[AparteToolCallView<I, R>]>;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<I = unknown, R = unknown> {
+    props(): ReturnType<typeof $$render<I, R>>['props'];
+    events(): ReturnType<typeof $$render<I, R>>['events'];
+    slots(): ReturnType<typeof $$render<I, R>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <I = unknown, R = unknown>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<I, R>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<I, R>['props']>, ReturnType<__sveltets_Render<I, R>['events']>, ReturnType<__sveltets_Render<I, R>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<I, R>['bindings']>;
+    } & ReturnType<__sveltets_Render<I, R>['exports']>;
+    <I = unknown, R = unknown>(internal: unknown, props: ReturnType<__sveltets_Render<I, R>['props']> & {}): ReturnType<__sveltets_Render<I, R>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any>['bindings']>;
+}
+declare const AparteToolUI: $$IsomorphicComponent;
+type AparteToolUI<I = unknown, R = unknown> = InstanceType<typeof AparteToolUI<I, R>>;
+export default AparteToolUI;

package/dist/runes/AparteUi.svelte

@@ -0,0 +1,68 @@
+<script lang="ts">
+  import { onMount, untrack } from 'svelte';
+  import { applyElementProps, APARTE_DEFAULT_UI_EVENTS } from '@aparte/core';
+
+  /**
+   * Mounts any element by tag name, sets its props and forwards its events — for an element
+   * aparté does not wrap (a plugin's, or one of yours). Svelte 5: props and a callback prop.
+   */
+  let {
+    name,
+    props = {},
+    events,
+    onelementEvent,
+  }: {
+    /** The custom element tag name (e.g. 'aparte-model-selector'). */
+    name: string;
+    /** Props to apply. Keys starting with `--` become CSS variables. */
+    props?: Record<string, unknown>;
+    /** Which custom events to forward. Defaults to `APARTE_DEFAULT_UI_EVENTS`. */
+    events?: string[];
+    /** Called with the element's own CustomEvent for every forwarded event. */
+    onelementEvent?: (event: CustomEvent) => void;
+  } = $props();
+
+  let hostEl: HTMLElement | undefined = $state();
+  let el = $state.raw<HTMLElement | null>(null);
+
+  // The element is created anew when the tag or the forwarded event set changes; a fresh
+  // inline `events` array with the same names does not recreate it.
+  const eventsKey = $derived((events ?? APARTE_DEFAULT_UI_EVENTS).join('|'));
+
+  let mounted = $state(false);
+  onMount(() => { mounted = true; });
+
+  $effect(() => {
+    if (!mounted || !hostEl) return;
+    const tag = name;
+    const names = eventsKey.split('|');
+    const created = document.createElement(tag);
+    const listener = (e: Event) => onelementEvent?.(e as CustomEvent);
+    for (const ev of names) created.addEventListener(ev, listener);
+    untrack(() => applyElementProps(created, props));
+    hostEl.appendChild(created);
+    el = created;
+    return () => {
+      for (const ev of names) created.removeEventListener(ev, listener);
+      created.remove();
+      if (el === created) el = null;
+    };
+  });
+
+  $effect(() => {
+    const current = el;
+    const next = props;
+    if (current) applyElementProps(current, next);
+  });
+
+  /** The mounted element — the same contract as `AparteUiHandle` on all four wrappers. */
+  export function getElement<T extends HTMLElement = HTMLElement>(): T | null {
+    return el as T | null;
+  }
+  export function callMethod<T = unknown>(methodName: string, ...args: unknown[]): T | undefined {
+    const fn = (el as unknown as Record<string, unknown>)?.[methodName];
+    return (typeof fn === 'function' ? (fn as (...a: unknown[]) => unknown).apply(el, args) : undefined) as T | undefined;
+  }
+</script>
+
+<span bind:this={hostEl} style="display: contents"></span>

package/dist/runes/AparteUi.svelte.d.ts

@@ -0,0 +1,16 @@
+type $$ComponentProps = {
+    /** The custom element tag name (e.g. 'aparte-model-selector'). */
+    name: string;
+    /** Props to apply. Keys starting with `--` become CSS variables. */
+    props?: Record<string, unknown>;
+    /** Which custom events to forward. Defaults to `APARTE_DEFAULT_UI_EVENTS`. */
+    events?: string[];
+    /** Called with the element's own CustomEvent for every forwarded event. */
+    onelementEvent?: (event: CustomEvent) => void;
+};
+declare const AparteUi: import("svelte").Component<$$ComponentProps, {
+    getElement: <T extends HTMLElement = HTMLElement>() => T | null;
+    callMethod: <T = unknown>(methodName: string, ...args: unknown[]) => T | undefined;
+}, "">;
+type AparteUi = ReturnType<typeof AparteUi>;
+export default AparteUi;

package/dist/runes/SnippetHost.svelte

@@ -0,0 +1,11 @@
+<script lang="ts" generics="V">
+  /**
+   * One snippet, drawn with one value — what `<AparteToolUI>` and `<AparteSegmentUI>` mount
+   * into each element core hands them. Internal: not exported.
+   */
+  import type { Snippet } from 'svelte';
+
+  let { snippet, value }: { snippet: Snippet<[V]>; value: V } = $props();
+</script>
+
+{@render snippet(value)}

package/dist/runes/SnippetHost.svelte.d.ts

@@ -0,0 +1,32 @@
+/**
+   * One snippet, drawn with one value — what `<AparteToolUI>` and `<AparteSegmentUI>` mount
+   * into each element core hands them. Internal: not exported.
+   */
+import type { Snippet } from 'svelte';
+declare function $$render<V>(): {
+    props: {
+        snippet: Snippet<[V]>;
+        value: V;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<V> {
+    props(): ReturnType<typeof $$render<V>>['props'];
+    events(): ReturnType<typeof $$render<V>>['events'];
+    slots(): ReturnType<typeof $$render<V>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <V>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<V>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<V>['props']>, ReturnType<__sveltets_Render<V>['events']>, ReturnType<__sveltets_Render<V>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<V>['bindings']>;
+    } & ReturnType<__sveltets_Render<V>['exports']>;
+    <V>(internal: unknown, props: ReturnType<__sveltets_Render<V>['props']> & {}): ReturnType<__sveltets_Render<V>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const SnippetHost: $$IsomorphicComponent;
+type SnippetHost<V> = InstanceType<typeof SnippetHost<V>>;
+export default SnippetHost;