@memberjunction/ng-conversations 5.40.1 → 5.41.0

package/dist/lib/components/realtime/channels/base-realtime-channel-client.js

@@ -0,0 +1,158 @@
+/**
+ * Base class for CLIENT-SIDE interactive-channel plugins (per
+ * `plans/ai-agent-sessions.md` → "Interactive Channels" / "Pluggable Channel Interfaces").
+ *
+ * An interactive channel is a bidirectional surface the session's single realtime agent
+ * both PERCEIVES and ACTS UPON (whiteboard, shared doc, map, …). A concrete plugin
+ * contributes everything the channel needs, so the session service / call overlay carry
+ * ZERO channel-specific wiring:
+ *
+ *  1. a CLIENT-EXECUTED TOOL SET ({@link GetToolDefinitions}, declared to the realtime
+ *     model at session mint) plus the local executor ({@link ApplyAgentTool}) the host
+ *     routes `{@link ToolNamePrefix}*` calls to — the ACTION direction;
+ *  2. a STATE→CONTEXT SERIALIZER policy — the plugin owns its state engine and pushes
+ *     coalesced deltas through {@link RealtimeChannelContext.SendContextNote} — the
+ *     PERCEPTION direction;
+ *  3. an OPTIONAL ANGULAR SURFACE ({@link GetSurfaceComponent}) the overlay creates dynamically
+ *     in a channel tab, handed back through {@link BindSurface} so the plugin wires its own
+ *     inputs/outputs (the host never knows the component's API). A channel may be **server-only**
+ *     (no rendered surface) — e.g. a bridge-contributed meeting-controls or native-whiteboard
+ *     channel whose surface lives on the external platform, not in MJ. Such a channel returns
+ *     `null` from {@link GetSurfaceComponent} ({@link HasSurface} is `false`) and the overlay
+ *     simply skips its tab while still wiring its tools + perception;
+ *  4. a STATE OF RECORD ({@link SerializeState}, persisted via
+ *     {@link RealtimeChannelContext.RequestSave} under {@link ChannelName}).
+ *
+ * ### Registration & resolution (mirrors the realtime model drivers)
+ * Concrete plugins are `@RegisterClass(BaseRealtimeChannelClient, '<ClientPluginClass>')`
+ * and are resolved at session start from the `MJ: AI Agent Channels` registry: each ACTIVE
+ * row's `ClientPluginClass` is the ClassFactory key (exactly how `BaseRealtimeClient`
+ * drivers resolve by provider key). Ship a `Load<YourChannel>()` no-op alongside the class
+ * and call it from a static code path to defeat tree-shaking.
+ *
+ * ### Lifecycle — ONE INSTANCE PER SESSION (not a singleton)
+ * `ClassFactory.CreateInstance` → {@link Initialize}(ctx) → zero or more
+ * {@link BindSurface}/{@link UnbindSurface} cycles (the surface pane is created/destroyed
+ * with the overlay's tab panel, e.g. collapse/expand) → {@link Dispose} at teardown.
+ * {@link ApplyAgentTool} MUST work with NO surface bound (apply to the state engine
+ * directly; skip the UI garnish) — tool calls can arrive while the panel is collapsed.
+ *
+ * @typeParam TSurface The plugin's Angular surface component type. The host only ever
+ *   sees the default (`object`) — the typed parameter exists so concrete plugins get a
+ *   fully typed {@link BindSurface} without casts.
+ */
+export class BaseRealtimeChannelClient {
+    /**
+     * The host context, available from {@link Initialize} until {@link Dispose}.
+     * `null` outside that window — guard with `?.` in any code that can run early/late.
+     */
+    Context = null;
+    /**
+     * The Angular component the overlay creates dynamically as this channel's tab pane, or `null`
+     * for a **server-only** channel that renders no MJ surface (its surface, if any, lives on the
+     * external platform — e.g. a bridge-contributed native whiteboard or meeting-controls channel).
+     *
+     * When this returns `null`, the overlay renders NO tab for the channel and never calls
+     * {@link BindSurface}/{@link UnbindSurface} — but the channel's tools ({@link GetToolDefinitions} /
+     * {@link ApplyAgentTool}) and perception ({@link RealtimeChannelContext.SendContextNote}) still run.
+     * A created surface instance is handed straight back via {@link BindSurface}; the host treats it as
+     * opaque.
+     *
+     * Default: `null` (server-only). A channel with a rendered surface overrides this to return its
+     * component type.
+     */
+    GetSurfaceComponent() {
+        return null;
+    }
+    /**
+     * Whether this channel has a rendered MJ surface ({@link GetSurfaceComponent} returns non-null).
+     * The overlay uses this to decide whether to register a surface tab; server-only channels are
+     * `false`. Override only if surface availability must be decided WITHOUT constructing the type
+     * (the default calls {@link GetSurfaceComponent} once).
+     */
+    HasSurface() {
+        return this.GetSurfaceComponent() != null;
+    }
+    /**
+     * The channel's FIRST-RUN INTRO content, or `null` when the channel offers no onboarding.
+     * The overlay shows this once per channel per user — the first time the user opens this
+     * channel's surface tab — and remembers "seen" via the user's settings (NOT localStorage),
+     * so it never re-appears on later sessions or other devices.
+     *
+     * Default: `null` (no intro). The base Voice/text channel has no plugin at all, so it never
+     * shows an intro; an interactive channel with a surface worth explaining (whiteboard, remote
+     * browser, …) overrides this to return its {@link ChannelOnboardingDetails}. A plugin that
+     * doesn't override it simply shows nothing — onboarding is strictly opt-in.
+     */
+    GetOnboardingDetails() {
+        return null;
+    }
+    /**
+     * Called by the host when the surface component is being destroyed (tab panel
+     * collapsed / overlay torn down). Drop the instance reference and unsubscribe any
+     * output subscriptions — after this, {@link ApplyAgentTool} runs in its no-surface
+     * mode. Default: no-op.
+     */
+    UnbindSurface() {
+        // default: nothing to release
+    }
+    /**
+     * Binds the host context and invokes the {@link OnInitialize} hook. Called exactly once
+     * per session, right after ClassFactory instantiation and before any tool call or
+     * surface bind.
+     */
+    Initialize(ctx) {
+        this.Context = ctx;
+        this.OnInitialize();
+    }
+    /**
+     * Subclass hook invoked from {@link Initialize} once {@link Context} is bound — wire
+     * state-engine subscriptions (e.g. state change → `Context.RequestSave(...)`) here.
+     * Default: no-op.
+     */
+    OnInitialize() {
+        // default: nothing to initialize
+    }
+    /**
+     * Serializes the channel's current state of record (the payload persisted on the
+     * session's channel row), or `null` when the channel keeps no persistent state.
+     * Default: `null`.
+     */
+    SerializeState() {
+        return null;
+    }
+    /**
+     * Restores a PRIOR session's saved channel state (the payload a previous session
+     * persisted via {@link SerializeState} / {@link RealtimeChannelContext.RequestSave}).
+     * Invoked by the session host AFTER {@link Initialize} and BEFORE any surface binding,
+     * when a prior session's saved state exists for this channel.
+     *
+     * Returns `true` when the state was applied; `false` when the channel ignored it —
+     * either because it keeps no persistent state (this default) or because the payload was
+     * malformed/incompatible. Implementations MUST be tolerant: never throw on bad input,
+     * just return `false` and start fresh.
+     */
+    RestoreState(stateJson) {
+        return false;
+    }
+    /**
+     * The focus pill's "exit" affordance, routed by the overlay to the channel that holds
+     * focus. Implementations should leave focus mode through their OWN surface (so surface
+     * toggles stay in sync), ultimately emitting `Context.SetFocusMode(false)`. The overlay
+     * defensively clears its layout flag as well, so a no-op default is safe.
+     */
+    RequestFocusExit() {
+        // default: the overlay's defensive clear handles it
+    }
+    /**
+     * Tears the plugin down at session end: release the surface binding, unsubscribe
+     * state-engine subscriptions, then drop the context. Subclasses overriding this MUST
+     * call `super.Dispose()`. Any final state save has already been flushed by the host
+     * (the debounced {@link RealtimeChannelContext.RequestSave} pipeline) before disposal.
+     */
+    Dispose() {
+        this.UnbindSurface();
+        this.Context = null;
+    }
+}
+//# sourceMappingURL=base-realtime-channel-client.js.map

