galaxy/specs/zachlloyd/markdown-table-consistency/TECH.md

# Markdown Table Styling Consistency — Tech Spec
Product spec: `specs/zachlloyd/markdown-table-consistency/PRODUCT.md`

## Problem
PR #23908 updated AI block list Markdown tables to the new blockless visual treatment, but the rest of Warp’s Markdown table renderers still use the older boxed table styling. On the current branch, Markdown table appearance is owned by two separate rendering paths:

- editor-backed Markdown surfaces use `RichTextStyles.table_style`
- AI block list tables build a separate WarpUI `TableConfig` inline

That split creates two technical problems:

1. the shared editor-backed renderer still paints outer borders, vertical dividers, filled header backgrounds, and alternating row backgrounds
2. future surfaces can drift again because there is no single shared source for Markdown table chrome

The implementation should make every current Markdown table renderer inherit the same structural style while preserving surface-specific typography and existing editing/selection behavior.

## Relevant code
- `specs/zachlloyd/markdown-table-consistency/PRODUCT.md` — approved product behavior
- `specs/blocklist-markdown-table-rendering/TECH.md` — prior AI block list table implementation plan
- `app/src/notebooks/editor/mod.rs (145-215)` — `rich_text_styles`; current shared editor-backed table style source
- `crates/editor/src/render/model/mod.rs (424-568)` — `RichTextStyles` and `TableStyle`
- `crates/editor/src/render/element/table.rs:1-220` — editor-backed Markdown table painting path
- `app/src/ai/blocklist/block/view_impl/common.rs (1140-1270)` — `render_table_section`; current AI block list table renderer and inline `TableConfig`
- `crates/warpui_core/src/elements/table/mod.rs (117-239)` — shared `TableConfig`, `RowBackground`, and `TableVerticalSizing`
- `crates/warpui_core/src/elements/table/mod.rs (537-759)` — intrinsic width measurement logic
- `crates/warpui_core/src/elements/table/mod.rs (1013-1211)` — viewported row layout and painting behavior
- `app/src/notebooks/file/mod.rs (230-278)` — file notebook view using `rich_text_styles`
- `app/src/ai/ai_document_view.rs (292-321)` — AI document view fallback editor using `rich_text_styles`
- `app/src/ai/document/ai_document_model.rs (783-801)` — AI document model creating notebook-backed editors with `rich_text_styles`
- `app/src/code/editor/comment_editor.rs (505-544)` — comment editor using `rich_text_styles`
- `app/src/code/editor/view.rs (2357-2381)` — `code_text_styles`; clones `rich_text_styles` before overriding non-table text settings

## Current state

### Editor-backed Markdown tables
Most rendered Markdown surfaces in the app are backed by `NotebooksEditorModel` and the shared editor renderer. Their table appearance comes from `rich_text_styles()` in `app/src/notebooks/editor/mod.rs`, which currently sets:

- `border_color = theme.surface_3()`
- `header_background = theme.surface_2()`
- `cell_background = theme.background()`
- `alternate_row_background = Some(theme.surface_2())`
- `cell_padding = 6.`

That style is then consumed by `RenderableTable` in `crates/editor/src/render/element/table.rs`. The renderer currently always paints:

- row backgrounds for header and body
- an outer top/bottom/left/right border
- horizontal row dividers
- vertical column dividers

This is the old notebook/editor table treatment that the new product spec wants to replace.

### Surfaces that inherit the editor-backed table style
The old table style is not limited to notebooks. The same `rich_text_styles()` entry point is reused by multiple surfaces:

- notebooks
- file notebooks
- AI documents / planning docs
- Markdown comment editors

In addition, `code_text_styles()` starts from `rich_text_styles()` before overriding paragraph-level settings, so any code-editor surface that ends up rendering Markdown tables also inherits the same table style unless it explicitly overrides it.

This means a change to the shared editor-backed style source will propagate to multiple surfaces automatically.

