@saga-a2ui/lit 0.0.0-stage → 0.7.7-rc.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @saga-a2ui/lit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lit renderer integration for SAGA A2UI. Entry points: the root mounts an application's own A2UI catalog; `/actions` attaches actions to rendered controls; `/faithful-card` supplies the optional FaithfulCard element. Components is optional for own-catalog rendering and required for FaithfulCard.
+
+Applications connecting Lit to MCP normally install `@saga-a2ui/lit-mcp-stack` and the Lit peer, and import from the stack only. Lower-level integrations may use this renderer directly with matching SAGA packages.
+
+Requires Node >=22.12.0 and a TypeScript-aware bundler; exports are TypeScript source. Apache-2.0, with dependency licenses retained separately.
+
+Release candidates use the npm `next` tag. Pin exact published SAGA versions. At the consumer root, override `@a2ui/markdown-it` to `0.2.1`; keep A2UI's Zod 3 and MCP's Zod 4 contexts separate.
+
+See [public installation](https://github.com/MachineWisdomAI/saga-a2ui/blob/main/docs/public-install.md) and [release preparation](https://github.com/MachineWisdomAI/saga-a2ui/blob/main/docs/release-packages.md). Source versions and candidate tarballs do not establish registry availability.

package/package.json

@@ -1,6 +1 @@
-{
-  "name": "@saga-a2ui/lit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{"name":"@saga-a2ui/lit","private":false,"description":"Lit binding for SAGA A2UI: mounts a core message session's surface with an application's own catalog and owns its disposal, with the optional /actions control and instance host and the optional /faithful-card element","license":"Apache-2.0","type":"module","exports":{".":"./src/index.ts","./actions":"./src/actions/index.ts","./faithful-card":"./src/faithful-card/index.ts"},"files":["src","!src/**/*.test.ts","!src/**/*.test-support.ts"],"scripts":{"typecheck":"tsc --noEmit"},"dependencies":{"@a2ui/lit":"0.13.0","@a2ui/web_core":"0.13.0","@saga-a2ui/core":"0.7.7-rc.1","lit":"^3.3.3"},"peerDependencies":{"@saga-a2ui/components":"0.7.7-rc.1"},"peerDependenciesMeta":{"@saga-a2ui/components":{"optional":true}},"devDependencies":{"@saga-a2ui/components":"0.7.7-rc.1","typescript":"^5.9.0","vitest":"^5.0.4"},"version":"0.7.7-rc.1","engines":{"node":">=22.12.0"},"repository":{"type":"git","url":"https://github.com/MachineWisdomAI/saga-a2ui.git","directory":"packages/lit"},"publishConfig":{"access":"public","tag":"next"}}

package/src/a2ui/app-element.ts

@@ -0,0 +1,238 @@
+import { A2uiSurface, type LitComponentApi } from '@a2ui/lit/v0_9';
+import type { Catalog, Subscription, SurfaceModel } from '@a2ui/web_core/v0_9';
+import {
+  a2uiV0_9Decoder,
+  createMessageSession,
+  type IngestFailure,
+  type IngestResult,
+  type MessageSession,
+  type SurfaceLayout,
+  type SurfaceUpdateFailure,
+} from '@saga-a2ui/core/protocols/a2ui/v0_9';
+import { LitElement, html, nothing } from 'lit';
+import { createRef, ref } from 'lit/directives/ref.js';
+
+export type A2uiSession = MessageSession<LitComponentApi>;
+
+/** One presentation of a surface by an app element: what an optional integration needs to know. */
+export interface A2uiSurfaceMount {
+  /** The app element presenting the surface. */
+  readonly owner: Element;
+  readonly surface: SurfaceModel<LitComponentApi>;
+  /** The one `<a2ui-surface>` the owner rendered for this presentation, once it has rendered. */
+  readonly mount: () => Element | undefined;
+}
+
+/**
+ * An optional integration that owns per-presentation state, such as the action host of
+ * `@saga-a2ui/lit/actions`. The app element starts it for each surface it presents and ends it when
+ * that presentation ends. This package defines only the seam, so an application that supplies
+ * none carries none of the integration's code.
+ */
+export interface A2uiActions {
+  /**
+   * Starts the integration for one presentation, before the surface renders, and returns the
+   * function that ends it. Throwing means the integration could not start: the element then
+   * shows its safe fallback and does not render the surface.
+   */
+  begin(mount: A2uiSurfaceMount): () => void;
+}
+
+/** Why `updateData` changed nothing. `message` is plain text that is safe to display. */
+export interface A2uiUpdateFailure {
+  readonly kind: SurfaceUpdateFailure['kind'] | IngestFailure['kind'];
+  readonly message: string;
+}
+
+export type A2uiUpdateResult =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly failure: A2uiUpdateFailure };
+
+export interface A2uiAppDependencies<TData> {
+  /**
+   * The catalog the surface's components come from. The element builds a fresh session over it
+   * on each connect, with the SDK's A2UI decoder, so an application never constructs one.
+   */
+  readonly catalog: Catalog<LitComponentApi>;
+  /** The one surface this element presents: its identity, its data type and how it opens. */
+  readonly layout: SurfaceLayout<TData>;
+  /** Optional. Started per presented surface and ended with it, on every exit. */
+  readonly actions?: A2uiActions;
+  /**
+   * Optional and advanced; an ordinary application leaves it out. Replaces the default session
+   * on each connect, for an application that must observe or wrap the session it is given
+   * `catalog`. The element owns and disposes what this returns.
+   */
+  readonly createSession?: (catalog: Catalog<LitComponentApi>) => A2uiSession;
+}
+
+// `a2ui-surface` is defined by importing upstream's A2uiSurface. This package renders it, so this
+// is the one place that import is relied on.
+void A2uiSurface;
+
+/**
+ * Builds a custom-element class that presents one A2UI surface from a core message session.
+ * The application supplies the catalog and the layout and defines the tag; subclass
+ * the result to add application chrome or wiring.
+ *
+ * Lifecycle: connecting creates a session, subscribes, and opens the layout. Disconnecting
+ * unsubscribes and disposes the session, so a reconnected element starts fresh and nothing from
+ * the retired session can reach the page. The element only presents results: decoding and
+ * validation live in the layout and the session.
+ *
+ * Data: `updateData(data)` validates against the layout and applies it as an A2UI data update. It
+ * changes what the mounted controls show without remounting them, so their action bindings and
+ * focus survive. A rejected update (invalid data, an element that is not connected, a disposed
+ * session) returns a failure and changes nothing: the surface, its data and its fallback state
+ * stay as they were. The element has no notion of selection.
+ *
+ * Failure: a layout the session cannot open (for example a root component the catalog lacks)
+ * shows a safe fallback instead of a blank surface.
+ *
+ * Actions: when `actions` is supplied it starts before each surface is first rendered and ends
+ * when that surface is deleted, replaced, or the element disconnects (before the session is
+ * disposed). If it cannot start, the surface is not rendered and a safe fallback shows until the
+ * surface is created again.
+ *
+ * Catalog components are custom elements the application defines with `defineElements`.
+ */
+export function createA2uiAppElement<TData>(deps: A2uiAppDependencies<TData>) {
+  class A2uiApp extends LitElement {
+    // Reactive state is declared with `static properties` and `declare`, not with decorators: this
+    // package ships TypeScript source that each application compiles with its own settings, and
+    // decorator syntax is only valid under the settings the workspace happens to use.
+    static override properties = {
+      surface: { state: true },
+      failure: { state: true },
+      presentationFailure: { state: true },
+    };
+    declare private surface?: SurfaceModel<LitComponentApi>;
+    declare private failure?: string;
+    declare private presentationFailure?: string;
+
+    private session?: A2uiSession;
+    private subscriptions: Subscription[] = [];
+    private endPresentation?: () => void;
+    private readonly mount = createRef<Element>();
+
+    /**
+     * Replaces the surface's data. (Not named `update`: Lit's `ReactiveElement.update` is the
+     * render lifecycle method of every element built on it.) Validated against the layout, then applied in place: no
+     * remount, so the rendered controls, their action bindings and focus survive. Never throws;
+     * a rejection returns a failure and leaves data, identity and any fallback unchanged.
+     */
+    updateData(data: TData): A2uiUpdateResult {
+      const messages = deps.layout.update(data);
+      if (!messages.ok) return { ok: false, failure: messages.failure };
+      return (
+        this.session?.ingest(messages.messages) ?? {
+          ok: false,
+          failure: {
+            kind: 'rejected',
+            message: 'The app is not connected.',
+          },
+        }
+      );
+    }
+
+    /**
+     * Applies unchecked protocol input to the current session, and shows the safe fallback when
+     * the session rejects it. Not part of the application contract (use `updateData`): it is for a
+     * subclass that relays protocol messages it did not author, such as a host that forwards
+     * server-supplied A2UI. Never throws for bad input. Messages applied before a rejection stay
+     * applied (there is no atomic rollback); the next input the session accepts clears the
+     * fallback.
+     */
+    protected ingest(input: unknown): IngestResult {
+      const result = this.session?.ingest(input) ?? {
+        ok: false as const,
+        failure: {
+          kind: 'rejected' as const,
+          message: 'The app is not connected.',
+        },
+      };
+      this.failure = result.ok ? undefined : result.failure.message;
+      return result;
+    }
+
+    private present(surface: SurfaceModel<LitComponentApi>) {
+      this.closePresentation();
+      this.presentationFailure = undefined;
+      if (deps.actions) {
+        try {
+          this.endPresentation = deps.actions.begin({
+            owner: this,
+            surface,
+            mount: () => this.mount.value,
+          });
+        } catch {
+          this.presentationFailure =
+            'The actions for this content could not be attached.';
+          return;
+        }
+      }
+      // Lit renders the surface later, so any setup the integration ran is in place by then.
+      this.surface = surface;
+    }
+
+    private closePresentation() {
+      const end = this.endPresentation;
+      this.endPresentation = undefined;
+      end?.();
+    }
+
+    connectedCallback() {
+      super.connectedCallback();
+      const session =
+        deps.createSession?.(deps.catalog) ??
+        createMessageSession({
+          catalogs: [deps.catalog],
+          decoder: a2uiV0_9Decoder,
+        });
+      this.session = session;
+      this.subscriptions = [
+        session.onSurfaceCreated((surface) => {
+          if (surface.id === deps.layout.surfaceId) this.present(surface);
+        }),
+        session.onSurfaceDeleted((id) => {
+          if (id !== deps.layout.surfaceId) return;
+          this.closePresentation();
+          this.presentationFailure = undefined;
+          this.surface = undefined;
+        }),
+      ];
+      this.ingest(deps.layout.opening);
+    }
+
+    disconnectedCallback() {
+      super.disconnectedCallback();
+      for (const subscription of this.subscriptions) subscription.unsubscribe();
+      this.subscriptions = [];
+      // The presentation ends before the session it depends on is disposed.
+      this.closePresentation();
+      this.session?.dispose();
+      this.session = undefined;
+      this.surface = undefined;
+      this.failure = undefined;
+      this.presentationFailure = undefined;
+    }
+
+    render() {
+      // Failure text is only ever a Lit text binding, so it stays inert.
+      const failure = this.failure ?? this.presentationFailure;
+      if (failure !== undefined) {
+        return html`<div role="alert" data-testid="failure">
+          Could not render this content:
+          <span data-testid="failure-detail">${failure}</span>
+        </div>`;
+      }
+      return this.surface
+        ? html`<a2ui-surface
+            ${ref(this.mount)}
+            .surface=${this.surface}
+          ></a2ui-surface>`
+        : nothing;
+    }
+  }
+  return A2uiApp;
+}

package/src/actions/action-button.ts

@@ -0,0 +1,130 @@
+import { A2uiLitElement, type LitComponentApi } from '@a2ui/lit/v0_9';
+import {
+  componentKind,
+  type InstanceEvent,
+  type OpenInstance,
+} from '@saga-a2ui/core/actions';
+import { html, nothing } from 'lit';
+import { ActionButtonApi } from '@saga-a2ui/core/actions/action-button-schema';
+import { hostOf } from './mount-owner.js';
+
+/** The event an `ActionButton` delivers: the instance's data scope plus the DOM click. */
+export type ActionButtonActivation = InstanceEvent<Event>;
+
+export interface ActionButtonEvents {
+  readonly activate: ActionButtonActivation;
+}
+
+/** The kind token application setup passes to `getById` and `watchById`. */
+export const ActionButton = componentKind<ActionButtonEvents>('ActionButton');
+
+/**
+ * One element class serves every instance of the kind. The instance belongs to the element
+ * together with the component model and data path it currently shows: the directive reuses
+ * elements, and parents replace `context` on every render, so neither alone is an identity.
+ *
+ * Upstream decides when a binding changed: `willUpdate` keeps the controller while the same
+ * component is shown at the same path and calls `createController()` otherwise, which is the
+ * supported seam this override uses. It never relies on `element.node`, which stays unset under
+ * `a2ui-surface`.
+ *
+ * The control has no upstream `action`, so its single click handler is the only activation site.
+ * Do not add another click listener to a rendered button as a shortcut: for an upstream Button it
+ * would run in addition to the Button's own action.
+ */
+export class ActionButtonElement extends A2uiLitElement<
+  typeof ActionButtonApi
+> {
+  protected readonly api = ActionButtonApi;
+  #instance: OpenInstance<ActionButtonEvents> | undefined;
+
+  protected override createController() {
+    this.#retire();
+    const controller = super.createController();
+    this.#open();
+    return controller;
+  }
+
+  override connectedCallback() {
+    super.connectedCallback();
+    // Reconnecting keeps upstream's controller, so no createController call opens a new instance.
+    if (this.controller) this.#open();
+  }
+
+  override disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#retire();
+  }
+
+  #open() {
+    if (this.#instance) return;
+    const context = this.context;
+    const { surface, path } = context.dataContext;
+    // `DataContext.surface` is optional in the 0.13.0 types: without it the control stays unbound.
+    if (!surface) return;
+    const host = hostOf(this, surface);
+    if (!host) return; // not presented by an app element with actions: stay unbound
+    const model = context.componentModel;
+    // A fresh pull on every call, never a stored answer. Each line closes a different window: the
+    // element left the document; the model was removed, replaced or its surface disposed; a parent
+    // already gave this element another component's context before its willUpdate has run.
+    const isLive = () =>
+      this.isConnected &&
+      surface.componentsModel.get(model.id) === model &&
+      this.context.componentModel === model &&
+      this.context.dataContext.path === path;
+    this.#instance = host.open<ActionButtonEvents>({
+      kind: ActionButton,
+      componentId: model.id,
+      dataPath: path,
+      events: ['activate'],
+      isLive,
+      // This instance's own scope, not this.context, which a same-tag reuse may already have replaced.
+      read: (dataPath) =>
+        isLive()
+          ? context.dataContext.resolveDynamicValue<unknown>({ path: dataPath })
+          : undefined,
+      // The runtime holds this only while an invocation is not settled. `DataModel.subscribe` calls
+      // back synchronously inside `set` and also for an ancestor or descendant of the scope's path;
+      // the microtask lets the whole change finish before the runtime reads the application's
+      // subject, so an A, B, A inside one call stack is not seen, and it runs before the next click.
+      // A subject that reads state outside the data model gets no wake-up here, only the runtime's
+      // own checkpoints.
+      watchScope: (revalidate) => {
+        const subscription = surface.dataModel.subscribe(path, () =>
+          queueMicrotask(revalidate),
+        );
+        return () => subscription.unsubscribe();
+      },
+    });
+  }
+
+  #retire() {
+    this.#instance?.retire();
+    this.#instance = undefined;
+  }
+
+  protected override render() {
+    const props = this.controller?.props;
+    if (!props) return nothing;
+    return html`<button
+      type="button"
+      ?disabled=${props.isValid === false}
+      @click=${this.#onClick}
+    >
+      ${props.child ? this.renderNode(props.child) : nothing}
+    </button>`;
+  }
+
+  #onClick = (event: Event) => {
+    if (this.controller?.props?.isValid === false) return; // the same check the upstream Button makes
+    this.#instance?.activate('activate', event);
+  };
+}
+
+/** The catalog entry. An application lists it in its own catalog and passes it to `defineElements`. */
+export const actionButtonEntry = {
+  ...ActionButtonApi,
+  tagName: 'saga-action-button',
+  element: ActionButtonElement,
+} satisfies LitComponentApi;

package/src/actions/index.ts

@@ -0,0 +1,12 @@
+// Optional Lit integration for direct action attachment. An application that lists none of this
+// in its catalog carries none of it: the main `@saga-a2ui/lit` entry does not import this module.
+export {
+  ActionButton,
+  ActionButtonElement,
+  actionButtonEntry,
+} from './action-button.js';
+export type {
+  ActionButtonActivation,
+  ActionButtonEvents,
+} from './action-button.js';
+export { createLitActions, type LitActionsOptions } from './lit-actions.js';