@mohamedatia/fly-design-system 2.13.0 → 2.15.0

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

@@ -2,6 +2,7 @@ import * as _angular_core from '@angular/core';
 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 { Editor } from '@tiptap/core';
 import { NavigationExtras } from '@angular/router';
 import * as _mohamedatia_fly_design_system from '@mohamedatia/fly-design-system';
 
@@ -123,6 +124,37 @@ declare const FLYOS_LAUNCH_EVENT = "flyos:launch";
 declare const FlyosPendingLaunchesGlobalKey: "__FLYOS_PENDING_LAUNCHES__";
 /** Type of the `globalThis[FlyosPendingLaunchesGlobalKey]` registry. */
 type FlyosPendingLaunches = Record<string, LaunchContext>;
+/**
+ * Detail payload of the <c>flyos:remote-route</c> window CustomEvent — the
+ * INVERSE of {@link FLYOS_LAUNCH_EVENT}. A federated remote dispatches this
+ * whenever its OWN logical route changes (user navigation inside the remote), so
+ * the shell — the single owner of the browser address bar and history — can
+ * mirror the route to `…/desktop?app=&route=` and push one history entry.
+ *
+ * Emitted by `FlyRemoteRouter` ONLY when {@link FlyosShellOwnsHistoryGlobalKey}
+ * is set (a new shell is present and listening). Older shells receive no event
+ * and the remote keeps writing its own `pushState` — so this is backward
+ * compatible.
+ */
+interface FlyRemoteRouteEventDetail {
+    /** The shell-registry app id (from `WINDOW_DATA`). */
+    readonly appId: string;
+    /** The window instance id, or null when `WINDOW_DATA` is split across bundles. */
+    readonly windowId: string | null;
+    /** The remote's new logical URL, e.g. `/signals/abc`. */
+    readonly url: string;
+}
+/** Name of the window CustomEvent a remote dispatches when its route changes. */
+declare const FLYOS_REMOTE_ROUTE_EVENT = "flyos:remote-route";
+/**
+ * `globalThis` flag set by the shell when it owns the address bar + history for
+ * ALL windows (os-core AND remotes) via `ShellHistoryService`. When set, a
+ * remote's `FlyRemoteRouter` defers history to the shell (dispatching
+ * {@link FLYOS_REMOTE_ROUTE_EVENT} instead of calling `history.pushState`) and
+ * stops handling its own `popstate` (the shell replays routes via
+ * {@link FLYOS_LAUNCH_EVENT}). Absent ⇒ legacy self-managed behaviour.
+ */
+declare const FlyosShellOwnsHistoryGlobalKey: "__FLYOS_SHELL_OWNS_HISTORY__";
 /**
  * Hint published by an app to drive the window-titlebar help-button deeplink.
  *
@@ -860,8 +892,12 @@ interface LoadBundleOptions {
 /**
  * Shared I18nService for the shell and Business Apps.
  *
- * **Merge order** (later keys win): shell layer → remote bundles in registration order.
+ * **Merge order** (later keys win): DS baseline → shell layer → remote bundles
+ * in registration order.
  *
+ * - Baseline: {@link DS_BASELINE_LOCALES} — built-in strings for DS components
+ *   (markdown editor, entity lookup) so they render localized labels even in a
+ *   standalone consumer that never populated the shell layer. Always overridable.
  * - Shell: `setShellTranslations()` after loading `locale/{lang}.json` and API overrides.
  * - Remotes: `loadBundle()` per manifest `localeBaseUrl`.
  */
@@ -872,6 +908,9 @@ declare class I18nService {
     private readonly _bundleOrder;
     private readonly _locale;
     private readonly _version;
+    /** Built-in DS strings for the active locale (falls back to `en` for any
+     *  locale we don't ship). Lowest-priority layer — always overridable. */
+    private readonly _baseline;
     private readonly _merged;
     readonly locale: _angular_core.Signal<string>;
     readonly version: _angular_core.Signal<number>;
@@ -893,6 +932,27 @@ declare class I18nService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<I18nService>;
 }
 
+/**
+ * Baseline UI strings for design-system components (markdown editor, entity
+ * lookup, …) in the four platform locales (`en`, `ar`, `fr`, `ur`).
+ *
+ * These are registered as the **lowest-priority** layer of {@link I18nService}
+ * (below the shell layer and any remote bundle), so DS components render real,
+ * localized labels even in a **standalone** consumer — a Business App running
+ * outside the desktop shell that never called `setShellTranslations()` — which
+ * would otherwise see raw keys (`common.label.bold`) as the pipe's fallback.
+ *
+ * Precedence: any consumer-supplied key with the same name still wins, so this
+ * is a safe default that an integrator can override without coordination.
+ *
+ * Scope: only the keys the **shippable** DS components reference today
+ * (`common.*` toolbar/link labels + `agent.lookup.*`). When a new DS component
+ * starts using `| translate`, add its keys here so it stays self-sufficient.
+ * Values are copied verbatim from the shell's `public/locale/*.json` — keep
+ * them in sync if either side changes.
+ */
+declare const DS_BASELINE_LOCALES: Readonly<Record<string, Readonly<Record<string, string>>>>;
+
 /** Single source of truth for persisted / API theme strings. */
 declare const FLY_THEME_MODE_IDS: readonly ["light", "dark"];
 type FlyThemeMode = (typeof FLY_THEME_MODE_IDS)[number];
@@ -1144,6 +1204,14 @@ declare class FlyRemoteRouter {
      *      (a known Native Federation edge case).
      */
     readonly isEmbedded: boolean;
+    /**
+     * True when a new shell owns the browser address bar + history for every
+     * window (it set {@link FlyosShellOwnsHistoryGlobalKey}). In that mode this
+     * router defers history to the shell: it dispatches {@link FLYOS_REMOTE_ROUTE_EVENT}
+     * instead of `pushState`, and does not handle its own `popstate` (the shell
+     * replays routes via `FLYOS_LAUNCH_EVENT`). Absent ⇒ legacy self-managed mode.
+     */
+    private get shellOwnsHistory();
     private readonly _url;
     /**
      * Current logical URL of the remote — `/signals/abc` etc.
@@ -1707,899 +1775,1154 @@ declare class MockAuthService {
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<MockAuthService>;
 }
 
-interface ContextMenuItem {
-    id: string;
-    label: string;
-    icon: string;
-}
-interface ContextMenuSection {
-    label?: string;
-    items: ContextMenuItem[];
-}
-declare class ContextMenuComponent implements AfterViewInit, OnDestroy {
-    private menuEl?;
-    private readonly doc;
-    private readonly hostEl;
-    x: _angular_core.InputSignal<number>;
-    y: _angular_core.InputSignal<number>;
-    sections: _angular_core.InputSignal<ContextMenuSection[]>;
-    action: _angular_core.OutputEmitterRef<string>;
-    closed: _angular_core.OutputEmitterRef<void>;
-    private menuWidth;
-    private menuHeight;
-    private previouslyFocused;
-    clampedPos: _angular_core.Signal<{
-        left: number;
-        top: number;
-    }>;
-    ngAfterViewInit(): void;
-    ngOnDestroy(): void;
-    onAction(id: string): void;
-    onClickOutside(event: MouseEvent): void;
-    onEscape(): void;
-    onContextMenu(event: MouseEvent): void;
-    onKeydown(event: KeyboardEvent): void;
-    private close;
-    private getMenuItems;
-    private focusItem;
-    private restoreFocus;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ContextMenuComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ContextMenuComponent, "fly-context-menu", never, { "x": { "alias": "x"; "required": true; "isSignal": true; }; "y": { "alias": "y"; "required": true; "isSignal": true; }; "sections": { "alias": "sections"; "required": true; "isSignal": true; }; }, { "action": "action"; "closed": "closed"; }, never, never, true, never>;
-}
-
-declare enum MessageBoxButtons {
-    OK = 0,
-    OKCancel = 1,
-    YesNo = 2,
-    YesNoCancel = 3,
-    RetryCancel = 4,
-    AbortRetryIgnore = 5
-}
-declare enum MessageBoxIcon {
-    None = 0,
-    Information = 1,
-    Warning = 2,
-    Error = 3,
-    Question = 4
-}
-declare enum DialogResult {
-    None = 0,
-    OK = 1,
-    Cancel = 2,
-    Yes = 3,
-    No = 4,
-    Retry = 5,
-    Abort = 6,
-    Ignore = 7
-}
-interface MessageBoxOptions {
-    title: string;
-    message: string;
-    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.
+ * 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.
  */
-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;
+/** 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.
+ *
+ *   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
+ * 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;
+    /**
+     * Category B (PR3): when present, selecting this command invokes a
+     * manifest-declared app skill instead of sending the composed text as a plain
+     * message. The host dispatches a Twin message carrying
+     * `system_context.slash_command_key = slashCommand.key` plus resolved context.
+     * See {@link AgentCommandSlashSpec}.
+     */
+    readonly slashCommand?: AgentCommandSlashSpec;
 }
 /**
- * Options narrowed to those carrying a `dontAskAgain` config — the only shape
- * accepted by `showAcknowledged()`.
+ * A context binding that resolves one `system_context` value for a Category B
+ * command at dispatch. Pure data so it travels app-agnostically in the
+ * Controller's app federation metadata (no callbacks). Discriminated by `from`:
+ *
+ *  - `route`    — value from the owning app's current route param `path`. The
+ *                 shell cannot read a federated remote's internal route, so route
+ *                 bindings **degrade** in v1 (the skill asks for the missing id);
+ *                 resolved only once a remote→shell route channel exists.
+ *  - `lookup`   — the host opens the `/lookup` entity picker for `entity` and
+ *                 writes the picked id into `system_context[key]` (picker-during-
+ *                 dispatch is a v1 follow-up — degrades to "ask" until then).
+ *  - `constant` — a literal value written into `system_context[key]`.
  */
