@praxisui/ai 8.0.0-beta.0 → 8.0.0-beta.2

package/README.md

@@ -22,7 +22,6 @@ source_of_truth:
   - "projects/praxis-ai/README.md"
   - "projects/praxis-ai/docs/ai-deployment-flow.md"
 related_docs:
-  - "core-public-surfaces-guide"
   - "host-integration-guide"
 ---
 
@@ -62,10 +61,65 @@ Peer dependencies (Angular v20):
 ## What this package is responsible for
 
 - assistant UX surfaces and interaction flow
+- reusable assistant shell primitives such as conversation messages, quick replies, prompt composer, apply actions and drag/resize chrome
 - backend API orchestration for provider catalog, suggestions, and patch generation
 - local lightweight session history with tenant/env/user scoping
 - confirmation and risk policy integration for sensitive changes
 
+`PraxisAiAssistantShellComponent` is the reusable shell for specialized authoring flows that own their own backend contract, such as Page Builder agentic authoring. It provides the conversational chrome and emits UI events; it does not resolve intent, call providers, compile Praxis JSON, or persist page configuration.
+
+### Canonical assistant shell
+
+`PraxisAiAssistantShellComponent` is the canonical chrome for Praxis assistant experiences that need a conversational surface. Hosts should prefer it for new specialized flows instead of creating component-local assistant UI.
+
+The shell owns the shared UX primitives:
+- conversation messages and message actions such as edit/resend/custom actions
+- prompt composer, Enter-to-submit behavior, pasted or selected file attachments, submit/apply actions and attach/remove attachment events
+- active context chips for component, schema, selection, route, tenant or custom context
+- attached context metadata for files, images, JSON, schema and text payloads
+- mode and state labels for `config`, `agentic-authoring`, `chat`, `diagnostic`, `review` and `inline-help`
+- draggable/resizable panel layout and accessibility labels
+
+The shell intentionally does not own component semantics. Specialized flows still own their adapter/service contract:
+- configuration assistants continue to use `AiConfigAdapter`, capabilities, suggestions and patch review
+- Page Builder agentic authoring continues to use `/api/praxis/config/ai/authoring/**`
+- future metadata/editorial flows should provide their own preview/apply contract while reusing the same shell chrome
+
+This keeps a single assistant identity across Praxis components while preserving the canonical owner of each config or authoring document.
+
+The shell ships with centralized PT-BR default labels and accepts the `labels` input for a flow-specific override. The override is partial: omitted labels continue to come from the shared defaults.
+
+By default, the prompt composer submits with `Enter` and keeps `Shift+Enter` for multiline prompts. Hosts with custom composer behavior can set `submitOnEnter` to `false`.
+
+When a user pastes an image into the prompt composer, the shell emits `attachmentsPasted` with `PraxisAssistantShellAttachment` items containing the original `File`, image metadata, `source: 'paste'` and a local preview URL.
+
+Hosts can also enable button-based file selection with `enableFileAttachments`, `attachmentAccept` and `attachmentMultiple`. In that mode, the attach button opens the native file picker and emits `attachmentsSelected` with `source: 'file-picker'`. When file selection is disabled, the legacy `attach` event remains available for host-defined context actions. The shell does not upload or persist files; the host owns storage, redaction and backend forwarding.
+
+Flows that forward attachments to backend authoring endpoints should send only serializable attachment summaries, such as `id`, `name`, `kind`, `mimeType`, `sizeBytes`, `source` and `hasPreview`. Do not send `File`, bytes, base64 payloads or local `blob:` URLs to the assistant contract. When a backend clarification needs to keep attachment context for the next turn, the flow can return those summaries inside `pendingClarification.diagnostics.attachmentSummaries`; the turn orchestrator preserves that pending clarification state and sends it back with the next `clarify` action.
+
+### Conversation turn orchestration
+
+`PraxisAssistantTurnOrchestratorService` is the canonical frontend coordination layer between the shell and specialized assistant flows. It creates a per-host controller so state is not shared globally between components.
+
+The orchestrator owns the turn lifecycle:
+- user prompt capture and conversation messages
+- stable `sessionId` creation per controller when the host does not provide one
+- fresh `clientTurnId` creation for each executable submit/apply/retry/cancel turn
+- LLM-assisted clarification as a first-class `clarification` state
+- structured clarification questions and quick replies
+- edit/resend actions for user messages, including conversation fork semantics
+- attached context add/remove state
+- apply/retry/cancel dispatch when the active flow supports it
+- normalized shell state for `idle`, `processing`, `clarification`, `review`, `applying`, `success` and `error`
+
+The orchestrator remains flow-agnostic. Each consumer provides a `PraxisAssistantTurnFlow` for its mode. For example, a config assistant flow can wrap `AiConfigAdapter` plus `/api/praxis/config/ai/patch`, while Page Builder agentic authoring can wrap `/api/praxis/config/ai/authoring/**`.
+
+When a flow asks for clarification, direct user input while the controller is in `clarification` state is sent to the flow as a `clarify` action with the pending clarification context. Hosts should not rewrite short answers locally; they should pass the request context through to the backend or flow that owns the authoring semantics.
+
+`pendingClarification.diagnostics` is opaque flow state. It is preserved across the next clarification answer so backend-owned semantics can keep metadata-only context, including attachment summaries, without the shell understanding the domain or retaining local file payloads.
+
+When a user edits or resends an earlier user message, the controller forks the conversation from that message before invoking the flow again. Downstream assistant/user messages, quick replies, pending clarification and preview state are cleared so the backend receives the revised conversation branch instead of stale follow-up context. Hosts that expose an edit composer should call `submitEditedMessage(messageId, text)` when the revised prompt is submitted.
+
 ## What this package does not own
 
 - direct provider SDK integration when the backend contract already exists
@@ -84,6 +138,15 @@ ng test praxis-ai
 
 The UI uses the backend orchestration endpoints instead of calling providers directly.
 
+### Host integration tokens
+
+Hosts configure tenant/env/user headers and global AI config through the `@praxisui/ai` tokens exported by the package:
+
+- `AI_BACKEND_STORAGE_OPTIONS`: provides `headersFactory`, optional `defaultHeaders`, and the explicit `allowLocalIdentityFallback` demo mode.
+- `AI_BACKEND_CONFIG_STORE`: provides `getAiConfigSnapshot`, `aiConfigChanges$`, and `saveAiConfig` for provider/model/global AI settings.
+
+The library does not consume `@praxisui/core` storage tokens as a hidden fallback. Host applications should wire the AI tokens directly when integrating with `/api/praxis/config/ai/**`.
+
 ### Provider catalog and validation
 - `GET /api/praxis/config/ai/providers/catalog`
 - `POST /api/praxis/config/ai/providers/models`