@mohamedatia/fly-design-system 2.12.0 → 2.13.0

package/scss/_tokens.scss

@@ -1,115 +1,115 @@
-// ─── visionOS System Colors & Design Tokens ─────────────────────────────────
-:root {
-  --system-red: #FF453A;
-  --system-orange: #FF9F0A;
-  --system-yellow: #FFD60A;
-  --system-green: #32D74B;
-  --system-mint: #66D4CF;
-  --system-teal: #6AC4DC;
-  --system-cyan: #5AC8F5;
-  --system-blue: #0A84FF;
-  --system-indigo: #5E5CE6;
-  --system-purple: #BF5AF2;
-  --system-pink: #FF375F;
-  --system-brown: #AC8E68;
-  --system-gray: #98989D;
-
-  // ── Semantic Status Colors ──
-  --status-success: var(--system-green);
-  --status-warning: var(--system-orange);
-  --status-error: var(--system-red);
-  --status-info: var(--system-blue);
-  --status-pending: var(--system-yellow);
-
-  // ── visionOS Typography ──
-  --font-family: 'SF Pro Display', 'SF Pro', 'Inter', -apple-system, blinkmacsystemfont, 'Segoe UI', sans-serif;
-  --font-xl-title1: 700 48px/56px var(--font-family);
-  --font-xl-title2: 700 38px/46px var(--font-family);
-  --font-large-title: 700 29px/38px var(--font-family);
-  --font-title1: 700 24px/32px var(--font-family);
-  --font-title2: 700 22px/28px var(--font-family);
-  --font-title3: 700 19px/24px var(--font-family);
-  --font-headline: 700 17px/22px var(--font-family);
-  --font-body: 510 17px/22px var(--font-family);
-  --font-callout: 590 15px/20px var(--font-family);
-  --font-subheadline: 400 15px/20px var(--font-family);
-  --font-footnote: 510 13px/18px var(--font-family);
-  --font-caption1: 510 12px/16px var(--font-family);
-  --font-caption2: 510 12px/16px var(--font-family);
-
-  // ── visionOS Label Colors ──
-  --label-primary: rgb(255 255 255 / 96%);
-  --label-secondary: rgb(255 255 255 / 56%);
-  --label-tertiary: rgb(255 255 255 / 36%);
-
-  // ── visionOS Materials ──
-  --material-glass: rgb(128 128 128 / 30%);
-  --material-glass-blur: 50px;
-  --material-glass-stroke: rgb(255 255 255 / 40%);
-  --material-glass-specular: inset 0px -0.5px 1px rgb(255 255 255 / 30%),
-                              inset 0px -0.5px 1px rgb(255 255 255 / 25%),
-                              inset 1px 1.5px 4px rgb(0 0 0 / 8%),
-                              inset 1px 1.5px 4px rgb(0 0 0 / 10%);
-  --material-recessed-bg: linear-gradient(rgb(208 208 208 / 50%), rgb(208 208 208 / 50%)),
-                           linear-gradient(rgb(0 0 0 / 10%), rgb(0 0 0 / 10%));
-  --material-recessed-shadow: inset 1px 1.5px 4px rgb(0 0 0 / 10%),
-                               inset 1px 1.5px 4px rgb(0 0 0 / 8%),
-                               inset 0px -0.5px 1px rgb(255 255 255 / 25%),
-                               inset 0px -0.5px 1px rgb(255 255 255 / 30%);
-  --material-thin: rgb(255 255 255 / 6%);
-  --material-regular: rgb(255 255 255 / 12%);
-  --material-thick: rgb(255 255 255 / 20%);
-  --control-idle: rgb(255 255 255 / 6%);
-  --control-hover: rgb(255 255 255 / 12%);
-  --control-selected: rgb(255 255 255 / 100%);
-  --control-disabled: rgb(255 255 255 / 4%);
-  --separator: rgb(255 255 255 / 12%);
-  --blur-shadow-small: 0 2px 4px rgb(0 0 0 / 10%);
-
-  // ── visionOS Button Tokens ──
-  --btn-font-weight: 590;
-  --btn-symbol-font-weight: 510;
-  --btn-radius-capsule: 500px;
-  --btn-radius-rect-lg: 16px;
-  --btn-radius-rect-sm: 8px;
-  --btn-sm-height: 32px;
-  --btn-sm-padding: 0 12px;
-  --btn-sm-font-size: 15px;
-  --btn-sm-line-height: 20px;
-  --btn-sm-symbol-size: 17px;
-  --btn-sm-gap: 2px;
-  --btn-reg-height: 44px;
-  --btn-reg-padding: 0 20px;
-  --btn-reg-font-size: 17px;
-  --btn-reg-line-height: 22px;
-  --btn-reg-symbol-size: 19px;
-  --btn-reg-gap: 6px;
-  --btn-lg-height: 52px;
-  --btn-lg-padding: 0 25px;
-  --btn-lg-font-size: 19px;
-  --btn-lg-line-height: 24px;
-  --btn-lg-symbol-size: 22px;
-  --btn-lg-gap: 6px;
-  --btn-symbol-mini: 28px;
-  --btn-symbol-mini-font: 13px;
-  --btn-symbol-sm: 36px;
-  --btn-symbol-sm-font: 15px;
-  --btn-symbol-reg: 44px;
-  --btn-symbol-reg-font: 19px;
-  --btn-symbol-lg: 52px;
-  --btn-symbol-lg-font: 22px;
-  --btn-symbol-xl: 60px;
-  --btn-symbol-xl-font: 26px;
-  --btn-platter-lighten: rgb(255 255 255 / 6%);
-  --btn-platter-dodge: rgb(94 94 94 / 18%);
-  --btn-hover-grad-white: rgb(255 255 255 / 7%);
-  --btn-hover-grad-gray: rgb(94 94 94 / 14%);
-  --btn-disabled-lighten: rgb(255 255 255 / 4%);
-  --btn-disabled-dodge: rgb(94 94 94 / 7%);
-  --btn-disabled-text: rgb(112 112 112 / 50%);
-  --btn-selected-bg: rgb(255 255 255 / 96%);
-  --btn-selected-text: #000;
-  --link-color: #3CD3FE;
-  --link-height: 26px;
-  --link-font-size: 13px;
-}
+// ─── visionOS System Colors & Design Tokens ─────────────────────────────────
+:root {
+  --system-red: #FF453A;
+  --system-orange: #FF9F0A;
+  --system-yellow: #FFD60A;
+  --system-green: #32D74B;
+  --system-mint: #66D4CF;
+  --system-teal: #6AC4DC;
+  --system-cyan: #5AC8F5;
+  --system-blue: #0A84FF;
+  --system-indigo: #5E5CE6;
+  --system-purple: #BF5AF2;
+  --system-pink: #FF375F;
+  --system-brown: #AC8E68;
+  --system-gray: #98989D;
+
+  // ── Semantic Status Colors ──
+  --status-success: var(--system-green);
+  --status-warning: var(--system-orange);
+  --status-error: var(--system-red);
+  --status-info: var(--system-blue);
+  --status-pending: var(--system-yellow);
+
+  // ── visionOS Typography ──
+  --font-family: 'SF Pro Display', 'SF Pro', 'Inter', -apple-system, blinkmacsystemfont, 'Segoe UI', sans-serif;
+  --font-xl-title1: 700 48px/56px var(--font-family);
+  --font-xl-title2: 700 38px/46px var(--font-family);
+  --font-large-title: 700 29px/38px var(--font-family);
+  --font-title1: 700 24px/32px var(--font-family);
+  --font-title2: 700 22px/28px var(--font-family);
+  --font-title3: 700 19px/24px var(--font-family);
+  --font-headline: 700 17px/22px var(--font-family);
+  --font-body: 510 17px/22px var(--font-family);
+  --font-callout: 590 15px/20px var(--font-family);
+  --font-subheadline: 400 15px/20px var(--font-family);
+  --font-footnote: 510 13px/18px var(--font-family);
+  --font-caption1: 510 12px/16px var(--font-family);
+  --font-caption2: 510 12px/16px var(--font-family);
+
+  // ── visionOS Label Colors ──
+  --label-primary: rgb(255 255 255 / 96%);
+  --label-secondary: rgb(255 255 255 / 56%);
+  --label-tertiary: rgb(255 255 255 / 36%);
+
+  // ── visionOS Materials ──
+  --material-glass: rgb(128 128 128 / 30%);
+  --material-glass-blur: 50px;
+  --material-glass-stroke: rgb(255 255 255 / 40%);
+  --material-glass-specular: inset 0px -0.5px 1px rgb(255 255 255 / 30%),
+                              inset 0px -0.5px 1px rgb(255 255 255 / 25%),
+                              inset 1px 1.5px 4px rgb(0 0 0 / 8%),
+                              inset 1px 1.5px 4px rgb(0 0 0 / 10%);
+  --material-recessed-bg: linear-gradient(rgb(208 208 208 / 50%), rgb(208 208 208 / 50%)),
+                           linear-gradient(rgb(0 0 0 / 10%), rgb(0 0 0 / 10%));
+  --material-recessed-shadow: inset 1px 1.5px 4px rgb(0 0 0 / 10%),
+                               inset 1px 1.5px 4px rgb(0 0 0 / 8%),
+                               inset 0px -0.5px 1px rgb(255 255 255 / 25%),
+                               inset 0px -0.5px 1px rgb(255 255 255 / 30%);
+  --material-thin: rgb(255 255 255 / 6%);
+  --material-regular: rgb(255 255 255 / 12%);
+  --material-thick: rgb(255 255 255 / 20%);
+  --control-idle: rgb(255 255 255 / 6%);
+  --control-hover: rgb(255 255 255 / 12%);
+  --control-selected: rgb(255 255 255 / 100%);
+  --control-disabled: rgb(255 255 255 / 4%);
+  --separator: rgb(255 255 255 / 12%);
+  --blur-shadow-small: 0 2px 4px rgb(0 0 0 / 10%);
+
+  // ── visionOS Button Tokens ──
+  --btn-font-weight: 590;
+  --btn-symbol-font-weight: 510;
+  --btn-radius-capsule: 500px;
+  --btn-radius-rect-lg: 16px;
+  --btn-radius-rect-sm: 8px;
+  --btn-sm-height: 32px;
+  --btn-sm-padding: 0 12px;
+  --btn-sm-font-size: 15px;
+  --btn-sm-line-height: 20px;
+  --btn-sm-symbol-size: 17px;
+  --btn-sm-gap: 2px;
+  --btn-reg-height: 44px;
+  --btn-reg-padding: 0 20px;
+  --btn-reg-font-size: 17px;
+  --btn-reg-line-height: 22px;
+  --btn-reg-symbol-size: 19px;
+  --btn-reg-gap: 6px;
+  --btn-lg-height: 52px;
+  --btn-lg-padding: 0 25px;
+  --btn-lg-font-size: 19px;
+  --btn-lg-line-height: 24px;
+  --btn-lg-symbol-size: 22px;
+  --btn-lg-gap: 6px;
+  --btn-symbol-mini: 28px;
+  --btn-symbol-mini-font: 13px;
+  --btn-symbol-sm: 36px;
+  --btn-symbol-sm-font: 15px;
+  --btn-symbol-reg: 44px;
+  --btn-symbol-reg-font: 19px;
+  --btn-symbol-lg: 52px;
+  --btn-symbol-lg-font: 22px;
+  --btn-symbol-xl: 60px;
+  --btn-symbol-xl-font: 26px;
+  --btn-platter-lighten: rgb(255 255 255 / 6%);
+  --btn-platter-dodge: rgb(94 94 94 / 18%);
+  --btn-hover-grad-white: rgb(255 255 255 / 7%);
+  --btn-hover-grad-gray: rgb(94 94 94 / 14%);
+  --btn-disabled-lighten: rgb(255 255 255 / 4%);
+  --btn-disabled-dodge: rgb(94 94 94 / 7%);
+  --btn-disabled-text: rgb(112 112 112 / 50%);
+  --btn-selected-bg: rgb(255 255 255 / 96%);
+  --btn-selected-text: #000;
+  --link-color: #3CD3FE;
+  --link-height: 26px;
+  --link-font-size: 13px;
+}

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

