Musewoods Canopy Technical Notes

1.1 Why this specification exists

The implementation was deliberately designed around a configuration-first philosophy. The desired operating model is that the meaning, topology, editorial composition, and entry paths of the Canopy can evolve primarily through configuration and content metadata, while the React component remains a stable rendering and interaction engine. This specification evaluates how far the current implementation already achieves that goal and identifies the minimum architectural changes required to make that philosophy durable as Musewoods grows.

1.2 Design principle

The core principle is:

Configuration should describe the ecology; code should render and operate it.

That principle does not mean that every visual constant or interaction detail belongs in YAML. A configuration-first system remains healthy only when configuration expresses facts and policies that are expected to change independently of the renderer, while stable algorithms, accessibility behavior, presentation-system integration, and rendering mechanics remain code.

The ideal boundary is therefore not "no code changes ever." It is "ordinary evolution of the Musewoods ecology should not require editing the renderer."

1.3 Scope

This specification covers the semantic manifest, the normalized CanopyModel consumed by the React component, the deterministic wide and compact layouts, relationship rendering, search, selection, URL state, contextual detail, graceful fallback, accessibility behavior, and the boundary between configuration and code.

The build-time model builder and the Canopy CSS implementation were not included in the supplied source set. Where this document describes artifact resolution, visibility filtering, neighbor derivation, or presentation-token mapping, it does so from the explicit manifest contract and the normalized model interface expected by CanopyLounge.tsx. Those behaviors should be verified against the repository implementation when this specification is checked in.

2.1 Current state

The current Canopy is already substantially configuration-driven where it matters most. The manifest defines which formations exist, their semantic summaries, their prominence, their color family, their authored positions, their entry artifact, their supporting artifacts, and their relationships. The React component receives a normalized model and does not contain the 17 formation definitions or 19 relationship declarations that produce the current field.

That is a strong foundation. Adding another formation that fits the existing semantic vocabulary can generally be accomplished by creating or identifying its underlying public artifact and adding a manifest record with positions and relationships. No change to CanopyLounge.tsx is required merely because the field contains another formation.

The current implementation becomes less configuration-driven when the system needs to change how formations behave. Compact visibility is hard-coded to tier 1, the default "Paths into the woods" suggestions are inferred from weight, the central Musewoods pulse is keyed directly to the literal formation id musewoods, search fields are fixed in code, the number of supporting artifacts displayed is fixed at three, the responsive breakpoint and node-size formulas are fixed in code, and the panel composition is fixed in code. These are manageable at 17 formations, but they create unnecessary code coupling if the Canopy becomes a long-lived system surface.

2.2 Current inventory

The supplied manifest contains 17 formations. Ten are tier 1 and seven are tier 2; the ten tier-1 formations have authored compact positions and are therefore the formations currently shown on narrow screens. The semantic field contains 19 authored relationships using six of the seven relationship types documented by the manifest: connects-to, informs, applies-to, emerges-from, questions, and extends.

The current tone vocabulary contains five families: parchment, sage, ochre, mineral, and moss. Entry artifacts currently resolve to 11 Stories, three Journals, and three Groves, while the supporting artifact set also includes a Viewgraph. The renderer itself uses generic artifact fields, so the visible panel is not structurally coupled to those three entry types.

2.3 Configuration-first assessment

The central conclusion is that the semantic graph is already config-first; the interaction policy is only partially config-first. The ideal future state should preserve the current renderer while extracting a small number of change-prone policies that are currently encoded as incidental constants or hidden semantic couplings.

3.1 Architectural flow

The Canopy can be understood as a five-stage pipeline.

The manifest is the authored semantic source. It does not embed artifact URLs or duplicate the publishing system's visibility state; artifact references are expressed as {type, id} and are expected to be resolved through existing Musewoods loaders. The normalized CanopyModel then becomes the boundary between build-time corpus logic and client-side interaction.

This separation is architecturally important. It allows the Canopy to remain a curated semantic layer over the corpus without becoming a second content database.

3.2 Manifest responsibility

