@meistrari/chat-ui-lang 0.3.0 → 0.4.0

package/README.md

@@ -1,18 +1,110 @@
 # @meistrari/chat-ui-lang
 
-The catalogue of widgets the chat agent may emit as OpenUI Lang, shared by
-chat-nuxt (which renders them) and agent-api (which puts `prompt()` in the
-system prompt). No Vue here: only names, descriptions, Zod props and the
-prompt generator.
-
-Adding a widget is a two-part change in this monorepo: define it here and add
-its Vue renderer to `chat-nuxt/src/runtime/rendering/openui/registry.ts`. The
-registry test fails until both sides match. The full walkthrough is in
+The catalogue of widgets an agent may emit as OpenUI Lang, shared by the renderers and by the agent runtimes that put
+`prompt()` in the system prompt, plus the Nuxt renderer of the web profile.
+
+| Entry | Contents |
+| --- | --- |
+| `@meistrari/chat-ui-lang` | Names, descriptions, Zod props, the prompt generator and the formats every surface shares (the answers message, the `<widget_context>` envelope, URL safety). No Vue or Nuxt, so agent runtimes can bundle it. |
+| `@meistrari/chat-ui-lang/nuxt` | A Nuxt module with `<OpenuiWidget>`, which renders any program of the catalogue with Tela Build components. Vue, Nuxt and Tela Build are optional peer dependencies, needed only here. |
+
+## Profiles
+
+Each surface renders a subset of the catalogue. `profiles` maps a profile to its library, its extra prompt rules and its
+examples, and `prompt({ profile })` builds the system prompt for one of them.
+
+| Profile | Renderer | Offers |
+| --- | --- | --- |
+| `web` | `@meistrari/chat-ui-lang/nuxt` | the whole catalogue |
+| `slack` | `renderSlackAnswer` | layout, text, metrics, one table, buttons |
+
+A Slack-only component must still get a web renderer, so every surface can show any message of a conversation that moved
+between them.
+
+## Slack
+
+`renderSlackAnswer(content, { prose, threadTs, maxBlocks })` turns an answer with `openui-lang` blocks into Block Kit, or
+returns null when it has none. `prose` is how the connector already renders markdown. Buttons that send a message carry
+`{ t: threadTs, m: message }` in their value under the action id `openui_send_<n>`; `parseSlackWidgetAction` reads it
+back when Slack reports the click. Link buttons (`openui_link_<n>`) only need an acknowledgement. Without `threadTs`,
+send buttons render as text, and so do buttons whose message with its widget context does not fit the 2000-character button value. When the answer does not fit `maxBlocks`, even as prose, `blocks` comes back empty and `text` is the whole answer. `maskWidgets` hides widget code while an answer streams.
+
+## Nuxt renderer
+
+chat-nuxt registers it by itself; apps that embed the chat do nothing. Another Nuxt app must extend Tela Build:
+
+```ts
+export default defineNuxtConfig({
+    extends: ['@meistrari/tela-build'],
+    modules: ['@meistrari/chat-ui-lang/nuxt'],
+})
+```
+
+Give the agent `prompt({ profile: 'web' })` in its system prompt, and render each `openui-lang` block of an answer with:
+
+```vue
+<OpenuiWidget
+    :code="block.code"
+    :complete="!block.streaming"
+    :interactive="isLatestMessage"
+    :send="sendUserMessage"
+    :host="host"
+    @errors="(errors, code) => report(errors, code)"
+    @copy-failed="showToast"
+/>
+```
+
+| Prop | Meaning |
+| --- | --- |
+| `code` | The program of one block; it may grow while `complete` is false |
+| `complete` | False while the block still streams; controls stay disabled |
+| `interactive` | False disables every control, e.g. on older messages |
+| `send(message)` | Sends a user message; resolve `false` when it was rejected. A widget answers once |
+| `host` | Optional `OpenuiHost` (a type exported by `@meistrari/chat-ui-lang/nuxt`): `prose` renders markdown for Markdown and Callout (props `text`, `partial`), `components` replaces widgets by name |
+
+Without a host, prose is plain text, FileCard shows the file name, Image is a link for `https` sources and Citation
+shows its label. chat-nuxt replaces all four with its markdown, vault previews and citation chips.
+
+A widget renderer lives in `src/nuxt/runtime/components/widgets/<name>.vue` and is registered in
+`src/nuxt/runtime/registry.ts`; `registry.test.ts` fails until catalogue and renderers match. A widget gets `props`
+(already evaluated) and `partial`; children arrive as element nodes that it renders with `renderNode` from
+`useOpenuiContext()`. In development the module serves `src/nuxt/runtime`, so edits reload without a rebuild.
+
+## Changing the catalogue
+
+A widget is a change in this monorepo: define it in `src/components/*.ts`, add it to the groups of every profile that
+offers it (`src/library.ts` for web, `src/profiles.ts` for the others) and add its renderer. The walkthrough is in
 `packages/chat-nuxt/docs/guides/widgets.md`.
 
