@memberjunction/ng-realtime-channels 0.0.0 → 6.2.0-edge.4

package/LICENSE

@@ -0,0 +1,183 @@
+Business Source License 1.1
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Blue Cypress, Inc.
+
+Licensed Work:        MemberJunction.
+                      The Licensed Work is (c) 2023-2026 Blue Cypress, Inc.
+
+Additional Use Grant: Subject to the terms of this License, Licensor grants
+                      you the following additional rights to make Production
+                      Use of the Licensed Work.
+
+                      1. Internal Use
+
+                      You may make production use of the Licensed Work for
+                      your own internal business or organizational operations.
+
+                      2. Nonprofit Use
+
+                      If you are a Nonprofit, you may make production use of
+                      the Licensed Work for the operations and activities of
+                      your Organizational Family.
+
+                      3. MemberJunction Certified Program Use
+
+                      If you are authorized by Licensor under the
+                      MemberJunction Certified Program to provide professional
+                      services using the Licensed Work, you may make
+                      production use of the Licensed Work in providing such
+                      professional services to a client, provided that:
+
+                      (a) the Licensed Work is deployed in, and the applicable
+                      production use occurs within, an environment owned,
+                      leased, licensed, subscribed to, or otherwise controlled
+                      by that client; and
+
+                      (b) the production use is for that client's own internal
+                      business or organizational operations or is otherwise
+                      independently permitted to that client under this
+                      Additional Use Grant.
+
+                      4. Definitions Applicable to the Additional Use Grant
+
+                      "Affiliate" means, with respect to a specified Person,
+                      any other Person that directly or indirectly Controls,
+                      is Controlled by, or is under common Control with such
+                      specified Person.
+
+                      "Control" (including the terms "Controls," "Controlled
+                      by," and "under common Control with") means the direct
+                      or indirect possession of the power to direct or cause
+                      the direction of the management and policies of a
+                      Person, whether through ownership of voting interests,
+                      by contract, or otherwise.
+
+                      "Organizational Family" means, with respect to a Person,
+                      (a) such Person and its Affiliates, and (b) any
+                      nonprofit organization, governmental entity, chapter,
+                      division, local affiliate, regional affiliate, state
+                      affiliate, national affiliate, or other entity that is
+                      formally affiliated with such Person through governing
+                      documents, a charter, bylaws, a membership agreement, or
+                      another written organizational instrument, and is
+                      recognized under such documents as part of the same
+                      organizational structure.
+
+                      "Nonprofit" means a Person recognized by the Internal
+                      Revenue Service as exempt from federal income taxation
+                      under Section 501(c)(3), 501(c)(4), 501(c)(5), or
+                      501(c)(6) of the Internal Revenue Code, or a foreign
+                      organization recognized under substantially equivalent
+                      laws.
+
+                      A Person claiming eligibility as a Nonprofit shall, upon
+                      Licensor's reasonable request, provide documentation
+                      reasonably sufficient to demonstrate that it qualifies
+                      as a Nonprofit. If such Person materially misrepresents,
+                      or is unable to demonstrate, its qualification as a
+                      Nonprofit, the rights granted to such Person under
+                      Section 2 of this Additional Use Grant shall terminate.
+
+                      "MemberJunction Certified Program" means Licensor's
+                      then-current program for certifying and authorizing a
+                      Person to provide professional services using the
+                      Licensed Work.
+
+                      "Person" means any individual, corporation, limited
+                      liability company, partnership, association, nonprofit
+                      organization, governmental entity, or other legal or
+                      organizational entity.
+
+Change Date:          Four (4) years from the date the Licensed Work is first
+                      made available.
+
+Change License:       MIT License.
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Blue Cypress, Inc.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/README.md

@@ -1,45 +1,59 @@
 # @memberjunction/ng-realtime-channels
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Build realtime-agent channels in Angular without the call overlay. A small package on purpose: it depends on the channel contract (`@memberjunction/realtime-runtime`, `@memberjunction/ai-core-plus`) and Angular's core, and nothing else of MemberJunction's UI (no overlay, no Explorer, no router), so an embed or an Open App can use it without pulling in the conversations stack.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+The how-to is [`guides/REALTIME_CHANNELS_GUIDE.md`](../../../../guides/REALTIME_CHANNELS_GUIDE.md); a complete worked example is [`@memberjunction/ng-realtime-channel-examples`](../realtime-channel-examples/README.md).
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## What is in it
 
-## Purpose
+| Export | Purpose |
+|---|---|
+| `AngularComponentChannel<TComponent>` | A base class that turns an **existing** Angular component into a realtime channel surface without rewriting it. You write a descriptor and a few binding functions; the adapter owns binding, perception, verbs, completion, persistence and pictures. |
+| `ChannelSurfaceEvent` | What a component's output becomes: `{ Name, Payload?, Author?, Perceive? }`. |
+| `EnableChannelFrameCapture(options?)` | Opts a host in to showing the model pictures of channel surfaces: registers a bounded `html-to-image` based rasterizer. Returns a function that removes it. |
+| `CreateDomFrameCapturer(options?)`, `DomFrameCaptureOptions`, `DomRasterizer` | Build a capturer with different limits or a different rasterizer. |
+| `ChannelFrameCapture`, `ElementFrameCapturer` | The singleton that holds the host's capturer (`Instance.Register(fn \| null)`, `Instance.Capturer`). |
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/ng-realtime-channels`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## `AngularComponentChannel`
 
-## What is OIDC Trusted Publishing?
+```ts
+@RegisterClass(BaseRealtimeChannelClient, 'SudokuChannel')
+export class SudokuChannel extends AngularComponentChannel<SudokuComponent> {
+    protected readonly ComponentClass: Type<SudokuComponent> = SudokuComponent;
+    protected readonly Descriptor: RealtimeChannelDescriptor = { Key: 'Sudoku', /* ... for the model ... */ };
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+    protected ReadSurfaceState(c: SudokuComponent): JSONObject { return { board: c.Board, moves: c.MoveCount }; }
+    protected ApplySurfaceVerb(c: SudokuComponent, verb: string, args: JSONObject, actor: RealtimeChannelActor): RealtimeChannelVerbResult { /* ... */ }
+    protected SurfaceEvents(c: SudokuComponent): Observable<ChannelSurfaceEvent> { return c.CellChanged.pipe(map(/* ... */)); }
+}
+export function LoadSudokuChannel(): void {}
+```
 
-## Setup Instructions
+Required members: `ComponentClass`, `Descriptor`, `ReadSurfaceState`, `ApplySurfaceVerb`, `SurfaceEvents`. Optional: `OnSurfaceOpen` (apply `open` inputs), `SurfaceCompletion` (a stream that becomes `Complete(output)`), `OnSurfaceBound` (restore a component created again from the last state), `SurfaceElement` (the root element, so the model can be shown a picture). A subclass that overrides `OnInitialize` must call `super.OnInitialize()`.
 
-To properly configure OIDC trusted publishing for this package:
+What the adapter does:
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+* **Binding.** `BindSurface` subscribes to `SurfaceEvents` and `SurfaceCompletion`, restores the last state through `OnSurfaceBound`, applies `open` inputs that arrived early and releases waiting verbs. `UnbindSurface` keeps the last state and lets go. A collapsed-then-expanded panel creates a new component, so durable state belongs to the channel.
+* **Perception.** Every event, and every successful verb, is recorded as a change: observers get a typed event and the model gets one coalesced delta note, gated by exposure policy. An event emitted while the adapter is running the agent's verb is attributed to the agent.
+* **Verbs.** Resolved against the descriptor (case-insensitive), refused for the agent when exposure is below the verb's `ReturnsChannelData`, validated against the parameter schema, serialized, run on the component. A throw becomes a `verb_failed` result the model can read, and is logged.
+* **A verb with no surface.** It waits, bounded (`SurfaceBindTimeoutMs`, 5 s), for the component to bind and runs against the real one; if it never binds the call fails with `surface_unavailable` and a message telling the agent to ask the user to open it. Not a hidden headless instance (it would hold state nobody is looking at) and not queue-and-acknowledge (the agent needs the real outcome).
+* **A verb that never answers.** Each verb has a bounded execution time (`VerbTimeoutMs`, 15 s, overridable; a non-positive value turns it off). On timeout the call fails with `verb_timeout` ("The X didn't respond to \"play\" within 15s; try again or ask the user."), the queue is released and the timeout is logged once with the channel and verb. The adapter cannot cancel the promise: a late result is never delivered, a late failure is logged, and a late success (the component changed after the agent was told it had not) is recorded as a change so the next perception note shows the real state. Nothing is rolled back, so the component's own rules must reject a duplicate retry.
+* **Persistence.** `SerializeState()` and `RestoreState()` carry the last state as JSON (a non-object is refused).
+* **Pictures.** If `SurfaceElement` returns an element and the host called `EnableChannelFrameCapture`, the channel sources the model's video track and a frame is pushed after each user change, only while the effective exposure is `'pixels'` and a video track is established.
 
-## DO NOT USE THIS PACKAGE
+## The rasterizer
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+Core ships no rasterizer: it is a heavy dependency every embed would pay for. A host that wants the model to see surfaces calls `EnableChannelFrameCapture()` once at startup, **before a session is minted** (Explorer does this in `ExplorerAppComponent`). The capturer is bounded (3000 nodes, 4 s, one capture at a time, a 1024 px longest edge, no web fonts) and fails soft: it costs the model a frame, never a call, and after three consecutive failures (or at once on one that cannot recover) turns itself off for the session and logs one reason.
 
-## More Information
+## Layering
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+Layer **L1 (widgets)**: no router, no Explorer, no overlay. See [`guides/UI_LAYERING_GUIDE.md`](../../../../guides/UI_LAYERING_GUIDE.md).
 
----
+## Testing
 
-**Maintained for OIDC setup purposes only**
+```bash
+cd packages/Angular/Generic/realtime-channels
+pnpm test           # node preset (adapter) + jsdom preset (rasterizer)
+pnpm run test:types # typecheck the specs
+pnpm run build
+```

package/dist/lib/angular-component-channel.d.ts

@@ -0,0 +1,244 @@
+/**
+ * @fileoverview {@link AngularComponentChannel}: turns an EXISTING Angular component into a realtime channel surface
+ * without rewriting it.
+ *
+ * A channel is what an agent and a user both operate during a call: the agent acts through verbs, perceives through
+ * state notes (and, if allowed, pictures), and the user acts directly on the surface. Writing one from scratch means
+ * writing the whole contract (descriptor, perception, verbs, binding the surface, completion). This base class owns the
+ * mechanics so a channel over a component you already have is a descriptor plus a few binding functions:
+ *
+ * ```ts
+ * @RegisterClass(BaseRealtimeChannelClient, 'SudokuChannel')
+ * export class SudokuChannel extends AngularComponentChannel<SudokuComponent> {
+ *   protected readonly ComponentClass = SudokuComponent;
+ *   protected readonly Descriptor: RealtimeChannelDescriptor = { Key: 'Sudoku', ... };
+ *   protected ReadSurfaceState(c: SudokuComponent): JSONObject { return { board: c.Board, moves: c.MoveCount }; }
+ *   protected ApplySurfaceVerb(c: SudokuComponent, verb: string, args: JSONObject): RealtimeChannelVerbResult { ... }
+ *   protected SurfaceEvents(c: SudokuComponent): Observable<ChannelSurfaceEvent> { return c.CellChanged.pipe(map(...)); }
+ * }
+ * export function LoadSudokuChannel(): void {}
+ * ```
+ *
+ * ## What the adapter does for you
+ *
+ * - **Binding.** The overlay creates the component and hands it to {@link BindSurface}; the adapter subscribes to
+ *   {@link SurfaceEvents}, applies anything that arrived early, and lets go cleanly on {@link UnbindSurface} (a host may
+ *   create a NEW component instance for the same channel, e.g. when the overlay is recreated, so durable state belongs
+ *   to the channel, see below).
+ * - **Perception.** Every event the component emits, and every verb the agent runs, is recorded as a change: observers
+ *   see a typed event, and the model gets ONE coalesced structured note carrying a delta of {@link ReadSurfaceState}
+ *   (see `RecordChange` in the base class). Exposure policy gates it like any channel.
+ * - **Verbs.** Parameters are validated against the descriptor's schema before your code runs; a verb the agent may not
+ *   have (exposure) is refused by the dispatcher; the outcome is a structured result the model can recover from.
+ * - **Completion.** An optional {@link SurfaceCompletion} stream becomes `Complete(output)`.
+ * - **Pictures.** If you can name the component's root element ({@link SurfaceElement}) and the host registered a
+ *   rasterizer (`EnableChannelFrameCapture`), the channel shows the model what the component looks like.
+ * - **Persistence.** The last state is saved as the channel's state of record and handed back to
+ *   {@link OnSurfaceBound} when the surface is created again (collapse/expand, or a resumed session).
+ *
+ * ## When there is no surface
+ *
+ * A verb can arrive while no component is bound (the panel was just opened and the overlay is still creating the
+ * component). The adapter does NOT run the verb against a hidden second instance, and it does NOT acknowledge it and apply
+ * it later: the agent needs the real outcome (a move can be refused), and a second instance would hold state the user is
+ * not looking at. Instead the call WAITS, bounded ({@link SurfaceBindTimeoutMs}, 5 s), for the surface, runs once it
+ * binds (calls are serialized, so order is preserved), and fails with `'surface_unavailable'` and a message the agent can
+ * act on ("ask the user to open it") if it never binds. Seed inputs of `open` are different: there is nothing to report back
+ * but success, so they are applied when the surface binds. (A channel with no surface at all, a pure wire, does not need this
+ * class.)
+ *
+ * ## A verb that never answers
+ *
+ * Verbs run one at a time, so one that never settles would stall every later call. Each verb therefore has a bounded execution
+ * time ({@link VerbTimeoutMs}, 15 s). On timeout the call fails with `'verb_timeout'` and a message the agent can act on ("try
+ * again or ask the user"), the queue is released, and the timeout is logged once with the channel and verb. The adapter cannot
+ * cancel the promise your {@link ApplySurfaceVerb} returned, so what happens next is deliberately defined:
+ *
+ * - A **late result is never delivered**: the agent was already told the verb failed, and it is not told otherwise.
+ * - A late **failure** is logged and dropped.
+ * - A late **success** means the component DID change after the agent was told it had not. Nothing is rolled back (the
+ *   component's own rules decide whether a retry is accepted, which is why they must live in the component), but the change is
+ *   recorded like any other so the next perception note shows the model the real state.
+ * - The next queued verb may run while the late one is still pending, so a verb should not assume exclusive access to the
+ *   component for longer than it takes to settle.
+ *
+ * @module @memberjunction/ng-realtime-channels
+ */
+import type { Type } from '@angular/core';
+import { Observable } from 'rxjs';
+import type { JSONObject } from '@memberjunction/ai';
+import { type RealtimeChannelActor, type RealtimeChannelDescriptor } from '@memberjunction/ai-core-plus';
+import { BaseRealtimeChannelClient, type RealtimeChannelVerbResult } from '@memberjunction/realtime-runtime';
+/**
+ * Something the wrapped component did that the channel should know about: a user's move, a selection, a state
+ * change worth telling the model about. Return these from {@link AngularComponentChannel.SurfaceEvents}.
+ */
+export interface ChannelSurfaceEvent {
+    /** The event's name; declare it in the descriptor's `Events` so the agent knows it exists. */
+    Name: string;
+    /** The event's payload (JSON). */
+    Payload?: JSONObject;
+    /**
+     * Who caused it. Default `'user'`, except that an event emitted while the adapter is running an agent's verb is
+     * attributed to the agent (the component echoes the agent's own move through the same outputs the user's use).
+     */
+    Author?: RealtimeChannelActor | 'system';
+    /** Set `false` for an event observers should see but the model should not be told about. Default `true`. */
+    Perceive?: boolean;
+}
+/**
+ * Base class for a realtime channel whose surface is an existing Angular component. See the file comment for the model.
+ *
+ * @typeParam TComponent The component class the channel shows and operates.
+ */
+export declare abstract class AngularComponentChannel<TComponent extends object> extends BaseRealtimeChannelClient<TComponent> {
+    /** The existing component to show as the channel's surface. The overlay creates it; the adapter binds to it. */
+    protected abstract readonly ComponentClass: Type<TComponent>;
+    /**
+     * The channel's self-description: what it is, what it holds (nouns), what it accepts (verbs with parameter schemas and
+     * `InvokableBy`), what it emits (events), how it opens (inputs) and what it hands back (output). Pure data, and the only
+     * thing an agent has to go on, so write `Instructions` and every description for the MODEL.
+     */
+    protected abstract readonly Descriptor: RealtimeChannelDescriptor;
+    /**
+     * The channel's state as the model should perceive it: one entry per noun in the descriptor, JSON only. Called whenever
+     * a perception note is built, so it must be a pure, cheap read of the component.
+     *
+     * @param component The bound component.
+     */
+    protected abstract ReadSurfaceState(component: TComponent): JSONObject;
+    /**
+     * Runs one verb on the component. The adapter has already resolved the verb against the descriptor and validated
+     * `args` against its schema, so trust the shape; check the GAME or DOCUMENT rules (is it the agent's turn? is the cell
+     * free?) and return a failure result with a message the model can act on rather than throwing.
+     *
+     * @param component The bound component.
+     * @param verb The verb's name, as declared in the descriptor.
+     * @param args The validated parameters.
+     * @param actor Who is acting: the agent, or the user acting through the same verb.
+     */
+    protected abstract ApplySurfaceVerb(component: TComponent, verb: string, args: JSONObject, actor: RealtimeChannelActor): RealtimeChannelVerbResult | Promise<RealtimeChannelVerbResult>;
+    /**
+     * What the component emits that the channel should react to, as a stream. Subscribed when the surface binds and
+     * unsubscribed when it unbinds. Merge the component's outputs here; map each to a {@link ChannelSurfaceEvent}.
+     *
+     * @param component The bound component.
+     */
+    protected abstract SurfaceEvents(component: TComponent): Observable<ChannelSurfaceEvent>;
+    /**
+     * Applies the seed inputs of `open` to the component (optional). Return a failure to refuse the open. Called when the
+     * surface is bound, immediately if it already is.
+     *
+     * @param component The bound component.
+     * @param inputs The validated open inputs.
+     */
+    protected OnSurfaceOpen?(component: TComponent, inputs: JSONObject): void | RealtimeChannelVerbResult | Promise<void | RealtimeChannelVerbResult>;
+    /**
+     * Emits when the component's job is done and it has something to hand back (a finished game, a submitted form):
+     * becomes `Complete(output)`, validated against the descriptor's `Output`. Optional.
+     *
+     * @param component The bound component.
+     */
+    protected SurfaceCompletion?(component: TComponent): Observable<JSONObject>;
+    /**
+     * Called each time a component is bound, with the last state the channel knew (this session's, or the saved one on a
+     * resumed session), so a component created fresh (a panel expanded again, a session resumed) can be restored to it.
+     * Optional; a component that keeps its own state elsewhere does not need it.
+     *
+     * @param component The newly bound component.
+     * @param lastState The last known state, or `null` when there is none.
+     */
+    protected OnSurfaceBound?(component: TComponent, lastState: JSONObject | null): void;
+    /**
+     * The component's root element, so the channel can show the model a picture of it. Optional: without it (or without a
+     * rasterizer registered by the host) the channel offers state only. A component can expose its host element by
+     * injecting `ElementRef`.
+     *
+     * @param component The bound component.
+     */
+    protected SurfaceElement?(component: TComponent): HTMLElement | null;
+    /** How long a verb waits for the surface to bind before failing with `'surface_unavailable'`, in ms. Override to change it. */
+    protected SurfaceBindTimeoutMs: number;
+    /**
+     * How long {@link ApplySurfaceVerb} may run before the call fails with `'verb_timeout'` and the queue is released, in ms
+     * (15 s by default; the surface bind wait is separate, see {@link SurfaceBindTimeoutMs}). Override it for a component whose
+     * verbs are legitimately slow; a value that is not a positive number turns the limit off, which is only safe for a verb that
+     * is guaranteed to settle. See the file comment for what happens to a verb that settles after the timeout.
+     */
+    protected VerbTimeoutMs: number;
+    get ChannelName(): string;
+    get TabTitle(): string;
+    GetDescriptor(): RealtimeChannelDescriptor;
+    /** The channel has no native tools: its verbs are reached through the `ContextTool` proxy. */
+    GetToolDefinitions(): never[];
+    GetSurfaceComponent(): Type<TComponent>;
+    private surface;
+    private surfaceSubscriptions;
+    private bindWaiters;
+    private lastState;
+    private pendingOpenInputs;
+    private verbChain;
+    private applyingActor;
+    /** The bound component, or `null` while no surface is up. */
+    protected get Surface(): TComponent | null;
+    /**
+     * Opts into pictures when the subclass can name the component's element and the host registered a rasterizer. Subclasses
+     * that override this MUST call `super.OnInitialize()`.
+     */
+    protected OnInitialize(): void;
+    /**
+     * The overlay created the component: bind to it. Subscribes to its events and completion, restores the last known
+     * state, applies any seed inputs that arrived before it existed, and releases verbs that were waiting for it.
+     */
+    BindSurface(component: TComponent): void;
+    /** The component is going away (the panel collapsed, or the session ended): keep its last state, let go of it. */
+    UnbindSurface(): void;
+    private unbindSubscriptions;
+    /** Resolves with the bound component, waiting (bounded) for it to bind; `null` when it never does. */
+    private whenSurfaceBound;
+    /**
+     * The channel's state: the live component's, or the last known when no component is bound (so a note built while the
+     * panel is collapsed still describes the channel truthfully).
+     */
+    GetState(): JSONObject;
+    /** Reads the component's state, logging and returning `null` if the subclass's reader throws (a perception note must never break a call). */
+    private safeReadState;
+    /** The state of record: the last known state as JSON, or `null` before there is any. */
+    SerializeState(): string | null;
+    /**
+     * A saved state came back (a resumed session): hold it, and hand it to {@link OnSurfaceBound} when the component is
+     * created. Returns `false` for anything that is not a JSON object.
+     */
+    RestoreState(stateJson: string): boolean;
+    /**
+     * Seeds the surface with the open inputs: now if the component is bound, otherwise when it binds (there is nothing to
+     * report back but success, so there is nothing to wait for).
+     */
+    protected OnOpen(inputs: JSONObject): Promise<void | RealtimeChannelVerbResult>;
+    private applyPendingOpen;
+    /**
+     * Runs one verb. Verbs are serialized (a second call waits for the first), wait (bounded) for the surface, and run
+     * against the real component, so the outcome the agent hears is the outcome the user sees.
+     */
+    ApplyVerb(verb: string, args: JSONObject, actor: RealtimeChannelActor): Promise<RealtimeChannelVerbResult>;
+    private runVerb;
+    private applyOnSurface;
+    /**
+     * Runs {@link ApplySurfaceVerb} with a bounded execution time. Settles with the verb's result, with `TimedOut` when it did
+     * not answer in time, or rejects with what it threw. Once it has timed out, whatever it later does is handled by
+     * {@link onLateVerbSettle} and never reaches the caller: the promise is already settled, so there is no second result.
+     */
+    private runWithTimeout;
+    /**
+     * A verb settled AFTER it timed out. The agent already has its answer (failure), so the late result is never delivered. A
+     * late failure is logged. A late success means the component changed after the agent was told it had not: it is recorded as
+     * a change (when the same component is still on screen) so the next perception note shows the model the real state.
+     */
+    private onLateVerbSettle;
+    /** The component emitted something: tell observers, and (unless told not to) record it as a change the model perceives. */
+    private onSurfaceEvent;
+    /** A picture of the component, or `null` when there is none to send (see the rules in the Interactive Component channel). */
+    private captureFrame;
+    Dispose(): void;
+}
+//# sourceMappingURL=angular-component-channel.d.ts.map

package/dist/lib/angular-component-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"angular-component-channel.d.ts","sourceRoot":"","sources":["../../src/lib/angular-component-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAgB,MAAM,MAAM,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAmC,KAAK,oBAAoB,EAAE,KAAK,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAG1I,OAAO,EAAE,yBAAyB,EAAE,KAAK,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAG7G;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAChC,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,oBAAoB,GAAG,QAAQ,CAAC;IACzC,4GAA4G;IAC5G,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAgBD;;;;GAIG;AACH,8BAAsB,uBAAuB,CAAC,UAAU,SAAS,MAAM,CAAE,SAAQ,yBAAyB,CAAC,UAAU,CAAC;IAGlH,gHAAgH;IAChH,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,cAAc,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAE7D;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC;IAElE;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU;IAEtE;;;;;;;;;OASG;IACH,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAC/B,SAAS,EAAE,UAAU,EACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,oBAAoB,GAC5B,yBAAyB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAEjE;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC,mBAAmB,CAAC;IAExF;;;;;;OAMG;IACH,SAAS,CAAC,aAAa,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,yBAAyB,GAAG,OAAO,CAAC,IAAI,GAAG,yBAAyB,CAAC;IAEjJ;;;;;OAKG;IACH,SAAS,CAAC,iBAAiB,CAAC,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC;IAE3E;;;;;;;OAOG;IACH,SAAS,CAAC,cAAc,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI;IAEpF;;;;;;OAMG;IACH,SAAS,CAAC,cAAc,CAAC,CAAC,SAAS,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI;IAEpE,+HAA+H;IAC/H,SAAS,CAAC,oBAAoB,EAAE,MAAM,CAA2B;IAEjE;;;;;OAKG;IACH,SAAS,CAAC,aAAa,EAAE,MAAM,CAAmB;IAIlD,IAAW,WAAW,IAAI,MAAM,CAE/B;IAED,IAAoB,QAAQ,IAAI,MAAM,CAErC;IAEe,aAAa,IAAI,yBAAyB;IAI1D,8FAA8F;IAC9E,kBAAkB,IAAI,KAAK,EAAE;IAI7B,mBAAmB,IAAI,IAAI,CAAC,UAAU,CAAC;IAMvD,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,oBAAoB,CAAsB;IAClD,OAAO,CAAC,WAAW,CAAqD;IACxE,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,iBAAiB,CAA2B;IACpD,OAAO,CAAC,SAAS,CAAuC;IACxD,OAAO,CAAC,aAAa,CAAqC;IAE1D,6DAA6D;IAC7D,SAAS,KAAK,OAAO,IAAI,UAAU,GAAG,IAAI,CAEzC;IAED;;;OAGG;cACgB,YAAY,IAAI,IAAI;IAMvC;;;OAGG;IACa,WAAW,CAAC,SAAS,EAAE,UAAU,GAAG,IAAI;IA2BxD,kHAAkH;IAClG,aAAa,IAAI,IAAI;IAQrC,OAAO,CAAC,mBAAmB;IAO3B,sGAAsG;IACtG,OAAO,CAAC,gBAAgB;IAmBxB;;;OAGG;IACa,QAAQ,IAAI,UAAU;IAWtC,6IAA6I;IAC7I,OAAO,CAAC,aAAa;IASrB,wFAAwF;IACxE,cAAc,IAAI,MAAM,GAAG,IAAI;IAK/C;;;OAGG;IACa,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAexD;;;OAGG;cACsB,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,GAAG,yBAAyB,CAAC;YAWhF,gBAAgB;IAkB9B;;;OAGG;IACa,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,yBAAyB,CAAC;YAM5G,OAAO;YAuBP,cAAc;IA0B5B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAoCtB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAYxB,2HAA2H;IAC3H,OAAO,CAAC,cAAc;IAWtB,6HAA6H;YAC/G,YAAY;IAmBV,OAAO,IAAI,IAAI;CASlC"}