"""W21B-wave-4 A2: marker legend render_role / top_down_legibility 직렬화.

A2 lock (Claude+Codex 2026-05-30): ``_format_layer_markers_block`` 가 marker
entry 의 ``render_role`` / ``top_down_legibility`` 를 한 줄 legend 에 surface 한다.
backward-compat 절대 조건: 메타가 없거나 둘 다 ``not_applicable`` 이면 옛 라인
(``"<num>. <label> [<category>] — <pos>"``)과 **byte-identical**.

LLM / image / VLM / DB I/O 0. 순수 직렬화 단위 테스트.
"""
from __future__ import annotations

from app.modules.pipeline.background_prompt import _format_layer_markers_block


def _marker(**over):
    base = {
        "number": 1,
        "label": "primary unit",
        "category": "area",
        "position_hint": "center",
        "base_layer_decision": "base_structural_unit",
    }
    base.update(over)
    return base


def test_marker_line_byte_identical_when_no_meta_keys():
    """render_role / top_down_legibility 키 자체가 없으면 옛 라인과 동일."""
    assert (
        _format_layer_markers_block([_marker()])
        == "1. primary unit [area] — center"
    )


def test_marker_line_byte_identical_when_meta_na():
    """둘 다 not_applicable 이면 옛 라인과 동일 (메타 있어도 옛 동작)."""
    line = _format_layer_markers_block(
        [_marker(render_role="not_applicable", top_down_legibility="not_applicable")]
    )
    assert line == "1. primary unit [area] — center"


def test_marker_line_surfaces_render_role_and_low_legibility():
    line = _format_layer_markers_block(
        [
            _marker(
                number=4,
                label="sleeping zone",
                position_hint="upper left",
                render_role="structural_skeleton",
                top_down_legibility="low",
            )
        ]
    )
    assert "structural_skeleton" in line
    assert "legibility=low" in line
    assert line.startswith("4. sleeping zone [area")
    assert line.endswith("— upper left")


def test_marker_line_surfaces_clear_legibility():
    line = _format_layer_markers_block(
        [_marker(render_role="persistent_context", top_down_legibility="clear")]
    )
    assert "legibility=clear" in line
    assert "persistent_context" in line


def test_marker_line_render_role_only_when_legibility_na():
    """render_role 만 있고 legibility=na → render_role 만 surface, legibility 미표기."""
    line = _format_layer_markers_block(
        [_marker(render_role="scene_essential_fixtures", top_down_legibility="not_applicable")]
    )
    assert "scene_essential_fixtures" in line
    assert "legibility=" not in line