Preserve initial frontend pattern language research scaffold

Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a0cffe-206f-7323-89d3-b20ca4cf4bf9
2026-09-24 07:55:34 +02:00 · 2026-09-24 07:55:34 +02:00 · 2a5dabdc85
commit 2a5dabdc85
parent 017ad6ea17
43 changed files with 2030 additions and 1 deletions
--- a/README.md
+++ b/README.md
@ -1,3 +1,85 @@
 # frontend-patterns
-A Christopher Alexander style pattern language for frontend architecture and design.
+A coherent, generative pattern language for frontend architecture and design.
 The project treats frontend architecture not as a choice among frameworks or named styles, but as the progressive resolution of recurring forces concerning:
 - authority,
 - addressability,
 - projection,
 - interaction,
 - mutation,
 - synchronization and reconciliation,
 - composition,
 - execution and delivery,
 - quality boundaries.
 The repository is intended as an **infospace for both human and agentic reference**.
 Its goal is to make frontend architecture:
 1. understandable as a set of recurring design problems,
 2. navigable as a connected language of patterns,
 3. generative rather than merely taxonomic,
 4. explicit about trade-offs and failure modes,
 5. independent of framework fashion,
 6. grounded in known implementations and sources,
 7. machine-readable enough for agents to reason over.
 ## Core proposition
 > Frontend architecture is the progressive resolution of forces concerning
 > authority, addressability, projection, interaction, synchronization,
 > composition, and execution. A frontend pattern language captures recurring
 > resolutions of those forces and the contexts they create for subsequent
 > design decisions.
 ## Repository map
 - `canon/` — normative vocabulary and structure of the language.
 - `patterns/` — individual frontend architecture and design patterns.
 - `sequences/` — generative sequences for common frontend situations.
 - `architectures/` — named architectural configurations expressed through patterns.
 - `technologies/` — mappings from technologies/frameworks to the patterns they implement.
 - `research/` — research material, source reconciliation, concepts, catalogues, and cases.
 - `templates/` — authoring templates for new patterns and mappings.
 ## Design principles
 ### Patterns before products
 React, Solid, HTMX, Astro, LiveView, Vue, Svelte and similar technologies are treated as implementations and examples, not as the ontology.
 ### Forces before preferences
 A pattern should be selected because of the forces present in a context, not because a framework community considers it idiomatic.
 ### Relations before lists
 Patterns form a graph. Important relations include:
 - requires
 - enables
 - refines
 - generalizes
 - complements
 - alternative-to
 - conflicts-with
 - commonly-combined-with
 - creates-context-for
 - implemented-by
 - observed-in
 ### Sequences before checklists
 A pattern language should help generate architecture through an ordered sequence of decisions.
 ### Failure modes are part of the pattern
 Software patterns must describe when they become harmful, misleading, expensive or fragile.
 ## Status
 This repository begins as a research-backed v0.1 scaffold. The first research case is Ryan Carniato's
 "The Grand Unifying Architecture of Frontend", used as a starting point for decomposing modern frontend
 architectures into deeper responsibilities and forces.
--- a/TREE.md
+++ b/TREE.md
@ -0,0 +1,69 @@
 # Repository Tree
 ```text
 frontend-patterns/
 ├── architectures/
 │   ├── DocumentWeb.md
 │   ├── Islands.md
 │   ├── LocalFirst.md
 │   ├── Microfrontends.md
 │   ├── README.md
 │   ├── ServerComponents.md
 │   └── SPA.md
 ├── canon/
 │   ├── Forces.md
 │   ├── FrontendPatternLanguage.md
 │   ├── PatternSchema.md
 │   ├── Relations.md
 │   ├── Responsibilities.md
 │   └── Scales.md
 ├── patterns/
 │   ├── address/
 │   │   └── README.md
 │   ├── affordance/
 │   │   └── README.md
 │   ├── authority/
 │   │   └── README.md
 │   ├── composition/
 │   │   └── README.md
 │   ├── execution/
 │   │   └── README.md
 │   ├── mutation/
 │   │   └── README.md
 │   ├── projection/
 │   │   └── README.md
 │   ├── quality/
 │   │   └── README.md
 │   ├── synchronization/
 │   │   └── README.md
 │   └── README.md
 ├── research/
 │   ├── cases/
 │   │   └── CarniatoGrandUnifyingArchitecture.md
 │   ├── catalog/
 │   │   ├── PatternCandidateCatalog.md
 │   │   └── SourceCatalog.md
 │   ├── compendium/
 │   │   └── FrontendArchitectureCompendium.md
 │   ├── concepts/
 │   │   ├── GenerativeSequence.md
 │   │   └── ResponsibilityModel.md
 │   ├── plan/
 │   │   ├── OpenQuestions.md
 │   │   └── ResearchProgram.md
 │   └── README.md
 ├── sequences/
 │   ├── CollaborativeApplication.md
 │   ├── ContentSite.md
 │   ├── GeneralWebApplication.md
 │   ├── LocalFirstApplication.md
 │   ├── README.md
 │   └── TransactionalApplication.md
 ├── technologies/
 │   └── README.md
 ├── templates/
 │   ├── Pattern.md
 │   └── TechnologyMapping.md
 ├── INTENT.md
 └── README.md
 ```
--- a/architectures/DocumentWeb.md
+++ b/architectures/DocumentWeb.md
@ -0,0 +1,18 @@
 # DocumentWeb
 Status: research stub
 ## Intent
 Describe **DocumentWeb** as a configuration of independent frontend patterns rather than as a monolithic architectural style.
 ## To establish
 - context
 - dominant forces
 - pattern configuration
 - variants
 - consequences
 - failure modes
 - known implementations
 - sources
--- a/architectures/Islands.md
+++ b/architectures/Islands.md
@ -0,0 +1,18 @@
 # Islands
 Status: research stub
 ## Intent
 Describe **Islands** as a configuration of independent frontend patterns rather than as a monolithic architectural style.
 ## To establish
 - context
 - dominant forces
 - pattern configuration
 - variants
 - consequences
 - failure modes
 - known implementations
 - sources
