@aintela/chat

Embeddable AI chat component built on a WebSocket agent gateway. This repo is the standalone home for what was previously packages/library/src/components/AiChat/ in envision-abi — extracted into a real library (built, versioned, peer-dep'd) instead of in-tree source aliasing, and published to the public npm registry.

Name history: @envision/aichat → @aia/chat → @aintela/chat (the npm @aia org was taken). Always install and import @aintela/chat.

Layout

This repo is the published package (@aintela/chat) at its root:

• src/, package.json, vite.config.ts, tsconfig.json — library source + config
• dist/ — built output, gitignored; shipped in the npm tarball (built on prepack/prepare via vite build)
• examples/demo/ — Vite + React SPA that exercises the library against a fake agent gateway, with an option to point at a real WSServer

Develop

npm install
cd examples/demo && npm install && npm run dev    # http://localhost:5174

The demo aliases the package to the root src/ during development so HMR works across the package boundary. To validate the built bundle the way a real consumer would:

npm run build
# then remove the alias in examples/demo/vite.config.ts (or use npm link)

Consuming

@aintela/chat is published to the public npm registry — install it like any package and pin a normal semver range:

npm install @aintela/chat

{
  "dependencies": {
    "@aintela/chat": "^0.2.16"
  }
}

The tarball ships the prebuilt dist/ (see the files field in package.json), so consumers don't build anything on install.

Subpath entry points are exported for focused imports: @aintela/chat (root), plus @aintela/chat/models, /services, /components, /hooks, /utils, /interfaces, and the stylesheet @aintela/chat/style.css.

Every peer in peerDependencies must be installed by the consumer at a compatible version — that's how shared singletons (React, MUI ThemeContext, Zustand stores, reflect-metadata's patched Reflect, notistack's SnackbarProvider) end up as exactly one instance per app instead of two.

Testing

Vitest runs the unit + integration suite. Co-located *.test.ts files live next to the source they cover; shared fixtures + fakes live under tests/ and are imported via the @tests/* path alias.

npm test               # one-shot run
npm run test:watch     # watch mode
npm run test:coverage  # generates coverage/ (html + lcov + json-summary)

VS Code wiring (auto-installed via .vscode/extensions.json):

• Vitest extension surfaces pass/fail gutters next to each it(...) and a tree view in the Test panel.
• Coverage Gutters paints green/red strips on the side of source files once npm run test:coverage has produced coverage/lcov.info. Trigger with "Coverage Gutters: Display Coverage" from the command palette.

Open coverage/index.html in a browser for the drill-down report.

Releasing

Cut a release whenever you ship a behavior change (bugfix, new prop, breaking API change). Publishing is tag-driven: pushing a v<semver> tag runs the publish-aia-chat.yml workflow, which npm publishes to the public npm registry via npm Trusted Publishing (OIDC — no stored token) with build provenance. access: public comes from package.json's publishConfig.

1. Bump + commit + tag + push

From the repo root, after the change is committed on main:

# 1. bump version in package.json (semver: patch / minor / major)
npm version patch --no-git-tag-version    # 0.2.16 → 0.2.17 (bugfix)
# npm version minor --no-git-tag-version  # 0.2.x → 0.3.0 (new prop / feature)
# npm version major --no-git-tag-version  # 0.x.y → 1.0.0 (breaking)

# 2. commit the bump
git add package.json
git commit -m "vX.Y.Z: <one-line summary of what changed>"

# 3. tag the commit + push branch and tag together
git tag -a vX.Y.Z -m "vX.Y.Z — <short release note>"
git push origin main vX.Y.Z

The pushed vX.Y.Z tag triggers CI (npm ci + npm publish --provenance). The tag version and the package.json version must match. You can also run the workflow manually (workflow_dispatch) to publish whatever version is currently in package.json.

--no-git-tag-version on npm version is deliberate: it bumps package.json without creating its own commit/tag, so you control the commit message and tag annotation explicitly (npm's defaults are ambiguous when the bump rides alongside the substantive change).

One-time setup (already done, noted here for recovery): on npmjs.com, the @aintela org / package registers a Trusted Publisher for repo envision-tecnologia/aichat, workflow publish-aia-chat.yml. A token fallback (NPM_TOKEN secret → NODE_AUTH_TOKEN) is stubbed in the workflow if OIDC ever needs to be bypassed.

2. Update consumers

Each consumer bumps its semver range (or just reinstalls, if the existing range already covers the new version):

- "@aintela/chat": "^0.2.16",
+ "@aintela/chat": "^0.2.17",

npm install @aintela/chat

Quick smoke-test before tagging

v0.1.1 shipped with a part-eventType bug that the demo surfaced within seconds. Before pushing a tag, give it a minute:

npm run build && npm run typecheck    # at repo root
cd examples/demo && npm install && npm run dev

Open the Flat tab in the demo, send a prompt, watch the streamed reply render and stay rendered. Switch tabs and back. If anything renders and disappears, the fix isn't ready to tag.

Scope

v0.1 carves the chat-essential subset out of the old library:

• AiChat component + ChatPane + variants (Drawer, Floating)
• AgentGatewayWS + WebSocket connection + event bus
• Session lifecycle (SessionStateManagerService) — with autoCreateSession defaulting to false, opposite of the old default
• LlmResponseRender + EnvironmentProvider + LiveTsxConfigProvider
• Models: Interaction, InteractionPart, ChatSession, ClientMessage, etc.
• Interfaces: ISessionService, IArtifactService, IStorageService — the library ships interfaces, hosts plug in implementations

Out of scope: admin Settings UI, dashboard rendering primitives, viz library, v2 app chrome, the Node/Mongo/Express server bundle. Those live in (or move back to) envision-abi/packages/dashboard-app.