World-Class Module Plan — gallery + FES

**Date**: 2026-08-26 21:55 UTC

**Author**: Mavis (helper-mavis, id 10, session 412100071272671)

**Inputs**: a753 (research_v001, 334KB), a756 (research_v002, 402KB), a761 (synthesis_v002, 58KB), `fv-cms-vendored/` (FvCMS 1.2.0 audit), `c8b2af3` gallery state

**Status**: PLAN ONLY — no module files written, no schema changes, no pushes

---

0. Source-of-truth chain (no memory assumptions, all receipts cited)

| What | Where | Size | Status |

|---|---|---|---|

| App-Builder Landscape Audit v001 | a753 (research_v001) | 334,523 bytes | retrieved from CDN, preserved at `/workspace/audits/a753-...html` |

| App-Builder Landscape Audit v002 | a756 (research_v002) | 402,910 bytes | retrieved, preserved at `/workspace/audits/a756-...html` |

| Module Universe Synthesis v002 | a761 (synthesis_v002) | 58,248 bytes | retrieved, preserved, **this is the canonical 93-role universe** |

| Task A spec (post-pull gallery) | a774 | 26,723 bytes | local + HQ |

| FES audit (this arc) | `/workspace/FES-AUDIT-2026-08-26.md` | 21,794 bytes | NEW, this turn |

| FvCMS vendored runtime | `fv-cms-vendored/` | 16 modules, 24 controls, 9 panels | vendored 2026-08-05 |

The App-Builder Landscape (a761) is **constitutional** per §3 FES MANDATORY CLAUSE (operator 2026-08-24 17:24). It defines 93 roles, 11 UI primitives, 6 behavior matrices, 15 canonical packs. The FES audit determines what FES + gallery can dispatch today. The plan combines both into the world-class target.

---

1. The two north stars (per App-Builder Landscape §3.13)

The "world-class" set, per a761's canonical 15:

1. **heading** — text content ✓

2. **text** (gallery: paragraph) — text content ✓

3. **image** — media ✓

4. **icon** — content ✗ MISSING

5. **button** — CTA ✓

6. **tabs** — structural ✗ MISSING

7. **accordion** — structural ✓

8. **modal** — structural ✗ MISSING

9. **form** — form, 50+ field types ✗ MISSING

10. **gallery** — media ✗ MISSING

11. **query-loop** — dynamic ✗ MISSING

12. **pricing-table** — marketing ✗ MISSING

13. **testimonial** — marketing ✓

14. **video** — media ✓

15. **map** — media ✗ MISSING

**Current: 7/15 canonical. Target: 15/15. Gap: 8 modules.**

---

2. The dispatch analysis (FES audit §10, restated for plan)

What FES dispatches today (16 modules, all 16 in gallery, all 16 in renderer)

accordion, breadcrumb, button, carousel, contact-form, cta, cta-box, heading, icon-list, image, info-box, menu, paragraph, social-icons, testimonial, video

What App-Builder Landscape says FES should dispatch (15 canonical + 78 non-canonical = 93)

Add the 8 missing canonical (icon, tabs, modal, form, gallery, query-loop, pricing-table, map) and 75 non-canonical (full taxonomy in a761 §3).

What's already in the gallery but NOT dispatched by FES

**Zero.** The gallery's 16 modules are an exact 1:1 with FES dispatch. No orphans in either direction. **Gallery and FES are in lockstep today.** This is a clean state to grow from.

---

3. The world-class module plan

Tier 1 — Canonical 8 (must add, in priority order)

These are the 8 missing canonical modules. Build order based on (a) frequency in real Elementor/EAEL sites, (b) build complexity, (c) downstream unlocks.

| # | Module ID (schema) | Runtime ID | FES source widget | Build complexity | Unlocks | Est. lines |

|---|---|---|---|---|---|---|

| 1 | `icon` | M-icon | `icon` (Elementor core) | LOW | Picker UI, sizing, link, 6 variants | 200-300 |

| 2 | `divider` | M-divider | `divider` (Elementor core) | LOW | Trivial horizontal rule primitive | 80-120 |

| 3 | `spacer` | M-spacer | `spacer` (Elementor core) | LOW | Trivial vertical/horizontal space | 60-100 |