--- a/architectures/LocalFirst.md
+++ b/architectures/LocalFirst.md
@ -0,0 +1,18 @@
 # LocalFirst
 Status: research stub
 ## Intent
 Describe **LocalFirst** as a configuration of independent frontend patterns rather than as a monolithic architectural style.
 ## To establish
 - context
 - dominant forces
 - pattern configuration
 - variants
 - consequences
 - failure modes
 - known implementations
 - sources
--- a/architectures/Microfrontends.md
+++ b/architectures/Microfrontends.md
@ -0,0 +1,18 @@
 # Microfrontends
 Status: research stub
 ## Intent
 Describe **Microfrontends** as a configuration of independent frontend patterns rather than as a monolithic architectural style.
 ## To establish
 - context
 - dominant forces
 - pattern configuration
 - variants
 - consequences
 - failure modes
 - known implementations
 - sources
--- a/architectures/README.md
+++ b/architectures/README.md
@ -0,0 +1,24 @@
 # Named Architectures
 Named frontend architectures are represented here as **configurations of patterns**.
 This prevents architectural labels from becoming indivisible categories.
 Initial candidates:
 - Document Web
 - SPA
 - Islands
 - Server Components
 - Microfrontends
 - Local-First
 Each file should eventually answer:
 - What problem family does the architecture address?
 - Which patterns are essential?
 - Which are optional?
 - Which forces make the configuration attractive?
 - Which forces make it unattractive?
 - Which architectural variants exist?
 - Which technologies commonly implement it?
--- a/architectures/SPA.md
+++ b/architectures/SPA.md
@ -0,0 +1,18 @@
 # SPA
 Status: research stub
 ## Intent
 Describe **SPA** as a configuration of independent frontend patterns rather than as a monolithic architectural style.
 ## To establish
 - context
 - dominant forces
 - pattern configuration
 - variants
 - consequences
 - failure modes
 - known implementations
 - sources
--- a/architectures/ServerComponents.md
+++ b/architectures/ServerComponents.md
@ -0,0 +1,18 @@
 # ServerComponents
 Status: research stub
 ## Intent
 Describe **ServerComponents** as a configuration of independent frontend patterns rather than as a monolithic architectural style.
 ## To establish
 - context
 - dominant forces
 - pattern configuration
 - variants
 - consequences
 - failure modes
 - known implementations
 - sources
--- a/canon/Forces.md
+++ b/canon/Forces.md
@ -0,0 +1,80 @@
 # Forces
 Forces make architectural decisions non-trivial.
 The initial force vocabulary is intentionally broader than frontend implementation concerns.
 ## Experience
 - interaction latency
 - perceived responsiveness
 - continuity of interaction
 - discoverability
 - addressability
 - accessibility
 - recoverability
 - offline usability
 ## Information
 - authoritative consistency
 - freshness
 - cacheability
 - conflict probability
 - collaborative concurrency
 - data locality
 - privacy
 - information completeness
 ## Execution
 - first-content latency
 - hydration cost
 - client compute cost
 - server compute cost
 - bandwidth cost
 - connection lifetime
 - network reliability
 - startup cost
 - incremental update cost
 ## Change
 - feature change frequency
 - schema change frequency
 - independent deployability
 - team autonomy
 - release coupling
 - compatibility pressure
 ## Engineering
 - implementation complexity
 - reconciliation complexity
 - cognitive load
 - testability
 - observability
 - debuggability
 - portability
 - security exposure
 ## Operations
 - scalability
 - fault containment
 - deployment complexity
 - cache invalidation complexity
 - telemetry quality
 - incident recoverability
 ## Research questions
 The vocabulary should remain small enough to reason with.
 Research should determine:
 - which forces are independent,
 - which are merely metrics,
 - which are compound concepts,
 - which forces recur across most frontend patterns,
 - which forces should be modeled as dimensions rather than labels.
--- a/canon/FrontendPatternLanguage.md
+++ b/canon/FrontendPatternLanguage.md
@ -0,0 +1,219 @@
 # Frontend Pattern Language
 ## 1. Premise
 Frontend architecture is best understood as a progression of design decisions made under interacting forces.
 Frameworks and named architectural styles are downstream manifestations of these decisions.
 The pattern language therefore models:
 1. the **context** in which a problem occurs,
 2. the **forces** that make the problem non-trivial,
 3. the **pattern** that resolves those forces,
 4. the **resulting context** created by the resolution,
 5. the **relations** to other patterns,
 6. the **known implementations** of the pattern.
 ## 2. Fundamental responsibilities
 The initial model uses the following responsibilities.
 ### Address
 How application state, resources, views or intents are named and revisited.
 Examples:
 - URL,
 - route,
 - document identifier,
 - workspace identifier,
 - command target.
 ### Authority
 Which copy or system is allowed to define truth.
 Examples:
 - server authority,
 - local authority,
 - replicated authority,
 - event-log authority.
 ### Projection
 How authoritative or selected information becomes perceivable frontend state.
 Examples:
 - server-rendered HTML,
 - client-rendered view,
 - streamed projection,
 - static projection.
 ### Affordance
 Immediate local state and behavior that makes interaction responsive and intelligible.
 Examples:
 - open/closed state,
 - focus state,
 - draft input,
 - pending feedback,
 - speculative UI.
 ### Mutation
 How user intent becomes a proposed or committed state change.
 ### Synchronization
 How separated copies discover and exchange changes.
 ### Reconciliation
 How conflicting, stale or concurrent observations and mutations are resolved.
 ### Composition
 How independently understandable pieces combine into a larger frontend.
 ### Execution
 Where and when computation occurs.
 Examples:
 - build time,
 - server,
 - edge,
 - browser,
 - worker,
 - device.
 ## 3. Relation to the Navigation → Content → Affordance model
 The useful decomposition proposed by Ryan Carniato can be interpreted as:
 ```text
 Navigation ≈ Address + mutation orchestration
 Content    ≈ Authority → Projection
 Affordance ≈ local interaction + speculative state
 ```
 This is a powerful projection for server-authoritative web applications.
 The broader language keeps authority independent so that local-first, peer-to-peer and replicated architectures can be represented without distortion.
 ## 4. Pattern families
 Initial families:
 - `authority`
 - `address`
 - `projection`
 - `affordance`
 - `mutation`
 - `synchronization`
 - `composition`
 - `execution`
 - `quality`
 Families are navigational aids, not the primary ontology.
 Patterns may participate in several families.
 ## 5. Pattern scales
 The initial scale model is:
 ```text
 L0 Experience / Product
 L1 Application Topology
 L2 Authority & Distribution
 L3 Navigation & Projection
 L4 Feature / Domain Boundaries
 L5 Components
 L6 Interaction & State
 L7 Elements / Implementation
 ```
 The scale prevents unlike patterns from being compared as peers.
 ## 6. Generative use
 The language should support a sequence such as:
 ```text
 1. Characterize the experience
 2. Place authority
 3. Establish addressability
 4. Place projection
 5. Choose communication window
 6. Add local affordances
 7. Define mutation and reconciliation
 8. Establish feature boundaries
 9. Establish deployment boundaries
 10. Strengthen quality boundaries
 11. Measure and adapt
 ```
 This sequence is provisional and must be tested against real systems.
 ## 7. Technology mappings
 Technologies should be described as pattern configurations.
 Example:
 ```text
 Astro
  implements:
    Static Projection
    Server Projection
    Islands of Interactivity
    Deferred Client Execution
 ```
 A framework may implement several alternative patterns depending on configuration.
 ## 8. Named architectures
 A named architecture is treated as a reusable configuration of patterns, not as an indivisible pattern.
 Examples:
 - SPA
 - Islands
 - Server Components
 - Microfrontends
 - Local-first
 - Document web
 - Hypermedia-driven application
 ## 9. Evidence maturity
 Every pattern should eventually carry an evidence maturity.
 Suggested levels:
 - `hypothesis`
 - `emerging`
 - `established`
 - `canonical`
 Maturity describes confidence in the pattern description, not desirability.
 ## 10. Canon evolution
 Changes to the core canon should prefer:
 1. extending terminology,
 2. clarifying relations,
 3. introducing specializations,
 4. only then redefining existing concepts.
 The objective is a stable conceptual core with an expanding edge.
