Prevent frontend fatal when Template_Cloud is absent from the Composer classmap

Summary

Otter can terminate a frontend WordPress request while initializing its Template Cloud module when that class cannot be loaded from the packaged autoloader.

Expected behavior: Startup continues when an optional listed module is unavailable, without taking down the request.

Actual behavior: The request fatals with Class "...Template_Cloud" not found during plugin initialization.

Impact: The affected site cannot serve the request that reaches this initialization path.

Customer context

• Product / area: Otter Blocks startup autoloader / Template Cloud
• Version: 3.2.1
• Environment: WordPress 7.0.2, PHP 8.4.23
• Integration / third party: Themeisle SDK 3.3.58 was present; the crash location is outside SDK code.
• Reported error / symptom: Frontend fatal: Class "...Template_Cloud" not found at inc/class-main.php:97.
• Impact: 2 telemetry occurrences across 1 production site in the captured window.

Reproduction notes

1. Install Otter Blocks 3.2.1 with a Composer classmap that does not resolve ThemeIsle\GutenbergBlocks\Plugins\Template_Cloud while the corresponding class remains in Main::autoload_classes().
2. Load a frontend WordPress request so Otter initialization runs.
3. Observed production result: startup reaches new $classname() and terminates with Class "...Template_Cloud" not found.

The exact packaged classmap from the affected production archive is not available, so the stale-map condition is inferred from source and later regression commits.

Diagnosis

Conclusion

Production telemetry places the fatal at the unguarded module instantiation in Otter 3.2.1. The Template_Cloud source file and declaration are present in the release, while the release relies on Composer's generated classmap to locate it. Later Otter commits explicitly describe stale Composer classmaps causing this fatal path, add an availability guard, and add a test for listed but unavailable classes. This is strong evidence that a stale packaged classmap can leave Template_Cloud unresolved and make frontend startup fatal.

Where this likely occurs

• inc/class-main.php — Main::autoload_classes() lines 66-97 includes ThemeIsle\GutenbergBlocks\Plugins\Template_Cloud at line 89 and directly evaluates new $classname() at line 97 without a loadability check.
• inc/plugins/class-template-cloud.php — ThemeIsle\GutenbergBlocks\Plugins\Template_Cloud lines 8-13 declares the exact namespace and class referenced by the startup list; it exists in v3.2.1.
• otter-blocks.php — plugin bootstrap lines 35-42 loads vendor/autoload.php and then starts Main; no alternate plugin-class resolution is present in the reported release.
• composer.json — autoload lines 61-65 maps inc/ as a Composer classmap with optimize-autoloader enabled at line 46.
• bin/dist.sh — packaging lines 26-32 copies the tree into dist before running Composer commands against the source working tree. .distignore lines 1-46 does not exclude vendor/, making a copied stale map a plausible artifact condition.
• Commit db3918ea moved Template_Cloud from inc/class-template-cloud.php to inc/plugins/class-template-cloud.php and changed its namespace. v3.2.1 is 059432d3; it does not contain commit 6d7c7c3b (fix: frontend fatal when a listed class cannot be autoloaded) or fb75ec38 (fix: resolve the plugin's own classes when the Composer classmap is stale).

Engineering notes

The fatal occurs before the module's instance() setup can run, so it affects normal frontend bootstrap rather than a Template Cloud interaction. The direct trigger is a class that Composer does not resolve even though its PHP file exists. The inspected checkout has no vendor/ directory, so the exact production autoload_classmap.php could not be compared with the shipped class file. WordPress core autoload behavior was not inspected and is not required for the observed new $classname() fatal.

Test coverage status

tests/test-template-cloud.php lines 7-19 directly instantiates Template_Cloud, covering module behavior only when the test autoloader resolves the class. No relevant packaged-classmap or unavailable-module coverage exists in v3.2.1 during inspection. A later, non-3.2.1 commit adds tests/test-main-autoload.php, including TestMainAutoload::test_autoload_classes_skips_unavailable_class() and TestMainAutoload::test_bundled_classnames_are_loadable().

What to verify or explore next

• Reproduce with the 3.2.1 distribution artifact and inspect whether its generated Composer classmap contains Template_Cloud at the relocated path.
• Run the later tests/test-main-autoload.php coverage against an artifact or fixture with an unavailable listed class.
• Check whether release workflows regenerate Composer metadata inside the copied distribution directory for affected release builds.

Unknowns / follow-up

• The telemetry report does not include the affected site's installed plugin archive or Composer classmap, so the exact artifact state is unavailable.
• The available evidence covers the reported Template_Cloud startup path; other stale classmap entries were not independently observed in telemetry.

Confidence

Confidence: 96/100

Production telemetry records a frontend fatal in Otter 3.2.1, and the tagged source unconditionally instantiates the missing class. Subsequent Otter commits explicitly cover unavailable/stale classmap entries and add coverage for this failure mode, confirming a product defect in the reported release.

Crash telemetry

Occurrences	2
Distinct sites	1
First seen	2026-08-02 18:29 UTC
Last seen	2026-08-02 18:29 UTC
Crash location	product:inc/class-main.php:97
Request context	frontend
Inside Themeisle SDK	no
Product versions	3.2.1
WP versions	7.0.2
PHP versions	8.4.23
SDK versions	3.3.58

---

Source: automated crash report — otter-blocks, fingerprint 86449a07a0dcb08489ae1f61b4dfefc9
Generated by bug-report-triage (ID: bug-report-triage_6a717ffb9cfee1.69490653)