fix(import): report loop references the importer cannot resolve

[DavidBabinec]

An invalid loop imported cleanly and published nothing

<instatic-loop data-source-id="posts" data-limit="12">

posts is a table slug; the source id is data.rows and the table goes in data-table-id. The importer copied the string verbatim into props, site_insert_html reported success, verify-docs found the document intact, and at publish loopPrefetch.ts:288-296 turned the unregistered source into a well-formed { items: [], totalItems: 0 } — indistinguishable from "this table has no rows". renderLoop then rendered ''.

The route still returned 200 with a unique title and one <h1>, so every downstream check passed. Two template packs shipped with an empty journal index before anyone looked at the page.

loopSourceRegistry has exposed has() and getOrThrow() the whole time, and nothing under src/core/htmlImport/ ever called either — so the shape site_list_loop_sources documents and the shape the importer accepts were validated against nothing in common. The one place that does look the id up, dynamicDetection.ts:143-152, explicitly treats a miss as "static".

The fix

The walk now checks each loop against that same registry and reports three cases: an unregistered source, no source at all, and a data.rows loop with no tableId — the second silent path, where filters: {} makes dataRows.ts:418 return empty just as quietly.

Live, through the real MCP surface:

BAD  loop  → Loop data-source-id "posts" is not a registered loop source, so it will render
             nothing. Valid source ids: "data.rows", "site.pages", "site.media", "entry.field".
             A table slug is not a source id — use data-source-id="data.rows" with
             data-table-id="<table>".
NO-TABLE   → Loop source "data.rows" needs data-table-id and will render nothing without it.
GOOD loop  → (silent)

All three still insert. Warnings, not rejections: a paste of thirty elements should not be thrown away over one mistyped attribute, and the importer also serves arbitrary user-pasted HTML. site_insert_html and site_replace_node_html return them alongside the ids they already report, so the caller is told at author time.

Warnings live on a WalkResult rather than on ImportFragment — that is the structural shape callers hand back to insertImportedNodes, and a diagnostic has no business in it.

Two descriptions that promised what the composer does not do

<instatic-outlet> is spliced away on page routes — templateCompose.ts:83 deletes the node and the page's content takes its position — so data-tag only takes effect on entry routes, where the outlet stays and wraps the entry body. The module's own doc comment describes this polymorphism correctly; the tool description and system prompt claimed omitting data-tag makes the outlet "own the page's main landmark", which is never true on a page route. That is how a layout ends up with no <main> on any public route.

Both now say what actually happens and tell authors to wrap the outlet themselves. I did not change the rendering: making the outlet a wrapper needs canHaveChildren and a render change against a deliberately polymorphic module, which is a redesign rather than a fix, and it would add a wrapper element to every templated page route.

Verification

Unit — a table slug, a missing id, and a missing table each warn with the fix in the message; a well-formed loop is silent; the node still imports; several bad loops in one payload all report.

Live — inserted all three shapes through MCP against a real site (above), then restored the page and re-audited: 19/19 routes, 0 problems.

Suite: 6505 pass / 0 fail. Lint clean. tsc -b clean.

Worth knowing

bunx tsc --noEmit typechecks nothing in this repo — tsconfig.json is solution-style with only references and no files/include. I confirmed it by planting a syntax error in a server/ file and getting exit 0. tsc -b (what bun run build and CI use) catches it. Anyone verifying locally with --noEmit is running a no-op.

Related

Follows #318 and #320 from the same investigation.

🤖 Generated with Claude Code