@saga-a2ui/lit-mcp-stack 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-mcp-stack
 
-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.
+The Lit renderer and MCP Apps delivery in one application dependency. Install the stack plus `lit@^3.3.3`, and import from the stack only: the root starts an application-owned catalog with `startA2uiView`; `/faithful-card` starts a card application with `startFaithfulCardApp`; `/content-policy` supplies content policies; `/server` supplies server composition. The server entry stays out of browser bundles.
+
+The stack declares core, components, MCP and the Lit renderer as dependencies. Your application owns its domain values, catalog, actions, verified identity and authorization.
+
+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-mcp-stack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{"name":"@saga-a2ui/lit-mcp-stack","private":false,"description":"The Lit and MCP Apps stack for SAGA A2UI: starts a view for an application's own catalog, and a FaithfulCard application from one validated definition","license":"Apache-2.0","type":"module","sideEffects":false,"exports":{".":"./src/index.ts","./faithful-card":"./src/faithful-card/index.ts","./content-policy":"./src/content-policy/index.ts","./server":"./src/server/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","@modelcontextprotocol/ext-apps":"2.0.3","@saga-a2ui/components":"0.7.7-rc.1","@saga-a2ui/core":"0.7.7-rc.1","@saga-a2ui/lit":"0.7.7-rc.1","@saga-a2ui/mcp":"0.7.7-rc.1","zod":"4.6.7"},"peerDependencies":{"lit":"^3.3.3"},"devDependencies":{"@modelcontextprotocol/client":"2.3.1","jsdom":"28.1.0","lit":"^3.3.3","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-mcp-stack"},"publishConfig":{"access":"public","tag":"next"}}

package/src/application-call.ts

@@ -0,0 +1,31 @@
+// An application callback that runs while the stack is still setting up (before there is a running
+// view to report through). A throw from it must not escape `start`: the stack cleans up what it had
+// made and returns a handle whose `ready` rejects with `StartFailure('application')`. Marking the
+// throw keeps that apart from a misuse or a defect of the stack itself, which still throws.
+
+class ApplicationCallFailure {
+  constructor(readonly cause: unknown) {}
+}
+
+/** Runs one application callback of the synchronous part of a start. */
+export function callApplication<T>(call: () => T): T {
+  try {
+    return call();
+  } catch (cause) {
+    throw new ApplicationCallFailure(cause);
+  }
+}
+
+/** Ends the synchronous part of a start as the application's own failure (it threw, if not here). */
+export function failApplication(cause: unknown): never {
+  throw new ApplicationCallFailure(cause);
+}
+
+/** The application's own throw, when `error` came out of {@link callApplication}. */
+export function applicationFailureOf(
+  error: unknown,
+): { readonly cause: unknown } | undefined {
+  return error instanceof ApplicationCallFailure
+    ? { cause: error.cause }
+    : undefined;
+}

package/src/container-claim.ts

@@ -0,0 +1,19 @@
+import { StartError } from './start-failure.js';
+
+// One view per container. A start claims the container; the claim ends when that view is gone from
+// the screen (disposed, or ended by the host). A view that failed to start keeps its failure text in
+// the container and so keeps the claim until the application disposes it. This is state about the
+// container, not about the module: it is the one thing two starts of different entries must agree on.
+const claimed = new WeakSet<Element>();
+
+/** Claims `container` for one view, or throws `StartError` and changes nothing. Returns the release. */
+export function claimContainer(container: unknown): {
+  readonly container: Element;
+  release(): void;
+} {
+  if (!(container instanceof Element) || !container.isConnected)
+    throw new StartError('container-missing');
+  if (claimed.has(container)) throw new StartError('container-busy');
+  claimed.add(container);
+  return { container, release: () => void claimed.delete(container) };
+}

package/src/content-policy/index.ts

@@ -0,0 +1,12 @@
+// The content-policy entry of the stack: how a server states and embeds the content policy that
+// the card application reads back from its document at startup. The policy is the owner's
+// (`@saga-a2ui/components`); this entry only names it for an application that installs the stack.
+// It carries no renderer and no delivery, and the own-catalog entry does not import it.
+export {
+  createContentPolicy,
+  embedContentPolicy,
+  type ContentPolicy,
+  type CreatePolicyResult,
+  type PolicyConfiguration,
+  type PolicyFailure,
+} from '@saga-a2ui/components/faithful-card';

package/src/faithful-card/document-policy.ts

