[amitbardos]

Start here: src/react/chat.types.ts is the whole public surface, and useBase44Chat.ts the hook. Usage lives in their JSDoc @example blocks, which the Mintlify pipeline turns into the reference's Example tabs.

What

A new subpath, @base44/platform/react, with one hook: useBase44Chat. It runs the AI chat for one app in the partner's own UI, on top of the platform client, and renders nothing. The contract is the one in the design doc "Partner chat: design".

import { useBase44Chat } from "@base44/platform/react";

const chat = useBase44Chat({ appId, backend, onAppCreated });
// chat.items, chat.status, chat.connection, chat.error, chat.send(), chat.create(), chat.clearError()

• backend: four calls the partner implements (createApp, openLiveSession, sendMessage, submitToolCallInput), in any language behind them. openLiveSession returns Base44's socket-session body unchanged, and the client calls it again on every renewal. No credential reaches the browser.
• items: the conversation, oldest first: role, text, createdAt, pending and steps, one per tool call (tool, files, label, status). A sent prompt shows at once with pending: true until Base44's own message arrives, matched by exact text.
• Questions: only the last assistant message makes the chat wait, as in Base44's builder, and only its waiting steps carry a question (choice, secrets, approval), bound to its own tool call. A choice answers with picked labels and optional free text (custom_text), sent the way the builder sends them. Every kind can be declined; a kind this release doesn't know is declined once per tool call.
• status: error > waiting > building > submitted > ready. A failed build is error with code build_failed. submitted runs from the call until Base44 reports a newer status, a reply or a queue change, or an answered call stops waiting.
• connection: connecting until the first snapshot, then connected, and disconnected once live updates stop for good, with error saying why. A reconnecting state needs a client callback and comes in its own PR.
• Apps: send(prompt) needs an app; create(prompt) makes one, and while appId is null the chat follows the app it made. A set appId always wins.
• Resilience: rejoins keep messages older than the snapshot's window; a status older than the newest seen is ignored, since Base44 resends an earlier turn's; a call that fails after the chat switched apps leaves the new app alone.
• Actions never throw: a failure lands in error; a question whose answer failed opens again.

Not in this PR: showing or editing Base44's prompt queue, a reconnecting state, and loading messages older than the last 50. The design doc's Next section lists them.

Packaging

• exports["./react"] plus typesVersions for node10 resolution.
• react is an optional peer; the client and server entries never import it. The tarball test asserts it is never a dependency.
• React, react-dom, their types and jsdom are devDependencies, for the hook tests only.

Tests

• tests/unit/react/chat-items.test.ts: the message-to-items mapping, without React.
• tests/unit/react/useBase44Chat.test.ts: the hook under jsdom with a recorded platform client: status precedence, pending prompts, stale statuses, renewal, switching apps, answers and automatic declines.
• tests/types/react.types.ts: compiles against the subpath.
• tests/package.test.mjs: the published /react entry resolves at runtime and under NodeNext, Bundler and Node resolution.

🤖 Generated with Claude Code

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.54-pr.315.e54dc54

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/sdk:

npm i "@base44/sdk@npm:@base44-preview/sdk@0.8.54-pr.315.e54dc54"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.54-pr.315.e54dc54"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.54-pr.315.e54dc54
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[github-actions]

🚀 Package Preview Available! (@base44/platform)

---

Install this PR's preview build with npm:

npm i @base44-preview/platform@0.2.0-pr.315.e54dc54

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/platform:

npm i "@base44/platform@npm:@base44-preview/platform@0.2.0-pr.315.e54dc54"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/platform": "npm:@base44-preview/platform@0.2.0-pr.315.e54dc54"
  }
}

• 📦 Preview Package: @base44-preview/platform@0.2.0-pr.315.e54dc54
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[ozsay]

The public contract
Fields the socket already sends that the hook drops. All are in builder.events.generated.ts; adding them is additive. Inspired by comparing the contract with AG-UI.

Ids and links