--- a/canon/PatternSchema.md
+++ b/canon/PatternSchema.md
@ -0,0 +1,96 @@
 # Pattern Schema
 Each pattern consists of structured metadata plus explanatory prose.
 ## Canonical metadata
 ```yaml
 ---
 id: FEP-AFF-001
 name: Optimistic Overlay
 family:
  - affordance
  - mutation
 scale: L6
 status: hypothesis
 context:
  - remote authority
  - perceptible mutation latency
 forces:
  improves:
    - interaction_latency
    - perceived_responsiveness
  worsens:
    - reconciliation_complexity
    - implementation_complexity
 requires:
  - identifiable_mutation
  - authoritative_state
 relations:
  refines:
    - local_interaction_state
  enables:
    - immediate_feedback
  conflicts_with:
    - destructive_uncompensated_mutation
 known_uses: []
 evidence:
  maturity: hypothesis
  sources: []
 ---
 ```
 ## Human-readable structure
 Every pattern should contain:
 ```text
 # Pattern Name
 ## Context
 ## Problem
 ## Forces
 ## Solution
 ## Dynamics
 ## Resulting Context
 ## Consequences
 ## Failure Modes
 ## Known Uses
 ## Related Patterns
 ## Evidence
 ## Implementation Notes
 ```
 ## Requirements
 A pattern should:
 - describe a recurring problem,
 - expose at least two meaningful forces,
 - propose a reusable configuration,
 - explain consequences,
 - identify failure modes,
 - create or refine a context in which other patterns apply.
 A useful technique is not automatically a pattern.
 A framework feature is not automatically a pattern.
 A pattern name should identify a reusable architectural idea rather than a product-specific API.
--- a/canon/Relations.md
+++ b/canon/Relations.md
@ -0,0 +1,71 @@
 # Pattern Relations
 The language is primarily a graph.
 ## Core relations
 ### requires
 Pattern A depends on the presence of Pattern B or on the context created by B.
 ### enables
 Applying A makes B possible or substantially easier.
 ### creates-context-for
 A changes the system such that B becomes a relevant subsequent decision.
 This is especially important for generative sequences.
 ### refines
 A is a more specific realization of B.
 ### generalizes
 A captures the common structure of several more specific patterns.
 ### complements
 A and B solve different parts of a larger problem and commonly reinforce each other.
 ### alternative-to
 A and B address substantially the same problem using different trade-offs.
 ### conflicts-with
 The assumptions or consequences of A and B are structurally incompatible or create severe tension.
 ### commonly-combined-with
 Empirical relation based on frequent co-occurrence.
 ### implemented-by
 Links a pattern to technologies or concrete mechanisms.
 ### observed-in
 Links a pattern to known systems or architectures.
 ## Relation semantics
 Relations should be directional where possible.
 For example:
 ```text
 Server Authority
    creates-context-for → Server Projection
 ```
 is more informative than:
 ```text
 Server Authority
    related-to ↔ Server Projection
 ```
 Avoid a generic `related-to` relation unless no stronger relation can be justified.
--- a/canon/Responsibilities.md
+++ b/canon/Responsibilities.md
@ -0,0 +1,49 @@
 # Responsibilities
 This document defines the current responsibility model used to analyze frontend architectures.
 ## Address
 Names or locates application state, resources, views and intents.
 ## Authority
 Determines which actor or replica may establish truth.
 ## Projection
 Transforms selected state into perceivable representation.
 ## Affordance
 Provides the local state and behavior necessary for immediate interaction.
 ## Mutation
 Carries user intent toward state change.
 ## Synchronization
 Propagates state or change between separated actors.
 ## Reconciliation
 Resolves divergence, conflict, stale state or concurrency.
 ## Composition
 Combines independently understandable frontend structures.
 ## Execution
 Places computation in time and location.
 ## Important qualification
 These responsibilities are analytical dimensions, not necessarily software components.
 One module may implement several responsibilities.
 One responsibility may be distributed across many modules.
 The model should therefore not be turned into a mandatory component architecture.
