Design Plans¶
Stable architecture and rationale for the published StoryTangl subsystems.
See also¶
Code-Adjacent Design Docs for design notes that still live beside source modules and should eventually be folded into this section.
- Canonical Vocabulary
- Conceptual Foundations
- Simplification Spec
- Content-Addressable Records
- Dereferencing GraphItems
- Hookable Dispatch Tasks
- Mechanics Families
- StoryTangl Widget Vocabulary
- 0 · Conventions and principles
- 1 · Top-level contract — Tier S
- 2 · Fragment widgets — Tier S
- 2.1
content— Prose block - 2.2
attributed— Dialog line - 2.3
media— Media frame - 2.4
group— Container - 2.5
kv— Key/value rows (unified shape) - 2.6
choice— Player commit point - 2.7
control— Silent fragment mutation - 2.8
user_event— Toast / silent stash - 2.9
interpretation— Backend command-resolution feedback (Tier P1)
- 2.1
- 3 · ProjectedState section values — Tier S
- 4 · Bundle customization — Tier S
- 5 · Conformance contracts
- 6 · Tier P1 — typed contract surfaces
- 7 · Tier P2 — interactive surface vocabulary (proposed, larger)
- 8 · Tier P3 — genre extensions (deferred)
- 9 · Port parity reference (Tier S + Tier P1)
- 10 · Conformance
- Appendix A — Glossary
- Appendix B — Open questions (working list)
- Appendix C — Cross-references to genre extensions
- Widget Contract Reconciliation
- How to read this doc
- §A — Tier S surfaces (core contract)
- §B — Tier P1 surfaces (target for next engine epoch)
- §C — Tier P2 surfaces (interactive surface vocabulary)
- §D — Tier P3 genre extension surfaces
- §E — API transport (Layer 2)
- §F — Conformance harness
- §G — Recent reconciliation events
- §H — How to use this doc
- §I — Forward-looking sequence
- StoryTangl Widget Wireframes
- StoryTangl Brand References
- StoryTan⅁l · brand usage
- 1. The mark
- 2. Where each asset goes
- 3. SVGs are font-dependent — when to convert to paths
- 4. The lockup is the wordmark or the wordmark + glyph — never the glyph alone with text
- 5. The ⅁ character (U+2141) is the ASCII fallback
- 6. Type stack rules
- 7. Palette rules
- 8. Voice and tone rules
- 9. What an agent must never do
- 10. Provenance
- Genre Audit Notes — v1.5
- Carwars Bundle — Widget Vocabulary Extensions
- 0 · Genre summary
- 1 · Slot-zone conventions
- 2 · Catalog conventions
- 3 · Pre-roll choice →
RollFragmentflow - 4 ·
ui_hints.dragtyped sub-shape - 5 · Worked example — Garage turn
- 6 · Combat-resolution patterns
- 7 · Edge cases — canonical responses
- 8 · Testing patterns
- 9 · Port parity addendum (carwars-specific widgets)
- Appendix — BGG mechanism coverage
- Credentials Bundle — Widget Vocabulary Extensions
- 0 · Genre summary
- 1 · Domain vocabulary mapped to v1.5
- 2 · Packet zone conventions
- 3 · Findings as annotated KvRows
- 4 · Mediation moves
- 5 · Disposition severity
- 6 · Restriction map projection
- 7 · Shift summary
- 8 · Worked example — one candidate, three turns
- 9 · Time pressure
- 10 · Port parity addendum
- Appendix — Prior art
- Elefant Hunt Bundle — Widget Vocabulary Extensions
- 0 · Genre summary
- 1 · Domain vocabulary mapped to v1.5
- 2 · Board topology
- 3 · Movement
- 4 · Hunters as mobs
- 5 · The hunt — composite RollFragment
- 6 · Hazard examples
- 7 · Port scoring
- 8 · Solitaire mode — beat the blind
- 9 · Multi-cursor framing (Tier P1 target)
- 10 · The journal-as-story validation
- 11 · Port parity addendum
- Appendix — Prior art
- Training Bundle — Widget Vocabulary Extensions
- 0 · Genre summary
- 1 · Domain vocabulary mapped to v1.5
- 2 · Mood as growth modulator
- 3 · Scheduled events and skill checks
- 4 · Inventory unlocks
- 5 · Weekly study commit (richer compose form)
- 6 · Worked example — Week 2 of coronate_the_regent
- 7 · Forward direction (Tier P3 aspirational)
- 8 · Port parity addendum
- Appendix — Prior art
- Interaction Vocabulary
- Journal Compose Contract
- Presence/Prose Contract Spike
- Conditional Narratives in StoryTangl
- Singleton Asset: Type/Token Pattern
- Concept Provisioning Design
- Core Philosophy
- Declaration Semantics
- Reference Semantics in Roles/Settings
- Shorthand Syntax
- Cost Model & Selection
- World Creation Modes
- Dependency Retargeting Policy
- Provisioner Behavior
- Lifecycle and Persistence
- Common Patterns
- Anti-Patterns
- Implementation Checklist
- Future Enhancements
- Implementation Status
- Hub Fanout and Sandbox Assembly
- Problem Statement
- Core Idea
- Definitions
- Relationship to Existing Vocabulary
- Compile-Time vs Runtime Responsibilities
- Scope Model
- Refresh Policies
- Projection Rules
- Sandbox as a Fanout Consumer
- Re-entrant Providers and Cycle Instances
- Minimal Data Shape
- Non-Goals
- Implementation Direction
- Current Implementation Status
- Related
- MenuBlock: Dynamic Choice Hubs
- Story Compilers
- How create world should work
- Cost Model & Offer Selection
- Planning & Provisioning System Design (v3.7)
- Executive Summary
- Core Concepts
- Architecture Overview
- The Planning Cycle
- Provisioning Mechanics
- What’s Implemented ✅
- What’s Missing ⚠️
- Integration Points
- Usage Examples
- Testing Strategy
- References
- Revision History
- Provisioning Pipeline
- Provisioning Behavior for Authors
- Template Scope
- Template System
- Navigation vs Automatic Redirects
- Story Entry Resolution
- Canonical Single-Source/Single-Sink Form
- Sinks, Softlocks, and Escape Hatches
- Service Layer Architecture (v3.7)
- Response Type Decision Matrix
- Fragment Stream Contract
- Media Subsystem Design
- Generative Media Design
- Implementation Status
- Context and Motivation
- Design Summary
- Part 1: Pending-RIT Lifecycle
- Part 2: Media Authority Chain — Dispatch, Not Hierarchy
- Part 3: Media Registries and Spec Templates
- Part 4: Phase-Bus Reconciliation Hooks
- Part 5: Anticipatory Media Affordances
- Part 6: Service Layer — MediaRenderProfile
- Part 7: WorkerDispatcher Interface
- Part 8: Scope of Changes (Implementation Checklist)
tangl/media/media_resource/media_resource_inv_tag.pytangl/media/media_creators/media_spec.pytangl/media/media_resource/media_dependency.pytangl/media/media_resource/media_provisioning.pytangl/media/media_resource/media_spec_registry.py(future)tangl/media/worker_dispatcher.py(new)tangl/media/phase_hooks.py(new)tangl/service/media.pytangl/service/(REST adapter / runtime controller)- Deferred
- Invariants
- Open Questions (Deferred)
- Future: Generative Prose as a Sibling System
- Relationship to Existing Design Documents