The manifest explicitly defines a formation as a meaningful body of thought rather than a publishing unit. It owns facts that no individual Story, Journal, Grove, Viewgraph, or Trailhead can author on its own: whether a formation belongs in the Canopy, where it sits, how prominent it is, how it relates to other formations, and which artifact is the intentional entry point.

The manifest therefore behaves as an editorial semantic composition, not a generated sitemap. That distinction should remain true even if future tooling helps discover candidate relationships or suggests placements.

3.3 Content resolution

Artifacts are referenced by type and id. The manifest contract states that titles, URLs, and visibility are resolved through the existing content loaders, that non-public supporting artifacts are dropped, and that a formation whose entry artifact is not public is dropped as a whole.

The component confirms the normalized result of that process. CanopyArtifact contains type, kind, title, and href, while each formation contains a fully resolved entry, an array of resolved artifacts, a forms summary, and a derived neighbor list. Those values are not all authored in the manifest, which demonstrates that an upstream normalization stage is already enriching the manifest from the corpus.

3.4 Normalized model boundary

The React component receives only:

type CanopyModel = {
  formations: CanopyFormation[];
  edges: CanopyEdge[];
};

A normalized formation contains four kinds of information:

1. Authored semantic identity — id, title, summary, origin.
2. Authored field composition — weight, tier, tone, wide and compact coordinates.
3. Resolved corpus references — entry, artifacts, forms, and the derived description.
4. Derived graph context — neighbors.

This is a good boundary because the rendering component does not need to know how Stories, Journals, Groves, Viewgraphs, or Trailheads are loaded. It needs only a normalized artifact contract.

4.1 Top-level contract

The manifest currently has a schema version and a list of formations:

version: "1"

formations:
  - ...

The schema version correctly belongs to the Canopy manifest rather than the Musewoods release version. The two values should remain independent: Musewoods may move from v8.0 to v8.1 without requiring a Canopy manifest schema migration.

4.2 Formation fields

The optional context reference is especially useful. Musewoods demonstrates why it exists: the primary entry is the canonical Musewoods Story, while the Canopy context may be derived from why-musewoods. That cleanly separates what explains a formation in the field from where the visitor enters it and should be retained in any future schema.

4.3 Relationships

A relationship is authored once on the source formation:

relationships:
  - target: architecture
    type: informs

The manifest defines the current vocabulary as emerges-from, evolves-into, informs, extends, applies-to, questions, and connects-to. The normalized model then presents relationships bidirectionally through CanopyNeighbor, including direction and a human-readable phrase.

This is another strong separation. CanopyLounge.tsx does not interpret the meaning of informs or questions; it receives a phrase and renders it. Relationship semantics therefore belong upstream of the visual component.

4.4 Spatial semantics

Positions are manually authored fractions rather than the result of a force-directed graph. This is an intentional editorial design choice. It gives Musewoods stable composition, allows semantic neighborhoods to be shaped deliberately, and ensures that a reader sees the same field rather than a different simulation on each visit.

The current manifest uses proximity to imply four broad neighborhoods without encoding those neighborhoods as explicit taxonomy. Formation and lineage gather upper-left, practice and inquiry lower-left, systems and authority upper-right, and regeneration lower-right. That allows the field to remain suggestive rather than imposing another classification hierarchy.

5.1 Layout selection

The renderer uses a media query at 860px to select one of two deterministic planes:

const WIDE = {
  w: 1000,
  h: 765,
  radius: (weight) => 13 + weight * 24,
  font: 17,
  wrap: 21,
  blur: 22
};

const COMPACT = {
  w: 420,
  h: 820,
  radius: (weight) => 9 + weight * 14,
  font: 15,
  wrap: 20,
  blur: 10
};

Wide coordinates use position.x/y. Compact coordinates use compact.x/y. Coordinates remain proportional to the plane, so changes in viewBox dimensions preserve the authored relative composition.

5.2 Compact formation filtering

Compact mode currently renders only formations where:

f.tier === 1

This means tier has two responsibilities: it expresses formation importance and determines mobile-field membership. Ten formations satisfy that rule in the current manifest, which matches the ten formations carrying compact coordinates.

