@aparte/core 0.9.0 → 0.10.0

package/dist/types/segments.d.ts

@@ -17,41 +17,88 @@ export interface AparteSegmentBase {
      * insertions and removals.
      */
     index?: number;
-    /** Epoch ms when the segment entered the transcript. */
+    /**
+     * 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. Core
-     * never renders either.
+     * 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.
+     * 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;
-    /**
-     * Extras only the producer of the segment can know — token counts, cost,
-     * compute device. Core writes nothing here: fill it from an app with
-     * `updateSegment(segmentId, { meta })`. Mirrors `AparteMessage.metadata`.
-     */
-    meta?: Record<string, unknown>;
 }
 /** 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;
 }
@@ -63,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';
@@ -187,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'];
 /**
@@ -230,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":"AAAA;;;GAGG;AAMH,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAC9B,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IAEX,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IAEb,kDAAkD;IAClD,WAAW,CAAC,EAAE,OAAO,CAAC;IAkBtB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,MAAM,CAAC,EAAE,mBAAmB,CAAA;KAAE,CAAC;CACrE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,mBAAmB;IAChC,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wCAAwC;AACxC,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtE,+CAA+C;AAC/C,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC5D,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,mDAAmD;AACnD,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,oBAAoB;AACpB,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IACzD,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6CAA6C;AAC7C,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC5D,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;CACzD;AAED,+EAA+E;AAC/E,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC5D,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,OAAO,YAAY,EAAE,cAAc,CAAC;IAC9C;;;OAGG;IACH,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,mBAAmB,GAAG,UAAU,CAAC;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,8EAA8E;AAC9E,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC1D,IAAI,EAAE,QAAQ,CAAC;IACf,yGAAyG;IACzG,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC5D,IAAI,EAAE,UAAU,CAAC;IACjB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB;AAMD,gEAAgE;AAChE,MAAM,WAAW,4BAA6B,SAAQ,iBAAiB;IACnE,IAAI,EAAE,kBAAkB,CAAC;CAC5B;AAED,iCAAiC;AACjC,MAAM,MAAM,aAAa,GACnB,iBAAiB,GACjB,qBAAqB,GACrB,iBAAiB,GACjB,kBAAkB,GAClB,qBAAqB,GACrB,mBAAmB,GACnB,qBAAqB,GACrB,qBAAqB,GACrB,4BAA4B,CAAC;AAEnC,wCAAwC;AACxC,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;AAMtD;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,iBAAiB,GAAG,iBAAiB;IAClF,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,MAAM,GAAG,WAAW,CAAC;IAEzC;;;OAGG;IACH,SAAS,CAAC,IAAI,MAAM,CAAC;IAErB;;;;OAIG;IACH,KAAK,CAAC,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IAE/C;;;;;OAKG;IACH,MAAM,CAAC,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IAEjD;;;OAGG;IACH,OAAO,CAAC,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;CACxC;AAMD,6DAA6D;AAC7D,MAAM,WAAW,8BAA8B;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/dist/utils/segments.d.ts

@@ -27,7 +27,7 @@
  * 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 { AparteSegment } from '../types/index.js';
+import type { AparteSegmentDefaults, AparteSegmentTiming, AparteSegment } from '../types/index.js';
 /**
  * Stamp identity and start time on a segment joining `segments` at the tail.
  *
@@ -38,7 +38,41 @@ import type { AparteSegment } from '../types/index.js';
  * 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): AparteSegment;
+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`.
  *
@@ -76,6 +110,21 @@ export declare function isSegmentSettled(segment: AparteSegment): boolean;
  * 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.
  *
@@ -113,9 +162,7 @@ export declare function segmentDuration(segment: AparteSegment): number | undefi
  *
  * Empty once the segment has settled, so a late write cannot move a final end.
  */
-export declare function stampSegmentActivity(segment: AparteSegment): {
-    endedAt?: number;
-};
+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.
@@ -162,6 +209,29 @@ export declare function isTerminalStatus(status: string | null | undefined): boo
  * 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.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"segments.d.ts","sourceRoot":"","sources":["../../src/utils/segments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AA6BvD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,MAAM,GAClB,aAAa,CAOf;AAED;;;;;;;;;;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,CAaxB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAI1E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAEjF;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;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,IAAI,CAMhE"}
+{"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.9.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.",