fix(mapbox): autoload map children declared with the hidden attribute

[titouanmathis]

Map children declared with the hidden attribute never autoloaded.

packages/ui-mapbox/src/catalog.ts declared one strategy: 'visible' for the whole package, and the generator stamped it onto all 14 manifest entries. The visible strategy installs an IntersectionObserver on the element. A hidden element is never rendered, so it never intersects, the dynamic import() never runs, and nothing is logged. hidden is the pattern packages/ui-mapbox/README.md recommends for the declarative-only children, so the two recommendations contradicted each other.

What changed

• scripts/manifest-types.ts — CuratedComponentMetadata takes an optional strategy.
• scripts/generate-manifests.ts — serializeComponent serializes component.strategy ?? catalog.strategy.
• packages/ui-mapbox/src/catalog.ts — the package default stays visible; the twelve map children declare eager. MapboxMap and StoreLocator are the rendered roots and keep visible.
• packages/ui-mapbox/src/manifest.ts — regenerated.

Why eager is right here

In js-toolkit v4, eager does not mean "load at page load".

The registry never walks the manifest. reconcileElement reads the data-component tokens declared on an element and calls schedule(el, name) per token, so a manifest entry is consulted only for a name present in the DOM. Nothing loads for a token absent from the page. applyMountStrategy handles eager with defaultScheduler.background(mount), which posts through scheduler.postTask at background priority: deferred and off-frame. For a manifest source the mount hook is importPair, which calls entry.load(). Imports are deduplicated per name and the entry is deleted once loaded, so many markers on a page cost one import.

So eager means "no condition left to wait for beyond the element existing". That is what these declarative-only children need. idle would also fix the bug but can delay controls and markers noticeably after the map appears. The heavy mapbox-gl import stays gated behind MapboxMap, which keeps visible.

Tests

• packages/tests/autoload/manifest.spec.ts asserted one uniform strategy per package. It now takes a per-token expectation, and a dedicated case lists both halves of the ui-mapbox split, so a new component fails the suite until it is classified.
• packages/tests/autoload/hidden-elements.spec.ts is new. It mounts a MapboxMap holding hidden children declared through the real package manifest and asserts each one loads and mounts, and it shows the contrast: a visible entry on a hidden element is never imported. Both positive tests fail against the old uniform visible manifest.

Full suite: 87 files, 973 tests, all passing. npm run manifest:check and npm run lint pass.

Docs

packages/docs/guide/autoloading/index.md gains a "What eager means" section and a "Package defaults" section describing the ui-mapbox split, and the Mapbox integration note is corrected. packages/ui-mapbox/README.md explains why the hidden children are eager (and its Usage section no longer shows the importWhen* helpers, which js-toolkit v4 removed). The hand-written manifest examples in the MapboxMap reference and the vue-mapbox-gl migration guide gave visible to MapboxMarker and MapboxPopup, which reproduces this bug; they now give eager.

Closes #625

🤖 Generated with Claude Code

https://claude.ai/code/session_01LMSCm41fm3g7chxD728vAu

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.32%. Comparing base (2d5253b) to head (93c5185).
⚠️ Report is 8 commits behind head on 2.x.

Additional details and impacted files

@@            Coverage Diff            @@
##                2.x     #655   +/-   ##
=========================================
  Coverage     86.32%   86.32%           
  Complexity      145      145           
=========================================
  Files            20       20           
  Lines           746      746           
  Branches         88       88           
=========================================
  Hits            644      644           
  Misses           95       95           
  Partials          7        7           

Flag	Coverage Δ
unittests	86.32% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Code Review

Risk: Low — The manifest strategy override is scoped to the declarative Mapbox children while rendered roots remain viewport-gated; no blocking issues were found.

This change adds per-component mount strategies to the manifest generator and regenerates the Mapbox manifest with eager entries for map children. It also adds coverage for hidden elements and updates the autoloading documentation and examples.

---

Review usage: 63,395 in (39,563 cached) / 830 out tokens — $0.0194 (openrouter/openai/gpt-5.6-luna, thinking: low)

Reviewed by @weareikko/code-review v0.9.5 for commit 93c5185.