@aparte/core 0.8.0 → 0.10.0

package/dist/types/segments.d.ts

@@ -10,16 +10,95 @@ export interface AparteSegmentBase {
     type: string;
     /** Whether segment is currently being streamed */
     isStreaming?: boolean;
+    /** Id of the message this segment belongs to. Stamped on insertion. */
+    messageId?: string;
+    /**
+     * Position in the owning message's `segments[]`, maintained across
+     * insertions and removals.
+     */
+    index?: number;
+    /**
+     * Extras the producer of the segment knows — token counts, cost, compute
+     * device — plus `aparte`, the one sub-object core writes.
+     *
+     * Everything except `meta.aparte` is yours: fill it with
+     * `updateSegment(segmentId, { meta })`, which MERGES rather than replaces.
+     * Mirrors `AparteMessage.metadata`.
+     */
+    meta?: Record<string, unknown> & {
+        aparte?: AparteSegmentTiming;
+    };
+}
+/**
+ * What core measured about a segment. Lives in `meta.aparte`, not on the segment.
+ *
+ * These two were first-class fields, and moving them is not tidying. **No protocol
+ * carries a timestamp on a content block** — verified rather than assumed: Anthropic's
+ * blocks have none (and neither does the message), OpenAI's `output_text` part is
+ * `{annotations, logprobs, text, type}` with `created_at` on the item above it, and the
+ * AI SDK's `UIMessage.parts` have none either. What the AI SDK does have is a metadata
+ * bag whose canonical example is literally `{ createdAt, model, totalTokens }` — at the
+ * message level. A per-block `id` has industry precedent; per-block time has none.
+ *
+ * So this is a **local measurement**, and the shape says so. It stays typed — the bag is
+ * where it belongs, opacity is not part of the deal — and it is namespaced under
+ * `aparte` because `meta` is the consumer's: a flat `startedAt` there would collide
+ * with a key of their own.
+ *
+ * Core reads it through {@link segmentDuration} and {@link isSegmentSettled}; it never
+ * renders either number.
+ */
+export interface AparteSegmentTiming {
+    /** Epoch ms when the segment entered a LIVE transcript. Absent for history. */
+    startedAt?: number;
+    /**
+     * Epoch ms when content last arrived on this segment.
+     *
+     * It ADVANCES while the segment streams and freezes when the segment settles, so
+     * `endedAt - startedAt` is a live duration during a turn and a final one after it
+     * — ask `isSegmentSettled(segment)` which you are looking at.
+     *
+     * Why not simply "when it finished": the two obvious rules are both wrong, and
+     * measurably. Closing at the end of the turn makes a reasoning block span the
+     * whole answer that followed it (2s of thinking before a 20s reply reads "22s").
+     * Closing when the next segment opens is the same error, smaller — a gap of ten
+     * seconds before the next segment is counted as thinking, while the person
+     * watching knows nothing happened. The last delta is the only moment the segment
+     * itself can vouch for.
+     */
+    endedAt?: number;
 }
 /** Text segment - plain text content */
 export interface AparteTextSegment extends AparteSegmentBase {
     type: 'text';
     content: string;
 }
+/**
+ * Field defaults for one segment TYPE, merged when a segment enters a message.
+ *
+ * A record and not a `Partial<AparteSegment>` on purpose: the type key is a string,
+ * a consumer's own segment type is as valid as a built-in one, and its fields cannot
+ * be known here. What CANNOT be defaulted is identity — `id`, `type`, `messageId`,
+ * `index`, `startedAt`, `endedAt` are refused, because a default `id` would give
+ * every segment in a conversation the same one.
+ */
+export type AparteSegmentDefaults = Readonly<Record<string, unknown>>;
 /** Thinking/reasoning segment - collapsible */
 export interface AparteThinkingSegment extends AparteSegmentBase {
     type: 'thinking';
     content: string;
+    /**
+     * Open the block. **Absent means CLOSED** — a reasoning block is a disclosure,
+     * and the reader opens it.
+     *
+     * It used to be the other way round: absent meant open, and core's own parser
+     * emitted `collapsed: false` on every block it produced, so a reasoning block
+     * stayed unfolded for the whole conversation and buried the answer under it. No
+     * assistant on the market does that — the content is behind a click, streaming
+     * or settled.
+     *
+     * `false` is still how you open one on purpose. Only ABSENT changed meaning.
+     */
     collapsed?: boolean;
     label?: string;
 }
