Skip to content

Commit 9c8e0b9

Browse files
fsecada01claude
fsecada01
and
claude
committed
docs: scope path-to-1.0 roadmap + market/gap analysis
Document the production-grade development path in the README and capture the supporting research. - README: add 0.5.0 (Complete); replace the thin "1.0 (Planned)" list with a milestone-based "Path to 1.0" (0.6.0b Hardening / 0.7.0b Real-App / 0.8.0b Mindshare / 1.0.0 Stable), naming the signed-state + DOM-morph critical-path enablers and linking the plan, research, and GitHub milestones. Add [flask] to the Requirements extras list. - claudedocs/research_liveview_market_2026-06-24.md: market analysis, competitor landscape, and per-feature gap analysis vs LiveView/Livewire/Hotwire. - claudedocs/dev_plan_production_grade_2026-06-24.md: epics, milestones, dependencies, sequencing, and effort estimates (filed as GitHub issues #21-28). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017hdmTV88wAXU8ew1rorMjt
1 parent 6bfdb22 commit 9c8e0b9

3 files changed

Lines changed: 458 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 48 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -568,12 +568,54 @@ just claude-prompt PROMPT_FILE=prompts/WORKFLOW.md
568568
- [x] State size guard — configurable warning (64 KB) and hard limit (512 KB)
569569
- [x] JS double-serialisation fix in `component-client.js`
570570

571-
### 1.0 (Planned)
572-
- [ ] Stable, frozen public API
573-
- [ ] Performance benchmarks and optimisation
571+
### 0.5.0 (Complete)
572+
- [x] Flask adapter — `FlaskRenderer` + HTTP blueprint (`[flask]` extra)
573+
- [x] Optimistic UI patching in the client (`component-client.js` + `component-framework.css`)
574+
- [x] JinjaX catalog sharing guidance (reuse the host app's `Catalog`)
575+
576+
### Path to 1.0 (Planned)
577+
578+
The road to a **production-grade** 1.0 is scoped into milestones, derived from a
579+
[market & gap analysis](claudedocs/research_liveview_market_2026-06-24.md) against
580+
Phoenix LiveView, Livewire, and Hotwire. Full work breakdown (epics, dependencies,
581+
effort) is in the [development plan](claudedocs/dev_plan_production_grade_2026-06-24.md)
582+
and tracked via [GitHub milestones](https://github.com/fsecada01/component-framework/milestones)
583+
and [epic issues](https://github.com/fsecada01/component-framework/issues?q=is%3Aissue+label%3Aepic).
584+
585+
> The two critical-path enablers are **signed state** (security gate — component state
586+
> currently round-trips to the client unsigned) and **DOM morphing** (today the client
587+
> does a full `innerHTML` replace, which unblocks navigation, forms fidelity, and
588+
> optimistic UI once it lands).
589+
590+
**0.6.0b — Hardening Foundation** *(Tier 0: security & rendering fidelity)*
591+
- [ ] Signed / tamper-proof state (HMAC) — *security gate*
592+
- [ ] DOM morphing — preserve focus / scroll / in-flight input; stable list keys
593+
- [ ] CSRF coverage for FastAPI / Litestar / Flask HTTP paths (today Django-only)
594+
- [ ] 422 re-render on form-validation failure (adapters currently return 200)
595+
- [ ] Cross-adapter request-parse hardening
596+
597+
**0.7.0b — Real-App Features** *(Tier 1: table-stakes app capabilities)*
598+
- [ ] Live SPA navigation — history / back-button, loading indicator, scroll restore
599+
- [ ] File uploads — progress, multiple files, size/type constraints
600+
- [ ] On-blur / real-time partial validation
601+
- [ ] WebSocket reconnection + automatic state resync
602+
- [ ] Flask WebSocket / SSE parity
603+
- [ ] Unified Redis pub/sub fan-out across adapters
604+
605+
**0.8.0b — Mindshare** *(Tier 2: observability & DX)*
606+
- [ ] Telemetry / observability — lifecycle spans + timing hooks
607+
- [ ] Published benchmarks (latency, payload, memory/connection, concurrency)
608+
- [ ] Declarative optimistic-JS command DSL; JS interop hooks with lifecycle
609+
- [ ] Latency simulation; offline detection + visibility-throttled polling
610+
611+
**1.0.0 — Stable**
612+
- [ ] Frozen, documented public API
613+
- [ ] Full narrative user guide and tutorials
614+
- [ ] Deployment guide (ASGI workers, load balancer, sticky sessions, WS termination)
574615
- [ ] Devtools / inspector
575-
- [ ] Component marketplace / registry
576-
- [ ] Full user guide and tutorials
616+
617+
**Post-1.0 (deferred):** server-side change-tracked diffing, CRDT-style presence,
618+
direct-to-cloud (S3) uploads, request batching, component marketplace.
577619

578620
---
579621

@@ -596,6 +638,7 @@ Optional extras:
596638
- `[fastapi]` — FastAPI 0.109+, Uvicorn, JinjaX 0.41+
597639
- `[django]` — Django 4.2+, Django Channels 4.0+, channels-redis 4.1+, django-cotton 0.9+
598640
- `[litestar]` — Litestar 2.0+, Jinja2 3.1+
641+
- `[flask]` — Flask 3.0+
599642
- `[websockets]` — websockets 12.0+
600643
- `[all]` — all of the above
601644

‎claudedocs/dev_plan_production_grade_2026-06-24.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Development Plan — Path to Production-Grade 1.0
2+
3+
**Date:** 2026-06-24
4+
**Source:** `claudedocs/research_liveview_market_2026-06-24.md` (Tier 0–3 gap analysis)
5+
**Current version:** 0.5.0b0 · **Target:** 1.0.0 (stable, "production-grade" claim earned)
6+
7+
## Legend
8+
- **Effort:** S = ~1–2 d · M = ~3–5 d · L = ~1–2 wk · XL = multi-week
9+
- **Type:** TS = table-stakes (required to claim production-grade) · D = differentiator · ENABLER = unblocks others
10+
- **Status today:** ❌ missing · 🟡 partial/unverified (per project docs; confirm in spike E0)
11+
12+
---
13+
14+
## Milestone map
15+
16+
| Milestone | Theme | Gate it unlocks |
17+
|---|---|---|
18+
| **0.6.0b** — Hardening Foundation | Tier 0: security, rendering fidelity, verification | Trust the state; trust the DOM patch |
19+
| **0.7.0b** — Real-App Features | Tier 1: navigation, uploads, forms, realtime robustness | "Build a real app" credibility |
20+
| **0.8.0b** — Mindshare | Tier 2: observability, benchmarks, DX | Public "production-grade" claim + marketing |
21+
| **1.0.0** — Stable | API freeze, user guide, deploy guide, devtools | Frozen API + docs = 1.0 |
22+
| **post-1.0** | Tier 3 advanced (streams, presence, S3, batching) | Opportunistic |
23+
24+
---
25+
26+
## Epics & work breakdown
27+
28+
### EPIC A — State Security & Integrity *(→ 0.6.0b)*
29+
The #1 credibility/security gap: server state round-trips to the client unsigned.
30+
31+
| ID | Task | Type | Effort | Depends |
32+
|---|---|---|---|---|
33+
| A1 | **Sign serialized state (HMAC)** with a configurable secret; verify on inbound, reject tampered (`CorruptStateError`) | TS / ENABLER | M | — |
34+
| A2 | Key management + rotation story; doc "set `SECRET`/`STATE_SIGNING_KEY` per adapter" | TS | S | A1 |
35+
| A3 | `Locked`/immutable server-trusted fields (client can't mutate) | D | S | A1 |
36+
| A4 | Audit CSRF coverage across FastAPI / Litestar / Flask HTTP paths; document per-adapter; note WS CSRF limitation | TS | S | — |
37+
38+
### EPIC B — DOM Morphing & Rendering Fidelity *(→ 0.6.0b)*
39+
Foundation for navigation, forms, and optimistic UI quality.
40+
41+
| ID | Task | Type | Effort | Depends |
42+
|---|---|---|---|---|
43+
| B1 | **Adopt a morph swap** (idiomorph/morphdom) in `component-client.js` instead of innerHTML replace | TS / ENABLER | M | — |
44+
| B2 | Preserve focus / scroll / in-flight input values across patches | TS | S | B1 |
45+
| B3 | Stable list reconciliation key (`cf-key` / `data-key`) | TS | S | B1 |
46+
| B4 | "Don't morph this" escape hatch (JS-owned regions) | TS | S | B1 |
47+
| B5 | *(Spike)* Server-side change tracking (statics-once/dynamics-diff) — feasibility only; likely post-1.0 | D | M | B1 |
48+
49+
### EPIC C — Live Navigation *(→ 0.7.0b)*
50+
| ID | Task | Type | Effort | Depends |
51+
|---|---|---|---|---|
52+
| C1 | **SPA-style navigation** (intercept links/forms, swap, `pushState` history/back) | TS | L | B1 |
53+
| C2 | Loading indicator / progress bar on slow navigations | TS | S | C1 |
54+
| C3 | Scroll preservation/restoration across navigations | TS | S | C1 |
55+
| C4 | In-place param update vs full navigate distinction | D | S | C1 |
56+
| C5 | Prefetch-on-hover / persist-element / active-link | D | M | C1 |
57+
58+
### EPIC D — Forms & Uploads *(→ 0.7.0b)*
59+
| ID | Task | Type | Effort | Depends |
60+
|---|---|---|---|---|
61+
| D1 | **File uploads**: progress events, multiple files, size/type constraints, validation | TS | L | — |
62+
| D2 | On-blur / real-time partial validation without full submit | TS | M | — |
63+
| D3 | Debounce/throttle defaults on input bindings | TS | S | — |
64+
| D4 | Verify + enforce **422 re-render** convention across adapters | TS | S | E0 |
65+
| D5 | Submit-button disable/busy during in-flight | TS | S | B1 |
66+
| D6 | Form-state recovery after reconnect (`auto-recover`) | D | M | F1 |
67+
| D7 | Dirty-state indicator; drag-drop / direct-to-S3 upload | D | M | D1 |
68+
69+
### EPIC E — Realtime Robustness & Scaling *(→ 0.7.0b)*
70+
| ID | Task | Type | Effort | Depends |
71+
|---|---|---|---|---|
72+
| E0 | **Verification spike**: confirm the 🟡 rows (morph today, list keys, 422, reconnection, CSRF, partial-validation) via `/sc:analyze` over the repo | ENABLER | S | — |
73+
| F1 | Reconnection + automatic state-resync after WS drop | TS | M | A1 |
74+
| E2 | Unify WS fan-out via Redis pub/sub across adapters (not just Django) | TS-multinode | L | — |
75+
| E3 | **Flask WS/SSE parity** (Flask adapter is HTTP-only today) | TS-parity | M | — |
76+
| E4 | Cross-adapter request-parse hardening (`TypeError`→400, empty-state) — from prior review | TS | S | — |
77+
| E5 | Document stateless scaling model + sticky-session guidance | TS | S | — |
78+
| E6 | Multi-user presence (only if a stateful-WS mode is pursued) | D | XL | E2 |
79+
80+
### EPIC F — Observability & Performance *(→ 0.8.0b)*
81+
| ID | Task | Type | Effort | Depends |
82+
|---|---|---|---|---|
83+
| G1 | Telemetry: lifecycle spans (mount/handle_event/render) + timing hooks | TS | M | — |
84+
| G2 | **Published benchmarks** (latency, payload, mem/connection, concurrency) | D | M | G1 |
85+
| G3 | Lazy/deferred component loading (viewport / post-paint) | D | M | C1 |
86+
| G4 | Request batching | D | M | — |
87+
88+
### EPIC G — Developer Experience *(→ 0.8.0b / 1.0.0)*
89+
| ID | Task | Type | Effort | Depends |
90+
|---|---|---|---|---|
91+
| H1 | Declarative optimistic-JS command DSL (show/hide/toggle/transition) | D | M | B1 |
92+
| H2 | JS interop hooks w/ lifecycle + auto-reattach after swap | TS | M | B1 |
93+
| H3 | Latency simulation for dev | D | S | — |
94+
| H4 | **Devtools / inspector** (state/events/connections) | D | L | G1 |
95+
| H5 | Offline detection + visibility-throttled polling | D | M | — |
96+
97+
### EPIC H — 1.0 Readiness *(→ 1.0.0)*
98+
| ID | Task | Type | Effort | Depends |
99+
|---|---|---|---|---|
100+
| I1 | **Freeze & document the public API** (mark provisional vs stable) | TS / GATE | M | most epics |
101+
| I2 | Narrative user guide + tutorials | TS | L | — |
102+
| I3 | Deployment guide (ASGI workers, LB, WS termination, sticky sessions) | TS | M | E5 |
103+
| I4 | Graceful-degradation (no-JS / no-connection) documentation + tests | TS | S | — |
104+
105+
---
106+
107+
## Sequencing (dependency-ordered)
108+
109+
```
110+
0.6.0b ── E0 (spike) ─┬─ A1 → A2,A3 (sign state)
111+
├─ A4 (CSRF audit)
112+
└─ B1 → B2,B3,B4 (morph foundation) ▲ ENABLERS for everything below
113+
E4 (parse hardening)
114+
115+
0.7.0b ── C1 → C2,C3,C4,C5 (navigation; needs B1)
116+
D1 → D7 ; D2 ; D3 ; D4 ; D5 (forms & uploads)
117+
F1 (reconnect; needs A1) → D6
118+
E2 ; E3 ; E5 (scaling, Flask parity, docs)
119+
120+
0.8.0b ── G1 → G2 ; G3 (needs C1) ; G4 (observability/perf)
121+
H1,H2 (need B1) ; H3 ; H5 (DX)
122+
123+
1.0.0 ── I1 (API freeze; after epics) ; I2 ; I3 (needs E5) ; I4 ; H4 (devtools)
124+
125+
post-1.0 ─ B5 (server diff) ; E6 (presence) ; D7 S3 ; G4 batching (advanced/optional)
126+
```
127+
128+
## Critical path
129+
**E0 → A1 + B1** are the gating enablers. A1 (signed state) is the security gate; B1 (morph) unblocks navigation, forms fidelity, optimistic-JS, and JS hooks. Land both early in 0.6.0b.
130+
131+
## Rough effort roll-up (planning only, not a commitment)
132+
- 0.6.0b: ~3–4 wk (1 dev) — A1–A4, B1–B4, E0, E4
133+
- 0.7.0b: ~5–7 wk — C1–C3, D1–D5, F1, E2/E3/E5
134+
- 0.8.0b: ~4–5 wk — G1–G2, H1–H3, H5
135+
- 1.0.0: ~4–5 wk — I1–I4, H4
136+
- **Total to 1.0:** ~16–21 wk solo; compressible with parallelism (forms ‖ navigation ‖ observability are independent once B1 lands).
137+
138+
## Out-of-scope for 1.0 (explicit)
139+
Server-side change-tracked diffing (B5), CRDT presence (E6), direct-to-S3 (D7 part), request batching (G4). Documented as post-1.0 so the milestone stays achievable.
140+
141+
## Proposed GitHub structure
142+
- **Milestones:** `0.6.0b — Hardening`, `0.7.0b — Real-App Features`, `0.8.0b — Mindshare`, `1.0.0 — Stable`.
143+
- **Issues:** one per task ID above (~40), labeled `epic:<A–H>`, `tier:table-stakes|differentiator`, `enhancement`/`security`/`docs`. Each epic also gets a tracking issue listing its task IDs.

0 commit comments

Comments
 (0)