--- a/canon/Scales.md
+++ b/canon/Scales.md
@ -0,0 +1,89 @@
 # Scales
 Patterns operate at different architectural scales.
 ## L0 — Experience / Product
 Concerns the overall interactive system experienced by a user.
 Examples:
 - collaborative editor,
 - transactional workflow,
 - content publication,
 - offline field application.
 ## L1 — Application Topology
 Large-scale application organization.
 Examples:
 - independently deployable frontend,
 - application shell,
 - frontend/backend partitioning.
 ## L2 — Authority & Distribution
 Placement and replication of authoritative state.
 Examples:
 - server authority,
 - local authority,
 - replicated authority.
 ## L3 — Navigation & Projection
 Addressability, routing, rendering and delivery of perceivable state.
 Examples:
 - URL as state,
 - server projection,
 - client projection,
 - streaming projection.
 ## L4 — Feature / Domain Boundaries
 Functional decomposition.
 Examples:
 - vertical feature slice,
 - bounded frontend feature,
 - backend for frontend.
 ## L5 — Components
 Reusable interaction and presentation structures.
 Examples:
 - presentation model,
 - compound component,
 - controlled component.
 ## L6 — Interaction & State
 Fine-grained interaction behavior.
 Examples:
 - local interaction state,
 - optimistic overlay,
 - pending state.
 ## L7 — Elements / Implementation
 Low-level implementation structures.
 Examples:
 - lazy boundary,
 - error boundary,
 - focus restoration.
 ## Rule
 Patterns from different scales may relate strongly, but should not be treated as equivalent alternatives merely because they are all called "frontend patterns".
--- a/patterns/README.md
+++ b/patterns/README.md
@ -0,0 +1,104 @@
 # Patterns
 This directory contains canonical frontend patterns.
 Each pattern should conform to `canon/PatternSchema.md`.
 ## Initial families
 - `authority/`
 - `address/`
 - `projection/`
 - `affordance/`
 - `mutation/`
 - `synchronization/`
 - `composition/`
 - `execution/`
 - `quality/`
 ## Candidate seed patterns
 ### Authority
 - Server Authority
 - Local Authority
 - Replicated Authority
 - Event-Log Authority
 - Single Writer
 - Derived State
 ### Address
 - URL as Application State
 - Resource Address
 - Hierarchical Route
 - Progressive Navigation
 ### Projection
 - Static Projection
 - Server Projection
 - Client Projection
 - Hybrid Projection
 - Streaming Projection
 - Islands of Interactivity
 - Server Components
 - Progressive Hydration
 - Resumable UI
 ### Affordance
 - Local Interaction State
 - Immediate Feedback
 - Pending State
 - Optimistic Overlay
 - Undoable Intent
 - Speculative Interaction
 ### Mutation & Synchronization
 - Command Mutation
 - Form Mutation
 - Idempotent Mutation
 - Invalidate and Reproject
 - Pull Synchronization
 - Push Synchronization
 - Persistent Subscription
 - Conflict-Free Merge
 - Explicit Conflict
 ### Composition
 - Presentation / Domain Separation
 - Presentation Model
 - Vertical Feature Slice
 - Public Module Surface
 - Independent Feature Boundary
 - Microfrontend
 - Backend for Frontend
 - Design System
 ### Execution
 - Build-Time Execution
 - Server Execution
 - Edge Execution
 - Client Execution
 - Deferred Execution
 - Code Split
 - Lazy Load
 - Independent Deployment
 ### Quality
 - Progressive Enhancement
 - Accessible by Construction
 - Failure Boundary
 - Async Boundary
 - Security Boundary
 - Privacy Boundary
 - Performance Budget
 - Observable Interaction
 - Recoverable Interaction
 These names are candidates. Research should consolidate, rename, split or reject them as needed.
--- a/patterns/address/README.md
+++ b/patterns/address/README.md
@ -0,0 +1,7 @@
 # Address Patterns
 Candidate and canonical patterns concerning **address**.
 Patterns in this directory should conform to `../../canon/PatternSchema.md`.
 This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata.
--- a/patterns/affordance/README.md
+++ b/patterns/affordance/README.md
@ -0,0 +1,7 @@
 # Affordance Patterns
 Candidate and canonical patterns concerning **affordance**.
 Patterns in this directory should conform to `../../canon/PatternSchema.md`.
 This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata.
--- a/patterns/authority/README.md
+++ b/patterns/authority/README.md
@ -0,0 +1,7 @@
 # Authority Patterns
 Candidate and canonical patterns concerning **authority**.
 Patterns in this directory should conform to `../../canon/PatternSchema.md`.
 This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata.
--- a/patterns/composition/README.md
+++ b/patterns/composition/README.md
@ -0,0 +1,7 @@
 # Composition Patterns
 Candidate and canonical patterns concerning **composition**.
 Patterns in this directory should conform to `../../canon/PatternSchema.md`.
 This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata.
--- a/patterns/execution/README.md
+++ b/patterns/execution/README.md
@ -0,0 +1,7 @@
 # Execution Patterns
 Candidate and canonical patterns concerning **execution**.
 Patterns in this directory should conform to `../../canon/PatternSchema.md`.
 This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata.
--- a/patterns/mutation/README.md
+++ b/patterns/mutation/README.md
@ -0,0 +1,7 @@
 # Mutation Patterns
 Candidate and canonical patterns concerning **mutation**.
 Patterns in this directory should conform to `../../canon/PatternSchema.md`.
 This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata.
--- a/patterns/projection/README.md
+++ b/patterns/projection/README.md
@ -0,0 +1,7 @@
 # Projection Patterns
 Candidate and canonical patterns concerning **projection**.
 Patterns in this directory should conform to `../../canon/PatternSchema.md`.
 This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata.
--- a/patterns/quality/README.md
+++ b/patterns/quality/README.md
@ -0,0 +1,7 @@
 # Quality Patterns
 Candidate and canonical patterns concerning **quality**.
 Patterns in this directory should conform to `../../canon/PatternSchema.md`.
 This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata.
--- a/patterns/synchronization/README.md
+++ b/patterns/synchronization/README.md
@ -0,0 +1,7 @@
 # Synchronization Patterns
 Candidate and canonical patterns concerning **synchronization**.
 Patterns in this directory should conform to `../../canon/PatternSchema.md`.
 This family is provisional: patterns may later move, participate in multiple families, or be represented primarily through graph metadata.
