@mohamedatia/fly-design-system 2.10.0 → 2.11.0

package/types/mohamedatia-fly-design-system.d.ts

@@ -1,7 +1,7 @@
 import * as _angular_core from '@angular/core';
-import { Type, InjectionToken, Signal, OnInit, EventEmitter, OnChanges, OnDestroy, SimpleChanges, PipeTransform, signal, AfterViewInit, ElementRef } from '@angular/core';
-import { ControlValueAccessor, Validator, AbstractControl, ValidationErrors } from '@angular/forms';
+import { Type, InjectionToken, Signal, WritableSignal, OnInit, EventEmitter, OnChanges, OnDestroy, SimpleChanges, PipeTransform, signal, AfterViewInit, ElementRef } from '@angular/core';
 import { Observable } from 'rxjs';
+import { ControlValueAccessor, Validator, AbstractControl, ValidationErrors } from '@angular/forms';
 import { NavigationExtras } from '@angular/router';
 import * as _mohamedatia_fly_design_system from '@mohamedatia/fly-design-system';
 
@@ -123,6 +123,61 @@ declare const FLYOS_LAUNCH_EVENT = "flyos:launch";
 declare const FlyosPendingLaunchesGlobalKey: "__FLYOS_PENDING_LAUNCHES__";
 /** Type of the `globalThis[FlyosPendingLaunchesGlobalKey]` registry. */
 type FlyosPendingLaunches = Record<string, LaunchContext>;
