notid/integreat
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

docs: SSR rendering modernization rollout plan #12

Merged
notid merged 5 commits from docs/ssr-rendering-modernization-plan into staging 2026-06-02 23:26:46 -07:00
Conversation 0 Commits 5 Files Changed 1 +777
notid commented 2026-06-02 21:39:46 -07:00
Owner
Copy Link

Adds docs/plans/2026-06-02-001-refactor-ssr-rendering-modernization-plan.md — a planning doc only, no code changes.

Synthesizes three SSR refactor exercises into one systematic, low-risk rollout where each migration sharpens a skill so the next is cheaper:

  • A — HTMX swap doctrine (render-whole-form): whole-form hx-select, zero-OOB, precise local swaps; OOB reframed as a DOM-structure smell (hoist to a common ancestor instead).
  • B — Wizard architecture (critique-wizard): data-driven engine, pure render functions, server-side state for true multi-step wizards only, 4 of 9 'wizards' reclassified as plain forms.
  • C — Hiccup to Selmer templating so Alpine/HTMX attributes are first-class HTML instead of keyword/string soup.

Highlights:

  • Cross-exercise tensions resolved as explicit Decisions.
  • Code-quality ratchet: per-migration scorecard (form-cursor usage to 0, implicit merges to 0, complexity down, LOC down, reuse up, routes to 2, OOB to ~0, attr consistency).
  • Test-first strategy with an e2e regression gate (baseline 27/2).
  • Simplest-first phasing (bulk-code pilot, then normal forms, then multi-step wizards; client wizard last).
  • A self-reinforcing ssr-form-migration skill (cookbook, gotchas, test-recipes, scorecard).

Section 11 lists open decisions for review.

Generated with Claude Code

Adds docs/plans/2026-06-02-001-refactor-ssr-rendering-modernization-plan.md — a planning doc only, no code changes. Synthesizes three SSR refactor exercises into one systematic, low-risk rollout where each migration sharpens a skill so the next is cheaper: - A — HTMX swap doctrine (render-whole-form): whole-form hx-select, zero-OOB, precise local swaps; OOB reframed as a DOM-structure smell (hoist to a common ancestor instead). - B — Wizard architecture (critique-wizard): data-driven engine, pure render functions, server-side state for true multi-step wizards only, 4 of 9 'wizards' reclassified as plain forms. - C — Hiccup to Selmer templating so Alpine/HTMX attributes are first-class HTML instead of keyword/string soup. Highlights: - Cross-exercise tensions resolved as explicit Decisions. - Code-quality ratchet: per-migration scorecard (form-cursor usage to 0, implicit merges to 0, complexity down, LOC down, reuse up, routes to 2, OOB to ~0, attr consistency). - Test-first strategy with an e2e regression gate (baseline 27/2). - Simplest-first phasing (bulk-code pilot, then normal forms, then multi-step wizards; client wizard last). - A self-reinforcing ssr-form-migration skill (cookbook, gotchas, test-recipes, scorecard). Section 11 lists open decisions for review. Generated with Claude Code
notid added 1 commit 2026-06-02 21:39:47 -07:00
docs: add SSR rendering modernization rollout plan 360847fa58 
Synthesize three SSR refactor exercises into one low-risk, compounding
rollout plan: the render-whole-form HTMX swap doctrine, the critique-wizard
architecture simplification, and a Hiccup -> Selmer templating migration.

Includes a code-quality ratchet (per-migration scorecard), an explicit
test-first strategy with an e2e regression gate, simplest-first phasing, and
a self-reinforcing ssr-form-migration skill so each migration makes the next
cheaper.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
notid added 1 commit 2026-06-02 21:56:13 -07:00
docs: make SSR migration plan self-contained and executable a8d8a8d111 
Rewrite the plan to stand on its own: state the goals and target patterns
directly (illustrated with code snippets) instead of reconciling experimental
workstreams. Spell out every migration as concrete, checkboxed tasks an agent
can execute, with per-modal rationale and specifics.

Reorder so the first step distils the proven transaction-edit migration into a
ssr-form-migration skill (Phase 1), then trials that skill on the same modal as
its first test subject (Phase 2), then rolls out simplest-first with every
phase feeding the skill. Adds an explicit migration inventory, per-migration
playbook, quality scorecard, and test-first strategy.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
notid added 1 commit 2026-06-02 22:02:27 -07:00
docs: clarify cursors are fine; only faked positions are the smell 917b7f3857 
Reframe goal 2, the rationale (2.2), the render-function pattern (3.2), and
scorecard heuristic 1 so the target is top-rooted cursors. Cursors stay; what
we remove is faking a cursor to start deeper in the tree and the duplicate
*-no-cursor* variants that fakery forces.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
notid added 1 commit 2026-06-02 22:09:42 -07:00
docs: multi-step wizards use session-stored step state (Django formtools) 0e02c489e0 
Replace the EDN snapshot + piecewise merge for multi-step wizards with per-step
form state stored in the session, combined only at the end -- the Django
formtools WizardView / SessionStorage model. Cite the inspiration and refs.

Adds rationale 2.4, reworks the engine snippet in 3.3 to thread session state
keyed by wizard-id (no snapshot, no merge), and updates goal 3, the Phase 6
engine tasks, the risk row, and Open decision 1 accordingly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
notid added 1 commit 2026-06-02 23:17:54 -07:00
docs: add swap-target selector strategy consideration d360316590 
Note in 3.1 that targeted hx-select/hx-target swaps in repeated/nested
structures may want a consistent scheme -- semantic markup + data-attributes,
or a form-path->selector helper (mirroring cursors) -- instead of hand-minting
a unique id per element. Framed as a consideration for advanced cases, with a
Phase 5 task to settle the convention into the skill cookbook.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
notid merged commit 3641846f70 into staging 2026-06-02 23:26:46 -07:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
notid
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: notid/integreat#12
Delete Branch "docs/ssr-rendering-modernization-plan"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?