@@ -1213,16 +1213,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
@@ -1982,6 +2101,60 @@ interface AgentCommand {
     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;
+}
+/**
+ * A context binding that resolves one `system_context` value for a Category B
+ * command at dispatch. Pure data so it travels app-agnostically in the
+ * Controller's app federation metadata (no callbacks). Discriminated by `from`:
+ *
+ *  - `route`    — value from the owning app's current route param `path`. The
+ *                 shell cannot read a federated remote's internal route, so route
+ *                 bindings **degrade** in v1 (the skill asks for the missing id);
+ *                 resolved only once a remote→shell route channel exists.
+ *  - `lookup`   — the host opens the `/lookup` entity picker for `entity` and
+ *                 writes the picked id into `system_context[key]` (picker-during-
+ *                 dispatch is a v1 follow-up — degrades to "ask" until then).
+ *  - `constant` — a literal value written into `system_context[key]`.
+ */
+type AgentCommandContextBinding = {
+    readonly key: string;
+    readonly from: 'route';
+    readonly path: string;
+} | {
+    readonly key: string;
+    readonly from: 'lookup';
+    readonly entity: string;
+    readonly exclude?: readonly string[];
+    readonly promptKey?: string;
+} | {
+    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[];
 }
 /** What hosts pass to {@link AgentCommandRegistry.register}. Adds the scope to {@link AgentCommand}. */
 interface AgentCommandRegistration extends AgentCommand {
@@ -2021,6 +2194,20 @@ interface LookupSearch {
     readonly displayField: string;
     /** Optional response-item field for the chip's secondary line (status, category). */
     readonly secondaryField?: string;
+    /**
+     * Optional response-item field whose value is a *row-level* app id — i.e. the
+     * app that owns this individual entity, distinct from the descriptor's
+     * {@link LookupDescriptor.appId} (which only names the app exposing the
+     * lookup endpoint). Help articles are the motivating case: every article is
+     * exposed by `help-center`, but each one was seeded by a *source* app's
+     * manifest (Circles, Trends, …). Surfacing that per-row appId lets the
+     * picker render a second source-app tag so the user can tell two
+     * similarly-titled rows from different source apps apart at a glance.
+     *
+     * Resolved through {@link LookupResult.appId} and the shell's app registry
+     * with the same fallback chain used for {@link LookupDescriptor.appId}.
+     */
+    readonly appIdField?: string;
     /**
      * Dotted path to the results array within the response body when it is
      * wrapped, e.g. `items` for `{ items: [...], total }`. Omit when the response
@@ -2049,17 +2236,80 @@ interface LookupDescriptor {
     /** 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.
+     * Stable id of the app that exposes this lookup, e.g. `notes`, `calendar`,
+     * `circles`. The picker resolves it to the app's display name via the shell's
+     * app registry and renders an "exposed by …" badge so the user can see which
+     * app owns the entity they're browsing (helps disambiguate when two apps
+     * register a similar-sounding entity, e.g. both Tasks and Notes one day).
+     *
+     * Populated automatically by the shell's registration paths:
+     *   - `CORE_APP_LOOKUPS` stamps it per descriptor at hand-edit time.
+     *   - `RemoteManifestService` stamps it from the manifest entry's `id` so
+     *     federation remotes don't have to repeat the id in every descriptor.
+     *
+     * Falls back to {@link appBadgeKey} (a locale-resolved literal) when an
+     * entity has no first-class home in the shell's app registry — e.g. `user`,
+     * `app-agent`, `robot`. When neither is set the picker omits the badge.
+     */
+    readonly appId?: string;
+    /**
+     * Optional i18n key the picker uses for the "exposed by …" badge **when
+     * {@link appId} is absent or unknown to the shell's app registry**. Lets
+     * entities that don't map to a single app (Users, Robots, App Agents) still
+     * surface a meaningful badge instead of silently omitting it. The picker
+     * resolves the key via the shared i18n service so the badge follows the
+     * user's locale.
+     */
+    readonly appBadgeKey?: string;
+    /**
+     * Advisory MCP tool-key prefixes the agent should prefer when the user
+     * references this entity via `/lookup` (e.g. `['dashboard.reports']`). The
+     * shell folds these into the turn's `mcp_scope` so the Twin self-serves the
+     * owning app's tools — fetching and analysing the referenced entity itself —
+     * instead of defaulting to a specialist-Robot consult for "tell me more"
+     * style prompts. Same dot-namespaced prefix vocabulary as
+     * {@link AgentMcpScope.apis}. Omit for entities with no first-class MCP tool
+     * family (e.g. `user`, `robot`).
+     */
+    readonly mcpApis?: readonly string[];
+    /**
+     * Optional in-app deep-link route TEMPLATE for this entity's detail page,
+     * e.g. `'/signals/{id}'`. When present, the desktop shell turns an agent's
+     * inline reference to this entity — the `flyos:<appId>.<entity>/<id>`
+     * anchors the agents backend emits in chat answers — into a launchable
+     * link: the single `{id}` placeholder is substituted with the referenced
+     * entity's id (URL-encoded) and the owning {@link appId} is launched on
+     * that route via the shell launcher.
+     *
+     * Omit for entities with no standalone detail page — their references then
+     * render as plain text (graceful degrade; never a dead link). The owning
+     * app declares this once in its `lookups[]` manifest entry, so a remote
+     * becomes agent-deep-linkable without any shell or design-system change.
+     * Only `{id}` is substituted here — richer parameterisation rides the
+     * deep-link `params` channel, not this template.
      */
-    readonly pages?: readonly string[];
+    readonly deepLinkRoute?: string;
     /** How to fetch + map candidates. */
     readonly search: LookupSearch;
 }
 /** What hosts pass to the lookup registry. Adds the scope to {@link LookupDescriptor}. */
 interface LookupRegistration extends LookupDescriptor {
-    /** Same scoping semantics as {@link AgentCommandScope}. */
+    /**
+     * 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;
 }
 /** One resolved row the picker returns once the user selects a candidate. */
@@ -2072,6 +2322,14 @@ interface LookupResult {
     readonly label: string;
     /** Optional secondary detail (status / category). */
     readonly secondary?: string;
+    /**
+     * Row-level source app id (e.g. `circles` for an article seeded by Circles'
+     * manifest). Populated when the descriptor sets {@link LookupSearch.appIdField}
+     * and the response item carries a non-empty value. The picker renders it as
+     * a second app tag alongside the descriptor-level badge so the user can see
+     * "this Help-Center article was contributed by Circles" without opening it.
+     */
+    readonly appId?: string;
 }
 /** Disposable handle returned by the lookup registry. Idempotent `dispose()`. */
 interface LookupHandle {
@@ -2395,12 +2653,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 +2675,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 +2701,27 @@ 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;
     /** Tear down by entity. Idempotent. */
     unregister(entity: string): void;
     /** Monotonic counter; identifies which registration call currently owns each entity. */
@@ -2975,6 +3268,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, DialogResult, FLYOS_LAUNCH_EVENT, FLY_LOCALE_CATALOG, FLY_REMOTE_BASE_PATH, FLY_REMOTE_CONTEXT_EVENT, FLY_REMOTE_CONTEXT_STORE_KEY, FLY_REMOTE_ROUTES, FLY_THEME_MODE_IDS, FLY_WINDOW_HELP_HINT_EVENT, FlyAgentDraggableDirective, FlyBlockUiComponent, FlyFileUploadComponent, FlyImageUploadComponent, FlyRemoteContextService, FlyRemoteRouter, FlyRemoteRouterOutletComponent, FlySecureSrcDirective, FlyThemeService, FlyWindowHelpService, FlyosPendingLaunchesGlobalKey, I18nService, LAUNCH_CONTEXT, MessageBoxButtons, MessageBoxComponent, MessageBoxIcon, MessageBoxService, MockAuthService, RTL_LOCALE_SET, SHARE_ORG_CHART_SYSTEM_KEY_APPS, SHARE_ORG_CHART_SYSTEM_KEY_DEFAULT, SHARE_PANEL_DEFAULT_FILE_LEVELS, SUPPORTED_AGENT_PAYLOAD_VERSIONS, SharePanelComponent, SourceAppResolver, StandaloneWindowManagerService, TranslatePipe, WINDOW_DATA, WINDOW_HELP_HINT, WindowManagerService, findLocaleByDialect, findLocaleByPrefix, isRtlLocale, isRtlLocaleEntry, loadRemoteStyles, matchFlyRoutePattern, normalizeFlyTheme, trimAgentPayload, trimAgentString, unloadRemoteStyles, utf8ByteLength, validateAgentPayload };
+export type { AgentAction, AgentActionDispatch, AgentActionVerb, AgentChipHostInputs, AgentCommand, AgentCommandContextBinding, AgentCommandHandle, AgentCommandRegistration, AgentCommandScope, AgentCommandSlashSpec, AgentDragPayload, AgentDraggableItem, AgentDropChipMode, AgentDropRendererRegistration, AgentEnvelopeAttachment, AgentMcpScope, AgentMessageEnvelope, AgentPayloadLimits, AgentPayloadValidationResult, AppEveryonePrincipal, AppEveryoneTerm, AppLookup, AppLookupEntry, AudienceEditTarget, AudienceErrorCode, AudienceFilter, AudienceOptions, AudiencePresetKind, AudienceTerm, AudienceTermKind, ChartTerm, ChildWindowData, ContextMenuItem, ContextMenuSection, DesktopApp, DesktopAppKind, DialogResultWithAcknowledgement, FlyFileInfo, FlyLaunchEventDetail, FlyLocaleEntry, FlyRemoteContext, FlyRemoteMatch, FlyRemoteRoute, FlyThemeMode, FlyWindowHelpHintEventDetail, FlyWindowHelpPublisher, FlyosPendingLaunches, LaunchContext, LoadBundleOptions, LookupDescriptor, LookupHandle, LookupRegistration, LookupResult, LookupSearch, MessageBoxButton, MessageBoxDontAskAgainConfig, MessageBoxOptions, MessageBoxOptionsWithAcknowledgement, MockAuthConfig, OpenWindowOptions, OuPrincipal, OuTerm, PresetTerm, RemoteAppDef, RoleOuLookupRow, RolePrincipal, RolesTerm, ShareOrgChartOption, ShareOuNode, SharePanelLevelOption, SharePermissionEntry, SharePrincipal, SharePrincipalKind, ShareUserResult, User, UserPrincipal, UsersTerm, WindowHelpHint, WindowInstance, WindowState };
 //# sourceMappingURL=mohamedatia-fly-design-system.d.ts.map