feat(platform): @base44/platform/react, option A: the hook only - #315

Option A of two. This PR ships only the hook. base44/javascript-sdk#314 is option B: the same hook plus a provider and replaceable parts. Only one of the two will be merged.

Start here: examples/react-chat/ is Tiny Sunny's chat rebuilt on this option: Chat.tsx is the chat, chatParts.tsx its look, server.ts the four backend calls. It imports the package from the workspace, so the diff there is only new files.

What

A new subpath of the platform package, @base44/platform/react, with one hook: useBase44Chat. It runs a white-label builder chat for one app on top of the existing client and renders nothing. The partner draws everything.

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

const chat = useBase44Chat({ appId, server, onAppCreated });
// chat.items, chat.phase, chat.error, chat.canSend, chat.send(), chat.create(), chat.clearError()

• Items made for rendering. chat.items is the conversation, oldest first: role, text, steps (one per tool call) and, while the builder waits, a question.
• Questions bound to their actions. A question is a union on kind (choice, input, approval, unknown) and carries only the actions its kind allows, each bound to its own tool call. A component can only answer the question it renders, also when several are open.
• server: four calls the partner implements, in any language behind them (createApp, openLiveSession, sendMessage, submitToolCallInput). No credential reaches the browser.
• phase and error instead of pre-worded status text; canSend is false while a question is open, because Base44 drops a message sent into a stopped turn.
• Actions never throw. A failure lands in error; a question whose reply failed opens again.

Packaging

• exports["./react"] plus typesVersions for node10 resolution.
• react is an optional peer; the root entry does not 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.

Where it comes from

The engine of the headless chat library prototyped in base44/base44-platform-starter#64 (Tiny Sunny), after Ronny's review there: bound question actions, send/create split, { phase, error }, explicit public types, server behind a ref.

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.
• tests/types/react.types.ts and examples/react-chat/: compile against the subpath, JSX included.
• tests/package.test.mjs: the published /react entry resolves at runtime and under NodeNext, Bundler and Node resolution.

🤖 Generated with Claude Code