+/**
+ * Hint published by an app to drive the window-titlebar help-button deeplink.
+ *
+ * The shell renders the help button automatically on every non-chromeless
+ * window, defaulting the deeplink to `params.appId = win.appId`. An app
+ * customises that deeplink by injecting <see cref="WINDOW_HELP_HINT"/> and
+ * setting the writable signal — typically once on construct + again as the
+ * active route/page changes.
+ *
+ *  - `appId` overrides `win.appId` (rare; reserved for embedded sub-apps
+ *    whose help lives under a different seed-pack id).
+ *  - `topic` seeds the help-center search query when the deeplink fires.
+ *    Free-form short phrase (e.g. "calculated measures", "share dialog").
+ *    Updated dynamically as the user navigates within the app.
+ */
+interface WindowHelpHint {
+    /** Override for the help-center `appId` chip pre-selection. Optional. */
+    readonly appId?: string;
+    /** Free-form search-query seed for the help-center landing. */
+    readonly topic?: string | null;
+}
+/**
+ * Per-window injection token carrying the active <see cref="WindowHelpHint"/>
+ * as a writable signal. The shell creates one writable signal per window
+ * (alongside <see cref="LAUNCH_CONTEXT"/>); apps inject it and `.set(...)` to
+ * publish or update their hint. Setting `null` clears the hint — the chrome
+ * falls back to the implicit `win.appId` deeplink.
+ *
+ * **Federation note:** same caveat as <see cref="LAUNCH_CONTEXT"/> — Native
+ * Federation can split the InjectionToken across host/remote bundles, so
+ * federated remotes cannot rely on DI to publish hints. Use
+ * <see cref="FLY_WINDOW_HELP_HINT_EVENT"/> instead.
+ */
+declare const WINDOW_HELP_HINT: InjectionToken<WritableSignal<WindowHelpHint | null>>;
+/**
+ * Federation-safe window CustomEvent name for publishing a help hint from a
+ * federated remote that cannot see <see cref="WINDOW_HELP_HINT"/> via DI.
+ *
+ * Detail: <see cref="FlyWindowHelpHintEventDetail"/>. The shell listens at
+ * `window` scope and mirrors the payload into the matching per-window signal
+ * (keyed by `windowId` from <see cref="WINDOW_DATA"/>). Pairs with the
+ * <see cref="FLYOS_LAUNCH_EVENT"/> pattern.
+ */
+declare const FLY_WINDOW_HELP_HINT_EVENT = "flyos:window-help-hint";
+/**
+ * Detail payload of the <see cref="FLY_WINDOW_HELP_HINT_EVENT"/> CustomEvent.
+ * Federated remotes dispatch one event per hint change; the shell filters
+ * by `windowId` (each window owns its own hint).
+ */
+interface FlyWindowHelpHintEventDetail {
+    /** Window id; remotes obtain via WINDOW_DATA at mount. */
+    readonly windowId: string;
+    /** Pass `null` to clear; the chrome reverts to win.appId. */
+    readonly hint: WindowHelpHint | null;
+}
 
 interface User {
     id: string;
@@ -1224,6 +1279,59 @@ declare class SourceAppResolver {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<SourceAppResolver>;
 }
 
+/**
+ * Publishes a {@link WindowHelpHint} for the current window so the shell's
+ * titlebar Help button deeplinks the help-center reader to the article most
+ * relevant to where the user is.
+ *
+ * This is the **publisher twin** of the shell's `WindowHelpHintService`
+ * (the listener). It exists in the design system so that **any app — and
+ * especially a federated remote — publishes hints the same way**, without
+ * hand-rolling the cross-bundle CustomEvent contract.
+ *
+ * **Why a `window` CustomEvent and not the `WINDOW_HELP_HINT` DI token?**
+ * Native Federation can split an `InjectionToken` instance across the host and
+ * remote bundles, so a remote that injects `WINDOW_HELP_HINT` may get a
+ * different token than the one the shell provides. The string-keyed
+ * {@link FLY_WINDOW_HELP_HINT_EVENT} crosses bundles reliably; the shell
+ * mirrors it into the matching per-window hint signal. In-shell (OS-Core) apps
+ * may still use the DI token directly, but this service works for them too.
+ *
+ * **Imperative by design.** The service holds no signals and runs no effect —
+ * the *app* owns its reactivity (route + state → resolved hint) and pushes the
+ * result via {@link setHint}. The design system owns only the wire format. A
+ * hint set before {@link bindWindow} is buffered and emitted once the window id
+ * arrives, so call order doesn't matter.
+ *
+ * Usage (typically from the remote root + its feature components):
+ * ```ts
+ * private help = inject(FlyWindowHelpService);
+ * constructor() {
+ *   this.help.bindWindow(inject(WINDOW_DATA, { optional: true })?.id);
+ *   effect(() => this.help.setHint(this.resolvedHint())); // app-specific
+ * }
+ * ```
+ */
+declare class FlyWindowHelpService {
+    private windowId;
+    private hint;
+    /**
+     * Bind (or clear) the host window id — typically once, from the app root,
+     * with `WINDOW_DATA.id`. Re-emits the current hint for the (new) window.
+     * Passing null/undefined (standalone, no shell) makes publishing a no-op.
+     */
+    bindWindow(windowId: string | null | undefined): void;
+    /**
+     * Set the active hint (or null to clear — the shell then reverts to the
+     * window's own `appId`). Emits immediately when a window is bound; otherwise
+     * the value is buffered and emitted on the next {@link bindWindow}.
+     */
+    setHint(hint: WindowHelpHint | null): void;
+    private publish;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlyWindowHelpService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<FlyWindowHelpService>;
+}
+
 /**
  * fly-remote-styles — Shell-layer CSS loader for Native Federation remotes.
  *
@@ -1826,8 +1934,25 @@ declare class FlyFileUploadComponent {
  */
 /** Frozen MIME used by `flyAgentDraggable` and the drop-zone reader. Never change without a DS major. */
 declare const AGENT_DRAG_MIME: "application/x-fly-agent-payload+json";
-/** Frozen payload envelope version. Bump only with a published DS major. */
-declare const AGENT_PAYLOAD_VERSION: 1;
+/**
+ * Frozen payload envelope version.
+ *
+ *   v1 — minimal drag payload: kind / appId / version / payload / plainTextFallback /
+ *        suggestedCommandIds. Still used by the drag/drop surface.
+ *
+ *   v2 — bus envelope ({@link AgentMessageEnvelope}). Adds optional `userMessage`,
+ *        `systemContext`, `attachments`, `mcpScope` so a dispatcher can give the agent
+ *        rich context without polluting the user-visible message bubble. v2 is a
+ *        superset of v1 — every v1 payload is a valid v2 payload — so the version
+ *        number ratchets forward without breaking existing callers.
+ */
+declare const AGENT_PAYLOAD_VERSION: 2;
+/**
+ * Versions accepted by the validator. v1 payloads (the drag/drop surface) remain valid;
+ * v2 adds the optional bus-envelope fields. Renderers narrow on `version` when they need
+ * to.
+ */
+declare const SUPPORTED_AGENT_PAYLOAD_VERSIONS: readonly number[];
 /**
  * Where a command surfaces. `'global'` = always offered. `{ appId }` = offered only when
  * the host's live `liveAppIds` set (passed to {@link AgentCommandRegistry.visible}) contains
@@ -1874,22 +1999,263 @@ interface AgentCommandHandle {
     dispose(): void;
 }
 /**
- * The wire envelope written to a `DataTransfer` by `flyAgentDraggable`. Renderers narrow
- * on `kind`; mismatches fall back to `plainTextFallback`.
+ * How a lookup fetches candidate entities. The picker calls the app's existing
+ * authenticated REST search endpoint (the same one the agent's MCP `*_list_brief`
+ * tool wraps) through the shell's HttpClient — gateway routing + auth
+ * interceptor apply. We deliberately do NOT route typeahead through MCP (agent-
+ * shaped, agent-auth) or the dataset executor (aggregation-shaped, no fulltext).
+ *
+ * Field mapping is declarative because entities differ: Circles trends/signals
+ * expose `/brief` endpoints returning `{ id, title, status }`, while scenarios
+ * have no brief variant and return full objects with `titleEn` / `titleAr`. The
+ * `displayField` / `secondaryField` indirection absorbs that per-entity skew so
+ * one picker component serves them all.
+ */
+interface LookupSearch {
+    /**
+     * Relative REST path the picker GETs, e.g. `/api/circles/trends/brief`. Must
+     * be a relative path (no scheme/host) — the SSRF guard at onboard time (when
+     * the descriptor is manifest-backed) and the picker both reject absolute URLs.
+     */
+    readonly endpoint: string;
+    /** Query param carrying the typed text, e.g. `search`. */
+    readonly queryParam: string;
+    /** Static query params merged into every request, e.g. `{ pageSize: '10' }`. */
+    readonly extraParams?: Readonly<Record<string, string>>;
+    /** Response-item field holding the entity id. Default `id`. */
+    readonly idField?: string;
+    /** Response-item field holding the display label, e.g. `title` / `titleEn`. */
+    readonly displayField: string;
+    /** Optional response-item field for the chip's secondary line (status, category). */
+    readonly secondaryField?: string;
+    /**
+     * Dotted path to the results array within the response body when it is
+     * wrapped, e.g. `items` for `{ items: [...], total }`. Omit when the response
+     * body IS the array.
+     */
+    readonly resultsPath?: string;
+}
+/**
+ * A lookupable entity offered by the `/lookup` palette. Registered by the owning
+ * app (a federation remote self-registers at boot, mirroring {@link AgentCommand})
+ * or, once manifest-backed, projected from the app's `lookups[]` manifest section.
+ *
+ * The descriptor is a shallow, business-logic-free descriptor: it tells the
+ * picker WHAT to search, WHERE it is offered, and HOW to map the response — the
+ * picker owns the typeahead UX, the shell owns the HTTP call.
+ */
+interface LookupDescriptor {
+    /**
+     * Stable entity key, kebab/lower, e.g. `scenario`. Doubles as the `/lookup
+     * <entity>` sub-token and the group key the picked ref is grouped under when
+     * serialized for the agent.
+     */
+    readonly entity: string;
+    /** i18n key for the entity's display name in the picker / palette. */
+    readonly labelKey: string;
+    /** Optional PrimeIcons class for the picker row + chip. */
+    readonly icon?: string;
+    /**
+     * Route globs where this lookup is offered (matched against the shell's
+     * router url), e.g. `['/scenarios/*', '/trends/*']`. Omit / empty = offered
+     * everywhere the owning app is live.
+     */
+    readonly pages?: readonly string[];
+    /** How to fetch + map candidates. */
+    readonly search: LookupSearch;
+}
+/** What hosts pass to the lookup registry. Adds the scope to {@link LookupDescriptor}. */
+interface LookupRegistration extends LookupDescriptor {
+    /** Same scoping semantics as {@link AgentCommandScope}. */
+    readonly scope: AgentCommandScope;
+}
+/** One resolved row the picker returns once the user selects a candidate. */
+interface LookupResult {
+    /** The entity kind (echoes {@link LookupDescriptor.entity}). */
+    readonly entity: string;
+    /** Selected entity id. */
+    readonly id: string;
+    /** Selected entity's display label. */
+    readonly label: string;
+    /** Optional secondary detail (status / category). */
+    readonly secondary?: string;
+}
+/** Disposable handle returned by the lookup registry. Idempotent `dispose()`. */
+interface LookupHandle {
+    dispose(): void;
+}
+/**
+ * The wire envelope used by both the drag/drop surface and the imperative
+ * {@link AgentActionBus}. Renderers narrow on `kind`; mismatches fall back to
+ * `plainTextFallback`.
+ *
+ * The base fields (v1) describe **what** is being handed to the agent panel.
+ * The v2 fields describe **how the agent should treat it** — `userMessage`
+ * scopes the user-visible bubble, `systemContext` extends the system prompt,
+ * `attachments` decorate the message with typed chips, and `mcpScope` hints
+ * the agent toward a tool family. All v2 fields are optional so existing
+ * v1 (drag/drop) payloads remain valid envelopes.
+ *
+ * Caps (see {@link AgentPayloadLimits}):
+ *   - JSON total            32 KB
+ *   - plainTextFallback      8 KB
+ *   - per-string field       4 KB
+ *   - userMessage              280 chars
+ *   - systemContext       32 entries × 4 KB per value, 8 KB total serialized
+ *   - attachments          4 entries, kind-dependent inner caps
+ *   - mcpScope.apis        5 prefixes × 128 chars
+ *
+ * The cap math is split per-section so an oversize attachment fails fast at the
+ * attachment site instead of the whole envelope; field paths are dotted (see
+ * {@link AgentPayloadValidationResult}).
  */
 interface AgentDragPayload<T = unknown> {
     /** Domain-stable kind, e.g. `circles.trend`. */
     readonly kind: string;
     /** Originating appId. Must match an entry in the host's app registry. */
     readonly appId: string;
-    /** Frozen format version. Mismatch -> renderer falls back to text. */
-    readonly version: typeof AGENT_PAYLOAD_VERSION;
+    /** Frozen format version. Accepted: 1 or {@link AGENT_PAYLOAD_VERSION} (2). */
+    readonly version: number;
     /** Domain object. Renderers narrow on `kind`. */
     readonly payload: T;
     /** Plain-text fallback written to the dataTransfer alongside the typed MIME. */
     readonly plainTextFallback: string;
     /** Optional command ids to highlight when this payload is dropped. */
     readonly suggestedCommandIds?: readonly string[];
+    /**
+     * Short, locale-resolved string the dispatcher wants shown in the user's
+     * chat bubble. The agent panel uses it as the visible message text; when
+     * absent, the panel falls back to a generic per-verb default
+     * (e.g. "Tell me more about this"). Cap 280 chars — chip-sized, not essay.
+     *
+     * This is the ONLY field that should ever surface to the user verbatim.
+     * Everything else (systemContext, attachment bodies, mcpScope) is wire-only.
+     */
+    readonly userMessage?: string;
+    /**
+     * Flat key→string facts the dispatcher wants injected into the agent's
+     * system prompt for this turn. Keys are dot-namespaced (e.g.
+     * `chart.name`, `chart.type`, `chart.dimension`) to keep the model's
+     * mental schema flat and grep-friendly. Values are strings — booleans,
+     * numbers, and dates must be pre-serialized at the call site so the
+     * dispatcher owns the formatting (timezone, locale, number style).
+     *
+     * Cap: 32 entries, 4 KB per value, 8 KB total when serialized.
+     *
+     * NOT user-visible. The agent panel may transiently embed this as an
+     * `[Internal context]` block in the wire content while the backend
+     * learns to consume the dedicated field, but never renders it in the
+     * user bubble.
+     */
+    readonly systemContext?: Readonly<Record<string, string>>;
+    /**
+     * Typed attachments rendered as a chip strip under the user's outgoing
+     * message bubble. Each entry has a `kind` discriminator and a `label`
+     * (locale-resolved by the dispatcher). v2 ships `json` + `text`;
+     * `image` and `file` are reserved — their interfaces are stable so
+     * future callers don't need a contract bump, but the panel may render
+     * a generic chip for them until per-kind renderers land.
+     *
+     * Cap: 4 entries per envelope. Per-kind body caps:
+     *   - json: 16 KB serialized
+     *   - text: 8 KB UTF-8
+     *   - image / file: dataUrl ≤ 32 KB (small previews; large media stays in
+     *     the files-manager and is referenced by id)
+     */
+    readonly attachments?: readonly AgentEnvelopeAttachment[];
+    /**
+     * Advisory MCP scope. The agent service injects these prefixes into the
+     * system prompt as a tool-selection hint ("prefer tools matching
+     * `dashboard.reports.*` for this turn") — NOT a hard filter. The agent
+     * remains free to pick any tool; this just biases the first guess so a
+     * dashboard explain doesn't waste a tool-call probing Notes APIs first.
+     *
+     * Cap: 5 prefixes × 128 chars. Prefixes should match gateway-aggregated
+     * OpenAPI tag/path roots so they line up with the names the MCP server
+     * exposes — see `src/backend/gateway` Swagger aggregation + the dynamic
+     * loader in `src/backend/mcp-server`.
+     */
+    readonly mcpScope?: AgentMcpScope;
+    /**
+     * Optional deep-link route the originating app can use to re-open the
+     * source object. When set, payload chips (and any other renderer that
+     * surfaces the envelope to the user) become clickable — clicking calls
+     * `ShellLauncherService.launch({ appId, route: deepLinkRoute })` so the
+     * target app opens / focuses and navigates to the originating object.
+     *
+     * Shape constraints (mirror `DeepLinkService.isValidRoute`):
+     *   - starts with `/`
+     *   - ≤ {@link AgentPayloadLimits.maxDeepLinkRouteBytes} bytes (default
+     *     1024) — matches the route limit on the wider shell deep-link
+     *     contract so this field can be handed straight to the launcher.
+     *   - no `..` segments
+     *   - no `//` runs
+     *   - no scheme-like prefixes (`/javascript:`, `/data:`, `/http:`, `/https:`)
+     *
+     * The DS validator enforces only the byte cap — full route syntax
+     * validation is owned by the shell side (`DeepLinkService`) because the
+     * DS package is shell-agnostic and shouldn't grow a second copy of the
+     * URL grammar. Apps building envelopes are expected to stamp routes that
+     * match their own internal route schema (e.g. dashboard publishes
+     * `/reports/{id}` and `/custom/{id}`); see `skills/cross-app-deep-linking.md`.
+     *
+     * Backwards-compat: absent on v1 payloads and on v2 payloads built
+     * before this field was added. Persisted JSONB chips without the field
+     * remain non-clickable; new chips light up automatically.
+     */
+    readonly deepLinkRoute?: string;
+}
+/**
+ * Canonical name for the bus-side envelope. v2 callers should reference this
+ * over {@link AgentDragPayload} for clarity — the underlying shape is
+ * identical, but the name signals "this is going to the agent, not to a
+ * drop zone." The alias is intentional: one wire shape, two semantic uses.
+ */
+type AgentMessageEnvelope<T = unknown> = AgentDragPayload<T>;
+/**
+ * Typed attachment discriminator for {@link AgentDragPayload.attachments}.
+ *
+ *   - `json` — structured data the panel renders as a "code-ish" chip the
+ *     user can expand. Used for chart snapshots, query results, etc.
+ *   - `text` — short utterance / excerpt with optional MIME. Used when the
+ *     dispatcher wants the chip to preview a note paragraph, log line,
+ *     code snippet, etc.
+ *   - `image` / `file` — reserved. Stable interface; renderers added per
+ *     downstream caller (the panel may fall back to a generic icon-chip).
+ *
+ * Every kind carries `label` — that's what shows on the chip face and what
+ * a11y trees announce.
+ */
+type AgentEnvelopeAttachment = {
+    readonly kind: 'json';
+    readonly label: string;
+    readonly json: unknown;
+} | {
+    readonly kind: 'text';
+    readonly label: string;
+    readonly text: string;
+    readonly mimeType?: string;
+} | {
+    readonly kind: 'image';
+    readonly label: string;
+    /** `data:` URL — small previews only. Large media stays in files-manager. */
+    readonly dataUrl: string;
+    readonly mimeType: string;
+} | {
+    readonly kind: 'file';
+    readonly label: string;
+    readonly dataUrl: string;
+    readonly mimeType: string;
+    readonly bytes: number;
+};
+/** Advisory tool-selection hint for {@link AgentDragPayload.mcpScope}. */
+interface AgentMcpScope {
+    /**
+     * Prefixes of gateway-aggregated OpenAPI tags / path roots — e.g.
+     * `dashboard.reports`, `notes.documents`. The agent service treats these
+     * as a soft preference, not a hard filter.
+     */
+    readonly apis: readonly string[];
 }
 /**
  * Where a chip is being rendered. `inline` = inside the input chip tray (removable);
@@ -1937,6 +2303,32 @@ interface AgentPayloadLimits {
     readonly maxPlainTextFallbackBytes: number;
     /** Cap on any single string field inside payload (recursive). Default 4 KB. */
     readonly maxStringFieldBytes: number;
+    /** Cap on `userMessage` UTF-8 byte length. Default 280 chars (~1.1 KB). */
+    readonly maxUserMessageBytes: number;
+    /** Max entries in `systemContext`. Default 32. */
+    readonly maxSystemContextEntries: number;
+    /** Cap on any single systemContext value's UTF-8 byte length. Default 4 KB. */
+    readonly maxSystemContextValueBytes: number;
+    /** Cap on the full JSON.stringify(systemContext). Default 8 KB. */
+    readonly maxSystemContextJsonBytes: number;
+    /** Max attachments per envelope. Default 4. */
+    readonly maxAttachments: number;
+    /** Cap on a `json` attachment's serialized body. Default 16 KB. */
+    readonly maxAttachmentJsonBytes: number;
+    /** Cap on a `text` attachment's body bytes. Default 8 KB. */
+    readonly maxAttachmentTextBytes: number;
+    /** Cap on an `image` / `file` attachment's dataUrl bytes. Default 32 KB. */
+    readonly maxAttachmentDataUrlBytes: number;
+    /** Max prefixes in `mcpScope.apis`. Default 5. */
+    readonly maxMcpScopeApis: number;
+    /** Cap on any single mcpScope prefix string. Default 128 chars. */
+    readonly maxMcpScopeApiBytes: number;
+    /**
+     * Cap on `deepLinkRoute` UTF-8 byte length. Default 1024 bytes — matches
+     * the route limit on `DeepLinkService.isValidRoute` so this field can be
+     * handed straight to the shell launcher without a second resize.
+     */
+    readonly maxDeepLinkRouteBytes: number;
 }
 declare const DEFAULT_AGENT_PAYLOAD_LIMITS: AgentPayloadLimits;
 /**
@@ -1951,7 +2343,7 @@ type AgentPayloadValidationResult = {
     readonly ok: true;
 } | {
     readonly ok: false;
-    readonly reason: 'json_too_large' | 'fallback_too_large' | 'field_too_large' | 'invalid_version' | 'invalid_kind';
+    readonly reason: 'json_too_large' | 'fallback_too_large' | 'field_too_large' | 'invalid_version' | 'invalid_kind' | 'user_message_too_large' | 'system_context_too_many_entries' | 'system_context_value_too_large' | 'system_context_json_too_large' | 'too_many_attachments' | 'attachment_invalid_kind' | 'attachment_json_too_large' | 'attachment_text_too_large' | 'attachment_data_url_too_large' | 'mcp_scope_too_many_apis' | 'mcp_scope_api_too_large' | 'deep_link_route_too_large' | 'deep_link_route_invalid_shape';
     /** Dotted property-access path to the offending field, e.g. `payload.title` or `payload.tags[2]`. NOT RFC 6901 JSON Pointer. */
     readonly fieldPath?: string;
     readonly actualBytes?: number;
