@mohamedatia/fly-design-system 2.12.0 → 2.14.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';
 
@@ -860,8 +861,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 +877,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 +901,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];
@@ -1213,16 +1242,135 @@ declare class FlyRemoteRouter {
      * In embedded mode: push a real browser history entry (so back/forward work)
      * and update the internal signal synchronously.
      *
-     * The state object carries `flyRemoteUrl` so the popstate listener can
-     * restore the exact URL without relying on window.location.pathname (which
-     * could be the shell's route, not the remote's logical URL).
+     * The browser address bar is written as the shell's **canonical deep-link
+     * form** — `<shell-path>?app=<appId>&route=<remote-url>` — NOT the bare remote
+     * URL. This is what makes a hard reload work: on reload the shell's
+     * `DeepLinkService` captures `?app=&route=` in its APP_INITIALIZER, re-opens
+     * this app, and replays the route through the pending-launch pipeline
+     * (`ShellLauncherService.launch` → `FLYOS_LAUNCH_EVENT` / pending registry →
+     * the remote's root applies `ctx.route`). Writing the bare remote URL (e.g.
+     * `/trends/abc`) instead would leave a host-unroutable path in the bar — on
+     * reload the shell router falls through to its `**` wildcard, redirects to
+     * `/desktop`, and the deep link is silently lost. See
+     * skills/cross-app-deep-linking.md.
+     *
+     * `flyRemoteUrl` is still stashed in the history state so the popstate
+     * listener restores the exact remote URL for back/forward without re-parsing
+     * the query string.
      */
     private _pushEmbedded;
+    /**
+     * Build the browser-address-bar URL for an embedded navigation: the shell's
+     * current path plus the canonical `?app=&route=` deep-link query (the same
+     * contract `DeepLinkService.captureFromCurrentUrl` parses on cold load).
+     *
+     * The path is left untouched — only the query string carries the remote's
+     * logical route — so the shell's own Angular Router (anchored at e.g.
+     * `/desktop`) is never handed a path it cannot match.
+     *
+     * Fallback: when `appId` is unknown (WINDOW_DATA not injected — the Native
+     * Federation token-split case where only `__FLYOS_SHELL__` proves embedding)
+     * we cannot build a shareable link, so we return the shell path query-less.
+     * Back/forward still work via the `flyRemoteUrl` history state; only
+     * reload-restore is unavailable — no regression over leaving the bar as-is.
+     */
+    private _buildEmbeddedHistoryUrl;
     private buildUrl;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlyRemoteRouter, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<FlyRemoteRouter>;
 }
 
