@mohamedatia/fly-design-system 2.9.0 → 2.11.0

package/fesm2022/mohamedatia-fly-design-system.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, signal, computed, Injectable, inject, ErrorHandler, PLATFORM_ID, DestroyRef, ChangeDetectionStrategy, Component, Pipe, DOCUMENT, ElementRef, input, output, HostListener, ViewChild, EventEmitter, Output, Input, forwardRef, Injector, viewChild, effect, afterNextRender, ViewEncapsulation, model, Directive } from '@angular/core';
+import { InjectionToken, signal, computed, Injectable, inject, ErrorHandler, PLATFORM_ID, DestroyRef, ChangeDetectionStrategy, Component, Pipe, DOCUMENT, ElementRef, input, output, HostListener, ViewChild, EventEmitter, Output, Input, forwardRef, Injector, viewChild, effect, afterNextRender, ViewEncapsulation, model, Directive, Renderer2 } from '@angular/core';
 import * as i1$1 from '@angular/common';
 import { isPlatformBrowser, NgComponentOutlet, CommonModule, DOCUMENT as DOCUMENT$1 } from '@angular/common';
 import { Router, NavigationEnd } from '@angular/router';
@@ -41,6 +41,29 @@ const FLYOS_LAUNCH_EVENT = 'flyos:launch';
  * Subsequent re-launches into the already-mounted remote arrive via the event.
  */
 const FlyosPendingLaunchesGlobalKey = '__FLYOS_PENDING_LAUNCHES__';
