Praxis Charts Authoring Settings
Use this skill for chart config editors and their Settings Panel hosts. The editor materializes canonical x-ui.chart decisions; it does not own business rules, analytics capabilities, persistence infrastructure, or an ECharts-shaped configuration language.
Pair it with:
praxis-settings-panel-shell for shell, footer, close, drawer, and SettingsValueProvider protocol defects.
praxis-settings-roundtrip-authoring for shared apply/save/reset/reopen invariants.
praxis-authoring-editors and praxis-ui-product-design for transversal editor governance and visual UX changes.
praxis-charts-authoring-catalogs for resource, field, target, capability, and preview catalog grounding.
praxis-charts-runtime-data and praxis-charts-analytics-interactions for mapper, stats, queryContext, and runtime consumption.
praxis-charts-ai-validation and praxis-charts-ai-handler-contracts when visual paths, component metadata, or executable manifest operations change.
praxis-charts-echarts-engine-boundary only for preview/runtime engine materialization.
Canonical Owners
praxis-metadata-starter/docs/spec/x-ui-chart.schema.json owns the published structural x-ui.chart vocabulary and version. Do not advance an Angular editor default independently from that schema.
@praxisui/charts owns PraxisXUiChartContract, normalization, validation, editor semantics, runtime mapping, preview, component metadata, and chart authoring manifest alignment.
@praxisui/settings-panel owns Apply/Save/Reset/Cancel gating and obtains values from SettingsValueProvider.
- The dynamic Page Builder/core widget host owns opening
ComponentDocMeta.configEditor, replacing widget inputs from the returned envelope, and persisting the page definition.
praxis-config-starter or the declared host storage owns governed persistence, ETag, approval, and publication. A chart editor does not write storage directly.
- Backend metadata, schemas, analytics projections, option sources, and capabilities own which resources, fields, operations, metrics, and targets are authorable.
Editor Envelope And Owner Boundaries
PraxisChartConfigEditor owns the canonical chart document. PraxisChartWidgetConfigEditor wraps that editor with the existing { inputs } contract for document, local data and query context; both the direct runtime host and Page Builder consume this wrapper.
Direct runtime chart
PraxisChartComponent.openConfigEditor() hosts PraxisChartWidgetConfigEditor with separate inputs and transient catalog context. Apply/Save returns { inputs }, preserving chartDocument, derived local data and queryContext as separate owner inputs:
runtime owner inputs -> widget editor -> { inputs } -> applied$/saved$ -> document/data/context runtime -> owner patch
Apply updates the preview/runtime without closing. chartDocumentApplied and chartDocumentSaved still emit only PraxisXUiChartContract; chartDocumentPatchChange.inputPatch carries the complete changed input fields. Consume that existing patch in the external owner to persist data/context as well as the document. Explicit null clears stale data/query-context precedence when removed; praxis.stats must not continue using local rows. Do not move rows into ChartContract, invent another event envelope, or claim durability from an emitted patch.
Treat document/config/data/query-context as one owner scope. Accumulate the latest expected acknowledgement per field across accepted patches, retaining fields omitted by a later patch. Accept equivalent or partial acknowledgements of those latest values without discarding the remaining local fields. The host must apply patches in order: without an epoch/revision in the existing contract, an old acknowledgement of A after B for the same field is indistinguishable from an intentional external change back to A, so the owner wins. Do not promise out-of-order acknowledgement delivery or invent history-based suppression of owner changes.
Recheck ownership after context awaits and before Apply/Save, even before change detection. Closing/destroying the session releases its subscriptions; late events cannot overwrite a newer owner. Prove local rows through real editor Apply/Save, runtime accessible data and reopen, plus Reset/Cancel, stats transition, partial owner echoes across Apply/Save and external replacement.
When a shell action invokes command: "openConfigEditor", route by the stable command rather than the authored action id or label. Query live availability from the chart owner: customization enabled, Settings Panel bridge present, canonical document present, context resolution complete, and owner still alive. These explanations are localized presentation state, not backend authorization, and must not enter chartDocument.
Context resolution can outlive the component or its customization session. Recheck eligibility after every asynchronous boundary, pass the chart DestroyRef as the transient Settings Panel owner, and release Apply/Save subscriptions on destruction. A late result must not open a panel or materialize another document patch after the chart owner disappears.
Dynamic widget/Page Builder
ComponentDocMeta.configEditor points to PraxisChartWidgetConfigEditor. The widget host passes one inputs object and accepts either an { inputs } envelope or a legacy bare object, then replaces the widget's complete input object:
widget.definition.inputs -> PraxisChartWidgetConfigEditor -> { inputs } -> apply/save -> complete widget input replacement -> page persistence -> reopen
Therefore the widget editor must preserve every unrelated input deliberately, update inputs.chartDocument and inputs.queryContext, and remove only inputs whose precedence would be wrong. For source.kind = "praxis.stats", remove stale local inputs.data; do not silently delete shell or host inputs.
Treat preserved inputs.data as local/derived runtime data only. It may be kept for legacy or source.kind = "derived" widgets, but when the canonical chartDocument.source.kind is praxis.stats, local rows must not remain as a palette/sample fallback, backend proof, capability evidence, or substitute for the stats request. If a host still needs sample data for an authoring preview, keep it in transient editor context or preview state, not in the persisted widget inputs envelope.
Initialization And Baselines
PraxisChartConfigEditor may initialize from its documented component input or SETTINGS_PANEL_DATA compatibility shape. Keep one canonical input name and do not rely on passing duplicate aliases that the Settings Panel filters out.
- Normalize a cloned external document into both current state and the reset baseline. Controlled normalization drift must be tested and documented; unknown canonical fields must not disappear accidentally.
- New documents must use the version published by the metadata schema and accepted by the manifest/validator. As of the current draft this is
0.1.0; a local 1.0.0 default is not a version migration.
- A widget with only runtime
config/data has no canonical authoring document. Do not fabricate a generic chart document on save and let it take precedence over the existing chart. Prefer canonical chartDocument insertion defaults; otherwise require an explicit, tested PraxisChartConfig -> PraxisXUiChartContract migration or block authoring with a diagnostic.
- Preserve a separate baseline for
queryContext and every widget-owned editable input. Reset must restore the entire editor scope, not only the nested chart document.
- When external inputs change while clean, rebase all baselines. Do not overwrite dirty local work silently.
SettingsValueProvider Semantics
isDirty$, isValid$, and isBusy$ are authoritative shell signals. Compose child editor and widget-level state without losing either source.
getSettingsValue() powers Apply and must be side-effect free: it returns the current canonical value but does not mark it saved or replace the reset baseline.
onSave() may finalize the same value, then establish the saved baseline. It must not return a different envelope from Apply.
reset() restores the opening/saved baseline for chart document, queryContext, errors, dirty, valid, and busy state. It must be idempotent.
- Invalid state should prevent shell actions, but value methods should still fail predictably rather than leaking an unhandled
JSON.parse exception if invoked programmatically.
- Do not add local Apply/Save gating or persistence calls to compensate for Settings Panel behavior.
Canonical Document Editing
Use ChartContractNormalizerService and ChartContractValidationService, then prove every visually editable path survives round-trip. Review at least:
- version, kind, preset, id, title/subtitle, source, dimensions, metrics, aggregations, group/sort/filter/limit;
- operation-specific stats options and refresh semantics supported by the runtime;
- legend, labels, tooltip, theme, surface, sizing, states, and motion;
- point click, selection, drilldown, cross-filter, governed targets, and mappings.
Changing kind, source, operation, or resource may invalidate dependent state. Preserve compatible values; surface validation for incompatible values; remove data only through explicit normalizer rules. Do not silently keep stale metric/axis/source options merely because the form control is hidden.
Local gauge consolidation preserves the authored metric aggregation and its result.
For SUM40+80, retain120 even when the current scale is0..100 and surface the canonical
out-of-range error until the author changes scale, data or aggregation. Do not
silently substitute AVG60 or clamp the value to make the presentation valid. Test
out-of-range SUM, a scale that admits120 and explicitly authored AVG.
The preview must consume the normalized document through the same canonical mapper and PraxisChartComponent. Synthetic rows are acceptable for an explicitly local authoring preview, but the UI must not imply that a remote stats request or backend capability was proved.
Query Context
- Keep
queryContext as a structured widget runtime input, separate from chartDocument.source and static document filters.
- A JSON textarea is an advanced fallback, not proof of rich authoring. Accept only a serializable non-array object and preserve filters, sort, limit, page, and meta that the runtime contract supports.
- Do not display raw parser exception messages. Use chart i18n keys for label, help, invalid JSON, and non-object errors.
- Empty text removes
inputs.queryContext; reset restores the original value and dirty/valid state; apply/save/reopen preserve semantic equality.
- Do not promise that every
queryContext property changes the default stats POST. Use praxis-charts-runtime-data for the exact execution boundary.
Governed Catalogs
availableResources, availableFields, and availableTargets are authoring context from governed metadata/catalog owners, not values the editor invents.
- Remote resource, field, metric, operation, and event-target choices must fail closed when required catalogs/capabilities are unavailable. A free-form resource URL or target input is not a safe fallback for governed authoring.
- Selecting a resource must resolve or refresh its compatible field, metric, operation, and capability catalog before dependent selections are accepted.
- Preserve stable identities: resource canonical key/path,
metrics[].field, dimension field, and target id. Labels are presentation only.
- Determine whether catalogs are transient editor context or intentionally persisted runtime inputs. Do not freeze stale API metadata into page config by accidental object spreading.
- Reuse canonical option-source/search controls where appropriate; do not create a chart-local lookup service when shared metadata or
@praxisui/dynamic-fields already owns discovery.
For gauge, treemap, grouped scatter, funnel/pyramid, KPI, histogram, and
comparison, round-trip the canonical presentation id and only its applicable
bindings/settings. Switching presentation must remove incompatible transient
editor state without deleting still-valid authored query context. Preview must
use the same catalog and adapter as runtime.
Metadata, AI, And Derived Artifacts
When an editable path or input envelope changes, inspect together:
praxis-chart.metadata.ts: runtime inputs, outputs, configEditor, insertion defaults/presets, ports, and authoringManifestRef;
praxis-charts-authoring-manifest.ts: schema version, runtime inputs, editable targets, operations, validators, affected paths, and round-trip requirements;
- AI registry ingestion/generated assets when metadata or manifest projection changes;
- README, public docs, recipes, playgrounds, and the Settings Panel smoke when public authoring behavior changes.
The visual editor and AI manifest must author the same canonical paths. Metadata must not expose a config editor whose default widget inputs cannot be reopened safely.
Inventory Before New Contract
ja-suportado-so-ux: canonical path exists; editor layout, i18n, diagnostics, or preview presentation is incomplete.
ja-suportado-mal-nomeado-ou-mal-materializado: local default version, raw URL/target fallback, stale catalog copy, or widget envelope obscures an existing canonical contract.
suportado-parcialmente: document/input/protocol exists but baseline, reset, catalog cascade, manifest metadata, persistence host, or runtime parity is incomplete.
lacuna-real-de-contrato: no canonical schema field, renderer-neutral runtime input, Settings Panel operation, catalog capability, or widget host envelope can express the behavior.
Only a real gap justifies a new public input, model, operation, or persistence contract. During beta, correct the canonical source and migrate monorepo consumers in one cycle instead of adding parallel aliases.
Validation Matrix
Require focused assertions for the changed rows:
- document editor: input/DI initialization, current versus baseline, dirty/valid/busy, controlled normalization, Apply, Save, Reset, readonly, external rebase, and every affected canonical path;
- widget editor: full
{ inputs } preservation, chart document precedence, missing-document behavior, query context valid/invalid/non-object/empty, remote-data pruning, reset, reopen, and multiple save cycles;
- catalogs: governed selection, missing-catalog fail-closed behavior, resource-to-field cascade, stale selection diagnostics, and stable identities;
- metadata/defaults: canonical
0.1.0 insertion document, configEditor, ports, runtime inputs, and manifest reference;
- AI: manifest version/schema/editable paths and registry projection;
- runtime parity: normalizer, validator, canonical mapper, component precedence, and local preview boundary;
- host proof: open -> edit -> Apply -> runtime reflects -> Save -> persisted widget inputs -> reopen -> Reset, at desktop and narrow widths when UI changed.
- shell-command lifecycle: renamed action still executes by command; unavailable states explain the current blocker; destruction before/during open cancels the panel and late Apply/Save emissions have no effect.
Typical focused gates from the Angular workspace root are:
npx ng test praxis-charts --watch=false --progress=false --include='projects/praxis-charts/src/lib/config-editor/praxis-chart-config-editor.spec.ts' --include='projects/praxis-charts/src/lib/config-editor/praxis-chart-widget-config-editor.spec.ts' --include='projects/praxis-charts/src/lib/praxis-chart.metadata.spec.ts' --include='projects/praxis-charts/src/lib/ai/praxis-charts-authoring-manifest.spec.ts'
npx ng test praxis-charts --watch=false --progress=false --include='projects/praxis-charts/src/lib/services/chart-contract-normalizer.service.spec.ts' --include='projects/praxis-charts/src/lib/services/chart-contract-validation.service.spec.ts' --include='projects/praxis-charts/src/lib/services/chart-canonical-contract-mapper.service.spec.ts' --include='projects/praxis-charts/src/lib/components/praxis-chart/praxis-chart.component.spec.ts'
npm run build:praxis-charts
npx playwright test --config tools/e2e/playwright/praxis-charts-settings-panel.playwright.config.ts
Do not claim round-trip from helper tests alone. Report the exact Settings Panel/host flow proved, backend/catalog capabilities not exercised, skipped screenshot/browser checks, and whether docs, metadata, manifest, registry, and direct consumers required updates.
1---2name: praxis-charts-authoring-settings3description: "Use when Codex must implement or audit @praxisui/charts visual authoring and Settings Panel round-trip: PraxisChartConfigEditor, PraxisChartWidgetConfigEditor, SettingsValueProvider, direct chart versus widget input envelopes, apply/save/reset/reopen, canonical x-ui.chart version and defaults, queryContext editing, config editor metadata, preview parity, governed catalogs, i18n, or AI manifest alignment."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-charts-authoring-settings6---78# Praxis Charts Authoring Settings910Use this skill for chart config editors and their Settings Panel hosts. The editor materializes canonical `x-ui.chart` decisions; it does not own business rules, analytics capabilities, persistence infrastructure, or an ECharts-shaped configuration language.1112Pair it with:1314- `praxis-settings-panel-shell` for shell, footer, close, drawer, and `SettingsValueProvider` protocol defects.15- `praxis-settings-roundtrip-authoring` for shared apply/save/reset/reopen invariants.16- `praxis-authoring-editors` and `praxis-ui-product-design` for transversal editor governance and visual UX changes.17- `praxis-charts-authoring-catalogs` for resource, field, target, capability, and preview catalog grounding.18- `praxis-charts-runtime-data` and `praxis-charts-analytics-interactions` for mapper, stats, `queryContext`, and runtime consumption.19- `praxis-charts-ai-validation` and `praxis-charts-ai-handler-contracts` when visual paths, component metadata, or executable manifest operations change.20- `praxis-charts-echarts-engine-boundary` only for preview/runtime engine materialization.2122## Canonical Owners2324- `praxis-metadata-starter/docs/spec/x-ui-chart.schema.json` owns the published structural `x-ui.chart` vocabulary and version. Do not advance an Angular editor default independently from that schema.25- `@praxisui/charts` owns `PraxisXUiChartContract`, normalization, validation, editor semantics, runtime mapping, preview, component metadata, and chart authoring manifest alignment.26- `@praxisui/settings-panel` owns Apply/Save/Reset/Cancel gating and obtains values from `SettingsValueProvider`.27- The dynamic Page Builder/core widget host owns opening `ComponentDocMeta.configEditor`, replacing widget inputs from the returned envelope, and persisting the page definition.28- `praxis-config-starter` or the declared host storage owns governed persistence, ETag, approval, and publication. A chart editor does not write storage directly.29- Backend metadata, schemas, analytics projections, option sources, and capabilities own which resources, fields, operations, metrics, and targets are authorable.3031## Editor Envelope And Owner Boundaries3233`PraxisChartConfigEditor` owns the canonical chart document. `PraxisChartWidgetConfigEditor` wraps that editor with the existing `{ inputs }` contract for document, local data and query context; both the direct runtime host and Page Builder consume this wrapper.3435### Direct runtime chart3637`PraxisChartComponent.openConfigEditor()` hosts `PraxisChartWidgetConfigEditor` with separate `inputs` and transient catalog `context`. Apply/Save returns `{ inputs }`, preserving `chartDocument`, derived local `data` and `queryContext` as separate owner inputs:3839`runtime owner inputs -> widget editor -> { inputs } -> applied$/saved$ -> document/data/context runtime -> owner patch`4041Apply updates the preview/runtime without closing. `chartDocumentApplied` and `chartDocumentSaved` still emit only `PraxisXUiChartContract`; `chartDocumentPatchChange.inputPatch` carries the complete changed input fields. Consume that existing patch in the external owner to persist data/context as well as the document. Explicit `null` clears stale data/query-context precedence when removed; `praxis.stats` must not continue using local rows. Do not move rows into `ChartContract`, invent another event envelope, or claim durability from an emitted patch.4243Treat document/config/data/query-context as one owner scope. Accumulate the latest expected acknowledgement per field across accepted patches, retaining fields omitted by a later patch. Accept equivalent or partial acknowledgements of those latest values without discarding the remaining local fields. The host must apply patches in order: without an epoch/revision in the existing contract, an old acknowledgement of A after B for the same field is indistinguishable from an intentional external change back to A, so the owner wins. Do not promise out-of-order acknowledgement delivery or invent history-based suppression of owner changes.4445Recheck ownership after context awaits and before Apply/Save, even before change detection. Closing/destroying the session releases its subscriptions; late events cannot overwrite a newer owner. Prove local rows through real editor Apply/Save, runtime accessible data and reopen, plus Reset/Cancel, stats transition, partial owner echoes across Apply/Save and external replacement.4647When a shell action invokes `command: "openConfigEditor"`, route by the stable command rather than the authored action id or label. Query live availability from the chart owner: customization enabled, Settings Panel bridge present, canonical document present, context resolution complete, and owner still alive. These explanations are localized presentation state, not backend authorization, and must not enter `chartDocument`.4849Context resolution can outlive the component or its customization session. Recheck eligibility after every asynchronous boundary, pass the chart `DestroyRef` as the transient Settings Panel owner, and release Apply/Save subscriptions on destruction. A late result must not open a panel or materialize another document patch after the chart owner disappears.5051### Dynamic widget/Page Builder5253`ComponentDocMeta.configEditor` points to `PraxisChartWidgetConfigEditor`. The widget host passes one `inputs` object and accepts either an `{ inputs }` envelope or a legacy bare object, then replaces the widget's complete input object:5455`widget.definition.inputs -> PraxisChartWidgetConfigEditor -> { inputs } -> apply/save -> complete widget input replacement -> page persistence -> reopen`5657Therefore the widget editor must preserve every unrelated input deliberately, update `inputs.chartDocument` and `inputs.queryContext`, and remove only inputs whose precedence would be wrong. For `source.kind = "praxis.stats"`, remove stale local `inputs.data`; do not silently delete shell or host inputs.5859Treat preserved `inputs.data` as local/derived runtime data only. It may be kept for legacy or `source.kind = "derived"` widgets, but when the canonical `chartDocument.source.kind` is `praxis.stats`, local rows must not remain as a palette/sample fallback, backend proof, capability evidence, or substitute for the stats request. If a host still needs sample data for an authoring preview, keep it in transient editor context or preview state, not in the persisted widget inputs envelope.6061## Initialization And Baselines6263- `PraxisChartConfigEditor` may initialize from its documented component input or `SETTINGS_PANEL_DATA` compatibility shape. Keep one canonical input name and do not rely on passing duplicate aliases that the Settings Panel filters out.64- Normalize a cloned external document into both current state and the reset baseline. Controlled normalization drift must be tested and documented; unknown canonical fields must not disappear accidentally.65- New documents must use the version published by the metadata schema and accepted by the manifest/validator. As of the current draft this is `0.1.0`; a local `1.0.0` default is not a version migration.66- A widget with only runtime `config`/`data` has no canonical authoring document. Do not fabricate a generic chart document on save and let it take precedence over the existing chart. Prefer canonical `chartDocument` insertion defaults; otherwise require an explicit, tested `PraxisChartConfig -> PraxisXUiChartContract` migration or block authoring with a diagnostic.67- Preserve a separate baseline for `queryContext` and every widget-owned editable input. Reset must restore the entire editor scope, not only the nested chart document.68- When external inputs change while clean, rebase all baselines. Do not overwrite dirty local work silently.6970## SettingsValueProvider Semantics7172- `isDirty$`, `isValid$`, and `isBusy$` are authoritative shell signals. Compose child editor and widget-level state without losing either source.73- `getSettingsValue()` powers Apply and must be side-effect free: it returns the current canonical value but does not mark it saved or replace the reset baseline.74- `onSave()` may finalize the same value, then establish the saved baseline. It must not return a different envelope from Apply.75- `reset()` restores the opening/saved baseline for chart document, `queryContext`, errors, dirty, valid, and busy state. It must be idempotent.76- Invalid state should prevent shell actions, but value methods should still fail predictably rather than leaking an unhandled `JSON.parse` exception if invoked programmatically.77- Do not add local Apply/Save gating or persistence calls to compensate for Settings Panel behavior.7879## Canonical Document Editing8081Use `ChartContractNormalizerService` and `ChartContractValidationService`, then prove every visually editable path survives round-trip. Review at least:8283- version, kind, preset, id, title/subtitle, source, dimensions, metrics, aggregations, group/sort/filter/limit;84- operation-specific stats options and refresh semantics supported by the runtime;85- legend, labels, tooltip, theme, surface, sizing, states, and motion;86- point click, selection, drilldown, cross-filter, governed targets, and mappings.8788Changing kind, source, operation, or resource may invalidate dependent state. Preserve compatible values; surface validation for incompatible values; remove data only through explicit normalizer rules. Do not silently keep stale metric/axis/source options merely because the form control is hidden.8990Local gauge consolidation preserves the authored metric aggregation and its result.91For SUM40+80, retain120 even when the current scale is0..100 and surface the canonical92out-of-range error until the author changes scale, data or aggregation. Do not93silently substitute AVG60 or clamp the value to make the presentation valid. Test94out-of-range SUM, a scale that admits120 and explicitly authored AVG.9596The preview must consume the normalized document through the same canonical mapper and `PraxisChartComponent`. Synthetic rows are acceptable for an explicitly local authoring preview, but the UI must not imply that a remote stats request or backend capability was proved.9798## Query Context99100- Keep `queryContext` as a structured widget runtime input, separate from `chartDocument.source` and static document filters.101- A JSON textarea is an advanced fallback, not proof of rich authoring. Accept only a serializable non-array object and preserve filters, sort, limit, page, and meta that the runtime contract supports.102- Do not display raw parser exception messages. Use chart i18n keys for label, help, invalid JSON, and non-object errors.103- Empty text removes `inputs.queryContext`; reset restores the original value and dirty/valid state; apply/save/reopen preserve semantic equality.104- Do not promise that every `queryContext` property changes the default stats POST. Use `praxis-charts-runtime-data` for the exact execution boundary.105106## Governed Catalogs107108- `availableResources`, `availableFields`, and `availableTargets` are authoring context from governed metadata/catalog owners, not values the editor invents.109- Remote resource, field, metric, operation, and event-target choices must fail closed when required catalogs/capabilities are unavailable. A free-form resource URL or target input is not a safe fallback for governed authoring.110- Selecting a resource must resolve or refresh its compatible field, metric, operation, and capability catalog before dependent selections are accepted.111- Preserve stable identities: resource canonical key/path, `metrics[].field`, dimension field, and target id. Labels are presentation only.112- Determine whether catalogs are transient editor context or intentionally persisted runtime inputs. Do not freeze stale API metadata into page config by accidental object spreading.113- Reuse canonical option-source/search controls where appropriate; do not create a chart-local lookup service when shared metadata or `@praxisui/dynamic-fields` already owns discovery.114115For gauge, treemap, grouped scatter, funnel/pyramid, KPI, histogram, and116comparison, round-trip the canonical presentation id and only its applicable117bindings/settings. Switching presentation must remove incompatible transient118editor state without deleting still-valid authored query context. Preview must119use the same catalog and adapter as runtime.120121## Metadata, AI, And Derived Artifacts122123When an editable path or input envelope changes, inspect together:124125- `praxis-chart.metadata.ts`: runtime inputs, outputs, `configEditor`, insertion defaults/presets, ports, and `authoringManifestRef`;126- `praxis-charts-authoring-manifest.ts`: schema version, runtime inputs, editable targets, operations, validators, affected paths, and round-trip requirements;127- AI registry ingestion/generated assets when metadata or manifest projection changes;128- README, public docs, recipes, playgrounds, and the Settings Panel smoke when public authoring behavior changes.129130The visual editor and AI manifest must author the same canonical paths. Metadata must not expose a config editor whose default widget inputs cannot be reopened safely.131132## Inventory Before New Contract133134- `ja-suportado-so-ux`: canonical path exists; editor layout, i18n, diagnostics, or preview presentation is incomplete.135- `ja-suportado-mal-nomeado-ou-mal-materializado`: local default version, raw URL/target fallback, stale catalog copy, or widget envelope obscures an existing canonical contract.136- `suportado-parcialmente`: document/input/protocol exists but baseline, reset, catalog cascade, manifest metadata, persistence host, or runtime parity is incomplete.137- `lacuna-real-de-contrato`: no canonical schema field, renderer-neutral runtime input, Settings Panel operation, catalog capability, or widget host envelope can express the behavior.138139Only a real gap justifies a new public input, model, operation, or persistence contract. During beta, correct the canonical source and migrate monorepo consumers in one cycle instead of adding parallel aliases.140141## Validation Matrix142143Require focused assertions for the changed rows:144145- document editor: input/DI initialization, current versus baseline, dirty/valid/busy, controlled normalization, Apply, Save, Reset, readonly, external rebase, and every affected canonical path;146- widget editor: full `{ inputs }` preservation, chart document precedence, missing-document behavior, query context valid/invalid/non-object/empty, remote-data pruning, reset, reopen, and multiple save cycles;147- catalogs: governed selection, missing-catalog fail-closed behavior, resource-to-field cascade, stale selection diagnostics, and stable identities;148- metadata/defaults: canonical `0.1.0` insertion document, `configEditor`, ports, runtime inputs, and manifest reference;149- AI: manifest version/schema/editable paths and registry projection;150- runtime parity: normalizer, validator, canonical mapper, component precedence, and local preview boundary;151- host proof: open -> edit -> Apply -> runtime reflects -> Save -> persisted widget inputs -> reopen -> Reset, at desktop and narrow widths when UI changed.152- shell-command lifecycle: renamed action still executes by command; unavailable states explain the current blocker; destruction before/during open cancels the panel and late Apply/Save emissions have no effect.153154Typical focused gates from the Angular workspace root are:155156```bash157npx ng test praxis-charts --watch=false --progress=false --include='projects/praxis-charts/src/lib/config-editor/praxis-chart-config-editor.spec.ts' --include='projects/praxis-charts/src/lib/config-editor/praxis-chart-widget-config-editor.spec.ts' --include='projects/praxis-charts/src/lib/praxis-chart.metadata.spec.ts' --include='projects/praxis-charts/src/lib/ai/praxis-charts-authoring-manifest.spec.ts'158npx ng test praxis-charts --watch=false --progress=false --include='projects/praxis-charts/src/lib/services/chart-contract-normalizer.service.spec.ts' --include='projects/praxis-charts/src/lib/services/chart-contract-validation.service.spec.ts' --include='projects/praxis-charts/src/lib/services/chart-canonical-contract-mapper.service.spec.ts' --include='projects/praxis-charts/src/lib/components/praxis-chart/praxis-chart.component.spec.ts'159npm run build:praxis-charts160npx playwright test --config tools/e2e/playwright/praxis-charts-settings-panel.playwright.config.ts161```162163Do not claim round-trip from helper tests alone. Report the exact Settings Panel/host flow proved, backend/catalog capabilities not exercised, skipped screenshot/browser checks, and whether docs, metadata, manifest, registry, and direct consumers required updates.