@cat-factory/app 0.152.1 → 0.153.0

package/app/components/panels/AppOverlayHost.logic.spec.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest'
+import { selectOverlay } from './AppOverlayHost.logic'
+import type { OverlayContribution } from '~/modular/slots'
+
+/**
+ * The pure selection behind `<AppOverlayHost>` (extension slice D — the frontend-extension-mechanism
+ * initiative). Pins the resilience the seam advertises: a matching id mounts its component, a
+ * dangling open (no registered component) degrades to nothing (`missing: true`, the host's dev-warn
+ * signal), no open renders nothing, and duplicate ids fail fast (the boot guard's contract).
+ */
+// A plain object stands in for the SFC — `selectOverlay` only ever keys by id.
+const overlay = (id: string): OverlayContribution => ({ id, component: { name: id } as never })
+
+describe('selectOverlay (AppOverlayHost slice D)', () => {
+  it('returns nothing when no overlay is open (null / undefined id)', () => {
+    const overlays = [overlay('acme:security-dashboard-overlay')]
+    expect(selectOverlay(overlays, null)).toEqual({ component: null, missing: false })
+    expect(selectOverlay(overlays, undefined)).toEqual({ component: null, missing: false })
+  })
+
+  it('picks the component whose id matches the active overlay', () => {
+    const entry = overlay('acme:security-dashboard-overlay')
+    const { component, missing } = selectOverlay([entry], 'acme:security-dashboard-overlay')
+    expect(component).toBe(entry.component)
+    expect(missing).toBe(false)
+  })
+
+  it('degrades a dangling open to nothing and flags it missing (no crash)', () => {
+    const { component, missing } = selectOverlay([overlay('acme:one')], 'acme:gone')
+    expect(component).toBeNull()
+    expect(missing).toBe(true)
+  })
+
+  it('fails fast on duplicate overlay ids (the boot guard contract)', () => {
+    const dupes = [overlay('acme:dup'), overlay('acme:dup')]
+    expect(() => selectOverlay(dupes, 'acme:dup')).toThrow()
+  })
+})

package/app/components/panels/AppOverlayHost.logic.ts

@@ -0,0 +1,24 @@
+import type { Component } from 'vue'
+import { resolveComponentRegistry } from '@modular-vue/core'
+import type { OverlayContribution } from '~/modular/slots'
+
+/**
+ * Pure selection for `<AppOverlayHost>` (extension slice D). Indexes the merged `appOverlays`
+ * slot into an id → component registry (`resolveComponentRegistry` — the same pick-one primitive
+ * `StepResultViewHost` uses; duplicate ids throw, as validated once at boot) and picks the entry
+ * matching the active overlay id.
+ *
+ * Kept side-effect-free — the host's dev-warn for a dangling open lives in a `watchEffect`, not
+ * here — so both the host's `computed` and the unit spec can call it. `missing` is the explicit
+ * dangling-open signal (an id with no registered component, e.g. a stale nav closure after an
+ * extension was removed): the host degrades that to nothing rather than crashing.
+ */
+export function selectOverlay(
+  overlays: OverlayContribution[],
+  activeId: string | null | undefined,
+): { component: Component | null; missing: boolean } {
+  if (!activeId) return { component: null, missing: false }
+  const registry = resolveComponentRegistry(overlays)
+  const component = (registry.get(activeId) as Component | undefined) ?? null
+  return { component, missing: !component }
+}

package/app/components/panels/AppOverlayHost.vue

