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

package/README.md

@@ -61,7 +61,7 @@ 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
+- reusable assistant shell primitives such as conversation messages, quick replies, prompt composer, governed actions, viewport-level drag/resize chrome, layout restore and minimized-session dock
 - 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
@@ -72,13 +72,36 @@ Peer dependencies (Angular v20):
 
 `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.
 
+`PraxisAiAssistantComponent` remains exported only as a compatibility surface for older configuration-assistant integrations. New Praxis components, demos and cockpit flows should use `PraxisAiAssistantShellComponent` with `PraxisAssistantTurnOrchestratorService` and, when the assistant can be minimized or resumed, `PraxisAssistantSessionRegistryService`.
+
 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
+- rich quick reply chips with optional description, icon, tone and structured context hints
 - 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
+- viewport-level draggable/resizable panel layout, pointer-only resize handles, layout restore, minimize affordance and accessibility labels
+
+The shell is a viewport-level assistant surface, not a component-bounded popover. A component trigger opens the assistant with local semantic context, but the panel can move across the page, resize from any edge or corner, and be restored to its initial safe layout through the shared "Restaurar posição do assistente" affordance. The default close affordance is "Minimizar assistente" because specialized hosts usually preserve the governed session through `PraxisAssistantSessionRegistryService`; hosts that truly close/discard the session may override the label.
+
+The assistant chrome belongs to the platform, not to the component that opened it. Hosts should provide contextual labels, mode, state and context chips, while `PraxisAiAssistantShellComponent` keeps the shared visual hierarchy: assistant identity first, contextual title/subtitle second, and operational mode/state as compact metadata. Component-specific styling should not make the shell look owned by Page Builder, Table, Dynamic Form or any other individual runtime.
+
+Composer actions are state-aware. The primary action changes from "Interpretar pedido" to clarification, review, applying, success or error labels according to the current turn state. Secondary recovery actions such as retry and cancel are surfaced by the shell when the active turn can be recovered, while hosts still own the flow-specific semantics.
+
+Hosts can render the primary action as icon-only with `iconOnly=true` when that matches modern LLM chat composer conventions. The action must still provide a semantic `label` or `ariaLabel`; the shell uses it for accessibility and tooltip text while omitting the visible label.
+
+Message-level actions can also be rendered as icon-only controls by setting `icon` or `iconOnly=true` on `PraxisAssistantShellMessageAction`. Built-in `edit`, `resend` and `copy` actions use `edit`, `replay` and `content_copy` icons by default, with the visible label moved to tooltip and `aria-label`.
+
+`PraxisAiAssistantDockComponent` is the companion minimized-session surface for the same assistant identity. Hosts use it when a specialized assistant session remains active but the full shell is minimized. The dock owns the shared visual language for assistant presence, state badges and reopen affordance; hosts still provide the semantic session summary and decide what reopening means.
+
+`PraxisAssistantSessionRegistryService` is the canonical in-memory registry for assistant sessions opened by different Praxis components in the same application shell. Component hosts register their active or minimized sessions with stable `ownerId`/`ownerType` metadata so a global assistant host can present one shared experience while preserving each component's semantic context. The registry accepts an optional `PraxisAssistantContextSnapshot`, normalizes it before storage and rejects snapshots whose `identity.sessionId`, `identity.ownerId` or `identity.ownerType` do not match the session descriptor. Components that already have a canonical context snapshot should prefer the context helpers: `upsertContextSession`, `openContextSession`, `minimizeContextSession`, `getContextSession` and `removeContextSession`.
+
+`PraxisAiAssistantSessionHostComponent` is the canonical presence host for minimized assistant sessions in an application or page shell. It reads `PraxisAssistantSessionRegistryService`, renders the shared dock for each minimized session, and emits the opened session snapshot after promoting that session to active in the registry. Specialized components still own the full shell events until their authoring action contracts are promoted to shared platform contracts.
+
+`PraxisAssistantContextSnapshot` is the canonical, UI-agnostic context contract for intelligent Praxis components. It represents safe assistant context: stable identity, current target, context chips, manifest reference, resource/schema hints, digests, governance hints, attachment summaries and declarative action contracts. It is intentionally not a raw component payload. Hosts should normalize snapshots with `normalizePraxisAssistantContextSnapshot` before storing them in a registry, passing them between components or using them as a handoff boundary.
+
+Context snapshots must not contain full configs, form values, table rows, `currentState`, `runtimeState`, `pendingPatch`, arbitrary diagnostics, `File`, bytes, base64 or local `blob:` preview URLs. Use `dataProfileDigest`, `runtimeStateDigest`, `schemaFields` and `PraxisAssistantAttachmentSummary` instead. `@praxisui/ai` can declare handoff actions such as `shared-rule-handoff`, `governed-publication-handoff`, `materialization-handoff` and `enforcement-validation-handoff`, but the executable semantics of approving, publishing, materializing or enforcing domain rules belong to Praxis Config/domain-rules contracts.
 
 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
@@ -93,7 +116,7 @@ By default, the prompt composer submits with `Enter` and keeps `Shift+Enter` for
 
 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.
+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. Hosts that do not support attachment semantics should set `showAttachAction=false`; hosts that do not support pasted image context should set `enablePastedAttachments=false`. 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.
 
@@ -106,7 +129,7 @@ The orchestrator owns the turn lifecycle:
 - 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
+- structured clarification questions and quick replies, including rich chip metadata from backend flows
 - 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
@@ -118,6 +141,8 @@ When a flow asks for clarification, direct user input while the controller is in
 
 `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.
 
