# Interaction Vocabulary Review Appendix

> Status: Non-normative source notes
> Sources: prior interaction-vocabulary review notes, reviewed during the
> April 2026 fragment-renderer design pass.

This appendix preserves the useful pressure from the interaction vocabulary
review without making every brainstormed mechanism part of the current contract.
The normative contract lives in
`docs/src/design/service/FRAGMENT_STREAM_CONTRACT.md` and
`docs/src/design/story/INTERACTION_VOCABULARY.md`.

## Central Framing

The review argued that StoryTangl should not try to define a universal game
engine vocabulary. The missing layer is narrower and more useful:

> a cross-client interaction-rendering vocabulary between authored/runtime logic
> and concrete UI affordances.

That layer lets a rich web client render cards, zones, hidden hands, and media
while a CLI still renders the same interaction as text, state, and numbered
choices.

## Adjacent Systems

The review compared StoryTangl with several neighboring systems.

| Reference family | Useful lesson |
| --- | --- |
| Ludii / ludemes | Use containers, components, moves, and end conditions as coverage checks. |
| GDL / General Game Playing | Enumerate legal moves, but keep rule reasoning inside the engine. |
| Zillions / board-game DSLs | Borrow board, piece, move, capture, and skinning ideas without centering boards. |
| BoardGameGeek mechanisms | Use mechanism names as coverage tags, not primitive schema fields. |
| Inform 7 | Preserve scope, visibility, and the distinction between observing and changing. |
| Ink / Yarn / Twine / Ren'Py | Keep runner/view separation and graceful line/option degradation. |
| Vassal / tabletop platforms | Use zones, decks, hands, tokens, logs, and permissions as UI surface examples. |
| WAI-ARIA | Compile StoryTangl semantics down to accessible widgets; do not use ARIA as the game vocabulary. |
| Machinations / Petri nets | Model resource loops as places, tokens, transitions, rates, and ledgers. |
| ECS | Prefer small capabilities/components over a subclass for every interaction kind. |
| xAPI / Open Game Data | Treat interaction requests, user actions, and state transitions as auditable records. |

## Mechanics Survey Highlights

The mechanics survey found a stable engine-side pattern:

- `Game` is the mutable round state.
- `GameHandler` is the stateless rules engine.
- `RoundRecord` is immutable history.
- strategy registries encode opponent behavior and scoring policy.
- handlers expose legal moves and resolve committed moves.

Known mechanics already fit this model:

- rock-paper-scissors and trivial test games
- Blackjack/21/22 sketches
- Nim and piece games
- Bag RPS typed-resource commitments
- credentials/Papers-Please-like inspection loops
- Calvin Cards contested card checks
- incremental/resource loops

The conclusion was that UI vocabulary should mirror exposed player surfaces
rather than invent a second game model.

## Adopted Design Pressures

These ideas were adopted into the current vocabulary:

- separate rules, interaction, presentation, and narrative projection
- distinguish affordance from handler-facing move
- represent zones and entities as renderable fragments or group members
- make hidden/visible/revealed state explicit
- keep unavailable choices visible with blocker diagnostics
- preserve action history as an audit trail
- support graceful degradation from rich widgets to text choices
- treat resource and piece pools as first-class interaction surfaces

## Deferred Ideas

These remain useful but are intentionally deferred:

- full Ludii-like formal game descriptions
- client-side general game playing or rule inference
- universal board topology
- full telemetry/xAPI compatibility
- a complete interaction record model replacing `RoundRecord`
- presentation-profile negotiation beyond current `ui_hints`
- browser E2E for rich interaction widgets before the widgets stabilize

## Coverage Checklist For Future Fixtures

Future fixtures should exercise one interaction family at a time:

- visible zone plus selectable piece
- hidden card or document with reveal state
- unavailable affordance with structured blockers
- quantity or resource-spend payload
- inspect/reveal action that changes visible state
- control update/delete that mutates a prior fragment
- result or user-event fragment that explains an outcome

If a fixture cannot still degrade into readable state plus choices, the contract
is probably leaking too much client-specific UI structure.