-Bump `LIBRARY_VERSION` on every catalogue change: agent-api stamps it on each
-turn and chat-nuxt logs it with widget errors, which is how drift between the
-prompt and the renderer shows up in production.
+The published version is not bumped by hand: the release workflow derives it from the conventional commits that touch
+this package, and stamps `LIBRARY_VERSION` with it before building (agent-api stamps it on each turn and the renderers
+log it with widget errors, which is how drift between prompt and renderer shows up in production). The values committed
+here are the baseline the workspace itself runs on; keep the two equal (a test fails otherwise).
+
+## Publishing
+
+`@meistrari/chat-ui-lang` ships together with `@meistrari/chat-nuxt`, which depends on it, from
+`.github/workflows/release.yml` (through `publish-chat-nuxt.yml`). Nobody runs `npm publish` by hand.
+
+| Trigger | What happens to chat-ui-lang |
+|---------|------------------------------|
+| Push to `main` | A release candidate `X.Y.Z-rc.N` is published to the `rc` dist-tag (and tagged `chat-ui-lang-X.Y.Z-rc.N`) when releasable commits touched `packages/ui-lang` since the last tag. Otherwise the newest published version is reused. chat-nuxt is then published pinned to that exact version. |
+| `Deploy` dispatch, `forninho` | The candidate chat-nuxt depends on is reused and exercised by the compatibility matrix. |
+| `Deploy` dispatch, `production` | The candidate chat-nuxt depends on is promoted to `X.Y.Z` on `latest` (the RC's contents, only the version rewritten), then chat-nuxt is promoted to a manifest that depends on `X.Y.Z`. |
+
+The build stamps `LIBRARY_VERSION` with the version without its `-rc.N` suffix and applies the `publishConfig` entry
+points to the manifest, both from `scripts/`: promotion republishes the candidate unchanged, so the RC must already
+report the stable version, and `npm publish` (which trusted publishing requires) ignores `publishConfig.main`/`exports`
+that pnpm would apply, leaving entry points that point at `src/`, which the tarball does not contain.
+
+Setup that lives outside this repository, needed once:
+
+- npmjs.com, package `@meistrari/chat-ui-lang` → Settings → Trusted publisher → GitHub Actions: repository
+  `meistrari/chat-app`, workflow `release.yml` (the calling workflow, not `publish-chat-nuxt.yml`). Without it the
+  publish fails with a bare `404 Not Found - PUT`.
+- A baseline tag `chat-ui-lang-<last published version>` on a commit merged into `main`. The release derives the next
+  version from the tags, and without one it would release the "first version" as a major bump. The workflow refuses to
+  run without any `chat-ui-lang-*` tag.
 
-`@openuidev/lang-core` ships a postinstall that sends installation telemetry;
-the root `pnpm.neverBuiltDependencies` entry disables it.
+`@openuidev/lang-core` ships a postinstall that sends installation telemetry; the root `pnpm.neverBuiltDependencies`
+entry disables it.

package/dist/actions.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export declare const CopyText: import("@openuidev/lang-core").DefinedAction<z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strip>, "CopyText">;
+export declare const actions: {
+    CopyText: import("@openuidev/lang-core").DefinedAction<z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strip>, "CopyText">;
+};

package/dist/answers.d.ts

@@ -0,0 +1,16 @@
+export type AnswerableQuestion = {
+    id: string;
+    title: string;
+    type: 'single' | 'multiple';
+    options: ReadonlyArray<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
+};
+export type QuestionAnswer = {
+    selected: string[];
+    skipped?: boolean;
+};
+/** The user message that answers a set of questions; null until every question has a valid answer. */
+export declare function formatQuestionAnswers(requestId: string, questions: readonly AnswerableQuestion[], answers: Readonly<Record<string, QuestionAnswer>>): string | null;

package/dist/components/actions.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+export declare const Button: import("..").UiComponent<z.ZodObject<{
+    label: z.ZodString;
+    action: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"open_url">;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"continue_conversation">;
+        context: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, z.core.$strip>]>>;
+    variant: z.ZodOptional<z.ZodEnum<{
+        primary: "primary";
+        secondary: "secondary";
+    }>>;
+}, z.core.$strip>>;
+export declare const Buttons: import("..").UiComponent<z.ZodObject<{
+    buttons: z.ZodArray<z.core.$ZodType<import("@openuidev/lang-core").SubComponentOf<{
+        label: string;
+        action?: {
+            type: "open_url";
+            url: string;
+        } | {
+            type: "continue_conversation";
+            context?: string | undefined;
+        } | {
+            type: string;
+            params?: Record<string, any> | undefined;
+        } | undefined;
+        variant?: "primary" | "secondary" | undefined;
+    }>, unknown, z.core.$ZodTypeInternals<import("@openuidev/lang-core").SubComponentOf<{
+        label: string;
+        action?: {
+            type: "open_url";
+            url: string;
+        } | {
+            type: "continue_conversation";
+            context?: string | undefined;
+        } | {
+            type: string;
+            params?: Record<string, any> | undefined;
+        } | undefined;
+        variant?: "primary" | "secondary" | undefined;
+    }>, unknown>>>;
+}, z.core.$strip>>;