--- a/research/README.md
+++ b/research/README.md
@ -0,0 +1,18 @@
 # Research
 Research material supports the canon but is kept separate from canonical patterns.
 The structure follows the C3 research deliverable model where useful:
 - `catalog/` — normalized inventories and indices.
 - `compendium/` — explanatory synthesis of established knowledge.
 - `concepts/` — emerging models and hypotheses.
 Additional directories:
 - `cases/` — focused analysis of articles, systems or architectural schools.
 - `plan/` — research program, methods and open questions.
 Research material may be provisional.
 Promotion into the canon should happen only after the concept has been reconciled with competing models and tested against multiple frontend architectures.
--- a/research/cases/CarniatoGrandUnifyingArchitecture.md
+++ b/research/cases/CarniatoGrandUnifyingArchitecture.md
@ -0,0 +1,79 @@
 # Case Study — The Grand Unifying Architecture of Frontend
 Status: initial research stub
 Source:
 Ryan Carniato, "The Grand Unifying Architecture of Frontend".
 ## Why this source matters
 The article attempts to unify several modern frontend architectures beneath framework-specific terminology.
 Its most useful conceptual move is the decomposition:
 ```text
 Navigation → Content → Affordance
 ```
 with a characteristic movement:
 ```text
 client → server → client
 ```
 for server-authoritative applications.
 ## Initial interpretation
 ### Navigation
 Contains aspects of:
 - addressability,
 - routing,
 - user intent,
 - mutation initiation.
 ### Content
 Contains aspects of:
 - authority,
 - server-side state,
 - projection.
 ### Affordance
 Contains aspects of:
 - local interaction state,
 - speculative state,
 - immediate feedback.
 ## Main qualification
 The model strongly fits server-authoritative web applications.
 It should not be promoted unchanged into the general canon because:
 - local-first systems may treat local data as primary,
 - replicated systems may have multiple authorities,
 - peer-to-peer systems may lack a distinguished server,
 - microfrontend concerns cut across this axis,
 - internal modularity is largely orthogonal to it.
 ## Research tasks
 - extract concrete architecture examples from the article,
 - identify all implicit assumptions,
 - map each example to responsibility dimensions,
 - identify candidate patterns,
 - compare against:
  - local-first,
  - HTMX/hypermedia,
  - SPA,
  - server components,
  - islands,
  - LiveView-style persistent server interaction,
 - identify where the model is descriptive versus normative,
 - determine which concepts should enter the canon.
--- a/research/catalog/PatternCandidateCatalog.md
+++ b/research/catalog/PatternCandidateCatalog.md
@ -0,0 +1,24 @@
 # Pattern Candidate Catalog
 This file tracks concepts before promotion into canonical pattern files.
 | Candidate | Family | Scale | Status | Main force |
 |---|---|---:|---|---|
 | Server Authority | authority | L2 | seed | authoritative consistency |
 | Local Authority | authority | L2 | seed | offline usability |
 | Replicated Authority | authority | L2 | seed | collaborative concurrency |
 | URL as Application State | address | L3 | seed | addressability |
 | Server Projection | projection | L3 | seed | client compute / delivery |
 | Client Projection | projection | L3 | seed | interaction locality |
 | Streaming Projection | projection | L3 | seed | first-content latency |
 | Islands of Interactivity | projection | L3 | seed | client execution cost |
 | Local Interaction State | affordance | L6 | seed | responsiveness |
 | Optimistic Overlay | affordance | L6 | seed | interaction latency |
 | Invalidate and Reproject | synchronization | L3/L6 | seed | freshness |
 | Persistent Subscription | synchronization | L3 | seed | update latency |
 | Vertical Feature Slice | composition | L4 | seed | change locality |
 | Independent Feature Boundary | composition | L4 | seed | team autonomy |
 | Progressive Enhancement | quality | cross-scale | seed | resilience/accessibility |
 | Failure Boundary | quality | L5/L6 | seed | fault containment |
 `seed` means "worth researching", not "accepted into the canon".
--- a/research/catalog/SourceCatalog.md
+++ b/research/catalog/SourceCatalog.md
@ -0,0 +1,31 @@
 # Source Catalog
 Initial source families to populate.
 | Family | Representative sources | Research purpose |
 |---|---|---|
 | Pattern languages | Christopher Alexander, Hillside/PLoP literature | Pattern form, relations, generative sequences |
 | GUI architecture | Martin Fowler, MVC/MVP/Presentation Model | Presentation/domain/state separation |
 | Unidirectional state | Flux, Redux, Elm | State transition and dependency direction |
 | Hypermedia | REST, HTML forms, HTMX | Navigation, mutation, server projection |
 | Rendering | web.dev, framework docs, Patterns.dev | CSR/SSR/SSG/hydration/islands/streaming |
 | Local-first | Ink & Switch and related work | Local authority, sync, conflict handling |
 | Distributed state | CRDT/event sourcing/sync literature | Reconciliation and replication |
 | Modularity | Feature-Sliced Design | Feature boundaries and dependency rules |
 | Organizational architecture | Microfrontend literature | Independent ownership/deployment |
 | Quality | WCAG, progressive enhancement, web performance | Cross-cutting architectural forces |
 ## Catalog policy
 Each source should eventually capture:
 - source identity,
 - date/version,
 - scope,
 - vocabulary used,
 - candidate patterns,
 - dominant forces,
 - assumptions,
 - contradictions,
 - known implementations,
 - evidence quality.
--- a/research/compendium/FrontendArchitectureCompendium.md
+++ b/research/compendium/FrontendArchitectureCompendium.md
@ -0,0 +1,31 @@
 # Frontend Architecture Compendium
 ## Purpose
 Provide a continuously improving synthesis of the major ideas used to reason about frontend architecture.
 The compendium explains schools of thought without treating any one of them as the canonical model.
 ## Initial chapters
 1. From GUI architecture to web architecture
 2. Navigation and the document web
 3. Client/server authority
 4. State management and unidirectional flow
 5. Rendering and projection
 6. Hydration, islands and resumability
 7. Server components and streamed UI
 8. Hypermedia-driven applications
 9. Local-first and replicated frontends
 10. Composition and feature slicing
 11. Microfrontends and organizational boundaries
 12. Accessibility, resilience and progressive enhancement
 13. Performance as architecture
 14. Frontend observability and recoverability
 15. Pattern languages as a unifying representation
 ## Editorial rule
 The compendium may explain technologies and historical movements in detail.
 Canonical patterns should remain technology-independent whenever possible.
