@saga-a2ui/react-mcp-stack 0.0.0-stage → 0.7.6

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,17 @@
-# Temporary Holding Version
+# @saga-a2ui/react-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 React stack for an MCP Apps view: it connects one React renderer to one delivery, the host's MCP Apps bridge, so an application writes only its own decisions. Entry points:
+
+- `.`: `startA2uiView` for an own-catalog A2UI view, `createReactActions`, the authoring exports, and `readingProfile`.
+- `/faithful-card`: `FaithfulCardApp`, `startFaithfulCardApp`, `CardResultOutcome`, `CardResultReader`, `DeliveredResult` (what the definition's one `result` reader receives), `useHostLink` and `readingProfile`.
+- `/faithful-card.css`: the card's stylesheet.
+- `/content-policy`: `createContentPolicy` and `embedContentPolicy`, for the server that states the policy the card application reads from its document.
+- `/server`: `createServerBudgets`, `registerPublicOperation`, `operationViewFromHtml`, `viewUriForHtml`, `attachRequestLifetime`, and the types `OperationView` and `RequestLifetime`. Node only; no browser entry imports it.
+
+The main entry does not import `@saga-a2ui/components`, so an own-catalog bundle contains neither FaithfulCard nor Markdown. The package still declares the components package, so one install makes the `/faithful-card` and `/content-policy` entries work. React and React DOM are peers, both exactly 19.3.1.
+
+Requires Node >=22.12.0 and a TypeScript-aware bundler; exports are TypeScript source. Apache-2.0, with dependency licenses retained separately.
+
+Release candidates are published under the npm `next` tag. Pin the same exact version of all saga a2ui packages used by your application.
+
+See [the installation recipe](https://github.com/MachineWisdomAI/saga-a2ui/blob/main/docs/release-packages.md).

package/package.json

@@ -1,6 +1 @@
-{
-  "name": "@saga-a2ui/react-mcp-stack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{"name":"@saga-a2ui/react-mcp-stack","private":false,"description":"The React and MCP Apps stack for SAGA A2UI: starts a view for an application's own catalog, and a FaithfulCard application from one validated definition, so an application installs one stack plus React and writes only its own decisions","license":"Apache-2.0","type":"module","sideEffects":["**/*.css"],"exports":{".":"./src/index.ts","./faithful-card":"./src/faithful-card/index.ts","./content-policy":"./src/content-policy/index.ts","./server":"./src/server/index.ts","./faithful-card.css":"./src/faithful-card/faithful-card.css"},"files":["src","!src/**/*.test.ts","!src/**/*.test-support.ts"],"scripts":{"typecheck":"tsc --noEmit"},"dependencies":{"@modelcontextprotocol/ext-apps":"2.0.3","@saga-a2ui/components":"0.7.6","@saga-a2ui/core":"0.7.6","@saga-a2ui/mcp":"0.7.6","@saga-a2ui/react":"0.7.6","zod":"4.6.7"},"peerDependencies":{"react":"19.3.1","react-dom":"19.3.1"},"devDependencies":{"@modelcontextprotocol/client":"2.3.1","@types/node":"22.20.5","@types/react":"19.3.0","@types/react-dom":"19.3.0","jsdom":"28.1.0","react":"19.3.1","react-dom":"19.3.1","typescript":"^5.9.0","vitest":"^5.0.4"},"version":"0.7.6","engines":{"node":">=22.12.0"},"repository":{"type":"git","url":"https://github.com/MachineWisdomAI/saga-a2ui.git","directory":"packages/react-mcp-stack"},"publishConfig":{"access":"public","tag":"next"}}

package/src/action-setup.ts

@@ -0,0 +1,53 @@
+import type { ReactActions } from '@saga-a2ui/react/actions';
+import { createElement, useEffect, type ReactNode } from 'react';
+import { applicationFailureError } from './application-call.js';
+
+// The application's action setup (`createReactActions`) runs in an effect of the first mount, and
+// the actions boundary swallows a throw from it once the application's sink has heard it: nothing
+// rejects and nothing is rendered, so on its own a start would be "ready" with an empty view. The
+// setup is the application's own callback running while the view starts, so the stack watches it
+// without taking it over. The sink still hears every error first; the stack then holds readiness
+// until the setup has been attempted and fails the start as `application` if it threw.
+
+export interface WatchedActionSetup {
+  /** The same actions, with their sink also telling the watch. */
+  readonly actions: ReactActions;
+  /** Shown beside the surface inside the actions scope: its effect runs after the setup's. */
+  readonly marker: ReactNode;
+  /**
+   * Settles once the setup was attempted: resolves when it did not throw; rejects with the
+   * application's failure (see `applicationFailureOf`) when it did. Settles at most once.
+   */
+  readonly attempted: Promise<void>;
+}
+
+function SetupAttempted(props: { readonly attempted: () => void }): null {
+  const { attempted } = props;
+  useEffect(() => attempted(), [attempted]);
+  return null;
+}
+
+export function watchActionSetup(actions: ReactActions): WatchedActionSetup {
+  let resolve!: () => void;
+  let reject!: (reason: unknown) => void;
+  const attempted = new Promise<void>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  // Handled here: whether anyone awaits readiness or not is not this promise's concern.
+  attempted.catch(() => undefined);
+  return {
+    actions: Object.freeze({
+      ...actions,
+      onSetupError(error: unknown): void {
+        try {
+          actions.onSetupError(error);
+        } finally {
+          reject(applicationFailureError(error));
+        }
+      },
+    }),
+    marker: createElement(SetupAttempted, { attempted: resolve }),
+    attempted,
+  };
+}

package/src/application-call.ts

@@ -0,0 +1,39 @@
+// 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 failure as a value, for work that settles after `start` returned (a readiness
+ * gate): `ready` then rejects as `application`, as for a throw from the synchronous part.
+ */
+export function applicationFailureError(cause: unknown): unknown {
+  return 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/faithful-card.css

@@ -0,0 +1,2 @@
+/* The card stylesheet, re-exported so an application imports it from its stack. */
+@import '@saga-a2ui/react/faithful-card.css';

package/src/faithful-card/index.ts

@@ -0,0 +1,35 @@
+// The React and MCP Apps stack, card entry: a FaithfulCard application started from one validated
+// definition. Import the card's stylesheet from `@saga-a2ui/react-mcp-stack/faithful-card.css`.
+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 CardChromeProps,
+  type CardViewState,
+  type StartFaithfulCardOptions,
+} from './start-faithful-card-app.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 {
+  useHostLink,
+  type HostLink,
+  type HostLinkOutcome,
+} from '@saga-a2ui/react/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';