@praxisui/rich-content 8.0.0-beta.1 → 8.0.0-beta.12

package/README.md

@@ -61,6 +61,17 @@ settings-panel editor for `praxis-rich-content`. Hosts such as
 `@praxisui/page-builder` should open this editor from the component metadata
 instead of creating local rich-content JSON editors.
 
+The canonical editor provides structured block authoring for common top-level
+nodes (`text`, `badge`, `icon`, `image`, `metric`, `progress`, `compose`,
+`link`, `card`, `mediaBlock`, `timeline` and `preset`), including add, reorder, inline
+removal confirmation and field-level editing. It also supports nested authoring
+for `card.content[]`, `compose.items[]` and `timeline.items[]`, plus governed
+preset selection from `PRAXIS_RICH_BLOCK_PRESETS`. Common node metadata such as
+`testId`, `className`, a simple `visibleWhen` equality rule and one safe inline
+style declaration can be edited visually. Advanced JSON remains available for
+less common nested fields and deep structures, but it is no longer the only
+authoring path.
+
 The editor receives the widget input envelope and returns the same canonical
 shape expected by the runtime:
 
@@ -85,6 +96,34 @@ Authoring labels, helper text and validation messages use the rich-content i18n
 dictionary. Apps can provide overrides with `providePraxisRichContentI18n()` or
 reuse `resolvePraxisRichContentText()` when extending the canonical editor.
 
+The editor validates the public `RichContentDocument` contract before
+Apply/Save. Hosts that need the same checks outside the settings panel can use
+`validateRichContentDocument()` from `@praxisui/rich-content` to reject
+unsupported document versions, unknown node types, unsafe URLs, unsafe style
+values and malformed nested nodes before persistence.
+
+## Agentic Authoring Contract
+
+`@praxisui/rich-content` publishes an executable `ComponentAuthoringManifest`
+through `PRAXIS_RICH_CONTENT_AUTHORING_MANIFEST`.
+
+The manifest treats rich content as structured `RichContentDocument` data, not
+HTML or markdown patches. It governs document replacement, block add/remove,
+block order, text updates, canonical link nodes, common node metadata,
+`mediaBlock` fields, `timeline.items[]`, preset refs and sanitization policy.
+Security-sensitive policy edits and destructive removals require confirmation
+before a patch can be compiled.
+
+Link authoring uses a first-class `link` node with `label`, `href`, `target`
+and `rel`; unsafe protocols are rejected by `validateRichContentDocument()`.
+
+Each operation declares its own editable target resolver, ambiguity policy,
+preconditions, validators, affected paths, effects and typed submission impact.
+Document, block, text, link, media, timeline, preset, metadata and sanitization
+operations are `config-only` because they edit the structured widget input
+contract. `display.mode.set` is `visual-only` because it changes `layout` and
+`rootClassName` without mutating the `RichContentDocument`.
+
 ## Layout Modes
 
 The component defaults to `layout="block"` to preserve document-style rendering.