@@ -0,0 +1,32 @@
+import {
+  CONTENT_POLICY_ELEMENT_ID,
+  contentPolicyFromEmbedded,
+  type CreatePolicyResult,
+} from '@saga-a2ui/components/faithful-card';
+
+// Where a view finds what its server embedded in the document it served. The format belongs to
+// `@saga-a2ui/components` (`embedContentPolicy`, `contentPolicyFromEmbedded`); reading the
+// document is the stack’s, because components and the renderers take no document.
+
+/**
+ * The content policy embedded in `doc`, validated again: no embedded policy means the Standard
+ * policy with empty lists, and anything that does not validate is a failure, so a view is never
+ * mounted on a guessed policy.
+ */
+export function contentPolicyFromDocument(doc: Document): CreatePolicyResult {
+  return contentPolicyFromEmbedded(
+    doc.getElementById(CONTENT_POLICY_ELEMENT_ID)?.textContent ?? null,
+  );
+}
+
+/**
+ * The Content-Security-Policy values `doc` carries in `<meta http-equiv>` elements: the restrictions
+ * image loading relies on. They are passed to `createFaithfulCardView` with the policy; images
+ * load only when the document carries exactly what that policy derives.
+ */
+export function documentContentSecurityPolicies(doc: Document): string[] {
+  return Array.from(
+    doc.querySelectorAll('meta[http-equiv="Content-Security-Policy" i]'),
+    (meta) => meta.getAttribute('content') ?? '',
+  );
+}

package/src/faithful-card/index.ts

@@ -0,0 +1,40 @@
+// The Lit and MCP Apps stack, card entry: a FaithfulCard application started from one validated
+// definition. The Lit card styles itself; there is no stylesheet to import.
+export { FaithfulCardApp } from '@saga-a2ui/components/faithful-card';
+export type {
+  CardContent,
+  CardResultOutcome,
+  CardResultReader,
+  FaithfulCardAppDefinition,
+} from '@saga-a2ui/components/faithful-card';
+// What an application's `result` reader receives: the delivery-neutral whole result.
+export type { DeliveredResult } from '@saga-a2ui/core/delivered-result';
+export {
+  startFaithfulCardApp,
+  type CardChrome,
+  type CardChromeParts,
+  type CardViewState,
+  type StartFaithfulCardOptions,
+} from './start-faithful-card-app.js';
+export {
+  contentPolicyFromDocument,
+  documentContentSecurityPolicies,
+} from './document-policy.js';
+// The failures `startFaithfulCardApp` reports, and the phase its `onError` callback is told: the
+// same values the main entry exports, so one `catch` serves an application that uses both.
+export {
+  StartError,
+  StartFailure,
+  type ErrorPhase,
+  type StartFailureKind,
+  type StartMisuse,
+} from '../start-failure.js';
+export type { RunningView } from '../running-view.js';
+// A link the card's host can be asked to open, for the application's own chrome.
+export {
+  bindHostLink,
+  type HostLinkBinding,
+  type HostLinkOutcome,
+} from '@saga-a2ui/lit/faithful-card';
+// How the reader meets the host (device or desktop), for an application that maps its own tokens.
+export { readingProfile, type ReadingProfile } from '@saga-a2ui/mcp/view';

package/src/faithful-card/start-faithful-card-app.ts

