@praxisui/ai 8.0.0-beta.30 → 8.0.0-beta.31

package/README.md

@@ -95,9 +95,9 @@ Message-level actions can also be rendered as icon-only controls by setting `ico
 
 `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`.
+`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. Sessions can use the default `presence: 'global-dock'` when the App Shell should render the minimized card, or `presence: 'origin-anchor'` when the owning component keeps the minimized affordance on its original trigger. 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.
+`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 `global-dock` session, and emits the opened session snapshot after promoting that session to active in the registry. Hosts can opt into `includeOriginAnchored=true` for diagnostics or custom shells, but the default respects owner-local minimized affordances. 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.
 
@@ -110,6 +110,17 @@ The shell intentionally does not own component semantics. Specialized flows stil
 
 This keeps a single assistant identity across Praxis components while preserving the canonical owner of each config or authoring document.
 
+### Component Authoring Context
+
+Configurable components that support AI authoring should expose a safe `authoringContract` through `AiConfigAdapter.getAuthoringContext()`. The contract lives at component level, not per capability, and can declare the response modes the component supports:
+
+- `consult/answer` for questions about the current component, such as active resource path, endpoint, schema fields, styling capabilities or how-to guidance.
+- `edit/componentEditPlan` for governed changes that must be compiled and reviewed before they become a patch.
+
+When a component exposes factual grounding for consultative answers, include a `consultativeContext` with the minimal safe facts, such as `resourcePath` and `answerableQuestionKinds`. The frontend must not classify intent through local keywords; it sends this context to the backend/LLM orchestrator, which decides whether the turn is `consult/answer` or `edit/componentEditPlan`. Do not duplicate this declaration on every operation. Individual operations should still describe their own target, effects, validators and materialization through the component manifest or edit-plan contract.
+
+Use `createComponentAuthoringContext(...)` from `@praxisui/ai` when returning the adapter context. The helper normalizes the contract into a JSON-safe object, drops `undefined` fields and rejects non-JSON values before they leak into `contextHints`.
+
 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`.