html-transform/TODO.md

TODO

Improve .ht Layout Evidence

Current scan evidence is useful for finding page structure, labels, inputs, buttons, tables, screenshots, and app-map hints, but it is still too weak as an implementation constraint for visual layout.

Observed problem:

• Generated Vue/Vuetify pages can preserve fields, buttons, routes, and APIs while drifting far from prototype layout.
• Reports may pass pages because functional elements exist, even when form density, alignment, spacing, table structure, and first-screen information density are wrong.
• desktop-default.png contains this evidence visually, but the generated JSON/Markdown artifacts do not expose enough layout metrics for deterministic checks.

Future work:

• Capture bounding boxes for important visible elements:
  • headings
  • labels
  • inputs/selects/textareas
  • buttons/links
  • tables
  • section containers
• Group form fields into likely rows and columns using bounding boxes.
• Detect table/list layout:
  • table count
  • table order
  • header labels
  • whether multiple tables are stacked vertically
• Capture first-viewport density:
  • visible section count
  • visible form field count
  • visible table/header count
  • approximate occupied content area
• Emit layout hints into .ht/spec/{page}.spec.json, for example:
  • layoutEvidence.sections
  • layoutEvidence.formRows
  • layoutEvidence.tables
  • layoutEvidence.primaryActions
  • layoutEvidence.firstViewport
• Render layout hints into .ht/spec/{page}.ui-contract.md so LLMs see layout constraints without manually inferring everything from screenshots.
• Add validation warnings for likely layout-critical structures:
  • stacked tables
  • dense row-based forms
  • query toolbar with adjacent submit button
  • multi-row detail tables

Non-goals:

• Do not require pixel-perfect HTML/JSP reproduction.
• Do not copy legacy CSS.
• Do not encode exact colors/fonts as hard constraints unless needed for functional recognition.

Goal:

• Preserve information architecture, form density, field alignment, table/list relationships, and operation flow while still allowing a modern Vue/Vuetify implementation.