package/dist/lib/components/realtime/channels/base-realtime-channel-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-realtime-channel-client.js","sourceRoot":"","sources":["../../../../../src/lib/components/realtime/channels/base-realtime-channel-client.ts"],"names":[],"mappings":"AAmHA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,OAAgB,yBAAyB;IAC7C;;;OAGG;IACO,OAAO,GAAkC,IAAI,CAAC;IAwCxD;;;;;;;;;;;;;OAaG;IACI,mBAAmB;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACI,UAAU;QACf,OAAO,IAAI,CAAC,mBAAmB,EAAE,IAAI,IAAI,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;OAUG;IACI,oBAAoB;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAYD;;;;;OAKG;IACI,aAAa;QAClB,8BAA8B;IAChC,CAAC;IAED;;;;OAIG;IACI,UAAU,CAAC,GAA2B;QAC3C,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;QACnB,IAAI,CAAC,YAAY,EAAE,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACO,YAAY;QACpB,iCAAiC;IACnC,CAAC;IAED;;;;OAIG;IACI,cAAc;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;OAUG;IACI,YAAY,CAAC,SAAiB;QACnC,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACI,gBAAgB;QACrB,oDAAoD;IACtD,CAAC;IAED;;;;;OAKG;IACI,OAAO;QACZ,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;CACF","sourcesContent":["import type { Type } from '@angular/core';\nimport { JSONValue, RealtimeToolDefinition } from '@memberjunction/ai';\n\n/**\n * Host services handed to a {@link BaseRealtimeChannelClient} at {@link BaseRealtimeChannelClient.Initialize}.\n *\n * The context is the plugin's ONLY line back to the live session — channels never talk to\n * `RealtimeSessionService` (or any host component) directly, which is what keeps them drop-in\n * plugins. Every member is host-implemented:\n *\n *  - the SESSION SERVICE supplies {@link SendContextNote} (perception feed into the live\n *    model), {@link RequestSave} (debounced state-of-record persistence onto the session's\n *    `MJ: AI Agent Session Channels` row) and {@link AgentName};\n *  - the OVERLAY SHELL wires {@link SetFocusMode} (through the service's focus stream) so a\n *    channel surface can request the focus layout — main call column collapsed, surface\n *    panel filling the overlay, floating call pill riding on top.\n */\nexport interface RealtimeChannelContext {\n  /** Display name of the agent the live session fronts (e.g. `\"Sage\"`), fixed at session start. */\n  AgentName: string;\n\n  /**\n   * Feeds a background context note into the live realtime model (no spoken reply is\n   * requested) — the PERCEPTION direction of the channel: serialized state deltas flow here\n   * so the agent stays aware of what's on the surface. No-op when the session isn't live.\n   */\n  SendContextNote(text: string): void;\n\n  /**\n   * Asks the host to persist `stateJson` as this channel's state of record. The host\n   * DEBOUNCES (a change burst becomes one save) and flushes any pending save at session\n   * teardown — the plugin just calls this on every state mutation and never schedules\n   * timers itself. Best-effort: persistence failures are logged host-side, never thrown.\n   */\n  RequestSave(stateJson: string): void;\n\n  /**\n   * Requests (or releases) the FOCUS layout for this channel's surface: the overlay\n   * collapses the main call column so the surface owns the screen, with a compact floating\n   * call pill keeping mute / thread / end reachable. Any channel may request it; the host\n   * tracks which channel holds focus and routes the pill's \"exit\" back to it via\n   * {@link BaseRealtimeChannelClient.RequestFocusExit}.\n   */\n  SetFocusMode(on: boolean): void;\n\n  /**\n   * Asks the live model to SPEAK a response to the supplied instructions RIGHT NOW —\n   * the channel's \"react to this\" path, e.g. a widget submission the user expects an\n   * audible reaction to ({@link SendContextNote} deliberately never triggers speech).\n   * Rides the realtime client's spoken-update channel, so on some providers the spoken\n   * reply is narration-kind (ephemeral, not persisted as a caption). OPTIONAL member:\n   * older host contexts may not supply it — plugins must call it null-safely.\n   */\n  RequestSpokenResponse?(instructions: string): void;\n\n  /**\n   * Persists a snapshot of the channel's state as a first-class versioned artifact\n   * (`MJ: Artifacts` + version, linked into conversation history when possible) — e.g. the\n   * whiteboard's \"Save to artifacts\". Distinct from {@link RealtimeChannelContext.RequestSave},\n   * which maintains the session's rolling state of record. Best-effort: resolves to the\n   * created Artifact ID, or `null` on failure (logged host-side, never thrown). Works during\n   * the call AND right after it ends (the host retains the session id for late saves).\n   */\n  SaveAsArtifact(name: string, contentJson: string): Promise<string | null>;\n\n  /**\n   * The live `MJ: AI Agent Sessions` id this channel belongs to, or `null` before the\n   * session has minted / after it has torn down. A channel whose tools or surface drive a\n   * SERVER-SIDE resource (e.g. the Remote Browser channel's server-hosted browser) passes\n   * this as the `agentSessionID` argument to its own GraphQL resolvers via\n   * {@link ExecuteServerAction}. Most channels (whiteboard, shared doc) keep all state\n   * client-side and never read it.\n   */\n  AgentSessionID: string | null;\n\n  /**\n   * Executes a CHANNEL-SPECIFIC GraphQL operation against the session's MJ server — the\n   * escape hatch for channels backed by a SERVER-SIDE resource that the generic\n   * {@link RequestSave} / {@link SaveAsArtifact} contract doesn't cover (e.g. the Remote\n   * Browser channel driving a server-hosted browser through its own\n   * `ExecuteRemoteBrowserAction` mutation + `RemoteBrowserSnapshot` query).\n   *\n   * The host runs the operation through the SAME provider the live session uses, so the\n   * request rides the authenticated session. Best-effort and tolerant: a transport or\n   * server error resolves to `null` (logged host-side) rather than throwing, so a channel\n   * can map the failure to a model-readable result string without `try/catch`.\n   *\n   * @typeParam TResult The expected shape of the GraphQL operation's data payload.\n   * @param query The GraphQL query/mutation document.\n   * @param variables The operation variables (all JSON-serializable).\n   * @returns The operation's `data` payload, or `null` on any failure / when no session is live.\n   */\n  ExecuteServerAction<TResult>(query: string, variables: Record<string, JSONValue>): Promise<TResult | null>;\n}\n\n/**\n * The first-run INTRO content for an interactive channel — the concise \"what is this surface\n * and how do I use it\" copy the overlay shows the very first time a user opens this channel's\n * tab (persisted \"seen\" per user, so it's shown ONCE per channel per user).\n *\n * A channel opts in by overriding {@link BaseRealtimeChannelClient.GetOnboardingDetails}; the\n * default returns `null`, so the base Voice/text channel (which has no plugin at all) AND any\n * plugin that doesn't override it show nothing.\n */\nexport interface ChannelOnboardingDetails {\n  /** Short title, usually the surface name (e.g. `\"Whiteboard\"`). */\n  Heading: string;\n  /** One or two sentences: what the surface is and what the user can expect to see on it. */\n  Description: string;\n  /** Optional quick-tip bullets (kept to 2-3 short, scannable lines). */\n  Tips?: string[];\n  /** Optional Font Awesome icon class for the intro panel (e.g. `'fa-solid fa-chalkboard'`). */\n  IconClass?: string;\n}\n\n/**\n * Base class for CLIENT-SIDE interactive-channel plugins (per\n * `plans/ai-agent-sessions.md` → \"Interactive Channels\" / \"Pluggable Channel Interfaces\").\n *\n * An interactive channel is a bidirectional surface the session's single realtime agent\n * both PERCEIVES and ACTS UPON (whiteboard, shared doc, map, …). A concrete plugin\n * contributes everything the channel needs, so the session service / call overlay carry\n * ZERO channel-specific wiring:\n *\n *  1. a CLIENT-EXECUTED TOOL SET ({@link GetToolDefinitions}, declared to the realtime\n *     model at session mint) plus the local executor ({@link ApplyAgentTool}) the host\n *     routes `{@link ToolNamePrefix}*` calls to — the ACTION direction;\n *  2. a STATE→CONTEXT SERIALIZER policy — the plugin owns its state engine and pushes\n *     coalesced deltas through {@link RealtimeChannelContext.SendContextNote} — the\n *     PERCEPTION direction;\n *  3. an OPTIONAL ANGULAR SURFACE ({@link GetSurfaceComponent}) the overlay creates dynamically\n *     in a channel tab, handed back through {@link BindSurface} so the plugin wires its own\n *     inputs/outputs (the host never knows the component's API). A channel may be **server-only**\n *     (no rendered surface) — e.g. a bridge-contributed meeting-controls or native-whiteboard\n *     channel whose surface lives on the external platform, not in MJ. Such a channel returns\n *     `null` from {@link GetSurfaceComponent} ({@link HasSurface} is `false`) and the overlay\n *     simply skips its tab while still wiring its tools + perception;\n *  4. a STATE OF RECORD ({@link SerializeState}, persisted via\n *     {@link RealtimeChannelContext.RequestSave} under {@link ChannelName}).\n *\n * ### Registration & resolution (mirrors the realtime model drivers)\n * Concrete plugins are `@RegisterClass(BaseRealtimeChannelClient, '<ClientPluginClass>')`\n * and are resolved at session start from the `MJ: AI Agent Channels` registry: each ACTIVE\n * row's `ClientPluginClass` is the ClassFactory key (exactly how `BaseRealtimeClient`\n * drivers resolve by provider key). Ship a `Load<YourChannel>()` no-op alongside the class\n * and call it from a static code path to defeat tree-shaking.\n *\n * ### Lifecycle — ONE INSTANCE PER SESSION (not a singleton)\n * `ClassFactory.CreateInstance` → {@link Initialize}(ctx) → zero or more\n * {@link BindSurface}/{@link UnbindSurface} cycles (the surface pane is created/destroyed\n * with the overlay's tab panel, e.g. collapse/expand) → {@link Dispose} at teardown.\n * {@link ApplyAgentTool} MUST work with NO surface bound (apply to the state engine\n * directly; skip the UI garnish) — tool calls can arrive while the panel is collapsed.\n *\n * @typeParam TSurface The plugin's Angular surface component type. The host only ever\n *   sees the default (`object`) — the typed parameter exists so concrete plugins get a\n *   fully typed {@link BindSurface} without casts.\n */\nexport abstract class BaseRealtimeChannelClient<TSurface extends object = object> {\n  /**\n   * The host context, available from {@link Initialize} until {@link Dispose}.\n   * `null` outside that window — guard with `?.` in any code that can run early/late.\n   */\n  protected Context: RealtimeChannelContext | null = null;\n\n  /**\n   * The channel definition name — MUST match the `MJ: AI Agent Channels` row's `Name`\n   * (e.g. `'Whiteboard'`). Used as the persistence key for {@link SerializeState} saves\n   * and as the channel tab's stable key.\n   */\n  public abstract get ChannelName(): string;\n\n  /**\n   * The shared name prefix of every tool this channel exposes (e.g. `'Whiteboard_'`).\n   * The host registers ONE local-execution route per plugin: tool calls whose name starts\n   * with this prefix go to {@link ApplyAgentTool} instead of the server relay.\n   */\n  public abstract get ToolNamePrefix(): string;\n\n  /** Label for the channel's tab on the overlay's surface panel (e.g. `'Whiteboard'`). */\n  public abstract get TabTitle(): string;\n\n  /** Font Awesome icon class for the channel's tab (e.g. `'fa-solid fa-chalkboard'`). */\n  public abstract get TabIcon(): string;\n\n  /**\n   * The channel's CLIENT-EXECUTED tool declarations, aggregated by the session service\n   * into the `clientTools` set declared to the realtime model at session mint. The server\n   * only DECLARES these — execution stays in the browser via {@link ApplyAgentTool}.\n   */\n  public abstract GetToolDefinitions(): RealtimeToolDefinition[];\n\n  /**\n   * Executes ONE agent tool call locally (the ACTION direction) and returns the result\n   * JSON string fed back to the model as the `tool_response`. Called for every tool whose\n   * name starts with {@link ToolNamePrefix}. Must work both WITH a bound surface (apply +\n   * UI garnish) and WITHOUT one (apply to the state engine directly — the tab pane may not\n   * exist, e.g. the surface panel is collapsed). Should not throw: return a\n   * `{ success: false, error }` payload so the model can narrate the failure (the host\n   * additionally wraps anything thrown).\n   */\n  public abstract ApplyAgentTool(toolName: string, argsJson: string): string | Promise<string>;\n\n  /**\n   * The Angular component the overlay creates dynamically as this channel's tab pane, or `null`\n   * for a **server-only** channel that renders no MJ surface (its surface, if any, lives on the\n   * external platform — e.g. a bridge-contributed native whiteboard or meeting-controls channel).\n   *\n   * When this returns `null`, the overlay renders NO tab for the channel and never calls\n   * {@link BindSurface}/{@link UnbindSurface} — but the channel's tools ({@link GetToolDefinitions} /\n   * {@link ApplyAgentTool}) and perception ({@link RealtimeChannelContext.SendContextNote}) still run.\n   * A created surface instance is handed straight back via {@link BindSurface}; the host treats it as\n   * opaque.\n   *\n   * Default: `null` (server-only). A channel with a rendered surface overrides this to return its\n   * component type.\n   */\n  public GetSurfaceComponent(): Type<TSurface> | null {\n    return null;\n  }\n\n  /**\n   * Whether this channel has a rendered MJ surface ({@link GetSurfaceComponent} returns non-null).\n   * The overlay uses this to decide whether to register a surface tab; server-only channels are\n   * `false`. Override only if surface availability must be decided WITHOUT constructing the type\n   * (the default calls {@link GetSurfaceComponent} once).\n   */\n  public HasSurface(): boolean {\n    return this.GetSurfaceComponent() != null;\n  }\n\n  /**\n   * The channel's FIRST-RUN INTRO content, or `null` when the channel offers no onboarding.\n   * The overlay shows this once per channel per user — the first time the user opens this\n   * channel's surface tab — and remembers \"seen\" via the user's settings (NOT localStorage),\n   * so it never re-appears on later sessions or other devices.\n   *\n   * Default: `null` (no intro). The base Voice/text channel has no plugin at all, so it never\n   * shows an intro; an interactive channel with a surface worth explaining (whiteboard, remote\n   * browser, …) overrides this to return its {@link ChannelOnboardingDetails}. A plugin that\n   * doesn't override it simply shows nothing — onboarding is strictly opt-in.\n   */\n  public GetOnboardingDetails(): ChannelOnboardingDetails | null {\n    return null;\n  }\n\n  /**\n   * Called by the host right after it created the surface component (and BEFORE the\n   * component's first change detection, so inputs set here are visible in its `ngOnInit`).\n   * The plugin — which knows its own component type — sets inputs (state engine, agent\n   * name, …) and subscribes outputs here, wiring perception/garnish flows back through\n   * {@link Context}. May be called again with a NEW instance after an\n   * {@link UnbindSurface} (the pane is destroyed/recreated with the tab panel).\n   */\n  public abstract BindSurface(instance: TSurface): void;\n\n  /**\n   * Called by the host when the surface component is being destroyed (tab panel\n   * collapsed / overlay torn down). Drop the instance reference and unsubscribe any\n   * output subscriptions — after this, {@link ApplyAgentTool} runs in its no-surface\n   * mode. Default: no-op.\n   */\n  public UnbindSurface(): void {\n    // default: nothing to release\n  }\n\n  /**\n   * Binds the host context and invokes the {@link OnInitialize} hook. Called exactly once\n   * per session, right after ClassFactory instantiation and before any tool call or\n   * surface bind.\n   */\n  public Initialize(ctx: RealtimeChannelContext): void {\n    this.Context = ctx;\n    this.OnInitialize();\n  }\n\n  /**\n   * Subclass hook invoked from {@link Initialize} once {@link Context} is bound — wire\n   * state-engine subscriptions (e.g. state change → `Context.RequestSave(...)`) here.\n   * Default: no-op.\n   */\n  protected OnInitialize(): void {\n    // default: nothing to initialize\n  }\n\n  /**\n   * Serializes the channel's current state of record (the payload persisted on the\n   * session's channel row), or `null` when the channel keeps no persistent state.\n   * Default: `null`.\n   */\n  public SerializeState(): string | null {\n    return null;\n  }\n\n  /**\n   * Restores a PRIOR session's saved channel state (the payload a previous session\n   * persisted via {@link SerializeState} / {@link RealtimeChannelContext.RequestSave}).\n   * Invoked by the session host AFTER {@link Initialize} and BEFORE any surface binding,\n   * when a prior session's saved state exists for this channel.\n   *\n   * Returns `true` when the state was applied; `false` when the channel ignored it —\n   * either because it keeps no persistent state (this default) or because the payload was\n   * malformed/incompatible. Implementations MUST be tolerant: never throw on bad input,\n   * just return `false` and start fresh.\n   */\n  public RestoreState(stateJson: string): boolean {\n    return false;\n  }\n\n  /**\n   * The focus pill's \"exit\" affordance, routed by the overlay to the channel that holds\n   * focus. Implementations should leave focus mode through their OWN surface (so surface\n   * toggles stay in sync), ultimately emitting `Context.SetFocusMode(false)`. The overlay\n   * defensively clears its layout flag as well, so a no-op default is safe.\n   */\n  public RequestFocusExit(): void {\n    // default: the overlay's defensive clear handles it\n  }\n\n  /**\n   * Tears the plugin down at session end: release the surface binding, unsubscribe\n   * state-engine subscriptions, then drop the context. Subclasses overriding this MUST\n   * call `super.Dispose()`. Any final state save has already been flushed by the host\n   * (the debounced {@link RealtimeChannelContext.RequestSave} pipeline) before disposal.\n   */\n  public Dispose(): void {\n    this.UnbindSurface();\n    this.Context = null;\n  }\n}\n"]}

package/dist/lib/components/realtime/channels/channel-onboarding-panel.component.d.ts

@@ -0,0 +1,25 @@
+import { EventEmitter } from '@angular/core';
+import { ChannelOnboardingDetails } from './base-realtime-channel-client';
+import * as i0 from "@angular/core";
+/**
+ * The FIRST-RUN INTRO overlay for an interactive channel — a generic, channel-agnostic card
+ * the surface panel floats over a channel's pane the very first time a user opens that channel
+ * (whiteboard, remote browser, …). It renders whatever {@link ChannelOnboardingDetails} the
+ * channel plugin supplied (icon · heading · description · optional tips) and a single "Got it"
+ * action plus a small ✕ — both emit {@link Dismissed}, which the host uses to mark the channel
+ * seen (per user, via the user's settings) and hide the panel.
+ *
+ * This component owns NO persistence or channel knowledge: it's a pure presenter wired by
+ * `RealtimeSurfaceTabsComponent`, so it stays reusable for any current or future channel. When
+ * {@link Content} is `null` it renders nothing (the host already gates on that, but the guard
+ * keeps the component safe to drop in unconditionally).
+ */
+export declare class ChannelOnboardingPanelComponent {
+    /** The intro content to present, or `null` to render nothing. */
+    Content: ChannelOnboardingDetails | null;
+    /** Emitted when the user dismisses the intro (the "Got it" button or the ✕). */
+    Dismissed: EventEmitter<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ChannelOnboardingPanelComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ChannelOnboardingPanelComponent, "mj-channel-onboarding-panel", never, { "Content": { "alias": "Content"; "required": false; }; }, { "Dismissed": "Dismissed"; }, never, never, true, never>;
+}
+//# sourceMappingURL=channel-onboarding-panel.component.d.ts.map

package/dist/lib/components/realtime/channels/channel-onboarding-panel.component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-onboarding-panel.component.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/realtime/channels/channel-onboarding-panel.component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,YAAY,EAAiB,MAAM,eAAe,CAAC;AAEvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;;AAE1E;;;;;;;;;;;;GAYG;AACH,qBAgJa,+BAA+B;IAC1C,iEAAiE;IACxD,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAAQ;IAEzD,gFAAgF;IACtE,SAAS,qBAA4B;yCALpC,+BAA+B;2CAA/B,+BAA+B;CAM3C"}

package/dist/lib/components/realtime/channels/channel-onboarding-panel.component.js

@@ -0,0 +1,140 @@
+import { Component, EventEmitter, Input, Output } from '@angular/core';
+import { MJButtonDirective } from '@memberjunction/ng-ui-components';
+import * as i0 from "@angular/core";
+function ChannelOnboardingPanelComponent_Conditional_0_Conditional_4_Template(rf, ctx) { if (rf & 1) {
+    i0.ɵɵelementStart(0, "div", 4);
+    i0.ɵɵelement(1, "i");
+    i0.ɵɵelementEnd();
+} if (rf & 2) {
+    const content_r3 = i0.ɵɵnextContext();
+    i0.ɵɵadvance();
+    i0.ɵɵclassMap(content_r3.IconClass);
+} }
+function ChannelOnboardingPanelComponent_Conditional_0_Conditional_9_For_2_Template(rf, ctx) { if (rf & 1) {
+    i0.ɵɵelementStart(0, "li", 10);
+    i0.ɵɵelement(1, "i", 11);
+    i0.ɵɵelementStart(2, "span");
+    i0.ɵɵtext(3);
+    i0.ɵɵelementEnd()();
+} if (rf & 2) {
+    const tip_r4 = ctx.$implicit;
+    i0.ɵɵadvance(3);
+    i0.ɵɵtextInterpolate(tip_r4);
+} }
+function ChannelOnboardingPanelComponent_Conditional_0_Conditional_9_Template(rf, ctx) { if (rf & 1) {
+    i0.ɵɵelementStart(0, "ul", 7);
+    i0.ɵɵrepeaterCreate(1, ChannelOnboardingPanelComponent_Conditional_0_Conditional_9_For_2_Template, 4, 1, "li", 10, i0.ɵɵrepeaterTrackByIdentity);
+    i0.ɵɵelementEnd();
+} if (rf & 2) {
+    const content_r3 = i0.ɵɵnextContext();
+    i0.ɵɵadvance();
+    i0.ɵɵrepeater(content_r3.Tips);
+} }
+function ChannelOnboardingPanelComponent_Conditional_0_Template(rf, ctx) { if (rf & 1) {
+    const _r1 = i0.ɵɵgetCurrentView();
+    i0.ɵɵelementStart(0, "div", 0)(1, "div", 1)(2, "button", 2);
+    i0.ɵɵlistener("click", function ChannelOnboardingPanelComponent_Conditional_0_Template_button_click_2_listener() { i0.ɵɵrestoreView(_r1); const ctx_r1 = i0.ɵɵnextContext(); return i0.ɵɵresetView(ctx_r1.Dismissed.emit()); });
+    i0.ɵɵelement(3, "i", 3);
+    i0.ɵɵelementEnd();
+    i0.ɵɵconditionalCreate(4, ChannelOnboardingPanelComponent_Conditional_0_Conditional_4_Template, 2, 2, "div", 4);
+    i0.ɵɵelementStart(5, "h3", 5);
+    i0.ɵɵtext(6);
+    i0.ɵɵelementEnd();
+    i0.ɵɵelementStart(7, "p", 6);
+    i0.ɵɵtext(8);
+    i0.ɵɵelementEnd();
+    i0.ɵɵconditionalCreate(9, ChannelOnboardingPanelComponent_Conditional_0_Conditional_9_Template, 3, 0, "ul", 7);
+    i0.ɵɵelementStart(10, "div", 8)(11, "button", 9);
+    i0.ɵɵlistener("click", function ChannelOnboardingPanelComponent_Conditional_0_Template_button_click_11_listener() { i0.ɵɵrestoreView(_r1); const ctx_r1 = i0.ɵɵnextContext(); return i0.ɵɵresetView(ctx_r1.Dismissed.emit()); });
+    i0.ɵɵtext(12, " Got it ");
+    i0.ɵɵelementEnd()()()();
+} if (rf & 2) {
+    const content_r3 = ctx;
+    i0.ɵɵattribute("aria-label", content_r3.Heading);
+    i0.ɵɵadvance(4);
+    i0.ɵɵconditional(content_r3.IconClass ? 4 : -1);
+    i0.ɵɵadvance(2);
+    i0.ɵɵtextInterpolate(content_r3.Heading);
+    i0.ɵɵadvance(2);
+    i0.ɵɵtextInterpolate(content_r3.Description);
+    i0.ɵɵadvance();
+    i0.ɵɵconditional((content_r3.Tips == null ? null : content_r3.Tips.length) ? 9 : -1);
+    i0.ɵɵadvance(2);
+    i0.ɵɵproperty("variant", "primary");
+} }
+/**
+ * The FIRST-RUN INTRO overlay for an interactive channel — a generic, channel-agnostic card
+ * the surface panel floats over a channel's pane the very first time a user opens that channel
+ * (whiteboard, remote browser, …). It renders whatever {@link ChannelOnboardingDetails} the
+ * channel plugin supplied (icon · heading · description · optional tips) and a single "Got it"
+ * action plus a small ✕ — both emit {@link Dismissed}, which the host uses to mark the channel
+ * seen (per user, via the user's settings) and hide the panel.
+ *
+ * This component owns NO persistence or channel knowledge: it's a pure presenter wired by
+ * `RealtimeSurfaceTabsComponent`, so it stays reusable for any current or future channel. When
+ * {@link Content} is `null` it renders nothing (the host already gates on that, but the guard
+ * keeps the component safe to drop in unconditionally).
+ */
+export class ChannelOnboardingPanelComponent {
+    /** The intro content to present, or `null` to render nothing. */
+    Content = null;
+    /** Emitted when the user dismisses the intro (the "Got it" button or the ✕). */
+    Dismissed = new EventEmitter();
+    static ɵfac = function ChannelOnboardingPanelComponent_Factory(__ngFactoryType__) { return new (__ngFactoryType__ || ChannelOnboardingPanelComponent)(); };
+    static ɵcmp = /*@__PURE__*/ i0.ɵɵdefineComponent({ type: ChannelOnboardingPanelComponent, selectors: [["mj-channel-onboarding-panel"]], inputs: { Content: "Content" }, outputs: { Dismissed: "Dismissed" }, decls: 1, vars: 1, consts: [["role", "dialog", "aria-modal", "false", 1, "onboarding"], [1, "onboarding__card"], ["type", "button", "title", "Dismiss", "aria-label", "Dismiss", 1, "onboarding__close", 3, "click"], ["aria-hidden", "true", 1, "fa-solid", "fa-xmark"], ["aria-hidden", "true", 1, "onboarding__icon"], [1, "onboarding__heading"], [1, "onboarding__description"], [1, "onboarding__tips"], [1, "onboarding__actions"], ["mjButton", "", "type", "button", 3, "click", "variant"], [1, "onboarding__tip"], ["aria-hidden", "true", 1, "fa-solid", "fa-check"]], template: function ChannelOnboardingPanelComponent_Template(rf, ctx) { if (rf & 1) {
+            i0.ɵɵconditionalCreate(0, ChannelOnboardingPanelComponent_Conditional_0_Template, 13, 6, "div", 0);
+        } if (rf & 2) {
+            let tmp_0_0;
+            i0.ɵɵconditional((tmp_0_0 = ctx.Content) ? 0 : -1, tmp_0_0);
+        } }, dependencies: [MJButtonDirective], styles: ["[_nghost-%COMP%] {\n      position: absolute;\n      inset: 0;\n      display: block;\n      z-index: 5;\n    }\n    .onboarding[_ngcontent-%COMP%] {\n      position: absolute;\n      inset: 0;\n      display: flex;\n      align-items: center;\n      justify-content: center;\n      padding: 1.5rem;\n      \n\n      background: color-mix(in srgb, var(--mj-bg-overlay) 55%, transparent);\n    }\n    .onboarding__card[_ngcontent-%COMP%] {\n      position: relative;\n      width: 100%;\n      max-width: 24rem;\n      padding: 1.75rem 1.5rem 1.5rem;\n      border: 1px solid var(--mj-border-default);\n      border-radius: var(--mj-radius-lg, 12px);\n      background: var(--mj-bg-surface);\n      box-shadow: 0 12px 32px color-mix(in srgb, var(--mj-bg-overlay) 35%, transparent);\n      text-align: center;\n    }\n    .onboarding__close[_ngcontent-%COMP%] {\n      position: absolute;\n      top: 0.5rem;\n      right: 0.5rem;\n      width: 1.75rem;\n      height: 1.75rem;\n      display: inline-flex;\n      align-items: center;\n      justify-content: center;\n      border: none;\n      border-radius: var(--mj-radius-full, 999px);\n      background: transparent;\n      color: var(--mj-text-muted);\n      cursor: pointer;\n      transition: background 0.15s ease, color 0.15s ease;\n    }\n    .onboarding__close[_ngcontent-%COMP%]:hover {\n      background: var(--mj-bg-surface-hover);\n      color: var(--mj-text-primary);\n    }\n    .onboarding__icon[_ngcontent-%COMP%] {\n      width: 3rem;\n      height: 3rem;\n      margin: 0 auto 0.75rem;\n      display: inline-flex;\n      align-items: center;\n      justify-content: center;\n      border-radius: var(--mj-radius-full, 999px);\n      font-size: 1.35rem;\n      color: var(--mj-brand-primary);\n      background: color-mix(in srgb, var(--mj-brand-primary) 12%, var(--mj-bg-surface-card));\n    }\n    .onboarding__heading[_ngcontent-%COMP%] {\n      margin: 0 0 0.4rem;\n      font-size: 1.15rem;\n      font-weight: 600;\n      color: var(--mj-text-primary);\n    }\n    .onboarding__description[_ngcontent-%COMP%] {\n      margin: 0;\n      font-size: 0.9rem;\n      line-height: 1.45;\n      color: var(--mj-text-secondary);\n    }\n    .onboarding__tips[_ngcontent-%COMP%] {\n      margin: 1rem 0 0;\n      padding: 0;\n      list-style: none;\n      text-align: left;\n    }\n    .onboarding__tip[_ngcontent-%COMP%] {\n      display: flex;\n      align-items: flex-start;\n      gap: 0.5rem;\n      padding: 0.3rem 0;\n      font-size: 0.85rem;\n      line-height: 1.4;\n      color: var(--mj-text-secondary);\n    }\n    .onboarding__tip[_ngcontent-%COMP%]   i[_ngcontent-%COMP%] {\n      margin-top: 0.18rem;\n      font-size: 0.75rem;\n      color: var(--mj-brand-primary);\n    }\n    .onboarding__actions[_ngcontent-%COMP%] {\n      margin-top: 1.25rem;\n      display: flex;\n      justify-content: center;\n    }"] });
+}
+(() => { (typeof ngDevMode === "undefined" || ngDevMode) && i0.ɵsetClassMetadata(ChannelOnboardingPanelComponent, [{
+        type: Component,
+        args: [{ standalone: true, selector: 'mj-channel-onboarding-panel', imports: [MJButtonDirective], template: `
+    @if (Content; as content) {
+      <div class="onboarding" role="dialog" aria-modal="false" [attr.aria-label]="content.Heading">
+        <div class="onboarding__card">
+          <button type="button"
+                  class="onboarding__close"
+                  (click)="Dismissed.emit()"
+                  title="Dismiss"
+                  aria-label="Dismiss">
+            <i class="fa-solid fa-xmark" aria-hidden="true"></i>
+          </button>
+
+          @if (content.IconClass) {
+            <div class="onboarding__icon" aria-hidden="true">
+              <i [class]="content.IconClass"></i>
+            </div>
+          }
+
+          <h3 class="onboarding__heading">{{ content.Heading }}</h3>
+          <p class="onboarding__description">{{ content.Description }}</p>
+
+          @if (content.Tips?.length) {
+            <ul class="onboarding__tips">
+              @for (tip of content.Tips; track tip) {
+                <li class="onboarding__tip">
+                  <i class="fa-solid fa-check" aria-hidden="true"></i>
+                  <span>{{ tip }}</span>
+                </li>
+              }
+            </ul>
+          }
+
+          <div class="onboarding__actions">
+            <button mjButton [variant]="'primary'" type="button" (click)="Dismissed.emit()">
+              Got it
+            </button>
+          </div>
+        </div>
+      </div>
+    }
+  `, styles: ["\n    :host {\n      position: absolute;\n      inset: 0;\n      display: block;\n      z-index: 5;\n    }\n    .onboarding {\n      position: absolute;\n      inset: 0;\n      display: flex;\n      align-items: center;\n      justify-content: center;\n      padding: 1.5rem;\n      /* Translucent backdrop over the channel pane \u2014 token-derived, no hardcoded colors. */\n      background: color-mix(in srgb, var(--mj-bg-overlay) 55%, transparent);\n    }\n    .onboarding__card {\n      position: relative;\n      width: 100%;\n      max-width: 24rem;\n      padding: 1.75rem 1.5rem 1.5rem;\n      border: 1px solid var(--mj-border-default);\n      border-radius: var(--mj-radius-lg, 12px);\n      background: var(--mj-bg-surface);\n      box-shadow: 0 12px 32px color-mix(in srgb, var(--mj-bg-overlay) 35%, transparent);\n      text-align: center;\n    }\n    .onboarding__close {\n      position: absolute;\n      top: 0.5rem;\n      right: 0.5rem;\n      width: 1.75rem;\n      height: 1.75rem;\n      display: inline-flex;\n      align-items: center;\n      justify-content: center;\n      border: none;\n      border-radius: var(--mj-radius-full, 999px);\n      background: transparent;\n      color: var(--mj-text-muted);\n      cursor: pointer;\n      transition: background 0.15s ease, color 0.15s ease;\n    }\n    .onboarding__close:hover {\n      background: var(--mj-bg-surface-hover);\n      color: var(--mj-text-primary);\n    }\n    .onboarding__icon {\n      width: 3rem;\n      height: 3rem;\n      margin: 0 auto 0.75rem;\n      display: inline-flex;\n      align-items: center;\n      justify-content: center;\n      border-radius: var(--mj-radius-full, 999px);\n      font-size: 1.35rem;\n      color: var(--mj-brand-primary);\n      background: color-mix(in srgb, var(--mj-brand-primary) 12%, var(--mj-bg-surface-card));\n    }\n    .onboarding__heading {\n      margin: 0 0 0.4rem;\n      font-size: 1.15rem;\n      font-weight: 600;\n      color: var(--mj-text-primary);\n    }\n    .onboarding__description {\n      margin: 0;\n      font-size: 0.9rem;\n      line-height: 1.45;\n      color: var(--mj-text-secondary);\n    }\n    .onboarding__tips {\n      margin: 1rem 0 0;\n      padding: 0;\n      list-style: none;\n      text-align: left;\n    }\n    .onboarding__tip {\n      display: flex;\n      align-items: flex-start;\n      gap: 0.5rem;\n      padding: 0.3rem 0;\n      font-size: 0.85rem;\n      line-height: 1.4;\n      color: var(--mj-text-secondary);\n    }\n    .onboarding__tip i {\n      margin-top: 0.18rem;\n      font-size: 0.75rem;\n      color: var(--mj-brand-primary);\n    }\n    .onboarding__actions {\n      margin-top: 1.25rem;\n      display: flex;\n      justify-content: center;\n    }\n  "] }]
+    }], null, { Content: [{
+            type: Input
+        }], Dismissed: [{
+            type: Output
+        }] }); })();
+(() => { (typeof ngDevMode === "undefined" || ngDevMode) && i0.ɵsetClassDebugInfo(ChannelOnboardingPanelComponent, { className: "ChannelOnboardingPanelComponent", filePath: "src/lib/components/realtime/channels/channel-onboarding-panel.component.ts", lineNumber: 162 }); })();
+//# sourceMappingURL=channel-onboarding-panel.component.js.map

package/dist/lib/components/realtime/channels/channel-onboarding-panel.component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-onboarding-panel.component.js","sourceRoot":"","sources":["../../../../../src/lib/components/realtime/channels/channel-onboarding-panel.component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;;;IAiCzD,8BAAiD;IAC/C,oBAAmC;IACrC,iBAAM;;;IADD,cAA2B;IAA3B,mCAA2B;;;IAU5B,8BAA4B;IAC1B,wBAAoD;IACpD,4BAAM;IAAA,YAAS;IACjB,AADiB,iBAAO,EACnB;;;IADG,eAAS;IAAT,4BAAS;;;IAJrB,6BAA6B;IAC3B,gJAKC;IACH,iBAAK;;;IANH,cAKC;IALD,8BAKC;;;;IAxBL,AADF,AADF,8BAA6F,aAC7D,gBAKC;IAFrB,mMAAS,uBAAgB,KAAC;IAGhC,uBAAoD;IACtD,iBAAS;IAET,+GAAyB;IAMzB,6BAAgC;IAAA,YAAqB;IAAA,iBAAK;IAC1D,4BAAmC;IAAA,YAAyB;IAAA,iBAAI;IAEhE,8GAA4B;IAY1B,AADF,+BAAiC,iBACiD;IAA3B,oMAAS,uBAAgB,KAAC;IAC7E,yBACF;IAGN,AADE,AADE,AADE,iBAAS,EACL,EACF,EACF;;;;IA1BF,eAIC;IAJD,+CAIC;IAE+B,eAAqB;IAArB,wCAAqB;IAClB,eAAyB;IAAzB,4CAAyB;IAE5D,cASC;IATD,oFASC;IAGkB,eAAqB;IAArB,mCAAqB;;AAlDlD;;;;;;;;;;;;GAYG;AAiJH,MAAM,OAAO,+BAA+B;IAC1C,iEAAiE;IACxD,OAAO,GAAoC,IAAI,CAAC;IAEzD,gFAAgF;IACtE,SAAS,GAAG,IAAI,YAAY,EAAQ,CAAC;yHALpC,+BAA+B;6DAA/B,+BAA+B;YA3IxC,kGAA2B;;;YAA3B,2DAsCC;4BAxCO,iBAAiB;;iFA6IhB,+BAA+B;cAhJ3C,SAAS;6BACI,IAAI,YACN,6BAA6B,WAC9B,CAAC,iBAAiB,CAAC,YAClB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCT;;kBAsGA,KAAK;;kBAGL,MAAM;;kFALI,+BAA+B","sourcesContent":["import { Component, EventEmitter, Input, Output } from '@angular/core';\nimport { MJButtonDirective } from '@memberjunction/ng-ui-components';\nimport { ChannelOnboardingDetails } from './base-realtime-channel-client';\n\n/**\n * The FIRST-RUN INTRO overlay for an interactive channel — a generic, channel-agnostic card\n * the surface panel floats over a channel's pane the very first time a user opens that channel\n * (whiteboard, remote browser, …). It renders whatever {@link ChannelOnboardingDetails} the\n * channel plugin supplied (icon · heading · description · optional tips) and a single \"Got it\"\n * action plus a small ✕ — both emit {@link Dismissed}, which the host uses to mark the channel\n * seen (per user, via the user's settings) and hide the panel.\n *\n * This component owns NO persistence or channel knowledge: it's a pure presenter wired by\n * `RealtimeSurfaceTabsComponent`, so it stays reusable for any current or future channel. When\n * {@link Content} is `null` it renders nothing (the host already gates on that, but the guard\n * keeps the component safe to drop in unconditionally).\n */\n@Component({\n  standalone: true,\n  selector: 'mj-channel-onboarding-panel',\n  imports: [MJButtonDirective],\n  template: `\n    @if (Content; as content) {\n      <div class=\"onboarding\" role=\"dialog\" aria-modal=\"false\" [attr.aria-label]=\"content.Heading\">\n        <div class=\"onboarding__card\">\n          <button type=\"button\"\n                  class=\"onboarding__close\"\n                  (click)=\"Dismissed.emit()\"\n                  title=\"Dismiss\"\n                  aria-label=\"Dismiss\">\n            <i class=\"fa-solid fa-xmark\" aria-hidden=\"true\"></i>\n          </button>\n\n          @if (content.IconClass) {\n            <div class=\"onboarding__icon\" aria-hidden=\"true\">\n              <i [class]=\"content.IconClass\"></i>\n            </div>\n          }\n\n          <h3 class=\"onboarding__heading\">{{ content.Heading }}</h3>\n          <p class=\"onboarding__description\">{{ content.Description }}</p>\n\n          @if (content.Tips?.length) {\n            <ul class=\"onboarding__tips\">\n              @for (tip of content.Tips; track tip) {\n                <li class=\"onboarding__tip\">\n                  <i class=\"fa-solid fa-check\" aria-hidden=\"true\"></i>\n                  <span>{{ tip }}</span>\n                </li>\n              }\n            </ul>\n          }\n\n          <div class=\"onboarding__actions\">\n            <button mjButton [variant]=\"'primary'\" type=\"button\" (click)=\"Dismissed.emit()\">\n              Got it\n            </button>\n          </div>\n        </div>\n      </div>\n    }\n  `,\n  styles: [`\n    :host {\n      position: absolute;\n      inset: 0;\n      display: block;\n      z-index: 5;\n    }\n    .onboarding {\n      position: absolute;\n      inset: 0;\n      display: flex;\n      align-items: center;\n      justify-content: center;\n      padding: 1.5rem;\n      /* Translucent backdrop over the channel pane — token-derived, no hardcoded colors. */\n      background: color-mix(in srgb, var(--mj-bg-overlay) 55%, transparent);\n    }\n    .onboarding__card {\n      position: relative;\n      width: 100%;\n      max-width: 24rem;\n      padding: 1.75rem 1.5rem 1.5rem;\n      border: 1px solid var(--mj-border-default);\n      border-radius: var(--mj-radius-lg, 12px);\n      background: var(--mj-bg-surface);\n      box-shadow: 0 12px 32px color-mix(in srgb, var(--mj-bg-overlay) 35%, transparent);\n      text-align: center;\n    }\n    .onboarding__close {\n      position: absolute;\n      top: 0.5rem;\n      right: 0.5rem;\n      width: 1.75rem;\n      height: 1.75rem;\n      display: inline-flex;\n      align-items: center;\n      justify-content: center;\n      border: none;\n      border-radius: var(--mj-radius-full, 999px);\n      background: transparent;\n      color: var(--mj-text-muted);\n      cursor: pointer;\n      transition: background 0.15s ease, color 0.15s ease;\n    }\n    .onboarding__close:hover {\n      background: var(--mj-bg-surface-hover);\n      color: var(--mj-text-primary);\n    }\n    .onboarding__icon {\n      width: 3rem;\n      height: 3rem;\n      margin: 0 auto 0.75rem;\n      display: inline-flex;\n      align-items: center;\n      justify-content: center;\n      border-radius: var(--mj-radius-full, 999px);\n      font-size: 1.35rem;\n      color: var(--mj-brand-primary);\n      background: color-mix(in srgb, var(--mj-brand-primary) 12%, var(--mj-bg-surface-card));\n    }\n    .onboarding__heading {\n      margin: 0 0 0.4rem;\n      font-size: 1.15rem;\n      font-weight: 600;\n      color: var(--mj-text-primary);\n    }\n    .onboarding__description {\n      margin: 0;\n      font-size: 0.9rem;\n      line-height: 1.45;\n      color: var(--mj-text-secondary);\n    }\n    .onboarding__tips {\n      margin: 1rem 0 0;\n      padding: 0;\n      list-style: none;\n      text-align: left;\n    }\n    .onboarding__tip {\n      display: flex;\n      align-items: flex-start;\n      gap: 0.5rem;\n      padding: 0.3rem 0;\n      font-size: 0.85rem;\n      line-height: 1.4;\n      color: var(--mj-text-secondary);\n    }\n    .onboarding__tip i {\n      margin-top: 0.18rem;\n      font-size: 0.75rem;\n      color: var(--mj-brand-primary);\n    }\n    .onboarding__actions {\n      margin-top: 1.25rem;\n      display: flex;\n      justify-content: center;\n    }\n  `]\n})\nexport class ChannelOnboardingPanelComponent {\n  /** The intro content to present, or `null` to render nothing. */\n  @Input() Content: ChannelOnboardingDetails | null = null;\n\n  /** Emitted when the user dismisses the intro (the \"Got it\" button or the ✕). */\n  @Output() Dismissed = new EventEmitter<void>();\n}\n"]}

package/dist/lib/components/realtime/channels/realtime-channel-pane.component.d.ts

@@ -0,0 +1,35 @@
+import { OnDestroy, OnInit } from '@angular/core';
+import { BaseRealtimeChannelClient } from './base-realtime-channel-client';
+import * as i0 from "@angular/core";
+/**
+ * Generic pane host for an interactive channel's surface inside the overlay's tabbed
+ * surface panel. Given the per-session channel {@link Plugin}, it:
+ *
+ *  1. dynamically creates the plugin's surface component
+ *     ({@link BaseRealtimeChannelClient.GetSurfaceComponent}) into its own view container;
+ *  2. immediately hands the created instance to
+ *     {@link BaseRealtimeChannelClient.BindSurface} — synchronously, BEFORE the surface's
+ *     first change detection, so inputs the plugin sets are visible in its `ngOnInit`;
+ *  3. notifies {@link BaseRealtimeChannelClient.UnbindSurface} when the pane is destroyed
+ *     (panel collapsed / overlay torn down), flipping the plugin back into its
+ *     no-surface tool-execution mode.
+ *
+ * This is how channel surfaces render with ZERO channel-specific wiring in the overlay:
+ * the host never knows the surface component's type or API — the plugin wires its own
+ * inputs/outputs in `BindSurface`.
+ *
+ * The created component is inserted as a SIBLING of this host element (standard
+ * `ViewContainerRef` semantics), so it participates directly in the pane's flex layout;
+ * the host element itself renders nothing (`display: none`).
+ */
+export declare class RealtimeChannelPaneComponent implements OnInit, OnDestroy {
+    /** The per-session channel plugin whose surface this pane hosts. */
+    Plugin: BaseRealtimeChannelClient;
+    private viewContainer;
+    private surfaceRef;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RealtimeChannelPaneComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<RealtimeChannelPaneComponent, "mj-realtime-channel-pane", never, { "Plugin": { "alias": "Plugin"; "required": true; }; }, {}, never, never, true, never>;
+}
+//# sourceMappingURL=realtime-channel-pane.component.d.ts.map

package/dist/lib/components/realtime/channels/realtime-channel-pane.component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-channel-pane.component.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/realtime/channels/realtime-channel-pane.component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,SAAS,EAAE,MAAM,EAA4B,MAAM,eAAe,CAAC;AAC5G,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;;AAE3E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAMa,4BAA6B,YAAW,MAAM,EAAE,SAAS;IACpE,oEAAoE;IACzC,MAAM,EAAG,yBAAyB,CAAC;IAE9D,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,UAAU,CAAqC;IAEvD,QAAQ,IAAI,IAAI;IAchB,WAAW,IAAI,IAAI;yCArBR,4BAA4B;2CAA5B,4BAA4B;CA0BxC"}

package/dist/lib/components/realtime/channels/realtime-channel-pane.component.js

@@ -0,0 +1,58 @@
+import { Component, Input, ViewContainerRef, inject } from '@angular/core';
+import * as i0 from "@angular/core";
+/**
+ * Generic pane host for an interactive channel's surface inside the overlay's tabbed
+ * surface panel. Given the per-session channel {@link Plugin}, it:
+ *
+ *  1. dynamically creates the plugin's surface component
+ *     ({@link BaseRealtimeChannelClient.GetSurfaceComponent}) into its own view container;
+ *  2. immediately hands the created instance to
+ *     {@link BaseRealtimeChannelClient.BindSurface} — synchronously, BEFORE the surface's
+ *     first change detection, so inputs the plugin sets are visible in its `ngOnInit`;
+ *  3. notifies {@link BaseRealtimeChannelClient.UnbindSurface} when the pane is destroyed
+ *     (panel collapsed / overlay torn down), flipping the plugin back into its
+ *     no-surface tool-execution mode.
+ *
+ * This is how channel surfaces render with ZERO channel-specific wiring in the overlay:
+ * the host never knows the surface component's type or API — the plugin wires its own
+ * inputs/outputs in `BindSurface`.
+ *
+ * The created component is inserted as a SIBLING of this host element (standard
+ * `ViewContainerRef` semantics), so it participates directly in the pane's flex layout;
+ * the host element itself renders nothing (`display: none`).
+ */
+export class RealtimeChannelPaneComponent {
+    /** The per-session channel plugin whose surface this pane hosts. */
+    Plugin;
+    viewContainer = inject(ViewContainerRef);
+    surfaceRef = null;
+    ngOnInit() {
+        // Server-only channels have no surface (GetSurfaceComponent === null). The overlay should not
+        // register a pane for them, but guard here too so a stray registration never crashes the panel.
+        const surface = this.Plugin.GetSurfaceComponent();
+        if (!surface) {
+            return;
+        }
+        this.surfaceRef = this.viewContainer.createComponent(surface);
+        // Bind BEFORE the created component's first change detection — inputs the plugin sets
+        // here are in place when the surface's ngOnInit runs.
+        this.Plugin.BindSurface(this.surfaceRef.instance);
+        this.surfaceRef.changeDetectorRef.markForCheck();
+    }
+    ngOnDestroy() {
+        this.Plugin.UnbindSurface();
+        this.surfaceRef?.destroy();
+        this.surfaceRef = null;
+    }
+    static ɵfac = function RealtimeChannelPaneComponent_Factory(__ngFactoryType__) { return new (__ngFactoryType__ || RealtimeChannelPaneComponent)(); };
+    static ɵcmp = /*@__PURE__*/ i0.ɵɵdefineComponent({ type: RealtimeChannelPaneComponent, selectors: [["mj-realtime-channel-pane"]], inputs: { Plugin: "Plugin" }, decls: 0, vars: 0, template: function RealtimeChannelPaneComponent_Template(rf, ctx) { }, styles: ["[_nghost-%COMP%] { display: none; }"] });
+}
+(() => { (typeof ngDevMode === "undefined" || ngDevMode) && i0.ɵsetClassMetadata(RealtimeChannelPaneComponent, [{
+        type: Component,
+        args: [{ standalone: true, selector: 'mj-realtime-channel-pane', template: '', styles: [":host { display: none; }"] }]
+    }], null, { Plugin: [{
+            type: Input,
+            args: [{ required: true }]
+        }] }); })();
+(() => { (typeof ngDevMode === "undefined" || ngDevMode) && i0.ɵsetClassDebugInfo(RealtimeChannelPaneComponent, { className: "RealtimeChannelPaneComponent", filePath: "src/lib/components/realtime/channels/realtime-channel-pane.component.ts", lineNumber: 31 }); })();
+//# sourceMappingURL=realtime-channel-pane.component.js.map

package/dist/lib/components/realtime/channels/realtime-channel-pane.component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-channel-pane.component.js","sourceRoot":"","sources":["../../../../../src/lib/components/realtime/channels/realtime-channel-pane.component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAgB,KAAK,EAAqB,gBAAgB,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;;AAG5G;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,MAAM,OAAO,4BAA4B;IACvC,oEAAoE;IACzC,MAAM,CAA6B;IAEtD,aAAa,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACzC,UAAU,GAAgC,IAAI,CAAC;IAEvD,QAAQ;QACN,8FAA8F;QAC9F,gGAAgG;QAChG,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAClD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO;QACT,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAC9D,sFAAsF;QACtF,sDAAsD;QACtD,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAClD,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,YAAY,EAAE,CAAC;IACnD,CAAC;IAED,WAAW;QACT,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;QAC5B,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;sHAzBU,4BAA4B;6DAA5B,4BAA4B;;iFAA5B,4BAA4B;cANxC,SAAS;6BACI,IAAI,YACN,0BAA0B,YAC1B,EAAE;;kBAKX,KAAK;mBAAC,EAAE,QAAQ,EAAE,IAAI,EAAE;;kFAFd,4BAA4B","sourcesContent":["import { Component, ComponentRef, Input, OnDestroy, OnInit, ViewContainerRef, inject } from '@angular/core';\nimport { BaseRealtimeChannelClient } from './base-realtime-channel-client';\n\n/**\n * Generic pane host for an interactive channel's surface inside the overlay's tabbed\n * surface panel. Given the per-session channel {@link Plugin}, it:\n *\n *  1. dynamically creates the plugin's surface component\n *     ({@link BaseRealtimeChannelClient.GetSurfaceComponent}) into its own view container;\n *  2. immediately hands the created instance to\n *     {@link BaseRealtimeChannelClient.BindSurface} — synchronously, BEFORE the surface's\n *     first change detection, so inputs the plugin sets are visible in its `ngOnInit`;\n *  3. notifies {@link BaseRealtimeChannelClient.UnbindSurface} when the pane is destroyed\n *     (panel collapsed / overlay torn down), flipping the plugin back into its\n *     no-surface tool-execution mode.\n *\n * This is how channel surfaces render with ZERO channel-specific wiring in the overlay:\n * the host never knows the surface component's type or API — the plugin wires its own\n * inputs/outputs in `BindSurface`.\n *\n * The created component is inserted as a SIBLING of this host element (standard\n * `ViewContainerRef` semantics), so it participates directly in the pane's flex layout;\n * the host element itself renders nothing (`display: none`).\n */\n@Component({\n  standalone: true,\n  selector: 'mj-realtime-channel-pane',\n  template: '',\n  styles: [':host { display: none; }']\n})\nexport class RealtimeChannelPaneComponent implements OnInit, OnDestroy {\n  /** The per-session channel plugin whose surface this pane hosts. */\n  @Input({ required: true }) Plugin!: BaseRealtimeChannelClient;\n\n  private viewContainer = inject(ViewContainerRef);\n  private surfaceRef: ComponentRef<object> | null = null;\n\n  ngOnInit(): void {\n    // Server-only channels have no surface (GetSurfaceComponent === null). The overlay should not\n    // register a pane for them, but guard here too so a stray registration never crashes the panel.\n    const surface = this.Plugin.GetSurfaceComponent();\n    if (!surface) {\n      return;\n    }\n    this.surfaceRef = this.viewContainer.createComponent(surface);\n    // Bind BEFORE the created component's first change detection — inputs the plugin sets\n    // here are in place when the surface's ngOnInit runs.\n    this.Plugin.BindSurface(this.surfaceRef.instance);\n    this.surfaceRef.changeDetectorRef.markForCheck();\n  }\n\n  ngOnDestroy(): void {\n    this.Plugin.UnbindSurface();\n    this.surfaceRef?.destroy();\n    this.surfaceRef = null;\n  }\n}\n"]}

package/dist/lib/components/realtime/realtime-activity-rail.component.d.ts

@@ -0,0 +1,63 @@
+import { EventEmitter, OnInit, OnDestroy } from '@angular/core';
+import { RealtimeSessionState, RealtimeDelegationCardVM } from './realtime-session-state';
+import { ParsedDelegationArtifact } from '../../services/delegation-result-parser';
+import * as i0 from "@angular/core";
+/**
+ * The "Session activity" RIGHT RAIL of the call overlay: a compact, newest-first list
+ * of EVERY tool/agent call of the session — so parallel/multiple delegations live here
+ * and the conversation thread stays clean.
+ *
+ * Each entry shows agent name, status (Running w/ spinner | Done | Failed), the latest
+ * friendly step label, elapsed time for finished work, and a one-line result preview
+ * for done items. Active items are emphasized; finished items are dimmed.
+ *
+ * Collapsible via the chevron in its header (collapses to a slim toggle strip).
+ * Presentational over the same {@link RealtimeSessionState} the thread renders —
+ * no subscriptions of its own beyond the state's change notifications.
+ */
+export declare class RealtimeActivityRailComponent implements OnInit, OnDestroy {
+    /** Maximum characters of the result preview in a done card. */
+    private static readonly PreviewMaxChars;
+    /** Shared live-session state, owned by the overlay shell. */
+    State: RealtimeSessionState;
+    /** Whether developer affordances ("Open run" links) are revealed (gear-gated). */
+    DevMode: boolean;
+    /**
+     * EMBEDDED mode: the rail renders as the content of the surface panel's Activity tab —
+     * its own header/collapse chrome is hidden (the panel's tab strip owns collapse) and it
+     * stretches to the pane's full width. Default `false` keeps the original standalone
+     * right-rail presentation for any other consumer.
+     */
+    Embedded: boolean;
+    /** Emitted with the delegated run's ID when an entry's dev "Open run" link is clicked. */
+    OpenRunRequested: EventEmitter<string>;
+    /** Emitted when an entry's "View" artifact chip is clicked (focuses the artifact's tab). */
+    OpenArtifactRequested: EventEmitter<ParsedDelegationArtifact>;
+    /** Whether the rail is collapsed to its slim toggle strip. */
+    Collapsed: boolean;
+    private changedSub?;
+    private cdr;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    /** Toggle the rail between expanded and slim-collapsed. */
+    Toggle(): void;
+    /** track fn for the @for over cards. */
+    TrackCard(index: number, card: RealtimeDelegationCardVM): string;
+    /** Friendly label of the card's latest step. */
+    StepLabel(card: RealtimeDelegationCardVM): string;
+    /** Elapsed duration for finished work ("8s", "1m 04s"); null while running (kept cheap). */
+    Elapsed(card: RealtimeDelegationCardVM): string | null;
+    /** True when the dev "Open run" link should render for this card (gear on + run id known). */
+    ShowOpenRun(card: RealtimeDelegationCardVM): boolean;
+    /** Emits the open-run request for the card's delegated run. */
+    OpenRun(card: RealtimeDelegationCardVM): void;
+    /** The artifacts a done card carries (empty array when none — keeps the template simple). */
+    CardArtifacts(card: RealtimeDelegationCardVM): ParsedDelegationArtifact[];
+    /** Emits the open-artifact request for a card's produced artifact. */
+    OpenArtifact(artifact: ParsedDelegationArtifact): void;
+    /** One-line result preview for done items. */
+    Preview(card: RealtimeDelegationCardVM): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RealtimeActivityRailComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<RealtimeActivityRailComponent, "mj-realtime-activity-rail", never, { "State": { "alias": "State"; "required": true; }; "DevMode": { "alias": "DevMode"; "required": false; }; "Embedded": { "alias": "Embedded"; "required": false; }; }, { "OpenRunRequested": "OpenRunRequested"; "OpenArtifactRequested": "OpenArtifactRequested"; }, never, never, true, never>;
+}
+//# sourceMappingURL=realtime-activity-rail.component.d.ts.map

package/dist/lib/components/realtime/realtime-activity-rail.component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-activity-rail.component.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/realtime/realtime-activity-rail.component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,YAAY,EAAiB,MAAM,EAAE,SAAS,EAA6B,MAAM,eAAe,CAAC;AAGrH,OAAO,EACL,oBAAoB,EAAE,wBAAwB,EAC/C,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,wBAAwB,EAAE,MAAM,yCAAyC,CAAC;;AAEnF;;;;;;;;;;;;GAYG;AACH,qBAOa,6BAA8B,YAAW,MAAM,EAAE,SAAS;IACrE,+DAA+D;IAC/D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAM;IAE7C,6DAA6D;IAClC,KAAK,EAAG,oBAAoB,CAAC;IAExD,kFAAkF;IACzE,OAAO,UAAS;IAEzB;;;;;OAKG;IACM,QAAQ,UAAS;IAE1B,0FAA0F;IAChF,gBAAgB,uBAA8B;IAExD,4FAA4F;IAClF,qBAAqB,yCAAgD;IAE/E,8DAA8D;IACvD,SAAS,UAAS;IAEzB,OAAO,CAAC,UAAU,CAAC,CAAe;IAClC,OAAO,CAAC,GAAG,CAA6B;IAExC,QAAQ,IAAI,IAAI;IAIhB,WAAW,IAAI,IAAI;IAInB,2DAA2D;IACpD,MAAM,IAAI,IAAI;IAIrB,wCAAwC;IACjC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,wBAAwB,GAAG,MAAM;IAIvE,gDAAgD;IACzC,SAAS,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM;IAIxD,4FAA4F;IACrF,OAAO,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM,GAAG,IAAI;IAO7D,8FAA8F;IACvF,WAAW,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO;IAI3D,+DAA+D;IACxD,OAAO,CAAC,IAAI,EAAE,wBAAwB,GAAG,IAAI;IAMpD,6FAA6F;IACtF,aAAa,CAAC,IAAI,EAAE,wBAAwB,GAAG,wBAAwB,EAAE;IAIhF,sEAAsE;IAC/D,YAAY,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI;IAI7D,8CAA8C;IACvC,OAAO,CAAC,IAAI,EAAE,wBAAwB,GAAG,MAAM;yCApF3C,6BAA6B;2CAA7B,6BAA6B;CAyFzC"}