@@ -31,56 +110,6 @@ export interface AparteCodeSegment extends AparteSegmentBase {
     filename?: string;
     showLineNumbers?: boolean;
 }
-/** Diff segment - before/after code comparison */
-export interface AparteDiffSegment extends AparteSegmentBase {
-    type: 'diff';
-    filename?: string;
-    hunks: AparteDiffHunk[];
-}
-export interface AparteDiffHunk {
-    oldStart: number;
-    newStart: number;
-    lines: AparteDiffLine[];
-}
-export interface AparteDiffLine {
-    type: 'add' | 'remove' | 'context';
-    content: string;
-}
-/** Terminal/console segment - command execution */
-export interface AparteTerminalSegment extends AparteSegmentBase {
-    type: 'terminal';
-    command?: string;
-    output?: string;
-    exitCode?: number;
-    isRunning?: boolean;
-}
-/** File tree segment - directory structure */
-export interface AparteFileTreeSegment extends AparteSegmentBase {
-    type: 'file-tree';
-    files: AparteFileNode[];
-    title?: string;
-}
-export interface AparteFileNode {
-    name: string;
-    path: string;
-    type: 'file' | 'directory';
-    children?: AparteFileNode[];
-    status?: 'added' | 'modified' | 'deleted';
-}
-/** Image segment */
-export interface AparteImageSegment extends AparteSegmentBase {
-    type: 'image';
-    url: string;
-    alt?: string;
-    caption?: string;
-}
-/** Preview/iframe segment */
-export interface ApartePreviewSegment extends AparteSegmentBase {
-    type: 'preview';
-    url: string;
-    title?: string;
-    height?: number;
-}
 /** Error segment */
 export interface AparteErrorSegment extends AparteSegmentBase {
     type: 'error';
@@ -155,7 +184,7 @@ export interface ApartePipelineWaitingSegment extends AparteSegmentBase {
     type: 'pipeline-waiting';
 }
 /** All built-in segment types */
-export type AparteSegment = AparteTextSegment | AparteThinkingSegment | AparteCodeSegment | AparteDiffSegment | AparteTerminalSegment | AparteFileTreeSegment | AparteImageSegment | ApartePreviewSegment | AparteErrorSegment | AparteProgressSegment | AparteCustomSegment | AparteToolCallSegment | AparteArtifactSegment | ApartePipelineWaitingSegment;
+export type AparteSegment = AparteTextSegment | AparteThinkingSegment | AparteCodeSegment | AparteErrorSegment | AparteProgressSegment | AparteCustomSegment | AparteToolCallSegment | AparteArtifactSegment | ApartePipelineWaitingSegment;
 /** Segment type discriminator values */
 export type AparteSegmentType = AparteSegment['type'];
 /**
@@ -198,6 +227,29 @@ export interface AparteSegmentRenderer<T extends AparteSegmentBase = AparteSegme
      * so the MutationObserver (childList) doesn't fire and scroll stays stable.
      */
     update?(element: HTMLElement, segment: T): void;
+    /**
+     * Optional: re-read the CONFIG-DERIVED text of an already-rendered segment —
+     * an icon from the icon provider, a label from the locale.
+     *
+     * Called when the config changes (a language switch, a new icon set), on every
+     * segment already on screen. Bound by the same rule as `update()`: **must not
+     * add or remove child nodes** — only attributes and textContent — so the
+     * viewport's childList observer stays quiet and scroll does not move.
+     *
+     * This exists because the obvious alternative does not work. Re-rendering the
+     * segments container to pick up a new locale destroys state the DOM owns and the
+     * segment data does not: a mounted sandboxed artifact preview, a reasoning block
+     * the reader expanded by clicking `<summary>` (which never writes back to
+     * `collapsed`), scroll position inside a long terminal, the focus on an
+     * Approve/Reject gate, and the buffered lookahead of the incremental Markdown
+     * parser mid-stream. It also fires container-wide childList mutations, which is
+     * exactly what the rule above forbids.
+     *
+     * Implement it only if the rendered output contains text or icons that came from
+     * the config. A renderer whose chrome is entirely its own data — `progress`,
+     * `text` — correctly does not, exactly as it does not implement `update()`.
+     */
+    relabel?(element: HTMLElement, segment: T): void;
     /**
      * Optional: Cleanup when segment is removed
      * @param element - The DOM element being removed

package/dist/types/segments.d.ts.map

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

package/dist/utils/segments.d.ts

@@ -0,0 +1,244 @@
+/**
+ * What a segment knows about itself — stamped in one place.
+ *
+ * A segment carried `id`, `type` and `isStreaming` and nothing else, while the
+ * message one level up already had a `timestamp`, a `usage` and a `metadata` bag.
+ * Three places in this repo paid for the gap: `render(segment)` takes one argument
+ * so a custom renderer could not learn its message, `aparte-terminal-run` shipped a
+ * `segmentId` nobody could resolve, and the artifact renderer fabricated a message
+ * id to slip past a consumer dedupe keyed on a pair it did not have.
+ *
+ * **Why the stamp lives here and not in `AparteStreamParser`.** The parser looked
+ * like the right owner — both agent loops share it, so parity would be free. It is
+ * the wrong one. `tool_call` segments are built by the client and the stream
+ * adapter (three sites), `pipeline-waiting` by two more, and `prefixSegments` by the
+ * app itself: stamping in the parser would have left a TOOL CALL — the single most
+ * useful duration in the whole transcript — with no measurement at all. Worse, the
+ * parser's own `segmentCounter` would have produced a wrong index: it is recreated
+ * on every `turn-start`, while a tool round-trip appends to the SAME message across
+ * turns, so one message would hold two segments at index 0, silently.
+ *
+ * A segment can only reach a transcript one way — through `addSegment` — and there
+ * are exactly two owners of the array behind it: `aparte-chat-viewport` (native) and
+ * `aparte-chat-host` (framework-managed). Both call these functions; nothing else
+ * writes those fields. `pnpm check:segment-stamp` keeps it that way, because two
+ * owners is exactly the shape of the forgotten-sibling bug this repo keeps finding.
+ *
+ * Everything here is pure and DOM-free, so a consumer can test their own wiring in
+ * Node — the introspectability half of the reachability rule.
+ */
+import type { AparteSegmentDefaults, AparteSegmentTiming, AparteSegment } from '../types/index.js';
+/**
+ * Stamp identity and start time on a segment joining `segments` at the tail.
+ *
+ * Returns a new object; the caller's segment is never mutated — the viewport hands
+ * the same segment object to the repository AND to the bubble, so mutating one is
+ * action at a distance (a bug this repo has already paid for in `appendToSegment`).
+ *
+ * A value already present is never overwritten, so a segment rehydrated from a
+ * consumer's storage keeps the numbers it was persisted with.
+ */
+export declare function stampSegmentOnInsert(segments: readonly AparteSegment[], segment: AparteSegment, messageId: string, defaults?: AparteSegmentDefaults): AparteSegment;
+/**
+ * A segment arriving from STORAGE or a server, rather than starting now.
+ *
+ * The counterpart of {@link stampSegmentOnInsert}, and the reason it exists: the two
+ * are not the same act, and treating them as one made the library invent history.
+ * `stampSegmentOnInsert` ran on every arrival path including a reload, so a
+ * conversation from three weeks ago came back claiming each of its segments had
+ * started this second — while THREE other load paths did not stamp at all, so the same
+ * stored conversation produced different numbers depending on the mode and on whether
+ * a branch tree had been saved. Not a lie so much as an incoherence.
+ *
+ * What it writes, and why each:
+ *
+ *  - `messageId` and `index` are **recomputed**, not preserved. They are derivable
+ *    facts about the array this segment is joining, so a stored value can only
+ *    contradict it — and no protocol persists either (Anthropic's block `index` exists
+ *    only in the streaming envelope, as a position).
+ *  - **no time, ever.** A measurement nobody took is absent, not zero and not now.
+ *    `segmentDuration` already answers `undefined` for that, so a consumer reading
+ *    through the helper degrades correctly.
+ *  - `isStreaming: false`, unconditionally. A persisted stream is dead: restoring one
+ *    with `isStreaming: true` would render a caret forever, and — through
+ *    `openSegmentIds`, which reads exactly this flag — would have the next turn-close
+ *    stamp it a brand-new `endedAt`.
+ */
+export declare function adoptSegment(segments: readonly AparteSegment[], segment: AparteSegment, messageId: string): AparteSegment;
+/**
+ * Read core's own measurements off a segment.
+ *
+ * A function rather than a property access because it is read from six places, and
+ * `segment.meta?.aparte` spelled six times is six chances to spell it differently —
+ * which is exactly how this repo's recurring bug starts.
+ */
+export declare function segmentTiming(segment: Pick<AparteSegment, 'meta'>): AparteSegmentTiming | undefined;
+/**
+ * Has this segment settled? The trigger for `endedAt`.
+ *
+ * Exported on purpose: a consumer rendering its own "thought for 8 s" line needs
+ * the same predicate, and a rule buried inside a component method is a rule that
+ * gets re-derived slightly differently somewhere else.
+ *
+ * A segment with no streaming flag at all is NOT settled. That is deliberate: a
+ * reply that arrived whole never had a span to measure, and stamping an `endedAt`
+ * equal to its `startedAt` would dress a zero up as a measurement.
+ */
+export declare function isSegmentSettled(segment: AparteSegment): boolean;
+/**
+ * Move `endedAt` to now while the segment is open; freeze it once it settles.
+ *
+ * `endedAt` is **the moment content last arrived**, and that is the only honest
+ * signal available. Two simpler rules were tried and are wrong, both measurably:
+ *
+ *  - *"ends when the turn ends"* — a reasoning block would then span the whole
+ *    answer that followed it. 2s of thinking before a 20s reply reads "22s". A
+ *    mocked stream hides this (it moves from reasoning to text in milliseconds); a
+ *    real model does not.
+ *  - *"ends when the next segment starts"* — the same error, smaller: if the next
+ *    segment opens ten seconds later, those ten seconds are counted as thinking,
+ *    while the person watching the screen knows perfectly well nothing happened.
+ *
+ * So every update nudges it forward, and the settling update keeps whatever the
+ * last delta left rather than stamping its own arrival time. A segment that settles
+ * having never received an update gets its end then — nothing else is knowable
+ * about it.
+ *
+ * The consequence, stated because it is a contract: `endedAt` is present WHILE a
+ * segment streams, and `endedAt - startedAt` is a live duration that grows. Ask
+ * {@link isSegmentSettled} whether it is final. That is also what a UI wants — the
+ * counter that ticks while a model reasons is the same number, read earlier.
+ */
+export declare function stampSegmentOnUpdate(segment: AparteSegment, updates: Partial<AparteSegment>): Partial<AparteSegment>;
+/**
+ * Merge an update into a segment without one writer erasing the other's `meta`.
+ *
+ * `{ ...segment, ...updates }` is wrong now that `meta` has two writers. A consumer's
+ * `updateSegment(id, { meta: { cost } })` is presentation, not activity, so it passes
+ * through {@link stampSegmentOnUpdate} untouched — and a plain spread would then
+ * replace the whole bag and take `meta.aparte` with it. The measurement would vanish
+ * the first time an app wrote a token count, which is precisely when it matters.
+ *
+ * So the bag is merged one level, and `aparte` inside it merged again. Every site that
+ * folds an update into a segment goes through here — the viewport, the host and the
+ * bubble each had their own spread, which is three chances to fix this twice and miss
+ * once.
+ */
+export declare function mergeSegmentUpdate(segment: AparteSegment, updates: Partial<AparteSegment>): AparteSegment;
+/**
+ * How long this segment took, or `undefined` when that is not knowable yet.
+ *
+ * The five identity/measurement fields are optional because they describe a
+ * LIFECYCLE: a segment built by hand or freshly emitted by the parser has not been
+ * inserted yet, so it has no start, and an open segment has no end. Making them
+ * required would either force every creation site to stamp — six of them, which is
+ * the forgotten-sibling shape this seam exists to prevent — or force a hand-written
+ * literal to invent values the owner then refuses to overwrite.
+ *
+ * The cost of that optionality lands on the reader, and this is what removes it. The
+ * guard it replaces was written three times in this repo before it earned a function:
+ *
+ *     if (!isSegmentSettled(seg) || !seg.startedAt || !seg.endedAt) return;
+ *
+ * — three conditions to get right, and the last two are wrong at epoch 0, where a
+ * valid timestamp is falsy. Nobody streams in 1970, but the test suite sets the clock
+ * to 0 routinely, so the trap was already in the repo waiting for its first victim.
+ *
+ * It deliberately does NOT ask whether the segment is finished: during a turn a
+ * growing duration is exactly what a "thinking…" counter shows. Pair it with
+ * {@link isSegmentSettled} when you need the final number.
+ */
+export declare function segmentDuration(segment: AparteSegment): number | undefined;
+/**
+ * The patch that records "content just arrived on this segment".
+ *
+ * The append paths do not go through {@link stampSegmentOnUpdate} — they rebuild
+ * the segment themselves, for reasons that predate this (the viewport must not
+ * mutate an object the bubble shares; the host coalesces a frame's chunks into one
+ * absolute write). They still have to move `endedAt`, because content arriving IS
+ * the activity it measures. So they spread this in, and the rule stays in one file
+ * — which is not a style preference: `pnpm check:segment-stamp` refused the two
+ * inline `endedAt: Date.now()` this replaced, and it was right to.
+ *
+ * Empty once the segment has settled, so a late write cannot move a final end.
+ */
+export declare function stampSegmentActivity(segment: AparteSegment): Partial<AparteSegment>;
+/**
+ * The update that forwards a parser-emitted segment's content — carrying the fact
+ * that it CLOSED, when it did.
+ *
+ * The parser marks the segments it closes (`</think>`, a closing fence,
+ * `</artifact>`, the opening of the next block). That mark reached nobody: every
+ * forwarding site sent `{ content }` alone, so a finished segment arrived at the
+ * owner looking exactly like a streaming one. The end then had to be inferred from
+ * the end of the TURN, which is what kept a reasoning block reading "Thinking" for
+ * as long as the answer took to stream.
+ *
+ * Five sites forward this way across the two agent loops, which is four too many to
+ * patch by hand — that is how the same rule ends up spelled three different ways.
+ */
+export declare function segmentContentUpdate(segment: AparteSegment): Partial<AparteSegment>;
+/**
+ * Statuses that mean the turn is over, whatever the outcome.
+ *
+ * `error` and `aborted` count: a stopped stream still produced what it produced,
+ * and refusing to close its segments would leave every one of them measuring
+ * forever. `undefined` does NOT count — a message with no status yet has not
+ * finished, and treating "unknown" as "done" would end a segment on its first
+ * render.
+ */
+export declare function isTerminalStatus(status: string | null | undefined): boolean;
+/**
+ * Ids of the segments a finished turn still has to close.
+ *
+ * Where `endedAt` comes from for everything that is not a tool call. Nothing in the
+ * stream says "this thinking block is over": the parser closes its active segment
+ * silently, and both agent loops report the end on the MESSAGE
+ * (`updateMessage({ status: 'completed' })`). So the message's end is the segments'
+ * end, and this says which ones are still waiting for it.
+ *
+ * It returns ids rather than settling the array itself, and that is the point. The
+ * first version did mutate in place — and the browser proved it half-broken: the
+ * model gained its `endedAt` while the RENDERER never learned the segment had
+ * settled, because a silent mutation notifies nobody. Routing each close through
+ * the owner's own `updateSegment` gives one path that stamps the model AND repaints
+ * the bubble, which is also the path `update()` and the incremental Markdown flush
+ * already depend on.
+ *
+ * Already-closed segments are skipped, so reporting a turn finished twice — a
+ * re-render, a branch switch, a reloaded conversation — cannot move an end.
+ */
+export declare function openSegmentIds(segments: readonly AparteSegment[]): string[];
+/**
+ * Adopt every segment of a message arriving from storage or a server.
+ *
+ * The message-level counterpart of {@link adoptSegment}, and the reason it exists as a
+ * function rather than a loop written four times: there are FOUR entry paths for
+ * historical data (`setMessages`, `importTree`, `addMessage`, and the framework host's
+ * own list setter) and they disagreed. One stamped and invented a start, one wrote
+ * straight to the repository, one did nothing, and the host's `appendMessage` — same
+ * name as the viewport's, opposite behaviour — did nothing either. The same stored
+ * conversation therefore produced different numbers depending on the mode and on
+ * whether a branch tree had been saved.
+ *
+ * Always returns a NEW object, even for a message with no segments. That looks like a
+ * missed optimisation and is the invariant of this whole file: the viewport hands the
+ * same object to the repository AND to the framework's list, so sharing one makes the
+ * immediate paint and the coalesced write land on the same string twice. Returning the
+ * caller's message here doubled every streamed reply — caught by the suite that exists
+ * for exactly that bug, within minutes of my writing the shortcut.
+ */
+export declare function adoptMessageSegments<T extends {
+    id: string;
+    segments?: AparteSegment[];
+}>(message: T): T;
+/**
+ * Close the gap a removal left, in place.
+ *
+ * The single place `index` is maintained after the array changes shape. Entries are
+ * REPLACED rather than mutated, for the same shared-object reason as
+ * {@link stampSegmentOnInsert}; a segment already at its correct position is left
+ * alone, so a renumber after an append-only sequence allocates nothing.
+ */
+export declare function renumberSegments(segments: AparteSegment[]): void;
+//# sourceMappingURL=segments.d.ts.map

package/dist/utils/segments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segments.d.ts","sourceRoot":"","sources":["../../src/utils/segments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AA6BnG;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,qBAAqB,GACjC,aAAa,CAWf;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CACxB,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,MAAM,GAClB,aAAa,CAOf;AASD;;;;;;GAMG;AACH,wBAAgB,aAAa,CACzB,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,GACrC,mBAAmB,GAAG,SAAS,CAEjC;AA6CD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAGhE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAChC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAChC,OAAO,CAAC,aAAa,CAAC,CAgBxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAChC,aAAa,CAef;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAI1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAEnF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAMnF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE3E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,EAAE,CAE3E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAA;CAAE,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CASxG;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,IAAI,CAMhE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aparte/core",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "High-performance AI conversation engine - Zero-dependency Web Components",
   "type": "module",
   "//sideEffects": "The BROWSER entry defines the custom elements and imports CSS at module scope, so it must never be tree-shaken; the Node entry (`index.node`) and every other module are pure. Listing them explicitly is what lets a bundler drop the rest — the whole package was implicitly side-effectful before, the only one of the 14 without this field.",