### AI block list tables
The AI block list no longer uses the old style. `render_table_section()` in `app/src/ai/blocklist/block/view_impl/common.rs` builds a WarpUI `Table` with an inline `TableConfig` that already matches the desired structural treatment:

- `outer_border: false`
- `column_dividers: false`
- `row_dividers: true`
- transparent header/background fills
- `cell_padding: 12.`
- `TableVerticalSizing::ExpandToContent`
- `measure_body_cells_for_intrinsic_widths: true`

That renderer is already the visual baseline from PR #23908, but it is defined inline inside the block list path rather than shared with editor-backed renderers.

### Ownership problem
Today there is no shared “Markdown table appearance” abstraction. The editor-backed path and block list path both describe the same visual decisions in different structures:

- `TableStyle` for the editor renderer
- `TableConfig` plus per-cell text styling for WarpUI `Table`

As a result:

- the two renderers can drift
- future surfaces may pick one path and forget to copy the latest style
- structural decisions like “no outer border” or “no column dividers” are not represented in the editor-backed style model yet

## Proposed changes

### 1. Introduce a shared Markdown table appearance helper
Add a small shared helper at the app layer that defines the canonical Markdown table chrome for the new blockless treatment.

The helper should represent the structural and color decisions that must stay aligned across renderers:

- divider color
- header text color
- body text color
- transparent vs filled backgrounds
- whether outer borders are shown
- whether column dividers are shown
- whether row dividers are shown
- row striping behavior
- cell padding

Typography should remain surface-specific. The helper should define the table chrome and text-color hierarchy, not force every surface to use the same font family or font size.

This gives us one source of truth that both renderers can map from.

### 2. Extend `TableStyle` so the editor renderer can express the blockless treatment
`crates/editor/src/render/model/mod.rs` currently cannot represent some of the structural choices already used by the block list renderer.

Extend `TableStyle` with the missing structural controls needed by the product spec:

- `outer_border: bool`
- `column_dividers: bool`
- `row_dividers: bool`

Keep the existing color and typography fields. The important change is letting the editor-backed renderer express “only horizontal separators, no outer border, no vertical dividers” directly instead of baking those assumptions into painting logic.

### 3. Update the editor-backed table painter to honor the expanded style model
Update `crates/editor/src/render/element/table.rs` so painting follows `TableStyle` rather than hardcoded table chrome assumptions.

Specifically:

- `paint_backgrounds()` should respect transparent header/body backgrounds and the absence of alternating row backgrounds
- `paint_borders()` should paint only the borders/dividers enabled by `TableStyle`
- the renderer should continue using the existing text layout, selection, cursor, and alignment logic unchanged

This keeps the behavioral parts of the editor renderer stable while changing only the visual treatment.

### 4. Make `rich_text_styles()` produce the new Markdown table style
Update `app/src/notebooks/editor/mod.rs` so `rich_text_styles()` returns the blockless Markdown table style from the new shared helper.

That means the shared editor-backed path should move from the current boxed style to:

- no outer border
- no column dividers
- row dividers only
- transparent header background
- transparent body background
- no alternating row backgrounds
- header/body text colors matching the block list hierarchy
- cell padding aligned with the block list treatment

This change is the main propagation point for notebooks, file notebooks, AI documents, comment editors, and any other surface using the shared editor-backed Markdown renderer.

### 5. Refactor the block list table renderer to consume the same shared appearance helper
Update `app/src/ai/blocklist/block/view_impl/common.rs` so the block list no longer constructs its structural table chrome entirely inline.

The block list should still keep its surface-specific text settings where needed:

- AI font family
- AI font size
- AI font weight
- AI selection color

But the structural table configuration should come from the same shared appearance helper used by `rich_text_styles()`. That keeps the existing block list result visually unchanged while preventing future drift.