This works today but is a hidden coupling. A future editor cannot make a tier-2 formation visible on mobile without either changing its semantic tier or changing React code.

5.3 Node geometry

Node size is calculated from weight, which makes prominence configurable while keeping the radius curve stable in code. The renderer then builds each node from a halo, core, sheen, optional selection ring, and an idle pulse for the formation whose id is literally musewoods.

Labels are wrapped by character count rather than measured text width. Wide labels wrap around 21 characters and compact labels around 20, with a deterministic vertical offset from the node. This is simple, predictable, and inexpensive, although it relies on manual validation to catch unusual long words or future typography changes.

5.4 Relationship geometry

Every eligible edge remains structurally present when relationship paths are enabled. A quadratic curve is calculated between the two formation coordinates, with a small deterministic bend based on edge index.

When a formation is targeted by hover, focus, or selection, direct incident edges become strong and unrelated edges recede. Relationship labels are deliberately not rendered along the paths; semantic wording is reserved for the contextual panel and accessible node name.

That separation is important because it keeps the field readable. The graph communicates connection visually, while prose communicates meaning.

5.5 Selection state

The renderer distinguishes four main node states:

• idle
• target
• neighbor
• dim

Search adds a fifth effective state, match, while non-matches dim. Hover has precedence over selected state for temporary neighborhood inspection, allowing a visitor to examine another formation without immediately replacing the selected context.

5.6 Search

Search is currently client-side over the normalized formation model. The fixed search corpus is:

title + summary + description + origin

The result set is shown in the left control rail, with a maximum of eight visible result buttons. Pressing Enter selects the first match.

This is efficient for a curated field of 17 formations and will remain efficient for a much larger formation set. The constraint is not computational scale but editorial scale: the spatial field itself should not become a representation of every corpus artifact.

5.7 Orientation choices

When no formation is selected, the right panel displays three suggested starting formations. Those are currently computed as the three formations with the highest weight.

This produces a pleasing result today, but it couples two separate editorial decisions: how large should a node be? and should this formation be a recommended entrance? A future schema should separate those concerns.

5.8 Detail panel

A selected formation renders:

1. artifact kind;
2. formation title;
3. summary;
4. optional description;
5. optional origin;
6. connected formations;
7. an "Explore through" section;
8. up to three supporting artifacts;
9. the primary entry CTA.

The panel is therefore data-driven but structurally fixed. The component does not need a formation-specific branch, which is a major extensibility advantage.

5.9 Browse route and error boundary

The same public formations are also rendered as a list beneath the field. This gives the experience an alternate browse path and ensures that the semantic inventory is not available only through SVG interaction.

FieldBoundary provides a stronger guarantee: if the field itself throws during rendering, the system shows the formation index opened rather than surfacing a raw error. This is an excellent example of a stable code responsibility that should remain code rather than configuration.

6.1 URL state

Selection is reflected in the query parameter:

?f=<formation-id>

The component validates the id against the current model before restoring a shared selection. Reset removes the parameter and returns to the whole field.

The current implementation uses history.replaceState, not pushState. As a result, a selected formation is shareable and refresh-safe, but successive formation selections do not become browser-history steps. This is a deliberate-enough behavior to document because changing it later would be interaction-policy evolution, not a content change.

6.2 Keyboard behavior

The / key focuses formation search unless the visitor is already typing in an input or textarea. Escape resets selection, hover, and search. Each SVG formation is keyboard focusable, exposes role="button" and aria-pressed, and can be activated with Enter or Space.

The accessible node label includes the title, summary, and relationship phrases. This means the semantic graph remains available to assistive technology even though relationship text is intentionally absent from the visible edge paths.

6.3 Motion

The field supports a motion toggle and honors prefers-reduced-motion. When the operating system requests reduced motion, the control is disabled and communicates that system preference.

This behavior belongs in the renderer because it is accessibility policy, not an editorial choice.

7.1 Add a formation