+Backend-owned flows may return quick replies as clickable chips for candidate resources, catalog follow-ups or clarification options. Hosts should keep the full quick reply object: `description`, `icon` and `tone` are presentation hints, while `contextHints` carries structured values such as `resourcePath`, `submitUrl`, `operation` and `schemaUrl` for the next turn. Do not downcast these replies to label/prompt pairs or recompute the options in the UI.
+
 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
@@ -193,6 +218,24 @@ Notes:
 - `currentState` must be the config root (not wrapped under `config`).
 - Clarifications may return `{ type: "clarification", message, options }`.
 
+### Agentic authoring manifest tools
+- `GET /api/praxis/config/ai/authoring/manifests/{componentId}`
+- `GET /api/praxis/config/ai/authoring/manifests/{componentId}/editable-targets`
+- `GET /api/praxis/config/ai/authoring/manifests/{componentId}/operations`
+- `POST /api/praxis/config/ai/authoring/manifests/{componentId}/resolve-target`
+- `POST /api/praxis/config/ai/authoring/manifests/{componentId}/validate-plan`
+- `POST /api/praxis/config/ai/authoring/manifests/{componentId}/compile-patch`
+
+`AiBackendApiService` exposes these endpoints through typed methods so hosts can inspect the executable manifest, resolve targets, validate a component edit plan and compile a backend-owned patch without routing by local keywords.
+
+### Agentic authoring turn streaming
+- `POST /api/praxis/config/ai/authoring/turn/stream/start`
+- `GET /api/praxis/config/ai/authoring/turn/stream/{streamId}`
+- `GET /api/praxis/config/ai/authoring/turn/stream/{streamId}/probe`
+- `POST /api/praxis/config/ai/authoring/turn/stream/{streamId}/cancel`
+
+`AiBackendApiService.startAgenticAuthoringTurnStream`, `connectAgenticAuthoringTurnStream` and `cancelAgenticAuthoringTurnStream` use the same SSE envelope contract as patch streaming. Browser `EventSource` cannot send custom headers, so signed stream tokens returned by the backend should be passed to `connectAgenticAuthoringTurnStream` and `cancelAgenticAuthoringTurnStream` when the backend uses signed-url stream auth.
+
 ## Assistant local history (UI)
 
 The assistant stores a lightweight local history in the browser using `localStorage`. It is scoped by