Musewoods · GroveThe Musewoods Field Manual

Architecture & Validation

Musewoods is easiest to understand as a set of explicit boundaries rather than as a collection of page components. Content enters through field discovery, passes through shared parsing primitives, is normalized into the field's own model, validated against registered structure, and only then reaches a renderer. That sequence keeps authored intent legible and gives failures a predictable place to occur.

The fields are intentionally allowed to diverge where their editorial models require it. Stories, Journals, Viewgraphs, and Groves do not share one giant schema; they share a disciplined pipeline shape and common semantic engines where the underlying responsibility is actually the same. Navigation System sources follow the same architectural discipline without becoming publishing fields: Trailhead v2 normalizes semantic journeys, while Trailmap v9 normalizes graph topology and projection hints before either reaches its renderer.

The End-To-End Flow

Figure 1

Rendering diagram…

The architectural value of the pipeline is not the number of boxes. It is that each box has a narrow responsibility: discovery does not validate, parsing does not decide presentation, validation does not repair source, and rendering does not invent undocumented structure.

The End-To-End Flow, Step By Step

  1. 01 Discover

    Each field owns a discover step that walks the appropriate content root and returns descriptors. Discovery identifies what exists and how it is addressed; it should not make editorial validity decisions. Reserved route segments keep Story discovery from colliding with application routes and the other publishing fields. The Navigation System adds application namespaces such as trailheads and trailmaps, while Resonance adds resonance-lab and r; those must remain reserved from Story routing. The Clearing design does not introduce a fifth field namespace: its durable human projection is expected to remain a Grove while semantic context is resolved in a separate system layer.

  2. 02 Parse

    The structural parser turns Markdown into ordered semantic blocks and authored field pairs while preserving source context such as names, keys, and line locations. parseStoryboard applies the stricter Storyboard contract used by Stories and as a structural basis for other fields; parseMarkdownDocument provides the more permissive document lane required by Journals.

  3. 03 Normalize

    Normalization is where authored source becomes the model its renderer can trust. Story sections resolve into Story motifs, Journal callouts are promoted into editorial blocks, Viewgraph source becomes a fixed-frame presentation, and Grove sections resolve against the Grove motif registry. Outside the publishing-field pipeline, Trailhead v2 becomes a TrailheadModel of Encounters, transitions, routes, and relationships, while Trailmap YAML becomes a normalized graph of Horizons, Regions, Nodes, Edges, Trails, provenance, and projection metadata. This is the point at which editorial purpose becomes explicit in the data model.

  4. 04 Validate

    Validation rejects shapes that a renderer cannot safely or meaningfully honor: unknown vocabulary, missing required fields, impossible cardinality, broken movement spines, incompatible Viewgraph children, invalid chart specs, malformed analytical primitives, invalid Trailhead transitions or routes, and broken Trailmap topology. Trailmap validation includes ids, references, regions, edge endpoints, Trails, Horizons, provenance basis, projection regions, and reachability. Structural failures stop the build; density, rhythm, and editorial fit can remain warnings when the source is still semantically valid.

  5. 05 Render

    Renderers receive validated models rather than raw Markdown guesses. Reuse the universal block path when the structure is ordinary; add a dedicated component only when a motif owns real layout or interaction semantics that a generic renderer cannot express.

  6. 06 Apply Surface

    The final field adapter contributes editorial width, spacing, local navigation, and shared Palette behavior. Stories and Groves can additionally resolve the same governed soil / forest-floor vocabulary at their bounded page or shell root, while Viewgraphs retain their separate frame-surface model. Surface concerns should remain outside semantic models so the same capability can render correctly in more than one host without duplicating its behavior.

What The Registry Actually Is

One vocabulary, explicit ownership

The Story and Grove systems each keep their public motif vocabulary in a registry module, while Viewgraphs and Journals have equivalent vocabulary contracts in their own models. A registry is not merely a menu for a renderer; it is the implementation boundary that says which authored structures the platform is willing to recognize and support.

Unknown vocabulary fails loudly

A misspelled or unsupported render value should produce a source-oriented error rather than fall back silently to something that happens to look acceptable. That failure mode protects both authors and maintainers: a typo cannot become a new accidental contract simply because a generic component was able to draw it.

Human reference follows the registry

Generated vocabulary documentation should be derived from the implementation registry wherever the platform supports that path. Hand-maintained prose still explains intent, tradeoffs, and examples, but machine-readable capability names should not have two independent sources of truth.

How The Pieces Relate

  • parser

    Produces ordered structural blocks and source context. It should remain unaware of route-specific prose titles and of visual decisions that belong to motifs.

    Relates to registry, validators

  • registry

    Declares recognized authoring responsibilities and gives normalization a stable set of names to resolve against.

    Relates to parser, renderers, capability-model

  • validators

    Enforce structural contracts before rendering. Their error messages should point back to authored source and explain the violated rule rather than expose component implementation detail.

    Relates to parser, registry

  • capability-model

    Aggregates implementation registries into a derived view so the Guide can ask what the platform actually supports without maintaining a second hand-written inventory.

    Relates to registry, system-health

  • system-health

    Turns the capability model and selected integrity checks into a build-time architectural portrait. It is documentation evidence, not production telemetry.

    Relates to capability-model, validators

Math Expressions Share The Same Parser Boundary

