flowchart TD
    A(["`**generateMaps(container, options)**`"]) --> B{container already\nhas .Dumby class?}
    B -- yes --> Z([return — no-op])
    B -- no --> C

    C["**setupContainer()**\nAdd .Dumby class\nSet data-crs, data-layout"] --> D

    D["**resolveHtmlHolder()**\nFind Semantic HTML element\nby priority:\n① contentSelector option\n② .SemanticHtml\n③ <main> or <article>\n④ child id/class ≈ main|content\n⑤ largest child by text length\n→ add .SemanticHtml class"] --> E

    E["**wrapDumbyBlocks()**\nEnsure content is inside .dumby-block elements"] --> E1

    subgraph WRAP ["wrapDumbyBlocks — block detection strategy"]
        E1{".dumby-block\nalready exists?"}
        E1 -- yes --> E2["Wrap loose text nodes\ninside existing blocks in <p>"]
        E1 -- no --> E3{h1/h2/h3\nheadings present?}
        E3 -- yes --> E4["Split at each heading:\nnew <article class=dumby-block>\nstarts at each h1/h2/h3"]
        E3 -- no --> E5{"<section> or <article>\nchildren present?"}
        E5 -- yes --> E6["Promote each section/article\nto .dumby-block"]
        E5 -- no --> E7["Wrap all children\nin a single .dumby-block"]
    end

    E2 & E4 & E6 & E7 --> F

    F["Remove all siblings of .SemanticHtml\nfrom container"] --> G

    G["**createShowcase()**\nAppend <div class=Showcase>"] --> H

    H["**createModal()**\nAppend PlainModal overlay"] --> J

    J["**buildDumbymap()**\nAssemble dumbymap object:\nlayouts, aliases, utils,\ngetters: htmlHolder, showcase, blocks"] --> K

    K["**setupContentObserver()**\nMutationObserver on character data:\n• re-scan text for geo-coord patterns\n• re-render map if YAML text changed"] --> L

    L["**setupChildObserver()**\nMutationObserver on child list + attrs:\n• update data-total on all blocks\n• init new GeoLinks / DocLinks\n• renderMap() for new map code blocks"] --> M

    M["**setupLayoutObserver()**\nMutationObserver on data-layout:\n• call leaveHandler of old layout\n• reset inline styles\n• call enterHandler of new layout\n• re-apply focus to current map"] --> N

    N{"urlParams\noption?"}
    N -- yes --> N1["Read ?layout= from URL\nApply to data-layout\nReflect future changes\nback to URL via replaceState"]
    N -- no --> O
    N1 --> O

    O["container.dataset.initDumby = 'true'\n→ triggers setupChildObserver\n→ kicks off initial map rendering"] --> P

    subgraph RENDER ["renderMap() — called per map code block"]
        P2["Parse YAML via\nmapclay.parseConfigsFromYaml()"]
        P3{"Map ID in\ncache?"}
        P4["Reuse cached renderer element\n(no re-init)"]
        P5["Assign unique map ID\n(use renderer name + counter)"]
        P6["debounce( render(), mapDelay )\ndefault 1000 ms\n(0 ms if data-render=no-delay)"]
        P7["After render fulfilled:\n• cache renderer\n• set style.order\n• start mapClassObserver\n• add .focus if no map focused\n• call renderCallback()"]
        P2 --> P3
        P3 -- yes --> P4
        P3 -- no --> P5
        P4 & P5 --> P6
        P6 --> P7
    end

    O --> P
    P["Each .map-container\n(pre:has(code.map) or .mapclay-container)\nfound in DOM"] --> P2

    P7 --> Q

    Q["**setupBlockEdit()**\nAssign data-block-index to all blocks\nBuild edit modal overlay (appended to body)\nReturn editBlockItem factory"] --> R

    R["**setupContextMenu()**\nAttach right-click handler:\nmap / block / geolink / doclink / selection\n→ context-sensitive popover menu"] --> S

    S["**setupMouseDrag()**\nAttach mousedown handler:\nhold 300 ms on selection\n→ drag-to-create GeoLink"] --> T

    T["**setupKeybindings()**\nAttach keydown to document:\nTab/Shift-Tab: focusNextMap\nx/X: switchToNextLayout\nn/p: focusNextBlock\nEscape: removeBlockFocus\n(removed on container removal)"] --> U

    U["**fetchDefaultAliases()**\nFetch defaultApply YAML URL\nParse aliases into dumbymap.aliases\n(async, non-blocking)"] --> V

    V(["return **Object.seal(dumbymap)**"])

    style A fill:#4a90d9,color:#fff
    style V fill:#27ae60,color:#fff
    style Z fill:#e74c3c,color:#fff
    style WRAP fill:#fef9e7,stroke:#f39c12
    style RENDER fill:#eaf4fb,stroke:#2980b9