Merge pull request #47 from keyxmakerx/claude/setup-foundry-ai-env-Znu2E

FM-SYNCCAL-ROOT-FIX: wrap sync-calendar.hbs body in single root (unblock app render)

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

styles/sync-calendar-pr3.css

@@ -3,6 +3,21 @@
  * Moon strip + recurrence builder + empty-state Calendaria import
  * ==================================================================== */
 
+/* --- FM-SYNCCAL-ROOT-FIX (#26) single-root wrapper -------------------
+ * The PARTS body is wrapped in `<div class="sync-calendar-root">` so
+ * Foundry's `_parsePartHTML` accepts both the degraded branch and the
+ * three-sibling non-degraded branch. Layout migrates from the prior
+ * `.sync-calendar .sync-calendar-content` container (which Foundry no
+ * longer feeds the children directly) onto this wrapper. See F-PR3-4
+ * in `.ai.md` and `tools/test-template-roots.mjs`. */
+
+.sync-calendar .sync-calendar-root {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  gap: 8px;
+}
+
 /* --- Moon-phase strip in month view --------------------------------- */
 
 .sync-calendar .moon-strip-block {

templates/sync-calendar.hbs

@@ -13,8 +13,17 @@
   binds to the actions map in DEFAULT_OPTIONS. Form-field inputs use
   data-form-field="..." attributes that the application's #wireFormInputs
   hook (in _onRender) listens to.
+
+  Single-root wrapper (`<div class="sync-calendar-root">`) is required:
+  ApplicationV2's `_parsePartHTML` rejects any PARTS template that emits
+  more than one root HTML element across any branch of any conditional
+  ("Template part 'body' must render a single HTML element"). The
+  `else` branch below has three siblings (header + main + footer) and
+  must be wrapped. See F-PR3-4 in `.ai.md` and the CI guard at
+  `tools/test-template-roots.mjs`.
 --}}
 
+<div class="sync-calendar-root">
 {{#if degraded}}
   <section class="sync-calendar-degraded">
     <i class="fa-solid fa-triangle-exclamation"></i>
@@ -580,3 +589,4 @@
     <span class="footer-meta">schema v{{schemaVersion}}</span>
   </footer>
 {{/if}}
+</div>