@praxisui/ai 8.0.0-beta.99 → 9.0.0-beta.0

package/README.md

@@ -37,20 +37,27 @@ Short mental model:
 
 ## Documentation
 
-- Official documentation: https://praxisui.dev
+- Official documentation: https://praxisui.dev/components/ai
+- AI docs: https://praxisui.dev/docs/ai
 - Quickstart reference app: https://github.com/codexrodrigues/praxis-ui-quickstart
+- Live Praxis UI demo: https://praxis-ui-4e602.web.app
 - Recommended for: Angular hosts that need AI-assisted configuration flows with provider orchestration and enterprise guardrails
 
 ## Install
 
 ```bash
-npm i @praxisui/ai
+npm i @praxisui/ai@beta
 ```
 
-Peer dependencies (Angular v20):
-- `@angular/core` `^20.3.0`
-- `@angular/common` `^20.3.0`
-- `@praxisui/core` `^1.0.0-beta.61`
+Peer dependencies:
+- `@angular/core` `^21.0.0`
+- `@angular/common` `^21.0.0`
+- `@angular/cdk` `^21.0.0`
+- `@angular/forms` `^21.0.0`
+- `@angular/material` `^21.0.0`
+- `@google/generative-ai` `^0.24.1`
+- `@praxisui/core` `^9.0.0-beta.0`
+- `rxjs` `~7.8.0`
 
 ## When to use
 
@@ -58,6 +65,38 @@ Peer dependencies (Angular v20):
 - Centralize provider and model validation behind backend-controlled endpoints
 - Apply tenant-aware confirmation and risk policies in enterprise environments
 
+## Minimal standalone shell
+
+Use the shell for governed assistant UX. The host still owns the backend flow,
+safe context, storage, and apply semantics.
+
+```ts
+import { Component } from '@angular/core';
+import { PraxisAiAssistantShellComponent } from '@praxisui/ai';
+
+@Component({
+  selector: 'app-ai-assistant-entry',
+  standalone: true,
+  imports: [PraxisAiAssistantShellComponent],
+  template: `
+    <praxis-ai-assistant-shell
+      mode="agentic-authoring"
+      state="idle"
+      [messages]="messages"
+      [contextItems]="contextItems"
+      (submitPrompt)="submitPrompt($event)" />
+  `,
+})
+export class AiAssistantEntryComponent {
+  messages = [];
+  contextItems = [{ label: 'Surface', value: 'Page Builder' }];
+
+  submitPrompt(prompt: string): void {
+    // Forward to the backend-owned Praxis Config AI flow.
+  }
+}
+```
+
 ## What this package is responsible for
 
 - assistant UX surfaces and interaction flow
@@ -150,6 +189,8 @@ The orchestrator owns the turn lifecycle:
 
 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 `@praxisui/core` runtime component observations are registered, the orchestrator attaches them to `PraxisAssistantTurnRequest.runtimeComponentObservations` as untrusted frontend evidence. Stream clients forward non-empty observations with `runtimeComponentObservationTrustBoundary="untrusted_frontend_observation"`. This field is transport-only in `@praxisui/ai`: it does not resolve intent, promote capabilities, select quick replies, alter previews or bypass backend grounding.
+
 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.
@@ -264,6 +305,8 @@ Notes:
 
 `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.
 
+`AgenticAuthoringTurnClientService` is the shared client for assistant turn flows that consume this canonical stream. It starts the turn, connects SSE and exposes two levels: `streamEvents()` for component flows that already own rich preview/apply semantics, and `streamTurn()` for flows that can consume normalized `PraxisAssistantTurnResult` values directly. The client can emit shared lifecycle status for silent streams, enforce a terminal-result timeout and surface transport lifecycle events such as probe readiness, transport opening and first-event receipt. `AiBackendApiService.connectAgenticAuthoringTurnStream` also falls back to `fetch` SSE parsing when `EventSource` is unavailable. Per-call `baseUrl` and header overrides allow component services with existing endpoint options to migrate without losing host configuration. Component-specific flows should use this shared client when migrating away from `/patch`, then add only component-owned context assembly and apply semantics locally.
+
 ## Assistant local history (UI)
 
 The assistant stores a lightweight local history in the browser using `localStorage`. It is scoped by