@mohamedatia/fly-design-system 2.4.0 → 2.6.0

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

@@ -2,6 +2,8 @@ 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 { Observable } from 'rxjs';
+import { NavigationExtras } from '@angular/router';
+import * as _mohamedatia_fly_design_system from '@mohamedatia/fly-design-system';
 
 /**
  * FlyOS architectural app category — see repo `docs/01-ecosystem-overview.md`.
@@ -880,6 +882,105 @@ declare class StandaloneWindowManagerService extends WindowManagerService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<StandaloneWindowManagerService>;
 }
 
+/**
+ * FlyOS standard navigation surface for Business / Supporting App remotes.
+ *
+ * Problem this solves
+ * -------------------
+ * A federated remote ships with its own Angular `Routes` table that works
+ * perfectly in **standalone** mode (e.g. `http://localhost:7202/signals/:id`).
+ * Once the same remote is mounted inside the FlyOS desktop shell via
+ * `*ngComponentOutlet`, `inject(Router)` resolves to the **host shell's**
+ * Router — which has no knowledge of `/signals/:id`. Calls like
+ * `router.navigate(['/signals', id])` then silently no-op and the click
+ * "does nothing."
+ *
+ * The fix
+ * -------
+ * Inject `FlyRemoteRouter` instead of `Router`. It mirrors `Router.navigate` /
+ * `Router.navigateByUrl` and:
+ *
+ *  - **Standalone** (no `WINDOW_DATA`): delegates to the real Angular Router,
+ *    so the URL bar, browser back button, and `RouterLink` continue to work
+ *    exactly as before.
+ *  - **Embedded** (mounted in the shell via `WINDOW_DATA`): writes the target
+ *    URL to an internal signal (`url`, `segments`) and does **not** touch the
+ *    host's Router. The remote's root component watches the signal and renders
+ *    the right view (typically a `@switch` on the first segment, plus an inline
+ *    overlay for detail pages).
+ *
+ * Usage in a list page
+ * --------------------
+ * ```ts
+ * private readonly router = inject(FlyRemoteRouter);
+ *
+ * openDetail(item: Signal): void {
+ *   this.router.navigate(['/signals', item.id]); // works in both modes
+ * }
+ * ```
+ *
+ * Usage in the remote's root component (embedded dispatcher)
+ * ----------------------------------------------------------
+ * ```ts
+ * private readonly router = inject(FlyRemoteRouter);
+ *
+ * readonly view = computed(() => {
+ *   if (!this.router.isEmbedded) return null;        // standalone: <router-outlet> handles it
+ *   const [head, id] = this.router.segments();
+ *   if (head === 'signals' && id) return { kind: 'signal-detail', id };
+ *   if (head === 'signals')      return { kind: 'signals-list' };
+ *   return { kind: head ?? 'home' };
+ * });
+ * ```
+ *
+ * Notes
+ * -----
+ * - `WINDOW_DATA` is the canonical "I am running inside the shell" marker; the
+ *   shell provides it per window, and it is `null` everywhere else.
+ * - `Router` is injected as `optional`. A remote that does not register a Router
+ *   (e.g. a tiny chromeless utility app) still gets a working `navigate` that
+ *   updates the `url` signal in embedded mode.
+ */
+declare class FlyRemoteRouter {
+    private readonly windowData;
+    private readonly router;
+    /** True when this remote is rendered inside the FlyOS desktop shell. */
+    readonly isEmbedded: boolean;
+    private readonly _url;
+    /**
+     * Current logical URL of the remote — `/signals/abc` etc.
+     *
+     * Standalone: mirrors `Router.url` and is updated on every `NavigationEnd`.
+     * Embedded:   updated by `navigate` / `navigateByUrl` only.
+     */
+    readonly url: _angular_core.Signal<string>;
+    /**
+     * `url` parsed into path segments, e.g. `'/signals/abc'` → `['signals', 'abc']`.
+     * Query string and hash are stripped. Empty segments removed.
+     */
+    readonly segments: _angular_core.Signal<readonly string[]>;
+    constructor();
+    /**
+     * Navigate to a route, identified by an array of commands as you would pass
+     * to Angular's `Router.navigate`. In embedded mode `extras` is ignored — the
+     * shell owns history and query-param handling for the window's URL.
+     */
+    navigate(commands: readonly unknown[], extras?: NavigationExtras): Promise<boolean>;
+    /**
+     * Navigate to a route given as a full URL string. Mirrors `Router.navigateByUrl`.
+     */
+    navigateByUrl(url: string, extras?: NavigationExtras): Promise<boolean>;
+    /**
+     * Convenience: pop the last two segments (the typical "go back from detail
+     * to list" gesture). In standalone mode this falls through to `history.back()`
+     * so the browser's back stack is respected.
+     */
+    back(): void;
+    private buildUrl;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlyRemoteRouter, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<FlyRemoteRouter>;
+}
+
 /**
  * Translates a key using the shared I18nService.
  *
@@ -1035,11 +1136,37 @@ interface MessageBoxOptions {
     buttons?: MessageBoxButtons;
     icon?: MessageBoxIcon;
 }
+/**
+ * Configuration for the "Don't ask again" checkbox rendered by
+ * `showAcknowledged()`. The field is intentionally NOT part of the base
+ * `MessageBoxOptions` so the type system enforces the rule
+ * "checkbox ⇒ caller MUST use `showAcknowledged()`": the classic `show()`
+ * entry point cannot accept this shape, eliminating the silent-discard
+ * dark-pattern path where the user's choice was thrown away.
+ */
+interface MessageBoxDontAskAgainConfig {
+    /** i18n key for the checkbox label, e.g. 'agent.command.builtin.clear.dont_ask_again'. */
+    labelKey: string;
+    /** Initial checked state. Default false. */
+    defaultChecked?: boolean;
+}
+/**
+ * Options narrowed to those carrying a `dontAskAgain` config — the only shape
+ * accepted by `showAcknowledged()`.
+ */
+interface MessageBoxOptionsWithAcknowledgement extends MessageBoxOptions {
+    dontAskAgain: MessageBoxDontAskAgainConfig;
+}
 interface MessageBoxButton {
     label: string;
     result: DialogResult;
     variant?: 'primary' | 'danger' | 'default';
 }