@@ -0,0 +1,253 @@
+import {
+  readCardResult,
+  type CardResultOutcome,
+  type FaithfulCardAppDefinition,
+} from '@saga-a2ui/components/faithful-card';
+import {
+  createFaithfulCardView,
+  openFaithfulCardSurface,
+  provideContentView,
+  registerFaithfulCard,
+} from '@saga-a2ui/lit/faithful-card';
+import type { CardSurface, ContentView } from '@saga-a2ui/lit/faithful-card';
+import {
+  deliveredResultFromToolResult,
+  hostLinksFromApp,
+} from '@saga-a2ui/mcp/view';
+import type { HostContext, ToolResult } from '@saga-a2ui/mcp/view';
+import { html, render, type TemplateResult } from 'lit';
+import { applicationFailureOf, callApplication } from '../application-call.js';
+import { claimContainer } from '../container-claim.js';
+import { connectToHost, type HostConnection } from '../host-connection.js';
+import {
+  runView,
+  viewFailedBeforeConnecting,
+  viewThatNeverStarted,
+  type RunningView,
+} from '../running-view.js';
+import { StartFailure, type ErrorPhase } from '../start-failure.js';
+import {
+  contentPolicyFromDocument,
+  documentContentSecurityPolicies,
+} from './document-policy.js';
+
+/** What the application’s chrome is told about the card, and what to say beside it. */
+export type CardViewState =
+  | { readonly kind: 'waiting'; readonly text: string }
+  | {
+      readonly kind: 'answer';
+      readonly heading: string | undefined;
+      /** Advances with every presented answer, including one whose text equals the last. */
+      readonly presentation: number;
+    }
+  | { readonly kind: 'problem'; readonly text: string };
+
+/** What the chrome function receives: the card to place, and the state to word around it. */
+export interface CardChromeParts {
+  /** The card. Place it exactly once; it is empty until the first answer. */
+  readonly card: Node;
+  readonly state: CardViewState;
+}
+
+/** The application’s chrome: renders the card and the words around it. Called again on every change of state. */
+export type CardChrome = (parts: CardChromeParts) => TemplateResult;
+
+export interface StartFaithfulCardOptions {
+  /** The element the view is rendered into. Must be attached to the document and free. */
+  readonly container: Element;
+  /** `own`: the view tells the host its size. `host`: the bridge reports it. */
+  readonly sizing: 'own' | 'host';
+  /** Optional. Work the view needs before it shows anything (for example fonts); `signal` aborts when the view ends. */
+  readonly readyWhen?: (signal: AbortSignal) => Promise<void>;
+  /** Optional. The negotiated host context and the host’s name, before the first answer and on change. */
+  readonly hostContext?: (
+    context: HostContext | undefined,
+    hostName: string | undefined,
+  ) => void;
+  /** Optional. The application’s chrome around the card. By default the status text, then the card. */
+  readonly chrome?: CardChrome;
+  /**
+   * Optional. The application's constructable stylesheets for the card. The card sits inside shadow
+   * roots a page stylesheet cannot select into; each connected card adopts these into the root it
+   * lives in (see `createFaithfulCardView`). Custom properties need none of this: they inherit.
+   */
+  readonly styles?: readonly CSSStyleSheet[];
+  /** Optional. Receives a throw from a callback after the view was ready. Defaults to `console.error`. */
+  readonly onError?: (error: unknown, phase: ErrorPhase) => void;
+}
+
+const defaultChrome: CardChrome = ({ card, state }) =>
+  html`${
+    state.kind === 'answer'
+      ? state.heading === undefined
+        ? ''
+        : html`<h2>${state.heading}</h2>`
+      : html`<p role="status">${state.text}</p>`
+  }${card}`;
+
+/**
+ * Starts a card application in `options.container` and returns it at once. The embedded policy is
+ * read from the container’s document, the host is connected with its handlers installed first,
+ * and each delivered result is read by the definition’s one `result` reader and shown in the card: a new
+ * presentation each time, even for equal text. Throws `StartError` (`container-missing`,
+ * `container-busy`) before connecting to anything.
+ * An application callback that throws while the view is being set up (the initial `chrome` call) does not
+ * throw out of `start`: the stack takes back what it made, frees the container and returns a
+ * view whose `ready` rejects with `StartFailure` of kind `application`.
+ */
+export function startFaithfulCardApp(
+  definition: FaithfulCardAppDefinition,
+  options: StartFaithfulCardOptions,
+): RunningView {
+  return startFaithfulCardAppOn(
+    () => connectToHost(definition.identity, options.sizing),
+    definition,
+    options,
+  );
+}
+
+/** {@link startFaithfulCardApp} over a connection the caller supplies: the seam the stack’s own tests use. */
+export function startFaithfulCardAppOn(
+  connect: () => HostConnection,
+  definition: FaithfulCardAppDefinition,
+  options: StartFaithfulCardOptions,
+): RunningView {
+  const claim = claimContainer(options.container);
+  // The view renders into an element of its own, so removing it leaves the container as it was.
+  const mount = document.createElement('div');
+  mount.style.display = 'contents';
+  let stopProviding: (() => void) | undefined;
+  let view: ContentView | undefined;
+  let surface: CardSurface | undefined;
+  try {
+    const { texts } = definition;
+    const chrome = options.chrome ?? defaultChrome;
+    let state: CardViewState = { kind: 'waiting', text: texts.waiting };
+    let card: Node = document.createDocumentFragment();
+    const show = (next: CardViewState): void => {
+      state = next;
+      render(chrome({ card, state }), mount);
+    };
+    const unmount = (): void => {
+      stopProviding?.();
+      mount.remove();
+    };
+    claim.container.append(mount);
+
+    const policy = contentPolicyFromDocument(claim.container.ownerDocument);
+    if (!policy.ok) {
+      callApplication(() =>
+        show({ kind: 'problem', text: texts.policyFailure }),
+      );
+      return viewFailedBeforeConnecting({
+        failure: new StartFailure('policy', policy.failure),
+        unmount,
+        releaseContainer: claim.release,
+        ...(options.onError === undefined ? {} : { onError: options.onError }),
+      });
+    }
+
+    const connection = connect();
+    const lifetime = new AbortController();
+    const cardView = (view = createFaithfulCardView({
+      ...definition.reader,
+      policy: policy.policy,
+      contentSecurityPolicies: documentContentSecurityPolicies(
+        claim.container.ownerDocument,
+      ),
+      hostLinks: hostLinksFromApp(connection.app, lifetime.signal),
+      ...(options.styles === undefined ? {} : { styles: options.styles }),
+    }));
+    registerFaithfulCard();
+    const opened = (surface = openFaithfulCardSurface());
+    card = opened.element;
+    // The card asks the nearest view for its settings when it connects, so the view is provided first.
+    stopProviding = provideContentView(mount, cardView);
+    callApplication(() => show(state));
+
+    const report =
+      options.onError ?? ((error: unknown) => console.error(error));
+    let presentation = 0;
+    const problem = (text: string): void => {
+      opened.clear();
+      show({ kind: 'problem', text });
+    };
+    /**
+     * The definition's one reader decides what the whole result means. A throw from the reader or
+     * from mapping the delivery's result is reported (phase `result`) and rejects the result.
+     */
+    const read = (result: ToolResult): CardResultOutcome =>
+      readCardResult(
+        definition,
+        () => deliveredResultFromToolResult(result),
+        (error) => {
+          try {
+            report(error, 'result');
+          } catch {
+            // A reporter that throws must not stop the answer from clearing.
+          }
+        },
+      );
+
+    return runView({
+      connection,
+      lifetime,
+      releaseContainer: claim.release,
+      sizing: options.sizing,
+      ...(options.readyWhen === undefined
+        ? {}
+        : { readyWhen: options.readyWhen }),
+      ...(options.hostContext === undefined
+        ? {}
+        : { hostContext: options.hostContext }),
+      // Every result is a new selection: `present` ends the earlier presentation, image consent
+      // included, even when the Markdown equals the previous one.
+      onToolResult(result) {
+        const outcome = read(result);
+        if (outcome.kind === 'rejected') {
+          // The application's wording for this rejection, else the definition's.
+          problem(outcome.text ?? texts.problem);
+          return;
+        }
+        if (!opened.present(outcome.content).ok) {
+          problem(texts.problem);
+          return;
+        }
+        presentation += 1;
+        show({
+          kind: 'answer',
+          heading: outcome.content.heading,
+          presentation,
+        });
+      },
+      ...(options.onError === undefined ? {} : { onError: options.onError }),
+      retire() {
+        cardView.consent.retire();
+        opened.dispose();
+      },
+      unmount,
+      showFailure(failure) {
+        const text = {
+          policy: texts.policyFailure,
+          connect: texts.connectFailure,
+          ready: texts.readyFailure,
+          application: texts.problem,
+          disposed: texts.problem,
+        }[failure.kind];
+        show({ kind: 'problem', text });
+        return true;
+      },
+    });
+  } catch (error) {
+    // Nothing connected: take back what this start made and free the container.
+    stopProviding?.();
+    mount.remove();
+    view?.consent.retire();
+    surface?.dispose();
+    claim.release();
+    const failed = applicationFailureOf(error);
+    if (failed === undefined) throw error;
+    // The application's chrome threw before a view existed: `ready` carries the failure.
+    return viewThatNeverStarted(failed.cause);
+  }
+}