| 4 | `tabs` | M-tabs | `tabs` (Elementor core) | MEDIUM | Tab triggers, panels, keyboard nav, URL hash sync | 350-500 |

| 5 | `modal` | M-modal | (new) | MEDIUM | Trigger pattern, focus trap, ESC dismiss, scroll lock | 400-600 |

| 6 | `map` | M-map | (new) | MEDIUM | Embed providers (OSM/Mapbox/Google), lat/lng/address, marker | 400-600 |

| 7 | `pricing-table` | M-pricing-table | eael-pricing-table | MEDIUM | Tiers, features list, highlight, CTA, 6 variants | 500-700 |

| 8 | `gallery` | M-gallery | `basic-gallery`, `image-gallery` (Elementor core) | HIGH | Lightbox, masonry, slideshow, captions, 6 variants | 700-1000 |

| 9 | `form` (superset) | M-form | `form`, `eael-weform`, `eael-fluentform` (already dispatch to M-contact-form, superset this) | HIGH | 50+ field types, 30+ actions, 3-level conditional, multi-step | 1500-2500 |

| 10 | `query-loop` | M-query-loop | `loop-grid`, `loop-carousel`, archive-* | HIGH | Query args, template, pagination, 8 variants | 800-1200 |

**Tier 1 total**: 10 modules, ~5000-7500 lines of code (FES pack shape: 11 files per module × 10 = 110 files).

Tier 2 — High-frequency (real-site coverage, 6 modules)

For Oscar / Hopfan-class sites, these widgets appear often. Add after Tier 1 lands.

| # | Module | Elementor widget | Build | Unlocks |

|---|---|---|---|---|

| 11 | `counter` | `counter` | LOW | Data viz entry, 4 variants |

| 12 | `progress-bar` | `progress-bar`, eael-progress-bar | LOW | Data viz, 4 variants |

| 13 | `data-table` | eael-table, `table` | MEDIUM | Tabular data, 4 variants |

| 14 | `timeline` | eael-timeline, `timeline` | MEDIUM | Process content, 4 variants |

| 15 | `lottie` | (new, or Elementor Pro) | MEDIUM | Animation primitive, 2 variants |

| 16 | `marquee` | (new) | MEDIUM | Engagement, 4 variants |

| 17 | `star-rating` | `star-rating` | LOW | Reviews, 2 variants |

**Tier 2 total**: 7 modules, ~2000-3000 lines.

Tier 3 — Layout primitives (10 modules, the region creator surface)

The biggest miss per the FES audit. No layouts in FES today. The detector reads `.e-con` as regions but doesn't expose layout as a dispatchable module.

| # | Module | Purpose | Build |

|---|---|---|---|

| 18 | `section` | Top-level region (full width vs boxed) | LOW |

| 19 | `container` | Block-level region (max-width + padding) | LOW |

| 20 | `column` | Vertical layout (flex column) | LOW |

| 21 | `row` | Horizontal layout (flex row) | LOW |

| 22 | `grid` | CSS grid wrapper (12-col) | MEDIUM |

| 23 | `stack` | Vertical flex with gap | LOW |

| 24 | `block` | Generic block (div + class) | LOW |

| 25 | `header` | Theme header (sticky + nav slot) | MEDIUM |

| 26 | `footer` | Theme footer (3-col + copyright) | MEDIUM |

| 27 | `divider-section` | Section-level shape divider | LOW |

**Tier 3 total**: 10 modules, ~1500-2500 lines.

Tier 4 — Marketing (6 modules)

Per a761 §3.9. The 9 marketing roles not in FES today.

| # | Module | Build |

|---|---|---|

| 28 | `banner` | MEDIUM |

| 29 | `testimonial-grid` | MEDIUM |

| 30 | `testimonial-carousel` | MEDIUM |

| 31 | `team-member` | LOW |

| 32 | `team-grid` | MEDIUM |

| 33 | `logo-grid` | MEDIUM |

| 34 | `logo-carousel` | MEDIUM |

**Tier 4 total**: 7 modules, ~1500-2000 lines.

Tier 5 — Engagement (5 modules)