A new formation can be admitted by adding a manifest record and ensuring its primary entry artifact exists and is publicly resolvable. If it uses an existing tone, relationship vocabulary, and current panel grammar, no React change is required.

For a wide-only tier-2 formation, the record needs a wide position. For a formation intended to appear in the current compact field, it needs a tier of 1 and compact coordinates.

7.2 Add or change relationships

Existing relationship types can be added, removed, or redirected entirely in the manifest. The field geometry, selected-neighborhood behavior, accessible relationship text, and detail-panel connections are all derived from the resulting graph.

This is one of the strongest parts of the current architecture because a semantic change does not require editing visualization code.

7.3 Change prominence or composition

weight, position, and compact coordinates allow editorial adjustment of the visual field without changing the renderer. This makes the Canopy closer to an authored viewgraph than an algorithmic network visualization.

The tradeoff is intentional: each new formation requires thoughtful placement rather than automatic layout.

7.4 Change entry and supporting paths

The primary entry artifact, context source, and supporting artifacts can all be changed in configuration. Because artifact URLs and visibility are resolved through the content system rather than copied into the manifest, route changes can remain centralized in the publishing layers.

7.5 Change formation language

Title, summary, and origin can be revised without touching React. This is important because the Canopy language will likely evolve more often than its interaction mechanics.

8.1 Responsive policy

The breakpoint, wide/compact plane dimensions, compact filtering rule, label geometry, node-size formula, and compact scroll offset are all hard-coded. Adding a third layout mode, changing which formations appear on compact screens without changing tier, or tuning layout policy requires a component change.

8.2 Featured entrances

The initial three suggestions are coupled to node weight. There is no configuration field for editorially curated starting paths or their order.

8.3 Anchor formation

The Musewoods idle pulse is selected by the literal id musewoods. If a future Canopy view had a different anchor, the component would need to change.

8.4 Search policy

The fields searched, maximum result count, Enter behavior, and placeholder microcopy are fixed in the component. These are not serious constraints today, but they are change-prone surface policies rather than rendering algorithms.

8.5 Panel policy

The renderer always shows the same section order and caps secondary artifacts at three. There is no manifest-level ability to suppress origin for a particular formation, feature five supporting artifacts, change the entry label, or intentionally hide the forms summary.

A generic panel grammar is desirable, but the system should avoid turning the manifest into a page-builder. Only simple policy switches with clear editorial value should become configuration.

8.6 Relationship vocabulary

The component is decoupled from relationship semantics, but the supplied files do not show where relationship types are validated or translated into CanopyNeighbor.phrase. If this mapping is hard-coded in the model builder, adding a new relationship type still requires code outside the renderer.

The ideal architecture should place this vocabulary in one validated semantic registry.

8.7 Visual tone vocabulary

The manifest configures tone names, and the component emits those names as data-tone. The actual color mapping is therefore outside the supplied component and presumably belongs to the Musewoods Presentation System.

That is the right design. A new tone should require registration in the Presentation System, not a raw color value in the manifest.

9.1 `weight` means both size and recommendation

weight determines node radius and indirectly determines whether a formation appears under "Paths into the woods." Those decisions may coincide today, but they represent different editorial intentions.

The future model should preserve weight for visual prominence and introduce an explicit orientation priority or curated starting list.

9.2 `tier` means both semantic importance and compact visibility

Tier currently controls whether a formation appears in the compact field. This creates pressure to change semantic importance merely to alter mobile composition.

A future schema should make layout participation explicit. The presence of a compact layout record can itself mean "show this formation in compact mode," eliminating the need for tier === 1 as a renderer rule.

9.3 `musewoods` is both data and renderer knowledge

The component otherwise treats formation ids generically, but the idle pulse contains one formation-specific branch:

f.id === "musewoods"

That should become a configured formation role such as anchor: true, or a top-level anchor_formation: musewoods.

9.4 Artifact prominence is fixed

All formations receive the same panel grammar and a maximum of three supporting artifacts. This makes the renderer predictable but prevents configuration from expressing that some formations have one definitive path while others should expose several.

The future state should allow a small artifact-display policy without making per-formation UI templates configurable.

