docs: add SOTA guidance for removing JS from dense CSS Grid implementation

docs/sota-no-js-grid.md

@@ -0,0 +1,197 @@
+<purpose>
+  Provide a state-of-the-art, production-feasible strategy to remove and purge JavaScript from the provided dynamic CSS Grid implementation while maintaining equivalent or very similar visual output and responsive behavior.
+</purpose>
+
+<context>
+  <role>
+    Documentation Analyst / Technical Revisor.
+    <tone>Formal, coherent, impersonal, and extensive.</tone>
+    <domain>Frontend Architecture and Content Rendering.</domain>
+  </role>
+
+  <input_handling>
+      [[new_raw_data]] is interpreted as the user request and the supplied HTML/CSS/JS sample. [[attachment_files]] contains no additional artifacts in this task.
+  </input_handling>
+
+  <constraints>
+    <constraint type="critical">No client-side JavaScript execution in the final rendering path.</constraint>
+    <constraint type="critical">Visual parity target: dense masonry-like packing with variable row/column spans and responsive column count.</constraint>
+    <constraint type="critical">Prefer standards-first solutions; use framework support only when it improves maintainability, not runtime dependency on browser JavaScript.</constraint>
+    <constraint type="formatting">Preserve the conceptual behavior of: random-like tile diversity, dense filling, and highlighted "new" or filler items where needed.</constraint>
+  </constraints>
+</context>
+
+<instructions>
+  <instruction step="1">STRUCTURAL MAPPING: The original implementation has fixed CSS grid rules and variable data generation/resize reconciliation performed by JavaScript.</instruction>
+
+  <instruction step="2">DATA EXTRACTION:
+    a. Core required effects: responsive auto-fit columns, variable spans (1-4), dense packing (`grid-auto-flow: dense`), and optional filler items.
+    b. Core JS-only behaviors to replace: random generation, resize-driven recomputation, and iterative empty-cell saturation.</instruction>
+
+  <instruction step="3">CONFLICT CHECK: No source conflicts were detected because only one authoritative implementation was provided.</instruction>
+
+  <instruction step="4">DRAFTING & SUBSTITUTION:
+    a. Rebuild behavior with server-side or build-time generation.
+    b. Move all randomness and saturation logic out of the browser runtime.
+    c. Keep CSS Grid as the visual engine.
+    d. Optionally use CSS-only selectors for decorative differentiation (instead of JS labels).</instruction>
+
+  <instruction step="5">LIST HANDLING:
+    a. Feasible solution tracks are listed in descending order of architectural robustness.
+    b. Framework options are listed under each track with practical adoption guidance.
+    c. Trade-offs are explicit to support implementation decisions.</instruction>
+
+  <instruction step="6">GAP FILLING: Since there are no attachments or production constraints (SEO, CMS, CDN, caching) explicitly provided, recommendations infer a typical modern web stack with CI/CD and static asset pipelines.</instruction>
+
+  <instruction step="7">DISCREPANCY REPORTING: Not applicable (no conflicting datasets).</instruction>
+
+  <instruction step="8">ANTI-RESIDUE SCAN: This document does not retain factual identifiers from the template skeleton and is fully rewritten for the current frontend architecture request.</instruction>
+</instructions>
+
+<output_format_specification>
+  <format>Markdown</format>
+  <requirements>
+    <requirement>Provide state-of-the-art approaches for JavaScript-free rendering with equivalent layout intent.</requirement>
+    <requirement>Include concrete framework families and decision criteria.</requirement>
+    <requirement>Include a migration blueprint from the provided implementation.</requirement>
+  </requirements>
+</output_format_specification>
+
+<examples>
+  <example>
+    <input_data>
+      <task_request>Remove browser JavaScript while preserving dense variable-size card grids.</task_request>
+    </input_data>
+    <output>
+      Preferred pattern: build-time/server-side tile generation + CSS Grid dense auto-placement + precomputed filler records.
+    </output>
+  </example>
+
+  <example>
+    <input_data>
+      <task_request>Keep random appearance but avoid runtime script execution.</task_request>
+    </input_data>
+    <output>
+      Use seeded pseudo-random generation on the server (or during static build) and emit deterministic class names such as `grid__item--column-span-3 grid__item--row-span-2`.
+    </output>
+  </example>
+</examples>
+
+<self_check>
+  <checklist>
+    <item>All client logic formerly handled by JavaScript is reassigned to server/build stages.</item>
+    <item>Layout parity is preserved through CSS Grid dense placement and class-based spans.</item>
+    <item>Framework recommendations avoid client JavaScript as a hard runtime dependency.</item>
+  </checklist>
+</self_check>
+
+<evaluation_notes>
+  <test_cases>
+    <case>Viewport resize with no script execution.</case>
+    <case>Dense fill persistence when content count or spans change.</case>
+    <case>Deterministic output across deployments using seeded generation.</case>
+    <case>Accessibility and source-order consistency when visual reorder occurs via dense packing.</case>
+  </test_cases>
+  <success_definition>The page renders a dense, responsive, variable-span grid without any browser JavaScript while preserving an equivalent visual impression.</success_definition>
+</evaluation_notes>
+
+<documentation>
+  <usage>
+    <step>1) Keep existing CSS Grid classes and span modifiers.</step>
+    <step>2) Generate tile records server-side/build-time (including optional filler tiles).</step>
+    <step>3) Render semantic HTML directly from templates/components.</step>
+    <step>4) Validate responsiveness using pure CSS breakpoints and container queries.</step>
+  </usage>
+  <known_limitations>
+    <limitation>Perfect geometric hole-filling in all scenarios may require precomputation complexity if exact parity with brute-force JS is required.</limitation>
+    <limitation>`grid-auto-flow: dense` may visually reorder elements relative to source order; ensure keyboard and screen-reader semantics remain correct.</limitation>
+  </known_limitations>
+</documentation>
+
+## SOTA Approach and Frameworks
+
+### 1) Primary SOTA Pattern (Recommended)
+**Server/Build-Time Layout Synthesis + Pure CSS Rendering**
+
+- Keep your existing CSS Grid model (`auto-fit`, `minmax`, span classes, dense auto-flow).
+- Replace runtime JS with a **layout compiler** that runs:
+  - at request-time (SSR), or
+  - at build-time (SSG/ISR).
+- The compiler outputs final HTML nodes with preassigned span classes.
+- Optional: precompute filler tiles so the grid appears saturated without client logic.
+
+Why this is state-of-the-art:
+- Eliminates hydration/runtime JS cost.
+- Maximizes cacheability and CDN friendliness.
+- Preserves design-system control and deterministic output.
+
+### 2) Framework Families That Fit "No Client JS"
+
+1. **Astro (SSR/SSG with islands disabled or minimal)**
+   - Strong for static-first output.
+   - Easy to emit pure HTML + CSS grids.
+   - Can run generation logic in content collections/build hooks.
+
+2. **11ty (Eleventy)**
+   - Excellent for deterministic pre-rendered HTML.
+   - Works well with Nunjucks/Liquid/Handlebars and data files.
+   - Very low runtime overhead.
+
+3. **Hugo / Jekyll / Zola**
+   - Fast static site generators.
+   - Ideal when content-driven and periodic rebuilds are acceptable.
+
+4. **Next.js / Nuxt / SvelteKit in SSR-only output mode**
+   - Use server components/SSR and avoid client-side interactive bundles.
+   - Useful when integrated backend logic is needed.
+
+5. **HTMX + server templates (optional progressive enhancement)**
+   - If future incremental updates are needed, HTMX can fetch server-rendered fragments.
+   - Still possible to keep the base page JavaScript-free if HTMX is omitted.
+
+### 3) Replacing Each JavaScript Responsibility in Your Snippet
+
+- `populateGrid(100)` -> generate records server-side:
+  - fields: `label`, `colSpan`, `rowSpan`, `isFiller`.
+- `generateRandomSizes()` -> seeded RNG on server/build:
+  - ensures reproducibility for caching and QA.
+- `fillEmptyGridCells()` -> precompute filler set during render pipeline:
+  - simple strategy: generate additional 1x1 + mixed spans until target row budget is reached.
+  - advanced strategy: bin-packing/occupancy-grid heuristic at build time.
+- `setupResizeBinding()` -> remove entirely:
+  - CSS `repeat(auto-fit, minmax(...))` and dense flow handle responsive recomposition naturally.
+
+### 4) Practical Migration Blueprint
+
+1. Keep CSS exactly (or nearly exactly) as-is.
+2. Move item generation into server/build function.
+3. Emit markup directly:
+   - `<div class="grid__item grid__item--column-span-X grid__item--row-span-Y">Item N</div>`
+4. Add filler items from backend with `grid__item--new` class if that visual distinction is needed.
+5. Validate at breakpoints (mobile/tablet/desktop) and for large datasets.
+6. Add visual regression snapshots in CI to ensure parity.
+
+### 5) If You Need Near-Perfect Hole Saturation
+
+Use a backend occupancy algorithm:
+- Represent grid as a matrix based on inferred column count at target breakpoints.
+- Place primary tiles first.
+- Backfill holes with candidate spans in descending area order, fallback to 1x1.
+- Emit per-breakpoint variants if exact parity is required for each layout width cluster.
+
+### 6) Accessibility and Content Integrity
+
+- Do not rely on visual order as reading order.
+- Keep semantic source order meaningful.
+- Avoid labeling filler as meaningful content; mark decorative fillers appropriately.
+
+### 7) Decision Matrix (Short)
+
+- **Best overall for no-JS frontend + maintainability:** Astro or 11ty.
+- **Best for enterprise SSR ecosystems:** Next.js/Nuxt in SSR-only rendering path.
+- **Best for ultra-fast static publishing:** Hugo/Zola.
+- **Best when partial dynamic updates are later required:** server templates + optional HTMX.
+
+### 8) Bottom Line
+
+Yes, it is fully feasible to purge JavaScript from this implementation and keep an equivalent visual result. The modern approach is to shift layout data synthesis to server/build time, keep CSS Grid dense behavior, and output deterministic HTML with span classes and optional precomputed filler tiles.