FM-SYNCCAL-ROOT-FIX: add F-PR3-4 footgun + test-template-roots.mjs Files row (4/4)

Author: keyxmakerx

.ai.md

@@ -65,6 +65,7 @@ All sync modules use a `_syncing` boolean flag to prevent infinite loops:
 | `chronicle-package.json` | Repo-root serving descriptor (schema v1). Chronicle's `foundry_vtt` sub-plugin reads this from the extracted release zip via `PostInstallHook` to learn how to serve this package: which fields to rewrite, what URL templates to emit, whether per-campaign signed tokens are required. Source of truth for the install/update flow's URL shape. |
 | `tools/check-package-descriptor.mjs` | CI script. Validates `chronicle-package.json` against `module.json` (id match, file paths resolve, endpoint templates carry required placeholders). Run by `.github/workflows/check-descriptor.yml` on every push + PR. |
 | `tools/test-lang-expand.mjs` | CI guard for `lang/en.json` (FM-LANG-COLLISION-FIX). Simulates Foundry's `expandObject` and fails loud on any string-vs-object collision or duplicate-after-expansion path that would cause Foundry to reject the whole lang file at boot. See F-LANG-1 footgun below. |
+| `tools/test-template-roots.mjs` | CI guard for ApplicationV2 PARTS templates (FM-SYNCCAL-ROOT-FIX). Discovers every `PARTS.*.template` binding in `scripts/*.mjs`, statically analyzes each referenced `.hbs` (recursing through every `{{#if/unless/each/with}}` branch), and asserts max-root-count == 1 — Foundry's `_parsePartHTML` rejects multi-root parts at render time. See F-PR3-4 footgun below. |
 | `scripts/calendar-sync.mjs` | Adapter pattern for Calendaria and SimpleCalendar. 0-indexed↔1-indexed conversion |
 | `scripts/shop-widget.mjs` | Shop window (Application v1). Context menu, drag-to-character-sheet, real-time updates |
 | `scripts/actor-sync.mjs` | Actor ↔ character entity bidirectional sync. System adapter loading, hook registration |
@@ -478,6 +479,31 @@ operator sees no error. The pure validator in
 save path blocks on `Errors.RootMustBeGroup`,
 `Errors.EmptyGroup`, and `Errors.NotAnObject`.
 
+### F-PR3-4: ApplicationV2 PARTS templates must render exactly one root HTML element
+
+Foundry's `_parsePartHTML` (foundry.mjs:32135) rejects any `static PARTS`
+template whose rendered output contains more than one root HTML element
+— or zero — with `Error: Template part 'X' must render a single HTML
+element.` Foundry catches this only at app render time; the JSON parses,
+the Handlebars compiles, the app object instantiates fine. The crash
+fires on `app.render()`.
+
+Worst part: the failure mode depends on which branch of `{{#if}}/{{else}}`
+fires. PR 3's `sync-calendar.hbs` had a `degraded` branch that emitted
+one `<section>` (clean) and an `else` branch that emitted three siblings
+(`<header>`, `<main>`, `<footer>`) — the app worked in degraded mode
+during PR 3 dev (no Calendaria connected, so the degraded branch fired)
+and crashed the moment the operator opened it against a real Calendaria.
+
+Same footgun class as F-LANG-1 (silent Foundry-runtime contract that
+Node tests can't catch by accident). Fix: wrap the entire template body
+in a single root element (e.g. `<div class="sync-calendar-root">`) so
+EVERY branch — degraded, year-view, month-view, with or without import
+banner — emits exactly one root. **CI guard at
+`tools/test-template-roots.mjs`** statically analyzes every PARTS-
+registered template across the repo, recurses through every
+`{{#if/unless/each/with}}` branch, and asserts max-root-count == 1.
+
 ### F-LANG-1: `lang/en.json` cannot mix dotted-flat keys with sibling literal-key strings
 
 Foundry's `Localization._loadTranslationFile` runs the parsed JSON