### 6. Preserve surface-specific typography
The product goal is shared styling, not identical typography across unrelated surfaces.

The shared appearance helper should therefore be mapped differently by each renderer:

- editor-backed surfaces continue using their surface’s `font_family` / `font_size` in `TableStyle`
- block list continues using its AI-output text settings

What must remain shared is the blockless table chrome and the text hierarchy relationship, not every literal font token.

### 7. Treat the shared helper as the default for future Markdown table renderers
Document in the code by naming and placement that this helper is the default source for Markdown table appearance in Warp.

The goal is that a new Markdown-rendering surface should not invent its own `TableConfig` or `TableStyle` values for tables unless it has a clear product reason to diverge.

## End-to-end flow
1. A surface creates a rendered Markdown editor or table view.
2. If it is editor-backed, it obtains `RichTextStyles` from `rich_text_styles()` or `code_text_styles()`.
3. `rich_text_styles()` builds `table_style` from the shared Markdown table appearance helper.
4. The editor renderer lays out and paints table content using the updated `TableStyle`, which now supports the blockless chrome.
5. If it is the AI block list path, `render_table_section()` builds its WarpUI `Table` using the same shared appearance helper, while keeping block-list-specific typography and selection settings.
6. The user sees the same structural Markdown table treatment across surfaces, with existing interaction behavior preserved.

## Risks and mitigations

### Risk: editor-backed behavior regressions
Changing `RenderableTable` painting could accidentally affect selection visibility, cursor readability, or perceived cell hit areas.

Mitigation:
- keep layout, selection, cursor, and alignment code unchanged
- scope the change to styling and border/background painting
- validate editable surfaces manually after the visual update

### Risk: block list drifts again later
If the block list keeps hand-authoring its own `TableConfig`, the two renderers can diverge again even after this change.

Mitigation:
- refactor both paths to read from the same shared appearance helper
- avoid leaving structural table chrome duplicated inline

### Risk: future surfaces bypass the shared style
Even after current surfaces are fixed, a new renderer could hardcode another table style.

Mitigation:
- make the helper discoverable and clearly named as the canonical Markdown table appearance
- reference it directly from both existing rendering paths so future work sees the pattern

### Risk: typography becomes unintentionally identical everywhere
If the shared helper carries too much font data, it could flatten legitimate surface-specific typography differences.

Mitigation:
- keep the helper focused on chrome and text hierarchy
- let each renderer keep its own font family, size, and weight choices where appropriate

## Testing and validation

### Shared-style tests
- Add focused tests for the shared Markdown table appearance helper so its structural defaults are explicit:
  - no outer border
  - no column dividers
  - row dividers enabled
  - transparent backgrounds
  - no alternating row striping
  - updated padding

### Editor-backed renderer coverage
- Add or update tests around editor-backed Markdown tables to ensure table rendering still occurs and existing Markdown table behavior does not regress.
- Keep existing geometry/selection-oriented table tests in `crates/editor/src/render/element/table_tests.rs` passing after the style changes.

### Surface propagation checks
- Manual validation in:
  - Markdown notebook
  - Markdown editor
  - file notebook
  - AI document / planning document
  - Markdown comment editor
  - AI block list
- Confirm these surfaces all show the same blockless table chrome.

### Behavior regression checks
- Manual validation of:
  - left/center/right alignment
  - inline formatting inside cells
  - cursor placement in editable contexts
  - selection within and across cells
  - link rendering and interaction
  - wide-table overflow handling

### Visual validation
- Screenshot-based comparison against the Figma node and the AI block list implementation from PR #23908
- Manual confirmation that the older notebook/editor chrome is gone everywhere in scope

## Follow-ups
- If additional Markdown table renderers appear outside the current editor-backed path and block list path, route them through the shared appearance helper rather than creating another table style definition.
- If we later want stricter visual parity between surfaces, we can consider a deeper shared text-style adapter, but that should be a follow-up after the chrome is unified.