Preserve initial frontend pattern language research scaffold

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

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.

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.

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.

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.

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.

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