@stencil/core 5.0.0-beta.34 → 5.0.0-beta.36

package/dist/{compiler-CVL510L-.mjs → compiler-DHNkXDvK.mjs}

@@ -1,9 +1,9 @@
 import { n as __require } from "./rolldown-runtime-BhDjJH2R.mjs";
-import { E as SERVER_BUILD_FLAGS, T as HYDRATED_CSS, w as CLIENT_BUILD_FLAGS } from "./client-UbH-XkYu.mjs";
+import { A as SSR_PROP_REF_PREFIX, D as HYDRATE_ID, E as HYDRATE_CHILD_ID, O as SERVER_BUILD_FLAGS, T as HYDRATED_CSS, k as SSR_PROPS_REGISTRY_KEY, w as CLIENT_BUILD_FLAGS } from "./client-CqQpuOUk.mjs";
 import { $ as VALID_CONFIG_OUTPUT_TARGETS, A as DIST_LAZY, D as COPY, E as COLLECTION_MANIFEST_FILE_NAME, J as STANDALONE, L as EVENT_FLAGS, P as DOCS_JSON, Q as TYPES, R as GENERATED_DTS, S as ASSETS, T as COLLECTION_APP_DATA_FILE_NAME, U as LOADER_BUNDLE, X as STYLE_EXT, Y as STATS, a as isBoolean$1, b as unique, c as isFunction, d as isObject, et as WATCH_FLAGS, f as isString$1, g as sortBy, i as fromEntries, l as isIterable, m as noop, p as mergeIntoWith, r as flatOne, t as dashToPascalCase, u as isNumber$1, v as toDashCase, w as COLLECTION, y as toTitleCase, z as GLOBAL_STYLE } from "./helpers-Cpp3qc3u.mjs";
 import { E as escapeRegExpSpecialCharacters, S as formatComponentRuntimeMeta, T as byteSize, _ as loadRolldownDiagnostics, a as getSourceMappingUrlForEndOfFile, b as splitLineBreaks, c as err, f as augmentDiagnosticWithNode, g as isRolldownError, h as createOnWarnFn, i as getInlineSourceMappingUrlLinker, l as map, m as loadTypeScriptDiagnostics, n as validateComponentTag, p as loadTypeScriptDiagnostic, r as isRemoteUrl, s as rolldownToStencilSourceMap, t as validateComponentModes, u as ok, w as stringifyRuntimeData, x as isRootPath, y as normalizeDiagnostics } from "./validation-BlVm1Vu0.mjs";
 import { $ as buildWarn, A as isOutputTargetDocsVscode, B as isValidConfigOutputTarget, C as isOutputTargetDistLazy, D as isOutputTargetDocsCustomElementsManifest, E as isOutputTargetDocsCustom, F as isOutputTargetSsrWasm, G as normalizeFsPath, H as shouldExcludeComponent, I as isOutputTargetStandalone, J as relative$1, K as normalizeFsPathQuery, L as isOutputTargetStats, M as isOutputTargetLoaderBundle, N as isOutputTargetServerRenderer, O as isOutputTargetDocsJson, P as isOutputTargetSsr, Q as buildJsonFileError, R as isOutputTargetTypes, S as isOutputTargetCustom, T as isOutputTargetDocsAgentSkill, U as join$2, V as relativeImport, Y as resolve$2, Z as buildError, a as hasDependency, b as isOutputTargetCollection, d as parsePackageJson, et as catchError, f as readOnlyArrayHasStringMember, g as getComponentsDtsSrcFilePath, h as filterExcludedComponents, i as getTextDocs, it as isGlob, j as isOutputTargetGlobalStyle, k as isOutputTargetDocsReadme, l as isTsFile, m as filterActiveTargets, n as createJsVarName, nt as hasWarning, o as isDtsFile, p as readPackageJson, q as normalizePath, r as generatePreamble, t as addDocBlock, tt as hasError, u as isTsxFile, v as getComponentsFromModules, w as isOutputTargetDocs, x as isOutputTargetCopy, y as isOutputTargetAssets, z as isOutputTargetWww } from "./util-C-H1H84W.mjs";
