Praxis Dynamic Fields Editorial
This praxis-fields-* plus praxis-dynamic-fields-editorial skill family is the canonical Codex skill surface for @praxisui/dynamic-fields and projects/praxis-dynamic-fields; do not create another parallel dynamic-fields skill family unless this family cannot express a proven contract gap.
Use this skill for the special authoring/discovery model of @praxisui/dynamic-fields.
For focused changes, pair this general editorial skill with the specialized family:
praxis-fields-runtime-loader for loader/registry/runtime coverage,
praxis-fields-option-sources for async selects, option sources, and entity lookup,
praxis-fields-editorial-discovery for descriptor/catalog/tooling coverage, and
praxis-fields-ai-canvas-validation for AI manifest, registry ingestion, recipes, or canvas proof.
Use praxis-fields-control-profile-ai for per-control AI profiles and capability catalogs,
praxis-fields-inline-overlay-runtime for inline overlay apply/cancel/clear semantics,
praxis-fields-text-number-time-controls for text, numeric, currency, date, time, and range families,
and praxis-fields-selection-lookup-controls for select, autocomplete, chips, tree, list, and lookup families.
For visual authoring coverage inside @praxisui/metadata-editor, pair this with
praxis-metadata-editor-renderer-coverage; for cascade or option-source dependency normalization in
the editor, use praxis-metadata-editor-cascade-normalization.
For operational file upload fields, use praxis-files-upload-form-field for pdx-material-files-upload,
valueMode, ControlValueAccessor behavior, and upload-specific field UX. Return here only when the
dynamic-fields catalog, selector mapping, aliases, or metadata discovery for that field changes.
For rich content or rich-input fields, use praxis-rich-content-runtime and
praxis-rich-content-integration-adapters for RichContentDocument semantics. Return here only when
dynamic-fields metadata discovery, control aliases, selector mapping, or editor/tooling coverage changes.
For CRON or schedule fields, use praxis-cron-builder-form-field, praxis-cron-builder-runtime, and
praxis-cron-schedule-authoring for field/runtime semantics. Return here only when dynamic-fields
catalog registration, selector mapping, aliases, editorial descriptors, or tooling discovery changes.
This library does not primarily follow the pattern "runtime component has its own config editor". Runtime rendering, editorial discovery, metadata tooling, and editor coverage are separate layers.
Before changing this skill or a dynamic-fields feature, inspect the current source for the involved
runtime and metadata path. For ordinary controls this means the component, .metadata.ts,
ComponentRegistryService, ComponentMetadataRegistry, editorial registry, catalog/AI files, and
selector mapping in @praxisui/core. For option-source controls, also inspect
OptionSourceMetadata, GenericCrudService.filterOptionSourceOptions,
GenericCrudService.getOptionSourceOptionsByIds, and the backend x-ui.optionSource projection.
For wrapper controls, inspect the owning package skill first: files upload, rich content, and CRON
field behavior belong to those package contracts; dynamic-fields owns only control registration,
metadata discovery, selector mapping, catalogs, and downstream materialization.
The goal is to encode working Praxis platform knowledge into the skill, not merely document a UI
convention.
First resolve the Angular workspace root. In the platform monorepo the files may live under
praxis-ui-angular/projects/...; in a standalone Angular checkout they may live directly under
projects/.... Audit the active praxis-ui-angular workspace, not stale issue worktrees such as
praxis-ui-angular-issue*, unless the user explicitly targets one of those worktrees.
When the platform monorepo is available, inspect projects/praxis-dynamic-fields/AGENTS.md before
editing and keep its governed docs in scope when relevant:
projects/praxis-dynamic-fields/docs/dynamic-fields-inventory.md
projects/praxis-dynamic-fields/docs/dynamic-fields-field-catalog.md
projects/praxis-dynamic-fields/docs/dynamic-fields-field-selection-guide.md
projects/praxis-dynamic-fields/docs/dynamic-fields-host-custom-field-guide.md
projects/praxis-dynamic-fields/docs/dynamic-fields-inline-filter-catalog.md
projects/praxis-dynamic-fields/docs/dynamic-fields-inline-filter-runtime-contract.md
projects/praxis-dynamic-fields/docs/dynamic-fields-inline-components-guide.md
If the task is to implement or review backend RESOURCE_ENTITY option sources, use
praxis-resource-entity-lookup-backend first. Use this skill when that backend change affects
Angular runtime registry, editorial descriptors, metadata-editor coverage, recipes, catalogs, or
AI registry projection.
Canonical Model
Treat these as distinct:
- runtime render
- forms integration
- metadata/editorial discovery
- hot metadata behavior
Do not assume runtime support implies editor/tooling support.
For metadata-driven option-source cascades, keep the boundary explicit:
x-ui.optionSource.dependsOn is the canonical backend/editor dependency declaration.
x-ui.optionSource.dependencyFilterMap is the canonical explicit mapping when the dependent field name differs from the backend filter key.
x-ui.optionSource.includeIds is an explicit runtime permission. Option-source filters must send includeIds only when this flag is true; when it is false or absent, selected-value rehydration must use the canonical by-ids/display path instead of adding includeIds to filter requests.
x-ui.optionSource.filterEndpoint, byIdsEndpoint, selectedReloadPolicy, and invalidSortPolicy are backend runtime-contract facts. Editors and examples may display or validate them, but must not synthesize them from local host assumptions when the backend publishes them.
dependencyFields and dependencyFilterMap are the runtime/manual metadata consumed by select components.
- A bridge may derive runtime metadata from
optionSource, but it should not synthesize authoring state or reset/reload policy unless the canonical contract says so.
- For dependent sources, editor/runtime support is incomplete until selected-value reload is proven on reopen/edit. If the selected ID is not self-contained, the runtime must use a contextual option-source by-ids path or downgrade the claim according to
selectedReloadPolicy; do not assume the filter cascade proves hydration.
If selectedReloadPolicy is required or supported, verify that presentation mode, reopen/edit,
and selected-value preload call the option-source by-ids path rather than a generic options path.
If it is unsupported-with-waiver, the UI may show a degraded retained value, but the example or
editor must mark the source as partial and point back to the backend/platform waiver.
Canonical Boundaries
ComponentRegistryService owns runtime component resolution by controlType.
ComponentMetadataRegistry owns editorial discovery metadata.
src/lib/editorial/** owns canonical package editorial descriptors.
@praxisui/core owns FieldControlType, OptionSourceMetadata,
DEFAULT_FIELD_SELECTOR_CONTROL_TYPE_MAP, and selector registry tokens. Do not add a
dynamic-fields-only alias when the canonical type or selector mapping belongs in core.
@praxisui/core also owns canonical control-type alias normalization through
resolveControlTypeAlias(...) and normalizeControlTypeToken(...). ComponentRegistryService
may keep residual runtime synonyms for compatibility after calling the core normalizer, but that
local table is not the place to introduce new canonical names. When adding or reviewing an alias,
update/prove the core normalizer first, keep registry fallback behavior compatible, and prevent
aliases from becoming primary catalog/editorial choices.
- Agentic authoring uses one family-level manifest for shared
FieldMetadata/registry/editorial semantics plus component-level control profiles for granular per-control operation hints; use praxis-fields-control-profile-ai for that layer and do not duplicate a full manifest per runtime control when a profile can express the semantic difference.
- Derived catalogs and inventories must stay aligned with the editorial source.
- AI Registry component docs must remain extractable from either literal
ComponentDocMeta metadata files or supported editorial factories such as createWave1ComponentDocMeta(descriptor). If a package-owned field uses a metadata factory, verify the registry extractor still projects it before claiming catalog coverage.
@praxisui/metadata-editor, @praxisui/dynamic-form, praxis-filter, and related tooling consume this chain downstream.
@praxisui/dynamic-form materializes FieldMetadata through this chain; it should not carry a
private control map when the package registry/editorial catalog already owns the decision.
@praxisui/metadata-editor must expose the same package-owned metadata shape that runtime fields
consume; renderer coverage gaps should be fixed in the editor bridge, not hidden in docs.
- Metadata-editor field patches use JSON Merge Patch semantics: changed primitive values are emitted,
cleared properties are emitted as
null, and hosts must remove those properties instead of
persisting the literal null unless the canonical field contract explicitly allows it.
entityLookup is an entity contract, not just a visual select variant. Runtime/editor coverage must
preserve canonical optionSource shape: type = RESOURCE_ENTITY, identity/display paths,
rich display, search, pagination, dependsOn, dependencyFilterMap, selectionPolicy,
capabilities, navigation/audit metadata, and detail.kind = surface when a canonical backend
surface exists.
- Inline/editor-critical runtime properties must have visual metadata-editor coverage or an explicit
documented advanced JSON fallback. If a runtime property is added to an inline field, the matching
projects/praxis-metadata-editor/src/lib/config/*.config.ts coverage should be reviewed in the
same cycle.
- Shared overlay infrastructure, layer tokens, and CDK stacking order belong to
@praxisui/core. If an inline field renders but overlay clicks are blocked, verify the core layer scale before patching the field, filter host, or landing app.
- Shared overlay color/contrast tokens also belong to
@praxisui/core. If a dynamic field overlay opens with low contrast, first verify @praxisui/core/theme-bridge.css and the host .cdk-overlay-container mappings for --pdx-overlay-surface and --pdx-overlay-on-surface; only add a host override when the host intentionally uses an overlay surface that differs from the global Material theme.
- Package-owned inline field and panel surface/contrast tokens belong to the inline components in
@praxisui/dynamic-fields (--pdx-inline-field-* and --pdx-inline-panel-*). If host global .mat-mdc-form-field, .mat-mdc-select-panel, or Material option/select token styles break inline filters, fix or preserve these component tokens before adding host-only overrides.
- Inline overlay commit semantics belong to the shared
inlineOverlay contract. Do not create local confirm, commitPolicy, or per-component Apply/Cancel contracts when inlineOverlay.applyMode and inlineOverlay.actions.* can represent the workflow. The public vocabulary is applyMode: "auto" | "explicit": use auto for simple, reversible, single-step inline interactions; use explicit when an overlay has a real draft state such as ranges, multi-selection, presets, sliders, or exploratory visual choices. In explicit, Apply commits, Cancel/Escape/outside close restore the last committed value, and Clear is distinct from Cancel.
Package-Owned Fields vs Host Custom Fields
Package-owned Praxis fields must follow the canonical library path:
- editorial descriptor
- derived metadata
- derived catalog
Host custom fields may use:
ComponentRegistryService.register(...)
ComponentMetadataRegistry.register(ComponentDocMeta)
Do not solve package-owned field issues with host-only patches.
Trigger Conditions
Use this skill when the task changes any of:
controlType
- aliases
- selector mapping
- runtime registry entries
- editorial descriptors
- component metadata
- inventory or catalog content
- inline filter discoverability
- naming/icon/discovery in editor/tooling
- package-owned field onboarding
- host custom field extension path
- official examples or recipes that project backend
RESOURCE_ENTITY metadata into package-owned
dynamic field behavior
Required Workflow
- Decide whether the field is package-owned or host custom.
- Check runtime registry resolution.
- Check metadata/editorial resolution.
- Check downstream discovery in editor/tooling.
- Check runtime/editor coverage status and any documented mismatch.
- Update the governed docs/catalog/inventory that mirror this chain when the canonical editorial source changed.
Required Checks
Always verify:
- runtime component still resolves for the target
controlType
- editorial metadata still resolves friendly name, icon, and discoverable identity
- aliases still resolve correctly
- alias normalization is covered in
@praxisui/core before relying on the dynamic-fields registry
fallback table
- selector-to-control mapping is correct in the
@praxisui/core default selector map or in an
explicit host override, with defaults disabled only at the root injector when intended
- downstream tooling can still discover the field
- any editor/tooling coverage claim remains true
- option-source controls honor backend
includeIds, dependency maps, selected reload policy, and
invalid sort policy instead of hiding backend contract gaps in local runtime code
- package-owned controls projected into AI registry have an applicable authoring control profile when the task touches agentic authoring semantics
- package-owned metadata factories are visible in
tools/ai-registry/component-docs.json after generate:registry:ingestion
- governed docs such as inventory, field catalog, field selection guide, and inline runtime contract still match the real behavior
- derived surfaces such as docs, playground catalog, AI registry, metadata-editor coverage, and dynamic-form materialization are either updated or explicitly not affected
If a field renders but becomes undiscoverable in editor/tooling, the change is incomplete.
High-Risk Failure Modes
- runtime registry updated but metadata registry not updated
- new
controlType added without editorial descriptor
- alias works in runtime but not in tooling
- alias is added only to
ComponentRegistryService residual synonyms, causing runtime resolution to
pass while @praxisui/core, catalogs, metadata-editor, AI profiles, or generated registry
surfaces still do not recognize the canonical identity
- catalog updated manually without updating canonical editorial source
- metadata exported through a factory renders in runtime/editorial tooling but is skipped by the AI Registry extractor, causing missing
authoringManifestProfiles
- consumer patched locally instead of fixing registry/editorial chain
- coverage claimed without evidence
- family authoring manifest projected to components without component-level profiles, causing text, numeric, option, temporal, or specialized controls to look semantically identical to agents
- inline overlay panels appear open but cannot be clicked because a CDK backdrop or shared overlay layer sits above the connected overlay pane
- inline overlay panels mix a dark-theme text token with a light overlay surface, or the inverse, because the host skipped the canonical
--pdx-overlay-surface / --pdx-overlay-on-surface bridge
- inline filter controls mix a host-forced Material field surface with package-owned inline text tokens because global
.mat-mdc-form-field overrides leaked into pdx-inline-* controls
- inline select panels lose dark-theme contrast or visible hover because host/global Material select panel tokens override the package-owned
--pdx-inline-panel-* surface and state tokens
- inline field autosize appears correct in the component but is visually ignored because a consumer shell such as
praxis-filter forces width: auto !important, grid minimums, or field-shell width variables over the package-owned inline width tokens
- inline chips render clear, dropdown/toggle, prefix, or suffix icons in the same visual lane without reserved spacing, causing overlap, redundant actions, or wider-than-needed compact filters
Validation Guidance
Prefer focused checks in this order:
- registry/component specs
- editorial/metadata contract specs
- catalog derivation specs
- downstream editor/tooling specs where affected
- Playwright or integration evidence when visual discovery is part of the change
Always distinguish:
- runtime coverage
- schema/type coverage
- editor/tooling coverage
Do not collapse them into a single "supported" statement.
For metadata-editor bridge changes, include focused validation around alias normalization,
null => remove patch semantics, and inline editor coverage before claiming Dynamic Fields runtime
support is also editor/tooling support.
References
Load these only as needed:
references/runtime-vs-editorial-chain.md
references/package-owned-vs-host-custom.md
references/coverage-semantics.md
references/downstream-consumers.md
1---2name: praxis-dynamic-fields-editorial3description: Use when changing @praxisui/dynamic-fields or praxis-dynamic-fields package control types, aliases, discovery, editorial descriptors, metadata registry entries, selector mappings, inline filter tooling coverage, runtime registry, field catalogs, or any change where runtime support and editor/tooling support may diverge.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-dynamic-fields-editorial6---78# Praxis Dynamic Fields Editorial910This `praxis-fields-*` plus `praxis-dynamic-fields-editorial` skill family is the canonical Codex skill surface for `@praxisui/dynamic-fields` and `projects/praxis-dynamic-fields`; do not create another parallel dynamic-fields skill family unless this family cannot express a proven contract gap.1112Use this skill for the special authoring/discovery model of `@praxisui/dynamic-fields`.1314For focused changes, pair this general editorial skill with the specialized family:15`praxis-fields-runtime-loader` for loader/registry/runtime coverage,16`praxis-fields-option-sources` for async selects, option sources, and entity lookup,17`praxis-fields-editorial-discovery` for descriptor/catalog/tooling coverage, and18`praxis-fields-ai-canvas-validation` for AI manifest, registry ingestion, recipes, or canvas proof.19Use `praxis-fields-control-profile-ai` for per-control AI profiles and capability catalogs,20`praxis-fields-inline-overlay-runtime` for inline overlay apply/cancel/clear semantics,21`praxis-fields-text-number-time-controls` for text, numeric, currency, date, time, and range families,22and `praxis-fields-selection-lookup-controls` for select, autocomplete, chips, tree, list, and lookup families.23For visual authoring coverage inside `@praxisui/metadata-editor`, pair this with24`praxis-metadata-editor-renderer-coverage`; for cascade or option-source dependency normalization in25the editor, use `praxis-metadata-editor-cascade-normalization`.26For operational file upload fields, use `praxis-files-upload-form-field` for `pdx-material-files-upload`,27`valueMode`, ControlValueAccessor behavior, and upload-specific field UX. Return here only when the28dynamic-fields catalog, selector mapping, aliases, or metadata discovery for that field changes.29For rich content or rich-input fields, use `praxis-rich-content-runtime` and30`praxis-rich-content-integration-adapters` for `RichContentDocument` semantics. Return here only when31dynamic-fields metadata discovery, control aliases, selector mapping, or editor/tooling coverage changes.32For CRON or schedule fields, use `praxis-cron-builder-form-field`, `praxis-cron-builder-runtime`, and33`praxis-cron-schedule-authoring` for field/runtime semantics. Return here only when dynamic-fields34catalog registration, selector mapping, aliases, editorial descriptors, or tooling discovery changes.3536This library does not primarily follow the pattern "runtime component has its own config editor". Runtime rendering, editorial discovery, metadata tooling, and editor coverage are separate layers.3738Before changing this skill or a dynamic-fields feature, inspect the current source for the involved39runtime and metadata path. For ordinary controls this means the component, `.metadata.ts`,40`ComponentRegistryService`, `ComponentMetadataRegistry`, editorial registry, catalog/AI files, and41selector mapping in `@praxisui/core`. For option-source controls, also inspect42`OptionSourceMetadata`, `GenericCrudService.filterOptionSourceOptions`,43`GenericCrudService.getOptionSourceOptionsByIds`, and the backend `x-ui.optionSource` projection.44For wrapper controls, inspect the owning package skill first: files upload, rich content, and CRON45field behavior belong to those package contracts; dynamic-fields owns only control registration,46metadata discovery, selector mapping, catalogs, and downstream materialization.47The goal is to encode working Praxis platform knowledge into the skill, not merely document a UI48convention.4950First resolve the Angular workspace root. In the platform monorepo the files may live under51`praxis-ui-angular/projects/...`; in a standalone Angular checkout they may live directly under52`projects/...`. Audit the active `praxis-ui-angular` workspace, not stale issue worktrees such as53`praxis-ui-angular-issue*`, unless the user explicitly targets one of those worktrees.5455When the platform monorepo is available, inspect `projects/praxis-dynamic-fields/AGENTS.md` before56editing and keep its governed docs in scope when relevant:5758- `projects/praxis-dynamic-fields/docs/dynamic-fields-inventory.md`59- `projects/praxis-dynamic-fields/docs/dynamic-fields-field-catalog.md`60- `projects/praxis-dynamic-fields/docs/dynamic-fields-field-selection-guide.md`61- `projects/praxis-dynamic-fields/docs/dynamic-fields-host-custom-field-guide.md`62- `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-filter-catalog.md`63- `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-filter-runtime-contract.md`64- `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-components-guide.md`6566If the task is to implement or review backend `RESOURCE_ENTITY` option sources, use67`praxis-resource-entity-lookup-backend` first. Use this skill when that backend change affects68Angular runtime registry, editorial descriptors, metadata-editor coverage, recipes, catalogs, or69AI registry projection.7071## Canonical Model7273Treat these as distinct:74751. runtime render762. forms integration773. metadata/editorial discovery784. hot metadata behavior7980Do not assume runtime support implies editor/tooling support.8182For metadata-driven option-source cascades, keep the boundary explicit:8384- `x-ui.optionSource.dependsOn` is the canonical backend/editor dependency declaration.85- `x-ui.optionSource.dependencyFilterMap` is the canonical explicit mapping when the dependent field name differs from the backend filter key.86- `x-ui.optionSource.includeIds` is an explicit runtime permission. Option-source filters must send `includeIds` only when this flag is `true`; when it is `false` or absent, selected-value rehydration must use the canonical by-ids/display path instead of adding `includeIds` to filter requests.87- `x-ui.optionSource.filterEndpoint`, `byIdsEndpoint`, `selectedReloadPolicy`, and `invalidSortPolicy` are backend runtime-contract facts. Editors and examples may display or validate them, but must not synthesize them from local host assumptions when the backend publishes them.88- `dependencyFields` and `dependencyFilterMap` are the runtime/manual metadata consumed by select components.89- A bridge may derive runtime metadata from `optionSource`, but it should not synthesize authoring state or reset/reload policy unless the canonical contract says so.90- For dependent sources, editor/runtime support is incomplete until selected-value reload is proven on reopen/edit. If the selected ID is not self-contained, the runtime must use a contextual option-source by-ids path or downgrade the claim according to `selectedReloadPolicy`; do not assume the filter cascade proves hydration.9192If `selectedReloadPolicy` is `required` or `supported`, verify that presentation mode, reopen/edit,93and selected-value preload call the option-source by-ids path rather than a generic options path.94If it is `unsupported-with-waiver`, the UI may show a degraded retained value, but the example or95editor must mark the source as partial and point back to the backend/platform waiver.9697## Canonical Boundaries9899- `ComponentRegistryService` owns runtime component resolution by `controlType`.100- `ComponentMetadataRegistry` owns editorial discovery metadata.101- `src/lib/editorial/**` owns canonical package editorial descriptors.102- `@praxisui/core` owns `FieldControlType`, `OptionSourceMetadata`,103 `DEFAULT_FIELD_SELECTOR_CONTROL_TYPE_MAP`, and selector registry tokens. Do not add a104 dynamic-fields-only alias when the canonical type or selector mapping belongs in core.105- `@praxisui/core` also owns canonical control-type alias normalization through106 `resolveControlTypeAlias(...)` and `normalizeControlTypeToken(...)`. `ComponentRegistryService`107 may keep residual runtime synonyms for compatibility after calling the core normalizer, but that108 local table is not the place to introduce new canonical names. When adding or reviewing an alias,109 update/prove the core normalizer first, keep registry fallback behavior compatible, and prevent110 aliases from becoming primary catalog/editorial choices.111- Agentic authoring uses one family-level manifest for shared `FieldMetadata`/registry/editorial semantics plus component-level control profiles for granular per-control operation hints; use `praxis-fields-control-profile-ai` for that layer and do not duplicate a full manifest per runtime control when a profile can express the semantic difference.112- Derived catalogs and inventories must stay aligned with the editorial source.113- AI Registry component docs must remain extractable from either literal `ComponentDocMeta` metadata files or supported editorial factories such as `createWave1ComponentDocMeta(descriptor)`. If a package-owned field uses a metadata factory, verify the registry extractor still projects it before claiming catalog coverage.114- `@praxisui/metadata-editor`, `@praxisui/dynamic-form`, `praxis-filter`, and related tooling consume this chain downstream.115- `@praxisui/dynamic-form` materializes `FieldMetadata` through this chain; it should not carry a116 private control map when the package registry/editorial catalog already owns the decision.117- `@praxisui/metadata-editor` must expose the same package-owned metadata shape that runtime fields118 consume; renderer coverage gaps should be fixed in the editor bridge, not hidden in docs.119- Metadata-editor field patches use JSON Merge Patch semantics: changed primitive values are emitted,120 cleared properties are emitted as `null`, and hosts must remove those properties instead of121 persisting the literal `null` unless the canonical field contract explicitly allows it.122- `entityLookup` is an entity contract, not just a visual select variant. Runtime/editor coverage must123 preserve canonical `optionSource` shape: `type = RESOURCE_ENTITY`, identity/display paths,124 rich `display`, search, pagination, `dependsOn`, `dependencyFilterMap`, `selectionPolicy`,125 `capabilities`, navigation/audit metadata, and `detail.kind = surface` when a canonical backend126 surface exists.127- Inline/editor-critical runtime properties must have visual metadata-editor coverage or an explicit128 documented advanced JSON fallback. If a runtime property is added to an inline field, the matching129 `projects/praxis-metadata-editor/src/lib/config/*.config.ts` coverage should be reviewed in the130 same cycle.131- Shared overlay infrastructure, layer tokens, and CDK stacking order belong to `@praxisui/core`. If an inline field renders but overlay clicks are blocked, verify the core layer scale before patching the field, filter host, or landing app.132- Shared overlay color/contrast tokens also belong to `@praxisui/core`. If a dynamic field overlay opens with low contrast, first verify `@praxisui/core/theme-bridge.css` and the host `.cdk-overlay-container` mappings for `--pdx-overlay-surface` and `--pdx-overlay-on-surface`; only add a host override when the host intentionally uses an overlay surface that differs from the global Material theme.133- Package-owned inline field and panel surface/contrast tokens belong to the inline components in `@praxisui/dynamic-fields` (`--pdx-inline-field-*` and `--pdx-inline-panel-*`). If host global `.mat-mdc-form-field`, `.mat-mdc-select-panel`, or Material option/select token styles break inline filters, fix or preserve these component tokens before adding host-only overrides.134- Inline overlay commit semantics belong to the shared `inlineOverlay` contract. Do not create local `confirm`, `commitPolicy`, or per-component Apply/Cancel contracts when `inlineOverlay.applyMode` and `inlineOverlay.actions.*` can represent the workflow. The public vocabulary is `applyMode: "auto" | "explicit"`: use `auto` for simple, reversible, single-step inline interactions; use `explicit` when an overlay has a real draft state such as ranges, multi-selection, presets, sliders, or exploratory visual choices. In `explicit`, Apply commits, Cancel/Escape/outside close restore the last committed value, and Clear is distinct from Cancel.135136## Package-Owned Fields vs Host Custom Fields137138Package-owned Praxis fields must follow the canonical library path:139140- editorial descriptor141- derived metadata142- derived catalog143144Host custom fields may use:145146- `ComponentRegistryService.register(...)`147- `ComponentMetadataRegistry.register(ComponentDocMeta)`148149Do not solve package-owned field issues with host-only patches.150151## Trigger Conditions152153Use this skill when the task changes any of:154155- `controlType`156- aliases157- selector mapping158- runtime registry entries159- editorial descriptors160- component metadata161- inventory or catalog content162- inline filter discoverability163- naming/icon/discovery in editor/tooling164- package-owned field onboarding165- host custom field extension path166- official examples or recipes that project backend `RESOURCE_ENTITY` metadata into package-owned167 dynamic field behavior168169## Required Workflow1701711. Decide whether the field is package-owned or host custom.1722. Check runtime registry resolution.1733. Check metadata/editorial resolution.1744. Check downstream discovery in editor/tooling.1755. Check runtime/editor coverage status and any documented mismatch.1766. Update the governed docs/catalog/inventory that mirror this chain when the canonical editorial source changed.177178## Required Checks179180Always verify:181182- runtime component still resolves for the target `controlType`183- editorial metadata still resolves friendly name, icon, and discoverable identity184- aliases still resolve correctly185- alias normalization is covered in `@praxisui/core` before relying on the dynamic-fields registry186 fallback table187- selector-to-control mapping is correct in the `@praxisui/core` default selector map or in an188 explicit host override, with defaults disabled only at the root injector when intended189- downstream tooling can still discover the field190- any editor/tooling coverage claim remains true191- option-source controls honor backend `includeIds`, dependency maps, selected reload policy, and192 invalid sort policy instead of hiding backend contract gaps in local runtime code193- package-owned controls projected into AI registry have an applicable authoring control profile when the task touches agentic authoring semantics194- package-owned metadata factories are visible in `tools/ai-registry/component-docs.json` after `generate:registry:ingestion`195- governed docs such as inventory, field catalog, field selection guide, and inline runtime contract still match the real behavior196- derived surfaces such as docs, playground catalog, AI registry, metadata-editor coverage, and dynamic-form materialization are either updated or explicitly not affected197198If a field renders but becomes undiscoverable in editor/tooling, the change is incomplete.199200## High-Risk Failure Modes201202- runtime registry updated but metadata registry not updated203- new `controlType` added without editorial descriptor204- alias works in runtime but not in tooling205- alias is added only to `ComponentRegistryService` residual synonyms, causing runtime resolution to206 pass while `@praxisui/core`, catalogs, metadata-editor, AI profiles, or generated registry207 surfaces still do not recognize the canonical identity208- catalog updated manually without updating canonical editorial source209- metadata exported through a factory renders in runtime/editorial tooling but is skipped by the AI Registry extractor, causing missing `authoringManifestProfiles`210- consumer patched locally instead of fixing registry/editorial chain211- coverage claimed without evidence212- family authoring manifest projected to components without component-level profiles, causing text, numeric, option, temporal, or specialized controls to look semantically identical to agents213- inline overlay panels appear open but cannot be clicked because a CDK backdrop or shared overlay layer sits above the connected overlay pane214- inline overlay panels mix a dark-theme text token with a light overlay surface, or the inverse, because the host skipped the canonical `--pdx-overlay-surface` / `--pdx-overlay-on-surface` bridge215- inline filter controls mix a host-forced Material field surface with package-owned inline text tokens because global `.mat-mdc-form-field` overrides leaked into `pdx-inline-*` controls216- inline select panels lose dark-theme contrast or visible hover because host/global Material select panel tokens override the package-owned `--pdx-inline-panel-*` surface and state tokens217- inline field autosize appears correct in the component but is visually ignored because a consumer shell such as `praxis-filter` forces `width: auto !important`, grid minimums, or field-shell width variables over the package-owned inline width tokens218- inline chips render clear, dropdown/toggle, prefix, or suffix icons in the same visual lane without reserved spacing, causing overlap, redundant actions, or wider-than-needed compact filters219220## Validation Guidance221222Prefer focused checks in this order:223224- registry/component specs225- editorial/metadata contract specs226- catalog derivation specs227- downstream editor/tooling specs where affected228- Playwright or integration evidence when visual discovery is part of the change229230Always distinguish:231232- runtime coverage233- schema/type coverage234- editor/tooling coverage235236Do not collapse them into a single "supported" statement.237238For metadata-editor bridge changes, include focused validation around alias normalization,239`null => remove` patch semantics, and inline editor coverage before claiming Dynamic Fields runtime240support is also editor/tooling support.241242## References243244Load these only as needed:245246- `references/runtime-vs-editorial-chain.md`247- `references/package-owned-vs-host-custom.md`248- `references/coverage-semantics.md`249- `references/downstream-consumers.md`