Framework Primitives

When To Use It

VMx is one language-neutral framework surface expressed through four idiomatic flavors. These pages are the practical map of that surface: which primitive to reach for, what it owns, how it participates in lifecycle and messaging, and where the flagship Notes Workspace examples use it.

Use this overview when you are choosing a starting area rather than looking up a single API. It is the top-level index for the primitive families introduced in Task 6.

Shape And Ownership

The primitives catalog is organized by responsibility:

• Start with ViewModel Families when you are choosing the shape of a new VM.
• Use Command Families and Capability Families when you need behavior without changing the core hierarchy.
• Use State & Reactive Helpers and Services, Messages & Dispatching when the question is about coordination, reactivity, or host wiring.
• Use Builders, Collections & Tree Utilities when the question is construction ergonomics, observable collections, or traversal helpers.

At this level, the ownership question is "which family owns this concern?" VM families own hierarchy and child relationships; command and capability families own behavior surfaces; the remaining sections cover coordination and utility layers.

Lifecycle And Messaging

Lifecycle and messaging rules are described on the family pages, but they follow one common pattern here: choose the primitive family first, then confirm how it constructs, destructs, publishes property changes, and participates in hub or dispatcher wiring.

The overview pages deliberately stay at that routing level so they do not invent surface APIs that belong on the concrete primitive pages.

Cross-Language Surface

The conceptual shape is identical across C#, Python, TypeScript, and Swift. The surface idiom changes:

Concept	C#	Python	TypeScript	Swift
Casing	PascalCase	snake_case	camelCase	camelCase
Modeled leaf	ComponentVM<M>	ComponentVMOf[M]	ComponentVMOf<M>	ComponentVMOf<M>
Null hub singleton	NullMessageHub.Instance	NULL_MESSAGE_HUB	NullMessageHub.INSTANCE	NullMessageHub.INSTANCE

The goal of these pages is not to restate the spec chapter by chapter. The goal is to help you pick the right primitive quickly and then follow through with the correct lifecycle, services, and related helpers.

Example

A typical reading path is:

1. start at ViewModel Families to choose the VM shape
2. jump to Command Families if the next question is how to expose executable behavior
3. finish with a utility page such as Services, Messages & Dispatching when the remaining work is host coordination

Common Pitfalls

• Treating the overview as an API reference instead of a routing page.
• Starting with commands or helpers before choosing the owning VM shape.
• Assuming a surface-name difference across languages implies a conceptual difference.

Related Primitives

If the VM is:

• a leaf that owns a single model or view concern, start with Component Family
• a selectable ordered list, start with Composite Family
• a non-selectable peer list, start with Group Family
• a fixed tuple of heterogeneous children, start with Aggregate Family
• a recursive tree, start with Hierarchical Family
• a specialized workflow such as edit/revert, active-mode switching, toast rendering, or modal completion, start with Specialized ViewModels & Coordinators

From there, continue into:

• Command Families
• Capability Families
• State & Reactive Helpers