@@ -0,0 +1,57 @@
+<script setup lang="ts">
+// Universal CONSUMER-overlay host (extension slice D — the frontend-extension-mechanism
+// initiative, docs/initiatives/frontend-extension-mechanism.md). The one top-level surface a
+// consumer deployment could not extend before: `pages/index.vue` hand-mounts every first-party
+// modal as a `v-if`, so a consumer nav item's `run` closure had nothing to open. This host is
+// the seam — a deployment registers `{ id: '<ns>:<name>', component }` in the `appOverlays` slot
+// and opens it with `ui.openOverlay(id, subject?)` (usually via `useAppOverlays().open(...)`).
+//
+// The mechanism is the same slice-2 pick-one primitive `StepResultViewHost` uses: index the
+// merged `appOverlays` slot into an id → component registry via `resolveComponentRegistry`, and
+// mount the entry whose id matches the active `ui.activeOverlay` pointer. Only ONE consumer
+// overlay is open at a time. The mounted overlay receives the optional `subject` as a prop and
+// emits `close` (the consumer overlay composes `ResultWindowShell` / `useModalBehavior` for its
+// own chrome, so Escape/backdrop/focus-trap are inherited — see the consumer-extensions guide).
+//
+// First-party modals stay hand-mounted in `index.vue`; this seam is deliberately scoped to
+// consumer extensions (strangler discipline — the ~34 existing lazy modals are not migrated).
+import { computed, watchEffect, type Component } from 'vue'
+import { useReactiveSlots } from '@modular-vue/runtime'
+import type { AppSlots } from '~/modular/slots'
+import { selectOverlay } from './AppOverlayHost.logic'
+
+const ui = useUiStore()
+const slots = useReactiveSlots<AppSlots>()
+
+// Pick the component for the active overlay id via the pure `selectOverlay` helper (indexes the
+// merged `appOverlays` slot with `resolveComponentRegistry`; duplicate ids throw, validated once
+// at boot in `modular.client.ts`). Recomputed if a consumer module's contributions change (they
+// don't after boot, but the read is cheap).
+const selection = computed(() => selectOverlay(slots.value.appOverlays ?? [], ui.activeOverlay?.id))
+const active = computed<Component | null>(() => selection.value.component)
+
+// Dev guard: a dangling open (`openOverlay('acme:x')` with no registered component — e.g. a stale
+// nav closure after an extension was removed) degrades to nothing rather than crashing. Kept in a
+// `watchEffect` — not the `computed` above — so the selection stays side-effect-free, mirroring
+// `StepResultViewHost`.
+if (import.meta.dev) {
+  watchEffect(() => {
+    if (selection.value.missing) {
+      const id = ui.activeOverlay?.id
+      console.warn(
+        `[AppOverlayHost] ui.openOverlay('${id}') has no registered component. ` +
+          `Contribute { id: '${id}', component } to the appOverlays slot in a registerAppModule module.`,
+      )
+    }
+  })
+}
+</script>
+
+<template>
+  <component
+    :is="active"
+    v-if="active"
+    :subject="ui.activeOverlay?.subject"
+    @close="ui.closeOverlay()"
+  />
+</template>

package/app/composables/useAppOverlays.ts

@@ -0,0 +1,26 @@
+import { computed } from 'vue'
+
+/**
+ * The public seam a consumer deployment uses to open its own top-level overlays (extension
+ * slice D — the frontend-extension-mechanism initiative). A deployment contributes an overlay
+ * component to the `appOverlays` slot (`{ id: '<ns>:<name>', component }`) and opens it from a
+ * nav item's `run` closure (or any consumer code) with `useAppOverlays().open('<ns>:<name>')`.
+ * The single `<AppOverlayHost>` in `pages/index.vue` resolves the slot and mounts the matching
+ * component, handing it the optional `subject`.
+ *
+ * This is a thin, auto-imported wrapper over the `ui` store's overlay pointer so a consumer
+ * never has to reach into the layer's Pinia stores directly — the same decoupling the rest of
+ * the consumer surface follows (auto-imported composables + `#components`, no deep layer
+ * imports). Opening a second overlay replaces the first (a pick-one host).
+ */
+export function useAppOverlays() {
+  const ui = useUiStore()
+  return {
+    /** The active consumer overlay (`{ id, subject? }`) or null when none is open. */
+    active: computed(() => ui.activeOverlay),
+    /** Open the `appOverlays`-slot overlay with this id, optionally passing it a subject. */
+    open: (id: string, subject?: unknown) => ui.openOverlay(id, subject),
+    /** Close the active consumer overlay. */
+    close: () => ui.closeOverlay(),
+  }
+}

