"""
Story 图片回填 — 将 asset:// 引用插入 markdown。

图片生成成功后，基于 source_span 或 fallback 位置插入 ![caption](asset://asset_id)。
"""


def backfill_image_into_markdown(
    markdown: str,
    asset_id: str,
    caption: str,
    *,
    source_span: dict | None = None,
) -> str:
    """
    将图片引用回填到 markdown。

    格式：![caption](asset://asset_id)
    位置：若 source_span 有效则在对应段落后插入；否则在开头插入。
    """
    img_ref = f"![{caption}](asset://{asset_id})"
    if not markdown or not markdown.strip():
        return img_ref

    if source_span and isinstance(source_span, dict):
        start = source_span.get("start")
        end = source_span.get("end")
        if start is not None and end is not None and 0 <= start <= end <= len(markdown):
            return markdown[:end] + "\n\n" + img_ref + "\n\n" + markdown[end:]

    parts = markdown.strip().split("\n\n", 1)
    if len(parts) == 1:
        return img_ref + "\n\n" + markdown.strip()
    return parts[0] + "\n\n" + img_ref + "\n\n" + parts[1]