+/**
+ * A federated remote's current navigation context, as published to the shell.
+ *
+ * `params` are the remote's **resolved route params** (e.g. `{ id: 'abc' }` for a
+ * `trends/:id` match) — the remote owns its route table, so it resolves these and
+ * the shell never has to know the remote's route patterns.
+ */
+interface FlyRemoteContext {
+    /** Owning app id — matches the shell's app registry and `AgentCommandScope.appId`. */
+    readonly appId: string;
+    /** Logical remote URL, e.g. `/trends/abc`. Query/hash stripped by the publisher. */
+    readonly url: string;
+    /** `url` split into path segments, e.g. `['trends', 'abc']`. */
+    readonly segments: readonly string[];
+    /** Resolved route params, e.g. `{ id: 'abc' }`. Empty when no param route matched. */
+    readonly params: Readonly<Record<string, string>>;
+}
+/**
+ * Shared cross-bundle store key + sync event. **Public contract** — a remote that
+ * cannot consume a DS new enough to back {@link FlyRemoteContextService.publish} on
+ * `globalThis` itself may write this slot directly (same shape, keyed by appId) and
+ * dispatch {@link FLY_REMOTE_CONTEXT_EVENT} to notify the shell. Keep these literals
+ * stable; they are an integration boundary, not an implementation detail.
+ */
+declare const FLY_REMOTE_CONTEXT_STORE_KEY = "__flyRemoteContext__";
+declare const FLY_REMOTE_CONTEXT_EVENT = "fly:remote-context";
+/**
+ * Remote → shell route/context channel.
+ *
+ * Why this exists
+ * ---------------
+ * A federated remote (e.g. Circles) renders inside a desktop-shell window and
+ * keeps its own internal Angular route (`/trends/:id`). The shell cannot see that
+ * route: the remote provides {@link FlyRemoteRouter} at its **component** injector
+ * (so it can read per-window `WINDOW_DATA`), which makes the route state invisible
+ * to the host. Shell-side features that need "what is the user looking at right
+ * now" — most importantly Category-B slash commands whose `contextBindings` include
+ * a `lookup`/`route` entity id — had no way to resolve the current entity id, and
+ * degraded to "ask the user".
+ *
+ * The channel — why `globalThis`, not the DI singleton
+ * ----------------------------------------------------
+ * This service is `providedIn: 'root'`, but a root instance is **NOT** reliably
+ * shared across the federation boundary. The shell builds the design system from
+ * workspace SOURCE while remotes consume the PUBLISHED npm package; Native
+ * Federation only collapses those two physical builds into one runtime instance if
+ * version negotiation succeeds perfectly (matching advertised `mappingVersion`,
+ * `singleton`, compatible ranges). That negotiation has silently split before —
+ * giving the shell and a remote *separate* `providedIn:'root'` instances, so a
+ * value published on one was invisible to the other.
+ *
+ * `globalThis` is the one substrate guaranteed shared across every federated bundle
+ * in the same realm (there are no iframes), so the channel stores its state there
+ * (see {@link FLY_REMOTE_CONTEXT_STORE_KEY}). {@link context} / {@link param} read
+ * it directly — split-proof, synchronous, no injector-token gymnastics. A per-
+ * instance signal mirrors the store for reactive consumers and is re-synced from a
+ * `globalThis` event whenever any copy of the service (or a remote writing the slot
+ * directly) mutates it. The same pattern already backs the shell's app-launch
+ * context bridge, so this is an established boundary, not a new hack.
+ *
+ * Contract
+ * --------
+ * - Remote: call {@link publish} whenever its embedded route changes, and
+ *   {@link clear} on teardown (window close / component destroy).
+ * - Shell: call {@link context} (or {@link param}) for an app id to resolve bindings.
+ *
+ * Keyed by `appId` (last publisher wins) — a single live window per app is the v1
+ * assumption; a windowId key is the natural extension if multi-window-per-app
+ * dispatch is ever needed.
+ */
+declare class FlyRemoteContextService {
+    private readonly _byApp;
+    /** All currently-published contexts, keyed by app id. Reactive. */
+    readonly contexts: _angular_core.Signal<ReadonlyMap<string, FlyRemoteContext>>;
+    constructor();
+    /** Publish (or replace) the active route context for an app. */
+    publish(ctx: FlyRemoteContext): void;
+    /** Drop an app's context (remote unmounted / window closed). No-op if absent. */
+    clear(appId: string): void;
+    /** Current context for an app, or `null` when nothing is published. */
+    context(appId: string): FlyRemoteContext | null;
+    /**
+     * Resolve a single route param for an app, e.g. `param('circles', 'id')`.
+     * Returns `null` when the app has no published context or the param is absent —
+     * the caller then degrades (the skill asks for the missing id).
+     */
+    param(appId: string, path: string): string | null;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlyRemoteContextService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<FlyRemoteContextService>;
+}
+
 /**
  * Minimal adapter the shell (or any host) provides so design-system services can
  * look up apps without depending on `AppRegistryService` directly. Keeps the
@@ -1588,760 +1736,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[]>;
+/**
+ * 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 {
     /**
-     * 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`.
+     * 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 dontAskAgain: _angular_core.WritableSignal<MessageBoxDontAskAgainConfig | undefined>;
+    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;
     /**
-     * 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.
+     * 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 dontAskAgainChecked: _angular_core.WritableSignal<boolean>;
-    private resolver;
-    show(options: MessageBoxOptions): Promise<DialogResult>;
+    readonly appIdField?: 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`.
+     * 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.
      */
-    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 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>;
-}
-
-/** 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>;
+    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;
 }
-
-/**
- * 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;
+/** 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;
 }
-
-/**
- * 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()"
- * />
- * ```
- */
-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>;
+/** 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;
 }
-
-interface UploadSlot {
-    file: File;
-    progress: number;
-    status: 'uploading' | 'done' | 'error';
-    info?: FlyFileInfo;
-    error?: string;
+/** Disposable handle returned by the lookup registry. Idempotent `dispose()`. */
+interface LookupHandle {
+    dispose(): void;
 }
 /**
- * Multi-file upload with drag-drop, progress, and validation.
+ * 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-file-upload
- *   [maxFiles]="5"
- *   [maxFileSizeBytes]="5242880"
- *   accept=".pdf,.docx,.xlsx"
- *   [(files)]="trend.attachments"
- *   sourceApp="circles"
- *   sourceEntityType="trend"
- *   (filesChanged)="onAttachmentsChanged($event)"
- * />
- * ```
+ * 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}).
  */