Per a761 §3.10. The "site utility" set — what every site needs but rarely builds.

| # | Module | Build |

|---|---|---|

| 35 | `cookie-consent` | MEDIUM |

| 36 | `reading-progress` | LOW |

| 37 | `scroll-to-top` | LOW |

| 38 | `coming-soon` | MEDIUM |

| 39 | `maintenance` | LOW |

**Tier 5 total**: 5 modules, ~800-1200 lines.

Tier 6 — Interactive (5 modules)

Per a761 §3.6. Image-driven interaction patterns.

| # | Module | Build |

|---|---|---|

| 40 | `image-compare` | MEDIUM |

| 41 | `image-hotspot` | MEDIUM |

| 42 | `image-mask` | MEDIUM |

| 43 | `flip-box` | MEDIUM |

| 44 | `call-to-action` (vs M-cta-box) | LOW |

**Tier 6 total**: 5 modules, ~1000-1500 lines.

Tier 7 — Dynamic content (10 modules)

Per a761 §3.4. The post-grid family. Most need `query-loop` as foundation (build #10 first).

| # | Module | Build |

|---|---|---|

| 45 | `post-grid` | MEDIUM (uses M-query-loop) |

| 46 | `post-carousel` | MEDIUM (uses M-query-loop) |

| 47 | `post-list` | LOW (uses M-query-loop) |

| 48 | `product-grid` | MEDIUM (uses M-query-loop) |

| 49 | `product-carousel` | MEDIUM (uses M-query-loop) |

| 50 | `archive` | MEDIUM (uses M-query-loop) |

| 51 | `single-field` | LOW (uses M-query-loop) |

| 52 | `single-product` | MEDIUM (uses M-query-loop) |

| 53 | `user-author` | LOW (uses M-query-loop) |

| 54 | `glossary` | LOW (uses M-query-loop) |

**Tier 7 total**: 10 modules, ~1500-2500 lines (most are thin skins on M-query-loop).

Tier 8 — WooCommerce (5 modules, scope-gated)

Per a761 §3.11. Only if/when WooCommerce scope is in.

| # | Module | Build |

|---|---|---|

| 55 | `product-single` | MEDIUM |

| 56 | `cart` | MEDIUM |

| 57 | `checkout` | MEDIUM |

| 58 | `my-account` | MEDIUM |

| 59 | `mini-cart` | MEDIUM |

**Tier 8 total**: 5 modules, ~1500-2000 lines.

---

4. Plan summary (totals)

| Tier | Modules | Est. lines | Build order |

|---|---|---|---|

| 1 — Canonical 8 (must) | 10 | 5,000-7,500 | build #1-10 first |

| 2 — High-frequency | 7 | 2,000-3,000 | after Tier 1 |

| 3 — Layout primitives | 10 | 1,500-2,500 | after Tier 1 |

| 4 — Marketing | 7 | 1,500-2,000 | after Tier 2 |

| 5 — Engagement | 5 | 800-1,200 | parallel with Tier 2 |

| 6 — Interactive | 5 | 1,000-1,500 | parallel with Tier 2 |

| 7 — Dynamic content (on M-query-loop) | 10 | 1,500-2,500 | after Tier 1 #10 |

| 8 — WooCommerce (scope-gated) | 5 | 1,500-2,000 | after Tier 1, if Woo scope |

| **Total world-class target** | **59 new modules** | **~14,000-22,000 lines** | |

Plus the schema expansion (Tier 4 of FES audit):

• responsive.json (per-module)

• conditions.json (per-module)

• dynamic.json (per-module)

• interactions.json (per-module)

• edge.json (per-module)

**Plus the detector expansion** (35+ Elementor widget handlers, see FES audit §6).

---

5. The 16 modules FES can dispatch TODAY (no work needed)

These are the 16 the inspector already understands. They can be used in real Oscar / Hopfan dist content. **No upgrade needed.**

| M- | Schema | Source widget | What it does today |

|---|---|---|---|

| M-heading | heading | heading, animated-headline | 8 levels of headings, animated text effect |

| M-paragraph | paragraph | text-editor | Rich text body |

| M-image | image | image, eael-image | Image with alt, link, caption, aspect |

| M-button | button | button, eael-creative-button | CTA button with icon, variant, size |

| M-accordion | accordion | eael-adv-accordion, eael-toggle | Expandable sections, multi-open |

| M-breadcrumb | breadcrumb | eael-breadcrumbs | Path navigation |

| M-testimonial | testimonial | premium-addon-testimonials, eael-testimonial | Quote + author + rating |

| M-video | video | video, eael-video | YouTube/Vimeo/file video, poster, autoplay |

| M-cta | cta | (same as button) | CTA — actually duplicates M-button in detector |

| M-cta-box | cta-box | eael-cta-box | Title + body + button card |

| M-icon-list | icon-list | icon-list | Bulleted list with leading icon |

| M-info-box | info-box | eael-info-box | Icon + title + body card |

| M-menu | menu | eael-simple-menu | Nav menu (horizontal/vertical) |

| M-social-icons | social-icons | social-icons | 14 platform icons + links |

| M-carousel | carousel | eael-post-carousel, eael-team-member-carousel, eael-stacked-cards | Sliding card carousel |

| M-contact-form | contact-form | form, eael-weform, eael-fluentform | Generic form (3 fields, no multi-step) |

**For Hopfan e2e, these 16 will cover maybe 40-50% of the actual content**. The rest (gallery, tabs, modal, map, pricing-table, query-loop, form-superset, icon, divider, spacer) will silently fall to `default: null` in the detector.

---

6. The 8 modules that need UPGRADES (already in gallery, but need re-work)

Wait — gallery and FES are in lockstep. So no upgrades needed in the literal sense. The 8 canonical missing are NEW modules, not upgrades.

**However**, two of the 16 need attention:

| M- | Issue | Recommendation |

|---|---|---|

| M-cta | Detector dispatches `button`/`eael-creative-button` to BOTH M-cta AND M-button. Duplicate. | De-duplicate: button-only → M-button, cta-class only → M-cta. Or merge M-cta into M-button (simpler). |

| M-contact-form | Generic 3-field default. Doesn't model the 50+ field types from A761 §3.5. | Build M-form as a superset (Tier 1 #9), keep M-contact-form as a thin alias for back-compat. |

---

7. The 35 new modules that must be DESIGNED (Tier 1-8, no recipes exist)

Of the 59 total, 35 are net-new with no scaffold anywhere. The other 24 are either "rename" (e.g. M-icon-list already exists, M-icon is new) or "superset" (M-contact-form → M-form).

The 35 net-new:

• Tier 1: icon, divider, spacer, tabs, modal, map, pricing-table, gallery, form, query-loop (10)

• Tier 2: counter, progress-bar, data-table, timeline, lottie, marquee, star-rating (7)

• Tier 3: section, container, column, row, grid, stack, block, header, footer, divider-section (10)

• Tier 4: banner, testimonial-grid, testimonial-carousel, team-member, team-grid, logo-grid, logo-carousel (7)

• Tier 5: cookie-consent, reading-progress, scroll-to-top, coming-soon, maintenance (5)

• Tier 6: image-compare, image-hotspot, image-mask, flip-box, call-to-action (5)

• Tier 7: post-grid, post-carousel, post-list, product-grid, product-carousel, archive, single-field, single-product, user-author, glossary (10)

• Tier 8: product-single, cart, checkout, my-account, mini-cart (5)

Wait — that's 59. Net-new = 59, all need design. The "upgrade" of M-cta (de-dup) and M-contact-form → M-form is in the "upgrade" column but really is a re-design.

---

8. The schema expansion (5 new files per module)

The App-Builder Landscape §2.3 specifies 11 files per pack:

• fes.json, inspector.json, renderer.html, renderer.css, renderer.js, dynamic.json, responsive.json, conditions.json, edge.json, tests.json, meta.json

**Today, gallery modules have**: module.json, module-meta.json, recipe.md, codex.md, rules.md, plan.md, coverage-matrix.md, ingredients.json, src/widget.js, visual/.

**Missing from gallery**: fes.json (the contract per A761), inspector.json (the inspector UI), dynamic.json, responsive.json, conditions.json, edge.json, tests.json, renderer.{html,css,js} (per A761 the renderer is the editor-delegated thing — FvCMS owns this).

**Schema expansion per new module**: add 4 new JSON files to the pack:

• `responsive.json` (5 breakpoints, container queries, per-device overrides)

• `conditions.json` (16 sources, 16 operators, 3-level nesting)

• `dynamic.json` (60+ sources, 6 format types)

• `edge.json` (100+ edge cases with mitigations)

Plus the existing files: module.json (extend with `fes_compliance` block), module-meta.json (extend with `pack_id`, `fes_version`), ingredients.json (extend with `fes_primitives_used`).

The schema expansion is **independent of the module count** — same 4 files added to every new pack.

---

9. The detector expansion (35+ widget handlers)

The current detector handles 23 Elementor widget types. The expansion list (from FES audit §6 Tier 3) is 35+ widget types. Each new detector handler is ~10-30 lines + config extractor.

**Estimate**: 35 handlers × 25 lines avg = ~900 lines of detector code. Plus the config extractors for the new fields (carousel items, post query, gallery image list, etc.) — maybe another 500 lines.

**Total detector work**: ~1500 lines.

---

10. The inspector control set

The 24 controls (FES audit §4c) cover all 16 current modules' fieldSchemas. For the new Tier 1 modules:

| New module | New control type needed? |

|---|---|

| M-icon | `icon-picker` (existing: pills + tags can fake it; new control worth ~150 lines) |

| M-tabs | No new control (text × N rows + pills for icon) |

| M-modal | No new control (existing: text, textarea, color, dimension) |

| M-map | `lat-lng` (new control, ~200 lines) OR text + lat/lng regex parsing |

| M-pricing-table | No new control (repeater pattern via tags control + nested fields) |

| M-gallery | `gallery` (image picker with multi-select, ~250 lines) |

| M-form | `form-field-builder` (composite control, ~600 lines) — biggest new control |

| M-query-loop | `query-builder` (composite control, ~700 lines) — second biggest |

| M-divider | No new control (color, dimension, dropdown for style) |

| M-spacer | No new control (dimension only) |

**New inspector controls needed**: 4 (icon-picker, lat-lng, gallery, form-field-builder, query-builder = 5). Total ~1900 lines.

---

11. Build sequence (the path forward)

Phase 1: Tier 1 (canonical 8 missing) — 4 weeks of focused work

Week 1: icon, divider, spacer (3 trivial) + map (medium) = 4 modules, ~1000 lines + 2 new inspector controls (icon-picker, lat-lng) ~350 lines

Week 2: tabs, modal (2 medium) = 2 modules, ~1000 lines

Week 3: pricing-table, gallery (1 medium, 1 high) = 2 modules, ~1500 lines + gallery control ~250 lines

Week 4: form (superset), query-loop (2 high) = 2 modules, ~3000 lines + 2 new inspector controls ~1300 lines

**End of Phase 1**: 10 new modules. Gallery: 26 modules. FES dispatch: 26. A761 canonical: 15/15 (100%).

Phase 2: Tier 2 + 3 — 2 weeks

Week 5: 7 Tier 2 modules (counter, progress-bar, data-table, timeline, lottie, marquee, star-rating) + detector expansion (15 new widget handlers) = ~3500 lines

Week 6: 10 Tier 3 layout modules (section, container, column, row, grid, stack, block, header, footer, divider-section) = ~2000 lines

**End of Phase 2**: 17 new modules. Gallery: 43 modules. FES dispatch: 43. A761 coverage: 43/93 (46%).

Phase 3: Tier 4 + 5 + 6 — 2 weeks

Weeks 7-8: 7 + 5 + 5 = 17 modules in marketing/engagement/interactive. ~3500 lines.

**End of Phase 3**: 17 new modules. Gallery: 60 modules. FES dispatch: 60. A761 coverage: 60/93 (65%).

Phase 4: Tier 7 (dynamic content) — 1 week

Week 9: 10 dynamic modules on top of M-query-loop. ~2000 lines.

**End of Phase 4**: Gallery: 70 modules. FES dispatch: 70. A761 coverage: 70/93 (75%).

Phase 5: Tier 8 (WooCommerce, scope-gated)

Conditional on operator confirming Woo scope. If yes: 5 modules, ~1500 lines, +1 week.

**End of Phase 5**: Gallery: 75 modules. FES dispatch: 75. A761 coverage: 75/93 (81%).

Phase 6: Schema + matrix coverage

Add responsive.json, conditions.json, dynamic.json, interactions.json, edge.json to all 75 modules. +5 files × 75 = 375 new files, ~20 lines avg = ~7500 lines of JSON.

**Total world-class target**: 75 modules, ~25,000-35,000 lines of code, 5-6 weeks of focused build time.

---

12. What's NOT in this plan (scope-locked)

• **Visual contract (F11 capture)** — deferred per HQ 769, not in this arc

• **State captures, breakpoint captures, manifest.json** — per a761 §12, deferred

• **FES v1 → v2 doctrine bump** — per a761 §11.10, deferred

• **Visual determinism tests, 12-year-old test** — deferred

• **The "m-prefix-convention.md" doc** — id 8's to write, not mine

• **The 7 open Q from the spec** — separate decision card

---

13. Decision points (the operator must answer)

The plan has 3 binary decisions that block the build:

D1 — Do we build Tier 1 (canonical 8) immediately, or scope down?

**Option A (full Tier 1)**: 4 weeks, 10 new modules, 15/15 canonical. FES becomes "world-class" by A761 standard.

**Option B (canonical 8 only, skip form + query-loop)**: 2 weeks, 8 modules, 13/15 canonical. Form is hard.

**Option C (canonical 8 only, skip form + query-loop + gallery)**: 1 week, 7 modules, 12/15 canonical. Pragmatic.

**Option D (no build, just plan)**: this doc IS the deliverable; no code yet.

D2 — Do we expand the detector (35+ new widget handlers)?

**Option A (yes, full)**: ~1500 lines of detector, ~19% → ~60% Elementor coverage. Real Oscar/Hopfan sites start working.

**Option B (yes, EAEL only)**: ~700 lines, ~19% → ~40% coverage. EAEL is the common one.

**Option C (no)**: detector stays at 23 widgets, FES dispatch list stays 16.

D3 — Do we add the 5 new inspector controls?

**Option A (all 5)**: icon-picker, lat-lng, gallery, form-field-builder, query-builder. ~1900 lines. Unlocks the new modules.

**Option B (3 of 5 — icon, lat-lng, gallery)**: ~700 lines. Tier 1 builds with controls. form + query-loop still need control work later.

**Option C (none)**: new modules must be edited via JSON / text field. Inspector UX drops.

---

14. Recommended path

**Recommended**: D1-A + D2-B + D3-B. Total: 4 weeks Tier 1 + 1 week detector + 1 week controls = 6 weeks. Gallery reaches 26 modules + 8 canonical. FES dispatch reaches 26. Detector covers EAEL + standard core. Inspector can edit the new modules.

The other 9 canonical + 67 non-canonical can come in Phase 2-5 after the canonical 8 land and operator confirms the trajectory.

**Pre-build prerequisites**:

1. Operator answers the 7 open Q (separate decision card)

2. Operator picks D1/D2/D3 above

3. Worktree created on `feat/world-class-modules` branch (NOT main, per a643)

4. Per-module build plan files in `cms-widgets/<name>/plan.md` BEFORE any code

5. Each module gets the FES audit + the App-Builder Landscape entry as input

---

15. Out of scope (R-117 reminder)

This plan is **planning**, not building. Per the operator directive 2026-08-26 23:50: "Do not build modules yet — only produce the plan."

**R-117 application**: this plan is "packaged" not "proven". The world-class target is ~25K-35K lines of code. Until that code is shipped, end-to-end tested on Oscar / Hopfan, and verified to dispatch correctly, the plan remains UNVERIFIED PLANNING.

The first build (Tier 1 #1, M-icon) is the canary. If M-icon ships, dispatches in the inspector, renders the Elementor icon widget correctly, and survives a F11 visual capture, the plan is valid. If not, the plan needs revision.

---

— Mavis (helper-mavis, id 10, session 412100071272671)

2026-08-26 22:00 UTC