package/dist/components/chart.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export declare const Bar: import("..").UiComponent<z.ZodObject<{
+    label: z.ZodString;
+    value: z.ZodNumber;
+    display: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export declare const BarChart: import("..").UiComponent<z.ZodObject<{
+    title: z.ZodString;
+    bars: z.ZodArray<z.core.$ZodType<import("@openuidev/lang-core").SubComponentOf<{
+        label: string;
+        value: number;
+        display?: string | undefined;
+    }>, unknown, z.core.$ZodTypeInternals<import("@openuidev/lang-core").SubComponentOf<{
+        label: string;
+        value: number;
+        display?: string | undefined;
+    }>, unknown>>>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        neutral: "neutral";
+        positive: "positive";
+        negative: "negative";
+    }>>;
+}, z.core.$strip>>;

package/dist/components/chat.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+export declare const Option: import("..").UiComponent<z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export declare const Question: import("..").UiComponent<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    options: z.ZodArray<z.core.$ZodType<import("@openuidev/lang-core").SubComponentOf<{
+        id: string;
+        label: string;
+        description?: string | undefined;
+    }>, unknown, z.core.$ZodTypeInternals<import("@openuidev/lang-core").SubComponentOf<{
+        id: string;
+        label: string;
+        description?: string | undefined;
+    }>, unknown>>>;
+    multiple: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>>;
+export declare const Questions: import("..").UiComponent<z.ZodObject<{
+    requestId: z.ZodString;
+    questions: z.ZodArray<z.core.$ZodType<import("@openuidev/lang-core").SubComponentOf<{
+        id: string;
+        title: string;
+        options: import("@openuidev/lang-core").SubComponentOf<{
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }>[];
+        multiple?: boolean | undefined;
+    }>, unknown, z.core.$ZodTypeInternals<import("@openuidev/lang-core").SubComponentOf<{
+        id: string;
+        title: string;
+        options: import("@openuidev/lang-core").SubComponentOf<{
+            id: string;
+            label: string;
+            description?: string | undefined;
+        }>[];
+        multiple?: boolean | undefined;
+    }>, unknown>>>;
+}, z.core.$strip>>;
+export declare const FileCard: import("..").UiComponent<z.ZodObject<{
+    vaultRef: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>>;
+export declare const Citation: import("..").UiComponent<z.ZodObject<{
+    ref: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export declare const Image: import("..").UiComponent<z.ZodObject<{
+    src: z.ZodString;
+    alt: z.ZodString;
+    caption: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;

package/dist/components/data.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+export declare const Metric: import("..").UiComponent<z.ZodObject<{
+    label: z.ZodString;
+    value: z.ZodString;
+    delta: z.ZodOptional<z.ZodString>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        neutral: "neutral";
+        positive: "positive";
+        negative: "negative";
+    }>>;
+}, z.core.$strip>>;
+export declare const Col: import("..").UiComponent<z.ZodObject<{
+    label: z.ZodString;
+    values: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    align: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+    }>>;
+}, z.core.$strip>>;
+export declare const Table: import("..").UiComponent<z.ZodObject<{
+    columns: z.ZodArray<z.core.$ZodType<import("@openuidev/lang-core").SubComponentOf<{
+        label: string;
+        values: (string | number)[];
+        align?: "left" | "right" | undefined;
+    }>, unknown, z.core.$ZodTypeInternals<import("@openuidev/lang-core").SubComponentOf<{
+        label: string;
+        values: (string | number)[];
+        align?: "left" | "right" | undefined;
+    }>, unknown>>>;
+    caption: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;

package/dist/components/form.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export declare const Input: import("..").UiComponent<z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+    placeholder: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export declare const Select: import("..").UiComponent<z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+    options: z.ZodArray<z.ZodString>;
+}, z.core.$strip>>;
+export declare const Checkbox: import("..").UiComponent<z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>>;
+export declare const Form: import("..").UiComponent<z.ZodObject<{
+    name: z.ZodString;
+    fields: z.ZodArray<z.ZodUnion<readonly [z.core.$ZodType<import("@openuidev/lang-core").SubComponentOf<{
+        name: string;
+        label: string;
+        placeholder?: string | undefined;
+    }>, unknown, z.core.$ZodTypeInternals<import("@openuidev/lang-core").SubComponentOf<{
+        name: string;
+        label: string;
+        placeholder?: string | undefined;
+    }>, unknown>>, z.core.$ZodType<import("@openuidev/lang-core").SubComponentOf<{
+        name: string;
+        label: string;
+        options: string[];
+    }>, unknown, z.core.$ZodTypeInternals<import("@openuidev/lang-core").SubComponentOf<{
+        name: string;
+        label: string;
+        options: string[];
+    }>, unknown>>, z.core.$ZodType<import("@openuidev/lang-core").SubComponentOf<{
+        name: string;
+        label: string;
+    }>, unknown, z.core.$ZodTypeInternals<import("@openuidev/lang-core").SubComponentOf<{
+        name: string;
+        label: string;
+    }>, unknown>>]>>;
+    submitLabel: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;