@meistrari/chat-nuxt 3.9.1 → 3.10.0

package/README.md

@@ -2,6 +2,8 @@
 
 Nuxt module that adds a complete AI chat interface to your app. Server-side chat behavior is delegated to the dedicated Chat API; the Nuxt module owns the UI, auth bridge, and local proxy routes.
 
+Consumer documentation lives in `docs/guides/` (indexed [below](#guides)); this README covers the package boundary and working on the package itself.
+
 ## Public Surface
 
 `@meistrari/chat-nuxt` is an external package. Its supported consumer surface is intentionally small:
@@ -14,468 +16,59 @@ Nuxt module that adds a complete AI chat interface to your app. Server-side chat
 
 Runtime internals under `src/runtime/**`, generated Nuxt aliases, and workspace-only schema package imports are implementation details unless they are explicitly exported above.
 
-## Installation
-
-```bash
-pnpm add @meistrari/chat-nuxt
-```
-
-### Required: Vue dedupe via pnpm overrides
-
-`@meistrari/tela-build` pins `vue@3.5.13` as a direct dependency, which collides with the Vue that Nuxt installs. Without an override, pnpm installs two Vue copies and you'll hit runtime errors such as `root.ce._hasShadowRoot is not a function` when custom elements register against one Vue and mount against the other.
-
-Until tela-build is published with Vue as a peer dependency, pin a single Vue version in your consumer `package.json`:
-
-```json
-{
-  "pnpm": {
-    "overrides": {
-      "vue": "3.5.33"
-    }
-  }
-}
-```
-
-Keep this entry until `@meistrari/tela-build` moves Vue to `peerDependencies` — at that point the override becomes unnecessary and should be removed.
-
-## Setup
-
-### 1. Register the modules
-
-```typescript
-// nuxt.config.ts
-export default defineNuxtConfig({
-    modules: [
-        '@meistrari/auth-nuxt', // must come before chat-nuxt
-        '@meistrari/chat-nuxt',
-    ],
-
-    ssr: false,
-
-    chatNuxt: {
-        chatApiUrl: process.env.CHAT_API_URL,
-        validateConfig: 'warn',
-    },
-
-    telaAuth: {
-        apiUrl: process.env.AUTH_API_URL ?? '',
-        application: {
-            enabled: true,
-            applicationId: process.env.APPLICATION_ID ?? '',
-            redirectUri: process.env.AUTH_REDIRECT_URI ?? 'http://localhost:3000/auth/callback',
-            dashboardUrl: process.env.AUTH_DASHBOARD_URL ?? '',
-        },
-    },
-})
-```
-
-### 2. Module options
-
-`chatApiUrl` accepts the value inline, or you can leave the option empty and set `CHAT_API_URL`. Resolution order: **module option → existing `runtimeConfig` → env var → empty**.
-
-| Option | Required | Env fallback | Description |
-|--------|----------|--------------|-------------|
-| `chatApiUrl` | ✅ Always | `CHAT_API_URL` | Dedicated Chat API base URL used by Nuxt server proxy routes. |
-| `validateConfig` | 🔧 Optional | — | `false` (default), `'warn'`, or `'error'`. Warns or fails fast when `chatApiUrl` is missing. |
-
-Set `chatNuxt.validateConfig` to `'warn'` to log a warning when `chatApiUrl` is missing, or `'error'` to fail fast at module setup. The check is off by default since some deployments inject runtime config after build.
-
-UI features are configured per component instance, not at the module level: the embed takes a `:features` prop (`ChatFeatureConfig`) and `<ChatConfigurationModal>` takes `show-credentials-tab`.
-
-### 3. Auth modes
-
-`@meistrari/chat-nuxt` can run with either auth mode exposed by `@meistrari/auth-nuxt`:
-
-- Application auth (`telaAuth.application.enabled: true`) delegates chat identity and workspace state to `useTelaApplicationAuth()`.
-- First-party auth delegates chat identity to `useTelaSession()` and workspace state to `useTelaOrganization()`.
-
-The module chooses the bridge during Nuxt setup. Host apps should keep registering `@meistrari/auth-nuxt` before `@meistrari/chat-nuxt`.
-
-### 4. Setup `app.vue`
-
-```vue
-<!-- app.vue -->
-<template>
-    <NuxtPage />
-    <AppStatusToast />
-</template>
-```
-
-`AppStatusToast`, Markstream styles, code block styles, and math delimiter defaults are auto-registered by the module.
-
-### 5. Use it
-
-```vue
-<!-- pages/index.vue -->
-<template>
-    <div h-screen>
-        <MeistrariChatEmbed />
-    </div>
-</template>
-```
-
-The chat workspace is resolved from the authenticated `activeOrganization` provided by `@meistrari/auth-nuxt`.
+`typedoc.ts` at the package root is the documentation barrel for that surface — it is what the published API reference is generated from. Adding an export there makes it public; keep internals out of it.
 
-### Chat runtime modes
+## Guides
 
-`<MeistrariChatEmbed />` has two mutually exclusive runtimes:
-
-- **Default chat mode** uses the Chat API and the workspace's configured Tela agent. Runtime configuration, entitlements, and workspace-specific agent selection are owned by `@meistrari/chat-api`. Workspaces whose legacy customization has not been migrated to a Tela agent are not ready to chat: sends fail with `workspace_agent_not_ready` and the embed surfaces guidance pointing to the settings modal, where the **Agente** tab offers a one-click agent creation.
-- **Tela agent mode** uses a configured Tela agent directly. Pass `telaAgentId`; the embed sends user messages to `POST /agent/:id/run`, polls `GET /agent/sessions/:sessionId`, and ends sessions with `DELETE /agent/sessions/:sessionId`.
-
-```vue
-<MeistrariChatEmbed tela-agent-id="agent_123" />
-```
-
-`conversationScope` works in both runtimes. In default chat mode, it isolates conversations inside the authenticated workspace while the Chat API resolves the correct Tela agent:
-
-```vue
-<MeistrariChatEmbed :conversation-scope="`user:${userId}`" />
-```
-
-Host apps can also provide Tela agent inputs directly. When `telaAgentInputs` is non-null, the chat sends those inputs with each agent run and does not render the agent variables panel.
-
-```vue
-<MeistrariChatEmbed
-    tela-agent-id="agent_123"
-    :conversation-scope="`customer:${customerId}`"
-    :tela-agent-inputs="[
-        { type: 'text', name: 'customer_id', content: customerId },
-    ]"
-/>
-```
-
-In Tela agent mode, `workspaceSettings` and `user` are not accepted by the public prop contract - the Tela agent owns runtime configuration and identity for execution. `features` is still accepted for shared UI controls.
+| Guide | Covers |
+|-------|--------|
+| [Installation and setup](docs/guides/installation.md) | Install, Vue dedupe override, module registration, module options, auth modes |
+| [Embedding in your layout](docs/guides/embedding.md) | Layout, key props, conversation scoping, events, slots |
+| [Chat runtime modes](docs/guides/tela-agent-mode.md) | Default chat mode vs Tela agent mode, agent inputs |
+| [Citations](docs/guides/citations.md) | `cite://` chips, metadata popover, document panel |
+| [Feature flags](docs/guides/feature-flags.md) | Usage tab, debug entry, cancel button, PostHog wiring |
+| [Message feedback](docs/guides/message-feedback.md) | 👍/👎 controls and host-owned persistence |
+| [Workspace settings](docs/guides/workspace-settings.md) | Settings overrides, agent runtime ownership, `<ChatConfigurationModal>` |
 
-## Embedding in Your Layout
+## API Reference
 
-The main use case: drop the chat inside your existing app UI.
+The JSDoc on each type is the source of truth, and the hosted reference is generated from it — Pantry builds it from [`typedoc.ts`](typedoc.ts), the barrel listing every public symbol, using its own pinned TypeDoc. Generated output is never committed here. The `postinstall` hook runs `nuxi prepare` so the Nuxt types `tsconfig.json` depends on exist before that build runs.
 
-```vue
-<template>
-    <div class="my-app-layout">
-        <MyHeader />
+To render the reference locally:
 
-        <main>
-            <!-- Chat embedded in a card -->
-            <div style="height: 600px" class="rounded-2xl overflow-hidden border">
-                <MeistrariChatEmbed
-                    v-model:conversation-id="activeConversation"
-                    :hide-sidebar="true"
-                    :loading-messages="['Buscando contratos', 'Lendo documentos', 'Preparando resposta']"
-                    loading-messages-mode="ordered"
-                />
-            </div>
-        </main>
-    </div>
-</template>
+```bash
+bunx --bun typedoc --entryPoints typedoc.ts --out /tmp/chat-nuxt-api --skipErrorChecking
 ```
 
-Key props for embedding:
-
-- **`:hide-sidebar="true"`** — removes the conversation list, keeps just the chat
-- **`v-model:conversation-id`** — sync the active conversation with your app's state
-- **`:initial-conversation-id`** — open a specific conversation on mount
-- **`conversation-scope`** — isolate conversation history inside the same workspace or Tela agent
+The table below is a quick index for reading in-repo. **When you change a prop, update its JSDoc and this row together.**
 
-## `<MeistrariChatEmbed>` Props
+### `<MeistrariChatEmbed>` props
 
-All prop, feature-flag, and event payload types are importable from the package root (or the `types/embed` subpath):
-
-```ts
-import type {
-    ChatActionPayload,
-    ChatFeatureConfig,
-    MeistrariChatEmbedProps,
-    MessageFeedbackConfig,
-    MessageFeedbackPayload,
-    MessageFeedbackRating,
-} from '@meistrari/chat-nuxt'
-```
+Declared in `src/runtime/embed/types.ts`; prop, feature-flag, and event payload types are importable from the package root or `@meistrari/chat-nuxt/types/embed`.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `hideSidebar` | `boolean` | `false` | Hide conversation list sidebar |
+| `hideSidebar` | `boolean` | `false` | Hide the conversation list and render only the active chat surface |
 | `sidebar` | `ChatSidebarConfig` | `undefined` | Sidebar layout: `{ position?, width?, bottomHeight?, collapsible?, defaultCollapsed? }`. `position` (`'left'`\|`'right'`, default `'left'`) picks the edge; `width` is the sidebar width in pixels (default `240`); `bottomHeight` is the `sidebar-bottom` pane height as a percentage 0–100 of the conversation area (default `50`); `collapsible` (default `false`) renders a native collapse handle and animates the sidebar open/closed; `defaultCollapsed` (default `false`) starts it collapsed |
 | `hideSettings` | `boolean` | `false` | Hide workspace settings actions while keeping the chat header and content unchanged |
-| `conversationId` | `string \| null` | `null` | Controlled conversation (supports v-model) |
-| `initialConversationId` | `string \| null` | `null` | Open this conversation on mount |
-| `conversationScope` | `string \| null` | `null` | Isolate conversation history by technical scope within the current workspace and runtime |
-| `defaultConversationCreatorFilter` | `'all' \| 'mine'` | `'all'` | Initial sidebar creator filter |
+| `conversationId` | `string \| null` | `null` | Controlled conversation (supports `v-model:conversation-id`) |
+| `initialConversationId` | `string \| null` | `null` | Conversation to open once on mount when `conversationId` is uncontrolled |
+| `conversationScope` | `string \| null` | `null` | Isolate conversation history by technical scope within the current workspace and runtime. Scoped embeds only see same-scope conversations; values are trimmed, blank becomes `null`, and the server accepts 1-200 chars from `A-Z`, `a-z`, `0-9`, `.`, `_`, `:`, `/`, `-` |
+| `defaultConversationCreatorFilter` | `'all' \| 'mine'` | `'all'` | Initial sidebar creator filter: every conversation in scope, or only the current user's |
 | `telaAgentId` | `string` | — | Use Tela agent mode for this embed |
 | `telaAgentInputs` | `TelaAgentExecutionInput[] \| null` | `undefined` | Inputs sent with each Tela agent run; hides the variables panel when non-null |
-| `workspaceSettings` | `WorkspaceSettings \| null` | `null` | Override settings from host app |
-| `user` | `ChatActor \| null` | `null` | Override current user display info |
-| `features` | `Partial<ChatFeatureConfig>` | `{}` | Toggle optional features |
+| `workspaceSettings` | `WorkspaceSettings \| null` | `null` | Override settings from host app; not accepted in Tela agent mode |
+| `user` | `ChatActor \| null` | `null` | Override current user display info; not accepted in Tela agent mode |
+| `features` | `Partial<ChatFeatureConfig>` | `{}` | Toggle optional features: `showUsageTab`, `showDebugOption`, `showCancelButton` (all `false`) |
 | `loadingMessages` | `readonly string[] \| null` | Default chat messages | Override pending-response messages |
-| `loadingMessagesMode` | `'ordered' \| 'random' \| null` | `'ordered'` | Show custom messages sequentially or randomly |
+| `loadingMessagesMode` | `'ordered' \| 'random' \| null` | `'ordered'` | Rotate custom messages in order or at random; only applies when `loadingMessages` has a non-empty message |
 | `customComponents` | `Record<string, Component>` | `undefined` | Custom markdown renderers keyed by markdown node or tag name |
 | `customHtmlTags` | `readonly string[]` | `undefined` | Extra HTML tags allowed by the markdown renderer |
-| `citations` | `ChatCitationsConfig \| null` | `undefined` | Enables `cite://` citations in assistant messages (see Citations below) |
+| `citations` | `ChatCitationsConfig \| null` | `undefined` | Enables `cite://` citations in assistant messages (see [Citations](docs/guides/citations.md)) |
 | `feedbackConfig` | `MessageFeedbackConfig \| null` | `undefined` | Enables 👍/👎 feedback on assistant messages; providing the prop (even `{}`) shows the controls |
 | `messageFeedback` | `Record<string, MessageFeedbackRating> \| null` | `undefined` | Host-persisted votes keyed by message id; when provided, it is the single source of truth for the selected thumbs |
 
-`loadingMessagesMode` only applies when `loadingMessages` has at least one non-empty message.
-
-Use `conversationScope` when you need multiple chat surfaces to share the same authenticated workspace but keep separate histories. This is useful for per-user inboxes, record detail pages, customer workspaces, template previews, workflow steps, or any app route where the same chat should only show conversations for that route's domain object. The scope is applied together with the workspace and, when present, the `telaAgentId`.
-
-Scoped embeds only see conversations created with the same scope. Unscoped embeds only see unscoped conversations, so adding a scope will not mix with existing workspace-level history. Scope values are technical identifiers: they are trimmed, blank strings become `null`, and server requests accept 1-200 characters from `A-Z`, `a-z`, `0-9`, `.`, `_`, `:`, `/`, and `-`.
-
-```vue
-<!-- Default chat mode: workspace + scope -->
-<MeistrariChatEmbed :conversation-scope="`user:${userId}`" />
-<MeistrariChatEmbed :conversation-scope="`customer:${customerId}`" />
-
-<!-- Tela agent mode: workspace + telaAgentId + scope -->
-<MeistrariChatEmbed
-    tela-agent-id="agent_123"
-    :conversation-scope="`template:${templateId}`"
-/>
-```
-
-**Citations (`cite://`):**
-
-Hosts whose agents cite retrievable documents can teach them (via prompt) the notation
-
-```
-[visible text](cite://<namespace>/<id>[#q=<term>&n=<nth>&p=<page>])
-```
-
-and pass `citations` to enable it. The lib detects the notation in assistant messages (markdown links and bare tokens), renders each citation as a chip with a metadata popover, and — when `getDocument` is provided — opens a built-in side panel that shows the document with the cited term highlighted (`#q`, nth occurrence via `#n`). What a namespace means, and every data access, belongs to the host: callbacks run against the host's own backend, carrying the viewing user's authorization. A citation that fails to resolve renders as "unverified" — an agent cannot fabricate a trusted-looking reference, and a viewer without access to a document learns nothing from a citation to it.
-
-```vue
-<MeistrariChatEmbed
-    tela-agent-id="agent_123"
-    :citations="{
-        resolve: ref => $fetch(`/api/citations/${ref.namespace}/${encodeURIComponent(ref.id)}`).catch(() => null),
-        getDocument: ref => $fetch(`/api/citations/${ref.namespace}/${encodeURIComponent(ref.id)}/document`).catch(() => null),
-        locate: (ref, term) => $fetch(`/api/citations/${ref.namespace}/${encodeURIComponent(ref.id)}/occurrences`, { query: { term } }).catch(() => null),
-    }"
-/>
-```
-
-`ref.id` arrives percent-decoded (natural identifiers may carry pipes, spaces, accents or slashes) — re-encode it when building URLs, as above.
-
-`ChatCitationsConfig` (exported from `@meistrari/chat-nuxt/types/citations`): `resolve` maps a citation to display metadata (`null` = unverified); `getDocument` enables the document panel; `locate` returns precise term offsets for highlighting (omit it for a client-side, accent-sensitive fallback); `component` replaces the built-in chip; `onOpen` takes over the click entirely. Without the `citations` prop nothing changes: `cite://` hrefs keep rendering as plain links.
-
-**Events:**
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `update:conversationId` | `string \| null` | Active conversation changed |
-| `action` | `ChatActionPayload` | Custom action triggered from chat content (`{ name, data, messageId? }`) |
-| `messageFeedback` | `MessageFeedbackPayload` | User voted on an assistant message (see [Message Feedback](#optional-message-feedback)) |
-
-**Slots:**
-
-| Slot | Description |
-|------|-------------|
-| `sidebar-bottom` | Splits the desktop sidebar into two panes and renders your content in the bottom one, below the conversation list. Each pane scrolls independently. Size it with `sidebar.bottomHeight` (percentage, default `50`). Not rendered on mobile or when `hideSidebar` is set. |
-
-```vue
-<MeistrariChatEmbed :sidebar="{ position: 'right', width: 300, bottomHeight: 30 }">
-    <template #sidebar-bottom>
-        <MyPinnedDocuments />
-    </template>
-</MeistrariChatEmbed>
-```
-
-## Optional: Feature Flags
-
-`<MeistrariChatEmbed>` accepts a `:features` prop with three optional toggles. All default to `false`. The host owns the policy - hardcode them, gate by user role, or wire them through a feature-flag provider of your choice.
-
-| Flag | Effect |
-|------|--------|
-| `showUsageTab` | Usage tab in the chat topbar (per-conversation token/cost stats) |
-| `showDebugOption` | Debug entry in the topbar overflow menu |
-| `showCancelButton` | "Stop generation" button while a response streams |
-
-Static example:
-
-```vue
-<MeistrariChatEmbed :features="{ showUsageTab: true, showCancelButton: true }" />
-```
-
-### With PostHog
-
-`chat-nuxt` ships a small PostHog helper for hosts that want to gate flags dynamically. The flag names live in your app — `chat-nuxt` has no opinion about them.
-
-1. Add to `nuxt.config.ts`:
-
-```typescript
-runtimeConfig: {
-    public: {
-        posthogPublicKey: process.env.POSTHOG_PUBLIC_KEY ?? '',
-        posthogHost: process.env.POSTHOG_HOST ?? '',
-        posthogDefaults: process.env.POSTHOG_DEFAULTS ?? '2026-01-30',
-    },
-},
-```
-
-2. Initialize in `app.vue`:
-
-```vue
-<script setup lang="ts">
-const { posthogPublicKey, posthogHost, posthogDefaults } = useRuntimeConfig().public
-
-// Application auth hosts:
-const { user, activeOrganization } = useTelaApplicationAuth()
-
-// First-party auth hosts can use this instead:
-// const session = useTelaSession()
-// const organization = useTelaOrganization()
-// const user = session.user
-// const activeOrganization = organization.activeOrganization
-// await organization.getActiveOrganization()
-
-onMounted(async () => {
-    if (!posthogPublicKey || !posthogHost) return
-    await initPosthog(posthogPublicKey, posthogHost, posthogDefaults)
-    if (user.value) identifyPosthogUser(user.value)
-    if (activeOrganization.value) setPosthogWorkspace(activeOrganization.value)
-})
-</script>
-```
-
-3. Thread the flags into the embed:
-
-```vue
-<script setup lang="ts">
-const { isFeatureEnabled } = useFeatureFlags()
-
-const features = computed(() => ({
-    showUsageTab: isFeatureEnabled('enable-usage-tab'),
-    showDebugOption: isFeatureEnabled('enable-debug-mode'),
-    showCancelButton: isFeatureEnabled('enable-cancel-generation'),
-}))
-</script>
-
-<template>
-    <MeistrariChatEmbed :features="features" />
-</template>
-```
-
-## Optional: Message Feedback
-
-Assistant messages can carry 👍/👎 controls. The package renders the controls and collects the vote; **persistence is owned by the host** — nothing is stored by `chat-nuxt`.
-
-Passing `feedbackConfig` (even `{}`) enables the controls:
-
-```vue
-<script setup lang="ts">
-import type { MessageFeedbackPayload, MessageFeedbackRating } from '@meistrari/chat-nuxt'
-
-const votes = ref<Record<string, MessageFeedbackRating>>({})
-
-async function onFeedback(payload: MessageFeedbackPayload) {
-    // payload: { conversationId, messageId, rating, reasons, comment }
-    await saveVoteToMyBackend(payload)
-    votes.value = { ...votes.value, [payload.messageId]: payload.rating }
-}
-</script>
-
-<template>
-    <MeistrariChatEmbed
-        :feedback-config="{
-            negativeReasons: ['Resposta incorreta', 'Fora do tema', 'Incompleta'],
-            requireReason: true,
-        }"
-        :message-feedback="votes"
-        @message-feedback="onFeedback"
-    />
-</template>
-```
-
-`MessageFeedbackConfig` fields:
-
-| Field | Effect |
-|-------|--------|
-| `positiveReasons` | Reason chips offered on a positive vote. Empty or omitted: 👍 submits directly |
-| `negativeReasons` | Reason chips offered on a negative vote |
-| `requireReason` | Blocks a bare negative vote: requires at least one reason chip when `negativeReasons` are configured, otherwise a non-empty comment |
-
-`messageFeedback` controls which thumb renders selected:
-
-- **Provided** (controlled): only host-persisted votes render. Update the map as `message-feedback` events are saved — optimistically or after persistence.
-- **Omitted**: votes are kept in component-local state only.
-
-## Optional: Custom Workspace Settings
-
-Agent-level configuration (system prompt, context files, tools, skills) lives in the workspace's Tela agent and is edited in the Tela app. The module's built-in settings UI manages knowledge sources (Tela workstations) and workspace credentials, persisted by the Chat API service.
-
-To override the settings the embed reads, pass them directly from your host app:
-
-```vue
-<MeistrariChatEmbed
-    :workspace-settings="{
-        workspaceId: 'ws_123',
-        systemMessage: 'You are a helpful assistant for Acme Corp.',
-        contextFiles: null,
-        canvasTools: null,
-        knowledgeSources: null,
-        externalSkills: null,
-        updatedAt: new Date(),
-    }"
-/>
-```
-
-The `server/chat/resolve-workspace-settings.ts` host resolver from earlier versions is no longer invoked: the module proxies chat requests to the Chat API, which owns workspace settings resolution.
-
-## Agent Runtime Configuration
-
-`chat-nuxt` proxies chat requests to `@meistrari/chat-api`; it does not start agent sessions directly or resolve runtime environment variables. Agent runtime configuration, entitlements, and Tela agent selection are owned by `chat-api` and the Tela agent configuration. Host apps do not need Nuxt-side agent environment resolver files for this module.
-
-A skill that calls a host backend must implement its own callback contract with the host backend. In short, callback authorization belongs to the skill and host backend, not `chat-nuxt`. The host backend remains responsible for validating invocation grants, allowed tools, schemas, replay protection, confirmation for writes, and audit logging.
-
-## `<ChatConfigurationModal>`
-
-A reusable workspace settings modal that any host app can open from any button. It has three tabs:
-
-- **`agent`** (Agente) — the workspace's Tela agent status. Shows the generic-chat state, the dedicated agent (id, copy, open in Tela), or — for workspaces whose legacy customization has not been migrated — a setup-required warning with a create-agent action. Agent configuration itself (system prompt, context files, tools, skills) is edited in the Tela app, not here.
-- **`knowledge-sources`** (Tela workstations) — the workstations injected as knowledge sources into new chat sessions.
-- **`credentials`** (Credenciais) — workspace credentials, shown when `showCredentialsTab` is set.
-
-By default, the modal uses `useWorkspaceSettings()` to fetch and persist settings. If the host passes the `settings` prop, the host owns workspace settings state and persistence.
-
-```vue
-<script setup lang="ts">
-import type { ChatConfigurationTab } from '@meistrari/chat-nuxt/types/workspace-settings'
-
-const open = ref(false)
-const initialTab = ref<ChatConfigurationTab>('agent')
-
-function openSettings(tab: ChatConfigurationTab = 'agent') {
-    initialTab.value = tab
-    open.value = true
-}
-</script>
-
-<template>
-    <button @click="openSettings()">
-        Configurações
-    </button>
-
-    <ChatConfigurationModal
-        v-model:open="open"
-        :initial-tab="initialTab"
-    />
-</template>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `open` | `boolean` | — | Modal visibility (supports `v-model:open`) |
-| `settings` | `WorkspaceSettings \| null` | `undefined` | Optional host-controlled settings. Omit this prop to let the modal fetch and persist via `useWorkspaceSettings()`; pass `null` or a settings object to make the host own state and persistence |
-| `initialTab` | `ChatConfigurationTab` | `'agent'` | Tab to open on: `'agent' \| 'knowledge-sources' \| 'credentials'` |
-| `saving` | `boolean` | `false` | Host-controlled spinner/disable while persistence is in flight |
-| `showCredentialsTab` | `boolean` | `false` | Show the workspace credentials tab |
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `update:open` | `boolean` | Modal open state changed |
-| `save` | `ChatConfigurationSavePayload` | Emitted only when the host passes `settings`; carries the knowledge-source updates plus `onSaved`; host persists (e.g. via `useWorkspaceSettings().updateSettings()`), calls `onSaved` after persistence succeeds, and closes the modal |
-
-Only the knowledge-sources tab produces a `save` payload. The `agent` tab acts immediately through the module's `/api/workspace/agent` endpoints, and the `credentials` tab manages its own data via `/api/workspace/credentials` — neither is part of the `save` payload.
+Events and slots are listed in [Embedding in your layout](docs/guides/embedding.md); `<ChatConfigurationModal>` props and events are in [Workspace settings](docs/guides/workspace-settings.md).
 
 ## What's Included
 
@@ -485,6 +78,23 @@ The module auto-registers everything — no manual imports needed:
 - **Composables**: `useChat`, `useConversations`, `useWorkspaceSettings`, `useFileUpload`, `useFeatureFlags`, and more
 - **Server routes**: thin proxy routes that forward chat requests to the Chat API service
 
+## Development
+
+Run from this package:
+
+```bash
+pnpm build          # nuxt-module-build + embedded schema/declaration post-processing
+pnpm dev:prepare    # stub build for local development
+pnpm typecheck      # builds the module, prepares chat-app, typechecks the host app
+pnpm test:types     # build + tsc against the consumer type tests
+pnpm smoke:pack     # pack the module and install it into a scratch consumer
+pnpm smoke:browser  # packed-consumer smoke test with a real browser
+pnpm lint           # eslint
+pnpm lint:attrs     # guards against stray `!` attribute typos in runtime templates
+```
+
+Unit tests run from the workspace root (`pnpm test`), which prepares this package before invoking vitest.
+
 ## Package Dependencies
 
 Installing `@meistrari/chat-nuxt` installs the runtime packages used by the layer. The host Nuxt app still owns the Nuxt and Vue versions.
@@ -515,5 +125,5 @@ Peer dependencies:
 
 | Package | Version | Purpose |
 |---------|---------|---------|
-| `nuxt` | `^3.17.0` | Host framework |
+| `nuxt` | `^3.17.0 \|\| ^4.0.0` | Host framework |
 | `vue` | `^3.5.0` | Host Vue runtime |

package/dist/module.d.mts

@@ -1,5 +1,5 @@
 export { ChatMessageStatus } from '../dist/runtime/messages/composables/chat-message-terminal.js';
-export { ChatActionPayload, ChatActor, ChatEmbedSharedProps, ChatFeatureConfig, ChatMessageTerminalPayload, ChatSidebarConfig, DefaultChatEmbedProps, MeistrariChatEmbedProps, MessageFeedbackConfig, MessageFeedbackPayload, MessageFeedbackRating, MessageOverviewResponse, TelaAgentChatEmbedProps, TelaAgentExecutionInput } from '../dist/runtime/types/embed.js';
+export { ChatActionPayload, ChatActor, ChatEmbedSharedProps, ChatEmbedVariant, ChatEmbedVariantProps, ChatFeatureConfig, ChatMessageTerminalPayload, ChatSidebarConfig, ChatSuggestion, DefaultChatEmbedProps, MeistrariChatEmbedProps, MessageFeedbackConfig, MessageFeedbackPayload, MessageFeedbackRating, MessageOverviewResponse, TelaAgentChatEmbedProps, TelaAgentExecutionInput } from '../dist/runtime/types/embed.js';
 
 type ChatNuxtConfigValidationMode = false | 'warn' | 'error';
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@meistrari/chat-nuxt",
   "configKey": "chatNuxt",
-  "version": "3.9.1",
+  "version": "3.10.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -125,6 +125,35 @@ function resolveRuntimeAliases(telaBuildPath) {
   return resolvedAliases;
 }
 
+const QUADRATIC_GUARDS = [
+  { from: "/[^~]*~{2,}[^~]+/", to: "/~{2,}[^~]/" },
+  { from: "/[^*]*\\*[^*]+/", to: "/\\*[^*]/" }
+];
+const STREAM_MARKDOWN_PARSER_GUARD_COUNT = QUADRATIC_GUARDS.length;
+function patchStreamMarkdownParserSource(source) {
+  let patched = source;
+  let applied = 0;
+  for (const { from, to } of QUADRATIC_GUARDS) {
+    if (!patched.includes(from)) {
+      continue;
+    }
+    patched = patched.replaceAll(from, to);
+    applied++;
+  }
+  patched = patched.replace(/\n?\/\/# sourceMappingURL=.*\n?$/, "\n");
+  return { source: patched, applied };
+}
+function resolvePatchedStreamMarkdownParser(from) {
+  try {
+    const markstreamEntry = createRequire(from).resolve("markstream-vue");
+    const entry = createRequire(markstreamEntry).resolve("stream-markdown-parser");
+    const { source, applied } = patchStreamMarkdownParserSource(readFileSync(entry, "utf8"));
+    return { entry, source, applied };
+  } catch {
+    return null;
+  }
+}
+
 const workspaceSettingsResolverCandidates = [
   "server/chat/resolve-workspace-settings.ts",
   "server/chat/resolve-workspace-settings.js"
@@ -347,12 +376,25 @@ const module$1 = defineNuxtModule({
       nuxt.options.extends = nuxt.options.extends ? [nuxt.options.extends] : [];
     }
     nuxt.options.extends.unshift(telaBuildPath);
+    const patchedStreamMarkdownParser = resolvePatchedStreamMarkdownParser(import.meta.url);
+    if (patchedStreamMarkdownParser?.applied !== STREAM_MARKDOWN_PARSER_GUARD_COUNT) {
+      const cause = patchedStreamMarkdownParser ? `${patchedStreamMarkdownParser.entry}: expected ${STREAM_MARKDOWN_PARSER_GUARD_COUNT} guards, found ${patchedStreamMarkdownParser.applied}` : "not resolvable through markstream-vue";
+      console.error(
+        `[@meistrari/chat-nuxt] Could not rewrite the quadratic guards in stream-markdown-parser (${cause}). Long unbroken Markdown paragraphs will parse quadratically and can freeze the chat UI. Update QUADRATIC_GUARDS in @meistrari/chat-nuxt, or drop the rewrite if upstream fixed the backtracking.`
+      );
+    }
+    const streamMarkdownParserAlias = patchedStreamMarkdownParser?.applied === STREAM_MARKDOWN_PARSER_GUARD_COUNT ? addTemplate({
+      filename: "chat-nuxt/stream-markdown-parser.mjs",
+      write: true,
+      getContents: () => patchedStreamMarkdownParser.source
+    }).dst : void 0;
     nuxt.options.alias = {
       ...nuxt.options.alias,
       "#chat-auth": chatAuthTemplate.dst,
       "#chat-workspace-settings-resolver": workspaceSettingsResolverEntry,
       "#chat-runtime": runtimeDir,
-      "@iconify-json/ph": resolvePackageRoot("@iconify-json/ph")
+      "@iconify-json/ph": resolvePackageRoot("@iconify-json/ph"),
+      ...streamMarkdownParserAlias ? { "stream-markdown-parser": streamMarkdownParserAlias } : {}
     };
     const importsOptions = nuxt.options.imports;
     if (importsOptions !== false) {
@@ -404,10 +446,20 @@ const module$1 = defineNuxtModule({
       });
     }
     nuxt.hook("vite:extendConfig", (config, { isServer }) => {
+      config.resolve = config.resolve || {};
+      if (streamMarkdownParserAlias) {
+        if (Array.isArray(config.resolve.alias)) {
+          config.resolve.alias.push({ find: "stream-markdown-parser", replacement: streamMarkdownParserAlias });
+        } else {
+          config.resolve.alias = {
+            ...config.resolve.alias || {},
+            "stream-markdown-parser": streamMarkdownParserAlias
+          };
+        }
+      }
       if (isServer) {
         return;
       }
-      config.resolve = config.resolve || {};
       config.plugins = config.plugins || [];
       if (Array.isArray(config.resolve.alias)) {
         config.resolve.alias.push(...Object.entries(runtimeAliases).map(([find, replacement]) => ({ find, replacement })));
@@ -451,7 +503,8 @@ export default globalThis.ELK;
         ...nitroConfig.alias,
         "#chat-auth": chatAuthTemplate.dst,
         "#chat-runtime": runtimeDir,
-        "#chat-workspace-settings-resolver": workspaceSettingsResolverEntry
+        "#chat-workspace-settings-resolver": workspaceSettingsResolverEntry,
+        ...streamMarkdownParserAlias ? { "stream-markdown-parser": streamMarkdownParserAlias } : {}
       };
       nitroConfig.publicAssets = nitroConfig.publicAssets || [];
       nitroConfig.publicAssets.push({