--- a/research/concepts/GenerativeSequence.md
+++ b/research/concepts/GenerativeSequence.md
@ -0,0 +1,42 @@
 # Concept — Generative Frontend Architecture Sequence
 Status: hypothesis
 ## Candidate sequence
 ```text
 Characterize Experience
 → Place Authority
 → Establish Addressability
 → Place Projection
 → Choose Communication Window
 → Add Local Affordances
 → Define Mutation & Reconciliation
 → Establish Feature Boundaries
 → Establish Deployment Boundaries
 → Strengthen Quality Boundaries
 → Measure & Adapt
 ```
 ## Hypothesis
 Ordering matters.
 For example:
 - authority influences synchronization,
 - addressability influences navigation and projection,
 - projection placement influences execution cost,
 - local affordances influence mutation/reconciliation requirements,
 - feature boundaries may later justify deployment boundaries.
 The language should capture these causal dependencies rather than present all patterns as an unordered menu.
 ## Validation
 Test the sequence against contrasting frontend systems and record:
 - decisions that occur too early,
 - missing decisions,
 - unavoidable feedback loops,
 - architecture types that require alternate branches.
--- a/research/concepts/ResponsibilityModel.md
+++ b/research/concepts/ResponsibilityModel.md
@ -0,0 +1,42 @@
 # Concept — Frontend Responsibility Model
 Status: hypothesis
 ## Proposition
 Frontend architectures can be usefully analyzed through nine responsibilities:
 1. Address
 2. Authority
 3. Projection
 4. Affordance
 5. Mutation
 6. Synchronization
 7. Reconciliation
 8. Composition
 9. Execution
 These are dimensions of responsibility, not mandatory modules.
 ## Value
 The model appears broad enough to describe:
 - document-oriented web applications,
 - SPAs,
 - server-rendered systems,
 - islands,
 - server components,
 - microfrontends,
 - offline-first applications,
 - local-first applications,
 - collaborative replicated applications.
 ## Research burden
 The model must be challenged for:
 - redundancy,
 - missing responsibilities,
 - ambiguous boundaries,
 - inability to distinguish materially different architectures.
--- a/research/plan/OpenQuestions.md
+++ b/research/plan/OpenQuestions.md
@ -0,0 +1,28 @@
 # Open Questions
 ## Core ontology
 - Is `Authority → Projection → Affordance` a better primary axis than traditional "state management" terminology?
 - Should `Mutation` represent intent, transport, state transition, or be split?
 - Is `Reconciliation` independent enough to be a first-class responsibility?
 - Should `Communication Window` become a canonical dimension?
 ## Pattern language
 - What qualifies as a pattern rather than a technique?
 - How much implementation detail belongs in canonical patterns?
 - How do we represent patterns that only make sense at one scale?
 - How should pattern relations be validated?
 ## Agentic use
 - Which metadata is necessary for useful pattern retrieval?
 - Should the pattern graph be exported as JSON/YAML/RDF?
 - Can force matching be made quantitative without creating false precision?
 - Can architecture review be expressed as unresolved-force detection?
 ## Evidence
 - What makes a frontend pattern "established"?
 - Should known uses be manually curated or automatically mined?
 - How should contradictory source claims be represented?
