# Praxis Dialog Surface Global Actions

> Use when changing or reviewing `@praxisui/dialog` surface/global-action materialization, `providePraxisSurfaceGlobalActions`, `GLOBAL_SURFACE_SERVICE`, `PraxisSurfaceHostComponent` dialog hosting, `SURFACE_DRAWER_BRIDGE`, surface open payloads, component/template registry resolution, selection result forwarding, dialog surface runtime, or metadata-driven dialog/surface open integration.

- Skill: `codexrodrigues/praxis-dialog-surface-global-actions` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add codexrodrigues/praxis-dialog-surface-global-actions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/praxis-dialog-surface-global-actions/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-dialog-surface-global-actions

---


# Praxis Dialog Surface Global Actions

Use this skill for the bridge where metadata-driven global actions materialize surfaces inside dialogs or host drawers. This is not a generic overlay shortcut; it is the runtime projection of governed surface/action contracts.

## Canonical Boundary

- `@praxisui/core` owns `GlobalActionRef`, `GLOBAL_SURFACE_SERVICE`, `GLOBAL_DIALOG_SERVICE`, surface open payloads, materializers, component metadata registry, and shared action validation.
- `@praxisui/dialog` owns the dialog-backed implementation of global dialog/surface actions.
- `providePraxisDialogGlobalActions()` bridges alert, confirm, prompt, and registered component dialogs through `GLOBAL_DIALOG_SERVICE`.
- `providePraxisSurfaceGlobalActions()` bridges materialized surfaces through `GLOBAL_SURFACE_SERVICE`, using `PraxisDialog` for dialog presentation and `SURFACE_DRAWER_BRIDGE` for drawer presentation.
- Hosted child widgets own their own runtime semantics and authoring manifests.

## Required Inventory

Inspect:

- `projects/praxis-dialog/AGENTS.md`
- `projects/praxis-dialog/README.md`
- `projects/praxis-dialog/docs/host-dialog-integration.md`
- `projects/praxis-dialog/src/lib/providers/dialog-global-actions.provider.ts`
- `projects/praxis-dialog/src/lib/providers/surface-global-actions.provider.ts`
- `projects/praxis-dialog/src/lib/providers/dialog-global-presets.provider.ts`
- `projects/praxis-dialog/src/lib/dialog/dialog.service.ts`
- `projects/praxis-dialog/src/lib/dialog/dialog.tokens.ts`
- `projects/praxis-dialog/src/lib/praxis-dialog.metadata.ts`
- `projects/praxis-core/src/lib/models/global-action.model.ts`
- core surface/global-action services, payload validators, and focused specs

Use `praxis-core-global-actions-metadata` for shared action contracts and `praxis-dialog-global-actions-ai` for dialog authoring manifests and registry ingestion.

## Materialization Rules

- Persist and consume structured `GlobalActionRef`/surface payloads, not command strings or localized action aliases.
- `dialog.open` requires `componentId`. Resolve via `ComponentMetadataRegistry` first, then dialog content registry.
- Apply `inputs` after the component exists and trigger change detection.
- Surface open payloads must pass through the core `SurfaceOpenMaterializerService` before dialog/drawer projection.
- Dialog surface runtime may expose `closed$`, `result$`, `emitResult`, `close`, and `updateSize`; it must not become a business workflow engine.
- Forward row/selection outputs from `PraxisSurfaceHostComponent` as surface results when the hosted component emits them.
- Treat forwarded row/selection envelopes and `surfaceRuntime.result$` emissions as runtime event
  forwarding. They are not persisted widget inputs, not child config-editor results, and not permission
  to patch host/page/form/table state directly from the dialog provider.
- If a surface result should update a page, component, or domain state, route it through the authored
  `GlobalActionRef`, `surface.result`, `dynamicPage.composition.dispatch`, composition link, or
  backend-confirmed domain action that owns that mutation. The dialog provider should emit/close; it
  should not decide the business continuation by parsing result type, row text, or localized labels.
- Drawer presentation requires `SURFACE_DRAWER_BRIDGE`; do not silently fall back to a different drawer contract.
- `providePraxisSurfaceGlobalActions()` and `providePraxisSurfaceDrawerBridge()` may coexist in the
  root injector or in a feature `EnvironmentInjector`. In feature scope, register both in the same
  injector so the global surface factory can resolve the optional drawer bridge; sibling routes do
  not inherit providers from that feature injector.
- Provider registration and resolution must remain inert: neither provider opens an overlay, starts
  polling, or schedules recurring work until an explicit `surface.open` requests presentation.
- Host/domain side effects after `afterClosed` or `result$` remain host-owned.

## Red Flags

Refactor or reject:

- `surface.open:{...}` strings, `showAlert:*` command strings, or local switch/case action grammars
- dialog providers that bypass core payload validation or materialization
- unregistered component ids invented by AI or host code
- surface drawer implementations that skip `SURFACE_DRAWER_BRIDGE`
- providers that persist `surfaceRuntime`, `result$` envelopes, row selections, or materialized
  widget inputs as component/page config
- child widget config patched through dialog shell contracts instead of delegated child manifests

## Validation

Use focused checks:

- `src/lib/providers/dialog-global-actions.provider.spec.ts`
- `src/lib/providers/surface-global-actions.provider.spec.ts`
- an integration spec using both concrete surface providers, proving idle resolution and exactly one
  drawer materialization after an explicit `surface.open`
- `src/lib/providers/dialog-global-presets.provider.spec.ts`
- core global action/payload validator specs when shared action contracts change
- service/component specs when overlay lifecycle or registry open behavior changes
- registry ingestion/docs validation when component metadata, manifests, or docs projections change

State whether public API, docs, examples, AI registry, or generated assets were updated or intentionally unaffected.

