# Five-MDX Structure Inventory

Issue: #98

Purpose: establish the empirical ground truth for T22-T30 before changing
the parser, matcher, layout planner, slot mapper, frontend override path, or
AI adaptation path.

This inventory intentionally compares three layers:

| Column | Meaning | Gap type exposed |
|---|---|---|
| A. Original MDX contains | What the source file actually expresses | Source structure |
| B. Current pipeline sees | What the current `task21d_*` runs expose in Step 02 / Step 06 / Step 20 | Parser, normalizer, component, and planner behavior |
| C. Expected result | What the slide pipeline should preserve and render | Layout, matching, slot mapping, override, and adaptation behavior |

Source files inspected:

- `samples/mdx/01. ... .mdx`
- `samples/mdx/02. ... .mdx`
- `samples/mdx/03. ... .mdx`
- `samples/mdx/04. ... .mdx`
- `samples/mdx/05. ... .mdx`

Observed pipeline runs:

- `data/runs/task21d_01`
- `data/runs/task21d_02`
- `data/runs/task21d_03`
- `data/runs/task21d_04`
- `data/runs/task21d_05`

## MDX 01

| A. Original MDX contains | B. Current pipeline sees | C. Expected result | Gap owner |
|---|---|---|---|
| A pre-intro block before the first numbered `##` heading. It includes a details/popup block and is user-visible content. | Step 02 only emits `01-1` and `01-2`. The pre-intro has no unit id. Existing `data/user_overrides/01.json` references `01-3`, but that id is orphaned. | Promote the pre-intro into a first-class unit such as `01-intro`, or define a documented alias/migration path for the existing `01-3` override. | T22 parser/normalizer and override migration |
| `## 1` and `## 2` numbered sections. | Step 06 selects two units: `01-1 -> construction_bim_three_usage`, `01-2 -> bim_dx_comparison_table`. | Body zones should be based on the normalized section tree after the pre-intro policy is decided. | T24 layout policy |
| An image reference in section 2 and details/popup content. | Recent asset handling removes broken image icons, but popup/details semantics remain only partially represented. | Image and popup/details nodes must be explicit node types, not raw markdown leftovers. | T22 node taxonomy and T25 slot mapping |

## MDX 02

| A. Original MDX contains | B. Current pipeline sees | C. Expected result | Gap owner |
|---|---|---|---|
| `## 1` with goal content and one image. | Step 02 emits `02-1`. Step 06 selects `construction_goals_three_circle_intersection`. A user override exists for `02-1`, but frontend/runtime override behavior is not proven end-to-end. | Section `02-1` must remain independently addressable, and selected/overridden frames must render without stale preview or silent fallback. | T28 frontend override E2E |
| `## 2`, with `### 2.1` and `### 2.2`. | Step 02 emits only parent `02-2`; child headings are raw content inside the section. | `2.1` and `2.2` should become frame-internal groups under the `02-2` unit, not separate slide zones unless a layout policy explicitly asks for that. | T22/T25 |
| `<DxEffect />`, which represents the stakeholder/persona effect table in `samples/src/components/dx.astro`. | The pipeline sees an opaque component tag; persona columns are not expanded into semantic nodes. | Register `DxEffect` in a component expansion registry and expand it into persona/table nodes before matching and slot mapping. | T23 component expansion |

## MDX 03

| A. Original MDX contains | B. Current pipeline sees | C. Expected result | Gap owner |
|---|---|---|---|
| `## 1` with three conceptual groups: technology, people, and environment/nature. | Step 06 selects `three_parallel_requirements` for `03-1`. Technical text coverage is currently PASS. | Child groups should populate the internal pillar labels and body slots of the selected frame. They must not become external slide titles. | T25 slot mapping |
| `## 2` with `### 2.1` process and `### 2.2` product, including table-like content. | Step 06 selects `process_product_two_way` for `03-2`. | Process/product child groups should map to the selected two-way frame with all source atoms preserved. | T25/T27 |
| Dense content in two zones. | Presentation can still become visually dense even when technical coverage is PASS. | Fit must be solved through zone sizing, frame expansion, or layout choice, not font shrinking or text truncation. | T27 and T30 |

## MDX 04