--- a/research/plan/ResearchProgram.md
+++ b/research/plan/ResearchProgram.md
@ -0,0 +1,395 @@
 # Frontend Patterns Research Program
 ## 1. Objective
 Develop a coherent Alexander-style pattern language for frontend architecture and design that is useful to both human practitioners and software agents.
 The work should move from source collection toward:
 1. common vocabulary,
 2. recurring forces,
 3. candidate patterns,
 4. pattern relations,
 5. generative sequences,
 6. architecture decompositions,
 7. technology mappings,
 8. machine-readable retrieval and reasoning.
 ## 2. Research thesis
 Frontend architecture is not fundamentally organized around frameworks.
 It is organized around recurring decisions concerning:
 - authority,
 - addressability,
 - projection,
 - interaction,
 - mutation,
 - synchronization,
 - reconciliation,
 - composition,
 - execution,
 - quality boundaries.
 Named architectures and frameworks are configurations or implementations of these decisions.
 ## 3. First research case
 Use Ryan Carniato's "The Grand Unifying Architecture of Frontend" as the first extraction exercise.
 Research tasks:
 1. reconstruct its Navigation → Content → Affordance model,
 2. identify implicit assumptions,
 3. extract candidate patterns,
 4. identify the forces each pattern resolves,
 5. identify where server-authority assumptions cease to hold,
 6. compare against local-first architectures,
 7. compare against hypermedia architectures,
 8. compare against SPA and server-component architectures,
 9. map findings into the responsibility model,
 10. retain useful concepts without treating the article as the canonical ontology.
 ## 4. Research streams
 ### Stream A — Historical GUI architecture
 Study:
 - MVC,
 - MVP,
 - Presentation Model,
 - Presentation / Domain Separation,
 - Flux / Redux,
 - Elm architecture,
 - event-driven UI.
 Goal:
 Identify durable state, dependency and interaction patterns that predate current web frameworks.
 ### Stream B — Web navigation and hypermedia
 Study:
 - document web,
 - REST/hypermedia,
 - progressive enhancement,
 - HTML forms,
 - HTMX-style server interaction,
 - browser navigation semantics.
 Goal:
 Understand addressability, navigation, mutation and server projection.
 ### Stream C — Rendering and execution
 Study:
 - CSR,
 - SSR,
 - SSG,
 - hydration,
 - partial hydration,
 - islands,
 - server components,
 - resumability,
 - streaming,
 - edge execution.
 Goal:
 Separate projection patterns from execution placement and delivery mechanisms.
 ### Stream D — State authority and synchronization
 Study:
 - client/server state,
 - remote caches,
 - optimistic UI,
 - local-first,
 - CRDTs,
 - event sourcing,
 - offline-first,
 - subscriptions,
 - push/pull synchronization.
 Goal:
 Establish a coherent authority/synchronization/reconciliation language.
 ### Stream E — Composition and organizational architecture
 Study:
 - component composition,
 - feature slicing,
 - microfrontends,
 - design systems,
 - frontend platform architecture,
 - backend-for-frontend patterns,
 - monorepos and deployment independence.
 Goal:
 Separate software composition from ownership and deployment boundaries.
 ### Stream F — Quality patterns
 Study:
 - accessibility,
 - progressive enhancement,
 - performance,
 - fault containment,
 - security,
 - privacy,
 - observability,
 - recovery.
 Goal:
 Represent cross-cutting frontend qualities as architectural patterns and forces rather than afterthoughts.
 ## 5. Research method
 For each source or architecture:
 ### Step 1 — Extract claims
 Record what the source says without prematurely normalizing terminology.
 ### Step 2 — Identify forces
 Ask what competing constraints make the proposed solution useful.
 ### Step 3 — Extract candidate patterns
 Look for recurring configurations rather than named technologies.
 ### Step 4 — Normalize vocabulary
 Map source-specific language into the current canon where possible.
 ### Step 5 — Find counterexamples
 Test whether the pattern still holds under:
 - offline operation,
 - local authority,
 - real-time collaboration,
 - very low interaction density,
 - high interaction density,
 - independent deployment,
 - unreliable networks,
 - strong accessibility requirements.
 ### Step 6 — Establish relations
 Record:
 - requires,
 - enables,
 - refines,
 - alternatives,
 - conflicts,
 - resulting contexts.
 ### Step 7 — Test generativity
 Ask whether the pattern helps produce a next architectural decision.
 ### Step 8 — Promote cautiously
 Move a concept into `patterns/` only when it is sufficiently stable and reusable.
 ## 6. Initial source families
 Create a source catalog spanning:
 - Christopher Alexander and pattern-language literature,
 - Martin Fowler GUI architecture,
 - REST and hypermedia literature,
 - Redux / Elm / Flux,
 - Feature-Sliced Design,
 - microfrontends,
 - local-first,
 - web.dev rendering literature,
 - Patterns.dev,
 - framework architectural documentation,
 - accessibility and progressive-enhancement literature,
 - distributed-systems synchronization concepts.
 ## 7. Initial pattern extraction targets
 Priority candidate patterns:
 ### Authority
 - Server Authority
 - Local Authority
 - Replicated Authority
 - Derived State
 - Single Writer
 ### Address & navigation
 - URL as Application State
 - Resource Address
 - Hierarchical Route
 - Progressive Navigation
 ### Projection
 - Static Projection
 - Server Projection
 - Client Projection
 - Streaming Projection
 - Islands of Interactivity
 ### Interaction
 - Local Interaction State
 - Immediate Feedback
 - Pending State
 - Optimistic Overlay
 ### Synchronization
 - Invalidate and Reproject
 - Pull Synchronization
 - Push Synchronization
 - Persistent Subscription
 - Conflict-Free Merge
 - Explicit Conflict
 ### Composition
 - Presentation / Domain Separation
 - Vertical Feature Slice
 - Independent Feature Boundary
 - Backend for Frontend
 ### Quality
 - Progressive Enhancement
 - Failure Boundary
 - Accessible by Construction
 - Performance Budget
 - Observable Interaction
 ## 8. Validation architectures
 The emerging language should be tested against at least these application types:
 1. mostly-static publication,
 2. e-commerce storefront,
 3. administrative CRUD application,
 4. high-interaction SaaS workspace,
 5. real-time dashboard,
 6. collaborative editor,
 7. offline field application,
 8. local-first personal tool,
 9. large microfrontend estate,
 10. mobile-web/PWA application.
 A useful language should explain all ten without forcing them into one preferred architecture.
 ## 9. Agentic use cases
 The infospace should eventually support prompts such as:
 > Given this application description, identify the dominant forces and propose applicable patterns.
 > Explain why the current architecture exhibits this failure mode.
 > Which patterns are incompatible with our offline requirement?
 > Decompose this framework architecture into technology-independent patterns.
 > What pattern should be considered next after choosing server authority and streaming projection?
 > Compare two architectures in terms of forces, not framework features.
 This requires graph-friendly metadata and stable identifiers.
 ## 10. Initial milestones
 ### M0 — Scaffold
 - repository structure,
 - intent,
 - responsibility model,
 - force vocabulary,
 - relation vocabulary,
 - pattern schema,
 - research method.
 ### M1 — Seed corpus
 - source catalog,
 - Carniato case analysis,
 - historical GUI architecture review,
 - local-first review,
 - rendering architecture review.
 ### M2 — First canonical language
 - 20–30 candidate patterns,
 - reviewed force vocabulary,
 - relation graph,
 - first architecture decompositions.
 ### M3 — Generative sequences
 - general web application,
 - content site,
 - transactional application,
 - collaborative application,
 - local-first application.
 ### M4 — Agentic reference surface
 - normalized metadata,
 - stable identifiers,
 - pattern graph export,
 - query examples,
 - retrieval/evaluation fixtures.
 ### M5 — Empirical refinement
 - test language against real repositories,
 - collect pattern co-occurrence,
 - identify missing forces,
 - identify misleading or redundant patterns,
 - revise maturity levels.
 ## 11. Open research questions
 1. Is the current responsibility model minimal?
 2. Should mutation be separate from intent?
 3. Is reconciliation a responsibility or a synchronization subfamily?
 4. Is addressability a frontend responsibility or a system-level concern?
 5. Should rendering and projection remain distinct terms?
 6. How should temporal behavior be represented?
 7. How should pattern strength or evidence be measured?
 8. Can pattern selection be meaningfully represented as constraint solving?
 9. How should anti-patterns be modeled?
 10. Can architecture health be described as unresolved or contradictory forces?
 ## 12. Definition of useful progress
 The project is not advanced by adding pattern names alone.
 Useful progress means improving one or more of:
 - conceptual precision,
 - pattern reuse,
 - relation quality,
 - generative power,
 - evidence quality,
 - applicability across architectures,
 - retrieval quality for humans and agents.
--- a/sequences/CollaborativeApplication.md
+++ b/sequences/CollaborativeApplication.md
@ -0,0 +1,15 @@
 # CollaborativeApplication
 Status: research stub
 A generative sequence for multi-user concurrent interaction, presence, synchronization and conflict resolution.
 ## Research tasks
 - identify dominant forces,
 - establish authority assumptions,
 - determine suitable projection patterns,
 - determine synchronization model,
 - identify failure modes,
 - derive candidate sequence,
 - test against known implementations.
