Preserve initial frontend pattern language research scaffold

Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a0cffe-206f-7323-89d3-b20ca4cf4bf9

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.

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.

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".

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.

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.

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.

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.

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?

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.