@aparte/core 0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aparté
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @aparte/core
+
+Framework-agnostic AI-chat UI as **vanilla Web Components** — zero runtime dependencies,
+ESM-only, usable in any framework or none.
+
+> 🚧 **Pre-alpha** — not yet published to npm. Part of the
+> [aparté](https://github.com/apartejs/aparte) monorepo.
+
+## Install
+
+```bash
+npm install @aparte/core
+```
+
+## Quick start
+
+```ts
+import '@aparte/core';               // registers the <aparte-*> custom elements
+import '@aparte/core/styles.css';    // theme variables + component styles
+import { registerDefaultRenderers, AparteClient } from '@aparte/core';
+
+registerDefaultRenderers();
+// Drop the shell in your HTML:  <aparte-chat placeholder="Ask anything…"></aparte-chat>
+
+// Give it a provider + transport (see the docs), then construct the client and call
+// .start() — it listens for the composer's events and streams the reply into the
+// conversation. (Without .start(), no listeners are attached and nothing streams.)
+new AparteClient().start();
+```
+
+## What's in it
+
+- **`<aparte-chat>`** — a drop-in shell (viewport + composer), or compose the primitives
+  yourself (`<aparte-chat-viewport>`, `<aparte-composer>`, `<aparte-chat-bubble>`, …).
+- **`AparteClient`** — an optional driver that turns composer events into a streamed reply.
+  Retry / edit fork the conversation into **branches** with a built-in `‹ 1/2 ›` picker.
+- **Transports** — `DirectTransport` (browser → provider, BYOK / local model) or
+  `BackendTransport` (browser → your endpoint, API key stays server-side).
+- **Theming** — restyle everything through `--aparte-*` CSS variables (Light DOM, no forking).
+- **Customization** — icons, render hooks, and a zoned action registry via `AparteConfig`.
+
+Zero runtime dependencies: Markdown, syntax highlighting, etc. are **opt-in** providers you inject.
+ESM-only (CJS consumers use `await import()`).
+
+## Docs
+
+Guides + a generated API reference live in the monorepo under
+[`apps/docs`](https://github.com/apartejs/aparte/tree/main/apps/docs): Getting started, Theming,
+Customization, Conversations &amp; branching, and The agent engine.
+
+## License
+
+MIT

package/dist/client/aparte-client.d.ts

@@ -0,0 +1,326 @@
+import { AparteConfigClass } from '../config/aparte-config.js';
+import type { AparteStreamRunner } from './stream-adapter.js';
+import type { AparteMessage } from '../types/index.js';
+import { AparteChatRequest, AparteChatMessage } from '../types/chat.js';
+/**
+ * Resolves a human-in-the-loop tool approval for a `needsApproval` tool call.
+ * Resolves `{ approved, payload? }`; the `signal` aborts a pending decision.
+ */
+export type AparteToolApprovalResolver = (toolCallId: string, signal: AbortSignal) => Promise<{
+    approved: boolean;
+    payload?: unknown;
+}>;
+/**
+ * Decides how a conversation is compacted: which messages are summarized away
+ * (`drop`) and which are preserved verbatim (`keep`). Pure — no LLM call.
+ *
+ * The default selector drops the whole history (summarize everything, replace
+ * all), which is the built-in behaviour. Inject a budget-aware selector (e.g.
+ * wrapping `@aparte/engine`'s `compactConversation`) so the compaction badge and
+ * the `compact()` action share one selection and only the old turns are sent to
+ * the summarizer — the budget is closed over by the consumer, not core's to know.
+ */
+export type AparteCompactionSelector = (messages: AparteMessage[]) => {
+    keep: AparteMessage[];
+    drop: AparteMessage[];
+};
+/**
+ * Configuration options for AparteClient
+ */
+export interface AparteClientOptions {
+    /**
+     * Function to resolve API keys for a given provider.
+     * Can return a string (key) or a full configuration object.
+     */
+    keyResolver?: (providerId: string) => string | Record<string, string> | Promise<string | Record<string, string> | undefined | null> | undefined | null;
+    /**
+     * Custom human-in-the-loop approval resolver for tools marked
+     * `needsApproval`. Defaults to a global `document` `aparte-tool-decision`
+     * listener (the built-in Approve/Reject gate). Inject this to run multiple
+     * isolated clients on one page, or to drive approval from a headless source
+     * (CLI / webhook) with no DOM.
+     */
+    approvalResolver?: AparteToolApprovalResolver;
+    /**
+     * Custom compaction selection strategy. Defaults to dropping the entire
+     * history (summarize all, replace all — the built-in behaviour). Inject a
+     * budget-aware selector so only old turns are summarized and recent ones are
+     * kept verbatim. See {@link AparteCompactionSelector}.
+     */
+    compactionSelector?: AparteCompactionSelector;
+    /**
+     * Optional headless stream-loop runner. When set, `_streamLoop` delegates the
+     * agentic loop to it and renders via the core adapter
+     * ({@link createStreamAdapter}); when absent, the built-in inline loop runs.
+     * Inject `@aparte/engine`'s `runStreamAgent` here so a backend/cloud path
+     * shares one tested loop — core stays the zero-dep leaf and never imports
+     * engine. Same injection pattern as {@link approvalResolver} /
+     * {@link compactionSelector}. See {@link AparteStreamRunner}.
+     */
+    streamRunner?: AparteStreamRunner;
+    /**
+     * Optional request interceptor to modify the chat request before sending.
+     */
+    requestInterceptor?: (request: AparteChatRequest) => AparteChatRequest | Promise<AparteChatRequest>;
+    /**
+     * Whether to automatically register default segment renderers.
+     * @default true
+     */
+    autoRegister?: boolean;
+    /**
+     * Conversation history strategy:
+     * - 'viewport' (default) — collects completed messages from the viewport
+     * - 'none'               — sends only the current message (original behavior)
+     * - function             — custom: receives viewport messages, returns AparteChatMessage[]
+     */
+    history?: 'viewport' | 'none' | ((viewportMessages: AparteMessage[]) => AparteChatMessage[]);
+    /**
+     * Optional resolver that returns the host element exposing `appendMessage`.
+     * Use this when the default event-bubble walk cannot reach the host
+     * (e.g. Angular re-renders detach the input element mid-flight).
+     *
+     * @example
+     * targetResolver: () => document.querySelector('aparte-chat')
+     */
+    targetResolver?: () => HTMLElement | null;
+    /**
+     * Scope this client to a specific target element id.
+     * When set, the client will only handle `aparte-send`, `aparte-retry`, `aparte-edit`
+     * and `aparte-abort` events whose `detail.targetId` matches this id.
+     * This allows multiple AparteClient instances (one per conversation) to coexist
+     * on the same page without interfering with each other.
+     *
+     * @example
+     * // Two independent conversations:
+     * new AparteClient({ scopeToTargetId: 'chat-left' }).start();
+     * new AparteClient({ scopeToTargetId: 'chat-right' }).start();
+     */
+    scopeToTargetId?: string;
+    /**
+     * Maximum number of agentic tool-call loop turns before the loop is forcibly
+     * stopped and an error segment is shown. Prevents infinite loops.
+     * Individual tools can override this via `AparteTool.maxTurns`.
+     * @default 10
+     */
+    maxTurns?: number;
+    /**
+     * Controls which files attached by the user are injected as raw content
+     * parts in the LLM request.
+     *
+     * - `'all'` (default) — images as base64, text files as code-fenced text
+     * - `'images-only'`   — only images are injected; text/binary documents
+     *   are left for the application layer (e.g. a RAG pipeline) to handle
+     * - `'none'`          — no files are injected as content parts; ALL file
+     *   types (including images) are routed to the application layer. Used
+     *   when images go through a captioning pipeline before RAG ingest, so
+     *   the chat context only ever sees retrieved text — never raw image
+     *   bytes. Saves bytes on every turn and matches the offline-first
+     *   intent (read file once at upload, retrieve text-only forever after).
+     *
+     * Set `'images-only'` when a `requestInterceptor` retrieves relevant
+     * document chunks and injects them as a system message instead, to avoid
+     * flooding the context window with full file contents.
+     */
+    rawFileInject?: 'all' | 'images-only' | 'none';
+    /**
+     * Config this client reads (providers, model selection, tools, system
+     * prompt). Defaults to the global `AparteConfig` singleton. Pass a host's
+     * instance config when scoping a client to one chat among several
+     * (pairs with `scopeToTargetId`).
+     */
+    config?: AparteConfigClass;
+}
+/**
+ * AparteClient
+ *
+ * The "Automatic Transmission" for Aparte.
+ * Connects the UI events (aparte-send) to the AI Providers (chat).
+ * Handles:
+ * - Listening to send events
+ * - Resolving API keys
+ * - Calling the appropriate Provider
+ * - Streaming the response back to the UI
+ * - Tool use: awaiting handlers and re-calling the provider
+ *
+ * @example
+ * ```typescript
+ * const client = new AparteClient({
+ *   keyResolver: (providerId) => process.env[providerId.toUpperCase() + '_KEY']
+ * });
+ * client.start();
+ * ```
+ */
+export declare class AparteClient {
+    private _boundHandler;
+    private _boundAbortHandler;
+    private _boundCompactHandler;
+    private _boundRetryHandler;
+    private _boundEditHandler;
+    private _activeToolControllers;
+    private _isAborted;
+    /** Aborts the in-flight vendor/transport fetch when the user stops a stream. */
+    private _streamController;
+    private options;
+    /** Config read by this client — an instance config, or the global default. */
+    private readonly _config;
+    constructor(options?: AparteClientOptions);
+    /**
+     * Sets up the event listeners.
+     * This is called once in the constructor.
+     */
+    private _setupListeners;
+    /**
+     * Start listening for aparte-send events on the window.
+     */
+    start(): void;
+    /**
+     * Stop listening.
+     */
+    stop(): void;
+    /**
+     * Abort the current streaming response and all active tool calls.
+     * Dispatches `aparte-message-aborted` on the target element.
+     */
+    abort(): void;
+    /**
+     * Human-in-the-loop: wait for an `aparte-tool-decision` event matching this
+     * tool call (dispatched by the built-in Approve/Reject UI or an app-level
+     * approval surface). Resolves `{ approved, payload }` — `approved` is `true`
+     * only on an explicit approve, and `payload` carries any arbitrary data a
+     * custom approval UI attached to the decision (the built-in gate sends
+     * none). The `signal` (an AbortController registered in
+     * `_activeToolControllers`) lets `abort()` cleanly resolve a pending
+     * approval to `{ approved: false }` — there is no timeout, since a human may
+     * take any amount of time to decide.
+     */
+    private _awaitToolDecision;
+    /**
+     * Resolve the auth for a provider: `options.keyResolver` takes precedence,
+     * then the AparteConfig key channel (`setKeyProvider`) so a key registered
+     * there reaches the request. One key source on the happy path.
+     */
+    private _resolveAuth;
+    /**
+     * The shared tail of send / retry / edit: attach the current tools, run the
+     * request interceptor, honour `toolChoice: 'none'`, reset the abort flag,
+     * dispatch `aparte-message-start`, run the agentic `_streamLoop`, then dispatch
+     * `aparte-message-done` or route the error to the lifecycle handler.
+     *
+     * Callers own only their turn-specific prep (target resolution, history
+     * building, appending the assistant placeholder) and hand the fully-built
+     * `messages` here — one place for the provider→interceptor→toolChoice→stream
+     * sequence, so it can't drift between the three entry points.
+     */
+    private _streamTurn;
+    /**
+     * Compact the current conversation: summarize all messages via the AI,
+     * clear the viewport, then inject the summary as a single context message.
+     *
+     * Triggered programmatically or by dispatching `window.dispatchEvent(new CustomEvent('aparte-compact'))`.
+     * Dispatches `aparte-compact-done` on window when complete, or `aparte-compact-error` on failure.
+     */
+    compact(): Promise<void>;
+    /**
+     * Handle aparte-retry — add a sibling branch to the assistant message and re-stream
+     * using the same conversation history minus the retried reply.
+     */
+    /**
+     * Registered tools, gated by capability: only returned when the current model
+     * declares `function_calling` support (else `[]`). Single source for the gate so
+     * send / retry / edit can't drift — the drift is exactly what shipped `tools` on
+     * the initial send while retry/edit correctly omitted them.
+     */
+    private _toolsForCurrentModel;
+    private _handleRetry;
+    /**
+     * Handle aparte-edit — update the user message in place, truncate all subsequent
+     * messages, then re-stream a fresh assistant response.
+     */
+    private _handleEdit;
+    /**
+     * Resolve a target element by id (from event detail.targetId) or via targetResolver / DOM scan.
+     */
+    private _resolveTarget;
+    /**
+     * Resolve an element to a usable render target: itself when it exposes
+     * `appendMessage`, else the viewport it delegates to. The `<aparte-chat>`
+     * shell matches the host selectors/id but owns no `appendMessage` (it forwards
+     * rendering to its `.viewport`), so returning the bare shell would make
+     * send / retry / edit silently no-op. Returns null when neither can render.
+     */
+    private _asRenderTarget;
+    /**
+     * Convert AparteMessage[] to AparteChatMessage[] for re-submission.
+     */
+    private _messagesToChatMessages;
+    private _handleSend;
+    /**
+     * Build the initial messages array, prepending system prompts and conversation history.
+     */
+    private _buildMessages;
+    private _toHistoryMessages;
+    private _extractText;
+    /**
+     * Convert an array of File objects to AparteContentPart[].
+     * - Images → AparteImagePart (base64 data URL)
+     * - Text files (txt, md, json, csv, xml, html, css, js, ts, …) → AparteTextPart
+     *   injected as a fenced block so all models (including local) can read them.
+     * - Other binary files → silently ignored.
+     */
+    private _filesToContentParts;
+    /**
+     * Stream loop: runs one provider.chat() call and repeats if a tool was called.
+     * Maintains a running messages array to inject tool_call / tool_result turns.
+     */
+    /**
+     * Feed one text delta to the Claude-style `<artifact>` XML streamer. Scans for
+     * `<artifact …>` / `</artifact>`, routing chat text through the text parser and
+     * artifact content into a dedicated artifact segment (handling tags split across
+     * deltas). Mutates `xml` in place. Extracted from _streamLoop.
+     */
+    private _feedXmlArtifactDelta;
+    /**
+     * Turn-1 forced tool call. When `toolChoice = { name, input }`
+     * (orchestrator-driven), execute the handler directly instead of consulting
+     * the LLM, render the tool segment, inject the result as `tool_result`, and
+     * strip `toolChoice` for the follow-up turn. Returns the (possibly-updated)
+     * request and whether the loop should skip to the next turn (handler missing
+     * or aborted). Extracted from `_streamLoop`. `messages` is mutated in place.
+     */
+    private _maybeRunSyntheticTool;
+    /**
+     * Handle one `tool_use` stream event from {@link _streamLoop}: the built-in
+     * `create_artifact`, per-tool renderer selection, the human-in-the-loop
+     * approval gate, and running the registered handler (timeout / abort).
+     * Mutates the shared `messages` / `toolCallsThisTurn` history in place and
+     * returns whether the agentic loop should keep going.
+     */
+    private _handleToolUseEvent;
+    private _streamLoop;
+    /**
+     * Delegate `_streamLoop`'s agentic loop to an injected {@link AparteStreamRunner},
+     * rendering its DOM-free events through {@link createStreamAdapter}.
+     * Builds the runner's dependencies from this client's config / provider /
+     * transport; the adapter reproduces the inline loop's `targetElement.*` calls
+     * (validated by the engine `stream-parity` suite). Leading writes (status
+     * streaming, prefix segments) mirror the inline path; the runner's `run-start`
+     * re-asserts `streaming` idempotently.
+     */
+    private _runViaStreamRunner;
+    /**
+     * Updates an existing message or appends a new error if ID lookup fails
+     */
+    private _updateMessage;
+    /**
+     * Gracefully handles errors by updating the current message instead of duplicating it
+     */
+    private _handleLifecycleError;
+    private _dispatchLifecycleEvent;
+    /**
+     * Dispatch the artifact lifecycle (`aparte-artifact-start` / `delta` / `ready`)
+     * on the host bubble element. Idempotent for `start` (fires once per segment id)
+     * and emits `delta` only when the body actually grew. `isFinal=true` fires `ready`.
+     */
+    private _dispatchArtifactLifecycle;
+}
+//# sourceMappingURL=aparte-client.d.ts.map

package/dist/client/aparte-client.d.ts.map

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

package/dist/client/stream-adapter.d.ts

@@ -0,0 +1,197 @@
+/**
+ * stream-adapter.ts — the DOM half of the structured-stream agent loop.
+ *
+ * `@aparte/engine`'s `runStreamAgent` is the headless loop: it emits high-level,
+ * DOM-free run events. This adapter is the other half — it turns each event into
+ * the exact `targetElement.*` calls + CustomEvents that `AparteClient._streamLoop`
+ * performs today, using the **real** `AparteStreamParser` and tool renderers. So
+ * `runStreamAgent` (engine, pure Node) + this adapter (core, DOM) reproduce
+ * `_streamLoop` byte-for-byte.
+ *
+ * DEPENDENCY DIRECTION: `@aparte/core` is the zero-dep leaf — it must NEVER import
+ * `@aparte/engine` (engine peer-deps core; importing back would create a build
+ * cycle). So the run-event contract is **mirrored** here as
+ * {@link AparteStreamRunEvent}, structurally identical to engine's `StreamRunEvent`.
+ * `@aparte/engine`'s `runStreamAgent` emits objects that satisfy this type; a
+ * consumer wires the two together via the injectable
+ * `AparteClientOptions.streamRunner` seam — the same pattern as `approvalResolver`
+ * (HITL) and `compactionSelector`. Keep the two unions in sync by hand.
+ */
+import type { AparteConfigClass } from '../config/aparte-config.js';
+import type { AparteSegment, AparteMessage, AparteStreamEvent } from '../types/index.js';
+import type { AparteUsage, AparteChatRequest } from '../types/chat.js';
+/**
+ * DOM-free run events emitted by `@aparte/engine`'s `runStreamAgent`, mirrored here
+ * so core need not import engine. **Structurally identical** to engine's
+ * `StreamRunEvent` — kept in sync manually (the boundary cost of the zero-dep
+ * leaf). See `packages/engine/src/agent/stream-events.ts` for the source of truth
+ * and the per-event `_streamLoop` mapping notes.
+ */
+export type AparteStreamRunEvent = {
+    type: 'run-start';
+} | {
+    type: 'turn-start';
+} | {
+    type: 'text-delta';
+    delta: string;
+    reduced?: boolean;
+} | {
+    type: 'text-flush';
+} | {
+    type: 'thinking-delta';
+    delta: string;
+} | {
+    type: 'artifact-open';
+    id: string;
+    mimeType: string;
+    kind: string;
+    title: string;
+} | {
+    type: 'artifact-chunk';
+    id: string;
+    content: string;
+} | {
+    type: 'artifact-close';
+    id: string;
+    content: string;
+    inline: boolean;
+} | {
+    type: 'artifact-ready';
+    id: string;
+    mimeType: string;
+    kind: string;
+    title: string;
+    content: string;
+} | {
+    type: 'tool-start';
+    toolCallId: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'tool-awaiting-approval';
+    toolCallId: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'tool-approved';
+    toolCallId: string;
+} | {
+    type: 'tool-rejected';
+    toolCallId: string;
+    reason: string;
+} | {
+    type: 'tool-resolved';
+    toolCallId: string;
+    result: string;
+} | {
+    type: 'tool-aborted';
+    toolCallId: string;
+} | {
+    type: 'turn-limit-exceeded';
+    scope: 'global' | 'tool';
+    limit: number;
+    toolCallId?: string;
+} | {
+    type: 'phase-advance';
+    index: number;
+} | {
+    type: 'run-aborted';
+} | {
+    type: 'run-done';
+    usage?: AparteUsage;
+};
+/** Synchronous, ordered event sink — mirrors engine's `StreamRunEmitter`. */
+export type AparteStreamRunEmitter = (event: AparteStreamRunEvent) => void;
+/**
+ * Options for an injected {@link AparteStreamRunner} — structurally identical to
+ * engine's `StreamRunOptions` (the mirror boundary again). `AparteClient` builds
+ * these from its config/provider/transport and hands them to the runner.
+ */
+export interface AparteStreamRunOptions {
+    messageId: string;
+    baseRequest: AparteChatRequest;
+    /** Calls the transport; returns the structured stream or a plain string. */
+    transportCall: (request: AparteChatRequest) => Promise<AsyncIterable<AparteStreamEvent> | string>;
+    /** Resolves a tool's handler by name (mirrors `AparteConfig.getToolHandler`). */
+    toolLookup: (name: string) => ((call: {
+        id: string;
+        name: string;
+        input: Record<string, unknown>;
+    }, signal: AbortSignal) => Promise<{
+        content: string;
+    }>) | undefined;
+    /** Resolves a tool's loop config by name (maxTurns / needsApproval). */
+    toolConfigLookup?: (name: string) => {
+        maxTurns?: number;
+        needsApproval?: boolean;
+    } | undefined;
+    /** HITL approval resolver for `needsApproval` tools. */
+    approvalResolver?: (toolCallId: string, signal: AbortSignal) => Promise<{
+        approved: boolean;
+        payload?: unknown;
+    }>;
+    /** The DOM adapter (from {@link createStreamAdapter}). */
+    emitter: AparteStreamRunEmitter;
+    /** Single abort signal (the client composes `_isAborted` + the controller). */
+    signal: AbortSignal;
+    maxTurns?: number;
+    toolTimeoutMs?: number;
+    idGen?: (prefix: string) => string;
+}
+/**
+ * A headless structured-stream loop injected via `AparteClientOptions.streamRunner`
+ * — the seam by which a consumer swaps `_streamLoop`'s inline loop for
+ * `@aparte/engine`'s `runStreamAgent` (core stays the zero-dep leaf; it never
+ * imports engine). Structurally identical to `runStreamAgent`; wire it with a
+ * cast at the injection site if the duck-typed shapes don't line up exactly.
+ */
+export type AparteStreamRunner = (opts: AparteStreamRunOptions) => Promise<AparteUsage | undefined>;
+/**
+ * The imperative surface the adapter drives (subset of `AparteChatTargetElement`).
+ * Every method is optional so a partial/mock target degrades gracefully.
+ */
+export interface StreamAdapterTarget {
+    updateMessage?(id: string, updates: Partial<AparteMessage>): void;
+    updateLastMessage?(content: string, options?: {
+        append?: boolean;
+    }): void;
+    addSegment?(segment: AparteSegment): void;
+    updateSegment?(segmentId: string, updates: Partial<AparteSegment>): void;
+    typeName?(text: string): void;
+    setUsage?(id: string, usage: AparteUsage): void;
+    dispatchEvent(event: Event): boolean;
+}
+export interface CreateStreamAdapterOptions {
+    /** The chat target element the events are rendered onto. */
+    target: StreamAdapterTarget;
+    /** Config for tool-renderer lookup + per-tool style injection. */
+    config: AparteConfigClass;
+    /** The streamed assistant message id (carried in run/artifact events). */
+    messageId: string;
+    /**
+     * Code-fence promotion hint (`baseRequest._meta.artifactHint`). When set, the
+     * first `code` segment produced by the text parser is promoted to an artifact
+     * — the one `_streamLoop` mechanism that stays adapter-side (it needs the
+     * parser). Absent for the raw / XML / create_artifact modes.
+     */
+    artifactHint?: {
+        mimeType: string;
+        kind: string;
+    };
+}
+/**
+ * Build the event → DOM adapter for one streamed message. Returns a synchronous
+ * {@link AparteStreamRunEmitter} to hand to `runStreamAgent` as its `emitter`.
+ * Reproduces `_streamLoop`'s `targetElement.*` call sequence exactly (validated
+ * by the engine parity test against the real loop).
+ */
+export declare function createStreamAdapter(opts: CreateStreamAdapterOptions): AparteStreamRunEmitter;
+/**
+ * Bridge a `ReadableStream` (what the transport returns) to the
+ * `AsyncIterable<AparteStreamEvent>` `runStreamAgent` consumes, cancelling the
+ * reader **synchronously** on abort so a user "stop" cuts the in-flight read.
+ * Used by the `_streamLoop` seam when building `transportCall` for an injected
+ * runner. Mirrors `_streamLoop`'s `reader.read()` loop + `reader.cancel()`.
+ */
+export declare function readableToAsyncIterable(stream: ReadableStream<AparteStreamEvent>, signal: AbortSignal): AsyncIterable<AparteStreamEvent>;
+//# sourceMappingURL=stream-adapter.d.ts.map

package/dist/client/stream-adapter.d.ts.map

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