-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;
-}
-/** What hosts pass to {@link AgentCommandRegistry.register}. Adds the scope to {@link AgentCommand}. */
-interface AgentCommandRegistration extends AgentCommand {
-    readonly scope: AgentCommandScope;
+    /** Builds the payload the moment the user picks the item. */
+    build(): AgentDragPayload<T>;
 }
-/** Disposable handle returned by {@link AgentCommandRegistry.register}. Idempotent `dispose()`. */
-interface AgentCommandHandle {
-    dispose(): void;
+/** 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>>;
 }
 /**
- * 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.
+ * 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 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;
+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;
     /**
-     * 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.
+     * 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 resultsPath?: string;
+    readonly maxDeepLinkRouteBytes: number;
+}
+declare const DEFAULT_AGENT_PAYLOAD_LIMITS: AgentPayloadLimits;
+/**
+ * Stable failure reasons emitted by {@link validateAgentPayload}.
+ *   - `invalid_version` — `version` !== {@link AGENT_PAYLOAD_VERSION}.
+ *   - `invalid_kind` — `kind` is empty / not a string.
+ *   - `field_too_large` — a string field inside `payload` exceeds `maxStringFieldBytes`.
+ *   - `fallback_too_large` — `plainTextFallback` exceeds `maxPlainTextFallbackBytes`.
+ *   - `json_too_large` — the full JSON.stringify(envelope) exceeds `maxJsonBytes`.
+ */
+type AgentPayloadValidationResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: 'json_too_large' | 'fallback_too_large' | 'field_too_large' | 'invalid_version' | 'invalid_kind' | '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;
+};
+
+/**
+ * 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 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;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * Host-provided handler that navigates to a resolved in-app entity deep link
+ * when the user clicks a `flyos:` anchor inside a {@link FlyMarkdownEditorComponent}.
+ *
+ * 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).
+ */
+type EntityLinkLauncher = (target: {
+    readonly appId: string;
+    readonly route: string;
+    readonly kind: string;
+    readonly id: string;
+}) => void;
+declare const ENTITY_LINK_LAUNCHER: InjectionToken<EntityLinkLauncher>;
+/**
+ * A toolbar control id, or `'|'` for a visual divider. `toolbar` accepts a
+ * preset name or an explicit ordered list of these.
+ */
+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>;
+}
+
+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;
 }
 /**
- * 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.
+ * 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 LookupDescriptor {
-    /**
-     * Stable entity key, kebab/lower, e.g. `scenario`. Doubles as the `/lookup
-     * <entity>` sub-token and the group key the picked ref is grouped under when
-     * serialized for the agent.
-     */
-    readonly entity: string;
-    /** i18n key for the entity's display name in the picker / palette. */
-    readonly labelKey: string;
-    /** Optional PrimeIcons class for the picker row + chip. */
-    readonly icon?: string;
-    /**
-     * Route globs where this lookup is offered (matched against the shell's
-     * router url), e.g. `['/scenarios/*', '/trends/*']`. Omit / empty = offered
-     * everywhere the owning app is live.
-     */
-    readonly pages?: readonly string[];
-    /** How to fetch + map candidates. */
-    readonly search: LookupSearch;
+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;
 }
