Praxis Core Widget Observations
Use this skill for core dynamic widgets, dynamic pages, widget events, composition links, and runtime observations. Treat these as shared runtime contracts for materialized Praxis decisions, not as Page Builder-only implementation details.
Source Audit
Before editing code or guidance, inspect:
projects/praxis-core/AGENTS.md
projects/praxis-core/docs/rfc-dynamic-page-canvas-runtime.md
projects/praxis-core/docs/connection-editor.md
projects/praxis-core/src/public-api.ts
projects/praxis-core/src/lib/widgets/**
projects/praxis-core/src/lib/composition/**
projects/praxis-core/src/lib/models/runtime-component-observation.model.ts
projects/praxis-core/src/lib/services/runtime-component-observation-registry.service.ts
projects/praxis-core/src/lib/widgets/widget-event-path-normalizer.ts
projects/praxis-core/src/lib/widgets/nested-widget-config-accessor.ts
projects/praxis-core/src/lib/widgets/widget-page-state-runtime.service.ts
- focused widget, composition, observation, and dynamic page specs
Canonical Boundary
@praxisui/core owns shared widget/page models, widget loader primitives, widget shell, widget event model/path normalization, nested widget config access, widget page state runtime, composition runtime contracts, runtime trace/diagnostics, and runtime component observation envelopes.
@praxisui/page-builder may author pages and canvases, and vertical packages may provide widgets, but they should consume the core contracts instead of inventing local widget graphs, event paths, observation payloads, or composition link semantics.
Runtime Rules
- Use
WidgetDefinition, WidgetPageDefinition, WidgetPageLayout, and related core models for page/runtime structure.
- Use
DynamicWidgetLoaderDirective and widget metadata rather than local selector switches when loading governed widgets.
- Use
WidgetEvent and normalized event paths for widget output wiring.
- Use core composition services/facade for links, transforms, nested ports, traces, and diagnostics.
- Runtime observations must be serializable
PraxisRuntimeComponentObservationEnvelope values with redaction diagnostics.
- Do not include functions, symbols, bigint, circular references, raw secrets, or unredacted large data snapshots in observations.
- Preserve identity fields: instance id, component id/type, widget key, owner package, route key, resource refs, page id, and manifest refs.
- Use observation claims for component, manifest, resource, schema field, selection, operation, surface, action, state digest, or data digest facts. Do not expose full backend payloads when a digest/ref is enough.
- Treat runtime observations as
untrusted_frontend_observation grounding only. They may rank, explain, or disambiguate visible component/page/surface/action context after semantic intent is resolved, but they must not choose the primary intent route, authorize preview/apply, mutate composition state, or replace backend/domain/catalog evidence.
- Observation claims must remain evidence pointers with stable ids, manifest/resource refs, digest/ref, redaction status, freshness/TTL, and source owner. Do not encode prompt labels, DOM text, raw payload values, or user-visible copy as executable semantics.
- If an observation is stale, redacted, invalid, or missing required identity/refs, fail closed to clarification or diagnostics and fetch canonical backend, registry, or composition evidence instead of repairing by local guesses.
- Treat absence from
listActive() or getByInstance(...) as missing or filtered frontend evidence, not proof that a component,
capability, surface, action, resource, or permission does not exist. The registry intentionally drops inactive, expired,
non-serializable, or failing provider observations. Resolve existence and authority from component metadata, manifests,
resource/action/surface discovery, composition definitions, or backend/domain contracts before making a decision.
Selection-Driven Shell Identity
Before declaring avatar unsupported, inspect WidgetShellConfig.avatar in
projects/praxis-core/src/lib/widgets/widget-shell.model.ts, the avatar component
and its spec, shell binding/transient specs, and the Core README section
“Selection-driven widget headers”. The existing optional object exposes textual
imageSrc, name, and initials, takes precedence over the icon, and uses the
Core image/initials/person fallback. Do not coerce objects into URLs or bypass
image URL sanitization/authentication. Prove missing/failed images and recovery
after changing/clearing identity, including late errors from an earlier image.
Dynamic Page resolves shell path bindings against state, transient, context
and the existing widget context. Keep selected identity transient and propagate
empty selection. The header does not fetch the record or format dates/documents;
use the canonical link projection in praxis-core-composition-runtime.
Use the native Page Builder shell editor's Appearance section for avatar fields.
Inspect projects/praxis-page-builder/src/lib/editor/widget-shell-editor.component.spec.ts
and pair with praxis-page-builder-authoring for Apply/Save/reopen/reset,
illustrative preview versus real bound values, and disabling the avatar. The
existing widget.shell.configure operation/capability owns these fields; no new
avatar link kind is needed. Check the manifest and target registry before claiming
AI discovery; a local editor screenshot does not prove remote publication.
For identity plus remote detail, verify first-frame hiding, error/retry and focus
in the Dynamic Form owner. Check actual widget width, action overflow and the open
editor at narrow width with praxis-ui-product-design; viewport size alone does
not describe the available shell width. Run shell/avatar/transient specs and
the shell editor round-trip tests for changes in these surfaces.
Runtime Shell Action Availability
Widget shell actions keep their authored id, label, icon and order, while execution
and live availability belong to the component owner. Resolve handlers by declared
command or canonical action reference, not button text or action id conventions.
An optional getWidgetShellActionAvailability result is transient presentation:
it may explain disabled customization, missing bridge/document, pending context or
other current owner state, but it must not be persisted or treated as permission.
Keep removal/configuration of an authored action available even when execution is
currently blocked. Recheck the owner's guard at execution and after asynchronous
context loading. When an editor targets a live widget instance, pass its lifecycle
owner to Settings Panel and cancel late open/apply/save work after destruction.
Prove renamed actions, unavailable explanations, positive execution, owner teardown
and subscription cleanup through the real contributor and shell host.
Controlled Page Acknowledgement And Settings Lifetime
For controlled pageChange consumers, inspect DynamicWidgetPageComponent.ngOnChanges,
models/page/page-config.model.ts, dynamic-widget-page-settings.spec.ts, the Core
README owner-lifetime section and a real host that returns the page to Core. A host
may recreate PageIdentity while acknowledging the same authored document.
Audit semantic no-op identity changes before the existing change pipeline. Only
non-first changes with the same identity presence and strictly equal canonical
appId, tenantId, userId, routePath and locale qualify. Compare against the
identity Core actually accepted, retained as a private snapshot of those primitive
values. A host can mutate the object referenced by SimpleChange.previousValue
before sending a clone; that mutable reference alone cannot prove an unchanged
scope. Preserve null/empty and absent-identity distinctions; do not trim, sanitize,
join delimiters or compare only the derived storage key. Normalize on a local copy/decision without mutating
the caller's SimpleChanges. An equivalent-identity-only change should not clear
the data-source overlay, rebootstrap composition or reset/reload persistence.
A matching authored-page acknowledgement accompanied by this redundant identity
must preserve the open settings owner through Apply then Save, including unified
shell/size sessions. All remaining changes follow the existing pipeline: a different
document, real scope/identity change, context (including function references),
component instance, customization or authoring capabilities must retain their
invalidation and persistence behavior. Do not JSON-serialize context or capabilities
to suppress a real change, or hide the Core defect with host-local memoization.
Prove equivalent identity with controlled page echoes, identity-only no-op,
first-change behavior, unchanged caller changes, delimiter/whitespace collisions,
in-place host identity mutation followed by a clone, and each real identity field change. Include overlay/composition/persistence and
late-event/owner cleanup assertions. Require focused Core settings proof, Core and
direct-consumer builds, and the real public-button Apply→Save flow on the target
published SDK. Local mocks/builds do not certify that published browser journey.
Inventory Before New Contract
Classify gaps before adding widget or observation contracts:
ja-suportado-so-ux: model/observation exists but Page Builder, docs, or diagnostics do not show it well.
ja-suportado-mal-nomeado-ou-mal-materializado: a local widget/event/observation shape should map to existing core contracts.
suportado-parcialmente: core model exists but loader, registry, composition, observation, docs, or consumer validation is incomplete.
lacuna-real-de-contrato: no core widget, composition, event, observation, or diagnostic contract can carry the runtime fact.
For real gaps, update core models/specs and at least one direct consumer proof.
Validation
Use the smallest reliable proof:
- widget loader, shell, event paths, nested widget access, page models, presets, and state runtime:
npm run test:core -- --include=projects/praxis-core/src/lib/widgets/dynamic-widget-loader.directive.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-shell.component.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-event-path-normalizer.spec.ts --include=projects/praxis-core/src/lib/widgets/nested-widget-config-accessor.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-page.model.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-page-presets.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-page-state-runtime.service.spec.ts
- dynamic widget page, composition serialization/factory, and record surface/open recipes:
npm run test:core -- --include=projects/praxis-core/src/lib/widgets/dynamic-widget-page.component.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-page-composition.serialization.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-page-composition.factory.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-widget-page-record-surface-open.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-page-rich-table-recipe.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-page-actions-workspace-recipe.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-page-nested-path-recipe.spec.ts
- composition runtime evidence consumed by observations:
npm run test:core -- --include=projects/praxis-core/src/lib/composition/composition-runtime.engine.spec.ts --include=projects/praxis-core/src/lib/composition/composition-runtime.facade.spec.ts --include=projects/praxis-core/src/lib/composition/composition-runtime-store.spec.ts --include=projects/praxis-core/src/lib/composition/composition-validator.service.spec.ts
- runtime observation envelopes, registry, serializability, redaction, and Page Builder collection integration:
npm run test:core -- --include=projects/praxis-core/src/lib/services/runtime-component-observation-registry.service.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-widget-page-runtime-observation.spec.ts
npm run ng -- test praxis-page-builder --watch=false --progress=false --include=projects/praxis-page-builder/src/lib/dynamic-page-builder.component.spec.ts --include=projects/praxis-page-builder/src/lib/editor/connection-editor/connection-editor-graph.util.spec.ts
npm run build:praxis-core plus a Page Builder or direct widget consumer build when public contracts change.
Report whether runtime observations were checked for serializability and redaction.
Companion Skills
- Use
praxis-core-composition-runtime for composition links, widget events, surface hosts, and runtime observations.
- Use
praxis-core-component-registry-contracts when widget discovery depends on component metadata registry entries, editorial descriptors, ports, insertion presets, or AI component context.
- Use
praxis-core-global-action-payloads when widget events execute structured global actions or emit surface.result/composition dispatch payloads.
- Use
praxis-page-builder-composition for Page Builder authoring/runtime composition on top of core.
- Use
praxis-core-providers-bootstrap when widget loading requires provider/registry wiring.
- Use
praxis-angular-public-api-governance and praxis-angular-validation-gates for public exports and validation scope.
1---2name: praxis-core-widget-observations3description: Use when Codex must implement, audit, document, or consume `@praxisui/core` dynamic widget infrastructure, including `WidgetDefinition`, `WidgetPageDefinition`, dynamic widget loader, widget shell, dynamic widget page, widget events, nested widget config accessor, widget page state runtime, composition runtime facade, connection manager, runtime component observation envelopes, observation registry, diagnostics, docs, public API, or Page Builder/runtime observation integration.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-core-widget-observations6---78# Praxis Core Widget Observations910Use this skill for core dynamic widgets, dynamic pages, widget events, composition links, and runtime observations. Treat these as shared runtime contracts for materialized Praxis decisions, not as Page Builder-only implementation details.1112## Source Audit1314Before editing code or guidance, inspect:1516- `projects/praxis-core/AGENTS.md`17- `projects/praxis-core/docs/rfc-dynamic-page-canvas-runtime.md`18- `projects/praxis-core/docs/connection-editor.md`19- `projects/praxis-core/src/public-api.ts`20- `projects/praxis-core/src/lib/widgets/**`21- `projects/praxis-core/src/lib/composition/**`22- `projects/praxis-core/src/lib/models/runtime-component-observation.model.ts`23- `projects/praxis-core/src/lib/services/runtime-component-observation-registry.service.ts`24- `projects/praxis-core/src/lib/widgets/widget-event-path-normalizer.ts`25- `projects/praxis-core/src/lib/widgets/nested-widget-config-accessor.ts`26- `projects/praxis-core/src/lib/widgets/widget-page-state-runtime.service.ts`27- focused widget, composition, observation, and dynamic page specs2829## Canonical Boundary3031`@praxisui/core` owns shared widget/page models, widget loader primitives, widget shell, widget event model/path normalization, nested widget config access, widget page state runtime, composition runtime contracts, runtime trace/diagnostics, and runtime component observation envelopes.3233`@praxisui/page-builder` may author pages and canvases, and vertical packages may provide widgets, but they should consume the core contracts instead of inventing local widget graphs, event paths, observation payloads, or composition link semantics.3435## Runtime Rules3637- Use `WidgetDefinition`, `WidgetPageDefinition`, `WidgetPageLayout`, and related core models for page/runtime structure.38- Use `DynamicWidgetLoaderDirective` and widget metadata rather than local selector switches when loading governed widgets.39- Use `WidgetEvent` and normalized event paths for widget output wiring.40- Use core composition services/facade for links, transforms, nested ports, traces, and diagnostics.41- Runtime observations must be serializable `PraxisRuntimeComponentObservationEnvelope` values with redaction diagnostics.42- Do not include functions, symbols, bigint, circular references, raw secrets, or unredacted large data snapshots in observations.43- Preserve identity fields: instance id, component id/type, widget key, owner package, route key, resource refs, page id, and manifest refs.44- Use observation claims for component, manifest, resource, schema field, selection, operation, surface, action, state digest, or data digest facts. Do not expose full backend payloads when a digest/ref is enough.45- Treat runtime observations as `untrusted_frontend_observation` grounding only. They may rank, explain, or disambiguate visible component/page/surface/action context after semantic intent is resolved, but they must not choose the primary intent route, authorize preview/apply, mutate composition state, or replace backend/domain/catalog evidence.46- Observation claims must remain evidence pointers with stable ids, manifest/resource refs, digest/ref, redaction status, freshness/TTL, and source owner. Do not encode prompt labels, DOM text, raw payload values, or user-visible copy as executable semantics.47- If an observation is stale, redacted, invalid, or missing required identity/refs, fail closed to clarification or diagnostics and fetch canonical backend, registry, or composition evidence instead of repairing by local guesses.48- Treat absence from `listActive()` or `getByInstance(...)` as missing or filtered frontend evidence, not proof that a component,49 capability, surface, action, resource, or permission does not exist. The registry intentionally drops inactive, expired,50 non-serializable, or failing provider observations. Resolve existence and authority from component metadata, manifests,51 resource/action/surface discovery, composition definitions, or backend/domain contracts before making a decision.5253## Selection-Driven Shell Identity5455Before declaring avatar unsupported, inspect `WidgetShellConfig.avatar` in56`projects/praxis-core/src/lib/widgets/widget-shell.model.ts`, the avatar component57and its spec, shell binding/transient specs, and the Core README section58“Selection-driven widget headers”. The existing optional object exposes textual59`imageSrc`, `name`, and `initials`, takes precedence over the icon, and uses the60Core image/initials/person fallback. Do not coerce objects into URLs or bypass61image URL sanitization/authentication. Prove missing/failed images and recovery62after changing/clearing identity, including late errors from an earlier image.6364Dynamic Page resolves shell path bindings against `state`, `transient`, `context`65and the existing widget context. Keep selected identity transient and propagate66empty selection. The header does not fetch the record or format dates/documents;67use the canonical link projection in `praxis-core-composition-runtime`.6869Use the native Page Builder shell editor's Appearance section for avatar fields.70Inspect `projects/praxis-page-builder/src/lib/editor/widget-shell-editor.component.spec.ts`71and pair with `praxis-page-builder-authoring` for Apply/Save/reopen/reset,72illustrative preview versus real bound values, and disabling the avatar. The73existing `widget.shell.configure` operation/capability owns these fields; no new74avatar link kind is needed. Check the manifest and target registry before claiming75AI discovery; a local editor screenshot does not prove remote publication.7677For identity plus remote detail, verify first-frame hiding, error/retry and focus78in the Dynamic Form owner. Check actual widget width, action overflow and the open79editor at narrow width with `praxis-ui-product-design`; viewport size alone does80not describe the available shell width. Run shell/avatar/transient specs and81the shell editor round-trip tests for changes in these surfaces.8283## Runtime Shell Action Availability8485Widget shell actions keep their authored id, label, icon and order, while execution86and live availability belong to the component owner. Resolve handlers by declared87`command` or canonical action reference, not button text or action id conventions.88An optional `getWidgetShellActionAvailability` result is transient presentation:89it may explain disabled customization, missing bridge/document, pending context or90other current owner state, but it must not be persisted or treated as permission.9192Keep removal/configuration of an authored action available even when execution is93currently blocked. Recheck the owner's guard at execution and after asynchronous94context loading. When an editor targets a live widget instance, pass its lifecycle95owner to Settings Panel and cancel late open/apply/save work after destruction.96Prove renamed actions, unavailable explanations, positive execution, owner teardown97and subscription cleanup through the real contributor and shell host.9899## Controlled Page Acknowledgement And Settings Lifetime100101For controlled `pageChange` consumers, inspect `DynamicWidgetPageComponent.ngOnChanges`,102`models/page/page-config.model.ts`, `dynamic-widget-page-settings.spec.ts`, the Core103README owner-lifetime section and a real host that returns the page to Core. A host104may recreate `PageIdentity` while acknowledging the same authored document.105106Audit semantic no-op identity changes before the existing change pipeline. Only107non-first changes with the same identity presence and strictly equal canonical108`appId`, `tenantId`, `userId`, `routePath` and `locale` qualify. Compare against the109identity Core actually accepted, retained as a private snapshot of those primitive110values. A host can mutate the object referenced by `SimpleChange.previousValue`111before sending a clone; that mutable reference alone cannot prove an unchanged112scope. Preserve null/empty and absent-identity distinctions; do not trim, sanitize,113join delimiters or compare only the derived storage key. Normalize on a local copy/decision without mutating114the caller's `SimpleChanges`. An equivalent-identity-only change should not clear115the data-source overlay, rebootstrap composition or reset/reload persistence.116117A matching authored-page acknowledgement accompanied by this redundant identity118must preserve the open settings owner through Apply then Save, including unified119shell/size sessions. All remaining changes follow the existing pipeline: a different120document, real scope/identity change, context (including function references),121component instance, customization or authoring capabilities must retain their122invalidation and persistence behavior. Do not JSON-serialize context or capabilities123to suppress a real change, or hide the Core defect with host-local memoization.124125Prove equivalent identity with controlled page echoes, identity-only no-op,126first-change behavior, unchanged caller changes, delimiter/whitespace collisions,127in-place host identity mutation followed by a clone, and each real identity field change. Include overlay/composition/persistence and128late-event/owner cleanup assertions. Require focused Core settings proof, Core and129direct-consumer builds, and the real public-button Apply→Save flow on the target130published SDK. Local mocks/builds do not certify that published browser journey.131132## Inventory Before New Contract133134Classify gaps before adding widget or observation contracts:135136- `ja-suportado-so-ux`: model/observation exists but Page Builder, docs, or diagnostics do not show it well.137- `ja-suportado-mal-nomeado-ou-mal-materializado`: a local widget/event/observation shape should map to existing core contracts.138- `suportado-parcialmente`: core model exists but loader, registry, composition, observation, docs, or consumer validation is incomplete.139- `lacuna-real-de-contrato`: no core widget, composition, event, observation, or diagnostic contract can carry the runtime fact.140141For real gaps, update core models/specs and at least one direct consumer proof.142143## Validation144145Use the smallest reliable proof:146147- widget loader, shell, event paths, nested widget access, page models, presets, and state runtime:148149```sh150npm run test:core -- --include=projects/praxis-core/src/lib/widgets/dynamic-widget-loader.directive.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-shell.component.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-event-path-normalizer.spec.ts --include=projects/praxis-core/src/lib/widgets/nested-widget-config-accessor.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-page.model.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-page-presets.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-page-state-runtime.service.spec.ts151```152153- dynamic widget page, composition serialization/factory, and record surface/open recipes:154155```sh156npm run test:core -- --include=projects/praxis-core/src/lib/widgets/dynamic-widget-page.component.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-page-composition.serialization.spec.ts --include=projects/praxis-core/src/lib/widgets/widget-page-composition.factory.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-widget-page-record-surface-open.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-page-rich-table-recipe.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-page-actions-workspace-recipe.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-page-nested-path-recipe.spec.ts157```158159- composition runtime evidence consumed by observations:160161```sh162npm run test:core -- --include=projects/praxis-core/src/lib/composition/composition-runtime.engine.spec.ts --include=projects/praxis-core/src/lib/composition/composition-runtime.facade.spec.ts --include=projects/praxis-core/src/lib/composition/composition-runtime-store.spec.ts --include=projects/praxis-core/src/lib/composition/composition-validator.service.spec.ts163```164165- runtime observation envelopes, registry, serializability, redaction, and Page Builder collection integration:166167```sh168npm run test:core -- --include=projects/praxis-core/src/lib/services/runtime-component-observation-registry.service.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-widget-page-runtime-observation.spec.ts169npm run ng -- test praxis-page-builder --watch=false --progress=false --include=projects/praxis-page-builder/src/lib/dynamic-page-builder.component.spec.ts --include=projects/praxis-page-builder/src/lib/editor/connection-editor/connection-editor-graph.util.spec.ts170```171172- `npm run build:praxis-core` plus a Page Builder or direct widget consumer build when public contracts change.173174Report whether runtime observations were checked for serializability and redaction.175176## Companion Skills177178- Use `praxis-core-composition-runtime` for composition links, widget events, surface hosts, and runtime observations.179- Use `praxis-core-component-registry-contracts` when widget discovery depends on component metadata registry entries, editorial descriptors, ports, insertion presets, or AI component context.180- Use `praxis-core-global-action-payloads` when widget events execute structured global actions or emit `surface.result`/composition dispatch payloads.181- Use `praxis-page-builder-composition` for Page Builder authoring/runtime composition on top of core.182- Use `praxis-core-providers-bootstrap` when widget loading requires provider/registry wiring.183- Use `praxis-angular-public-api-governance` and `praxis-angular-validation-gates` for public exports and validation scope.