[docs] code clarifications around CSS rendering (#3940)

* [docs] code clarifications around CSS rendering

* revert variable rename and add a couple more comments

* hoist index lookup logic

Co-authored-by: Rich Harris <hello@rich-harris.dev>

packages/kit/src/core/build/build_client.js

@@ -89,6 +89,11 @@ export async function build_client({
 		plugins: [
 			svelte({
 				extensions: config.extensions,
+				// In AMP mode, we know that there are no conditional component imports. In that case, we
+				// don't need to include CSS for components that are imported but unused, so we can just
+				// include rendered CSS.
+				// This would also apply if hydrate and router are both false, but we don't know if one
+				// has been enabled at the page level, so we don't do anything there.
 				emitCss: !config.kit.amp,
 				compilerOptions: {
 					hydratable: !!config.kit.browser.hydrate

packages/kit/src/core/dev/index.js

@@ -61,6 +61,11 @@ export async function dev({ cwd, port, host, https, config }) {
 		plugins: [
 			svelte({
 				extensions: config.extensions,
+				// In AMP mode, we know that there are no conditional component imports. In that case, we
+				// don't need to include CSS for components that are imported but unused, so we can just
+				// include rendered CSS.
+				// This would also apply if hydrate and router are both false, but we don't know if one
+				// has been enabled at the page level, so we don't do anything there.
 				emitCss: !config.kit.amp,
 				compilerOptions: {
 					hydratable: !!config.kit.browser.hydrate

packages/kit/src/core/dev/plugin.js

@@ -98,6 +98,7 @@ export async function create_plugin(config, cwd) {
 									entry: url.endsWith('.svelte') ? url : url + '?import',
 									css: [],
 									js: [],
+									// in dev we inline all styles to avoid FOUC
 									styles
 								};
 							};

packages/kit/src/core/generate_manifest/index.js

@@ -13,6 +13,8 @@ export function generate_manifest(
 	routes = build_data.manifest_data.routes,
 	format = 'esm'
 ) {
+	/** @typedef {{ index: number, path: string }} LookupEntry */
+	/** @type {Map<string, LookupEntry>} */
 	const bundled_nodes = new Map();
 
 	// 0 and 1 are special, they correspond to the root layout and root error nodes
@@ -52,6 +54,9 @@ export function generate_manifest(
 		assets.push(build_data.service_worker);
 	}
 
+	/** @param {string} id */
+	const get_index = (id) => id && /** @type {LookupEntry} */ (bundled_nodes.get(id)).index;
+
 	// prettier-ignore
 	return `{
 		appDir: ${s(build_data.app_dir)},
@@ -71,8 +76,8 @@ export function generate_manifest(
 							params: ${get_params(route.params)},
 							path: ${route.path ? s(route.path) : null},
 							shadow: ${route.shadow ? importer(`${relative_path}/${build_data.server.vite_manifest[route.shadow].file}`) : null},
-							a: ${s(route.a.map(component => component && bundled_nodes.get(component).index))},
-							b: ${s(route.b.map(component => component && bundled_nodes.get(component).index))}
+							a: ${s(route.a.map(get_index))},
+							b: ${s(route.b.map(get_index))}
 						}`.replace(/^\t\t/gm, '');
 					} else {
 						if (!build_data.server.vite_manifest[route.file]) {

packages/kit/src/runtime/server/page/render.js

@@ -189,12 +189,15 @@ export async function render_response({
 	`;
 
 	if (options.amp) {
+		// inline_style contains CSS files (i.e. `import './styles.css'`)
+		// rendered.css contains the CSS from `<style>` tags in Svelte components
+		const styles = `${inlined_style}\n${rendered.css.code}`;
 		head += `
 		<style amp-boilerplate>body{-webkit-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-moz-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-ms-animation:-amp-start 8s steps(1,end) 0s 1 normal both;animation:-amp-start 8s steps(1,end) 0s 1 normal both}@-webkit-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-moz-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-ms-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-o-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}</style>
 		<noscript><style amp-boilerplate>body{-webkit-animation:none;-moz-animation:none;-ms-animation:none;animation:none}</style></noscript>
 		<script async src="https://cdn.ampproject.org/v0.js"></script>
 
-		<style amp-custom>${inlined_style}\n${rendered.css.code}</style>`;
+		<style amp-custom>${styles}</style>`;
 
 		if (options.service_worker) {
 			head +=
@@ -226,6 +229,8 @@ export async function render_response({
 				}
 
 				if (styles.has(dep)) {
+					// don't load stylesheets that are already inlined
+					// include them in disabled state so that Vite can detect them and doesn't try to add them
 					attributes.push('disabled', 'media="(max-width: 0)"');
 				}