-interface MessageBoxOptionsWithAcknowledgement extends MessageBoxOptions {
-    dontAskAgain: MessageBoxDontAskAgainConfig;
+type AgentCommandContextBinding = {
+    readonly key: string;
+    readonly from: 'route';
+    readonly path: string;
+} | {
+    readonly key: string;
+    readonly from: 'lookup';
+    readonly entity: string;
+    readonly exclude?: readonly string[];
+    readonly promptKey?: string;
+} | {
+    readonly key: string;
+    readonly from: 'constant';
+    readonly value: string;
+};
+/**
+ * Category B slash-command dispatch metadata (PR3). Travels app-agnostically in
+ * the Controller's app federation metadata and is registered by the shell's
+ * `RemoteManifestService` (the same path that registers `/lookup` descriptors) —
+ * remotes do NOT self-register. When an {@link AgentCommand} carries this,
+ * selecting it dispatches a Twin message with `system_context.slash_command_key
+ * = key`, merged with the resolved `contextBindings`.
+ */
+interface AgentCommandSlashSpec {
+    /** Dispatched as `system_context.slash_command_key`; matches the agents-side
+     *  skill's `slash_command_key` (= its manifest_key). */
+    readonly key: string;
+    /** Reserved: a future confirm step before dispatch (manifest `requiresConfirmation`). */
+    readonly requiresConfirmation?: boolean;
+    /** Parameter sources resolved into `system_context` at dispatch. */
+    readonly contextBindings?: readonly AgentCommandContextBinding[];
 }
-interface MessageBoxButton {
-    label: string;
-    result: DialogResult;
-    variant?: 'primary' | 'danger' | 'default';
+/** What hosts pass to {@link AgentCommandRegistry.register}. Adds the scope to {@link AgentCommand}. */
+interface AgentCommandRegistration extends AgentCommand {
+    readonly scope: AgentCommandScope;
 }
-/** Shape returned by `showAcknowledged()` — pairs the dialog result with the checkbox state. */
-interface DialogResultWithAcknowledgement {
-    readonly result: DialogResult;
-    readonly dontAskAgain: boolean;
+/** Disposable handle returned by {@link AgentCommandRegistry.register}. Idempotent `dispose()`. */
+interface AgentCommandHandle {
+    dispose(): void;
 }
-declare class MessageBoxService {
-    private readonly i18n;
-    readonly visible: _angular_core.WritableSignal<boolean>;
-    readonly title: _angular_core.WritableSignal<string>;
-    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.
+/**
+ * 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 dontAskAgainChecked: _angular_core.WritableSignal<boolean>;
-    private resolver;
-    show(options: MessageBoxOptions): Promise<DialogResult>;
+    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;
     /**
-     * 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`.
+     * Optional response-item field whose value is a *row-level* app id — i.e. the
+     * app that owns this individual entity, distinct from the descriptor's
+     * {@link LookupDescriptor.appId} (which only names the app exposing the
+     * lookup endpoint). Help articles are the motivating case: every article is
+     * exposed by `help-center`, but each one was seeded by a *source* app's
+     * manifest (Circles, Trends, …). Surfacing that per-row appId lets the
+     * picker render a second source-app tag so the user can tell two
+     * similarly-titled rows from different source apps apart at a glance.
+     *
+     * Resolved through {@link LookupResult.appId} and the shell's app registry
+     * with the same fallback chain used for {@link LookupDescriptor.appId}.
      */
-    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>;
+    readonly appIdField?: 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;
 }
-
-declare class MessageBoxComponent implements AfterViewInit {
-    service: MessageBoxService;
-    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>;
+/**
+ * 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 {
     /**
-     * User-driven checkbox state, owned by the service and re-seeded on every
-     * `_open()` so reusing a constant options literal cannot leak prior state.
+     * 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 dontAskAgainChecked: _angular_core.WritableSignal<boolean>;
+    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;
     /**
-     * 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.
+     * Stable id of the app that exposes this lookup, e.g. `notes`, `calendar`,
+     * `circles`. The picker resolves it to the app's display name via the shell's
+     * app registry and renders an "exposed by …" badge so the user can see which
+     * app owns the entity they're browsing (helps disambiguate when two apps
+     * register a similar-sounding entity, e.g. both Tasks and Notes one day).
+     *
+     * Populated automatically by the shell's registration paths:
+     *   - `CORE_APP_LOOKUPS` stamps it per descriptor at hand-edit time.
+     *   - `RemoteManifestService` stamps it from the manifest entry's `id` so
+     *     federation remotes don't have to repeat the id in every descriptor.
+     *
+     * Falls back to {@link appBadgeKey} (a locale-resolved literal) when an
+     * entity has no first-class home in the shell's app registry — e.g. `user`,
+     * `app-agent`, `robot`. When neither is set the picker omits the badge.
      */
-    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;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MessageBoxComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MessageBoxComponent, "fly-message-box", never, {}, {}, never, never, true, never>;
+    readonly appId?: string;
+    /**
+     * Optional i18n key the picker uses for the "exposed by …" badge **when
+     * {@link appId} is absent or unknown to the shell's app registry**. Lets
+     * entities that don't map to a single app (Users, Robots, App Agents) still
+     * surface a meaningful badge instead of silently omitting it. The picker
+     * resolves the key via the shared i18n service so the badge follows the
+     * user's locale.
+     */
+    readonly appBadgeKey?: string;
+    /**
+     * Advisory MCP tool-key prefixes the agent should prefer when the user
+     * references this entity via `/lookup` (e.g. `['dashboard.reports']`). The
+     * shell folds these into the turn's `mcp_scope` so the Twin self-serves the
+     * owning app's tools — fetching and analysing the referenced entity itself —
+     * instead of defaulting to a specialist-Robot consult for "tell me more"
+     * style prompts. Same dot-namespaced prefix vocabulary as
+     * {@link AgentMcpScope.apis}. Omit for entities with no first-class MCP tool
+     * family (e.g. `user`, `robot`).
+     */
+    readonly mcpApis?: readonly string[];
+    /**
+     * Optional in-app deep-link route TEMPLATE for this entity's detail page,
+     * e.g. `'/signals/{id}'`. When present, the desktop shell turns an agent's
+     * inline reference to this entity — the `flyos:<appId>.<entity>/<id>`
+     * anchors the agents backend emits in chat answers — into a launchable
+     * link: the single `{id}` placeholder is substituted with the referenced
+     * entity's id (URL-encoded) and the owning {@link appId} is launched on
+     * that route via the shell launcher.
+     *
+     * Omit for entities with no standalone detail page — their references then
+     * render as plain text (graceful degrade; never a dead link). The owning
+     * app declares this once in its `lookups[]` manifest entry, so a remote
+     * becomes agent-deep-linkable without any shell or design-system change.
+     * Only `{id}` is substituted here — richer parameterisation rides the
+     * deep-link `params` channel, not this template.
+     */
+    readonly deepLinkRoute?: string;
+    /** How to fetch + map candidates. */
+    readonly search: LookupSearch;
 }
-
-/** Full-bleed loading overlay for window content (shell) or embedded hosts. */
-declare class FlyBlockUiComponent {
-    /** When false, the overlay is not rendered (host may use @if instead). */
-    active: _angular_core.InputSignal<boolean>;
-    /** i18n key for status text; empty uses `common.loading`. */
-    messageKey: _angular_core.InputSignal<string>;
-    readonly resolvedMessageKey: _angular_core.Signal<string>;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlyBlockUiComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FlyBlockUiComponent, "fly-block-ui", never, { "active": { "alias": "active"; "required": true; "isSignal": true; }; "messageKey": { "alias": "messageKey"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+/** What hosts pass to the lookup registry. Adds the scope to {@link LookupDescriptor}. */
+interface LookupRegistration extends LookupDescriptor {
+    /**
+     * Affinity hint, NOT a visibility gate.
+     *
+     * Unlike {@link AgentCommandScope} — where `{appId}` HIDES a command unless the
+     * app is live — lookup scope is a *priority hint*. Every registered lookup is
+     * always offered in `/lookup`; when the app named by `{appId}` is in the host's
+     * live app set, that lookup sorts to the **top** of the entity picker so the
+     * "what am I working on right now?" entities surface first. `'global'` lookups
+     * have no affinity and sort after app-affinity matches.
+     *
+     * Rationale: OS-core entities (note, calendar event, file) are always
+     * referenceable — there's no "open the app first" condition the way there is
+     * for federated remotes — so a visibility gate would just produce a confusing
+     * empty state. Affinity-as-sort preserves the "Circles is open → prefer
+     * scenarios/trends/signals" intuition without hiding the rest.
+     */
+    readonly scope: AgentCommandScope;
 }
-
-/**
- * Metadata returned by Files Manager after a successful upload or metadata query.
- * Mirrors the `FileMetadataDto` shape from `GET /api/files/{id}` and `POST /api/files/upload`.
- */
-interface FlyFileInfo {
-    id: string;
-    fileName: string;
-    contentType: string;
-    sizeBytes: number;
-    sourceApp: string;
-    sourceEntityType?: string;
-    sourceEntityId?: string;
-    uploadedByUserId?: string;
-    correlationId?: string;
-    isConfirmed: boolean;
-    version: number;
-    scanStatus: string;
-    createdAt: string;
-    folderId?: string;
-    hasErrors: boolean;
+/** 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;
+    /**
+     * Row-level source app id (e.g. `circles` for an article seeded by Circles'
+     * manifest). Populated when the descriptor sets {@link LookupSearch.appIdField}
+     * and the response item carries a non-empty value. The picker renders it as
+     * a second app tag alongside the descriptor-level badge so the user can see
+     * "this Help-Center article was contributed by Circles" without opening it.
+     */
+    readonly appId?: string;
+}
+/** Disposable handle returned by the lookup registry. Idempotent `dispose()`. */
+interface LookupHandle {
+    dispose(): void;
 }
-
 /**
- * Image upload component with built-in cropperjs cropping modal.
+ * The wire envelope used by both the drag/drop surface and the imperative
+ * {@link AgentActionBus}. Renderers narrow on `kind`; mismatches fall back to
+ * `plainTextFallback`.
  *
- * Usage:
- * ```html
- * <fly-image-upload
- *   [aspectRatio]="16/9"
- *   [currentImageId]="trend.coverImageId"
- *   sourceApp="circles"
- *   sourceEntityType="trend"
- *   (uploaded)="onImageUploaded($event)"
- *   (removed)="onImageRemoved()"
- * />
- * ```
- */
-declare class FlyImageUploadComponent {
-    private http;
-    private injector;
-    aspectRatio: _angular_core.InputSignal<number>;
-    maxSizeBytes: _angular_core.InputSignal<number>;
-    currentImageId: _angular_core.InputSignal<string | null>;
-    sourceApp: _angular_core.InputSignal<string>;
-    sourceEntityType: _angular_core.InputSignal<string | null>;
-    sourceEntityId: _angular_core.InputSignal<string | null>;
-    uploaded: _angular_core.OutputEmitterRef<FlyFileInfo>;
-    removed: _angular_core.OutputEmitterRef<void>;
-    uploading: _angular_core.WritableSignal<boolean>;
-    error: _angular_core.WritableSignal<string | null>;
-    showCropper: _angular_core.WritableSignal<boolean>;
-    rawImageUrl: _angular_core.WritableSignal<string>;
-    localBlob: _angular_core.WritableSignal<string | null>;
-    fileInput: _angular_core.Signal<ElementRef<HTMLInputElement> | undefined>;
-    cropImage: _angular_core.Signal<ElementRef<HTMLImageElement> | undefined>;
-    private cropper;
-    private selectedFile;
-    /** Resolved preview URL — uses blob for local uploads, fetches authenticated for existing images */
-    previewUrl: _angular_core.WritableSignal<string | null>;
-    constructor();
-    sizeHint: _angular_core.Signal<string>;
-    triggerFileInput(): void;
-    onDragOver(e: DragEvent): void;
-    onDrop(e: DragEvent): void;
-    onFileSelected(e: Event): void;
-    removeImage(): void;
-    cancelCrop(): void;
-    applyCrop(): void;
-    private processFile;
-    private initCropper;
-    private destroyCropper;
-    private uploadFile;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlyImageUploadComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FlyImageUploadComponent, "fly-image-upload", never, { "aspectRatio": { "alias": "aspectRatio"; "required": false; "isSignal": true; }; "maxSizeBytes": { "alias": "maxSizeBytes"; "required": false; "isSignal": true; }; "currentImageId": { "alias": "currentImageId"; "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; }; }, { "uploaded": "uploaded"; "removed": "removed"; }, never, never, true, never>;
-}
-
-interface UploadSlot {
-    file: File;
-    progress: number;
-    status: 'uploading' | 'done' | 'error';
-    info?: FlyFileInfo;
-    error?: string;
-}
-/**
- * Multi-file upload with drag-drop, progress, and validation.
+ * 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.
  *
- * Usage:
- * ```html
- * <fly-file-upload
- *   [maxFiles]="5"
- *   [maxFileSizeBytes]="5242880"
- *   accept=".pdf,.docx,.xlsx"
- *   [(files)]="trend.attachments"
- *   sourceApp="circles"
- *   sourceEntityType="trend"
- *   (filesChanged)="onAttachmentsChanged($event)"
- * />
- * ```
+ * 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}).
  */
-declare class FlyFileUploadComponent {
-    private http;
-    maxFiles: _angular_core.InputSignal<number>;
-    maxFileSizeBytes: _angular_core.InputSignal<number>;
-    accept: _angular_core.InputSignal<string>;
-    sourceApp: _angular_core.InputSignal<string>;
-    sourceEntityType: _angular_core.InputSignal<string | null>;
-    sourceEntityId: _angular_core.InputSignal<string | null>;
-    /** Optional: provide file IDs to auto-fetch metadata for pre-existing files (edit mode). */
-    existingFileIds: _angular_core.InputSignal<string[] | null>;
-    /** Two-way model for completed file metadata. */
-    files: _angular_core.ModelSignal<FlyFileInfo[]>;
-    filesChanged: _angular_core.OutputEmitterRef<FlyFileInfo[]>;
-    error: _angular_core.WritableSignal<string | null>;
-    dragging: _angular_core.WritableSignal<boolean>;
-    slots: _angular_core.WritableSignal<UploadSlot[]>;
-    /** Pre-existing files loaded from the entity (before any new uploads this session). */
-    existingFiles: _angular_core.WritableSignal<FlyFileInfo[]>;
-    fileInput: _angular_core.Signal<ElementRef<HTMLInputElement> | undefined>;
-    constructor();
-    allSlots: _angular_core.Signal<UploadSlot[]>;
-    canAddMore: _angular_core.Signal<boolean>;
-    limitHint: _angular_core.Signal<string>;
-    triggerFileInput(): void;
-    onDragOver(e: DragEvent): void;
-    onDragLeave(e: DragEvent): void;
-    onDrop(e: DragEvent): void;
-    onFilesSelected(e: Event): void;
-    removeSlot(slot: UploadSlot): void;
-    removeExisting(f: FlyFileInfo): void;
-    iconFor(slot: UploadSlot): string;
-    iconForInfo(f: FlyFileInfo): string;
-    formatFileSize(bytes: number): string;
-    private processFiles;
-    private uploadFile;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlyFileUploadComponent, never>;
-    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>;
+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. 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;
 }
-
 /**
- * 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.
+ * 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.
  */
-/** 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";
+type AgentMessageEnvelope<T = unknown> = AgentDragPayload<T>;
 /**
- * Frozen payload envelope version.
+ * Typed attachment discriminator for {@link AgentDragPayload.attachments}.
  *
- *   v1 — minimal drag payload: kind / appId / version / payload / plainTextFallback /
- *        suggestedCommandIds. Still used by the drag/drop surface.
+ *   - `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).
  *
- *   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.
+ * Every kind carries `label` — that's what shows on the chip face and what
+ * a11y trees announce.
  */
-declare const AGENT_PAYLOAD_VERSION: 2;
+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[];
+}
 /**
- * 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.
+ * Where a chip is being rendered. `inline` = inside the input chip tray (removable);
+ * `message` = embedded in a sent message bubble (not removable).
  */
-declare const SUPPORTED_AGENT_PAYLOAD_VERSIONS: readonly number[];
+type AgentDropChipMode = 'inline' | 'message';
 /**
- * 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.
+ * Public input shape for chip-renderer components. Components declare matching
+ * `input()` signals; the registry wires them via `NgComponentOutlet`.
  */
-type AgentCommandScope = 'global' | {
-    readonly appId: string;
-};
+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;
+}
 /**
- * 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.
+ * 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 AgentCommand {
-    /** Stable id, kebab-case. Becomes the slash text after `/`, e.g. `/analyze-trend`. */
+interface AgentDraggableItem<T = unknown> {
+    /** Stable id within its app. Used as a list key in the kbd menu. */
     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;
+    /** 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;
+    /** 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;
     /**
-     * Category B (PR3): when present, selecting this command invokes a
-     * manifest-declared app skill instead of sending the composed text as a plain
-     * message. The host dispatches a Twin message carrying
-     * `system_context.slash_command_key = slashCommand.key` plus resolved context.
-     * See {@link AgentCommandSlashSpec}.
+     * 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 slashCommand?: AgentCommandSlashSpec;
+    readonly maxDeepLinkRouteBytes: number;
 }
+declare const DEFAULT_AGENT_PAYLOAD_LIMITS: AgentPayloadLimits;
 /**
- * A context binding that resolves one `system_context` value for a Category B
- * command at dispatch. Pure data so it travels app-agnostically in the
- * Controller's app federation metadata (no callbacks). Discriminated by `from`:
- *
- *  - `route`    — value from the owning app's current route param `path`. The
- *                 shell cannot read a federated remote's internal route, so route
- *                 bindings **degrade** in v1 (the skill asks for the missing id);
- *                 resolved only once a remote→shell route channel exists.
- *  - `lookup`   — the host opens the `/lookup` entity picker for `entity` and
- *                 writes the picked id into `system_context[key]` (picker-during-
- *                 dispatch is a v1 follow-up — degrades to "ask" until then).
- *  - `constant` — a literal value written into `system_context[key]`.
- */
-type AgentCommandContextBinding = {
-    readonly key: string;
-    readonly from: 'route';
-    readonly path: string;
-} | {
-    readonly key: string;
-    readonly from: 'lookup';
-    readonly entity: string;
-    readonly exclude?: readonly string[];
-    readonly promptKey?: string;
+ * 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 key: string;
-    readonly from: 'constant';
-    readonly value: string;
+    readonly ok: false;
+    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;
+    readonly limitBytes?: number;
 };
+
 /**
- * Category B slash-command dispatch metadata (PR3). Travels app-agnostically in
- * the Controller's app federation metadata and is registered by the shell's
- * `RemoteManifestService` (the same path that registers `/lookup` descriptors) —
- * remotes do NOT self-register. When an {@link AgentCommand} carries this,
- * selecting it dispatches a Twin message with `system_context.slash_command_key
- * = key`, merged with the resolved `contextBindings`.
+ * Emitted by {@link EntityLookupComponent} when the user picks an entity that
+ * resolves to an in-app deep link — everything a consumer needs to insert a
+ * clickable `flyos:` link into an editor or message, without touching the
+ * lookup registry itself.
  */
-interface AgentCommandSlashSpec {
-    /** Dispatched as `system_context.slash_command_key`; matches the agents-side
-     *  skill's `slash_command_key` (= its manifest_key). */
-    readonly key: string;
-    /** Reserved: a future confirm step before dispatch (manifest `requiresConfirmation`). */
-    readonly requiresConfirmation?: boolean;
-    /** Parameter sources resolved into `system_context` at dispatch. */
-    readonly contextBindings?: readonly AgentCommandContextBinding[];
-}
-/** What hosts pass to {@link AgentCommandRegistry.register}. Adds the scope to {@link AgentCommand}. */
-interface AgentCommandRegistration extends AgentCommand {
-    readonly scope: AgentCommandScope;
+interface EntityLinkSelection {
+    /** The entity's display title — the link's visible text. */
+    readonly label: string;
+    /** Dotted `<appId>.<entity>` kind token (the `flyos:` host segment). */
+    readonly kind: string;
+    /** The entity id. */
+    readonly id: string;
+    /** Owning app id. */
+    readonly appId: string;
+    /** Resolved in-app route, e.g. `/trends/<id>`. */
+    readonly route: string;
+    /** Full `flyos:<appId>.<entity>/<id>` deep-link href. */
+    readonly href: string;
 }
-/** Disposable handle returned by {@link AgentCommandRegistry.register}. Idempotent `dispose()`. */
-interface AgentCommandHandle {
-    dispose(): void;
+
+/**
+ * Shared floating entity typeahead — the `/lookup` picker promoted out of the
+ * agent composer into the design-system so any app (agent composer, notes,
+ * task comments, federated remotes) can let a user find an entity and act on
+ * it. Editor-agnostic: it emits a {@link LookupResult} ({@link pick}) and,
+ * when the entity resolves to a deep link, an {@link EntityLinkSelection}
+ * ({@link entityLinkSelected}) — the consumer decides whether to make a ref
+ * chip, insert a `flyos:` link into an editor, etc.
+ *
+ * Two-stage cascade:
+ *   - **Stage 1 — entity**: a filterable autocomplete of the offered entities.
+ *     Skipped when there's one entity or `initialEntity` already names one.
+ *   - **Stage 2 — search**: a debounced typeahead against the chosen entity's
+ *     search endpoint, with a breadcrumb back to stage 1.
+ *
+ * The HTTP call goes through the host's `HttpClient` so the gateway routing +
+ * auth interceptor apply — the same path the MCP `*_list_brief` tools wrap,
+ * but user-authenticated. The "exposed by app" badge resolves names via the
+ * optional {@link LOOKUP_APP_NAME_RESOLVER} the host provides (the DS has no
+ * app registry); absent it, the badge falls back to `appBadgeKey`.
+ */
+declare class EntityLookupComponent implements OnInit, OnDestroy {
+    private readonly http;
+    private readonly i18n;
+    private readonly host;
+    private readonly lookupRegistry;
+    /** Host-provided appId → {id,name} adapter for the "exposed by app" badge.
+     *  The DS has no app registry; the shell (and remotes) provide APP_LOOKUP.
+     *  Optional — absent, the badge falls back to a descriptor's appBadgeKey. */
+    private readonly appLookup;
+    /** Entities the picker may search — already filtered to the live-app scope
+     *  by the caller. Empty renders a "nothing to look up" hint. */
+    readonly descriptors: _angular_core.InputSignal<readonly LookupDescriptor[]>;
+    /** Entity pre-selected (e.g. from `/lookup <entity>`). Ignored when it
+     *  doesn't match any descriptor (falls back to the first). */
+    readonly initialEntity: _angular_core.InputSignal<string | undefined>;
+    /** Query text pre-seeded (e.g. from `/lookup <entity> <query>`). */
+    readonly initialQuery: _angular_core.InputSignal<string>;
+    /** Per-instance listbox id so `aria-controls` / `aria-activedescendant`
+     *  resolve unambiguously when multiple panels mount. */
+    readonly listboxId: _angular_core.InputSignal<string>;
+    /** Open direction. `'up'` (default) suits a bottom-anchored composer (the
+     *  agent input); `'down'` suits a top-anchored toolbar button (notes / task
+     *  comments) — the panel then anchors to the host's positioned parent (the
+     *  button wrapper) and opens below it with a fixed width. */
+    readonly placement: _angular_core.InputSignal<"up" | "down" | "above">;
+    /** Raw pick — every consumer gets this (agent ref chips, etc.). */
+    readonly pick: _angular_core.OutputEmitterRef<LookupResult>;
+    /** Deep-link selection — emitted ONLY when the picked entity resolves to a
+     *  route via the lookup registry (so the consumer never gets a dead link).
+     *  Editors bind this to insert a `flyos:` anchor. */
+    readonly entityLinkSelected: _angular_core.OutputEmitterRef<EntityLinkSelection>;
+    readonly dismiss: _angular_core.OutputEmitterRef<void>;
+    /** Which cascade stage is active: pick an entity, then search within it. */
+    readonly stage: _angular_core.WritableSignal<"search" | "entity">;
+    /** entity key of the descriptor currently being searched. */
+    readonly activeEntity: _angular_core.WritableSignal<string | null>;
+    /** In stage 1 this filters the entity list; in stage 2 it's the search text. */
+    readonly query: _angular_core.WritableSignal<string>;
+    readonly results: _angular_core.WritableSignal<readonly LookupResult[]>;
+    readonly loading: _angular_core.WritableSignal<boolean>;
+    /** i18n key for an inline error (network / bad endpoint); null when clear. */
+    readonly errorKey: _angular_core.WritableSignal<string | null>;
+    readonly activeIndex: _angular_core.WritableSignal<number>;
+    /** Query stashed when no entity matched, so it can seed the search field the
+     *  moment the user picks an entity. One-shot. */
+    private _seedQuery;
+    /** The descriptor matching {@link activeEntity}, or null. */
+    readonly activeDescriptor: _angular_core.Signal<LookupDescriptor | null>;
+    /** Stage-1 entity options, narrowed by the typed filter. Touches
+     *  `i18n.version()` so a locale switch re-resolves the label match. */
+    readonly filteredEntities: _angular_core.Signal<readonly LookupDescriptor[]>;
+    /** Size of the list the keyboard currently navigates (entities vs results). */
+    readonly listSize: _angular_core.Signal<number>;
+    /** Show the breadcrumb / back affordance only when there's a real choice of
+     *  entity to step back to. */
+    readonly showBack: _angular_core.Signal<boolean>;
+    /** Placeholder reflects the active stage. */
+    readonly searchPlaceholderKey: _angular_core.Signal<string>;
+    private _debounceTimer;
+    private _searchSub;
+    private readonly searchEl?;
+    constructor();
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    optionId(index: number): string;
+    readonly activeDescendant: _angular_core.Signal<string>;
+    private _clampedIndex;
+    onQueryInput(value: string): void;
+    onSelectEntity(entity: string): void;
+    goBackToEntity(): void;
+    onRowClick(row: LookupResult): void;
+    onRowHover(index: number): void;
+    /**
+     * Single pick exit. Emits the raw {@link pick} for every consumer, AND —
+     * when the entity resolves to a deep-link route via the registry — an
+     * {@link entityLinkSelected} carrying the `flyos:` href. Resolution failures
+     * (unknown entity / app mismatch / owning app not installed / no
+     * `deepLinkRoute`) simply omit the deep-link event: editor consumers get
+     * nothing to insert rather than a dead link, while the raw `pick` path
+     * (agent ref chips) still fires.
+     */
+    private _selectRow;
+    onKeydown(ev: KeyboardEvent): void;
+    onDocumentMouseDown(ev: MouseEvent): void;
+    onDocumentEscape(): void;
+    private _scheduleSearch;
+    private _clearTimer;
+    private _runSearch;
+    private _mapResults;
+    private _extractArray;
+    private _focusSearch;
+    entityLabel(desc: LookupDescriptor): string;
+    readonly activeEntityLabel: _angular_core.Signal<string>;
+    /**
+     * Display name of the app exposing this descriptor, for the "exposed by …"
+     * badge. Resolution order: host-provided {@link LOOKUP_APP_NAME_RESOLVER}
+     * (keyed by `descriptor.appId`) → descriptor `appBadgeKey` (literal i18n
+     * key, for entities not mapped to a single shell app) → '' (no badge).
+     */
+    appLabel(desc: LookupDescriptor): string;
+    readonly activeAppLabel: _angular_core.Signal<string>;
+    /** Per-row source-app label for stage-2 rows. Resolves {@link LookupResult.appId}
+     *  through the host resolver. '' when the row carries no `appId`, the resolver
+     *  is absent / doesn't know it, or it duplicates {@link activeAppLabel}. */
+    rowAppLabel(row: LookupResult): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<EntityLookupComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<EntityLookupComponent, "fly-entity-lookup", never, { "descriptors": { "alias": "descriptors"; "required": true; "isSignal": true; }; "initialEntity": { "alias": "initialEntity"; "required": false; "isSignal": true; }; "initialQuery": { "alias": "initialQuery"; "required": false; "isSignal": true; }; "listboxId": { "alias": "listboxId"; "required": false; "isSignal": true; }; "placement": { "alias": "placement"; "required": false; "isSignal": true; }; }, { "pick": "pick"; "entityLinkSelected": "entityLinkSelected"; "dismiss": "dismiss"; }, never, never, true, never>;
 }
+
 /**
- * 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).
+ * Host-provided handler that navigates to a resolved in-app entity deep link
+ * when the user clicks a `flyos:` anchor inside a {@link FlyMarkdownEditorComponent}.
  *
- * 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.
+ * The design-system can RESOLVE a `flyos:<appId>.<entity>/<id>` href to a
+ * `{ appId, route }` (via `AgentLookupRegistry`), but it cannot LAUNCH it — the
+ * launcher lives in the host (the desktop shell's `ShellLauncherService`, or a
+ * remote's own router). The host provides this token; when absent, a `flyos:`
+ * click is a no-op (the link is non-routable in a bare browser anyway).
  */
-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;
-    /**
-     * Optional response-item field whose value is a *row-level* app id — i.e. the
-     * app that owns this individual entity, distinct from the descriptor's
-     * {@link LookupDescriptor.appId} (which only names the app exposing the
-     * lookup endpoint). Help articles are the motivating case: every article is
-     * exposed by `help-center`, but each one was seeded by a *source* app's
-     * manifest (Circles, Trends, …). Surfacing that per-row appId lets the
-     * picker render a second source-app tag so the user can tell two
-     * similarly-titled rows from different source apps apart at a glance.
-     *
-     * Resolved through {@link LookupResult.appId} and the shell's app registry
-     * with the same fallback chain used for {@link LookupDescriptor.appId}.
-     */
-    readonly appIdField?: 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;
-}
+type EntityLinkLauncher = (target: {
+    readonly appId: string;
+    readonly route: string;
+    readonly kind: string;
+    readonly id: string;
+}) => void;
+declare const ENTITY_LINK_LAUNCHER: InjectionToken<EntityLinkLauncher>;
 /**
- * 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.
+ * A toolbar control id, or `'|'` for a visual divider. `toolbar` accepts a
+ * preset name or an explicit ordered list of these.
  */
-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;
-    /**
-     * Stable id of the app that exposes this lookup, e.g. `notes`, `calendar`,
-     * `circles`. The picker resolves it to the app's display name via the shell's
-     * app registry and renders an "exposed by …" badge so the user can see which
-     * app owns the entity they're browsing (helps disambiguate when two apps
-     * register a similar-sounding entity, e.g. both Tasks and Notes one day).
-     *
-     * Populated automatically by the shell's registration paths:
-     *   - `CORE_APP_LOOKUPS` stamps it per descriptor at hand-edit time.
-     *   - `RemoteManifestService` stamps it from the manifest entry's `id` so
-     *     federation remotes don't have to repeat the id in every descriptor.
-     *
-     * Falls back to {@link appBadgeKey} (a locale-resolved literal) when an
-     * entity has no first-class home in the shell's app registry — e.g. `user`,
-     * `app-agent`, `robot`. When neither is set the picker omits the badge.
-     */
-    readonly appId?: string;
-    /**
-     * Optional i18n key the picker uses for the "exposed by …" badge **when
-     * {@link appId} is absent or unknown to the shell's app registry**. Lets
-     * entities that don't map to a single app (Users, Robots, App Agents) still
-     * surface a meaningful badge instead of silently omitting it. The picker
-     * resolves the key via the shared i18n service so the badge follows the
-     * user's locale.
-     */
-    readonly appBadgeKey?: string;
-    /**
-     * Advisory MCP tool-key prefixes the agent should prefer when the user
-     * references this entity via `/lookup` (e.g. `['dashboard.reports']`). The
-     * shell folds these into the turn's `mcp_scope` so the Twin self-serves the
-     * owning app's tools — fetching and analysing the referenced entity itself —
-     * instead of defaulting to a specialist-Robot consult for "tell me more"
-     * style prompts. Same dot-namespaced prefix vocabulary as
-     * {@link AgentMcpScope.apis}. Omit for entities with no first-class MCP tool
-     * family (e.g. `user`, `robot`).
-     */
-    readonly mcpApis?: readonly string[];
-    /**
-     * Optional in-app deep-link route TEMPLATE for this entity's detail page,
-     * e.g. `'/signals/{id}'`. When present, the desktop shell turns an agent's
-     * inline reference to this entity — the `flyos:<appId>.<entity>/<id>`
-     * anchors the agents backend emits in chat answers — into a launchable
-     * link: the single `{id}` placeholder is substituted with the referenced
-     * entity's id (URL-encoded) and the owning {@link appId} is launched on
-     * that route via the shell launcher.
-     *
-     * Omit for entities with no standalone detail page — their references then
-     * render as plain text (graceful degrade; never a dead link). The owning
-     * app declares this once in its `lookups[]` manifest entry, so a remote
-     * becomes agent-deep-linkable without any shell or design-system change.
-     * Only `{id}` is substituted here — richer parameterisation rides the
-     * deep-link `params` channel, not this template.
-     */
-    readonly deepLinkRoute?: string;
-    /** How to fetch + map candidates. */
-    readonly search: LookupSearch;
+type MarkdownToolbarItem = 'undo' | 'redo' | 'h1' | 'h2' | 'h3' | 'bold' | 'italic' | 'underline' | 'strike' | 'code' | 'bulletList' | 'orderedList' | 'taskList' | 'blockquote' | 'codeBlock' | 'horizontalRule' | 'link' | 'entityLink' | '|';
+/** Named toolbar presets. `full` ≈ the notes editor; `compact` ≈ task comments. */
+type MarkdownToolbarPreset = 'full' | 'compact';
+declare const MARKDOWN_TOOLBAR_PRESETS: Record<MarkdownToolbarPreset, readonly MarkdownToolbarItem[]>;
+
+/**
+ * Shared rich-text/markdown editor — the single Tiptap-backed editor for FlyOS
+ * apps (notes, task comments, admin) and Business Apps (Circles). Emits a
+ * Markdown string via `ControlValueAccessor`, so it slots into reactive forms
+ * or `[(ngModel)]` with no orchestration.
+ *
+ * Bakes in the platform's `flyos:` entity-deep-link contract: the Link mark
+ * whitelists the `flyos` scheme (so authored/pasted deep links aren't blanked),
+ * clicks on a resolvable `flyos:` anchor launch the owning app via the
+ * host-provided {@link ENTITY_LINK_LAUNCHER}, and the optional "entity link"
+ * toolbar button opens the shared {@link EntityLookupComponent} to insert one.
+ */
+declare class FlyMarkdownEditorComponent implements ControlValueAccessor, OnDestroy {
+    private readonly cdr;
+    private readonly lookupRegistry;
+    private readonly launcher;
+    /** Toolbar preset name or an explicit ordered item list. */
+    readonly toolbar: _angular_core.InputSignal<MarkdownToolbarPreset | readonly MarkdownToolbarItem[]>;
+    /** Show the "insert in-app link" (entity-lookup) toolbar button. */
+    readonly enableEntityLink: _angular_core.InputSignal<boolean>;
+    /** Direction the entity-lookup dropdown opens. `down` (default) suits a
+     *  top toolbar (notes); `above` suits a bottom-anchored composer (task
+     *  comments) so the panel doesn't run off the viewport. */
+    readonly entityLinkPlacement: _angular_core.InputSignal<"down" | "above">;
+    readonly placeholder: _angular_core.InputSignal<string>;
+    readonly readonly: _angular_core.InputSignal<boolean>;
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    /** Fired on Ctrl/Cmd+Enter (host can submit a comment, etc.). */
+    readonly submitShortcut: _angular_core.OutputEmitterRef<void>;
+    private onChange;
+    private onTouched;
+    private currentValue;
+    readonly activeStates: _angular_core.WritableSignal<Record<string, boolean>>;
+    readonly canUndo: _angular_core.WritableSignal<boolean>;
+    readonly canRedo: _angular_core.WritableSignal<boolean>;
+    readonly showLinkPopover: _angular_core.WritableSignal<boolean>;
+    readonly linkInputValue: _angular_core.WritableSignal<string>;
+    readonly showEntityLookup: _angular_core.WritableSignal<boolean>;
+    readonly entityLookupDescriptors: _angular_core.Signal<readonly LookupDescriptor[]>;
+    /** Resolved toolbar items (preset → array), entityLink stripped when disabled. */
+    readonly toolbarItems: _angular_core.Signal<readonly MarkdownToolbarItem[]>;
+    readonly editor: Editor;
+    constructor();
+    ngOnDestroy(): void;
+    writeValue(value: string | null): void;
+    registerOnChange(fn: (v: string) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    /** Current markdown (same as the CVA value). */
+    getMarkdown(): string;
+    /** Current rendered HTML snapshot. */
+    getHtml(): string;
+    /** Focus the editor surface. */
+    focus(): void;
+    button(id: MarkdownToolbarItem): {
+        icon: string;
+        labelKey: string;
+    } | null;
+    /** Short visual label for buttons rendered as text (B / I / U / S / H1…). */
+    textLabel(id: MarkdownToolbarItem): string | null;
+    run(id: MarkdownToolbarItem): void;
+    isActive(id: MarkdownToolbarItem): boolean;
+    disabled(id: MarkdownToolbarItem): boolean;
+    private refreshState;
+    openLinkPopover(): void;
+    onLinkInput(value: string): void;
+    commitLink(): void;
+    cancelLink(): void;
+    onLinkKeydown(event: KeyboardEvent): void;
+    toggleEntityLookup(): void;
+    closeEntityLookup(): void;
+    onEntityLinkSelected(sel: EntityLinkSelection): void;
+    /** True (click handled) when a resolvable `flyos:` anchor was launched. */
+    private handleFlyosClick;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlyMarkdownEditorComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FlyMarkdownEditorComponent, "fly-markdown-editor", never, { "toolbar": { "alias": "toolbar"; "required": false; "isSignal": true; }; "enableEntityLink": { "alias": "enableEntityLink"; "required": false; "isSignal": true; }; "entityLinkPlacement": { "alias": "entityLinkPlacement"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "submitShortcut": "submitShortcut"; }, never, never, true, never>;
 }
-/** What hosts pass to the lookup registry. Adds the scope to {@link LookupDescriptor}. */
-interface LookupRegistration extends LookupDescriptor {
-    /**
-     * Affinity hint, NOT a visibility gate.
-     *
-     * Unlike {@link AgentCommandScope} — where `{appId}` HIDES a command unless the
-     * app is live — lookup scope is a *priority hint*. Every registered lookup is
-     * always offered in `/lookup`; when the app named by `{appId}` is in the host's
-     * live app set, that lookup sorts to the **top** of the entity picker so the
-     * "what am I working on right now?" entities surface first. `'global'` lookups
-     * have no affinity and sort after app-affinity matches.
-     *
-     * Rationale: OS-core entities (note, calendar event, file) are always
-     * referenceable — there's no "open the app first" condition the way there is
-     * for federated remotes — so a visibility gate would just produce a confusing
-     * empty state. Affinity-as-sort preserves the "Circles is open → prefer
-     * scenarios/trends/signals" intuition without hiding the rest.
-     */
-    readonly scope: AgentCommandScope;
+
+interface ContextMenuItem {
+    id: string;
+    label: string;
+    icon: string;
+}
+interface ContextMenuSection {
+    label?: string;
+    items: ContextMenuItem[];
+}
+declare class ContextMenuComponent implements AfterViewInit, OnDestroy {
+    private menuEl?;
+    private readonly doc;
+    private readonly hostEl;
+    x: _angular_core.InputSignal<number>;
+    y: _angular_core.InputSignal<number>;
+    sections: _angular_core.InputSignal<ContextMenuSection[]>;
+    action: _angular_core.OutputEmitterRef<string>;
+    closed: _angular_core.OutputEmitterRef<void>;
+    private menuWidth;
+    private menuHeight;
+    private previouslyFocused;
+    clampedPos: _angular_core.Signal<{
+        left: number;
+        top: number;
+    }>;
+    ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    onAction(id: string): void;
+    onClickOutside(event: MouseEvent): void;
+    onEscape(): void;
+    onContextMenu(event: MouseEvent): void;
+    onKeydown(event: KeyboardEvent): void;
+    private close;
+    private getMenuItems;
+    private focusItem;
+    private restoreFocus;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ContextMenuComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ContextMenuComponent, "fly-context-menu", never, { "x": { "alias": "x"; "required": true; "isSignal": true; }; "y": { "alias": "y"; "required": true; "isSignal": true; }; "sections": { "alias": "sections"; "required": true; "isSignal": true; }; }, { "action": "action"; "closed": "closed"; }, never, never, true, never>;
+}
+
+declare enum MessageBoxButtons {
+    OK = 0,
+    OKCancel = 1,
+    YesNo = 2,
+    YesNoCancel = 3,
+    RetryCancel = 4,
+    AbortRetryIgnore = 5
+}
+declare enum MessageBoxIcon {
+    None = 0,
+    Information = 1,
+    Warning = 2,
+    Error = 3,
+    Question = 4
 }
-/** 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;
-    /**
-     * Row-level source app id (e.g. `circles` for an article seeded by Circles'
-     * manifest). Populated when the descriptor sets {@link LookupSearch.appIdField}
-     * and the response item carries a non-empty value. The picker renders it as
-     * a second app tag alongside the descriptor-level badge so the user can see
-     * "this Help-Center article was contributed by Circles" without opening it.
-     */
-    readonly appId?: string;
+declare enum DialogResult {
+    None = 0,
+    OK = 1,
+    Cancel = 2,
+    Yes = 3,
+    No = 4,
+    Retry = 5,
+    Abort = 6,
+    Ignore = 7
 }
-/** Disposable handle returned by the lookup registry. Idempotent `dispose()`. */
-interface LookupHandle {
-    dispose(): void;
+interface MessageBoxOptions {
+    title: string;
+    message: string;
+    buttons?: MessageBoxButtons;
+    icon?: MessageBoxIcon;
 }
 /**
- * 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}).
+ * 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 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. 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>>;
+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>;
+    readonly title: _angular_core.WritableSignal<string>;
+    readonly message: _angular_core.WritableSignal<string>;
+    readonly icon: _angular_core.WritableSignal<MessageBoxIcon>;
+    readonly buttons: _angular_core.WritableSignal<MessageBoxButton[]>;
     /**
-     * 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)
+     * 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 attachments?: readonly AgentEnvelopeAttachment[];
+    readonly dontAskAgain: _angular_core.WritableSignal<MessageBoxDontAskAgainConfig | undefined>;
     /**
-     * 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`.
+     * 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 mcpScope?: AgentMcpScope;
+    readonly dontAskAgainChecked: _angular_core.WritableSignal<boolean>;
+    private resolver;
+    show(options: MessageBoxOptions): Promise<DialogResult>;
     /**
-     * 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.
+     * 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`.
      */
-    readonly deepLinkRoute?: string;
+    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>;
 }
-/**
- * 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 {
+
+declare class MessageBoxComponent implements AfterViewInit {
+    service: MessageBoxService;
+    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>;
     /**
-     * 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.
+     * 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 apis: readonly string[];
+    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;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MessageBoxComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MessageBoxComponent, "fly-message-box", never, {}, {}, never, never, true, never>;
 }
+
+/** Full-bleed loading overlay for window content (shell) or embedded hosts. */
+declare class FlyBlockUiComponent {
+    /** When false, the overlay is not rendered (host may use @if instead). */
+    active: _angular_core.InputSignal<boolean>;
+    /** i18n key for status text; empty uses `common.loading`. */
+    messageKey: _angular_core.InputSignal<string>;
+    readonly resolvedMessageKey: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlyBlockUiComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FlyBlockUiComponent, "fly-block-ui", never, { "active": { "alias": "active"; "required": true; "isSignal": true; }; "messageKey": { "alias": "messageKey"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
 /**
- * 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`.
+ * Metadata returned by Files Manager after a successful upload or metadata query.
+ * Mirrors the `FileMetadataDto` shape from `GET /api/files/{id}` and `POST /api/files/upload`.
  */
-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;
+interface FlyFileInfo {
+    id: string;
+    fileName: string;
+    contentType: string;
+    sizeBytes: number;
+    sourceApp: string;
+    sourceEntityType?: string;
+    sourceEntityId?: string;
+    uploadedByUserId?: string;
+    correlationId?: string;
+    isConfirmed: boolean;
+    version: number;
+    scanStatus: string;
+    createdAt: string;
+    folderId?: string;
+    hasErrors: boolean;
 }
+
 /**
- * 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.
+ * Image upload component with built-in cropperjs cropping modal.
+ *
+ * Usage:
+ * ```html
+ * <fly-image-upload
+ *   [aspectRatio]="16/9"
+ *   [currentImageId]="trend.coverImageId"
+ *   sourceApp="circles"
+ *   sourceEntityType="trend"
+ *   (uploaded)="onImageUploaded($event)"
+ *   (removed)="onImageRemoved()"
+ * />
+ * ```
  */
-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>;
+declare class FlyImageUploadComponent {
+    private http;
+    private injector;
+    aspectRatio: _angular_core.InputSignal<number>;
+    maxSizeBytes: _angular_core.InputSignal<number>;
+    currentImageId: _angular_core.InputSignal<string | null>;
+    sourceApp: _angular_core.InputSignal<string>;
+    sourceEntityType: _angular_core.InputSignal<string | null>;
+    sourceEntityId: _angular_core.InputSignal<string | null>;
+    uploaded: _angular_core.OutputEmitterRef<FlyFileInfo>;
+    removed: _angular_core.OutputEmitterRef<void>;
+    uploading: _angular_core.WritableSignal<boolean>;
+    error: _angular_core.WritableSignal<string | null>;
+    showCropper: _angular_core.WritableSignal<boolean>;
+    rawImageUrl: _angular_core.WritableSignal<string>;
+    localBlob: _angular_core.WritableSignal<string | null>;
+    fileInput: _angular_core.Signal<ElementRef<HTMLInputElement> | undefined>;
+    cropImage: _angular_core.Signal<ElementRef<HTMLImageElement> | undefined>;
+    private cropper;
+    private selectedFile;
+    /** Resolved preview URL — uses blob for local uploads, fetches authenticated for existing images */
+    previewUrl: _angular_core.WritableSignal<string | null>;
+    constructor();
+    sizeHint: _angular_core.Signal<string>;
+    triggerFileInput(): void;
+    onDragOver(e: DragEvent): void;
+    onDrop(e: DragEvent): void;
+    onFileSelected(e: Event): void;
+    removeImage(): void;
+    cancelCrop(): void;
+    applyCrop(): void;
+    private processFile;
+    private initCropper;
+    private destroyCropper;
+    private uploadFile;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlyImageUploadComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FlyImageUploadComponent, "fly-image-upload", never, { "aspectRatio": { "alias": "aspectRatio"; "required": false; "isSignal": true; }; "maxSizeBytes": { "alias": "maxSizeBytes"; "required": false; "isSignal": true; }; "currentImageId": { "alias": "currentImageId"; "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; }; }, { "uploaded": "uploaded"; "removed": "removed"; }, never, never, true, never>;
 }
-/** 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>>;
+
+interface UploadSlot {
+    file: File;
+    progress: number;
+    status: 'uploading' | 'done' | 'error';
+    info?: FlyFileInfo;
+    error?: string;
 }
 /**
- * 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.
+ * Multi-file upload with drag-drop, progress, and validation.
+ *
+ * Usage:
+ * ```html
+ * <fly-file-upload
+ *   [maxFiles]="5"
+ *   [maxFileSizeBytes]="5242880"
+ *   accept=".pdf,.docx,.xlsx"
+ *   [(files)]="trend.attachments"
+ *   sourceApp="circles"
+ *   sourceEntityType="trend"
+ *   (filesChanged)="onAttachmentsChanged($event)"
+ * />
+ * ```
  */
-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;
-    /** 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 class FlyFileUploadComponent {
+    private http;
+    maxFiles: _angular_core.InputSignal<number>;
+    maxFileSizeBytes: _angular_core.InputSignal<number>;
+    accept: _angular_core.InputSignal<string>;
+    sourceApp: _angular_core.InputSignal<string>;
+    sourceEntityType: _angular_core.InputSignal<string | null>;
+    sourceEntityId: _angular_core.InputSignal<string | null>;
+    /** Optional: provide file IDs to auto-fetch metadata for pre-existing files (edit mode). */
+    existingFileIds: _angular_core.InputSignal<string[] | null>;
+    /** Two-way model for completed file metadata. */
+    files: _angular_core.ModelSignal<FlyFileInfo[]>;
+    filesChanged: _angular_core.OutputEmitterRef<FlyFileInfo[]>;
+    error: _angular_core.WritableSignal<string | null>;
+    dragging: _angular_core.WritableSignal<boolean>;
+    slots: _angular_core.WritableSignal<UploadSlot[]>;
+    /** Pre-existing files loaded from the entity (before any new uploads this session). */
+    existingFiles: _angular_core.WritableSignal<FlyFileInfo[]>;
+    fileInput: _angular_core.Signal<ElementRef<HTMLInputElement> | undefined>;
+    constructor();
+    allSlots: _angular_core.Signal<UploadSlot[]>;
+    canAddMore: _angular_core.Signal<boolean>;
+    limitHint: _angular_core.Signal<string>;
+    triggerFileInput(): void;
+    onDragOver(e: DragEvent): void;
+    onDragLeave(e: DragEvent): void;
+    onDrop(e: DragEvent): void;
+    onFilesSelected(e: Event): void;
+    removeSlot(slot: UploadSlot): void;
+    removeExisting(f: FlyFileInfo): void;
+    iconFor(slot: UploadSlot): string;
+    iconForInfo(f: FlyFileInfo): string;
+    formatFileSize(bytes: number): string;
+    private processFiles;
+    private uploadFile;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlyFileUploadComponent, never>;
+    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>;
 }
-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' | '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;
-    readonly limitBytes?: number;
-};
 
 /**
  * Singleton registry of slash commands offered by the agent input palette.
@@ -2722,6 +3045,24 @@ declare class AgentLookupRegistry {
         readonly appId: string;
         readonly route: string;
     } | null;
+    /**
+     * Resolve a deep-link target from a bare `(entity, id)` pair — the shape a
+     * `/lookup` ref carries (it has no `<appId>.<entity>` kind token; the owning
+     * app is implicit in the registered descriptor). `entity` is the registry's
+     * unique storage key, so it identifies the descriptor unambiguously without
+     * an app prefix.
+     *
+     * Returns `{ appId, route }` (the descriptor's {@link LookupDescriptor.appId}
+     * / affinity `scope.appId` as the owner, `{id}` substituted URL-encoded) when
+     * a matching descriptor carries a {@link LookupDescriptor.deepLinkRoute};
+     * `null` otherwise (unknown entity, no template, or the owning app has since
+     * unregistered) so callers render plain text rather than a dead link — the
+     * same graceful-degrade contract as {@link resolveDeepLink}.
+     */
+    resolveDeepLinkForEntity(entity: string, id: string): {
+        readonly appId: string;
+        readonly route: string;
+    } | null;
     /** Tear down by entity. Idempotent. */
     unregister(entity: string): void;
     /** Monotonic counter; identifies which registration call currently owns each entity. */
@@ -3268,6 +3609,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, 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_CONTEXT_EVENT, FLY_REMOTE_CONTEXT_STORE_KEY, FLY_REMOTE_ROUTES, FLY_THEME_MODE_IDS, FLY_WINDOW_HELP_HINT_EVENT, FlyAgentDraggableDirective, FlyBlockUiComponent, FlyFileUploadComponent, FlyImageUploadComponent, FlyRemoteContextService, 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, AgentCommandContextBinding, AgentCommandHandle, AgentCommandRegistration, AgentCommandScope, AgentCommandSlashSpec, 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, FlyRemoteContext, FlyRemoteMatch, FlyRemoteRoute, FlyThemeMode, FlyWindowHelpHintEventDetail, FlyWindowHelpPublisher, 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 };
+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, DS_BASELINE_LOCALES, DialogResult, ENTITY_LINK_LAUNCHER, EntityLookupComponent, FLYOS_LAUNCH_EVENT, FLYOS_REMOTE_ROUTE_EVENT, FLY_LOCALE_CATALOG, FLY_REMOTE_BASE_PATH, FLY_REMOTE_CONTEXT_EVENT, FLY_REMOTE_CONTEXT_STORE_KEY, FLY_REMOTE_ROUTES, FLY_THEME_MODE_IDS, FLY_WINDOW_HELP_HINT_EVENT, FlyAgentDraggableDirective, FlyBlockUiComponent, FlyFileUploadComponent, FlyImageUploadComponent, FlyMarkdownEditorComponent, FlyRemoteContextService, FlyRemoteRouter, FlyRemoteRouterOutletComponent, FlySecureSrcDirective, FlyThemeService, FlyWindowHelpService, FlyosPendingLaunchesGlobalKey, FlyosShellOwnsHistoryGlobalKey, I18nService, LAUNCH_CONTEXT, MARKDOWN_TOOLBAR_PRESETS, 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, AgentCommandContextBinding, AgentCommandHandle, AgentCommandRegistration, AgentCommandScope, AgentCommandSlashSpec, 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, EntityLinkLauncher, EntityLinkSelection, FlyFileInfo, FlyLaunchEventDetail, FlyLocaleEntry, FlyRemoteContext, FlyRemoteMatch, FlyRemoteRoute, FlyRemoteRouteEventDetail, FlyThemeMode, FlyWindowHelpHintEventDetail, FlyWindowHelpPublisher, FlyosPendingLaunches, LaunchContext, LoadBundleOptions, LookupDescriptor, LookupHandle, LookupRegistration, LookupResult, LookupSearch, MarkdownToolbarItem, MarkdownToolbarPreset, 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