package/src/host-connection.ts

@@ -0,0 +1,39 @@
+import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
+
+/**
+ * The two halves of a connection to the MCP Apps host: the bridge and the transport it will connect
+ * over. Making them is the stack’s job so that no application imports the bridge package; a start
+ * takes the pair as a value so a test can supply a bridge joined to an in-memory host.
+ */
+export interface HostConnection {
+  readonly app: App;
+  readonly transport: NonNullable<Parameters<App['connect']>[0]>;
+}
+
+/** What a server tool call answers: the reply type of the bridge’s own `callServerTool`. */
+export type ServerReply = Awaited<ReturnType<App['callServerTool']>>;
+
+export interface HostIdentity {
+  readonly name: string;
+  readonly version: string;
+}
+
+/**
+ * The connection a view uses in a host’s iframe: a bridge named for the application and the
+ * `postMessage` transport to the embedding window. With `own` sizing the view tells the host its
+ * size itself (`startOwnSizing`), so the bridge’s automatic resizing is turned off and sizing has
+ * exactly one owner.
+ */
+export function connectToHost(
+  identity: HostIdentity,
+  sizing: 'own' | 'host',
+): HostConnection {
+  return {
+    app: new App(
+      { name: identity.name, version: identity.version },
+      {},
+      sizing === 'own' ? { autoResize: false } : undefined,
+    ),
+    transport: new PostMessageTransport(window.parent, window.parent),
+  };
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+// The Lit and MCP Apps stack, main entry: an application's own catalog and nothing else. It
+// imports nothing from `@saga-a2ui/components`, so an own-catalog application's emitted browser
+// bundle holds neither the FaithfulCard nor a Markdown parser. (Its installed tree does include
+// them, as declared dependencies of the stack; the card application's entry is `/faithful-card`.)
+//
+// An application that installs this stack and Lit writes its view, its catalog and its actions
+// against the names below and declares no other SDK or upstream package for them. The list is
+// what the qualifying consumers use, no more.
+export {
+  startA2uiView,
+  type BoundSurface,
+  type RunningA2uiView,
+  type StartA2uiViewOptions,
+  type ViewHost,
+} from './start-a2ui-view.js';
+// What a start can fail with and the phase an `onError` callback is told; the card entry shares them.
+export {
+  StartError,
+  StartFailure,
+  type ErrorPhase,
+  type StartFailureKind,
+  type StartMisuse,
+} from './start-failure.js';
+export type { RunningView } from './running-view.js';
+// The shapes of the two notifications an application's handlers receive.
+export type { ToolInput, ToolResult } from '@saga-a2ui/mcp/view';
+// How the reader meets the host (device or desktop), for an application that maps its own tokens.
+export { readingProfile, type ReadingProfile } from '@saga-a2ui/mcp/view';
+// The link opener a running view hands its actions, for an optional card the catalog includes.
+export type { HostLinks } from '@saga-a2ui/core/host-links';
+// The authoring surface of an own-catalog application: the layout and its schemas.
+export { defineSurface } from '@saga-a2ui/core/protocols/a2ui/v0_9';
+export type { SurfaceLayout } from '@saga-a2ui/core/protocols/a2ui/v0_9';
+export { z } from '@saga-a2ui/core/protocols/a2ui/zod3';
+// The catalog an application builds: its components over upstream's component API, and the
+// catalog value and schemas it declares them with.
+export {
+  A2uiLitElement,
+  basicCatalog,
+  Catalog,
+  CommonSchemas,
+  type LitComponentApi,
+} from '@saga-a2ui/lit';
+// The actions an application attaches to the controls it renders.
+export {
+  ActionButton,
+  actionButtonEntry,
+  createLitActions,
+  type ActionButtonActivation,
+  type LitActionsOptions,
+} from '@saga-a2ui/lit/actions';
+export { Action, type ActionBinding } from '@saga-a2ui/core/actions';

package/src/running-view.ts

@@ -0,0 +1,215 @@
+import {
+  runToolResultView,
+  startOwnSizing,
+  ViewStartFailure,
+  type HostContext,
+  type ToolInput,
+  type ToolResult,
+} from '@saga-a2ui/mcp/view';
+import type { HostConnection } from './host-connection.js';
+import { StartFailure, type ErrorPhase } from './start-failure.js';
+
+// What both entries of the stack share once they have something to show: one view in one container
+// whose lifetime is `runToolResultView`'s. It adds what is the stack’s alone: the typed failure,
+// own sizing that starts only once the host can be told, the claim on the container, and when a
+// view that has ended leaves the screen. It decides nothing about what is shown.
+
+/** The handle both entries return, synchronously. */
+export interface RunningView {
+  /**
+   * Settles when the embedded policy was valid, the host connected with the handlers installed
+   * first, the latest host context was applied and the application's readiness work finished.
+   * Rejects with a {@link StartFailure} otherwise. Ignoring it never causes an unhandled rejection.
+   */
+  readonly ready: Promise<void>;
+  /**
+   * Ends the view and removes what it showed, whatever state it is in: ready, still starting, or
+   * failed (a failed view keeps its failure text on screen until it is disposed). Idempotent;
+   * settles after cleanup and never rejects. Afterwards the container may be started again.
+   */
+  dispose(): Promise<void>;
+}
+
+export interface RunViewOptions {
+  readonly connection: HostConnection;
+  /** Aborts when the view ends. Anything the view started for the host (links, sizing) listens to it. */
+  readonly lifetime: AbortController;
+  /** Frees the container; called once, after `unmount`. */
+  readonly releaseContainer: () => void;
+  readonly sizing: 'own' | 'host';
+  readonly readyWhen?: (signal: AbortSignal) => Promise<void>;
+  readonly hostContext?: (
+    context: HostContext | undefined,
+    hostName: string | undefined,
+  ) => void;
+  /** Called for each delivered result once the view is ready (the held one at that moment). */
+  readonly onToolResult: (result: ToolResult) => void;
+  /** Called for the tool call that is starting, once the view is ready and before the held result. */
+  readonly onToolInput?: (input: ToolInput) => void;
+  readonly onError?: (error: unknown, phase: ErrorPhase) => void;
+  /** The first step of ending, once, before the connection ends: retire consent and the surface. */
+  readonly retire: () => void;
+  /** Removes everything the view rendered. Called once. */
+  readonly unmount: () => void;
+  /**
+   * Shows why the view did not start. Returns true when the failure is now on screen, which keeps
+   * the view mounted until it is disposed. Not asked for `disposed`, which shows nothing.
+   */
+  readonly showFailure?: (failure: StartFailure) => boolean;
+}
+
+function startFailureOf(failure: unknown): StartFailure {
+  return failure instanceof ViewStartFailure
+    ? new StartFailure(failure.kind, failure.cause)
+    : new StartFailure('application', failure);
+}
+
+export function runView(options: RunViewOptions): RunningView {
+  const { app, transport } = options.connection;
+  const report = options.onError ?? ((error: unknown) => console.error(error));
+  let onScreen = true;
+  let failureShown = false;
+  let sizingStarted = false;
+
+  const reportError = (error: unknown, phase: ErrorPhase): void => {
+    try {
+      report(error, phase);
+    } catch {
+      // A reporter that throws must not stop cleanup.
+    }
+  };
+
+  /** The view is gone from the screen: unmount, then free the container, whatever unmount did. */
+  const leave = (): void => {
+    if (!onScreen) return;
+    onScreen = false;
+    try {
+      options.unmount();
+    } finally {
+      options.releaseContainer();
+    }
+  };
+
+  const running = runToolResultView({
+    app,
+    transport,
+    ...(options.readyWhen === undefined
+      ? {}
+      : { readyWhen: options.readyWhen }),
+    onToolResult: options.onToolResult,
+    ...(options.onToolInput === undefined
+      ? {}
+      : { onToolInput: options.onToolInput }),
+    onHostContext(context, hostName) {
+      // Told only once the host can hear it: sizing before the handshake would be dropped, and the
+      // size it measured would then count as sent.
+      if (options.sizing === 'own' && !sizingStarted) {
+        sizingStarted = true;
+        startOwnSizing(app, options.lifetime.signal);
+      }
+      options.hostContext?.(context, hostName);
+    },
+    onTeardown(startupFailure) {
+      options.lifetime.abort();
+      const failures: unknown[] = [];
+      try {
+        options.retire();
+      } catch (error) {
+        failures.push(error);
+      }
+      // Whatever ended the view, nothing it showed may outlast its connection. Only a start that
+      // failed keeps something on screen: the failure, which is known only after the connection
+      // has ended (see below).
+      if (startupFailure === undefined) {
+        try {
+          leave();
+        } catch (error) {
+          reportError(error, 'teardown');
+        }
+      }
+      queueMicrotask(() => {
+        void running.dispose().then(() => {
+          if (!failureShown) {
+            try {
+              leave();
+            } catch (error) {
+              reportError(error, 'teardown');
+            }
+          }
+        });
+      });
+      // Every step ran; the runner reports the first thing that threw and still ends the connection.
+      if (failures.length > 0) throw failures[0];
+    },
+    onFailure(failure) {
+      const startFailure = startFailureOf(failure);
+      if (startFailure.kind !== 'disposed')
+        failureShown = options.showFailure?.(startFailure) ?? false;
+    },
+    onError: options.onError ?? ((error, phase) => reportError(error, phase)),
+  });
+
+  const readiness = running.ready.then(
+    () => undefined,
+    (failure: unknown) => {
+      throw startFailureOf(failure);
+    },
+  );
+  readiness.catch(() => undefined);
+
+  return {
+    ready: readiness,
+    async dispose() {
+      await running.dispose();
+      try {
+        leave();
+      } catch (error) {
+        reportError(error, 'teardown');
+      }
+    },
+  };
+}
+
+/**
+ * The view of a start that failed before it connected to anything (an invalid embedded policy):
+ * its failure is already on screen, `ready` rejects with it, and disposing it removes it.
+ */
+export function viewFailedBeforeConnecting(options: {
+  readonly failure: StartFailure;
+  readonly unmount: () => void;
+  readonly releaseContainer: () => void;
+  readonly onError?: (error: unknown, phase: ErrorPhase) => void;
+}): RunningView {
+  let onScreen = true;
+  const ready = Promise.reject<void>(options.failure);
+  ready.catch(() => undefined);
+  return {
+    ready,
+    async dispose() {
+      if (!onScreen) return;
+      onScreen = false;
+      try {
+        options.unmount();
+      } catch (error) {
+        try {
+          (options.onError ?? ((e) => console.error(e)))(error, 'teardown');
+        } catch {
+          // Nothing more to do for a reporter that throws.
+        }
+      } finally {
+        options.releaseContainer();
+      }
+    },
+  };
+}
+
+/**
+ * The view of a start whose application callback threw before anything ran: the stack already took
+ * back what it had made and freed the container, so `ready` rejects with the failure and there is
+ * nothing left to dispose.
+ */
+export function viewThatNeverStarted(cause: unknown): RunningView {
+  const ready = Promise.reject<void>(new StartFailure('application', cause));
+  ready.catch(() => undefined);
+  return { ready, dispose: () => Promise.resolve() };
+}

package/src/server/index.ts

@@ -0,0 +1,14 @@
+// The server entry of the stack: what an application's MCP server composes to serve a card or an
+// own-catalog view, from the same package it installs for the view. It re-exports the delivery
+// owner's named operations and nothing from a renderer, `@saga-a2ui/components` or the browser
+// entries, so a server never loads a renderer and a browser bundle never loads a server module.
+// The operations, their failures and their lifetimes are specified in `@saga-a2ui/mcp/server`.
+export {
+  attachRequestLifetime,
+  createServerBudgets,
+  operationViewFromHtml,
+  registerPublicOperation,
+  viewUriForHtml,
+  type OperationView,
+  type RequestLifetime,
+} from '@saga-a2ui/mcp/server';

package/src/start-a2ui-view.ts

@@ -0,0 +1,263 @@
+import type { LitComponentApi } from '@a2ui/lit/v0_9';
+import type { Catalog } from '@a2ui/web_core/v0_9';
+import type { ServerTransport } from '@saga-a2ui/core/actions';
+import { type SurfaceLayout } from '@saga-a2ui/core/protocols/a2ui/v0_9';
+import {
+  createA2uiAppElement,
+  defineElements,
+  type A2uiActions,
+  type A2uiUpdateResult,
+} from '@saga-a2ui/lit';
+import type { HostLinks } from '@saga-a2ui/core/host-links';
+import {
+  hostLinksFromApp,
+  type HostContext,
+  type ToolInput,
+  type ToolResult,
+} from '@saga-a2ui/mcp/view';
+import {
+  applicationFailureOf,
+  callApplication,
+  failApplication,
+} from './application-call.js';
+import { claimContainer } from './container-claim.js';
+import {
+  connectToHost,
+  type HostConnection,
+  type HostIdentity,
+  type ServerReply,
+} from './host-connection.js';
+import {
+  runView,
+  viewThatNeverStarted,
+  type RunningView,
+} from './running-view.js';
+import type { ErrorPhase } from './start-failure.js';
+
+/** What the application may use of the host while it states its actions. */
+export interface ViewHost {
+  /** The way an action reaches the application’s server, through the host. */
+  readonly server: ServerTransport<ServerReply>;
+  /** The one way to ask the host to open a link, for an optional card the application's catalog includes. Ends with the view. */
+  readonly links: HostLinks;
+}
+
+/** The typed way to change what a running view shows. */
+export interface BoundSurface<TData> {
+  /**
+   * Validates `data` against the layout and applies it in place: no remount, so the mounted
+   * controls, their action bindings and focus survive. Never throws. A rejection (data the layout’s
+   * schema refuses, or a view that has ended) returns the failure and changes nothing.
+   */
+  update(data: TData): A2uiUpdateResult;
+}
+
+export interface StartA2uiViewOptions<TData> {
+  /** The element the view is rendered into. Must be attached to the document and free. */
+  readonly container: Element;
+  /** The one surface the view presents: its identity, its data type and how it opens. */
+  readonly layout: SurfaceLayout<TData>;
+  /**
+   * The application's own catalog. The stack defines each component's custom element (repeating
+   * that for a catalog that is already defined is harmless).
+   */
+  readonly catalog: Catalog<LitComponentApi>;
+  /**
+   * Optional. The application’s action setup (`createLitActions`), or a function that makes it
+   * from the host when the setup needs the server (`host.server`).
+   */
+  readonly actions?:
+    A2uiActions | ((host: ViewHost) => A2uiActions | undefined);
+  /** Optional. Work the view needs before it shows anything; `signal` aborts when the view ends. */
+  readonly readyWhen?: (signal: AbortSignal) => Promise<void>;
+  /** `own`: the view tells the host its size. `host` (the default): the bridge reports it. */
+  readonly sizing?: 'own' | 'host';
+  /** Optional. The negotiated host context and the host’s name, before the first result and on change. */
+  readonly hostContext?: (
+    context: HostContext | undefined,
+    hostName: string | undefined,
+  ) => void;
+  /**
+   * Optional. The tool call that is starting, with its own arguments: the only place the host
+   * announces them. Delivered once the view is ready, before the held result. It is not that
+   * call's response and authenticates nothing.
+   */
+  readonly onToolInput?: (input: ToolInput) => void;
+  /** Each delivered result, once the view is ready. Update the surface through `view.surface`. */
+  readonly onToolResult: (
+    result: ToolResult,
+    view: RunningA2uiView<TData>,
+  ) => void;
+  /**
+   * Optional. Called once, whichever way the view ends (host teardown request, `dispose()`,
+   * `pagehide` or a startup failure), after the surface has been retired and before the connection
+   * ends. For an application that holds something outside the page's own rendering. It must
+   * tolerate being called on a view that never showed anything; a throw is reported and never
+   * skips the connection's disposal.
+   */
+  readonly onTeardown?: () => void;
+  /** Optional. Receives a throw from a callback after the view was ready. Defaults to `console.error`. */
+  readonly onError?: (error: unknown, phase: ErrorPhase) => void;
+  /** Optional. Who the host sees. Defaults to the layout’s surface id at version `0.0.0`. */
+  readonly identity?: HostIdentity;
+}
+
+/** The running view of an own-catalog application, and the typed way to update what it shows. */
+export interface RunningA2uiView<TData> extends RunningView {
+  readonly surface: BoundSurface<TData>;
+}
+
+/** Each view is its own custom element, so each needs a tag of its own. */
+let views = 0;
+
+/**
+ * Starts an own-catalog view in `options.container` and returns it at once. The view connects to
+ * the MCP Apps host, holds results that arrive before it is ready, presents the layout over the
+ * catalog and gives each result to `onToolResult` with the bound surface to update. Throws
+ * `StartError` (`container-missing`, `container-busy`) before connecting to anything.
+ * An application callback that throws while the view is being set up (the `actions` factory) does not
+ * throw out of `start`: the stack takes back what it made, frees the container and returns a
+ * view whose `ready` rejects with `StartFailure` of kind `application`. Imports
+ * nothing from `@saga-a2ui/components`.
+ */
+export function startA2uiView<TData>(
+  options: StartA2uiViewOptions<TData>,
+): RunningA2uiView<TData> {
+  return startA2uiViewOn(
+    () =>
+      connectToHost(
+        options.identity ?? {
+          name: options.layout.surfaceId,
+          version: '0.0.0',
+        },
+        options.sizing ?? 'host',
+      ),
+    options,
+  );
+}
+
+/** {@link startA2uiView} over a connection the caller supplies: the seam the stack’s own tests use. */
+export function startA2uiViewOn<TData>(
+  connect: () => HostConnection,
+  options: StartA2uiViewOptions<TData>,
+): RunningA2uiView<TData> {
+  const claim = claimContainer(options.container);
+  let element: Element | undefined;
+  try {
+    const connection = connect();
+    const { app } = connection;
+    const lifetime = new AbortController();
+    const { actions: makeActions } = options;
+    const actions =
+      typeof makeActions === 'function'
+        ? callApplication(() =>
+            makeActions({
+              server: {
+                callServerTool: (request, requestOptions) =>
+                  app.callServerTool(request, requestOptions),
+              },
+              links: hostLinksFromApp(app, lifetime.signal),
+            }),
+          )
+        : makeActions;
+
+    // The app element presents the surface, and so starts the actions, as it connects. A setup
+    // that throws there is swallowed into the element's safe fallback after the application's sink
+    // heard it; the stack notes it here, so the start fails as `application` instead of reporting
+    // a view that shows nothing. Only the first presentation, made as the element connects, counts.
+    let connecting = true;
+    let setupFailure: { readonly cause: unknown } | undefined;
+    const watched: A2uiActions | undefined =
+      actions === undefined
+        ? undefined
+        : {
+            begin(mount) {
+              try {
+                return actions.begin(mount);
+              } catch (error) {
+                if (connecting) setupFailure ??= { cause: error };
+                throw error;
+              }
+            },
+          };
+
+    defineElements([...options.catalog.components.values()]);
+    const AppElement = createA2uiAppElement({
+      catalog: options.catalog,
+      layout: options.layout,
+      ...(watched === undefined ? {} : { actions: watched }),
+    });
+    views += 1;
+    customElements.define(`saga-a2ui-view-${views}`, AppElement);
+    const shown = new AppElement();
+    element = shown;
+    try {
+      claim.container.append(shown);
+    } finally {
+      connecting = false;
+    }
+    if (setupFailure !== undefined) failApplication(setupFailure.cause);
+
+    const surface: BoundSurface<TData> = {
+      update: (data) => shown.updateData(data),
+    };
+    const remove = (): void => shown.remove();
+
+    const running = runView({
+      connection,
+      lifetime,
+      releaseContainer: claim.release,
+      sizing: options.sizing ?? 'host',
+      ...(options.readyWhen === undefined
+        ? {}
+        : { readyWhen: options.readyWhen }),
+      ...(options.hostContext === undefined
+        ? {}
+        : { hostContext: options.hostContext }),
+      onToolResult: (result) => options.onToolResult(result, view),
+      ...(options.onToolInput === undefined
+        ? {}
+        : { onToolInput: options.onToolInput }),
+      ...(options.onError === undefined ? {} : { onError: options.onError }),
+      retire() {
+        try {
+          remove();
+        } finally {
+          options.onTeardown?.();
+        }
+      },
+      unmount: remove,
+    });
+    const view: RunningA2uiView<TData> = { ...running, surface };
+    return view;
+  } catch (error) {
+    element?.remove();
+    claim.release();
+    const failed = applicationFailureOf(error);
+    if (failed === undefined) throw error;
+    // The application's own callback threw before a view existed: nothing connected, so what was
+    // made is gone and the view ends as it would for any other startup failure, with `onTeardown`
+    // told once. `ready` carries the failure; the container is free for another start.
+    try {
+      options.onTeardown?.();
+    } catch (teardownError) {
+      try {
+        (options.onError ?? ((e) => console.error(e)))(
+          teardownError,
+          'teardown',
+        );
+      } catch {
+        // A reporter that throws must not turn a typed startup failure into a throw.
+      }
+    }
+    return {
+      ...viewThatNeverStarted(failed.cause),
+      surface: {
+        update: () => ({
+          ok: false,
+          failure: { kind: 'rejected', message: 'The app is not connected.' },
+        }),
+      },
+    };
+  }
+}

package/src/start-failure.ts

@@ -0,0 +1,41 @@
+import type { ViewErrorPhase, ViewFailureKind } from '@saga-a2ui/mcp/view';
+
+/**
+ * Why a view did not become ready.
+ *
+ * - `policy`: the embedded content policy is malformed or not valid; no connection was made.
+ * - `connect`: the handshake with the host failed.
+ * - `ready`: the application's own readiness work rejected.
+ * - `application`: an application callback threw while the view was starting. Cleanup completed
+ *   before this was reported.
+ * - `disposed`: the view was ended (dispose, host teardown or `pagehide`) before it was ready.
+ */
+export type StartFailureKind = 'policy' | ViewFailureKind;
+
+/** The reason `ready` rejects. */
+export class StartFailure extends Error {
+  constructor(
+    readonly kind: StartFailureKind,
+    readonly cause?: unknown,
+  ) {
+    super(`The view did not become ready (${kind}).`);
+    this.name = 'StartFailure';
+  }
+}
+
+/** Where an application callback threw after the view was ready. */
+export type ErrorPhase = ViewErrorPhase;
+
+/** Misuse of `start`, thrown before any connection is made. */
+export type StartMisuse = 'container-missing' | 'container-busy';
+
+export class StartError extends Error {
+  constructor(readonly code: StartMisuse) {
+    super(
+      code === 'container-busy'
+        ? 'container-busy: a view is already running in this container; dispose it first.'
+        : 'container-missing: the container is missing or not attached to the document.',
+    );
+    this.name = 'StartError';
+  }
+}