package/app/docs/consumer-extensions.md

@@ -69,6 +69,7 @@ export default defineNuxtPlugin(() => {
 | Custom task types                   | `taskTypes`       | `{ taskType: '<ns>:<name>', presentation, fields?, defaultPipelineId?, formPanel? }`             | `AddTaskModal` picker/fields + `TaskCard` badge (via `taskTypeMeta`) |
 | Sidebar / command-palette / toolbar | `nav`             | `{ id, labelKey, icon, surfaces, gate?, run, sidebar?, command?, toolbar? }`                     | the three shells via `useNavContributions`                           |
 | Inspector body panels               | `inspectorPanels` | `{ id, component, when(block), order }` (`PanelEntry<Block>`)                                    | `<PanelsOutlet>` in `InspectorPanel`                                 |
+| Top-level overlays                  | `appOverlays`     | `{ id: '<ns>:<name>', component }`                                                               | `<AppOverlayHost>` via `useAppOverlays().open(id)`                   |
 | Multi-step wizards                  | (journeys)        | `registerJourney` + step modules                                                                 | `<JourneyHost>` / `<JourneyOutlet>`                                  |
 | Locale strings                      | (i18n)            | `i18n/locales/*.json` in the deployment                                                          | `@nuxtjs/i18n` layer deep-merge                                      |
 
@@ -135,6 +136,33 @@ task created with it round-trips with zero host edits.
 > silently — the type just won't pre-select a pipeline and an unpaired `formPanel` degrades to the
 > descriptor `fields`. Prefer backend registration when you want the fail-fast guardrail.
 
+### Top-level overlays (`appOverlays`)
+
+A nav item's `run` closure — or any consumer code — often needs to open a full-screen panel of
+its own: a dashboard, a wizard, a settings surface. The layer's first-party modals are
+hand-mounted in `pages/index.vue`, which a consumer can't edit, so the `appOverlays` slot + the
+single `<AppOverlayHost>` are the seam:
+
+1. Contribute `{ id: '<ns>:<name>', component }` to the `appOverlays` slot (see
+   `acme:security-dashboard-overlay` in the example module).
+2. Open it from anywhere with the auto-imported `useAppOverlays().open('<ns>:<name>', subject?)`
+   — typically a nav item's `run` closure. The optional `subject` is any value your overlay
+   renders against (e.g. a block id); it reaches the component as a `subject` prop.
+3. `<AppOverlayHost>` resolves the slot with `resolveComponentRegistry` (the same pick-one
+   primitive `resultViews` uses) and mounts the matching component, wiring its `close` emit to
+   `useAppOverlays().close()`.
+
+It is a **pick-one** host: opening a second overlay replaces the first, and `close()` clears it.
+Compose the shared `ResultWindowShell` (via `#components`) for chrome so your overlay inherits
+focus-trap / scroll-lock / shared-stack Escape — emit `close` from its `@close`. A dangling open
+(`open('<ns>:x')` with no registered component — e.g. a stale closure after the extension was
+removed) degrades to nothing (a dev-console warning names the id), never a crash. Duplicate ids
+across modules throw at boot, like every other slot.
+
+> **Scope.** This seam is for CONSUMER overlays. The layer's own ~34 first-party modals stay
+> hand-mounted in `index.vue` and are migrated only opportunistically — don't reach for
+> `appOverlays` to replace a first-party fast-path modal.
+
 ## Reuse the shared building blocks — don't reinvent them
 
 The layer ships window/inspector primitives you compose instead of hand-rolling chrome or
@@ -152,6 +180,7 @@ below). Compose these:
 | `InspectorSection`     | `#components` → `PanelsInspectorSection`  | The collapsible inspector-section shell (chevron header, count, hint) so a consumer panel reads like a built-in one.                                                                                                                                                                                          |
 | `useResultView(id)`    | auto-imported                             | The window seam contract: `{ open, blockId, instanceId, stepIndex, close }` (+ an `onOpen` loader for windows that fetch, and an `onClose` flush). Escape is owned by the shell, not here.                                                                                                                    |
 | `usePanelSubject<T>()` | `@modular-vue/core`                       | Read the block injected into an inspector panel by `<PanelsOutlet>`.                                                                                                                                                                                                                                          |
+| `useAppOverlays()`     | auto-imported                             | Open / close your own top-level overlays: `{ open(id, subject?), close(), active }`. The store-free seam a nav `run` closure uses to open an `appOverlays`-slot component (see "Top-level overlays").                                                                                                         |
 
 > **Reference layer components through `#components`, not bare tags.** Nuxt auto-registers a
 > layer's components under a **path-derived** name (`components/panels/ResultWindowShell.vue`

package/app/modular/nav-contributions.spec.ts

@@ -52,6 +52,7 @@ const slots = (): AppSlots => ({
   inspectorPanels: [],
   taskTypes: [],
   taskTypeFormPanels: [],
+  appOverlays: [],
 })
 const ids = (s: unknown) => (s as AppSlots).nav.map((i) => i.id)
 

package/app/modular/registry.spec.ts

@@ -111,4 +111,27 @@ describe('app modular registry', () => {
     expect(ids).toContain('build-pipeline')
     expect(ids).toContain('consumer:reports')
   })
+
+  it('merges a consumer-contributed overlay into the appOverlays slot (slice-D extensibility)', () => {
+    // A deployment contributes its OWN top-level overlay to the `appOverlays` slot; the layer's
+    // single `<AppOverlayHost>` mounts it on `ui.openOverlay(id)` — no host edit (the slice-D
+    // extensibility promise). A fake component (plain object) stands in for the SFC.
+    const fakeOverlay = { name: 'AcmeSecurityDashboard' }
+    registerAppModule(
+      defineModule({
+        id: 'consumer:overlay',
+        version: '1.0.0',
+        slots: {
+          appOverlays: [{ id: 'acme:security-dashboard-overlay', component: fakeOverlay }],
+        },
+      }),
+    )
+
+    const slots = createAppRegistry({ gates: NO_GATES }).resolveManifest().slots as {
+      appOverlays: { id: string }[]
+    }
+    // The slot exists by default (empty) even with no first-party overlays, and the consumer
+    // entry lands in it.
+    expect(slots.appOverlays.map((o) => o.id)).toContain('acme:security-dashboard-overlay')
+  })
 })