+/** Shape returned by `showAcknowledged()` — pairs the dialog result with the checkbox state. */
+interface DialogResultWithAcknowledgement {
+    readonly result: DialogResult;
+    readonly dontAskAgain: boolean;
+}
 declare class MessageBoxService {
     private readonly i18n;
     readonly visible: _angular_core.WritableSignal<boolean>;
@@ -1047,9 +1174,32 @@ declare class MessageBoxService {
     readonly message: _angular_core.WritableSignal<string>;
     readonly icon: _angular_core.WritableSignal<MessageBoxIcon>;
     readonly buttons: _angular_core.WritableSignal<MessageBoxButton[]>;
+    /**
+     * Active "Don't ask again" config — populated only by `showAcknowledged()`.
+     * `show()` callers cannot reach this signal because the type system rejects
+     * `dontAskAgain` on the base `MessageBoxOptions`.
+     */
+    readonly dontAskAgain: _angular_core.WritableSignal<MessageBoxDontAskAgainConfig | undefined>;
+    /**
+     * Component-side checkbox state. The component (`MessageBoxComponent`) wires
+     * its own signal to this one; the service explicitly re-seeds it on every
+     * `_open()` so reusing a constant `options` literal across two opens does
+     * NOT leak the previous user's checkbox state through signal `===` dedupe.
+     * Exposed for the component to read/write; not for general callers.
+     */
+    readonly dontAskAgainChecked: _angular_core.WritableSignal<boolean>;
     private resolver;
     show(options: MessageBoxOptions): Promise<DialogResult>;
-    resolve(result: DialogResult): void;
+    /**
+     * Opens a message box with a "Don't ask again" checkbox and resolves to both
+     * the dialog result and the checkbox state. Throws when `options.dontAskAgain`
+     * is missing — the checkbox config is mandatory for this entry point. The
+     * compile-time signature already guarantees presence; the runtime check is
+     * defense-in-depth for callers that bypass the type system via `as never`.
+     */
+    showAcknowledged(options: MessageBoxOptionsWithAcknowledgement): Promise<DialogResultWithAcknowledgement>;
+    resolve(result: DialogResult, dontAskAgain?: boolean): void;
+    private _open;
     private resolveButtons;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MessageBoxService, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<MessageBoxService>;
@@ -1060,11 +1210,25 @@ declare class MessageBoxComponent implements AfterViewInit {
     private elRef;
     readonly MessageBoxIcon: typeof MessageBoxIcon;
     readonly DialogResult: typeof DialogResult;
+    /** Mirror of the service's `dontAskAgain` config so the template can read it directly. */
+    readonly dontAskAgainConfig: _angular_core.Signal<_mohamedatia_fly_design_system.MessageBoxDontAskAgainConfig | undefined>;
+    /**
+     * User-driven checkbox state, owned by the service and re-seeded on every
+     * `_open()` so reusing a constant options literal cannot leak prior state.
+     */
+    readonly dontAskAgainChecked: _angular_core.WritableSignal<boolean>;
+    /**
+     * Concatenated id list for the dialog's `aria-describedby`. Always includes
+     * the message; appends the checkbox label id when the checkbox is rendered
+     * so screen readers announce the checkbox as part of the description.
+     */
+    readonly ariaDescribedBy: _angular_core.Signal<"mb-message mb-dont-ask" | "mb-message">;
     private previouslyFocused;
     ngAfterViewInit(): void;
     onEscape(): void;
     onBackdropClick(): void;
     onButtonClick(result: DialogResult): void;
+    onDontAskAgainToggle(ev: Event): void;
     iconClass(): string;
     private focusPrimaryButton;
     private restoreFocus;
@@ -1221,6 +1385,465 @@ declare class FlyFileUploadComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<FlyFileUploadComponent, "fly-file-upload", never, { "maxFiles": { "alias": "maxFiles"; "required": false; "isSignal": true; }; "maxFileSizeBytes": { "alias": "maxFileSizeBytes"; "required": false; "isSignal": true; }; "accept": { "alias": "accept"; "required": false; "isSignal": true; }; "sourceApp": { "alias": "sourceApp"; "required": false; "isSignal": true; }; "sourceEntityType": { "alias": "sourceEntityType"; "required": false; "isSignal": true; }; "sourceEntityId": { "alias": "sourceEntityId"; "required": false; "isSignal": true; }; "existingFileIds": { "alias": "existingFileIds"; "required": false; "isSignal": true; }; "files": { "alias": "files"; "required": false; "isSignal": true; }; }, { "files": "filesChange"; "filesChanged": "filesChanged"; }, never, never, true, never>;
 }
 
+/**
+ * Agent input contracts.
+ *
+ * These types define the wire and DI surface for the new `<fly-agent-input>` orchestrator
+ * (Phase 2+). Phase 1 ships only the contracts: payload envelope, command/drop registry
+ * shapes, and chip-host inputs. The concrete components consume them later.
+ *
+ * Design rules:
+ *   - All fields are `readonly` — the registries store these in signal stores and we never
+ *     want a host mutating after registration. Hosts construct fresh objects to update.
+ *   - The discriminated kinds (`scope`, `mode`, `kind`) carry the entire variance — no
+ *     boolean flags. New variants extend the union without breaking existing consumers.
+ *   - The `Type<AgentChipHostInputs<T>>` shape is intentional: chip components declare
+ *     `payload`, `mode`, optional `onRemove` as Angular `input()` signals; the registry
+ *     wires them via `NgComponentOutlet` inputs in the consumer. The component reference
+ *     itself never leaks across the federation boundary by value — only by class identity.
+ */
+/** 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;
+/**
+ * Where a command surfaces. `'global'` = always offered. `{ appId }` = offered only when
+ * the host's live `liveAppIds` set (passed to {@link AgentCommandRegistry.visible}) contains
+ * that id. This lets a remote register its slash command at boot but only have it appear
+ * in the palette while at least one of the remote's windows is open.
+ */
+type AgentCommandScope = 'global' | {
+    readonly appId: string;
+};
+/**
+ * A slash command offered by the agent input palette. Commands are deliberately shallow
+ * descriptors — the host (shell) decides what happens on Send. The descriptor's role is
+ * to make the palette row renderable (icon, label, kbd hint, app badge) and matchable
+ * (id, aliases, drop-kind suggestions) without coupling DS to any business logic.
+ */
+interface AgentCommand {
+    /** Stable id, kebab-case. Becomes the slash text after `/`, e.g. `/analyze-trend`. */
+    readonly id: string;
+    /** i18n key for the visible label, e.g. `agent.command.analyze_trend.label`. */
+    readonly labelKey: string;
+    /** i18n key for an optional sublabel / description shown beneath the label. */
+    readonly descriptionKey?: string;
+    /** PrimeIcons class, e.g. `pi-chart-line`. */
+    readonly icon?: string;
+    /** App badge label key — appears as a small tag, e.g. `agent.command.app_badge.circles`. */
+    readonly appBadgeKey?: string;
+    /** Optional kbd hint i18n key. */
+    readonly kbdHintKey?: string;
+    /** When the command is keyword-matched against drop payload kinds, list those kinds here. */
+    readonly suggestForDropKinds?: readonly string[];
+    /** Extra match terms beyond id + label, used by the fuzzy filter. */
+    readonly aliases?: readonly string[];
+    /** When `'send'`, the command is inserted as a bound prefix and executed on Send. */
+    readonly executeOn: 'send';
+    /** Optional client-side gate. Return false to hide the command in this scope. */
+    readonly isVisible?: () => boolean;
+}
+/** What hosts pass to {@link AgentCommandRegistry.register}. Adds the scope to {@link AgentCommand}. */
+interface AgentCommandRegistration extends AgentCommand {
+    readonly scope: AgentCommandScope;
+}
+/** Disposable handle returned by {@link AgentCommandRegistry.register}. Idempotent `dispose()`. */
+interface AgentCommandHandle {
+    dispose(): void;
+}
+/**
+ * The wire envelope written to a `DataTransfer` by `flyAgentDraggable`. Renderers narrow
+ * on `kind`; mismatches fall back to `plainTextFallback`.
+ */
+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;
+    /** 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[];
+}
+/**
+ * Where a chip is being rendered. `inline` = inside the input chip tray (removable);
+ * `message` = embedded in a sent message bubble (not removable).
+ */
+type AgentDropChipMode = 'inline' | 'message';
+/**
+ * Public input shape for chip-renderer components. Components declare matching
+ * `input()` signals; the registry wires them via `NgComponentOutlet`.
+ */
+interface AgentChipHostInputs<T = unknown> {
+    payload: AgentDragPayload<T>;
+    mode: AgentDropChipMode;
+    /** Called when the user clicks the chip's remove control (only in inline mode). */
+    onRemove?: () => void;
+}
+/**
+ * Keyboard-alternative draggable item. Hosts publish these via
+ * {@link AgentDropRegistry.publishDraggables} so the "Attach from app…" menu can offer
+ * them when pointer drag isn't available.
+ */
+interface AgentDraggableItem<T = unknown> {
+    /** Stable id within its app. Used as a list key in the kbd menu. */
+    readonly id: string;
+    readonly labelKey: string;
+    readonly icon?: string;
+    /** Builds the payload the moment the user picks the item. */
+    build(): AgentDragPayload<T>;
+}
+/** Registry input shape for binding a chip-renderer component to a kind+appId pair. */
+interface AgentDropRendererRegistration<T = unknown> {
+    readonly kind: string;
+    readonly appId: string;
+    readonly component: Type<AgentChipHostInputs<T>>;
+}
+/**
+ * Caps applied by {@link validateAgentPayload} / {@link trimAgentPayload}. The defaults
+ * trade off "fits comfortably in a single MQ frame" against "covers a richly-populated
+ * trend or note card". Hosts may pass a partial override.
+ */
+interface AgentPayloadLimits {
+    /** Cap on the JSON.stringify(envelope) byte length. Default 32 KB. */
+    readonly maxJsonBytes: number;
+    /** Cap on the plainTextFallback byte length. Default 8 KB. */
+    readonly maxPlainTextFallbackBytes: number;
+    /** Cap on any single string field inside payload (recursive). Default 4 KB. */
+    readonly maxStringFieldBytes: number;
+}
+declare const DEFAULT_AGENT_PAYLOAD_LIMITS: AgentPayloadLimits;
+/**
+ * Stable failure reasons emitted by {@link validateAgentPayload}.
+ *   - `invalid_version` — `version` !== {@link AGENT_PAYLOAD_VERSION}.
+ *   - `invalid_kind` — `kind` is empty / not a string.
+ *   - `field_too_large` — a string field inside `payload` exceeds `maxStringFieldBytes`.
+ *   - `fallback_too_large` — `plainTextFallback` exceeds `maxPlainTextFallbackBytes`.
+ *   - `json_too_large` — the full JSON.stringify(envelope) exceeds `maxJsonBytes`.
+ */
+type AgentPayloadValidationResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: 'json_too_large' | 'fallback_too_large' | 'field_too_large' | 'invalid_version' | 'invalid_kind';
+    /** 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;
+    readonly limitBytes?: number;
+};
+
+/**
+ * Singleton registry of slash commands offered by the agent input palette.
+ *
+ * Lives in the DS so it crosses the federation boundary as a single instance via
+ * `sharedMappings: ['@mohamedatia/fly-design-system']`. Federated remotes register
+ * their commands at boot (and dispose on window close) without forking the shell.
+ *
+ * Storage is a signal store. `register` is O(1) for the unique-id case and O(n) when
+ * replacing an existing id (filter then push). The append-then-replace strategy is
+ * deliberate: registrations are rare (each one corresponds to a remote's app-init
+ * effect), and the tradeoff buys us a stable id-collision contract — the *latest*
+ * registration wins, and the previous handle's `dispose()` becomes a no-op rather
+ * than removing the new entry.
+ */
+declare class AgentCommandRegistry {
+    private readonly _commands;
+    /** All currently-registered commands, in insertion order. */
+    readonly all: Signal<readonly AgentCommandRegistration[]>;
+    /**
+     * Returns a signal of commands whose scope is `'global'` OR whose `scope.appId` is in
+     * the live app set. The signal recomputes when either the registry or `liveAppIds`
+     * changes — pass a `Signal<ReadonlySet<string>>` from the host's app-registry service
+     * for reactive filtering.
+     */
+    visible(liveAppIds: ReadonlySet<string> | Signal<ReadonlySet<string>>): Signal<readonly AgentCommandRegistration[]>;
+    /**
+     * Register a single command. Returns a handle whose `dispose()` removes the row by
+     * id. If the same id is later re-registered, the original handle's `dispose()`
+     * becomes a no-op (the newer registration owns the row). Idempotent disposal.
+     */
+    register(cmd: AgentCommandRegistration): AgentCommandHandle;
+    /**
+     * Bulk register. Rolls back on duplicate id 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.
+     *
+     * Returns a handle whose `dispose()` tears down every row registered by this call.
+     */
+    registerAll(cmds: readonly AgentCommandRegistration[]): AgentCommandHandle;
+    /** Tear down by id. Idempotent. */
+    unregister(id: string): void;
+    /** Monotonic counter; identifies which registration call currently owns each id. */
+    private _generation;
+    /** id → generation. Used so a stale handle's `dispose()` is a no-op after replacement. */
+    private readonly _owners;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AgentCommandRegistry, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<AgentCommandRegistry>;
+}
+
+/**
+ * Singleton registry of chip-renderer components and keyboard-alternative draggable
+ * items, keyed by `kind` and `appId`.
+ *
+ * Like {@link AgentCommandRegistry}, this lives in the DS so it crosses the federation
+ * boundary as a single instance. Hosts (the shell `<fly-agent-input>`) lookup
+ * renderers; remotes register them.
+ *
+ * Renderer lookup is `O(n)` over the registered list — the registry is small (one or
+ * two entries per app) and lookups happen on drop, not per frame.
+ *
+ * Draggable storage is per-`appId` writable signal cached in a Map, so each `appId`
+ * gets a stable {@link Signal} reference across reads (callers can `===`-compare).
+ */
+declare class AgentDropRegistry {
+    private readonly _renderers;
+    /** Per-appId writable store for draggables. Read-only mirror returned to callers. */
+    private readonly _draggablesByApp;
+    /**
+     * Look up the chip-renderer component class for a `kind`. The newest registration for
+     * a given `kind` wins, regardless of `appId` — we scan the list in reverse so a later
+     * `register` call shadows an earlier one for the same `kind`.
+     *
+     * Returns `null` when no renderer is registered; the host falls back to a generic
+     * `plainTextFallback` chip.
+     */
+    rendererFor(kind: string): Type<AgentChipHostInputs> | null;
+    /**
+     * Register a renderer for a `(kind, appId)` pair. Re-registering the same pair
+     * replaces the prior entry; the disposal handle for the prior registration becomes
+     * a no-op.
+     *
+     * Returns a {@link AgentCommandHandle} (re-used to keep the disposable shape uniform
+     * across registries) whose `dispose()` removes this exact registration.
+     */
+    register<T = unknown>(reg: AgentDropRendererRegistration<T>): AgentCommandHandle;
+    /**
+     * Apps publish their live "draggable from focused window" set so the keyboard
+     * "Attach from app…" menu can offer them. Hosts call this each time the user-visible
+     * draggable list changes; passing an empty array clears the entry for this `appId`.
+     */
+    publishDraggables(appId: string, items: readonly AgentDraggableItem[]): void;
+    /**
+     * Reactive read of the draggable set published for `appId`. Empty when none. The
+     * returned signal is stable across calls (cached by `appId`), so consumers can use
+     * it as a stable input to `computed()`.
+     */
+    draggablesFor(appId: string): Signal<readonly AgentDraggableItem[]>;
+    /** Lazy-init the per-appId writable bucket. Returns the writable handle for internal use. */
+    private bucketFor;
+    private _generation;
+    private readonly _owners;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AgentDropRegistry, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<AgentDropRegistry>;
+}
+
+/**
+ * Single canonical way to declare a drag source for the agent input.
+ *
+ * Apply on any element a remote wants to make draggable into the `<fly-agent-input>`:
+ *
+ * ```html
+ * <article [flyAgentDraggable]="() => buildPayload(trend)" flyAgentDraggableGhostId="trend-ghost">…</article>
+ * ```
+ *
+ * On `dragstart` the directive:
+ *   1. Resolves the payload (calls the builder fn if supplied; otherwise reads the
+ *      static value).
+ *   2. Validates against {@link DEFAULT_AGENT_PAYLOAD_LIMITS} via
+ *      {@link validateAgentPayload}. On failure it `console.warn`s with the structured
+ *      reason and writes ONLY the `text/plain` fallback — the receiver still sees a
+ *      legible drop, but the typed envelope is skipped so a misconfigured app can't
+ *      corrupt downstream consumers with an oversize payload.
+ *   3. Writes the typed MIME (`application/x-fly-agent-payload+json`) plus the
+ *      `text/plain` fallback so non-Fly drop targets still get useful text.
+ *   4. Sets `effectAllowed = 'copy'` (we never *move* domain objects across windows).
+ *   5. When `flyAgentDraggableGhostId` resolves to an element in the DOM, calls
+ *      `setDragImage` to use that element as the drag preview; otherwise the browser
+ *      default applies.
+ *
+ * Notes:
+ *   - Builder form is preferred over static — it captures fresh state at `dragstart`,
+ *     not at directive init. A static `AgentDragPayload` is fine for items whose
+ *     domain object never changes after the row mounts.
+ *   - The directive sets `[attr.draggable]="true"` so callers don't have to.
+ */
+declare class FlyAgentDraggableDirective<T = unknown> {
+    /**
+     * Either a static payload or a builder evaluated at `dragstart` (preferred — captures
+     * fresh state). `input.required` so misuse fails at template compile time.
+     */
+    readonly flyAgentDraggable: _angular_core.InputSignal<AgentDragPayload<T> | (() => AgentDragPayload<T>)>;
+    /**
+     * Optional ghost element id (an existing element in the DOM whose snapshot becomes
+     * the drag image). Falls back to the default browser drag image when absent or the
+     * element can't be resolved.
+     *
+     * Must be a valid HTML id (ASCII, letter-led). `getElementById` is intentional —
+     * do NOT swap to `querySelector` without re-introducing this whitelist.
+     */
+    readonly flyAgentDraggableGhostId: _angular_core.InputSignal<string | undefined>;
+    private readonly doc;
+    onDragStart(ev: DragEvent): void;
+    private resolvePayload;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlyAgentDraggableDirective<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<FlyAgentDraggableDirective<any>, "[flyAgentDraggable]", never, { "flyAgentDraggable": { "alias": "flyAgentDraggable"; "required": true; "isSignal": true; }; "flyAgentDraggableGhostId": { "alias": "flyAgentDraggableGhostId"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Pure utility helpers for agent drag payload size guarding.
+ *
+ * Used by `flyAgentDraggable` at `dragstart` (Phase 2) and by app pre-flight code that
+ * wants a clean payload before constructing the directive input. No Angular DI, no
+ * runtime side effects — safe to import from anywhere.
+ *
+ * Performance notes:
+ *   - The `TextEncoder` is lazily allocated and cached. The constructor runs once per
+ *     module instance even under federation (singleton DS).
+ *   - String trimming uses `Intl.Segmenter` when available (all evergreen browsers
+ *     including Safari 14.1+) so we cut on grapheme boundaries — emoji ZWJ sequences,
+ *     combining marks, regional indicator pairs all stay intact. Fallback is
+ *     UTF-16 code-unit slice, which is a graceful degradation: it can split a
+ *     surrogate pair, but the resulting JSON is still syntactically valid and
+ *     downstream renderers handle the replacement char.
+ */
+/**
+ * Thrown by {@link trimAgentPayload} when even a fully string-trimmed envelope still
+ * exceeds `maxJsonBytes` (e.g. an envelope with thousands of nested empty objects /
+ * array entries / property keys). Subclasses `RangeError` so callers using the standard
+ * `instanceof RangeError` check still match, while exposing the structured fields
+ * (`actualBytes`, `limitBytes`, `reason: 'json_too_large'`) needed for telemetry and
+ * symmetric handling with {@link AgentPayloadValidationResult} failures.
+ */
+declare class AgentPayloadOversizeError extends RangeError {
+    readonly actualBytes: number;
+    readonly limitBytes: number;
+    readonly reason: "json_too_large";
+    constructor(message: string, actualBytes: number, limitBytes: number);
+}
+/** UTF-8 byte length of `s`. Cheap; cached encoder. */
+declare function utf8ByteLength(s: string): number;
+/**
+ * Trim `input` so the UTF-8 byte length of the result is `<= maxBytes`. When trimming
+ * occurs, append `ellipsis` (default `…`, U+2026) — its bytes are included in the cap.
+ *
+ * Idempotent: `trimAgentString(trimAgentString(s, n), n)` equals `trimAgentString(s, n)`.
+ *
+ * Edge cases:
+ *   - `maxBytes` shorter than the ellipsis itself returns an empty string.
+ *   - `Intl.Segmenter` (when present) ensures we never split a grapheme cluster.
+ *   - When the encoded length is already within the cap, returns `input` unchanged.
+ */
+declare function trimAgentString(input: string, maxBytes: number, ellipsis?: string): string;
+/**
+ * Validate an {@link AgentDragPayload} against the supplied limits (or
+ * {@link DEFAULT_AGENT_PAYLOAD_LIMITS} when omitted). Returns `{ ok: true }` or a
+ * structured failure with the offending field path and byte counts.
+ *
+ * Order of checks (cheap → expensive):
+ *   1. `version` matches the frozen {@link AGENT_PAYLOAD_VERSION}.
+ *   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.
+ *
+ * The walker stops on the first oversize string field — the intent is to surface
+ * actionable feedback, not enumerate every offender.
+ */
+declare function validateAgentPayload(payload: AgentDragPayload<unknown>, limits?: Partial<AgentPayloadLimits>): AgentPayloadValidationResult;
+/**
+ * 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
+ * JSON cap. Idempotent — a second call against the trimmed result yields equal output.
+ *
+ * Throws {@link AgentPayloadOversizeError} only if even an empty trim couldn't shrink it
+ * under the cap (e.g. an envelope with 1000+ nested empty objects). The error subclasses
+ * `RangeError`, so legacy `instanceof RangeError` checks still match. Apps that hit this
+ * should re-shape `payload` rather than call again.
+ */
+declare function trimAgentPayload<T>(payload: AgentDragPayload<T>, limits?: Partial<AgentPayloadLimits>): AgentDragPayload<T>;
+
+/**
+ * Cross-cutting locale catalog — used by the dictation language picker today, and
+ * reusable for any future feature that needs a "pick a recognition / translation /
+ * synthesis language" UI (independent of the shell UI locale).
+ *
+ * Keep this shape aligned with `Fly.Shared.Core`'s `LanguageDTO` so backend lookups
+ * stay one-to-one. Translations of feature-specific strings (`detected`, `searching`,
+ * `elevating`, `translating`, `generatingAnswersForYou`, `learnMore`,
+ * `waitingForResponseMsg`) are carried verbatim from the canonical list — they are NOT
+ * used by the agent input today but are preserved so we don't fork the data when the
+ * translation feature ships.
+ *
+ * Kept in a separate module from {@link FLY_LOCALE_CATALOG} so consumers can
+ * `import type { FlyLocaleEntry } from '@mohamedatia/fly-design-system'` without
+ * pulling in the 31-row data table (tree-shaking when only the type is needed).
+ */
+interface FlyLocaleEntry {
+    /** Two-letter UPPERCASE prefix, e.g. `AR`. Display-friendly badge text. */
+    readonly prefix: string;
+    /** BCP-47 / dialect tag, e.g. `ar-AE`. Use this for `SpeechRecognition.lang`. */
+    readonly dialect: string;
+    readonly englishName: string;
+    readonly arabicName: string;
+    readonly nativeName: string;
+    readonly detected: string;
+    readonly searching: string;
+    readonly elevating: string;
+    readonly translating: string;
+    readonly generatingAnswersForYou: string;
+    readonly learnMore: string;
+    readonly waitingForResponseMsg: string;
+    /** True for `he-IL`, `ur-IN`, `ar-AE`. Used to set `dir` on the dictation chip / interim text. */
+    readonly isRtl: boolean;
+}
+
+/**
+ * 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`,
+ * `ar-AE`. Includes `cmn-Hant-TW` for Chinese and `ka-GE` for Georgian.
+ *
+ * The order matches the C# source byte-for-byte — do not re-sort. Downstream tests
+ * (`fly-locale-catalog.spec.ts`) pin the count, the unique-key constraints, and the
+ * RTL set; if you reorder or add an entry, those tests will guide the fix.
+ *
+ * The strings carry Cyrillic, Hebrew, Vietnamese, Thai, Indonesian, Bengali, Devanagari,
+ * Urdu, Catalan, Polish, Korean, Russian, Japanese, Han, Turkish, Romanian, Norwegian,
+ * Hungarian, Greek, Finnish, Danish, Dutch, Swedish, Portuguese, Italian, German,
+ * Spanish, French, English, Arabic, and Georgian. The file is saved as UTF-8 without
+ * BOM (matches every other locale file in the repo). The `…` (U+2026) ellipsis is
+ * preserved verbatim.
+ */
+declare const FLY_LOCALE_CATALOG: readonly FlyLocaleEntry[];
+/**
+ * Lookup by BCP-47 dialect (e.g. `'ar-AE'`). Case-insensitive per BCP-47 §2.1.1
+ * (subtags are case-insensitive on the wire) — accepts `'en-US'`, `'en-us'`,
+ * `'EN-US'`, etc. all as the canonical EN entry. The catalog itself keeps its
+ * canonical casing for display.
+ *
+ * Returns `undefined` when not found; callers decide whether to fall back to `'en-US'`.
+ */
+declare function findLocaleByDialect(dialect: string): FlyLocaleEntry | undefined;
+/**
+ * Lookup by short prefix (e.g. `'AR'`). Prefixes are unique in the catalog (asserted by tests).
+ * Case-insensitive — accepts `'AR'`, `'ar'`, `'Ar'`. Catalog stores prefixes uppercase
+ * for display.
+ */
+declare function findLocaleByPrefix(prefix: string): FlyLocaleEntry | undefined;
+/**
+ * Type-narrowing helper for entries flagged RTL.
+ *
+ * Named with the `Entry` suffix to avoid colliding with the existing
+ * `isRtlLocale(lang: string)` from `i18n.service.ts`, which answers a different
+ * question (is the *UI* locale code RTL?). Both helpers coexist in `public-api`.
+ */
+declare function isRtlLocaleEntry(entry: FlyLocaleEntry): entry is FlyLocaleEntry & {
+    isRtl: true;
+};
+
 /**
  * Stable error codes returned by audience-aware backend endpoints. Mirror of
  * `Fly.Shared.Core.Audience.AudienceErrorCodes`. Compare on these strings, not on HTTP
@@ -1234,6 +1857,6 @@ declare const AUDIENCE_ERROR_CODES: {
 };
 type AudienceErrorCode = (typeof AUDIENCE_ERROR_CODES)[keyof typeof AUDIENCE_ERROR_CODES];
 
-export { AUDIENCE_ERROR_CODES, AUDIENCE_LIMITS, AUDIENCE_PRESETS, AUDIENCE_TERM_KINDS, AudienceBuilderComponent, AuthService, ContextMenuComponent, DEFAULT_FLY_THEME_MODE, DialogResult, FLY_THEME_MODE_IDS, FlyBlockUiComponent, FlyFileUploadComponent, FlyImageUploadComponent, FlyThemeService, 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, StandaloneWindowManagerService, TranslatePipe, WINDOW_DATA, WindowManagerService, isRtlLocale, normalizeFlyTheme };
-export type { AppEveryonePrincipal, AppEveryoneTerm, AudienceEditTarget, AudienceErrorCode, AudienceFilter, AudienceOptions, AudiencePresetKind, AudienceTerm, AudienceTermKind, ChartTerm, ChildWindowData, ContextMenuItem, ContextMenuSection, DesktopApp, DesktopAppKind, FlyFileInfo, FlyThemeMode, LaunchContext, LoadBundleOptions, MessageBoxButton, MessageBoxOptions, 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, 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, FLY_LOCALE_CATALOG, FLY_THEME_MODE_IDS, FlyAgentDraggableDirective, FlyBlockUiComponent, FlyFileUploadComponent, FlyImageUploadComponent, FlyRemoteRouter, FlyThemeService, 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, StandaloneWindowManagerService, TranslatePipe, WINDOW_DATA, WindowManagerService, findLocaleByDialect, findLocaleByPrefix, isRtlLocale, isRtlLocaleEntry, normalizeFlyTheme, trimAgentPayload, trimAgentString, utf8ByteLength, validateAgentPayload };
+export type { AgentChipHostInputs, AgentCommand, AgentCommandHandle, AgentCommandRegistration, AgentCommandScope, AgentDragPayload, AgentDraggableItem, AgentDropChipMode, AgentDropRendererRegistration, AgentPayloadLimits, AgentPayloadValidationResult, AppEveryonePrincipal, AppEveryoneTerm, AudienceEditTarget, AudienceErrorCode, AudienceFilter, AudienceOptions, AudiencePresetKind, AudienceTerm, AudienceTermKind, ChartTerm, ChildWindowData, ContextMenuItem, ContextMenuSection, DesktopApp, DesktopAppKind, DialogResultWithAcknowledgement, FlyFileInfo, FlyLocaleEntry, FlyThemeMode, 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 };
 //# sourceMappingURL=mohamedatia-fly-design-system.d.ts.map