docs: clarify options_missing_custom_element warning regarding ShadowRoot CSS extraction (#18199)

.changeset/clarify-options-missing-custom-element.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+docs: clarify `options_missing_custom_element` warning regarding ShadowRoot CSS extraction

documentation/docs/98-reference/.generated/compile-warnings.md

@@ -776,7 +776,7 @@ The `immutable` option has been deprecated. It will have no effect in runes mode
 ### options_missing_custom_element
 
 ```
-The `customElement` option is used when generating a custom element. Did you forget the `customElement: true` compile option?
+The `customElement` option is used when generating a custom element, but `customElement: true` (or `css: 'injected'`) is not set in compiler options. If child components are rendered inside a ShadowRoot, their styles will be extracted externally and will not be visible inside the shadow tree. Set `compilerOptions.customElement: true` (or `css: 'injected'`) in `svelte.config.js`
 ```
 
 ### options_removed_enable_sourcemap

packages/svelte/messages/compile-warnings/options.md

@@ -8,7 +8,7 @@
 
 ## options_missing_custom_element
 
-> The `customElement` option is used when generating a custom element. Did you forget the `customElement: true` compile option?
+> The `customElement` option is used when generating a custom element, but `customElement: true` (or `css: 'injected'`) is not set in compiler options. If child components are rendered inside a ShadowRoot, their styles will be extracted externally and will not be visible inside the shadow tree. Set `compilerOptions.customElement: true` (or `css: 'injected'`) in `svelte.config.js`
 
 ## options_removed_enable_sourcemap
 

packages/svelte/src/compiler/warnings.js

@@ -556,11 +556,11 @@ export function options_deprecated_immutable(node) {
 }
 
 /**
- * The `customElement` option is used when generating a custom element. Did you forget the `customElement: true` compile option?
+ * The `customElement` option is used when generating a custom element, but `customElement: true` (or `css: 'injected'`) is not set in compiler options. If child components are rendered inside a ShadowRoot, their styles will be extracted externally and will not be visible inside the shadow tree. Set `compilerOptions.customElement: true` (or `css: 'injected'`) in `svelte.config.js`
  * @param {null | NodeLike} node
  */
 export function options_missing_custom_element(node) {
-	w(node, 'options_missing_custom_element', `The \`customElement\` option is used when generating a custom element. Did you forget the \`customElement: true\` compile option?\nhttps://svelte.dev/e/options_missing_custom_element`);
+	w(node, 'options_missing_custom_element', `The \`customElement\` option is used when generating a custom element, but \`customElement: true\` (or \`css: 'injected'\`) is not set in compiler options. If child components are rendered inside a ShadowRoot, their styles will be extracted externally and will not be visible inside the shadow tree. Set \`compilerOptions.customElement: true\` (or \`css: 'injected'\`) in \`svelte.config.js\`\nhttps://svelte.dev/e/options_missing_custom_element`);
 }
 
 /**

packages/svelte/tests/validator/samples/custom-element-props-identifier-props-option/warnings.json

@@ -5,7 +5,7 @@
 			"column": 2,
 			"line": 3
 		},
-		"message": "The `customElement` option is used when generating a custom element. Did you forget the `customElement: true` compile option?",
+		"message": "The `customElement` option is used when generating a custom element, but `customElement: true` (or `css: 'injected'`) is not set in compiler options. If child components are rendered inside a ShadowRoot, their styles will be extracted externally and will not be visible inside the shadow tree. Set `compilerOptions.customElement: true` (or `css: 'injected'`) in `svelte.config.js`",
 		"start": {
 			"column": 16,
 			"line": 1

packages/svelte/tests/validator/samples/custom-element-props-identifier-rest/warnings.json

@@ -5,7 +5,7 @@
 			"column": 34,
 			"line": 1
 		},
-		"message": "The `customElement` option is used when generating a custom element. Did you forget the `customElement: true` compile option?",
+		"message": "The `customElement` option is used when generating a custom element, but `customElement: true` (or `css: 'injected'`) is not set in compiler options. If child components are rendered inside a ShadowRoot, their styles will be extracted externally and will not be visible inside the shadow tree. Set `compilerOptions.customElement: true` (or `css: 'injected'`) in `svelte.config.js`",
 		"start": {
 			"column": 16,
 			"line": 1

packages/svelte/tests/validator/samples/custom-element-props-identifier/warnings.json

@@ -5,7 +5,7 @@
 			"column": 34,
 			"line": 1
 		},
-		"message": "The `customElement` option is used when generating a custom element. Did you forget the `customElement: true` compile option?",
+		"message": "The `customElement` option is used when generating a custom element, but `customElement: true` (or `css: 'injected'`) is not set in compiler options. If child components are rendered inside a ShadowRoot, their styles will be extracted externally and will not be visible inside the shadow tree. Set `compilerOptions.customElement: true` (or `css: 'injected'`) in `svelte.config.js`",
 		"start": {
 			"column": 16,
 			"line": 1

packages/svelte/tests/validator/samples/tag-custom-element-options-missing/warnings.json

@@ -1,7 +1,7 @@
 [
 	{
 		"code": "options_missing_custom_element",
-		"message": "The `customElement` option is used when generating a custom element. Did you forget the `customElement: true` compile option?",
+		"message": "The `customElement` option is used when generating a custom element, but `customElement: true` (or `css: 'injected'`) is not set in compiler options. If child components are rendered inside a ShadowRoot, their styles will be extracted externally and will not be visible inside the shadow tree. Set `compilerOptions.customElement: true` (or `css: 'injected'`) in `svelte.config.js`",
 		"start": {
 			"line": 1,
 			"column": 16