| A. Original MDX contains | B. Current pipeline sees | C. Expected result | Gap owner |
|---|---|---|---|
| `## 1` with several perception/problem groups. | Step 06 selects `pre_construction_model_info_stacked` with a reject/provisional path. Step 20 marks design readiness as `needs_review`. | Reject/provisional candidates must remain visible as candidates, but the slide should surface that adaptation is required. | T26 candidate policy |
| `## 2` with `### 2.1` and `### 2.2`, plus details blocks. | Step 06 keeps parent `04-2` and selects `bim_issues_quadrant_four`; earlier runs showed child handling instability. | Child groups under `04-2` should become internal quadrant/list items in source order. | T25 slot mapping |
| Content is larger than the currently chosen zones in some layouts. | Technical PASS does not guarantee presentation readiness. | The system should resize/replan zones or expand frame structure. It must not shrink font size to hide overflow. | T24/T27/T30 |

## MDX 05

| A. Original MDX contains | B. Current pipeline sees | C. Expected result | Gap owner |
|---|---|---|---|
| Two top-level numbered sections, `05-1` and `05-2`. | Step 06 now emits two units, but both use `three_parallel_requirements` through `generic_fallback`. Step 20 marks design readiness as `not_ready`. | Sections must stay separated, and fallback/generic frames must be visible as not ready unless a real matching/adaptation path is used. | T24/T26 |
| `05-2` uses numeric `### 1` and `### 2` headings, not decimal `### 2.1` style headings. | These child headings are raw section content. | The contract must decide whether numeric child headings are allowed input or require MDX standardization. | T21.6/T22 |
| User-selected alternative frames can work through CLI override, but UI selection has not been proven. | `data/user_overrides/05.json` contains zone assignment but no `frames` override. | Frontend frame selection must persist `frames` and backend must apply the selected frame without stale preview or silent no-op. | T28 frontend override E2E |

## Aggregate Node Inventory

| Node type | Found in | Current state | Contract decision needed |
|---|---|---|---|
| `pre_intro` | MDX 01 | Not promoted to a unit | Allow as first-class unit or require source standardization |
| `numbered_section` | MDX 01-05 | Parsed as top-level units | Keep as the main slide-zone unit type |
| `subsection_decimal` | MDX 02, 03, 04 | Usually raw content under parent | Map to frame-internal groups unless explicitly split |
| `subsection_numeric` | MDX 05 | Raw content under parent | Decide whether allowed or normalized to decimal form |
| `component_ref` | MDX 02 `<DxEffect />` | Opaque tag | Registry-based component expansion |
| `image_ref` | MDX 01, MDX 02 | Asset copy now works for known frame images; content images still need typed handling | Explicit image node and image slot policy |
| `details_popup` | MDX 01, MDX 04 | Raw markdown/html-like content | Explicit popup/details node and presentation policy |
| `table_like_content` | MDX 01 details, MDX 02 component, MDX 03 table | Partly raw content | Explicit table/comparison nodes |
| `summary_footer` | All five MDX samples conceptually | Must stay outside body frame zones | Fixed base-slide region, not a body layout zone |

## Aggregate Gap List

| Gap | Evidence | Next task |
|---|---|---|
| Pre-intro content lacks stable unit identity | MDX 01 source has visible content before the first `##`; Step 02 emits only `01-1` and `01-2`; override references orphan `01-3` | T22 |
| Registered component expansion does not exist | MDX 02 uses `<DxEffect />`; current parser sees only the component tag | T23 |
| Child headings need frame-internal mapping | MDX 02/03/04/05 child headings remain raw content or map inconsistently | T25 |
| Generic fallback can be technically PASS but design-not-ready | MDX 05 uses `generic_fallback` for both units | T26/T30 |
| Frontend override persistence is not proven | MDX 05 override JSON has no `frames`; CLI override works separately | T28 |
| Fit is still a structure/layout problem, not a font problem | MDX 03/04 can be dense; policy forbids font shrinking | T24/T27/T30 |

## Immediate Contract Decisions For T21.6

1. Unit identity policy:
   - Prefer stable explicit ids such as `01-intro`, not implicit renumbering.
   - Existing user override aliases such as `01-3` need a tested migration or compatibility rule.
2. Component registry:
   - Start with `DxEffect`.
   - New components must be added through registry entries, not one-off parser branches.
3. Child-section policy:
   - Top-level `## n.` sections map to body zones.
   - Child headings map to internal frame slots by default.
4. Allowed input policy:
   - `## n. Title` is allowed.
   - Registered component tags are allowed.
   - Unregistered component tags are unsupported.
   - Raw JSX/style blobs are disallowed in rendered text and must be sanitized or rejected.
5. Coverage-state policy:
   - `covered_native`: current frame and builder can render source atoms verbatim.
   - `covered_via_expand`: current frame can render after deterministic repeat/expand.
   - `requires_adaptation`: visual motif is usable, but an adapted schema is needed.
   - `unsupported`: no current contract path; must be surfaced honestly.