+/**
+ * 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.
+ */
+const WINDOW_HELP_HINT = new InjectionToken('WINDOW_HELP_HINT');
+/**
+ * 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.
+ */
+const FLY_WINDOW_HELP_HINT_EVENT = 'flyos:window-help-hint';
 
 /**
  * Generic share / ACL panel models — hosts map domain DTOs to these shapes.
@@ -799,6 +822,74 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImpor
             args: [{ providedIn: 'root' }]
         }] });
 
+/**
+ * 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
+ * }
+ * ```
+ */
+class FlyWindowHelpService {
+    windowId = null;
+    hint = null;
+    /**
+     * 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) {
+        this.windowId = windowId ?? null;
+        this.publish();
+    }
+    /**
+     * 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) {
+        this.hint = hint;
+        this.publish();
+    }
+    publish() {
+        if (typeof window === 'undefined' || !this.windowId)
+            return;
+        const detail = { windowId: this.windowId, hint: this.hint };
+        window.dispatchEvent(new CustomEvent(FLY_WINDOW_HELP_HINT_EVENT, { detail }));
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: FlyWindowHelpService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: FlyWindowHelpService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: FlyWindowHelpService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
 /**
  * fly-remote-styles — Shell-layer CSS loader for Native Federation remotes.
  *
@@ -3359,7 +3450,7 @@ class AgentCommandRegistry {
      * for reactive filtering.
      */
     visible(liveAppIds) {
-        const liveSignal = isSignal(liveAppIds) ? liveAppIds : signal(liveAppIds).asReadonly();
+        const liveSignal = isSignal$1(liveAppIds) ? liveAppIds : signal(liveAppIds).asReadonly();
         return computed(() => {
             const live = liveSignal();
             return this._commands().filter((cmd) => {
@@ -3432,6 +3523,111 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImpor
             args: [{ providedIn: 'root' }]
         }] });
 /** `isSignal` shim — narrows to either `Signal<T>` or a plain value. */
+function isSignal$1(v) {
+    return typeof v === 'function';
+}
+
+/**
+ * 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.
+ */
+class AgentLookupRegistry {
+    _lookups = signal([], ...(ngDevMode ? [{ debugName: "_lookups" }] : /* istanbul ignore next */ []));
+    /** All currently-registered lookups, in insertion order. */
+    all = this._lookups.asReadonly();
+    /**
+     * 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) {
+        const liveSignal = isSignal(liveAppIds)
+            ? liveAppIds
+            : signal(liveAppIds).asReadonly();
+        return computed(() => {
+            const live = liveSignal();
+            return this._lookups().filter((l) => {
+                if (l.scope === 'global')
+                    return true;
+                return live.has(l.scope.appId);
+            });
+        });
+    }
+    /**
+     * 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) {
+        const generation = ++this._generation;
+        this._lookups.update((rows) => [
+            ...rows.filter((r) => r.entity !== lookup.entity),
+            lookup,
+        ]);
+        this._owners.set(lookup.entity, generation);
+        return {
+            dispose: () => {
+                if (this._owners.get(lookup.entity) === generation) {
+                    this._owners.delete(lookup.entity);
+                    this._lookups.update((rows) => rows.filter((r) => r.entity !== lookup.entity));
+                }
+            },
+        };
+    }
+    /**
+     * 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) {
+        const seen = new Set();
+        for (const l of lookups) {
+            if (seen.has(l.entity)) {
+                throw new Error(`AgentLookupRegistry.registerAll: duplicate entity "${l.entity}" in batch`);
+            }
+            seen.add(l.entity);
+        }
+        const handles = lookups.map((l) => this.register(l));
+        let disposed = false;
+        return {
+            dispose: () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                for (const h of handles)
+                    h.dispose();
+            },
+        };
+    }
+    /** Tear down by entity. Idempotent. */
+    unregister(entity) {
+        if (this._owners.delete(entity)) {
+            this._lookups.update((rows) => rows.filter((r) => r.entity !== entity));
+        }
+    }
+    /** Monotonic counter; identifies which registration call currently owns each entity. */
+    _generation = 0;
+    /** entity → generation. Lets a stale handle's `dispose()` no-op after replacement. */
+    _owners = new Map();
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: AgentLookupRegistry, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: AgentLookupRegistry, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: AgentLookupRegistry, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+/** `isSignal` shim — narrows to either `Signal<T>` or a plain value. */
 function isSignal(v) {
     return typeof v === 'function';
 }
@@ -3539,6 +3735,21 @@ function compositeKey(kind, appId) {
     return `${kind}::${appId}`;
 }
 
+/**
+ * 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.
+ */
+class AgentActionUnsupportedDispatchError extends Error {
+    dispatch;
+    constructor(dispatch) {
+        super(`AgentActionBus: dispatch="${dispatch}" not supported in this DS version`);
+        this.dispatch = dispatch;
+        this.name = 'AgentActionUnsupportedDispatchError';
+    }
+}
+
 /**
  * Agent input contracts.
  *
@@ -3558,12 +3769,40 @@ function compositeKey(kind, appId) {
  */
 /** Frozen MIME used by `flyAgentDraggable` and the drop-zone reader. Never change without a DS major. */
 const AGENT_DRAG_MIME = 'application/x-fly-agent-payload+json';
-/** Frozen payload envelope version. Bump only with a published DS major. */
-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.
+ */
+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.
+ */
+const SUPPORTED_AGENT_PAYLOAD_VERSIONS = Object.freeze([1, 2]);
 const DEFAULT_AGENT_PAYLOAD_LIMITS = Object.freeze({
     maxJsonBytes: 32 * 1024,
     maxPlainTextFallbackBytes: 8 * 1024,
     maxStringFieldBytes: 4 * 1024,
+    maxUserMessageBytes: 280 * 4, // 280 chars × 4 bytes/char worst-case UTF-8
+    maxSystemContextEntries: 32,
+    maxSystemContextValueBytes: 4 * 1024,
+    maxSystemContextJsonBytes: 8 * 1024,
+    maxAttachments: 4,
+    maxAttachmentJsonBytes: 16 * 1024,
+    maxAttachmentTextBytes: 8 * 1024,
+    maxAttachmentDataUrlBytes: 32 * 1024,
+    maxMcpScopeApis: 5,
+    maxMcpScopeApiBytes: 128,
+    maxDeepLinkRouteBytes: 1024,
 });
 
 /**
@@ -3669,18 +3908,21 @@ function trimAgentString(input, maxBytes, ellipsis = '…') {
  * 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.
  */
 function validateAgentPayload(payload, limits) {
     const eff = { ...DEFAULT_AGENT_PAYLOAD_LIMITS, ...(limits ?? {}) };
-    if (payload.version !== AGENT_PAYLOAD_VERSION) {
+    if (!SUPPORTED_AGENT_PAYLOAD_VERSIONS.includes(payload.version)) {
         return { ok: false, reason: 'invalid_version' };
     }
     if (typeof payload.kind !== 'string' || payload.kind.length === 0) {
@@ -3699,6 +3941,16 @@ function validateAgentPayload(payload, limits) {
     const fieldFailure = walkStringsForOverage(payload.payload, 'payload', eff.maxStringFieldBytes);
     if (fieldFailure)
         return fieldFailure;
+    // v2 — per-section caps. Each helper is a no-op when its section is absent
+    // so a v1 payload (no userMessage / systemContext / attachments / mcpScope /
+    // deepLinkRoute) sails through unchanged.
+    const v2Failure = checkUserMessage(payload, eff) ??
+        checkSystemContext(payload, eff) ??
+        checkAttachments(payload, eff) ??
+        checkMcpScope(payload, eff) ??
+        checkDeepLinkRoute(payload, eff);
+    if (v2Failure)
+        return v2Failure;
     const json = safeStringify(payload);
     const jsonBytes = utf8ByteLength(json);
     if (jsonBytes > eff.maxJsonBytes) {
@@ -3711,6 +3963,200 @@ function validateAgentPayload(payload, limits) {
     }
     return { ok: true };
 }
+// ─── v2 section validators ──────────────────────────────────────────────────
+function checkUserMessage(payload, eff) {
+    if (payload.userMessage === undefined)
+        return null;
+    if (typeof payload.userMessage !== 'string')
+        return null; // structural; ts catches at the call site
+    const bytes = utf8ByteLength(payload.userMessage);
+    if (bytes > eff.maxUserMessageBytes) {
+        return {
+            ok: false,
+            reason: 'user_message_too_large',
+            fieldPath: 'userMessage',
+            actualBytes: bytes,
+            limitBytes: eff.maxUserMessageBytes,
+        };
+    }
+    return null;
+}
+function checkSystemContext(payload, eff) {
+    const ctx = payload.systemContext;
+    if (!ctx)
+        return null;
+    const keys = Object.keys(ctx);
+    if (keys.length > eff.maxSystemContextEntries) {
+        return {
+            ok: false,
+            reason: 'system_context_too_many_entries',
+            fieldPath: 'systemContext',
+            actualBytes: keys.length,
+            limitBytes: eff.maxSystemContextEntries,
+        };
+    }
+    for (const k of keys) {
+        const v = ctx[k];
+        if (typeof v !== 'string')
+            continue;
+        const bytes = utf8ByteLength(v);
+        if (bytes > eff.maxSystemContextValueBytes) {
+            return {
+                ok: false,
+                reason: 'system_context_value_too_large',
+                fieldPath: `systemContext.${k}`,
+                actualBytes: bytes,
+                limitBytes: eff.maxSystemContextValueBytes,
+            };
+        }
+    }
+    const ctxJsonBytes = utf8ByteLength(safeStringify(ctx));
+    if (ctxJsonBytes > eff.maxSystemContextJsonBytes) {
+        return {
+            ok: false,
+            reason: 'system_context_json_too_large',
+            fieldPath: 'systemContext',
+            actualBytes: ctxJsonBytes,
+            limitBytes: eff.maxSystemContextJsonBytes,
+        };
+    }
+    return null;
+}
+function checkAttachments(payload, eff) {
+    const atts = payload.attachments;
+    if (!atts)
+        return null;
+    if (atts.length > eff.maxAttachments) {
+        return {
+            ok: false,
+            reason: 'too_many_attachments',
+            fieldPath: 'attachments',
+            actualBytes: atts.length,
+            limitBytes: eff.maxAttachments,
+        };
+    }
+    for (let i = 0; i < atts.length; i++) {
+        const a = atts[i];
+        const path = `attachments[${i}]`;
+        switch (a.kind) {
+            case 'json': {
+                const bytes = utf8ByteLength(safeStringify(a.json));
+                if (bytes > eff.maxAttachmentJsonBytes) {
+                    return {
+                        ok: false,
+                        reason: 'attachment_json_too_large',
+                        fieldPath: `${path}.json`,
+                        actualBytes: bytes,
+                        limitBytes: eff.maxAttachmentJsonBytes,
+                    };
+                }
+                break;
+            }
+            case 'text': {
+                const bytes = utf8ByteLength(a.text ?? '');
+                if (bytes > eff.maxAttachmentTextBytes) {
+                    return {
+                        ok: false,
+                        reason: 'attachment_text_too_large',
+                        fieldPath: `${path}.text`,
+                        actualBytes: bytes,
+                        limitBytes: eff.maxAttachmentTextBytes,
+                    };
+                }
+                break;
+            }
+            case 'image':
+            case 'file': {
+                const bytes = utf8ByteLength(a.dataUrl ?? '');
+                if (bytes > eff.maxAttachmentDataUrlBytes) {
+                    return {
+                        ok: false,
+                        reason: 'attachment_data_url_too_large',
+                        fieldPath: `${path}.dataUrl`,
+                        actualBytes: bytes,
+                        limitBytes: eff.maxAttachmentDataUrlBytes,
+                    };
+                }
+                break;
+            }
+            default:
+                return {
+                    ok: false,
+                    reason: 'attachment_invalid_kind',
+                    fieldPath: `${path}.kind`,
+                };
+        }
+    }
+    return null;
+}
+/**
+ * Validate `deepLinkRoute` — byte cap + minimal shape sanity check.
+ *
+ * The DS package is shell-agnostic, so full route grammar validation
+ * (scheme prefixes, `..` segments, `//` runs) lives in the shell's
+ * `DeepLinkService.isValidRoute` — the launcher is the authoritative
+ * gate. Here we just enforce:
+ *   - byte cap so a malicious payload can't bloat the JSON
+ *   - must start with `/` so the value matches the launcher's contract
+ *     and a renderer can safely concatenate / display it.
+ *
+ * Anything more would force the DS to grow a second copy of the route
+ * grammar; the launcher rejects malformed routes at click time so the
+ * worst-case impact of a bad route landing here is a no-op click.
+ */
+function checkDeepLinkRoute(payload, eff) {
+    const route = payload.deepLinkRoute;
+    if (route === undefined)
+        return null;
+    if (typeof route !== 'string')
+        return null; // structural; ts catches at the call site
+    if (!route.startsWith('/')) {
+        return {
+            ok: false,
+            reason: 'deep_link_route_invalid_shape',
+            fieldPath: 'deepLinkRoute',
+        };
+    }
+    const bytes = utf8ByteLength(route);
+    if (bytes > eff.maxDeepLinkRouteBytes) {
+        return {
+            ok: false,
+            reason: 'deep_link_route_too_large',
+            fieldPath: 'deepLinkRoute',
+            actualBytes: bytes,
+            limitBytes: eff.maxDeepLinkRouteBytes,
+        };
+    }
+    return null;
+}
+function checkMcpScope(payload, eff) {
+    const scope = payload.mcpScope;
+    if (!scope)
+        return null;
+    const apis = scope.apis ?? [];
+    if (apis.length > eff.maxMcpScopeApis) {
+        return {
+            ok: false,
+            reason: 'mcp_scope_too_many_apis',
+            fieldPath: 'mcpScope.apis',
+            actualBytes: apis.length,
+            limitBytes: eff.maxMcpScopeApis,
+        };
+    }
+    for (let i = 0; i < apis.length; i++) {
+        const bytes = utf8ByteLength(apis[i]);
+        if (bytes > eff.maxMcpScopeApiBytes) {
+            return {
+                ok: false,
+                reason: 'mcp_scope_api_too_large',
+                fieldPath: `mcpScope.apis[${i}]`,
+                actualBytes: bytes,
+                limitBytes: eff.maxMcpScopeApiBytes,
+            };
+        }
+    }
+    return null;
+}
 /**
  * Returns a NEW payload with all string fields trimmed to fit the per-field cap, the
  * `plainTextFallback` trimmed to its cap, and the full envelope re-checked against the
@@ -3816,6 +4262,234 @@ function safeStringify(value) {
     });
 }
 
+/**
+ * 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.
+ */
+class AgentActionBus {
+    _actions$ = new Subject();
+    /** 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. */
+    actions$ = this._actions$.asObservable();
+    /** Most recent action — for DevTools, smoke tests, and late-subscriber
+     *  catch-up. Null until the first successful dispatch. */
+    lastAction = signal(null, ...(ngDevMode ? [{ debugName: "lastAction" }] : /* istanbul ignore next */ []));
+    /**
+     * 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).
+     */
+    inFlight = signal(null, ...(ngDevMode ? [{ debugName: "inFlight" }] : /* istanbul ignore next */ []));
+    /**
+     * 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(action) {
+        if (action.dispatch === 'auto') {
+            throw new AgentActionUnsupportedDispatchError(action.dispatch);
+        }
+        const v = validateAgentPayload(action.payload);
+        if (!v.ok) {
+            const where = v.fieldPath ? ` at ${v.fieldPath}` : '';
+            throw new Error(`AgentActionBus.dispatch: invalid payload — ${v.reason}${where}`);
+        }
+        const a = action;
+        this.lastAction.set(a);
+        this.inFlight.set(a);
+        this._actions$.next(a);
+    }
+    /**
+     * 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) {
+        if (this.inFlight() === action) {
+            this.inFlight.set(null);
+        }
+    }
+    /**
+     * 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) {
+        if (this.inFlight() === action) {
+            this.inFlight.set(null);
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: AgentActionBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: AgentActionBus, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: AgentActionBus, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * 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.
+ */
+class AgentFlightAnimator {
+    /** Hardcoded — see class doc. */
+    static DURATION_MS = 900;
+    static EASING = 'cubic-bezier(.2,.7,.2,1)';
+    /** Floor the target/source scale ratio so a tiny target rect doesn't
+     *  collapse the ghost to invisibility before the animation finishes. */
+    static MIN_SCALE = 0.05;
+    targetEl = null;
+    /** 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) {
+        this.targetEl = el;
+    }
+    /**
+     * 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, opts = {}) {
+        if (!this.targetEl)
+            return;
+        if (typeof document === 'undefined')
+            return;
+        const reduced = typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+            ? window.matchMedia('(prefers-reduced-motion: reduce)').matches
+            : false;
+        const to = this.targetEl.getBoundingClientRect();
+        const ghost = document.createElement('div');
+        ghost.className = 'fly-agent-flight-ghost';
+        // The ghost is purely decorative — it duplicates the source content
+        // (chart title + snapshot) that the user just clicked and screen-reader
+        // users have already heard via the sparkle button's aria-label. Re-
+        // announcing the same content during the flight would be noisy at best
+        // and confusing at worst. aria-hidden hides the subtree from assistive
+        // tech while leaving it visible for sighted users.
+        ghost.setAttribute('aria-hidden', 'true');
+        // role="presentation" is belt-and-braces — even if a future renderer
+        // walks the tree looking for semantic landmarks, the ghost has none.
+        ghost.setAttribute('role', 'presentation');
+        if (opts.previewHtml) {
+            // Caller is responsible for safe HTML — the bus subscriber escapes
+            // plainTextFallback before passing it here.
+            ghost.innerHTML = opts.previewHtml;
+        }
+        Object.assign(ghost.style, {
+            position: 'fixed',
+            left: `${from.left}px`,
+            top: `${from.top}px`,
+            width: `${from.width}px`,
+            height: `${from.height}px`,
+            pointerEvents: 'none',
+            zIndex: '99999',
+            transformOrigin: 'top left',
+            willChange: 'transform, opacity',
+        });
+        document.body.appendChild(ghost);
+        if (reduced) {
+            ghost.remove();
+            return;
+        }
+        const dx = to.left - from.left;
+        const dy = to.top - from.top;
+        const sx = Math.max(to.width / from.width, AgentFlightAnimator.MIN_SCALE);
+        const sy = Math.max(to.height / from.height, AgentFlightAnimator.MIN_SCALE);
+        const anim = ghost.animate([
+            { transform: 'translate(0,0) scale(1,1)', opacity: 1 },
+            { transform: `translate(${dx}px,${dy}px) scale(${sx},${sy})`, opacity: 0.15 },
+        ], {
+            duration: AgentFlightAnimator.DURATION_MS,
+            easing: AgentFlightAnimator.EASING,
+            fill: 'forwards',
+        });
+        const cleanup = () => ghost.remove();
+        anim.onfinish = cleanup;
+        anim.oncancel = cleanup;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: AgentFlightAnimator, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: AgentFlightAnimator, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: AgentFlightAnimator, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
 /**
  * Strict whitelist for the ghost element id. Letter-led ASCII, allows word/hyphen/colon/dot,
  * capped at 128 chars. Anything else is rejected before reaching `getElementById` so a
@@ -3922,6 +4596,113 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImpor
                 args: ['dragstart', ['$event']]
             }] } });
 
+/**
+ * Renders an authenticated image into a host `<img>` element by fetching the
+ * resource as a blob through Angular's `HttpClient` and binding the resulting
+ * object URL to the host's `src` attribute.
+ *
+ * Why this exists: every Business / Supporting app stores files in the Files
+ * Manager service, which authenticates with a Bearer JWT. A raw `<img src>`
+ * request bypasses the Angular HTTP interceptor — the browser issues the GET
+ * without the Authorization header, so the response is 401 and the image is
+ * broken. The standard workaround is roughly fifteen lines of `effect` +
+ * `URL.createObjectURL` + `URL.revokeObjectURL` per call site (see prior
+ * inline copies in `FlyImageUploadComponent` and the Circles trend-detail
+ * cover). This directive centralizes that pattern so:
+ *
+ *   * Memory hygiene is automatic — the previous object URL is revoked
+ *     whenever the input changes and on destroy. Easy to forget inline.
+ *   * Error handling is uniform — a fetch failure clears the host `src`
+ *     so the browser shows its broken-image affordance once, not the prior
+ *     image stuck on screen.
+ *   * A future protocol change (per-request signed URLs, CDN tokens, etc.)
+ *     lands in one place rather than across every app's image bindings.
+ *
+ * Usage:
+ *
+ * ```html
+ * <img [flySecureSrc]="trend.coverImageId" alt="" class="cover-img" />
+ * ```
+ *
+ * Pass a full URL when the resource lives somewhere other than the default
+ * Files Manager download endpoint:
+ *
+ * ```html
+ * <img [flySecureSrc]="'/api/avatars/' + user.id" alt="" />
+ * ```
+ *
+ * A bare file id (no `/` prefix) is resolved against
+ * `/api/files/{id}/download`, which matches the Files Manager convention
+ * used everywhere in the platform. Anything that starts with `/` is treated
+ * as a literal URL and passed through unchanged — apps with bespoke download
+ * routes (signed Excel exports, attachment thumbnails, …) keep working
+ * without a wrapper.
+ */
+class FlySecureSrcDirective {
+    /**
+     * File id or absolute path. Passing `null` / `undefined` / `''` clears the
+     * `src` attribute and revokes the previous blob. Useful when binding to a
+     * signal whose value can become empty (e.g. after a file is detached).
+     */
+    flySecureSrc = input(...(ngDevMode ? [undefined, { debugName: "flySecureSrc" }] : /* istanbul ignore next */ []));
+    http = inject(HttpClient);
+    host = inject((ElementRef));
+    renderer = inject(Renderer2);
+    /**
+     * The object URL currently bound to the host's `src` attribute. Tracked so
+     * we can revoke it before binding a new one (avoids leaking blob memory
+     * across rapid input changes — e.g. carousel scrubbing) and on destroy.
+     */
+    currentUrl = null;
+    constructor() {
+        effect((onCleanup) => {
+            const raw = this.flySecureSrc();
+            this.releaseCurrent();
+            this.renderer.removeAttribute(this.host.nativeElement, 'src');
+            if (!raw)
+                return;
+            const url = raw.startsWith('/') ? raw : `/api/files/${raw}/download`;
+            const sub = this.http
+                .get(url, { responseType: 'blob' })
+                .subscribe({
+                next: (blob) => {
+                    const objectUrl = URL.createObjectURL(blob);
+                    this.currentUrl = objectUrl;
+                    this.renderer.setAttribute(this.host.nativeElement, 'src', objectUrl);
+                },
+                // A 401 / 403 / 404 here means the image is unavailable for this user.
+                // Don't loop or retry — clear the src and let the host page render its
+                // own placeholder. Logging is intentionally silent: it's expected on
+                // permission boundaries (e.g. shared-evidence on a trend you can read
+                // but whose file you can't), and stack-traces would be noise.
+                error: () => {
+                    this.releaseCurrent();
+                    this.renderer.removeAttribute(this.host.nativeElement, 'src');
+                },
+            });
+            onCleanup(() => sub.unsubscribe());
+        });
+    }
+    ngOnDestroy() {
+        this.releaseCurrent();
+    }
+    releaseCurrent() {
+        if (this.currentUrl) {
+            URL.revokeObjectURL(this.currentUrl);
+            this.currentUrl = null;
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: FlySecureSrcDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "21.2.5", type: FlySecureSrcDirective, isStandalone: true, selector: "img[flySecureSrc]", inputs: { flySecureSrc: { classPropertyName: "flySecureSrc", publicName: "flySecureSrc", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImport: i0, type: FlySecureSrcDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: 'img[flySecureSrc]',
+                    standalone: true,
+                }]
+        }], ctorParameters: () => [], propDecorators: { flySecureSrc: [{ type: i0.Input, args: [{ isSignal: true, alias: "flySecureSrc", required: false }] }] } });
+
 /**
  * Verbatim TypeScript port of the C# `LanguageDTO[] _AllLanguages` array supplied by
  * product. **31 entries**, in the canonical order. Three RTL flagged: `he-IL`, `ur-IN`,
@@ -4533,6 +5314,31 @@ function isRtlLocaleEntry(entry) {
  *         centralising the canonicalization rule that strips `-service` from
  *         JWT client_ids (`circles-service` → `circles`) so chips, banners,
  *         and launchers stay consistent across the shell.
+ * v2.6.0: Agent action bus + flight animator. New imperative sibling to
+ *         `AgentCommandRegistry` / `AgentDropRegistry`: `AgentActionBus` lets
+ *         any app push a typed `AgentAction { verb, payload, dispatch, originRect }`
+ *         to the agent panel without going through drag-drop. `AgentFlightAnimator`
+ *         plays a FLIP-style transform animation from the source DOM rect to the
+ *         registered panel-header rect (hardcoded 420 ms / cubic-bezier; honours
+ *         prefers-reduced-motion). Phase 1 supports `dispatch: 'stage'` only —
+ *         `'auto'` throws `AgentActionUnsupportedDispatchError` until
+ *         `AgentInputComponent.programmaticSubmit` ships. Re-uses
+ *         `AgentDragPayload<T>` as the wire envelope so drag and programmatic
+ *         transports never fork. New verbs: `explain`, `why-empty`,
+ *         `compose-query`, `compare`, `forecast`, `summarize`.
+ * v2.10.0: Per-window help-deeplink contract. The shell renders a help-icon
+ *          button in every non-chromeless `<fly-window>` titlebar. By default
+ *          the deeplink uses `win.appId`; apps override or augment via the
+ *          new `WINDOW_HELP_HINT` InjectionToken (a `WritableSignal<WindowHelpHint | null>`)
+ *          provided per-window. `WindowHelpHint` is `{ appId?, topic? }` —
+ *          `topic` is a free-form search-query seed updated dynamically as the
+ *          user navigates within the app. New federation-safe channel
+ *          `FLY_WINDOW_HELP_HINT_EVENT` mirrors the DI surface for federated
+ *          remotes. New exports: `WindowHelpHint`, `WINDOW_HELP_HINT`,
+ *          `FLY_WINDOW_HELP_HINT_EVENT`, `FlyWindowHelpHintEventDetail`.
+ *          Backed by the help-center reader's new `params.topic` launch payload
+ *          and "no help for this app yet" empty-state. See
+ *          `skills/help-center.md` and `skills/desktop-shell-angular.md`.
  * v2.5.1: New `MessageBoxService.showAcknowledged()` entry point returning
  *         `DialogResultWithAcknowledgement` for "Don't ask again"-style flows.
  *         The `dontAskAgain` config (`MessageBoxDontAskAgainConfig`) lives ONLY on
@@ -4560,5 +5366,5 @@ const AUDIENCE_ERROR_CODES = {
  * Generated bundle index. Do not edit.
  */
 
-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, 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 { 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 };
 //# sourceMappingURL=mohamedatia-fly-design-system.mjs.map