-import { i as CustomElementsExportBehaviorOptions, o as buildEvents, r as createNodeLogger, t as createNodeSys } from "./node-eg7pofz5.mjs";
+import { i as CustomElementsExportBehaviorOptions, o as buildEvents, r as createNodeLogger, t as createNodeSys } from "./node-DwwBX_GL.mjs";
 import ts, { default as ts$1 } from "typescript";
 import { readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
@@ -461,9 +461,9 @@ const scopeCss = (cssText, scopeId, commentOriginalSelector) => {
 };
 //#endregion
 //#region src/version.ts
-const version = "5.0.0-beta.34";
-const buildId = "1793980027";
-const vermoji = "🦀";
+const version = "5.0.0-beta.36";
+const buildId = "1794253443";
+const vermoji = "🌎";
 /**
 * Get the installed version of a tool/dependency.
 * Handles packages with exports maps that point to subdirectories.
@@ -3049,6 +3049,9 @@ const objectLiteralToObjectMap = (objectLiteral, typeChecker, diagnostics, error
 				case ts.SyntaxKind.FalseKeyword:
 					val = false;
 					break;
+				case ts.SyntaxKind.NullKeyword:
+					val = null;
+					break;
 				case ts.SyntaxKind.Identifier:
 					const escapedText = propAssignment.initializer.escapedText;
 					if (escapedText === "String") val = String;
@@ -3235,7 +3238,7 @@ const getAllTypeReferences = (checker, node) => {
 */
 const getTypeReferenceLocation = (typeName, type, sourceFile, checker, program) => {
 	const importTypeDeclaration = sourceFile.statements.find((st) => {
-		if (!(ts.isImportDeclaration(st) && st.importClause && ts.isImportClause(st.importClause) && st.importClause.namedBindings && ts.isNamedImports(st.importClause.namedBindings) && Array.isArray(st.importClause.namedBindings.elements) && st.importClause.namedBindings.elements.find((nbe) => nbe.name.getText() === typeName))) return false;
+		if (!(ts.isImportDeclaration(st) && st.importClause && ts.isImportClause(st.importClause) && st.importClause.namedBindings && ts.isNamedImports(st.importClause.namedBindings) && Array.isArray(st.importClause.namedBindings.elements) && st.importClause.namedBindings.elements.find((nbe) => nbe.name.text === typeName))) return false;
 		return true;
 	});
 	const namedImportBindings = importTypeDeclaration?.importClause?.namedBindings;
@@ -3244,7 +3247,7 @@ const getTypeReferenceLocation = (typeName, type, sourceFile, checker, program)
 		const options = program.getCompilerOptions();
 		const importHomeModule = getHomeModule(sourceFile, localImportPath, options, ts.createCompilerHost(options), program);
 		if (importHomeModule) {
-			const importElement = namedImportBindings.elements.find((nbe) => nbe.name.getText() === typeName);
+			const importElement = namedImportBindings.elements.find((nbe) => nbe.name.text === typeName);
 			const importName = importElement.name;
 			const originalTypeName = getOriginalTypeName(importName, checker);
 			const importedAs = importElement.propertyName ? importElement.propertyName.getText() : typeName;
@@ -7705,9 +7708,9 @@ const updateStencilCoreImports = (updatedCoreImportPath) => {
 						}
 						if (moduleSpecifierText === "@stencil/core") {
 							if (s.importClause && s.importClause.namedBindings && s.importClause.namedBindings.kind === ts.SyntaxKind.NamedImports) {
-								const keepImports = s.importClause.namedBindings.elements.map((e) => e.getText()).filter((name) => KEEP_IMPORTS.has(name));
+								const keepImports = s.importClause.namedBindings.elements.filter((e) => KEEP_IMPORTS.has((e.propertyName ?? e.name).text));
 								if (keepImports.length > 0) {
-									const newImport = ts.factory.updateImportDeclaration(s, void 0, ts.factory.createImportClause(false, void 0, ts.factory.createNamedImports(keepImports.map((name) => ts.factory.createImportSpecifier(false, void 0, ts.factory.createIdentifier(name))))), ts.factory.createStringLiteral(updatedCoreImportPath), void 0);
+									const newImport = ts.factory.updateImportDeclaration(s, void 0, ts.factory.createImportClause(false, void 0, ts.factory.createNamedImports(keepImports.map((e) => ts.factory.createImportSpecifier(false, e.propertyName ? ts.factory.createIdentifier(e.propertyName.text) : void 0, ts.factory.createIdentifier(e.name.text))))), ts.factory.createStringLiteral(updatedCoreImportPath), void 0);
 									newStatements.push(newImport);
 								}
 							}
@@ -12524,10 +12527,44 @@ const SSR_FACTORY_INTRO = `
 // Used for the hydrate timeout timer to avoid being affected by constrainTimeouts.
 var $nativeSetTimeout = (typeof globalThis !== 'undefined' ? globalThis : global).setTimeout;
 var $nativeClearTimeout = (typeof globalThis !== 'undefined' ? globalThis : global).clearTimeout;
+// Holds the \`ssrProp()\` registry, which template code writes to outside the factory.
+var $stencilNativeGlobal = typeof globalThis !== 'undefined' ? globalThis : global;
 // Used to abort in-flight fetch() calls and to call any user defined AbortControllers when ssr times out.
 var $stencilNativeAbortController = AbortController;
 
+// Evaluated SSR platforms, per window and per serializeShadowRoot mode. Evaluating the platform
+// (runtime, vdom and every component class) is the main fixed cost of a render, so a window that's
+// rendered into again (see the \`reuseWindow\` option) reuses it. A new window gets a new platform.
+var $stencilSsrApps = new WeakMap();
+
 export function ssrFactory($stencilWindow, $stencilHydrateOpts, $stencilHydrateResults, $stencilAfterHydrate, $stencilHydrateResolve) {
+  // Rendering shadow components as scoped permanently changes their metadata inside the platform,
+  // so a platform is only shared by renders whose serializeShadowRoot marks the same components as
+  // scoped: keyed by the canonical key the renderer computes for it.
+  var $stencilShadowModeKey = $stencilHydrateOpts.serializeShadowRootKey;
+  var $stencilApp;
+  if (typeof $stencilShadowModeKey !== 'string') {
+    $stencilApp = $stencilCreateSsrApp($stencilWindow);
+  } else {
+    var $stencilWindowApps = $stencilSsrApps.get($stencilWindow);
+    if (!$stencilWindowApps) {
+      $stencilWindowApps = new Map();
+      $stencilSsrApps.set($stencilWindow, $stencilWindowApps);
+    }
+    $stencilApp = $stencilWindowApps.get($stencilShadowModeKey);
+    if (!$stencilApp) {
+      $stencilApp = $stencilCreateSsrApp($stencilWindow);
+      $stencilWindowApps.set($stencilShadowModeKey, $stencilApp);
+    }
+  }
+  $stencilApp($stencilHydrateOpts, $stencilHydrateResults, $stencilAfterHydrate, $stencilHydrateResolve);
+}
+
+/**
+ * Evaluates the SSR platform for a window, and returns a function that renders with it.
+ * Renders using the same platform must run one at a time.
+ */
+function $stencilCreateSsrApp($stencilWindow) {
   var globalThis = $stencilWindow;
   var self = $stencilWindow;
   var top = $stencilWindow;
@@ -12616,7 +12653,9 @@ export function ssrFactory($stencilWindow, $stencilHydrateOpts, $stencilHydrateR
   // Aborted when the render times out or errors, so in-flight fetch() calls
   // made by component code stop holding the render's window/results alive
   // instead of running to completion against a torn-down window. See #6864.
-  var $stencilAbortController = new $stencilNativeAbortController();
+  // A new one is created for every render (see the function returned below),
+  // so one render's timeout never cancels the next render's work.
+  var $stencilAbortController;
 
   // Any AbortController a component creates itself is transparently wired to
   // cascade-abort when the render times out too, so component code using the
@@ -12688,10 +12727,19 @@ export function ssrFactory($stencilWindow, $stencilHydrateOpts, $stencilHydrateR
 `;
 const SSR_FACTORY_OUTRO = `
     /*hydrateAppClosure end*/
-    ssrApp(window, $stencilHydrateOpts, $stencilHydrateResults, $stencilAfterHydrate, $stencilHydrateResolve, $stencilAbortController);
+    return function ($stencilHydrateOpts, $stencilHydrateResults, $stencilAfterHydrate, $stencilHydrateResolve) {
+      $stencilAbortController = new $stencilNativeAbortController();
+      // a reused window is reset between renders, which removes these; put them back
+      $stencilWindow.fetch = fetch;
+      $stencilWindow.FetchError = FetchError;
+      $stencilWindow.Headers = Headers;
+      $stencilWindow.Request = Request;
+      $stencilWindow.Response = Response;
+      ssrApp(window, $stencilHydrateOpts, $stencilHydrateResults, $stencilAfterHydrate, $stencilHydrateResolve, $stencilAbortController);
+    };
   }
 
-  hydrateAppClosure($stencilWindow);
+  return hydrateAppClosure($stencilWindow);
 }
 `;
 //#endregion
@@ -12805,6 +12853,7 @@ const writeSsrOutput = async (config, compilerCtx, buildCtx, outputTarget, rolld
 	const hydrateAppDirPath = outputTarget.dir;
 	if (!hydrateAppDirPath) throw new Error(`outputTarget config missing the "dir" property`);
 	await copySsrRunnerDts(config, compilerCtx, hydrateAppDirPath);
+	await writeSsrPropModule(compilerCtx, hydrateAppDirPath, outputTarget.cjs === true);
 	buildCtx.ssrAppFilePath = join$2(hydrateAppDirPath, "index.js");
 	const minify = outputTarget.minify === true;
 	await Promise.all(rolldownOutput.output.map(async (output) => {
@@ -12828,7 +12877,86 @@ const copySsrRunnerDts = async (config, compilerCtx, hydrateAppDirPath) => {
 	const packageDir = join$2(config.sys.getCompilerExecutingPath(), "..", "..");
 	const srcSsrDir = join$2(packageDir, "runtime", "server", "runner.d.mts");
 	const runnerDtsDestPath = join$2(hydrateAppDirPath, "index.d.ts");
-	await compilerCtx.fs.copyFile(srcSsrDir, runnerDtsDestPath);
+	const dts = await config.sys.readFile(srcSsrDir);
+	if (dts == null) return;
+	await compilerCtx.fs.writeFile(runnerDtsDestPath, stripSideEffectImports(dts), { immediateWrite: true });
+};
+/**
+* The bundled runner types keep bare imports (`import "rolldown";`) of modules whose types were
+* tree-shaken away. They declare nothing, but a library's consumers won't have those packages
+* (often not even `@stencil/core`), which breaks under `noUncheckedSideEffectImports`.
+* @param dts the runner's `.d.mts` contents
+* @returns the contents without bare imports
+*/
+const stripSideEffectImports = (dts) => dts.replace(/^import\s*["'][^"']+["'];?[ \t]*\r?\n/gm, "");
+const SSR_PROP_JS = `const PREFIX = ${JSON.stringify(SSR_PROP_REF_PREFIX)};
+const REGISTRY = Symbol.for(${JSON.stringify(SSR_PROPS_REGISTRY_KEY)});
+// a value nothing picked up (the page never reached renderToString()) is dropped after this long
+const TTL = 60000;
+let nextSweep = 0;
+
+/**
+ * Pass a value to a component's property from a framework template, so it reaches the component
+ * when it's rendered on the server too. In the browser, returns the value. On the server, keeps
+ * the value and returns a reference to it, which the template renders as an attribute and the
+ * SSR module (in the same process) turns back into the value. Getting it on to the browser is the
+ * prop's job: @Prop({ serialize: 'json' }), or a @PropSerialize() / @AttrDeserialize() pair.
+ */
+export function ssrProp(value) {
+  if (typeof window !== 'undefined') return value;
+  const registry = globalThis[REGISTRY] || (globalThis[REGISTRY] = new Map());
+  const now = Date.now();
+  if (now > nextSweep) {
+    nextSweep = now + TTL;
+    for (const [id, entry] of registry) if (entry.expires < now) registry.delete(id);
+  }
+  const id = globalThis.crypto && globalThis.crypto.randomUUID
+    ? globalThis.crypto.randomUUID()
+    : Math.random().toString(36).slice(2) + now.toString(36);
+  registry.set(id, { value, expires: now + TTL });
+  return PREFIX + id;
+}
+`;
+const SSR_PROP_DTS = `/**
+ * Pass a value to a component's property from a framework template, so it reaches the component
+ * when it's rendered on the server too.
+ *
+ * \`\`\`vue
+ * <my-chart :data="ssrProp(data)" />
+ * \`\`\`
+ *
+ * In the browser, returns the value. On the server, keeps the value and returns a reference to it
+ * (a string the template renders as an attribute), which the SSR module turns back into the
+ * value. Nothing is serialized, so any value works: a \`Map\`, a \`Date\`, a class instance.
+ *
+ * The SSR module must render the page in the same process, soon after the template runs: the
+ * whole-document \`renderToString()\` hook every framework integration uses.
+ *
+ * This gets the value into the server render only. For the component to have it when it first
+ * renders in the browser too, before the framework sets the property, the prop needs to carry it
+ * in its attribute: \`@Prop({ serialize: 'json' })\`, or a \`@PropSerialize()\` /
+ * \`@AttrDeserialize()\` pair for other formats. Without either, \`renderToString()\` adds a
+ * warning to its \`diagnostics\`.
+ * @param value the property value
+ * @returns \`value\` in the browser, a reference to it (a string) typed as \`T\` on the server
+ */
+export declare function ssrProp<T>(value: T): T;
+`;
+/**
+* Write `ssr-prop.js` (`./ssr-prop` in export maps): `ssrProp()`, for framework templates. It runs
+* on both server and client, so it's separate from the server-only SSR module.
+* @param compilerCtx the compiler context
+* @param dir the ssr output directory
+* @param cjs whether to also write a CommonJS copy
+*/
+const writeSsrPropModule = async (compilerCtx, dir, cjs) => {
+	const opts = { immediateWrite: true };
+	await compilerCtx.fs.writeFile(join$2(dir, "ssr-prop.js"), SSR_PROP_JS, opts);
+	await compilerCtx.fs.writeFile(join$2(dir, "ssr-prop.d.ts"), SSR_PROP_DTS, opts);
+	if (cjs) {
+		const cjsCode = SSR_PROP_JS.replace("export function ssrProp", "function ssrProp") + "exports.ssrProp = ssrProp;\n";
+		await compilerCtx.fs.writeFile(join$2(dir, "ssr-prop.cjs"), cjsCode, opts);
+	}
 };
 //#endregion
 //#region src/compiler/output-targets/ssr/generate-ssr-app.ts
@@ -12941,10 +13069,42 @@ const generateSsrFactoryEntry = async (buildCtx) => {
 	return s.toString();
 };
 //#endregion
+//#region src/compiler/output-targets/ssr/validate-reserved-attributes.ts
+/** Attributes server rendering writes on component hosts and the nodes they render. */
+const SSR_ATTRIBUTES = /* @__PURE__ */ new Set([
+	HYDRATE_ID,
+	HYDRATE_CHILD_ID,
+	"s-sn",
+	"s-mode"
+]);
+/**
+* Report props whose attribute would collide with one server rendering writes (`@Prop() sId` is
+* `s-id`): the server would overwrite or remove the value and the client would misread it. Only
+* relevant to builds that render on a server, so it's run by the `ssr` and `ssr-wasm` outputs.
+*
+* Complex props have no attribute of their own, but templates bind `ssrProp()` values under the
+* dash-cased prop name, so that's checked too.
+*
+* @param config the validated config
+* @param buildCtx the current build context
+*/
+const validateSsrReservedAttributes = (config, buildCtx) => {
+	for (const cmp of buildCtx.components) for (const prop of cmp.properties) {
+		const attribute = prop.attribute ?? toDashCase(prop.name);
+		if (!SSR_ATTRIBUTES.has(attribute)) continue;
+		const err = buildError(buildCtx.diagnostics);
+		err.header = "Reserved Attribute Name";
+		err.messageText = `The "${prop.name}" prop of <${cmp.tagName}> uses the attribute "${attribute}", which Stencil writes when it renders on the server. Rename the prop, or give it another attribute name: @Prop({ attribute: '...' }).`;
+		err.absFilePath = cmp.sourceFilePath;
+		err.relFilePath = relative$1(config.rootDir, cmp.sourceFilePath);
+	}
+};
+//#endregion
 //#region src/compiler/output-targets/ssr/index.ts
 const outputSsr = async (config, compilerCtx, buildCtx) => {
 	const ssrOutputTargets = filterActiveTargets(config.outputTargets.filter(isOutputTargetSsr), config.devMode);
 	if (ssrOutputTargets.length > 0) {
+		validateSsrReservedAttributes(config, buildCtx);
 		const timespan = buildCtx.createTimeSpan(`generate SSR app started`);
 		await generateSsrApp(config, compilerCtx, buildCtx, ssrOutputTargets);
 		timespan.finish(`generate SSR app finished`);
@@ -13081,9 +13241,17 @@ const SSR_WASM_INTERFACE = `declare module "main" {
   export function resetSsrDocData(): void;
 }\n`;
 const SSR_WASM_OUTRO = `
+// Whether a renderToString call is in progress. Still true at the start of a call means the last
+// call ended with its render waiting on work that never resolved (see below).
+var $stencilWasmRenderInProgress = false;
+
 module.exports = {
   renderToString: async function() {
     try {
+      if ($stencilWasmRenderInProgress && typeof resetReusableWindows === 'function') {
+        // That render will never finish, so it would hold its reusable window and queue forever.
+        resetReusableWindows();
+      }
       if (typeof renderToString !== 'function') {
         Host.outputString(JSON.stringify({ __error: 'renderToString is ' + typeof renderToString }));
         return;
@@ -13095,15 +13263,20 @@ module.exports = {
       // silence, then overwrite it once renderToString() actually resolves.
       Host.outputString(JSON.stringify({ __error: 'renderToString did not complete - a component may be waiting on work that never resolves' }));
       var opts = inp.options || {};
+      // A plugin instance runs one call at a time, so its renders can always share one window
+      // (see the reuseWindow option). Skips re-evaluating the whole platform on every call.
+      if (typeof opts.reuseWindow !== 'boolean') opts.reuseWindow = true;
       var budget = typeof opts.timeout === 'number' ? opts.timeout : 15000;
       var timers = globalThis.__stencilSsrWasmTimers;
       var render = timers && timers.start(budget, function() {
         Host.outputString(JSON.stringify({ __error: 'renderToString did not complete within the ' + budget + 'ms timeout - a component may be waiting on work that never resolves, on a timer due after the timeout, or on timers it schedules forever' }));
       });
       var result;
+      $stencilWasmRenderInProgress = true;
       try {
-        result = await renderToString(inp.html, inp.options);
+        result = await renderToString(inp.html, opts);
       } finally {
+        $stencilWasmRenderInProgress = false;
         if (render) timers.stop(render);
       }
       // renderToString reports some failures (e.g. input that isn't an HTML string) as an
@@ -13129,6 +13302,9 @@ module.exports = {
       var m = mappings.find(function(x) { return x.from === tag; });
       return m ? m.to : tag;
     });
+    // Platforms register components under their transformed tags when they're set up, so the
+    // reused windows' platforms have to be set up again.
+    if (typeof resetReusableWindows === 'function') resetReusableWindows();
   },
   resetSsrDocData: function() {
     resetSsrDocData();
@@ -13225,6 +13401,7 @@ const compileToWasm = async (buildCtx, jsPath, interfacePath, wasmPath) => {
 const outputSsrWasm = async (config, compilerCtx, buildCtx) => {
 	const ssrWasmTargets = filterActiveTargets(config.outputTargets.filter(isOutputTargetSsrWasm), config.devMode);
 	if (ssrWasmTargets.length > 0) {
+		if (filterActiveTargets(config.outputTargets.filter(isOutputTargetSsr), config.devMode).length === 0) validateSsrReservedAttributes(config, buildCtx);
 		const timespan = buildCtx.createTimeSpan(`generate SSR WASM started`);
 		await generateSsrWasmApp(config, compilerCtx, buildCtx, ssrWasmTargets);
 		timespan.finish(`generate SSR WASM finished`);
@@ -13305,17 +13482,9 @@ const createDefineCase = (tagName, actionExpression) => {
 	return ts.factory.createCaseClause(ts.factory.createStringLiteral(tagName), [ts.factory.createIfStatement(getCheck, ts.factory.createBlock([ts.factory.createExpressionStatement(actionExpression)])), ts.factory.createBreakStatement()]);
 };
 /**
-* Adds the exported `defineCustomElement` function declaration.
+* Adds the exported `defineCustomElement` function declaration. `__stencil_getRegistry()` returns
+* `undefined` where there's no `customElements` (e.g. on a server), so the call is a no-op there.
 *
-* Global path:
-* ```js
-* export function defineCustomElement() {
-*   if (typeof customElements === 'undefined') return;
-*   ['my-comp', ...].forEach(tagName => { switch (tagName) { ... } });
-* }
-* ```
-*
-* Scoped path:
 * ```js
 * export function defineCustomElement(opts) {
 *   const _storeReg = __stencil_getRegistry();
@@ -15838,8 +16007,8 @@ var ImportAliasMap = class extends Map {
 		for (const importDeclaration of importDeclarations) if (importDeclaration.moduleSpecifier.getText().includes("@stencil/core")) {
 			const namedBindings = importDeclaration.importClause?.namedBindings;
 			if (namedBindings && ts.isNamedImports(namedBindings)) for (const element of namedBindings.elements) {
-				const importName = element.name.getText();
-				const originalImportName = element.propertyName?.getText() ?? importName;
+				const importName = element.name.text;
+				const originalImportName = element.propertyName?.text ?? importName;
 				if (STENCIL_DECORATORS.includes(originalImportName)) this.set(originalImportName, importName);
 			}
 		}
@@ -15849,6 +16018,102 @@ var ImportAliasMap = class extends Map {
 	}
 };
 //#endregion
+//#region src/compiler/transformers/decorators-to-static/json-serialize-prop.ts
+/**
+* `@Prop({ serialize: 'json' })` is shorthand for a `@PropSerialize()` / `@AttrDeserialize()` pair
+* that writes the value to the prop's attribute as JSON on the server, and reads it back in the
+* browser. These are the generated methods' names (no leading `_`: the runtime metadata drops
+* those keys), and the alias of the `Build` import they use.
+*/
+const JSON_SERIALIZE_METHOD = "stencilSerializeJson";
+const JSON_DESERIALIZE_METHOD = "stencilDeserializeJson";
+const BUILD_ALIAS = "__stencil_Build";
+/**
+* Find the props declared `@Prop({ serialize: 'json' })`, reporting invalid combinations.
+* @param diagnostics for surfacing errors
+* @param typeChecker a TypeScript typechecker instance
+* @param decoratedMembers the class's decorated members
+* @param propDecoratorName the name `@Prop` is imported as
+* @param handWritten serializers and deserializers written with the decorators
+* @returns the names of the props to serialize as JSON
+*/
+const getJsonSerializedProps = (diagnostics, typeChecker, decoratedMembers, propDecoratorName, handWritten) => decoratedMembers.flatMap((member) => {
+	if (!ts.isPropertyDeclaration(member) && !ts.isGetAccessor(member)) return [];
+	const decorator = retrieveTsDecorators(member)?.find(isDecoratorNamed(propDecoratorName));
+	if (!decorator) return [];
+	const [options] = getDecoratorParameters(decorator, typeChecker);
+	if (options?.serialize == null) return [];
+	const { staticName: propName } = tsPropDeclName(member, typeChecker);
+	const error = (messageText) => {
+		const err = buildError(diagnostics);
+		err.messageText = messageText;
+		augmentDiagnosticWithNode(err, decorator);
+	};
+	if (options.serialize !== "json") {
+		error(`@Prop({ serialize }) on "${propName}" must be 'json'. For other formats, use @PropSerialize() and @AttrDeserialize().`);
+		return [];
+	}
+	if (options.attribute === null) {
+		error(`@Prop({ serialize: 'json' }) on "${propName}" needs an attribute to write to, but it has "attribute: null".`);
+		return [];
+	}
+	if (handWritten.some((h) => h.propName === propName)) {
+		error(`"${propName}" has both @Prop({ serialize: 'json' }) and its own @PropSerialize() / @AttrDeserialize(). Use one or the other.`);
+		return [];
+	}
+	return [propName];
+});
+/**
+* The methods `@Prop({ serialize: 'json' })` uses, shared by every such prop in a class:
+*
+* ```ts
+* stencilSerializeJson(value) {
+*   return __stencil_Build.isServer ? JSON.stringify(value) : null;
+* }
+* stencilDeserializeJson(value, propName) {
+*   try {
+*     return JSON.parse(value);
+*   } catch {
+*     if (__stencil_Build.isDev) console.warn(...);
+*     // leave the prop as it is
+*     return __stencil_Build.isServer ? undefined : this[propName];
+*   }
+* }
+* ```
+*
+* The serializer only writes on the server, like a hand-written one should: in the browser the
+* attribute's job is done, and rewriting it on every change would be wasted work.
+* @returns the two method declarations
+*/
+const createJsonSerializerMethods = () => {
+	const f = ts.factory;
+	const build = (flag) => f.createPropertyAccessExpression(f.createIdentifier(BUILD_ALIAS), flag);
+	const jsonCall = (method, arg) => f.createCallExpression(f.createPropertyAccessExpression(f.createIdentifier("JSON"), method), void 0, [arg]);
+	const param = (name) => f.createParameterDeclaration(void 0, void 0, name);
+	const method = (name, params, body) => f.createMethodDeclaration(void 0, void 0, name, void 0, void 0, params.map(param), void 0, f.createBlock(body, true));
+	const serialize = method(JSON_SERIALIZE_METHOD, ["value"], [f.createReturnStatement(f.createConditionalExpression(build("isServer"), void 0, jsonCall("stringify", f.createIdentifier("value")), void 0, f.createNull()))]);
+	const warn = f.createIfStatement(build("isDev"), f.createExpressionStatement(f.createCallExpression(f.createPropertyAccessExpression(f.createIdentifier("console"), "warn"), void 0, [f.createTemplateExpression(f.createTemplateHead("The \""), [f.createTemplateSpan(f.createIdentifier("propName"), f.createTemplateMiddle(`" attribute isn't valid JSON, so the prop was left as it is: `)), f.createTemplateSpan(f.createIdentifier("value"), f.createTemplateTail(""))])])));
+	return [serialize, method(JSON_DESERIALIZE_METHOD, ["value", "propName"], [f.createTryStatement(f.createBlock([f.createReturnStatement(jsonCall("parse", f.createIdentifier("value")))], true), f.createCatchClause(void 0, f.createBlock([warn, f.createReturnStatement(f.createConditionalExpression(build("isServer"), void 0, f.createIdentifier("undefined"), void 0, f.createElementAccessExpression(f.createThis(), f.createIdentifier("propName"))))], true)), void 0)])];
+};
+/**
+* Import `Build` (as {@link BUILD_ALIAS}) from `@stencil/core`, for the generated methods. Added
+* to an existing `@stencil/core` import, which a component's source always has.
+* @param sourceFile the source file
+* @returns the source file with the import
+*/
+const addBuildImport = (sourceFile) => {
+	const f = ts.factory;
+	const specifier = f.createImportSpecifier(false, f.createIdentifier("Build"), f.createIdentifier(BUILD_ALIAS));
+	let added = false;
+	const statements = sourceFile.statements.map((s) => {
+		if (added || !ts.isImportDeclaration(s) || !ts.isStringLiteral(s.moduleSpecifier) || s.moduleSpecifier.text !== "@stencil/core" || !s.importClause?.namedBindings || !ts.isNamedImports(s.importClause.namedBindings) || s.importClause.isTypeOnly) return s;
+		added = true;
+		return f.updateImportDeclaration(s, s.modifiers, f.updateImportClause(s.importClause, false, s.importClause.name, f.updateNamedImports(s.importClause.namedBindings, [...s.importClause.namedBindings.elements, specifier])), s.moduleSpecifier, s.attributes);
+	});
+	if (!added) statements.unshift(f.createImportDeclaration(void 0, f.createImportClause(false, void 0, f.createNamedImports([specifier])), f.createStringLiteral(STENCIL_CORE_ID)));
+	return f.updateSourceFile(sourceFile, statements);
+};
+//#endregion
 //#region src/compiler/transformers/decorators-to-static/listen-decorator.ts
 const listenDecoratorsToStatic = (diagnostics, typeChecker, decoratedMembers, newMembers, decoratorName) => {
 	const listeners = decoratedMembers.filter(ts.isMethodDeclaration).map((method) => parseListenDecorators(diagnostics, typeChecker, method, decoratorName));
@@ -16262,7 +16527,7 @@ const isTypePromise = (typeStr) => {
 };
 const validateMethods = (diagnostics, members) => {
 	members.filter(ts.isMethodDeclaration).map((method) => {
-		if (method.name.getText() === "componentDidUnload") {
+		if (ts.isIdentifier(method.name) && method.name.text === "componentDidUnload") {
 			const err = buildError(diagnostics);
 			err.header = `Replace "componentDidUnload()" with "disconnectedCallback()"`;
 			err.messageText = `The "componentDidUnload()" method was removed in Stencil 2. Please use the "disconnectedCallback()" method instead.`;
@@ -16627,7 +16892,7 @@ const getPropertyNameText = (name) => {
 };
 //#endregion
 //#region src/compiler/transformers/decorators-to-static/serialize-decorators.ts
-const serializeDecoratorsToStatic = (typeChecker, decoratedProps, newMembers, decoratorName, translateType, propDecoratorName) => {
+const serializeDecoratorsToStatic = (typeChecker, decoratedProps, newMembers, decoratorName, translateType, propDecoratorName, generated = []) => {
 	const props = decoratedProps.filter((prop) => ts.isPropertyDeclaration(prop) || ts.isGetAccessor(prop)).flatMap((prop) => {
 		if (retrieveTsDecorators(prop)?.find(isDecoratorNamed(propDecoratorName))) {
 			const { staticName } = tsPropDeclName(prop, typeChecker);
@@ -16635,7 +16900,7 @@ const serializeDecoratorsToStatic = (typeChecker, decoratedProps, newMembers, de
 		}
 		return [];
 	});
-	const serializers = decoratedProps.filter(ts.isMethodDeclaration).flatMap((method) => parseSerializeDecorator(typeChecker, method, decoratorName, props));
+	const serializers = [...decoratedProps.filter(ts.isMethodDeclaration).flatMap((method) => parseSerializeDecorator(typeChecker, method, decoratorName, props)), ...generated];
 	if (serializers.length > 0) {
 		if (translateType === "PropSerialize") newMembers.push(createStaticGetter("serializers", convertValueToLiteral(serializers)));
 		else newMembers.push(createStaticGetter("deserializers", convertValueToLiteral(serializers)));
@@ -16735,6 +17000,8 @@ const parseWatchDecorator = (typeChecker, method, decoratorName) => {
 * @returns a TypeScript transformer factory which can be passed to
 * TypeScript to transform source code during the compilation process
 */
+/** Source files with a `@Prop({ serialize: 'json' })`, which need a `Build` import. */
+const filesWithJsonProps = /* @__PURE__ */ new WeakSet();
 const convertDecoratorsToStatic = (config, diagnostics, typeChecker, program, includeClassExpressions = false) => {
 	return (transformCtx) => {
 		let sourceFile;
@@ -16744,7 +17011,8 @@ const convertDecoratorsToStatic = (config, diagnostics, typeChecker, program, in
 		};
 		return (tsSourceFile) => {
 			sourceFile = tsSourceFile;
-			return ts.visitEachChild(tsSourceFile, visit, transformCtx);
+			const updated = ts.visitEachChild(tsSourceFile, visit, transformCtx);
+			return filesWithJsonProps.has(tsSourceFile) ? addBuildImport(updated) : updated;
 		};
 	};
 };
@@ -16782,8 +17050,20 @@ const visitClassDeclaration = (config, diagnostics, typeChecker, program, classN
 	const filteredMethodsAndFields = removeStencilMethodDecorators(Array.from(classMembers), diagnostics, importAliasMap);
 	if (componentDecorator && ts.isClassDeclaration(classNode)) componentDecoratorToStatic(config, typeChecker, diagnostics, classNode, filteredMethodsAndFields, componentDecorator);
 	if (decoratedMembers.length > 0) {
-		const serializers = serializeDecoratorsToStatic(typeChecker, decoratedMembers, filteredMethodsAndFields, importAliasMap.get("PropSerialize"), "PropSerialize", importAliasMap.get("Prop"));
-		const deserializers = serializeDecoratorsToStatic(typeChecker, decoratedMembers, filteredMethodsAndFields, importAliasMap.get("AttrDeserialize"), "AttrDeserialize", importAliasMap.get("Prop"));
+		const handWritten = serializeDecoratorsToStatic(typeChecker, decoratedMembers, [], importAliasMap.get("PropSerialize"), "PropSerialize", importAliasMap.get("Prop")).concat(serializeDecoratorsToStatic(typeChecker, decoratedMembers, [], importAliasMap.get("AttrDeserialize"), "AttrDeserialize", importAliasMap.get("Prop")));
+		const jsonProps = getJsonSerializedProps(diagnostics, typeChecker, decoratedMembers, importAliasMap.get("Prop"), handWritten);
+		if (jsonProps.length > 0) {
+			filteredMethodsAndFields.push(...createJsonSerializerMethods());
+			filesWithJsonProps.add(sourceFile);
+		}
+		const serializers = serializeDecoratorsToStatic(typeChecker, decoratedMembers, filteredMethodsAndFields, importAliasMap.get("PropSerialize"), "PropSerialize", importAliasMap.get("Prop"), jsonProps.map((propName) => ({
+			propName,
+			methodName: JSON_SERIALIZE_METHOD
+		})));
+		const deserializers = serializeDecoratorsToStatic(typeChecker, decoratedMembers, filteredMethodsAndFields, importAliasMap.get("AttrDeserialize"), "AttrDeserialize", importAliasMap.get("Prop"), jsonProps.map((propName) => ({
+			propName,
+			methodName: JSON_DESERIALIZE_METHOD
+		})));
 		propDecoratorsToStatic(config, diagnostics, decoratedMembers, typeChecker, program, filteredMethodsAndFields, importAliasMap.get("Prop"), serializers, deserializers);
 		stateDecoratorsToStatic(decoratedMembers, filteredMethodsAndFields, typeChecker, importAliasMap.get("State"));
 		eventDecoratorsToStatic(config, diagnostics, decoratedMembers, typeChecker, program, filteredMethodsAndFields, importAliasMap.get("Event"));
@@ -19030,7 +19310,7 @@ const performAutomaticKeyInsertion = (transformCtx) => {
 	* @returns the result of handling the node
 	*/
 	function findRenderMethodVisitor(node) {
-		if (ts.isMethodDeclaration(node) && node.name.getText() === "render" && numReturnStatements(node) === 1) {
+		if (ts.isMethodDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === "render" && numReturnStatements(node) === 1) {
 			resetKeyCounter();
 			return ts.visitEachChild(node, jsxElementVisitor, transformCtx);
 		} else return ts.visitEachChild(node, findRenderMethodVisitor, transformCtx);
@@ -20392,6 +20672,11 @@ const getGeneratedExports = (config, buildCtx, loaderBundle, standalone, ssr, ty
 			import: `${outDir}/index.js`,
 			require: ssr.cjs ? `${outDir}/index.cjs` : void 0
 		};
+		generated["./ssr-prop"] = {
+			types: `${outDir}/ssr-prop.d.ts`,
+			import: `${outDir}/ssr-prop.js`,
+			require: ssr.cjs ? `${outDir}/ssr-prop.cjs` : void 0
+		};
 	}
 	if (loaderBundle || standalone) {
 		const globalStyles = config.outputTargets.filter(isOutputTargetGlobalStyle);

package/dist/declarations/stencil-public-compiler.d.ts

@@ -2536,6 +2536,16 @@ interface SsrDocumentOptions {
    * Sets `document.referrer`
    */
   referrer?: string;
+  /**
+   * Render into one long-lived mock window, reset between renders, instead of creating a new one
+   * for every call. Skips evaluating the whole SSR platform (runtime and every component)
+   * on each render: most of the cost of rendering a small fragment, and a good part of a whole page.
+   *
+   * Applies to HTML string input (not a `Document`). One window per distinct `serializeShadowRoot` value,
+   * and renders sharing a window run one at a time.
+   * Defaults to `false`, except in the `ssr-wasm` output target, where it defaults to `true`.
+   */
+  reuseWindow?: boolean;
   /**
    * Removes every `<script>` element found in the `document`. Defaults to `false`.
    */
@@ -2672,6 +2682,12 @@ interface SsrFactoryOptions extends SerializeDocumentOptions {
   serializeToHtml: boolean;
   destroyWindow: boolean;
   destroyDocument: boolean;
+  /**
+   * A canonical key for `serializeShadowRoot`, set by the renderer. Renders with the same key
+   * render every component the same way, so they can share an SSR platform.
+   * @internal
+   */
+  serializeShadowRootKey?: string;
 }
 /**
  * Backwards compat for v4

package/dist/declarations/stencil-public-runtime.d.ts

@@ -191,6 +191,16 @@ interface PropOptions {
    * In this case you can set the `reflect` option to `true`, since it defaults to `false`:
    */
   reflect?: boolean;
+  /**
+   * Carry the prop's value from a server render to the browser in its attribute, as JSON:
+   * shorthand for a `@PropSerialize()` that writes `JSON.stringify(value)` on the server and an
+   * `@AttrDeserialize()` that reads it back with `JSON.parse()`. Attribute values that aren't
+   * valid JSON leave the prop as it is (with a warning in dev builds).
+   *
+   * For other formats (a `Map`, a `Date`...), write the `@PropSerialize()` /
+   * `@AttrDeserialize()` pair yourself.
+   */
+  serialize?: 'json';
 }
 interface MethodDecorator {
   (opts?: MethodOptions): CustomMethodDecorator<any>;

package/dist/{index-Da-rNa6f.d.mts → index-CIjtinKD.d.mts}

@@ -1,4 +1,4 @@
-import { ar as RafCallback, cr as TagTransformer, lr as UserBuildConditionals, n as ChildType, nr as ErrorHandler, p as HostElement, rr as FunctionalComponent, sr as ResolutionHandler, ur as VNode, v as PropsType, y as RuntimeRef } from "./index-B0NfYeIA.mjs";
+import { ar as RafCallback, cr as TagTransformer, lr as UserBuildConditionals, n as ChildType, nr as ErrorHandler, p as HostElement, rr as FunctionalComponent, sr as ResolutionHandler, ur as VNode, v as PropsType, y as RuntimeRef } from "./index-DG4wtfhx.mjs";
 //#region src/client/client-build.d.ts
 /**
  * `isDev` / `isTesting` are getters, not copies: the transpile path (e.g. `@stencil/unplugin`)

package/dist/{index-B0NfYeIA.d.mts → index-DG4wtfhx.d.mts}

@@ -2583,6 +2583,16 @@ interface SsrDocumentOptions {
    * Sets `document.referrer`
    */
   referrer?: string;
+  /**
+   * Render into one long-lived mock window, reset between renders, instead of creating a new one
+   * for every call. Skips evaluating the whole SSR platform (runtime and every component)
+   * on each render: most of the cost of rendering a small fragment, and a good part of a whole page.
+   *
+   * Applies to HTML string input (not a `Document`). One window per distinct `serializeShadowRoot` value,
+   * and renders sharing a window run one at a time.
+   * Defaults to `false`, except in the `ssr-wasm` output target, where it defaults to `true`.
+   */
+  reuseWindow?: boolean;
   /**
    * Removes every `<script>` element found in the `document`. Defaults to `false`.
    */
@@ -2719,6 +2729,12 @@ interface SsrFactoryOptions extends SerializeDocumentOptions {
   serializeToHtml: boolean;
   destroyWindow: boolean;
   destroyDocument: boolean;
+  /**
+   * A canonical key for `serializeShadowRoot`, set by the renderer. Renders with the same key
+   * render every component the same way, so they can share an SSR platform.
+   * @internal
+   */
+  serializeShadowRootKey?: string;
 }
 /**
  * Backwards compat for v4