10.1 What scales well

Artifact resolution, relationship derivation, text search, fallback browsing, and generic detail rendering can scale substantially beyond the current 17 formations. The component operates on arrays and maps with trivial computational cost at the scale Musewoods is likely to maintain for a curated semantic field.

The fallback list is especially tolerant of growth because it is conventional document flow rather than spatial composition.

10.2 What does not scale automatically

The authored field is intentionally not a force graph. Every additional formation increases the editorial burden of placement, label separation, edge density, and compact composition.

This is not a defect. The Canopy should remain a curated layer of formations, not become a visual index of hundreds of documents. Corpus growth should normally increase the artifacts reachable through formations rather than cause every new artifact to become a new formation.

10.3 Admission principle

A new Story, Journal, Viewgraph, Grove, or Trailhead should not automatically become a Canopy formation. Formation admission should remain an explicit editorial act because the Canopy is an interpretation of the ecology, not a generated table of contents.

Automation may eventually propose candidate formations or relationships, but publication into the Canopy should remain governed and intentional.

11.1 Target design

The ideal future state keeps the current architecture but sharpens its boundaries:

musewoods.yaml remains responsible for global system identity and release configuration. It should not absorb Canopy-specific layout or behavior merely because it is global configuration.

The Canopy manifest remains the correct home for semantic field composition. A small top-level Canopy policy block can absorb the few change-prone behaviors that currently force component edits.

11.2 What should remain code

The following should remain renderer responsibilities:

• SVG composition mechanics;
• accessible keyboard activation;
• prefers-reduced-motion handling;
• error boundary and fallback behavior;
• relationship highlighting algorithm;
• URL read/write implementation;
• search algorithm implementation;
• node/edge rendering primitives;
• focus management;
• safe responsive rendering;
• Presentation System token application.

Moving these into YAML would make configuration brittle and turn the manifest into a frontend programming language.

11.3 What should become configuration

The following are reasonable configuration candidates because they are editorial or policy choices likely to evolve independently:

• anchor formation;
• compact breakpoint;
• layout profiles and visible formation participation;
• default relationship-path state;
• default motion state if product policy changes;
• search fields and result cap;
• curated "Paths into the woods";
• supporting-artifact display limit;
• URL query key if the routing contract ever changes;
• visitor-facing Canopy microcopy;
• relationship vocabulary if not already centrally registered.

Only values with plausible independent lifecycle should be externalized. Stable SVG geometry such as the number and radii of decorative field rings does not need to become configuration simply because it can.

12.1 Goals

Manifest v2 should remove hidden semantic couplings while preserving the successful authored-field model. The migration should be additive and behavior-preserving: v1 data should be mechanically convertible without changing what the visitor sees.

A suitable direction is:

version: "2"

canopy:
  anchor_formation: musewoods

  layouts:
    wide:
      width: 1000
      height: 765
    compact:
      max_width: 860
      width: 420
      height: 820

  orientation:
    formations:
      - musewoods
      - kriyas
      - regenerative-prosperity

  search:
    fields:
      - title
      - summary
      - description
      - origin
    result_limit: 8

  detail:
    artifact_limit: 3

  state:
    query_parameter: f
    relationship_paths_default: true
    motion_default: true

  copy:
    eyebrow: Musewoods / Arrival
    title: Enter the musewoods.
    lede: Musewoods reveals itself through relationships. Choose a formation and follow what becomes connected.
    search_placeholder: Find a formation…
    orientation_title: Begin where the canopy opens.
    orientation_label: Paths into the woods
    browse_label: Browse the whole field

formations:
  - id: musewoods
    title: Musewoods
    summary: A place for ideas before they know what they will become.
    origin: Grew from a need for somewhere unfinished questions could stay together long enough to reveal what they are.
    weight: 1
    tone: parchment

    layouts:
      wide:
        x: 0.5
        y: 0.5
      compact:
        x: 0.58
        y: 0.15

    entry:
      type: story
      id: home

    context:
      type: story
      id: why-musewoods

    relationships:
      - target: 451
        type: informs

