[timeleft--]

Change

This PR proposes two draft designs for review. It changes no code.

Today a React developer has a published stack but no starter. Nothing shows an assistant taking part in an app, either. A view can call its own server, but it has no supported way to tell the assistant that it is the assistant's turn.

• Getting-started tracks (status: draft) proposes:
  • a qualified React/Hono starter pair, saga init --a2ui-stack react-mcp --server hono DIR, from a new templates/react-hono whose server/ shares the lit-hono text;
  • splitting the setup guide into a common guide plus two build tracks: notes with Lit (existing material moved) and tic-tac-toe with React (new);
  • the tic-tac-toe example:
    • The person clicks squares, and the host's assistant plays O through the same play_move operation. The server enforces turns, occupancy, completion and expectedMoveNumber staleness.
    • After an X move, the board appends a short move message, with the accepted game as best-effort context. The message names the game and never restates the board, and the viewless get_game is the assistant's fallback read.
    • A winning or drawing X move appends a result message instead, which asks for no move.
    • The board learns the assistant's move through a bounded get_game wait. MCP Apps delivers a model call's result to a card mounted for that call, not to the board that is already open.
  • operations without a view. view becomes optional on saga operation declarations, so play_move and get_game are saga operations that open no card. Three requirements apply:
    • the same input and output contracts, budgets, cancellation handling and safe failures;
    • no view resource and no UI metadata on definitions or results;
    • one consumer interface, with any plain MCP registration kept inside @saga-a2ui/mcp;
  • the "Simple Agentic Apps" expansion change on the current brand surfaces.
• View conversation (status: draft) proposes a delivery-neutral Conversation contract in @saga-a2ui/core, exposed as ViewHost.conversation in both stacks:
  • appendMessage(text, {role?, context?}). On MCP Apps, context becomes ui/update-model-context sent before ui/message.
  • By default, a context that can't be delivered blocks the message. context.bestEffort opts into sending the message anyway. The result names the stage that stopped the append, or the context that was skipped.
  • Applications recheck their own state identity when the request settles, because an action's current() ends with its hook.
  • A2A is mapped (one message/send, with context as a data part) but not proposed.
• Application setup records the draft successor and stays current until approval.
• Two new diagrams, diagrams/tic-tac-toe-turn-loop and diagrams/view-conversation, ship with their Mermaid sources.

Neither design is approved. This PR asks for human design approval of both Blueprints at this PR's head revision, including the diagrams. Implementation tickets follow only after that approval. The one remaining open decision is the wait's cadence and limit, which host runs will settle.

Validation

• python3 scripts/check-blueprint-length.py --base origin/main: only advisory length warnings.
• python3 scripts/mw-version.py check --base origin/main: "Version policy passed", with no component changed. Blueprints and diagrams are excluded paths.
• Relative links and anchors in the changed Blueprints resolve, checked by a local script.
• Both diagrams were rendered from their .mmd sources with Mermaid 11.4.1 in Chromium, then inspected. python3 scripts/check-lfs.py validated the PNG pointers, and git lfs push uploaded them.
• No code or host checks were run, because this PR proposes design only. The host behaviour the designs rely on comes from the @modelcontextprotocol/ext-apps 2.0.3 typings and is unverified in Claude, ChatGPT and Alexa+:
  • ui/message and ui/update-model-context support;
  • context being deferred to the next user message;
  • how a host places a model call's card.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vus14ntFwS1mYMaD3siMkK

[yia-mw-agent]

Helmet-Review-Request: #320 (comment)

Reviewed the full merge-base-to-head diff (base main, merge-base a5cf9d0, head 6c3638b, 10 files, +564/-0) at the exact head.

No material defects found. This PR is documentation and diagrams only, and both Blueprints stay status: draft.

What I checked:

• Both new Blueprints follow the lifecycle rules in blueprints/README.md: draft status, a Status section, Implementation "not started", and the successor note in application_setup.blueprint.md that leaves the approved design current until approval.
• Relative links and anchors in the four changed Markdown files all resolve (local script). The SVG, PNG pointer and Mermaid source for both diagrams are present.
• The repo claims the designs rest on match the tree: templates/ has only the Lit templates; SUPPORTED_PAIRS and the react-mcp refusal tests exist in scripts/saga.ts and saga.test.ts; OperationView is currently required in packages/mcp/src/server/operation.ts; hostLinksFromApp lives in packages/mcp/src/view; the Lit stack's ViewHost has links, the React stack's does not; the lit-hono pins (hono 4.13.13, @hono/node-server 1.19.17, @modelcontextprotocol/hono 2.0.2) and the <starter-app marker in operations.ts are as described.
• CI on this head passes: build/test/qualification, documentation and policy, version policy, GitBook. check-blueprint-length reports only the advisory word-count warnings. A local mw-version.py run failed only for lack of a PR title in my environment, and check-lfs.py failed because git-lfs is not installed here. I relied on the passing CI jobs for both.

Non-blocking observations:

• This approval covers the PR's content and hygiene. It is not the human design approval the description asks for. Both Blueprints need that approval of this head revision, diagrams included.
• The host behaviour the designs rely on (ui/message, ui/update-model-context, how a host places a model call's card) is unverified in Claude, ChatGPT and Alexa+. The PR says so, and the wait cadence is correctly left as an open decision.
• play_move is callable by the model for either player. The design states this tradeoff and keeps the server authoritative through expectedMoveNumber.