@@ -2007,6 +2399,53 @@ declare class AgentCommandRegistry {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<AgentCommandRegistry>;
 }
 
+/**
+ * Singleton registry of entity lookups offered by the `/lookup` typeahead.
+ *
+ * Mirrors {@link AgentCommandRegistry} exactly — same federation-singleton story
+ * (`sharedMappings: ['@mohamedatia/fly-design-system']`), same id-collision
+ * "latest wins" contract, same disposable-handle ergonomics. Federated remotes
+ * register their lookupable entities at boot (Circles: scenario / trend / signal)
+ * and dispose on window close, so the picker only ever offers entities whose app
+ * is currently live.
+ *
+ * Storage is a signal store keyed on {@link LookupRegistration.entity}. Because
+ * `entity` is the collision key, an app re-registering the same entity replaces
+ * the prior descriptor; a stale handle's `dispose()` then no-ops.
+ */
+declare class AgentLookupRegistry {
+    private readonly _lookups;
+    /** All currently-registered lookups, in insertion order. */
+    readonly all: Signal<readonly LookupRegistration[]>;
+    /**
+     * Lookups whose scope is `'global'` OR whose `scope.appId` is in the live app
+     * set. Recomputes when either the registry or `liveAppIds` changes — pass a
+     * `Signal<ReadonlySet<string>>` from the host's app-registry for reactive
+     * filtering, exactly like {@link AgentCommandRegistry.visible}.
+     */
+    visible(liveAppIds: ReadonlySet<string> | Signal<ReadonlySet<string>>): Signal<readonly LookupRegistration[]>;
+    /**
+     * Register one lookup. Returns a handle whose `dispose()` removes the row by
+     * `entity`. A later re-registration of the same entity makes the original
+     * handle's `dispose()` a no-op (the newer registration owns the row).
+     */
+    register(lookup: LookupRegistration): LookupHandle;
+    /**
+     * Bulk register. Rolls back on a duplicate entity WITHIN the input batch
+     * (throws before any row lands). Cross-batch duplicates against existing rows
+     * follow the standard "latest wins" rule and do NOT trigger rollback.
+     */
+    registerAll(lookups: readonly LookupRegistration[]): LookupHandle;
+    /** Tear down by entity. Idempotent. */
+    unregister(entity: string): void;
+    /** Monotonic counter; identifies which registration call currently owns each entity. */
+    private _generation;
+    /** entity → generation. Lets a stale handle's `dispose()` no-op after replacement. */
+    private readonly _owners;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AgentLookupRegistry, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<AgentLookupRegistry>;
+}
+
 /**
  * Singleton registry of chip-renderer components and keyboard-alternative draggable
  * items, keyed by `kind` and `appId`.
@@ -2063,6 +2502,202 @@ declare class AgentDropRegistry {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<AgentDropRegistry>;
 }
 
+/**
+ * Imperative action published by an app, consumed by the agent panel.
+ *
+ * Re-uses {@link AgentDragPayload} as the wire envelope so a dragged item
+ * and a programmatic "Explain" click are byte-for-byte the same shape —
+ * renderers, validators, and serialisation paths never fork on transport.
+ *
+ * Adding a verb is a minor DS bump (consumers ignore unknown verbs in
+ * their `switch`). Removing one is a major DS bump.
+ */
+type AgentActionVerb = 'explain' | 'why-empty' | 'compose-query' | 'compare' | 'forecast' | 'summarize';
+/**
+ * Whether the agent panel sends the staged payload immediately or stages
+ * the chip for the user to edit and send manually.
+ *
+ * Phase 1 (DS v2.6.0) supports `'stage'` only. Dispatching with `'auto'`
+ * throws {@link AgentActionUnsupportedDispatchError} so callers don't
+ * silently fail. `'auto'` lands once `AgentInputComponent.programmaticSubmit`
+ * is exposed and reviewed against the input's state machine.
+ */
+type AgentActionDispatch = 'auto' | 'stage';
+interface AgentAction<T = unknown> {
+    /** Intent the agent should apply to {@link payload}. */
+    readonly verb: AgentActionVerb;
+    /** The wire envelope. Validated against {@link validateAgentPayload}'s
+     *  size caps before the bus fans it out. */
+    readonly payload: AgentDragPayload<T>;
+    /** Optional slash command id to bind before send (e.g. `'explain-report'`).
+     *  Phase 1 captures this for telemetry only — actual binding lands when
+     *  the input's programmatic-send API ships. An unknown id is dropped
+     *  silently with a console warning, the chip still arrives. */
+    readonly autoCommandId?: string;
+    /** Phase 1 supports `'stage'` only. See {@link AgentActionDispatch}. */
+    readonly dispatch: AgentActionDispatch;
+    /** Source DOM rect for the FLIP entry animation. Omit to skip the
+     *  animation (e.g. dispatching from a keyboard shortcut with no anchor). */
+    readonly originRect?: DOMRect;
+    /** Optional HTML snippet rendered inside the flight ghost. Callers are
+     *  responsible for escaping untrusted text — the bus does not sanitise.
+     *  Defaults (when omitted) to a strong-wrapped escape of the payload's
+     *  `plainTextFallback` rendered by the panel host. */
+    readonly originPreviewHtml?: string;
+}
+/**
+ * Thrown synchronously by {@link AgentActionBus.dispatch} when a caller
+ * supplies a dispatch mode this DS version doesn't implement yet. Catching
+ * by class name lets a forward-compatible caller fall back to `'stage'`
+ * without depending on instanceof across federation boundaries.
+ */
+declare class AgentActionUnsupportedDispatchError extends Error {
+    readonly dispatch: AgentActionDispatch;
+    constructor(dispatch: AgentActionDispatch);
+}
+
+/**
+ * Imperative sibling to {@link AgentCommandRegistry} / {@link AgentDropRegistry}.
+ *
+ * Apps call {@link dispatch} to push a typed {@link AgentAction} onto the bus;
+ * the agent panel subscribes once at construct and routes by verb. The bus
+ * itself is a thin pass-through — it does NOT decide UI behaviour. The
+ * subscriber (agent-panel) owns: showing the panel, staging the chip,
+ * triggering the flight animation, and binding the command. This keeps the
+ * DS free of host policy.
+ *
+ * Federation-safe: `providedIn: 'root'` + `sharedMappings: ['@mohamedatia/fly-design-system']`
+ * give every federated remote the same singleton, so a remote's "Explain"
+ * button reaches the host's panel without any cross-bundle wiring.
+ *
+ * Validation runs synchronously inside `dispatch` so a caller that sends an
+ * oversize payload sees the throw at their site, not on the subscriber. The
+ * subscriber therefore never has to defend against malformed envelopes.
+ */
+declare class AgentActionBus {
+    private readonly _actions$;
+    /** Hot stream of actions in dispatch order. Subscribers receive only
+     *  actions dispatched AFTER they subscribe — late subscribers see nothing
+     *  retroactively. Use {@link lastAction} for the latest snapshot. */
+    readonly actions$: Observable<AgentAction>;
+    /** Most recent action — for DevTools, smoke tests, and late-subscriber
+     *  catch-up. Null until the first successful dispatch. */
+    readonly lastAction: _angular_core.WritableSignal<AgentAction<unknown> | null>;
+    /**
+     * The action currently being processed by the subscriber, or null when
+     * none. Set by {@link dispatch} immediately before emitting on
+     * {@link actions$}; cleared by the subscriber via {@link settle} once
+     * it finishes its handler (success or fail). Lets the dispatcher render
+     * a busy state on the originating control — e.g. a card swapping its
+     * sparkle icon for a spinner while the agent panel mints the optimistic
+     * thread and starts the request. Identity check (`bus.inFlight() === act`)
+     * is the panel-side contract; dispatchers usually project to a stable id
+     * inside the payload (e.g. <c>reportId</c>) to scope busy-state visually.
+     *
+     * If multiple dispatches race, the latest wins — the prior in-flight
+     * action is dropped on the floor here (the panel may still handle it,
+     * but the dispatcher's busy indicator follows the newer action). Apps
+     * that need stricter single-flight semantics should guard at the call
+     * site (the agent-panel's <c>_pendingTempThreadId</c> already does so
+     * for the explain verb).
+     */
+    readonly inFlight: _angular_core.WritableSignal<AgentAction<unknown> | null>;
+    /**
+     * Push an action onto the bus.
+     *
+     * Throws synchronously when:
+     *   - `dispatch === 'auto'` (not implemented in this DS version) — see
+     *     {@link AgentActionUnsupportedDispatchError}.
+     *   - the payload fails {@link validateAgentPayload} (oversize, invalid
+     *     version, invalid kind). The error message carries the field path
+     *     so the caller can fix the offending field.
+     *
+     * Subscribers see the action via {@link actions$} on the next tick of
+     * the Subject; the {@link lastAction} signal updates synchronously
+     * before the Subject emits so an effect reading both stays consistent.
+     */
+    dispatch<T>(action: AgentAction<T>): void;
+    /**
+     * Subscriber contract: call after the handler for {@link inFlight}
+     * completes (success or fail). Only clears {@link inFlight} if it still
+     * points at the passed action — a no-op when a later dispatch already
+     * superseded it. Pass the same action reference the subscriber received
+     * from {@link actions$}; identity is the gate.
+     */
+    settle(action: AgentAction): void;
+    /**
+     * Semantic alias of {@link settle} for explicit user-driven cancellation —
+     * e.g. a future "Stop" button in the agent input tray, or a dispatcher
+     * teardown that wants to abandon its own in-flight action. Identical
+     * runtime behaviour (identity check + clear), but the two-method surface
+     * lets the UI distinguish "handler finished" from "user said no" in
+     * telemetry / logs without sniffing a "reason" parameter.
+     *
+     * Pass the same action reference returned from {@link inFlight} or held
+     * by the dispatcher; identity is the gate.
+     */
+    cancel(action: AgentAction): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AgentActionBus, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<AgentActionBus>;
+}
+
+/**
+ * FLIP-style entry animation for payloads landing in the agent panel.
+ *
+ * Pure DOM + Web Animations API — no Chart.js, no Angular animations module,
+ * no CSS transitions racing layout. Honours `prefers-reduced-motion`: the
+ * ghost is appended then removed without animating when the user asked for
+ * less motion (so DOM side-effects stay consistent).
+ *
+ * Lifecycle:
+ *   1. The agent panel calls {@link registerTarget} in `ngAfterViewInit`
+ *      with its header element.
+ *   2. A source app dispatches an `AgentAction` carrying an `originRect`
+ *      from `getBoundingClientRect()` on the click target.
+ *   3. The bus subscriber calls {@link flyInto} with that rect.
+ *   4. The animator creates a fixed-position ghost at the origin, animates
+ *      transform + opacity toward the registered target's rect, then
+ *      removes itself on `onfinish` / `oncancel`.
+ *
+ * Uses `getBoundingClientRect()` (physical viewport coords) so the animation
+ * is RTL-correct without inset-inline math — the rect already encodes the
+ * physical position regardless of `dir`.
+ *
+ * The 900 ms duration and easing curve are deliberately hardcoded — making
+ * them configurable surfaces an API the host can't usefully tune without
+ * understanding motion design as a whole.
+ */
+declare class AgentFlightAnimator {
+    /** Hardcoded — see class doc. */
+    private static readonly DURATION_MS;
+    private static readonly EASING;
+    /** Floor the target/source scale ratio so a tiny target rect doesn't
+     *  collapse the ghost to invisibility before the animation finishes. */
+    private static readonly MIN_SCALE;
+    private targetEl;
+    /** Called by the panel host to publish where flights should land. Pass
+     *  `null` on destroy so a re-mounted panel doesn't leave the animator
+     *  pointing at a detached node. */
+    registerTarget(el: HTMLElement | null): void;
+    /**
+     * Animate a ghost element from {@link from} to the registered target's
+     * rect. No-ops when:
+     *   - no target is registered (silent — panel may not be mounted yet)
+     *   - running outside a browser (SSR safety)
+     *   - the user has `prefers-reduced-motion: reduce` set (DOM is still
+     *     touched so callers see consistent side-effects, but no animation
+     *     runs)
+     *
+     * The ghost is appended to `document.body` (not the panel) so a parent
+     * `overflow: hidden` on the panel can't clip the flight path.
+     */
+    flyInto(from: DOMRect, opts?: {
+        previewHtml?: string;
+    }): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AgentFlightAnimator, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<AgentFlightAnimator>;
+}
+
 /**
  * Single canonical way to declare a drag source for the agent input.
  *
@@ -2231,11 +2866,14 @@ declare function trimAgentString(input: string, maxBytes: number, ellipsis?: str
  * structured failure with the offending field path and byte counts.
  *
  * Order of checks (cheap → expensive):
- *   1. `version` matches the frozen {@link AGENT_PAYLOAD_VERSION}.
+ *   1. `version` is in {@link SUPPORTED_AGENT_PAYLOAD_VERSIONS}.
  *   2. `kind` is a non-empty string.
  *   3. `plainTextFallback` fits its cap.
  *   4. Every string in `payload` (recursively) fits the per-field cap.
- *   5. The full `JSON.stringify(envelope)` fits the JSON cap.
+ *   5. v2 sections — `userMessage`, `systemContext`, `attachments`, `mcpScope` —
+ *      each fits their independent caps. Skipped when absent so v1 payloads pass
+ *      unchanged.
+ *   6. The full `JSON.stringify(envelope)` fits the JSON cap.
  *
  * The walker stops on the first oversize string field — the intent is to surface
  * actionable feedback, not enumerate every offender.
@@ -2344,6 +2982,6 @@ declare const AUDIENCE_ERROR_CODES: {
 };
 type AudienceErrorCode = (typeof AUDIENCE_ERROR_CODES)[keyof typeof AUDIENCE_ERROR_CODES];
 
-export { AGENT_DRAG_MIME, AGENT_PAYLOAD_VERSION, APP_LOOKUP, AUDIENCE_ERROR_CODES, AUDIENCE_LIMITS, AUDIENCE_PRESETS, AUDIENCE_TERM_KINDS, AgentCommandRegistry, AgentDropRegistry, AgentPayloadOversizeError, AudienceBuilderComponent, AuthService, ContextMenuComponent, DEFAULT_AGENT_PAYLOAD_LIMITS, DEFAULT_FLY_THEME_MODE, DialogResult, FLYOS_LAUNCH_EVENT, FLY_LOCALE_CATALOG, FLY_REMOTE_BASE_PATH, FLY_REMOTE_ROUTES, FLY_THEME_MODE_IDS, FlyAgentDraggableDirective, FlyBlockUiComponent, FlyFileUploadComponent, FlyImageUploadComponent, FlyRemoteRouter, FlyRemoteRouterOutletComponent, FlySecureSrcDirective, FlyThemeService, FlyosPendingLaunchesGlobalKey, I18nService, LAUNCH_CONTEXT, MessageBoxButtons, MessageBoxComponent, MessageBoxIcon, MessageBoxService, MockAuthService, RTL_LOCALE_SET, SHARE_ORG_CHART_SYSTEM_KEY_APPS, SHARE_ORG_CHART_SYSTEM_KEY_DEFAULT, SHARE_PANEL_DEFAULT_FILE_LEVELS, SharePanelComponent, SourceAppResolver, StandaloneWindowManagerService, TranslatePipe, WINDOW_DATA, WindowManagerService, findLocaleByDialect, findLocaleByPrefix, isRtlLocale, isRtlLocaleEntry, loadRemoteStyles, matchFlyRoutePattern, normalizeFlyTheme, trimAgentPayload, trimAgentString, unloadRemoteStyles, utf8ByteLength, validateAgentPayload };
-export type { AgentChipHostInputs, AgentCommand, AgentCommandHandle, AgentCommandRegistration, AgentCommandScope, AgentDragPayload, AgentDraggableItem, AgentDropChipMode, AgentDropRendererRegistration, AgentPayloadLimits, AgentPayloadValidationResult, AppEveryonePrincipal, AppEveryoneTerm, AppLookup, AppLookupEntry, AudienceEditTarget, AudienceErrorCode, AudienceFilter, AudienceOptions, AudiencePresetKind, AudienceTerm, AudienceTermKind, ChartTerm, ChildWindowData, ContextMenuItem, ContextMenuSection, DesktopApp, DesktopAppKind, DialogResultWithAcknowledgement, FlyFileInfo, FlyLaunchEventDetail, FlyLocaleEntry, FlyRemoteMatch, FlyRemoteRoute, FlyThemeMode, FlyosPendingLaunches, LaunchContext, LoadBundleOptions, MessageBoxButton, MessageBoxDontAskAgainConfig, MessageBoxOptions, MessageBoxOptionsWithAcknowledgement, MockAuthConfig, OpenWindowOptions, OuPrincipal, OuTerm, PresetTerm, RemoteAppDef, RoleOuLookupRow, RolePrincipal, RolesTerm, ShareOrgChartOption, ShareOuNode, SharePanelLevelOption, SharePermissionEntry, SharePrincipal, SharePrincipalKind, ShareUserResult, User, UserPrincipal, UsersTerm, WindowInstance, WindowState };
+export { AGENT_DRAG_MIME, AGENT_PAYLOAD_VERSION, APP_LOOKUP, AUDIENCE_ERROR_CODES, AUDIENCE_LIMITS, AUDIENCE_PRESETS, AUDIENCE_TERM_KINDS, AgentActionBus, AgentActionUnsupportedDispatchError, AgentCommandRegistry, AgentDropRegistry, AgentFlightAnimator, AgentLookupRegistry, AgentPayloadOversizeError, AudienceBuilderComponent, AuthService, ContextMenuComponent, DEFAULT_AGENT_PAYLOAD_LIMITS, DEFAULT_FLY_THEME_MODE, DialogResult, FLYOS_LAUNCH_EVENT, FLY_LOCALE_CATALOG, FLY_REMOTE_BASE_PATH, FLY_REMOTE_ROUTES, FLY_THEME_MODE_IDS, FLY_WINDOW_HELP_HINT_EVENT, FlyAgentDraggableDirective, FlyBlockUiComponent, FlyFileUploadComponent, FlyImageUploadComponent, FlyRemoteRouter, FlyRemoteRouterOutletComponent, FlySecureSrcDirective, FlyThemeService, FlyWindowHelpService, FlyosPendingLaunchesGlobalKey, I18nService, LAUNCH_CONTEXT, MessageBoxButtons, MessageBoxComponent, MessageBoxIcon, MessageBoxService, MockAuthService, RTL_LOCALE_SET, SHARE_ORG_CHART_SYSTEM_KEY_APPS, SHARE_ORG_CHART_SYSTEM_KEY_DEFAULT, SHARE_PANEL_DEFAULT_FILE_LEVELS, SUPPORTED_AGENT_PAYLOAD_VERSIONS, SharePanelComponent, SourceAppResolver, StandaloneWindowManagerService, TranslatePipe, WINDOW_DATA, WINDOW_HELP_HINT, WindowManagerService, findLocaleByDialect, findLocaleByPrefix, isRtlLocale, isRtlLocaleEntry, loadRemoteStyles, matchFlyRoutePattern, normalizeFlyTheme, trimAgentPayload, trimAgentString, unloadRemoteStyles, utf8ByteLength, validateAgentPayload };
+export type { AgentAction, AgentActionDispatch, AgentActionVerb, AgentChipHostInputs, AgentCommand, AgentCommandHandle, AgentCommandRegistration, AgentCommandScope, AgentDragPayload, AgentDraggableItem, AgentDropChipMode, AgentDropRendererRegistration, AgentEnvelopeAttachment, AgentMcpScope, AgentMessageEnvelope, AgentPayloadLimits, AgentPayloadValidationResult, AppEveryonePrincipal, AppEveryoneTerm, AppLookup, AppLookupEntry, AudienceEditTarget, AudienceErrorCode, AudienceFilter, AudienceOptions, AudiencePresetKind, AudienceTerm, AudienceTermKind, ChartTerm, ChildWindowData, ContextMenuItem, ContextMenuSection, DesktopApp, DesktopAppKind, DialogResultWithAcknowledgement, FlyFileInfo, FlyLaunchEventDetail, FlyLocaleEntry, FlyRemoteMatch, FlyRemoteRoute, FlyThemeMode, FlyWindowHelpHintEventDetail, FlyosPendingLaunches, LaunchContext, LoadBundleOptions, LookupDescriptor, LookupHandle, LookupRegistration, LookupResult, LookupSearch, MessageBoxButton, MessageBoxDontAskAgainConfig, MessageBoxOptions, MessageBoxOptionsWithAcknowledgement, MockAuthConfig, OpenWindowOptions, OuPrincipal, OuTerm, PresetTerm, RemoteAppDef, RoleOuLookupRow, RolePrincipal, RolesTerm, ShareOrgChartOption, ShareOuNode, SharePanelLevelOption, SharePermissionEntry, SharePrincipal, SharePrincipalKind, ShareUserResult, User, UserPrincipal, UsersTerm, WindowHelpHint, WindowInstance, WindowState };
 //# sourceMappingURL=mohamedatia-fly-design-system.d.ts.map