-/** What hosts pass to the lookup registry. Adds the scope to {@link LookupDescriptor}. */
-interface LookupRegistration extends LookupDescriptor {
-    /** Same scoping semantics as {@link AgentCommandScope}. */
-    readonly scope: AgentCommandScope;
+/**
+ * Options narrowed to those carrying a `dontAskAgain` config — the only shape
+ * accepted by `showAcknowledged()`.
+ */
+interface MessageBoxOptionsWithAcknowledgement extends MessageBoxOptions {
+    dontAskAgain: MessageBoxDontAskAgainConfig;
 }
-/** 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;
+interface MessageBoxButton {
+    label: string;
+    result: DialogResult;
+    variant?: 'primary' | 'danger' | 'default';
 }
-/** Disposable handle returned by the lookup registry. Idempotent `dispose()`. */
-interface LookupHandle {
-    dispose(): void;
+/** Shape returned by `showAcknowledged()` — pairs the dialog result with the checkbox state. */
+interface DialogResultWithAcknowledgement {
+    readonly result: DialogResult;
+    readonly dontAskAgain: boolean;
 }
-/**
- * The wire envelope used by both the drag/drop surface and the imperative
- * {@link AgentActionBus}. Renderers narrow on `kind`; mismatches fall back to
- * `plainTextFallback`.
- *
- * The base fields (v1) describe **what** is being handed to the agent panel.
- * The v2 fields describe **how the agent should treat it** — `userMessage`
- * scopes the user-visible bubble, `systemContext` extends the system prompt,
- * `attachments` decorate the message with typed chips, and `mcpScope` hints
- * the agent toward a tool family. All v2 fields are optional so existing
- * v1 (drag/drop) payloads remain valid envelopes.
- *
- * Caps (see {@link AgentPayloadLimits}):
- *   - JSON total            32 KB
- *   - plainTextFallback      8 KB
- *   - per-string field       4 KB
- *   - userMessage              280 chars
- *   - systemContext       32 entries × 4 KB per value, 8 KB total serialized
- *   - attachments          4 entries, kind-dependent inner caps
- *   - mcpScope.apis        5 prefixes × 128 chars
- *
- * The cap math is split per-section so an oversize attachment fails fast at the
- * attachment site instead of the whole envelope; field paths are dotted (see
- * {@link AgentPayloadValidationResult}).
- */
-interface AgentDragPayload<T = unknown> {
-    /** Domain-stable kind, e.g. `circles.trend`. */
-    readonly kind: string;
-    /** Originating appId. Must match an entry in the host's app registry. */
-    readonly appId: string;
-    /** Frozen format version. 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>>;
+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.
@@ -2395,12 +2937,18 @@ declare class AgentCommandRegistry {
 /**
  * Singleton registry of entity lookups offered by the `/lookup` typeahead.
  *
- * Mirrors {@link AgentCommandRegistry} exactly — same federation-singleton story
- * (`sharedMappings: ['@mohamedatia/fly-design-system']`), same id-collision
- * "latest wins" contract, same disposable-handle ergonomics. Federated remotes
- * register their lookupable entities at boot (Circles: scenario / trend / signal)
- * and dispose on window close, so the picker only ever offers entities whose app
- * is currently live.
+ * Mirrors {@link AgentCommandRegistry}'s federation-singleton story
+ * (`sharedMappings: ['@mohamedatia/fly-design-system']`), id-collision
+ * "latest wins" contract, and disposable-handle ergonomics. OS-core entities
+ * (note / calendar event / file) register once at shell bootstrap via
+ * `CORE_APP_LOOKUPS`; federated remotes (Circles: scenario / trend / signal)
+ * register at remote-component boot and dispose on window close.
+ *
+ * **Scope semantics diverge from commands.** Commands HIDE when their `appId`
+ * isn't in `liveAppIds`. Lookups DO NOT — they're always offered, and
+ * `{appId}` is just a *priority hint* that bumps that lookup to the top of
+ * the entity picker when the app is live. See {@link LookupRegistration.scope}
+ * for the rationale.
  *
  * Storage is a signal store keyed on {@link LookupRegistration.entity}. Because
  * `entity` is the collision key, an app re-registering the same entity replaces
@@ -2411,10 +2959,18 @@ declare class AgentLookupRegistry {
     /** All currently-registered lookups, in insertion order. */
     readonly all: Signal<readonly LookupRegistration[]>;
     /**
-     * Lookups whose scope is `'global'` OR whose `scope.appId` is in the live app
-     * set. Recomputes when either the registry or `liveAppIds` changes — pass a
+     * All registered lookups, sorted by affinity to `liveAppIds`:
+     *
+     *   1. Lookups whose `scope.appId` is in the live app set (in registration
+     *      order within that bucket).
+     *   2. Then everything else — `'global'` lookups AND scoped lookups whose
+     *      app isn't currently live — in registration order.
+     *
+     * Recomputes when either the registry or `liveAppIds` changes. Pass a
      * `Signal<ReadonlySet<string>>` from the host's app-registry for reactive
-     * filtering, exactly like {@link AgentCommandRegistry.visible}.
+     * re-sorting. **Always returns the full registry** — see the type doc on
+     * {@link LookupRegistration.scope} for why this differs from
+     * {@link AgentCommandRegistry.visible}.
      */
     visible(liveAppIds: ReadonlySet<string> | Signal<ReadonlySet<string>>): Signal<readonly LookupRegistration[]>;
     /**
@@ -2429,6 +2985,45 @@ declare class AgentLookupRegistry {
      * follow the standard "latest wins" rule and do NOT trigger rollback.
      */
     registerAll(lookups: readonly LookupRegistration[]): LookupHandle;
+    /**
+     * Resolve a deep-link anchor to a concrete launch target.
+     *
+     * `kind` is the dotted `<appId>.<entity>` token the agents backend emits
+     * inside `flyos:<kind>/<id>` chat-answer anchors — the same entity-kind
+     * vocabulary as drag-payload kinds and `ref` parts. Returns
+     * `{ appId, route }` when a registered lookup for that `(appId, entity)`
+     * pair carries a {@link LookupDescriptor.deepLinkRoute} template; `null`
+     * otherwise (unknown entity, app mismatch, or no template — e.g. the
+     * owning app isn't installed) so the caller renders plain text rather than
+     * a dead link.
+     *
+     * `appId` and `entity` are both dot-free by their own grammars, so the
+     * FIRST dot is the unambiguous split point; a dotless `kind` can't carry an
+     * app and never resolves. The template's single `{id}` placeholder is
+     * substituted URL-encoded.
+     */
+    resolveDeepLink(kind: string, id: string): {
+        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. */
@@ -2975,6 +3570,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_ROUTES, FLY_THEME_MODE_IDS, FLY_WINDOW_HELP_HINT_EVENT, FlyAgentDraggableDirective, FlyBlockUiComponent, FlyFileUploadComponent, FlyImageUploadComponent, FlyRemoteRouter, FlyRemoteRouterOutletComponent, FlySecureSrcDirective, FlyThemeService, FlyWindowHelpService, FlyosPendingLaunchesGlobalKey, I18nService, LAUNCH_CONTEXT, MessageBoxButtons, MessageBoxComponent, MessageBoxIcon, MessageBoxService, MockAuthService, RTL_LOCALE_SET, SHARE_ORG_CHART_SYSTEM_KEY_APPS, SHARE_ORG_CHART_SYSTEM_KEY_DEFAULT, SHARE_PANEL_DEFAULT_FILE_LEVELS, SUPPORTED_AGENT_PAYLOAD_VERSIONS, SharePanelComponent, SourceAppResolver, StandaloneWindowManagerService, TranslatePipe, WINDOW_DATA, WINDOW_HELP_HINT, WindowManagerService, findLocaleByDialect, findLocaleByPrefix, isRtlLocale, isRtlLocaleEntry, loadRemoteStyles, matchFlyRoutePattern, normalizeFlyTheme, trimAgentPayload, trimAgentString, unloadRemoteStyles, utf8ByteLength, validateAgentPayload };
-export type { AgentAction, AgentActionDispatch, AgentActionVerb, AgentChipHostInputs, AgentCommand, AgentCommandHandle, AgentCommandRegistration, AgentCommandScope, AgentDragPayload, AgentDraggableItem, AgentDropChipMode, AgentDropRendererRegistration, AgentEnvelopeAttachment, AgentMcpScope, AgentMessageEnvelope, AgentPayloadLimits, AgentPayloadValidationResult, AppEveryonePrincipal, AppEveryoneTerm, AppLookup, AppLookupEntry, AudienceEditTarget, AudienceErrorCode, AudienceFilter, AudienceOptions, AudiencePresetKind, AudienceTerm, AudienceTermKind, ChartTerm, ChildWindowData, ContextMenuItem, ContextMenuSection, DesktopApp, DesktopAppKind, DialogResultWithAcknowledgement, FlyFileInfo, FlyLaunchEventDetail, FlyLocaleEntry, FlyRemoteMatch, FlyRemoteRoute, FlyThemeMode, FlyWindowHelpHintEventDetail, 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, 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, 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, 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