Math Expressions (docs/musewoods-v7.0-mathexp-implementation-guide.md) are the newest proof that "one vocabulary, explicit ownership" holds under a real addition rather than only in retrospect. Authors write AsciiMath — inline as {{math: V_r = V_e + V_ec + V_s}}, or as a standalone :::math ... ::: block — and Musewoods converts it to sanitized MathML before it ever reaches a component.

{{math: ...}} / :::math...:::   (registered in the shared parser, lib/storyboard-parser.mjs)
        -> Math node on the ordinary ContentBlock / InlineToken tree
        -> AsciiMath -> MathML adapter    (lib/math/ascii-math-to-mathml.mjs)
        -> MathML allowlist sanitizer     (lib/math/sanitize-mathml.mjs)
        -> MathInline / MathBlock         (present only; parse nothing)

Math needed no field-specific adapter. Because Story, Journal, Grove, Viewgraph, and Trailhead prose already parse content through that shared parser and render blocks through the one shared ContentBlocks.tsx / InlineContent.tsx path, registering Math once made it available everywhere those fields already render prose — the same leverage a registry-backed vocabulary is supposed to produce. Conversion and sanitization both happen before a page reaches the browser, so the semantic <math> markup is already present in server-rendered HTML; nothing about Math depends on client-side JavaScript the way Mermaid's diagram rendering does. A malformed expression degrades to its own safe source text — the failure stays local to the expression, never to the containing page or the build. Trailmap source is YAML and remains outside this Markdown/AsciiMath parser boundary.

One Path, Named

A Story request illustrates the shape clearly. The exact helper names are less important than the ownership boundaries they represent: content is loaded, parsed, resolved against the Story vocabulary, validated, and then handed to the page and section renderers.

content/stories/<slug>.md
  -> loadStoryboardFromPath        (content loading)
  -> parseStoryboard              (structural parse)
  -> resolveMotifs                (Story normalization)
  -> assertValidStoryboard        (Story validation)
  -> renderStoryboardPage         (page composition)
  -> SectionView / NodeView       (registered rendering)

Groves, Journals, and Viewgraphs follow the same responsibility sequence with their own normalization and validation steps. The architectural rule is more important than the function spelling: field differences should be explicit at the model boundary rather than hidden in conditionals inside a universal page template.

Canonical Publication Feeds Cross-Field Systems

clearing-boundary

Clearing is designed to consume stable canonical identity plus explicit semantic declarations and deterministic structural relationships. It should not enter the field normalizer or duplicate canonical prose. A future context resolver assembles subject-centered Context Packages whose provenance remains traceable to authored or platform-known sources. Until that resolver exists, Clearing System is a normative design contract rather than a statement of shipped runtime paths.

navigation-boundary-summary

Trailheads may reference canonical Stories, Journals, Viewgraphs, and Groves while adding journey-specific interpretation. Trailmaps may reference the same objects while also containing derived Waymarkers and semantic edges whose provenance remains explicit. Neither Navigation instrument changes ownership of the canonical source object.

resonance-boundary-summary

Resonance starts from canonical content and explicit relationship choices. It owns v1 Path circulation, Follow, bounded journey signals, stores, attribution, and explicit send boundaries. It may circulate a Trailhead experience, but the current v2 semantic journey and v9 Trailmap grammars are Navigation System contracts rather than provider or relationship-plane semantics.

Figure 2

Rendering diagram…

Publication Ends Before Navigation And Resonance Begin

canonical-boundary

The four field pipelines own discovery, parsing, normalization, validation, and rendering for canonical work. Resonance is not another branch in the field normalizer. It starts from a typed reference to an already-owned Story, Journal, Viewgraph, or Grove and resolves the canonical title, route, field, preview, and visibility metadata needed by a Path.

navigation-boundary

Trailhead v2 and Trailmap v9 consume canonical references without entering the field normalizers that own Stories, Journals, Viewgraphs, and Groves. A broken Trailmap edge should invalidate the map that declares it, not the Story it references. A malformed Trailhead route should invalidate that journey, not the canonical Grove it points toward.

resonance-boundary

The v1 Trailhead edition and Path remain available to the established Resonance web/email circulation pipeline. Follow, signal, store, attribution, and send boundaries sit beside Navigation and publishing rather than inside either one. A runtime failure in those planes must not invalidate canonical content, a v2 Trailhead, or a static Trailmap field.

Figure 3

Rendering diagram…

Validation Guide

Structural contracts worth knowing

Visible Contents entries and numbered movements must resolve one-to-one and in order.

Story Ground is one optional page-level metadata value, validated before rendering and applied at the bounded Story root.

Only registered Journal markers are promoted, and marker-specific structural rules are enforced before rendering.

Each fixed-frame layout declares the child shapes and cardinality it can safely contain.

Identity, navigation, visibility, and Ground are explicit local-site contracts rather than inferred conveniences.

A chart must declare a supported analytical family, valid data semantics, and an accessible first frame.

Shared analytical primitives validate the authored semantics they need before a host field renders them.

v2 is the current semantic journey grammar; v1 remains a separate Resonance compatibility generation.

The authored field must be semantically complete before projection creates woodland geometry or Explorer interaction.

Only the registered `{{math: ...}}` / `:::math` syntax invokes Math; generated MathML must pass an explicit sanitization allowlist before it reaches the DOM.

Journey measurement is a closed, identity-separated grammar rather than an open analytics endpoint.