package/app/modular/registry.ts

@@ -108,6 +108,7 @@ export function createAppRegistry(
       inspectorPanels: [],
       taskTypes: [],
       taskTypeFormPanels: [],
+      appOverlays: [],
     },
   }).use(journeysPlugin())
   for (const mod of [...FIRST_PARTY_MODULES, ...extraModules, ...consumerModules]) {

package/app/modular/slots.ts

@@ -31,6 +31,14 @@ import type { NavContribution } from './nav-contributions'
  *    per custom task type, addressed by the type's `formPanel` id and paired via
  *    `resolveComponentRegistry` (same shape as `resultViews`); shown INSTEAD of the
  *    descriptor-driven `fields`. An unpaired id degrades to the descriptor fields.
+ *  - `appOverlays` (extension slice D) — top-level modals/overlays a consumer module
+ *    contributes ({@link OverlayContribution}, an id → component `ComponentEntry`),
+ *    opened by `ui.openOverlay(id, subject?)` / `useAppOverlays().open(...)` and
+ *    mounted by the single `<AppOverlayHost>` in `pages/index.vue` (which selects the
+ *    active entry through `resolveComponentRegistry`, the same pick-one primitive
+ *    `resultViews` uses). This is the one host surface a consumer flatly could not
+ *    extend before — a nav item's `run` closure now has something to open. First-party
+ *    modals stay hand-mounted in `index.vue`; the seam is for consumer overlays.
  *
  * The index signature is mutable (`unknown[]`) to satisfy the runtime's
  * `SlotMap` constraint while `unknown[]` still meets `useReactiveSlots`'
@@ -43,6 +51,7 @@ export interface AppSlots {
   inspectorPanels: PanelEntry<Block>[]
   taskTypes: CustomTaskType[]
   taskTypeFormPanels: ResultViewContribution[]
+  appOverlays: OverlayContribution[]
   [key: string]: unknown[]
 }
 
@@ -57,3 +66,15 @@ export interface AppSlots {
  * custom task type's `formPanel` id).
  */
 export type ResultViewContribution = ComponentEntry<Component>
+
+/**
+ * One consumer-contributed top-level overlay (a modal/panel with no first-party
+ * home), addressed by its namespaced `<ns>:<name>` id. A plain `ComponentEntry`,
+ * so `<AppOverlayHost>` indexes the merged `appOverlays` slot with the same
+ * `resolveComponentRegistry` pick-one primitive as `resultViews` and mounts the
+ * entry whose id matches the active `ui.openOverlay(...)` request. The overlay
+ * component receives the (optional) subject as a `subject` prop and emits `close`;
+ * it composes the layer's `ResultWindowShell` / `useModalBehavior` for its own
+ * chrome (see the consumer-extensions guide).
+ */
+export type OverlayContribution = ComponentEntry<Component>

package/app/pages/index.vue

@@ -16,6 +16,7 @@ import InspectorPanel from '~/components/panels/InspectorPanel.vue'
 import DecisionModal from '~/components/panels/DecisionModal.vue'
 import AgentStepDetail from '~/components/panels/AgentStepDetail.vue'
 import StepResultViewHost from '~/components/panels/StepResultViewHost.vue'
+import AppOverlayHost from '~/components/panels/AppOverlayHost.vue'
 import AddTaskModal from '~/components/board/AddTaskModal.vue'
 import ReviewFrictionDialog from '~/components/board/ReviewFrictionDialog.vue'
 import CreateInitiativeModal from '~/components/board/CreateInitiativeModal.vue'
@@ -377,6 +378,9 @@ watch(
       <DecisionModal />
       <AgentStepDetail />
       <StepResultViewHost />
+      <!-- Consumer-contributed top-level overlays (extension slice D). Renders nothing until a
+           consumer opens one via `ui.openOverlay` / `useAppOverlays().open(...)`. -->
+      <AppOverlayHost />
       <AddTaskModal />
       <ReviewFrictionDialog v-if="ui.reviewFrictionContext" />
       <CreateInitiativeModal />

package/app/plugins/modular.client.ts

@@ -15,7 +15,7 @@ import {
   environmentSetupModule,
   environmentSetupPersistence,
 } from '~/modular/journeys/environmentSetup'
-import type { AppSlots, ResultViewContribution } from '~/modular/slots'
+import type { AppSlots, OverlayContribution, ResultViewContribution } from '~/modular/slots'
 import type { Block, CustomAgentKind, CustomTaskType } from '~/types/domain'
 
 /**
@@ -102,6 +102,11 @@ export default defineNuxtPlugin({
     // duplicate `formPanel` id across the first-party + consumer modules throws at BOOT
     // rather than the first time the create-task form opens a custom type's section.
     resolveComponentRegistry((slots.taskTypeFormPanels ?? []) as ResultViewContribution[])
+    // Same fail-fast for the consumer-overlay registry (extension slice D): a duplicate
+    // `appOverlays` id across the first-party + consumer modules throws at BOOT rather than
+    // the first time `<AppOverlayHost>` mounts one. The slot is static after this resolve, so
+    // the host's own reactive re-resolve is a cheap read this has already validated.
+    resolveComponentRegistry((slots.appOverlays ?? []) as OverlayContribution[])
     // Consumer agent kinds + task types contributed as CODE to the static `agentKinds` /
     // `taskTypes` slots (module slots resolve once, so the static base is the full set).
     useAgentsStore().registerConsumerKinds((slots.agentKinds ?? []) as CustomAgentKind[])

package/app/stores/ui/modals.ts

@@ -839,6 +839,33 @@ function createAiOnboardingModals() {
   }
 }
 
+/**
+ * The generic CONSUMER-overlay host (extension slice D — the frontend-extension-mechanism
+ * initiative). Unlike every sub-slice above, this holds NO per-modal boolean: it is a single
+ * pick-one pointer to whichever consumer-contributed overlay (the `appOverlays` slot) is
+ * currently open, so a consumer nav item's `run` closure finally has something to open. A
+ * deployment registers `{ id: '<ns>:<name>', component }` in the `appOverlays` slot and calls
+ * `ui.openOverlay(id, subject?)` (usually via the auto-imported `useAppOverlays()` composable);
+ * the single `<AppOverlayHost>` in `pages/index.vue` resolves the slot and mounts the matching
+ * component, handing it the optional `subject`. First-party modals stay hand-mounted in
+ * `index.vue` — this seam is deliberately scoped to consumer extensions (strangler discipline).
+ */
+function createConsumerOverlayHost() {
+  // The active consumer overlay: its slot id + an optional opaque subject the overlay renders
+  // against (e.g. a block id). Null when no consumer overlay is open. Only ONE at a time —
+  // opening another replaces it (a pick-one host, like the result-view seam).
+  const activeOverlay = ref<{ id: string; subject?: unknown } | null>(null)
+
+  function openOverlay(id: string, subject?: unknown) {
+    activeOverlay.value = { id, subject }
+  }
+  function closeOverlay() {
+    activeOverlay.value = null
+  }
+
+  return { activeOverlay, openOverlay, closeOverlay }
+}
+
 /**
  * The modal / panel slice of the UI store: every open-close flag for the dozens of modals,
  * panels and hubs (document + task import, bootstrap, integrations, workspace/account settings,
@@ -904,6 +931,7 @@ export function createUiModals() {
   const misc = createMiscModals()
   const documentsTasks = createDocumentTaskModals(resetHubReturn)
   const overlays = createOverlayModals()
+  const consumerOverlays = createConsumerOverlayHost()
   const panels = createIntegrationPanelModals(resetHubReturn)
   const settings = createSettingsModals(resetHubReturn)
   const infra = createInfraModals(resetHubReturn)
@@ -924,6 +952,7 @@ export function createUiModals() {
     ...misc,
     ...documentsTasks,
     ...overlays,
+    ...consumerOverlays,
     ...panels,
     ...settings,
     ...infra,

package/app/stores/ui/overlays.spec.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest'
+import { createUiModals } from '~/stores/ui/modals'
+
+/**
+ * The consumer-overlay host slice (extension slice D — the frontend-extension-mechanism
+ * initiative). It is composed into `createUiModals`, so these tests drive it there directly
+ * (plain refs/functions, no Pinia). The pointer is pick-one: opening a second overlay replaces
+ * the first, and closing clears it — this is what `<AppOverlayHost>` reads to mount exactly one
+ * consumer overlay.
+ */
+describe('ui overlay host (slice D)', () => {
+  it('starts with no active overlay', () => {
+    const ui = createUiModals()
+    expect(ui.activeOverlay.value).toBeNull()
+  })
+
+  it('openOverlay sets the active id + subject; closeOverlay clears it', () => {
+    const ui = createUiModals()
+    ui.openOverlay('acme:security-dashboard-overlay', { blockId: 'blk_1' })
+    expect(ui.activeOverlay.value).toEqual({
+      id: 'acme:security-dashboard-overlay',
+      subject: { blockId: 'blk_1' },
+    })
+    ui.closeOverlay()
+    expect(ui.activeOverlay.value).toBeNull()
+  })
+
+  it('openOverlay without a subject leaves subject undefined', () => {
+    const ui = createUiModals()
+    ui.openOverlay('acme:security-dashboard-overlay')
+    expect(ui.activeOverlay.value).toEqual({
+      id: 'acme:security-dashboard-overlay',
+      subject: undefined,
+    })
+  })
+
+  it('is pick-one — opening a second overlay replaces the first', () => {
+    const ui = createUiModals()
+    ui.openOverlay('acme:one')
+    ui.openOverlay('acme:two', 42)
+    expect(ui.activeOverlay.value).toEqual({ id: 'acme:two', subject: 42 })
+  })
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.152.1",
+  "version": "0.153.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",