# Praxis Core Widget Observations

> 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.

- Skill: `codexrodrigues/praxis-core-widget-observations` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add codexrodrigues/praxis-core-widget-observations`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/praxis-core-widget-observations/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: codexrodrigues (https://skillmd.com/u/codexrodrigues)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/codexrodrigues/praxis-core-widget-observations

---


# 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:

```sh
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:

```sh
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:

```sh
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:

```sh
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.

