@kitn.ai/ui 0.23.0 → 0.24.0

package/dist/state/stream.d.ts

@@ -1,22 +1,39 @@
-import { ChatMessage, Source } from '../elements/chat-types.js';
+import { ChatMessage, MessagePart, Source } from '../elements/chat-types.js';
 import { ToolPart } from '../components/tool-types.js';
 import { CardEnvelope } from '../primitives/card-contract.js';
 import { AttachmentData } from '../components/attachment-types.js';
 import { ReasoningOpts } from './parts.js';
 /** The one universal contract: a functional-updater setter (React setState shape). */
 export type SetMessages = (updater: (prev: ChatMessage[]) => ChatMessage[]) => void;
+/** Every OBJECT payload a `MessagePart` variant carries. `type`/`raw` are the
+ *  variant's own bookkeeping, not payload; the primitive payloads (`text`,
+ *  `label`, `index`, ...) drop out at `Extract<..., object>`. */
+type PartPayload = Extract<MessagePart extends infer P ? (P extends object ? P[Exclude<keyof P, 'type' | 'raw'>] : never) : never, object>;
+/** Every bag one of these mutators takes: the part payloads plus the options
+ *  bags that are not payloads themselves. */
+type MutatorBag = PartPayload | ReasoningOpts;
+/** `keyof` over a union member-by-member. The bare `keyof (A | B)` is the
+ *  INTERSECTION of their keys, which is the opposite of what this needs. */
+type KeysOf<T> = T extends unknown ? keyof T : never;
+/** `Shape`, but any key that belongs exclusively to a SIBLING bag is a compile
+ *  error. Keys `Shape` never heard of are untouched, so a consumer's own
+ *  superset of a citation still passes — only the mix-ups fail. That is a
+ *  denylist, not an exact type, and deliberately so: boundary point 1. */
+type Unmixed<Shape> = Shape & {
+    [K in Exclude<KeysOf<MutatorBag>, keyof Shape>]?: never;
+};
 /** A fluent builder for one in-flight assistant message. Owns no state. */
 export interface AssistantStream {
     readonly id: string;
     appendText(delta: string): AssistantStream;
-    appendReasoning(delta: string, opts?: ReasoningOpts): AssistantStream;
-    upsertTool(toolCallId: string, patch: Partial<ToolPart>): AssistantStream;
+    appendReasoning(delta: string, opts?: Unmixed<ReasoningOpts>): AssistantStream;
+    upsertTool(toolCallId: string, patch: Unmixed<Partial<ToolPart>>): AssistantStream;
     /** Adds a card, or REPLACES the existing one with the same `envelope.id`. A
      *  model that revises a card mid-turn re-sends the whole envelope, so a second
      *  call with a known id revises that card in place rather than rendering a
      *  second copy of it. See `upsertCardPart`. */
     addCard(envelope: CardEnvelope): AssistantStream;
-    addSource(source: Source): AssistantStream;
+    addSource(source: Unmixed<Source>): AssistantStream;
     addFile(attachment: AttachmentData): AssistantStream;
     done(): void;
     abort(reason?: string): void;
@@ -26,3 +43,4 @@ export declare function createAssistantStream(set: SetMessages, init?: Partial<C
 /** Wrap a stream so `onSettle` fires on done/abort (used to toggle a `loading` flag).
  *  Preserves the fluent chain by returning the wrapper from every mutator. */
 export declare function onStreamSettled(inner: AssistantStream, onSettle: () => void): AssistantStream;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitn.ai/ui",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "nx": {
     "name": "ui",
     "targets": {
@@ -165,16 +165,16 @@
     "build:subpath-dts": "node scripts/emit-subpath-dts.mjs",
     "verify:card-validation": "node scripts/gen-card-validation-schemas.mjs --check",
     "verify:consumer": "node scripts/verify-consumer-sideeffects.mjs",
-    "verify:dts": "node scripts/verify-dts-boundaries.mjs",
+    "verify:dts": "node scripts/verify-dts-boundaries.mjs --self-test && node scripts/verify-dts-boundaries.mjs",
     "verify:elements-bundle": "node scripts/verify-elements-bundle.mjs --self-test && node scripts/verify-elements-bundle.mjs",
     "verify:dts:consumer": "node scripts/verify-dts-consumer.mjs",
-    "verify:generated": "node scripts/verify-generated-sync.mjs",
-    "verify:quarantine": "node scripts/verify-quarantine.mjs",
+    "verify:generated": "node scripts/verify-generated-sync.mjs --self-test && node scripts/verify-generated-sync.mjs",
+    "verify:quarantine": "node scripts/verify-quarantine.mjs --self-test && node scripts/verify-quarantine.mjs",
     "verify:react-wrappers": "node scripts/verify-react-wrappers.mjs --self-test && node scripts/verify-react-wrappers.mjs",
     "verify:scaffold": "node scripts/verify-scaffold-compiles.mjs",
-    "verify:schemas": "node scripts/verify-schemas-exported.mjs",
+    "verify:schemas": "node scripts/verify-schemas-exported.mjs --self-test && node scripts/verify-schemas-exported.mjs",
     "verify:shader-lazy": "node scripts/verify-shader-lazy.mjs --self-test && node scripts/verify-shader-lazy.mjs",
-    "verify:solid-coverage": "node scripts/verify-solid-coverage.mjs",
+    "verify:solid-coverage": "node scripts/verify-solid-coverage.mjs --self-test && node scripts/verify-solid-coverage.mjs",
     "verify:tool-schemas": "node scripts/verify-tool-schemas.mjs",
     "verify:ssr": "node scripts/verify-ssr-imports.mjs && node scripts/verify-ssr-render.mjs",
     "verify:ssr:imports": "node scripts/verify-ssr-imports.mjs",

package/src/state/stream.ts

@@ -8,6 +8,93 @@ import { appendReasoningPart, appendTextPart, upsertCardPart, upsertToolPart, ty
 /** The one universal contract: a functional-updater setter (React setState shape). */
 export type SetMessages = (updater: (prev: ChatMessage[]) => ChatMessage[]) => void;
 
+/* --------------------------------------------------------------------------
+ * Bag exclusivity: why the mutators below do not just take their payload type.
+ *
+ * `Source`, `Partial<ToolPart>` and `ReasoningOpts` are WEAK types — not one
+ * required field between them — and TypeScript only excess-property-checks
+ * OBJECT LITERALS. Hand a mutator a VARIABLE and that check never runs, so any
+ * bag sharing a single optional key name flows straight in. `addSource(source:
+ * Source)` therefore accepted an `AttachmentData` and a `CardEnvelope`, and
+ * `addFile(a) { inner.addSource(a); }` compiled clean at exit 0 while writing a
+ * file payload into a `source` part. Nine such pairs existed across these three
+ * bags and not one of them was a type error; `./stream-types.test.ts` pins all
+ * nine, and fails with nine "Unused '@ts-expect-error'" if this guard is lifted.
+ *
+ * Tightening the PAYLOAD types is not available. A citation with no url and no
+ * title is a rendered, tested state (`citationTitle` in components/message.tsx
+ * falls through title -> url -> a generic word, and message.stories.tsx ships
+ * "a citation with no url at all"), and a patch/opts bag is optional by
+ * definition. So the exclusivity lives on the PARAMETER instead, which leaves
+ * every published data type — and every artifact generated from them — alone.
+ *
+ * The forbidden key set is DERIVED from the `MessagePart` union, the same
+ * derivation `verify:scaffold` and `lint:silent-drops` read, so a seventh
+ * variant re-fires this on its own rather than quietly widening the hole.
+ *
+ * THE BOUNDARY — three things this deliberately does NOT cover. Each is a
+ * decision with a reason, not an unfinished edge; they are collected here so
+ * the whole boundary reads in one place instead of being met one at a time.
+ *
+ * 1. A KEY NO SIBLING BAG OWNS still passes. `Unmixed` is a denylist over the
+ *    sibling vocabulary, not an exact type, so a consumer's own superset of a
+ *    citation — `{ url, title, relevance }` — keeps compiling. Full exactness
+ *    would catch marginally more and push real callers toward a cast, and a
+ *    cast to `Source` from an attachment is the original bug. A guard people
+ *    route around is worse than a narrower guard they keep.
+ *
+ * 2. `addCard` / `addFile` ARE NOT WRAPPED. Both take STRONG types —
+ *    `CardEnvelope` requires type+id+data, `AttachmentData` requires id+type —
+ *    so ordinary assignability already does what `Unmixed` exists to do for a
+ *    weak bag. Measured, not assumed: wrapping `addCard` buys ZERO (no sibling
+ *    bag is assignable to `CardEnvelope`, because nothing else carries `data`).
+ *    Wrapping `addFile` buys exactly one pair — `addFile(c)` with
+ *    `c: CardEnvelope<'file', unknown>` — and costs two ordinary consumer
+ *    shapes, since the derived denylist owns `state` and `index`:
+ *
+ *        { id, type: 'file', filename, state: 'uploading' }  // upload progress
+ *        { id, type: 'file', filename, index: 3 }            // display position
+ *
+ *    That one pair needs a hand-written generic narrowing with no other
+ *    purpose; an ordinarily-inferred `CardEnvelope` is ALREADY rejected.
+ *    Rejecting likely code to block contrived code is the wrong trade — the
+ *    same trade point 1 refused. Both facts this rests on are pinned in
+ *    ./stream-types.test.ts, so it re-opens if either stops holding.
+ *
+ * 3. A HAND-BUILT PART BYPASSES ALL OF IT. `parts.push({ type: 'source',
+ *    source: attachmentVariable })` compiles, because these mutators are not
+ *    in the path. Closing it means intersecting the guard into `MessagePart`
+ *    itself — and `docs/web-components.md` and `llms-full.txt` inline that
+ *    union's fully-expanded structural text, so dozens of consumer-facing
+ *    prop-table rows would grow `type?: undefined; state?: undefined;
+ *    data?: undefined`. That cost lands on every consumer reading the docs
+ *    while the benefit reaches only someone who has already stepped around
+ *    the provided API. The mutators are the supported path; they are guarded.
+ *    This is where the supported path ends, not a gap in it.
+ * ------------------------------------------------------------------------ */
+
+/** Every OBJECT payload a `MessagePart` variant carries. `type`/`raw` are the
+ *  variant's own bookkeeping, not payload; the primitive payloads (`text`,
+ *  `label`, `index`, ...) drop out at `Extract<..., object>`. */
+type PartPayload = Extract<
+  MessagePart extends infer P ? (P extends object ? P[Exclude<keyof P, 'type' | 'raw'>] : never) : never,
+  object
+>;
+
+/** Every bag one of these mutators takes: the part payloads plus the options
+ *  bags that are not payloads themselves. */
+type MutatorBag = PartPayload | ReasoningOpts;
+
+/** `keyof` over a union member-by-member. The bare `keyof (A | B)` is the
+ *  INTERSECTION of their keys, which is the opposite of what this needs. */
+type KeysOf<T> = T extends unknown ? keyof T : never;
+
+/** `Shape`, but any key that belongs exclusively to a SIBLING bag is a compile
+ *  error. Keys `Shape` never heard of are untouched, so a consumer's own
+ *  superset of a citation still passes — only the mix-ups fail. That is a
+ *  denylist, not an exact type, and deliberately so: boundary point 1. */
+type Unmixed<Shape> = Shape & { [K in Exclude<KeysOf<MutatorBag>, keyof Shape>]?: never };
+
 function newId(): string {
   if (typeof crypto !== 'undefined' && crypto.randomUUID) return crypto.randomUUID();
   return 'kai-' + Math.random().toString(36).slice(2);
@@ -17,14 +104,16 @@ function newId(): string {
 export interface AssistantStream {
   readonly id: string;
   appendText(delta: string): AssistantStream;
-  appendReasoning(delta: string, opts?: ReasoningOpts): AssistantStream;
-  upsertTool(toolCallId: string, patch: Partial<ToolPart>): AssistantStream;
+  appendReasoning(delta: string, opts?: Unmixed<ReasoningOpts>): AssistantStream;
+  upsertTool(toolCallId: string, patch: Unmixed<Partial<ToolPart>>): AssistantStream;
   /** Adds a card, or REPLACES the existing one with the same `envelope.id`. A
    *  model that revises a card mid-turn re-sends the whole envelope, so a second
    *  call with a known id revises that card in place rather than rendering a
    *  second copy of it. See `upsertCardPart`. */
   addCard(envelope: CardEnvelope): AssistantStream;
-  addSource(source: Source): AssistantStream;
+  addSource(source: Unmixed<Source>): AssistantStream;
+  /* Unwrapped on purpose — these two take STRONG types, so ordinary
+   * assignability already holds. Measurements and the trade: boundary point 2. */
   addFile(attachment: AttachmentData): AssistantStream;
   done(): void;
   abort(reason?: string): void;