@schukai/monster 4.154.12 → 5.0.1

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 
 
+## [5.0.1] - 2026-10-11
+
+### Bug Fixes
+
+- **docs:** ship Monster 5 migration guide ([#597](https://gitlab.schukai.com/oss/libraries/javascript/monster/issues/597))
+
+
+
+## [5.0.0] - 2026-10-10
+
+### Breaking Changes
+
+- **custom-element:** `getOption()`, `setOption()` and `setOptions()` now throw
+  `OptionsNotInitializedError` while `defaults` or `customization` are being
+  evaluated ([#596](https://gitlab.schukai.com/oss/libraries/javascript/monster/issues/596)).
+  Keep both getters and their helpers declarative. Use `initMethodSymbol` for
+  initialized constructor options and `assembleMethodSymbol` after late
+  attributes or script configuration have been applied. Monster 5 deliberately
+  provides no compatibility switch, early fallback or write queue. See the
+  [Monster 5 options migration guide](documentation/migrations/monster-5-options.md).
+
 ## [4.154.12] - 2026-10-10
 
 ### Bug Fixes

package/README.md

@@ -25,6 +25,14 @@ For certain functions, additional [polyfills](#polyfill) may be required.
 
 To access our documentation and examples, visit [monsterjs.org/](https://monsterjs.org/).
 
+### Migrating to Monster 5
+
+Monster 5 makes the custom-element option lifecycle strict. Option access is
+not available while `defaults` or `customization` are being evaluated. See the
+[Monster 5 options migration guide](documentation/migrations/monster-5-options.md)
+for the lifecycle contract, migration examples and the correct use of
+`initMethodSymbol` and `assembleMethodSymbol`.
+
 ## Installation
 
 Install Monster using npm, Yarn, or pnpm:

package/documentation/migrations/monster-5-options.md

@@ -0,0 +1,90 @@
+# Monster 5: initialized options
+
+`CustomElement.getOption()`, `setOption()` and `setOptions()` require an initialized
+option observer. Calls made while the constructor evaluates `defaults` or
+`customization` throw `OptionsNotInitializedError`. The error is exported from
+`source/dom/customelement.mjs` and the main Monster entry point; its `method` and
+`component` properties identify the attempted operation and class.
+
+Monster 4.154.10 restored a fallback for early reads. Monster 5 removes that
+fallback. There is no compatibility switch, dependency injection setting or
+queue for early writes. Normal fallback values for missing initialized options
+continue to work, as do `false`, `0`, `""` and `null`.
+
+## Lifecycle
+
+1. The constructor reads `defaults`, applies available `data-monster-option-*`
+   attributes and applies `customization` (evaluated once).
+2. It creates the option observer, then calls `initMethodSymbol`. All three
+   option methods are now usable. Derived instance fields are not initialized
+   yet: this hook runs inside the base constructor.
+3. On first connection, option attributes are read again. The base assembly
+   merges `data-monster-options`, then the script selected by
+   `data-monster-options-selector`, before rendering and connecting updaters.
+4. Runtime setters notify observers. `setOptions()` merges without resetting
+   defaults. Reconnection rebinds the existing DOM and updater snapshot; it does
+   not repeat assembly or reload the JSON/script configuration.
+
+Available attributes depend on the creation path. In particular,
+`document.createElement()` cannot see attributes the caller will set later.
+An initialized API is therefore not a promise that all configuration sources
+have already been applied. Existing attribute conversion and precedence remain
+unchanged, including the attribute reread on connection.
+
+## Migration
+
+This creates a circular dependency and is no longer supported:
+
+```js
+get defaults() {
+  return { ...super.defaults, title: this.getOption("labels.title", "Details") };
+}
+```
+
+Define initial values without reading the options under construction:
+
+```js
+get defaults() {
+  return {
+    ...super.defaults,
+    labels: { title: "Details" },
+    templates: {
+      main: '<h2 data-monster-replace="path:labels.title"></h2>',
+    },
+  };
+}
+```
+
+Updater-bound markup reads the assembled configuration and follows subsequent
+changes. For imperative work that needs JSON/script options, use the existing
+assembly hook after its `super` call:
+
+```js
+[assembleMethodSymbol]() {
+  super[assembleMethodSymbol]();
+  this.configureFromResource(this.getOption("resourceConfig"));
+  return this;
+}
+```
+
+At that point the base template has already rendered. Do not move template
+configuration after rendering and expect it to rebuild automatically. Prefer a
+static template with updater bindings, or update the rendered component through
+its established API. Do not permanently cache IDs or context keys from
+constructor-time fallbacks.
+
+Work needing only constructor configuration can use `initMethodSymbol` after
+its `super` call. Callbacks stored in defaults may read options when invoked
+later; the restriction concerns execution during initialization, not where a
+callback is declared. The same rule applies to helpers called by either getter.
+
+Consumer subclasses must migrate before adopting Monster 5. Other option
+classes, including the deprecated `BaseWithOptions`, are outside this change.
+
+## Verification
+
+Issue #596 adds API lifecycle tests, a local AST call-graph check, and browser
+construction/assembly coverage for the registered component catalog. The static
+check resolves direct calls, local helpers and methods; it is not a proof about
+imported or dynamically selected functions. Browser coverage complements it.
+Existing form, updater, datatable and reconnect suites remain release gates.

package/package.json

@@ -1 +1 @@
-{"author":"Volker Schukai","dependencies":{"@floating-ui/dom":"^1.7.6"},"description":"Monster is a simple library for creating fast, robust and lightweight websites.","exports":{".":"./source/monster.mjs","./CHANGELOG.md":"./CHANGELOG.md","./LICENSE":"./LICENSE","./README.md":"./README.md","./package.json":"./package.json","./source/*":"./source/*","./test/*":"./test/*"},"files":["source","test/cases","test/util","CHANGELOG.md"],"homepage":"https://monsterjs.org/","keywords":["framework","web","dom","css","sass","mobile-first","app","front-end","templates","schukai","core","shopcloud","alvine","monster","buildmap","stack","observer","observable","uuid","node","nodelist","css-in-js","logger","log","theme"],"license":"AGPL 3.0","main":"source/monster.mjs","module":"source/monster.mjs","name":"@schukai/monster","repository":{"type":"git","url":"https://gitlab.schukai.com/oss/libraries/javascript/monster.git"},"sideEffects":["./source/monster.mjs","./source/components/**","./source/i18n/**","./test/**"],"type":"module","version":"4.154.12"}
+{"author":"Volker Schukai","dependencies":{"@floating-ui/dom":"^1.7.6"},"description":"Monster is a simple library for creating fast, robust and lightweight websites.","exports":{".":"./source/monster.mjs","./CHANGELOG.md":"./CHANGELOG.md","./LICENSE":"./LICENSE","./README.md":"./README.md","./documentation/migrations/monster-5-options.md":"./documentation/migrations/monster-5-options.md","./package.json":"./package.json","./source/*":"./source/*","./test/*":"./test/*"},"files":["source","test/cases","test/util","documentation/migrations/monster-5-options.md","CHANGELOG.md"],"homepage":"https://monsterjs.org/","keywords":["framework","web","dom","css","sass","mobile-first","app","front-end","templates","schukai","core","shopcloud","alvine","monster","buildmap","stack","observer","observable","uuid","node","nodelist","css-in-js","logger","log","theme"],"license":"AGPL 3.0","main":"source/monster.mjs","module":"source/monster.mjs","name":"@schukai/monster","repository":{"type":"git","url":"https://gitlab.schukai.com/oss/libraries/javascript/monster.git"},"sideEffects":["./source/monster.mjs","./source/components/**","./source/i18n/**","./test/**"],"type":"module","version":"5.0.1"}

package/source/dom/customelement.mjs

@@ -61,6 +61,7 @@ import { addErrorAttribute } from "./error.mjs";
 
 export {
 	CustomElement,
+	OptionsNotInitializedError,
 	initMethodSymbol,
 	assembleMethodSymbol,
 	attributeObserverSymbol,
@@ -69,6 +70,34 @@ export {
 	updaterTransformerMethodsSymbol,
 };
 
+/**
+ * An options API was used before the element's option observer was created.
+ * @summary Reports an option access before CustomElement initialization.
+ * @since 5.0.0
+ */
+class OptionsNotInitializedError extends Error {
+	/**
+	 * @param {string} method attempted options API method
+	 * @param {string} component component constructor name
+	 */
+	constructor(method, component) {
+		super(
+			`${component}.${method}() requires initialized options. Do not use the options API while defaults or customization are being evaluated during construction. Use initMethodSymbol for initial options, or assembly for attribute/script configuration.`,
+		);
+		this.name = "OptionsNotInitializedError";
+		this.method = method;
+		this.component = component;
+	}
+}
+
+function requireOptionObserver(element, method) {
+	const observer = element[internalSymbol];
+	if (observer === undefined) {
+		throw new OptionsNotInitializedError(method, element.constructor.name);
+	}
+	return observer;
+}
+
 /**
  * @type {symbol}
  */
@@ -224,12 +253,15 @@ class RevisionObserver extends Observer {
  */
 class CustomElement extends HTMLElement {
 	/**
-	 * A new object is created. First, the `initOptions` method is called. Here the
-	 * options can be defined in derived classes. Subsequently, the shadowRoot is initialized.
+	 * Initializes defaults, available option attributes and customization before
+	 * creating the option observer and calling initMethodSymbol. The options API
+	 * must not be called while defaults or customization are being evaluated.
+	 * JSON/script options and DOM rendering are handled later by base assembly.
 	 *
 	 * IMPORTANT: CustomControls instances are not created via the constructor, but either via a tag in the HTML or via <code>document.createElement()</code>.
 	 *
 	 * @throws {Error} the option attribute does not contain a valid JSON definition.
+	 * @throws {OptionsNotInitializedError} an options API was called too early
 	 */
 	constructor() {
 		super();
@@ -247,9 +279,10 @@ class CustomElement extends HTMLElement {
 			);
 		}
 
-		if (this.customization instanceof Map) {
+		const customization = this.customization;
+		if (customization instanceof Map) {
 			const pathfinder = new Pathfinder(options);
-			this.customization.forEach((value, key) => {
+			customization.forEach((value, key) => {
 				if (key === undefined || key === null || key === "") {
 					return;
 				}
@@ -333,6 +366,7 @@ class CustomElement extends HTMLElement {
 	 * Unlike the defaults that expect an object, the customization is a Map.
 	 * This also allows overwriting individual values in a deeper structure
 	 * without having to redefine the entire structure and thus changing the defaults.
+	 * Evaluated once during construction, before the options API is available.
 	 * @return {Map}
 	 */
 	get customization() {
@@ -540,20 +574,17 @@ class CustomElement extends HTMLElement {
 	/**
 	 * nested options can be specified by path `a.b.c`
 	 *
-	 * Before the constructor has initialized the option observer, this method
-	 * returns the supplied default value. This preserves option reads from
-	 * derived `defaults` and `customization` getters during initialization.
+	 * Options are available from initMethodSymbol onwards. Attribute/script JSON
+	 * is applied during assembly. The fallback only applies to initialized options.
 	 *
 	 * @param {string} path
 	 * @param {*} defaultValue
 	 * @return {*}
+	 * @throws {OptionsNotInitializedError} options have not been initialized
 	 * @since 1.10.0
 	 */
 	getOption(path, defaultValue = undefined) {
-		const optionObserver = this[internalSymbol];
-		if (optionObserver === undefined) {
-			return defaultValue;
-		}
+		const optionObserver = requireOptionObserver(this, "getOption");
 
 		return new Pathfinder(optionObserver.getRealSubject().options).getVia(
 			path,
@@ -568,12 +599,12 @@ class CustomElement extends HTMLElement {
 	 * @param {*} value
 	 * @return {CustomElement}
 	 * @since 1.14.0
+	 * @throws {OptionsNotInitializedError} options have not been initialized
 	 */
 	setOption(path, value) {
-		new Pathfinder(this[internalSymbol].getSubject()["options"]).setVia(
-			path,
-			value,
-		);
+		new Pathfinder(
+			requireOptionObserver(this, "setOption").getSubject().options,
+		).setVia(path, value);
 		return this;
 	}
 
@@ -581,15 +612,17 @@ class CustomElement extends HTMLElement {
 	 * @since 1.15.0
 	 * @param {string|object} options
 	 * @return {CustomElement}
+	 * @throws {OptionsNotInitializedError} options have not been initialized
 	 */
 	setOptions(options) {
+		const optionObserver = requireOptionObserver(this, "setOptions");
 		if (isString(options)) {
 			options = parseOptionsJSON.call(this, options);
 		}
 		// 2024-01-21: remove this.defaults, otherwise it will overwrite
 		// the current settings that have already been made.
 		// https://gitlab.schukai.com/oss/libraries/javascript/monster/-/issues/136
-		extend(this[internalSymbol].getSubject()["options"], options);
+		extend(optionObserver.getSubject().options, options);
 
 		return this;
 	}

package/source/types/version.mjs

@@ -156,7 +156,7 @@ function getMonsterVersion() {
 	}
 
 	/** Managed by the release script; keep synchronized with package.json. */
-	monsterVersion = new Version("4.154.12");
+	monsterVersion = new Version("5.0.1");
 
 	return monsterVersion;
 }

package/test/cases/dom/customelement.mjs

@@ -1232,7 +1232,7 @@ describe('DOM', function () {
                 mocks.innerHTML = html1;
             })
 
-            it('should return the fallback while defaults and customization initialize options', function () {
+            it('should reject option reads while defaults initialize options (#596)', function () {
                 const htmlTAG = 'monster-testclass-early-option-576';
 
                 if (!customElements.get(htmlTAG)) {
@@ -1270,13 +1270,9 @@ describe('DOM', function () {
                     registerCustomElement(EarlyOptionComponent);
                 }
 
-                const element = document.createElement(htmlTAG);
-
-                expect(element.getOption('fromDefaults')).to.equal(
-                    'defaults-fallback',
-                );
-                expect(element.getOption('fromCustomization')).to.equal(
-                    'customization-fallback',
+                const Constructor = customElements.get(htmlTAG);
+                expect(() => new Constructor()).to.throw(
+                    'getOption() requires initialized options',
                 );
             });
 

package/test/cases/dom/early-options-contract.mjs

@@ -0,0 +1,40 @@
+import { strict as assert } from "node:assert";
+import { readFileSync } from "node:fs";
+import { globSync } from "glob";
+import { findEarlyOptions } from "../../util/early-options.mjs";
+
+describe("Early options source contract (#596)", () => {
+	it("rejects synchronous helper and method calls but allows deferred callbacks", () => {
+		const source = `
+		function helper() { return this.getOption("value"); }
+		class Example {
+			get defaults() { return { value: helper.call(this), later: () => this.getOption("later") }; }
+			get customization() { this.configure(); return new Map(); }
+			configure() { this.setOptions({}); }
+		}`;
+		assert.deepEqual(
+			findEarlyOptions(source).map(({ phase, method }) => ({ phase, method })),
+			[
+				{ phase: "defaults", method: "getOption" },
+				{ phase: "customization", method: "setOptions" },
+			],
+		);
+		assert.equal(
+			findEarlyOptions(
+				'class Example { get defaults() { return (() => this.setOption("x", 1))(); } }',
+			).length,
+			1,
+		);
+	});
+	it("has no statically resolved early options access in library getters", () => {
+		const root = new URL("../../../", import.meta.url);
+		const files = globSync("source/**/*.mjs", { cwd: root }).sort();
+		assert.ok(files.length > 300);
+		const failures = files.flatMap((file) =>
+			findEarlyOptions(readFileSync(new URL(file, root), "utf8")).map(
+				(failure) => ({ file, ...failure }),
+			),
+		);
+		assert.deepEqual(failures, []);
+	});
+});

package/test/cases/dom/options-lifecycle.mjs

@@ -0,0 +1,216 @@
+import { expect } from "chai";
+import { initJSDOM } from "../../util/jsdom.mjs";
+
+describe("Strict options lifecycle (#596)", function () {
+	let api;
+	let fixture;
+	let sequence = 0;
+	const tick = () => new Promise((resolve) => setTimeout(resolve, 30));
+
+	before(async () => {
+		await initJSDOM({});
+		api = await import("../../../source/dom/customelement.mjs");
+	});
+	beforeEach(() => {
+		fixture = document.createElement("div");
+		document.getElementById("mocks").append(fixture);
+	});
+	afterEach(() => fixture.remove());
+
+	function register(Constructor) {
+		const tag = `monster-options-596-${++sequence}`;
+		customElements.define(tag, Constructor);
+		return tag;
+	}
+
+	for (const phase of ["defaults", "customization"]) {
+		for (const [method, args] of [
+			["getOption", ["value", "fallback"]],
+			["setOption", ["value", "early"]],
+			["setOptions", [{ value: "early" }]],
+			["setOptions", ["invalid JSON"]],
+		]) {
+			it(`rejects ${method}(${JSON.stringify(args)}) in ${phase}`, () => {
+				class EarlyOptions extends api.CustomElement {}
+				Object.defineProperty(EarlyOptions.prototype, phase, {
+					get() {
+						return this[method](...args);
+					},
+				});
+				register(EarlyOptions);
+				let failure;
+				try {
+					new EarlyOptions();
+				} catch (error) {
+					failure = error;
+				}
+				expect(failure).to.be.instanceOf(api.OptionsNotInitializedError);
+				expect(failure.name).to.equal("OptionsNotInitializedError");
+				expect(failure.method).to.equal(method);
+				expect(failure.component).to.equal("EarlyOptions");
+				expect(failure.message).to.include("initMethodSymbol");
+			});
+		}
+	}
+
+	it("evaluates customization once and makes reads and writes available in init", () => {
+		let evaluations = 0;
+		class Initialized extends api.CustomElement {
+			get defaults() {
+				return { ...super.defaults, value: "default", nested: { kept: true } };
+			}
+			get customization() {
+				evaluations++;
+				return new Map([["value", "custom"]]);
+			}
+			[api.initMethodSymbol]() {
+				super[api.initMethodSymbol]();
+				expect(this.getOption("value")).to.equal("custom");
+				expect(this.setOption("nested.added", 1)).to.equal(this);
+				expect(this.setOptions('{"nested":{"other":2}}')).to.equal(this);
+			}
+		}
+		const element = document.createElement(register(Initialized));
+		expect(element).to.be.instanceOf(Initialized);
+		expect(evaluations).to.equal(1);
+		expect(element.getOption("nested")).to.deep.equal({
+			kept: true,
+			added: 1,
+			other: 2,
+		});
+	});
+
+	it("preserves fallback and falsy values, and propagates unrelated failures", () => {
+		class Options extends api.CustomElement {}
+		const element = document.createElement(register(Options));
+		for (const value of [null, false, 0, ""]) {
+			element.setOption("value", value);
+			expect(element.getOption("value", "fallback")).to.equal(value);
+		}
+		element.setOption("value", undefined);
+		expect(element.getOption("value", "fallback")).to.equal("fallback");
+		expect(element.getOption("missing.deep", "fallback")).to.equal("fallback");
+		expect(element.getOption("missing.deep")).to.equal(undefined);
+		expect(() => element.setOptions("invalid JSON")).to.throw();
+		const failure = new Error("property failure");
+		element.setOption(
+			"broken",
+			Object.defineProperty({}, "value", {
+				get() {
+					throw failure;
+				},
+				enumerable: true,
+			}),
+		);
+		expect(() => element.getOption("broken.value", "fallback")).to.throw(
+			failure,
+		);
+	});
+
+	it("preserves attribute/customization precedence on upgrade and permits deferred defaults callbacks", async () => {
+		class Upgraded extends api.CustomElement {
+			get defaults() {
+				return {
+					...super.defaults,
+					value: "default",
+					fromAttribute: "default",
+					readLater: () => this.getOption("value"),
+					templates: { main: "<span></span>" },
+				};
+			}
+			get customization() {
+				return new Map([["value", "custom"]]);
+			}
+			[api.initMethodSymbol]() {
+				super[api.initMethodSymbol]();
+				this.initialValue = this.getOption("value");
+				this.initialAttribute = this.getOption("fromAttribute");
+			}
+		}
+		const tag = `monster-options-596-${++sequence}`;
+		const holder = document.createElement("div");
+		holder.innerHTML = `<${tag} data-monster-option-value="attribute" data-monster-option-from-attribute="present"></${tag}>`;
+		const element = holder.firstElementChild;
+		customElements.define(tag, Upgraded);
+		customElements.upgrade(element);
+		expect(element).to.be.instanceOf(Upgraded);
+		expect(element.initialValue).to.equal("custom");
+		expect(element.initialAttribute).to.equal("present");
+		expect(element.getOption("readLater")()).to.equal("custom");
+		fixture.append(element);
+		await tick();
+		expect(element.getOption("readLater")()).to.equal("attribute");
+	});
+
+	it("applies late attributes, JSON and script before rendering; reconnect keeps state", async () => {
+		let assemblies = 0;
+		class Configured extends api.CustomElement {
+			get defaults() {
+				return {
+					...super.defaults,
+					value: "default",
+					flag: false,
+					count: 0,
+					templates: {
+						main: '<span data-monster-replace="path:value"></span>',
+					},
+				};
+			}
+			get customization() {
+				return new Map([["value", "custom"]]);
+			}
+			[api.initMethodSymbol]() {
+				super[api.initMethodSymbol]();
+				this.initialValue = this.getOption("value");
+			}
+			[api.assembleMethodSymbol]() {
+				assemblies++;
+				super[api.assembleMethodSymbol]();
+				this.assembledValue = this.getOption("value");
+			}
+		}
+		const element = document.createElement(register(Configured));
+		expect(element.initialValue).to.equal("custom");
+		element.setOption("value", "runtime-before-connect");
+		element.setAttribute("data-monster-option-value", "attribute");
+		element.setAttribute("data-monster-option-flag", "true");
+		element.setAttribute("data-monster-option-count", "7");
+		element.setAttribute("data-monster-options", '{"value":"json"}');
+		const script = document.createElement("script");
+		script.type = "application/json";
+		script.id = "options-script-596";
+		script.textContent = '{"value":"script"}';
+		fixture.append(script);
+		element.setAttribute(
+			"data-monster-options-selector",
+			"#options-script-596",
+		);
+		fixture.append(element);
+		await tick();
+		expect(element.assembledValue).to.equal("script");
+		expect(element.getOption("flag")).to.equal(true);
+		expect(element.getOption("count")).to.equal(7);
+		expect(element.shadowRoot.querySelector("span").textContent).to.equal(
+			"script",
+		);
+		element.removeAttribute("data-monster-option-value");
+		await tick();
+		element.setOption("value", "runtime");
+		await tick();
+		expect(element.shadowRoot.querySelector("span").textContent).to.equal(
+			"runtime",
+		);
+		element.remove();
+		script.textContent = '{"value":"must-not-reload"}';
+		fixture.append(element);
+		await tick();
+		expect(assemblies).to.equal(1);
+		expect(element.getOption("value")).to.equal("runtime");
+		element.setOption("value", "reconnected");
+		await tick();
+		expect(element.shadowRoot.querySelector("span").textContent).to.equal(
+			"reconnected",
+		);
+		expect(element.hasAttribute("data-monster-error")).to.equal(false);
+	});
+});

package/test/cases/packaging.mjs

@@ -27,6 +27,10 @@ function readBuildNix() {
 	return readFileSync(join(projectRoot, "nix/scripts/build.nix"), "utf8");
 }
 
+function readProjectFile(path) {
+	return readFileSync(join(projectRoot, path), "utf8");
+}
+
 describe("Packaging issue #577", function () {
 	describe("exports map", function () {
 		it("should resolve every literal export target to an existing file", function () {
@@ -161,6 +165,62 @@ describe("Packaging issue #577", function () {
 				).to.be.true;
 			}
 		});
+
+		it("should ship and export the Monster 5 migration guide", function () {
+			const migrationPath = "documentation/migrations/monster-5-options.md";
+			const pkg = readPackageJson();
+			const buildNix = readBuildNix();
+
+			expect(pkg.files).to.include(migrationPath);
+			expect(pkg.exports[`./${migrationPath}`]).to.equal(`./${migrationPath}`);
+			expect(existsSync(join(projectRoot, migrationPath))).to.be.true;
+			expect(buildNix).to.include(migrationPath);
+			expect(buildNix).to.include(`package/${migrationPath}`);
+		});
+	});
+
+	describe("Monster 5 migration contract", function () {
+		it("should document the strict lifecycle and migration phases", function () {
+			const guide = readProjectFile(
+				"documentation/migrations/monster-5-options.md",
+			);
+
+			for (const contract of [
+				"OptionsNotInitializedError",
+				"getOption()",
+				"setOption()",
+				"setOptions()",
+				"defaults",
+				"customization",
+				"document.createElement()",
+				"initMethodSymbol",
+				"assembleMethodSymbol",
+				"There is no compatibility switch",
+			]) {
+				expect(guide, `migration guide is missing ${contract}`).to.include(
+					contract,
+				);
+			}
+		});
+
+		it("should describe the breaking change in the 5.0.0 changelog", function () {
+			const changelog = readProjectFile("CHANGELOG.md");
+			const release = changelog
+				.split("## [5.0.0]")[1]
+				.split("## [4.154.12]")[0];
+
+			for (const contract of [
+				"### Breaking Changes",
+				"OptionsNotInitializedError",
+				"initMethodSymbol",
+				"assembleMethodSymbol",
+				"documentation/migrations/monster-5-options.md",
+			]) {
+				expect(release, `5.0.0 changelog is missing ${contract}`).to.include(
+					contract,
+				);
+			}
+		});
 	});
 
 	describe("generated barrel", function () {

package/test/util/early-options.mjs

@@ -0,0 +1,84 @@
+import { parse } from "espree";
+
+const optionMethods = new Set(["getOption", "setOption", "setOptions"]);
+const functions = new Set([
+	"FunctionDeclaration",
+	"FunctionExpression",
+	"ArrowFunctionExpression",
+]);
+const children = (node) =>
+	Object.values(node)
+		.flat()
+		.filter((value) => value && typeof value.type === "string");
+const property = (node) =>
+	node.computed ? node.property?.value : node.property?.name;
+
+// A conservative local call-graph check. Imported/dynamic dispatch is covered
+// by the actual component construction tests, not claimed as statically proven.
+export function findEarlyOptions(source) {
+	const ast = parse(source, {
+		ecmaVersion: "latest",
+		sourceType: "module",
+		loc: true,
+	});
+	const helpers = new Map();
+	const getters = [];
+	function collect(node, methods = new Map()) {
+		if (node.type === "ClassBody") {
+			methods = new Map(
+				node.body
+					.filter((entry) => !entry.computed && entry.value)
+					.map((entry) => [entry.key.name, entry.value]),
+			);
+		}
+		if (node.type === "FunctionDeclaration" && node.id)
+			helpers.set(node.id.name, node);
+		if (node.type === "VariableDeclarator" && functions.has(node.init?.type))
+			helpers.set(node.id.name, node.init);
+		if (
+			node.type === "MethodDefinition" &&
+			node.kind === "get" &&
+			["defaults", "customization"].includes(node.key.name)
+		) {
+			getters.push({ node, methods });
+		}
+		for (const child of children(node)) collect(child, methods);
+	}
+	collect(ast);
+	const failures = [];
+	for (const { node: getter, methods } of getters) {
+		const visited = new Set();
+		function execute(fn) {
+			if (!fn || visited.has(fn)) return;
+			visited.add(fn);
+			walk(fn.body);
+		}
+		function walk(node) {
+			if (!node || functions.has(node.type)) return; // callbacks are deferred unless invoked
+			if (node.type === "CallExpression") {
+				let callee = node.callee;
+				if (
+					callee.type === "MemberExpression" &&
+					["call", "apply"].includes(property(callee))
+				)
+					callee = callee.object;
+				if (callee.type === "MemberExpression") {
+					const name = property(callee);
+					if (optionMethods.has(name))
+						failures.push({
+							phase: getter.key.name,
+							method: name,
+							line: node.loc.start.line,
+						});
+					if (callee.object.type === "ThisExpression")
+						execute(methods.get(name));
+				} else if (callee.type === "Identifier")
+					execute(helpers.get(callee.name));
+				else if (functions.has(callee.type)) execute(callee);
+			}
+			for (const child of children(node)) walk(child);
+		}
+		execute(getter.value);
+	}
+	return failures;
+}