@x12i/ai 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+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

@@ -1,3 +1,40 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @x12i/ai
+
+Neutral message shape and store contracts for the Unified UI Kit AI chat set.
+
+> **Status: foundation.** This package ships the typed message parts and the
+> `ThreadStore` contract. The chat components (`ChatThread`, `PromptInput`,
+> `ToolCall`, `ApprovalPrompt`, ...) and the provider adapters are not built yet.
+
+Components read a neutral message with typed parts (`text`, `reasoning`, `tool`,
+`source`, `file`, `data`), so they never import a provider SDK. Adapters convert
+provider formats, such as Vercel AI SDK message parts, into this shape.
+
+```ts
+import { messageText, type Message } from "@x12i/ai";
+
+const message: Message = {
+  id: "m1",
+  role: "assistant",
+  parts: [{ type: "text", text: "Hello" }],
+};
+
+messageText(message); // "Hello"
+```
+
+## Contracts
+
+- `MessageAdapter<Input>`: converts a provider message into a `Message`.
+- `ThreadStore`: the thread component is stateless, so storage and history belong
+  to the app. `@x12i/flowix-ui` has one that keeps each thread as a Flowix fact
+  (`createFlowixThreadStore`), so a conversation survives a reload and every save
+  stays in Flowix's revision history.
+- `DataPart`: structured data a component can render. Tool input and output, and
+  any JSON you attach, can be painted with `@x12i/records`' `RecordView`, which
+  lays out undescribed JSON from its shape.
+
+## References
+
+The kit adopts structure and naming from Vercel AI Elements (Apache-2.0),
+assistant-ui (MIT) and prompt-kit (MIT), restyled through tokens, and does not
+depend on any of them at runtime.

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The neutral message shape (spec section 6). Components read typed parts and
+ * never import a provider SDK; adapters convert provider formats into this
+ * shape.
+ */
+type MessageRole = "user" | "assistant" | "system";
+interface TextPart {
+    type: "text";
+    text: string;
+}
+interface ReasoningPart {
+    type: "reasoning";
+    text: string;
+    /** How long the model thought, for the "Thought for 4s" line. */
+    durationMs?: number;
+}
+type ToolState = "queued" | "running" | "succeeded" | "failed" | "needs-approval";
+interface ToolPart {
+    type: "tool";
+    id: string;
+    name: string;
+    state: ToolState;
+    input?: unknown;
+    output?: unknown;
+    /** A human-readable cause when `state` is `failed`. */
+    error?: string;
+    durationMs?: number;
+}
+interface SourcePart {
+    type: "source";
+    id: string;
+    title: string;
+    url: string;
+    /** Shown in the source list next to the title and domain. */
+    snippet?: string;
+}
+interface FilePart {
+    type: "file";
+    name: string;
+    mediaType: string;
+    url: string;
+    size?: number;
+}
+/** Structured data a component can render, for example an artifact or a chart spec. */
+interface DataPart {
+    type: "data";
+    /** Identifies the shape of `data`, such as `chart` or `diagram`. */
+    kind: string;
+    data: unknown;
+}
+type MessagePart = TextPart | ReasoningPart | ToolPart | SourcePart | FilePart | DataPart;
+type MessageStatus = "streaming" | "complete" | "error" | "stopped";
+interface Message {
+    id: string;
+    role: MessageRole;
+    parts: MessagePart[];
+    status?: MessageStatus;
+    createdAt?: string;
+    /** The message this one replaces or follows, for branches between versions. */
+    parentId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Thread {
+    id: string;
+    title?: string;
+    messages: Message[];
+    updatedAt?: string;
+}
+/** Converts a provider's message format into the neutral shape. */
+type MessageAdapter<Input> = (input: Input) => Message;
+/**
+ * The thread component is stateless. Storage and history belong to the app,
+ * through this small interface.
+ */
+interface ThreadStore {
+    load(threadId: string): Promise<Thread | null>;
+    save(thread: Thread): Promise<void>;
+    list?(): Promise<Array<Pick<Thread, "id" | "title" | "updatedAt">>>;
+    delete?(threadId: string): Promise<void>;
+}
+/** The text of a message: its text parts, joined. Reasoning and tool output are left out. */
+declare function messageText(message: Message): string;
+/** Tool calls that are waiting for a human decision. */
+declare function pendingApprovals(message: Message): ToolPart[];
+
+export { messageText, pendingApprovals };
+export type { DataPart, FilePart, Message, MessageAdapter, MessagePart, MessageRole, MessageStatus, ReasoningPart, SourcePart, TextPart, Thread, ThreadStore, ToolPart, ToolState };

package/dist/index.js

@@ -0,0 +1,13 @@
+// src/index.ts
+function messageText(message) {
+  return message.parts.filter((part) => part.type === "text").map((part) => part.text).join("");
+}
+function pendingApprovals(message) {
+  return message.parts.filter(
+    (part) => part.type === "tool" && part.state === "needs-approval"
+  );
+}
+
+export { messageText, pendingApprovals };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AAgGO,SAAS,YAAY,OAAA,EAA0B;AACpD,EAAA,OAAO,QAAQ,KAAA,CACZ,MAAA,CAAO,CAAC,IAAA,KAA2B,KAAK,IAAA,KAAS,MAAM,CAAA,CACvD,GAAA,CAAI,CAAC,IAAA,KAAS,IAAA,CAAK,IAAI,CAAA,CACvB,KAAK,EAAE,CAAA;AACZ;AAGO,SAAS,iBAAiB,OAAA,EAA8B;AAC7D,EAAA,OAAO,QAAQ,KAAA,CAAM,MAAA;AAAA,IACnB,CAAC,IAAA,KAA2B,IAAA,CAAK,IAAA,KAAS,MAAA,IAAU,KAAK,KAAA,KAAU;AAAA,GACrE;AACF","file":"index.js","sourcesContent":["/**\r\n * The neutral message shape (spec section 6). Components read typed parts and\r\n * never import a provider SDK; adapters convert provider formats into this\r\n * shape.\r\n */\r\n\r\nexport type MessageRole = \"user\" | \"assistant\" | \"system\";\r\n\r\nexport interface TextPart {\r\n  type: \"text\";\r\n  text: string;\r\n}\r\n\r\nexport interface ReasoningPart {\r\n  type: \"reasoning\";\r\n  text: string;\r\n  /** How long the model thought, for the \"Thought for 4s\" line. */\r\n  durationMs?: number;\r\n}\r\n\r\nexport type ToolState = \"queued\" | \"running\" | \"succeeded\" | \"failed\" | \"needs-approval\";\r\n\r\nexport interface ToolPart {\r\n  type: \"tool\";\r\n  id: string;\r\n  name: string;\r\n  state: ToolState;\r\n  input?: unknown;\r\n  output?: unknown;\r\n  /** A human-readable cause when `state` is `failed`. */\r\n  error?: string;\r\n  durationMs?: number;\r\n}\r\n\r\nexport interface SourcePart {\r\n  type: \"source\";\r\n  id: string;\r\n  title: string;\r\n  url: string;\r\n  /** Shown in the source list next to the title and domain. */\r\n  snippet?: string;\r\n}\r\n\r\nexport interface FilePart {\r\n  type: \"file\";\r\n  name: string;\r\n  mediaType: string;\r\n  url: string;\r\n  size?: number;\r\n}\r\n\r\n/** Structured data a component can render, for example an artifact or a chart spec. */\r\nexport interface DataPart {\r\n  type: \"data\";\r\n  /** Identifies the shape of `data`, such as `chart` or `diagram`. */\r\n  kind: string;\r\n  data: unknown;\r\n}\r\n\r\nexport type MessagePart = TextPart | ReasoningPart | ToolPart | SourcePart | FilePart | DataPart;\r\n\r\nexport type MessageStatus = \"streaming\" | \"complete\" | \"error\" | \"stopped\";\r\n\r\nexport interface Message {\r\n  id: string;\r\n  role: MessageRole;\r\n  parts: MessagePart[];\r\n  status?: MessageStatus;\r\n  createdAt?: string;\r\n  /** The message this one replaces or follows, for branches between versions. */\r\n  parentId?: string;\r\n  metadata?: Record<string, unknown>;\r\n}\r\n\r\nexport interface Thread {\r\n  id: string;\r\n  title?: string;\r\n  messages: Message[];\r\n  updatedAt?: string;\r\n}\r\n\r\n/** Converts a provider's message format into the neutral shape. */\r\nexport type MessageAdapter<Input> = (input: Input) => Message;\r\n\r\n/**\r\n * The thread component is stateless. Storage and history belong to the app,\r\n * through this small interface.\r\n */\r\nexport interface ThreadStore {\r\n  load(threadId: string): Promise<Thread | null>;\r\n  save(thread: Thread): Promise<void>;\r\n  list?(): Promise<Array<Pick<Thread, \"id\" | \"title\" | \"updatedAt\">>>;\r\n  delete?(threadId: string): Promise<void>;\r\n}\r\n\r\n/** The text of a message: its text parts, joined. Reasoning and tool output are left out. */\r\nexport function messageText(message: Message): string {\r\n  return message.parts\r\n    .filter((part): part is TextPart => part.type === \"text\")\r\n    .map((part) => part.text)\r\n    .join(\"\");\r\n}\r\n\r\n/** Tool calls that are waiting for a human decision. */\r\nexport function pendingApprovals(message: Message): ToolPart[] {\r\n  return message.parts.filter(\r\n    (part): part is ToolPart => part.type === \"tool\" && part.state === \"needs-approval\",\r\n  );\r\n}\r\n"]}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@x12i/ai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Neutral message shape and store contracts for the Unified UI Kit AI chat set. Components and provider adapters are planned.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x12i/unified-ui-kit.git",
+    "directory": "packages/ai"
+  },
+  "homepage": "https://github.com/x12i/unified-ui-kit/tree/main/packages/ai#readme",
+  "bugs": {
+    "url": "https://github.com/x12i/unified-ui-kit/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests"
+  }
 }