--- a/sequences/ContentSite.md
+++ b/sequences/ContentSite.md
@ -0,0 +1,15 @@
 # ContentSite
 Status: research stub
 A generative sequence optimized for content-oriented sites with strong addressability, delivery and progressive-enhancement requirements.
 ## Research tasks
 - identify dominant forces,
 - establish authority assumptions,
 - determine suitable projection patterns,
 - determine synchronization model,
 - identify failure modes,
 - derive candidate sequence,
 - test against known implementations.
--- a/sequences/GeneralWebApplication.md
+++ b/sequences/GeneralWebApplication.md
@ -0,0 +1,112 @@
 # General Web Application — Generative Sequence
 Status: hypothesis
 ## Starting question
 How should a web application progressively resolve its frontend architecture without starting from a framework choice?
 ## Sequence
 ### 1. Characterize the experience
 Identify:
 - dominant user activities,
 - interaction intensity,
 - continuity requirements,
 - collaboration requirements,
 - offline requirements,
 - addressability requirements,
 - latency sensitivity.
 ### 2. Place authority
 Choose among patterns such as:
 - Server Authority
 - Local Authority
 - Replicated Authority
 - Event-Log Authority
 ### 3. Establish addressability
 Determine what must be named, linked, revisited, bookmarked or shared.
 Potential patterns:
 - URL as Application State
 - Resource Address
 - Hierarchical Route
 ### 4. Place projection
 Determine where perceivable state is derived.
 Potential patterns:
 - Static Projection
 - Server Projection
 - Client Projection
 - Hybrid Projection
 - Streaming Projection
 ### 5. Choose the communication window
 Determine whether communication is:
 - request/response,
 - polling,
 - long-lived,
 - streamed,
 - replicated,
 - peer-to-peer.
 ### 6. Add local affordances
 Identify state that should remain near the user interaction.
 Potential patterns:
 - Local Interaction State
 - Pending State
 - Immediate Feedback
 - Optimistic Overlay
 ### 7. Define mutation and reconciliation
 Decide:
 - command shape,
 - idempotency,
 - conflict handling,
 - invalidation,
 - resynchronization.
 ### 8. Establish feature boundaries
 Determine which domain and interaction capabilities can evolve independently.
 ### 9. Establish deployment boundaries
 Only split independent deployment where the organizational and runtime forces justify it.
 ### 10. Strengthen quality boundaries
 Apply accessibility, failure containment, security, privacy, observability and performance patterns.
 ### 11. Measure and adapt
 Observe runtime behavior and revisit earlier choices when actual forces differ from assumed forces.
 ## Research status
 This sequence must be tested against contrasting architectures:
 - content site,
 - CRUD SaaS,
 - real-time dashboard,
 - collaborative editor,
 - e-commerce storefront,
 - local-first application,
 - microfrontend estate.
--- a/sequences/LocalFirstApplication.md
+++ b/sequences/LocalFirstApplication.md
@ -0,0 +1,15 @@
 # LocalFirstApplication
 Status: research stub
 A generative sequence for applications in which local state remains usable and authoritative interaction continues despite network loss.
 ## Research tasks
 - identify dominant forces,
 - establish authority assumptions,
 - determine suitable projection patterns,
 - determine synchronization model,
 - identify failure modes,
 - derive candidate sequence,
 - test against known implementations.
--- a/sequences/README.md
+++ b/sequences/README.md
@ -0,0 +1,23 @@
 # Generative Sequences
 A sequence guides architecture construction through an ordered series of pattern decisions.
 Sequences are not mandatory reference architectures.
 They should explain:
 - starting context,
 - major forces,
 - ordering rationale,
 - decision points,
 - applicable patterns,
 - branches,
 - resulting contexts.
 Initial sequence candidates:
 - `GeneralWebApplication.md`
 - `ContentSite.md`
 - `TransactionalApplication.md`
 - `CollaborativeApplication.md`
 - `LocalFirstApplication.md`
--- a/sequences/TransactionalApplication.md
+++ b/sequences/TransactionalApplication.md
@ -0,0 +1,15 @@
 # TransactionalApplication
 Status: research stub
 A generative sequence for applications dominated by forms, workflows, commands, validation and authoritative transactions.
 ## Research tasks
 - identify dominant forces,
 - establish authority assumptions,
 - determine suitable projection patterns,
 - determine synchronization model,
 - identify failure modes,
 - derive candidate sequence,
 - test against known implementations.
--- a/technologies/README.md
+++ b/technologies/README.md
@ -0,0 +1,17 @@
 # Technology Mappings
 Technologies are mapped to the patterns they can implement.
 Technology files are descriptive, not normative.
 A mapping may contain:
 - implemented patterns,
 - optional patterns,
 - constraints,
 - characteristic defaults,
 - architectural assumptions,
 - counterexamples,
 - source references.
 A technology must not become part of the core ontology merely because it is popular.
--- a/templates/Pattern.md
+++ b/templates/Pattern.md
@ -0,0 +1,56 @@
 ---
 id: FEP-XXX-000
 name: Pattern Name
 family: []
 scale: L0
 status: hypothesis
 context: []
 forces:
  improves: []
  worsens: []
 requires: []
 relations:
  enables: []
  refines: []
  generalizes: []
  complements: []
  alternative-to: []
  conflicts-with: []
  creates-context-for: []
 known_uses: []
 evidence:
  maturity: hypothesis
  sources: []
 ---
 # Pattern Name
 ## Context
 ## Problem
 ## Forces
 ## Solution
 ## Dynamics
 ## Resulting Context
 ## Consequences
 ## Failure Modes
 ## Known Uses
 ## Related Patterns
 ## Evidence
 ## Implementation Notes
--- a/templates/TechnologyMapping.md
+++ b/templates/TechnologyMapping.md
@ -0,0 +1,17 @@
 # Technology Name
 ## Scope
 ## Characteristic architectural assumptions
 ## Implemented patterns
 ## Optional patterns
 ## Constraints
 ## Known variants
 ## Counterexamples
 ## Sources