The exact field names should follow repository conventions, but the architectural change is more important than the spelling. Compact participation is now explicit through the presence of layouts.compact, the anchor is explicit, and orientation choices no longer depend on visual weight.

12.2 Relationship registry

If relationship phrases are currently coded in the model builder, they should move to one semantic registry. That registry may be a small YAML block or an existing Musewoods semantic registry if one already exists.

A relationship definition should be able to express at least:

relationship_types:
  informs:
    outgoing: informs
    incoming: is informed by

  applies-to:
    outgoing: applies to
    incoming: receives from

  questions:
    outgoing: questions
    incoming: is questioned by

The exact prose should remain editorially controlled. The important property is that the component continues to receive already-resolved neighbor phrases and never becomes responsible for semantic interpretation.

13.1 Validation

The model builder should validate the complete manifest before rendering. Validation should reject duplicate ids, missing relationship targets, unsupported tones, invalid normalized coordinates, unresolved entry artifacts, invalid layout definitions, unknown relationship types, and multiple anchor formations.

Supporting artifacts that are not publicly visible may continue to be dropped according to the existing manifest contract. Entry-artifact failure should continue to remove or fail the formation according to current repository policy.

13.2 Enrichment

The builder should continue to resolve artifact metadata through the existing corpus loaders. It should produce normalized CanopyArtifact values with canonical hrefs and display kinds, derive description from the configured context/entry source, summarize available forms, and derive incoming and outgoing neighbors from the relationship graph.

This keeps the React component independent of every publishing-form loader.

13.3 Diagnostics

The ideal system should add build-time diagnostics for authored spatial quality without introducing automatic force layout. Useful checks include duplicate coordinates, node centers closer than a configured warning threshold, missing compact coordinates for compact-visible formations, and likely label collisions.

Diagnostics should warn or fail according to severity, but they should not silently move formations. Musewoods' deterministic editorial composition should remain intact.

15.1 Stage 1 — Formalize the current contract

Before changing behavior, document or add a schema validator for manifest v1 and verify the actual model builder against this specification. Confirm how description, forms, neighbor phrases, visibility filtering, and tone validation are currently derived.

This stage should not change the rendered Canopy.

15.2 Stage 2 — Remove the three strongest hidden couplings

The first migration should externalize only:

1. anchor formation;
2. orientation/start formations;
3. compact participation.

Those three changes eliminate the most obvious formation-specific and semantic-policy knowledge in CanopyLounge.tsx while keeping the schema small.

A v2 migration can convert current data mechanically: musewoods becomes the anchor, the current top-three weight results become the explicit orientation list, and every current tier-1 formation with compact coordinates becomes compact-visible.

15.3 Stage 3 — Externalize change-prone interaction policy

Move search fields/result limit, supporting-artifact limit, breakpoint/layout dimensions, and visitor-facing microcopy into the Canopy policy block only if the team expects those values to evolve independently.

Do not externalize every renderer constant for theoretical purity.

15.4 Stage 4 — Add editorial diagnostics

Add collision and completeness checks to the build process so that adding formations remains safe as the field grows. Diagnostics should protect deterministic composition rather than replace it.

At this point, ordinary Canopy evolution should be almost entirely a manifest/content operation.

16.1 `musewoods.yaml`

musewoods.yaml should remain the source of truth for system identity, release version, canonical site identity, and global brand assets. It should not become a generic bucket for Canopy-specific configuration.

16.2 Canopy manifest

The Canopy manifest should remain the source of truth for the curated semantic field and its Canopy-specific policies. This preserves a clean lifecycle: Musewoods can release without changing the Canopy schema, and the Canopy can add a formation without changing global system configuration.

16.3 Presentation System

Colors, typography, focus treatment, surfaces, rules, and dark-context behavior remain governed by the Musewoods Presentation System. The manifest should refer to semantic tone names rather than raw colors.

16.4 Corpus

Stories, Journals, Groves, Viewgraphs, and Trailheads remain authoritative for their own titles, routes, visibility, and content. The Canopy references them; it does not duplicate their route registry or access policy.