• StatusObject.turn_id: the turn the status belongs to (AG-UI's run id). Could be Base44Chat.turnId and ChatItem.turnId.
• additional_message_params.client_creation_id: lets a pending prompt be matched by id, not text (see the pending-prompt finding).
• Message.checkpoint_id: the app before or after a turn. Enables "restore to here" UIs.
• Questions: expose toolCallId and messageId as data next to the bound methods, so items can be logged or stored.

Steps

• display.summary (bash, exec, screenshot, shell), display.entity_name and record_count, arguments.summary for entity updates and deletes: far better labels than tool name plus files.
• results on media tools (ImageResult with image_url and status) and the image.resolved event: show generated images.
• task.progressed (current, total, percentage, keyed by tool_call_id): a progress bar on a running step.
• auto_approved and mutation_applied on every call: an "auto-approved" badge and "no changes made".
• display.writes_entities: tells a partner to refresh the preview.

Questions

• QuestionAnswer.custom_text and Question.type: the choice answer can only send picked labels, so a free-text question cannot be answered.
• user_input on question calls: what was answered stays visible after the question closes; today the question disappears.
• Approval guard and details (entity_name, change_type, changed_ops, function_name, method, inspection_failed): the approval exposes only the tool name and a reason.
• Question.covers with UpdatePlanArguments, PrdArguments and the plan_mode / plan_approved message flags: everything a plan-mode UI needs.

Chat-level state and events

• snapshot.queue and queue.updated (items, is_paused): the queue, and why a pending prompt waits (the builder pauses it while a question is open). The description defers the queue to another PR.
• preview.reload_requested, preview.navigation_requested and files.changed: partners embedding a preview need these, and today only the raw client gives them.

Not candidates: system role (never sent), text deltas (messages are replaced whole).

[amitbardos]

@ozsay thanks, the AG-UI comparison was useful. On the fields the hook drops, I took the ones without which a partner's chat breaks or misleads, and left the rest until a partner asks: adding a field later is free, and taking one out after release breaks partners.

Added

• Free-text answers (9035fc7): answer(picked, texts?) sends custom_text, and ChoiceEntry.type says which questions take only text. Answers now also go out the way Base44's builder sends them, one pick in selected_label, several in selected_labels: Base44 reads a design or palette pick only from selected_label.
• Approval guard and details (c77c79d), so the user sees what they approve.
• ChatStep.answered from user_input, so the history keeps what was answered after the question closes.
• label uses Base44's own description of the step (display.summary, arguments.summary), then the entity and record count, then the tool and files. A separate summary field was left out: label already shows it.

Left for later

• toolCallId / messageId on questions, turn_id, checkpoint_id: nothing needs them yet.
• Media results with image.resolved, and task.progressed: each needs new event handling and state; worth it once a partner draws images or progress.
• Preview events: needs a decision on how the hook exposes them.
• Plan mode: approving a plan goes through Base44's private /exit-plan-mode, so it can't be built on the public API yet.
• The queue: its own PR, with remove and edit.

Could you take another look?

🤖 Generated with Claude Code

[ozsay]

Thanks @amitbardos, re-reviewed at 5ffd6d3. All five comments are fixed, and each fix has a test:

• Status stuck at submitted: the answer's submission ends once its call stops waiting, and any newer status ends it too.
• Description: now matches the code (three connection states; reconnecting in its own PR).
• Failures after an app switch: send, answer and create check the app they ran for before touching state.
• Another client's prompt settling ours: exact text match only.
• Hidden prompt after create with a set appId: the prompt is dropped.

The new fields (free-text answers, selected_label vs selected_labels, approval guard/details, answered, the richer label) read well. Leaving the rest until a partner needs it makes sense.

One low-severity edge in the exact-match fix. The removed fallback was also the only way out for a pending prompt whose text never arrives. Base44 keeps the text as sent for a plain send, but the public queue API can edit (PUT /queue/{item_id}) or delete a queued prompt. An edited prompt arrives with different text, and a deleted one never arrives. Either way our pending item now stays until the app changes. Nothing in this PR edits the queue, so this belongs in the queue PR: settle or drop pending prompts from queue.updated (an item that left the queue without a matching message).

On client_creation_id: the send endpoint already accepts it today, inside the undocumented additional_message_params, and it comes back on the socket. It is hidden from the public spec, so I wouldn't build on it yet. Asking the backend to make it a documented field would let pending prompts match by id and remove the text matching entirely.

Nits (no change needed):

• A single-select answer() given several labels sends only the first, silently. A line in the JSDoc would cover it.
• Once an answer is taken, the submission clears even if a send went out after the answer, so status can read ready a moment early.

🤖 Generated with Claude Code