@funstack/static 0.0.2 → 0.0.3

package/README.md

@@ -38,6 +38,18 @@ export default defineConfig({
 });
 ```
 
+## CLI Commands
+
+### `funstack-static-skill-installer`
+
+Installs the `funstack-static-knowledge` skill for AI coding assistants (like [Claude Code](https://docs.anthropic.com/en/docs/claude-code)).
+
+```sh
+npx funstack-static-skill-installer
+```
+
+This command registers the skill that provides AI assistants with knowledge about the FUNSTACK Static framework, including API references, best practices, and architectural guidance. After installation, your AI assistant will be able to better understand and work with your FUNSTACK Static project.
+
 ## Documentation
 
 For detailed API documentation and guides, visit the **[Documentation](https://uhyo.github.io/funstack-static/)**.

package/dist/bin/skill-installer.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/bin/skill-installer.mjs

@@ -0,0 +1,12 @@
+#! /usr/bin/env node
+import path from "node:path";
+import { install } from "@funstack/skill-installer";
+
+//#region src/bin/skill-installer.ts
+const resolved = path.resolve("./node_modules/@funstack/static/skills/funstack-static-knowledge");
+console.log("Installing skill from:", resolved);
+await install(resolved);
+
+//#endregion
+export {  };
+//# sourceMappingURL=skill-installer.mjs.map

package/dist/bin/skill-installer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-installer.mjs","names":[],"sources":["../../src/bin/skill-installer.ts"],"sourcesContent":["#! /usr/bin/env node\n\nimport { install } from \"@funstack/skill-installer\";\nimport path from \"node:path\";\n\nconst skillDir =\n  \"./node_modules/@funstack/static/skills/funstack-static-knowledge\";\n\nconst resolved = path.resolve(skillDir);\n\nconsole.log(\"Installing skill from:\", resolved);\n\nawait install(resolved);\n"],"mappings":";;;;;AAQA,MAAM,WAAW,KAAK,QAFpB,mEAEqC;AAEvC,QAAQ,IAAI,0BAA0B,SAAS;AAE/C,MAAM,QAAQ,SAAS"}

package/dist/build/buildApp.mjs

@@ -21,11 +21,12 @@ async function buildApp(builder, context) {
 	const finalHtmlContent = htmlContent.replaceAll(rscPayloadPlaceholder, mainPayloadPath);
 	await writeFileNormal(path.join(baseDir, "index.html"), finalHtmlContent, context);
 	await writeFileNormal(path.join(baseDir, getRscPayloadPath(mainPayloadHash).replace(/^\//, "")), appRscContent, context);
-	for (const { finalId, finalContent } of components) await writeFileNormal(path.join(baseDir, getModulePathFor(finalId).replace(/^\//, "")), finalContent, context);
+	for (const { finalId, finalContent, name } of components) await writeFileNormal(path.join(baseDir, getModulePathFor(finalId).replace(/^\//, "")), finalContent, context, name);
 }
-async function writeFileNormal(filePath, data, context) {
+async function writeFileNormal(filePath, data, context, name) {
 	await mkdir(path.dirname(filePath), { recursive: true });
-	context.info(`[funstack] Writing ${filePath}`);
+	const nameInfo = name ? ` (${name})` : "";
+	context.info(`[funstack] Writing ${filePath}${nameInfo}`);
 	await writeFile(filePath, data);
 }
 

package/dist/build/buildApp.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"buildApp.mjs","names":[],"sources":["../../src/build/buildApp.ts"],"sourcesContent":["import { mkdir, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport type { ViteBuilder, MinimalPluginContextWithoutEnvironment } from \"vite\";\nimport { rscPayloadPlaceholder, getRscPayloadPath } from \"./rscPath\";\nimport { getModulePathFor } from \"../rsc/rscModule\";\nimport { processRscComponents } from \"./rscProcessor\";\nimport { computeContentHash } from \"./contentHash\";\nimport { drainStream } from \"../util/drainStream\";\n\nexport async function buildApp(\n  builder: ViteBuilder,\n  context: MinimalPluginContextWithoutEnvironment,\n) {\n  const { config } = builder;\n  // import server entry\n  const entryPath = path.join(config.environments.rsc.build.outDir, \"index.js\");\n  const entry: typeof import(\"../rsc/entry\") = await import(\n    pathToFileURL(entryPath).href\n  );\n\n  // render rsc and html\n  const baseDir = config.environments.client.build.outDir;\n  const { html, appRsc, deferRegistry } = await entry.build();\n\n  // Drain HTML stream to string (needed for placeholder replacement later)\n  const htmlContent = await drainStream(html);\n\n  // Process RSC components with content-based hashes for deterministic file names\n  const { components, appRscContent } = await processRscComponents(\n    deferRegistry.loadAll(),\n    appRsc,\n    context,\n  );\n\n  // Compute hash for main RSC payload and apply base path\n  const mainPayloadHash = await computeContentHash(appRscContent);\n  const base = config.base.endsWith(\"/\")\n    ? config.base.slice(0, -1)\n    : config.base;\n  const mainPayloadPath =\n    base === \"/\"\n      ? getRscPayloadPath(mainPayloadHash)\n      : base + getRscPayloadPath(mainPayloadHash);\n\n  // Replace placeholder with final hashed path (including base path)\n  const finalHtmlContent = htmlContent.replaceAll(\n    rscPayloadPlaceholder,\n    mainPayloadPath,\n  );\n\n  // Write HTML with replaced path\n  await writeFileNormal(\n    path.join(baseDir, \"index.html\"),\n    finalHtmlContent,\n    context,\n  );\n\n  // Write main RSC payload with hashed filename\n  await writeFileNormal(\n    path.join(baseDir, getRscPayloadPath(mainPayloadHash).replace(/^\\//, \"\")),\n    appRscContent,\n    context,\n  );\n\n  // Write processed components with hash-based IDs\n  for (const { finalId, finalContent } of components) {\n    const filePath = path.join(\n      baseDir,\n      getModulePathFor(finalId).replace(/^\\//, \"\"),\n    );\n    await writeFileNormal(filePath, finalContent, context);\n  }\n}\n\nasync function writeFileNormal(\n  filePath: string,\n  data: string,\n  context: MinimalPluginContextWithoutEnvironment,\n) {\n  await mkdir(path.dirname(filePath), { recursive: true });\n  context.info(`[funstack] Writing ${filePath}`);\n  await writeFile(filePath, data);\n}\n"],"mappings":";;;;;;;;;;AAUA,eAAsB,SACpB,SACA,SACA;CACA,MAAM,EAAE,WAAW;CAGnB,MAAM,QAAuC,MAAM,OACjD,cAFgB,KAAK,KAAK,OAAO,aAAa,IAAI,MAAM,QAAQ,WAAW,CAEnD,CAAC;CAI3B,MAAM,UAAU,OAAO,aAAa,OAAO,MAAM;CACjD,MAAM,EAAE,MAAM,QAAQ,kBAAkB,MAAM,MAAM,OAAO;CAG3D,MAAM,cAAc,MAAM,YAAY,KAAK;CAG3C,MAAM,EAAE,YAAY,kBAAkB,MAAM,qBAC1C,cAAc,SAAS,EACvB,QACA,QACD;CAGD,MAAM,kBAAkB,MAAM,mBAAmB,cAAc;CAC/D,MAAM,OAAO,OAAO,KAAK,SAAS,IAAI,GAClC,OAAO,KAAK,MAAM,GAAG,GAAG,GACxB,OAAO;CACX,MAAM,kBACJ,SAAS,MACL,kBAAkB,gBAAgB,GAClC,OAAO,kBAAkB,gBAAgB;CAG/C,MAAM,mBAAmB,YAAY,WACnC,uBACA,gBACD;AAGD,OAAM,gBACJ,KAAK,KAAK,SAAS,aAAa,EAChC,kBACA,QACD;AAGD,OAAM,gBACJ,KAAK,KAAK,SAAS,kBAAkB,gBAAgB,CAAC,QAAQ,OAAO,GAAG,CAAC,EACzE,eACA,QACD;AAGD,MAAK,MAAM,EAAE,SAAS,kBAAkB,WAKtC,OAAM,gBAJW,KAAK,KACpB,SACA,iBAAiB,QAAQ,CAAC,QAAQ,OAAO,GAAG,CAC7C,EAC+B,cAAc,QAAQ;;AAI1D,eAAe,gBACb,UACA,MACA,SACA;AACA,OAAM,MAAM,KAAK,QAAQ,SAAS,EAAE,EAAE,WAAW,MAAM,CAAC;AACxD,SAAQ,KAAK,sBAAsB,WAAW;AAC9C,OAAM,UAAU,UAAU,KAAK"}
+{"version":3,"file":"buildApp.mjs","names":[],"sources":["../../src/build/buildApp.ts"],"sourcesContent":["import { mkdir, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport type { ViteBuilder, MinimalPluginContextWithoutEnvironment } from \"vite\";\nimport { rscPayloadPlaceholder, getRscPayloadPath } from \"./rscPath\";\nimport { getModulePathFor } from \"../rsc/rscModule\";\nimport { processRscComponents } from \"./rscProcessor\";\nimport { computeContentHash } from \"./contentHash\";\nimport { drainStream } from \"../util/drainStream\";\n\nexport async function buildApp(\n  builder: ViteBuilder,\n  context: MinimalPluginContextWithoutEnvironment,\n) {\n  const { config } = builder;\n  // import server entry\n  const entryPath = path.join(config.environments.rsc.build.outDir, \"index.js\");\n  const entry: typeof import(\"../rsc/entry\") = await import(\n    pathToFileURL(entryPath).href\n  );\n\n  // render rsc and html\n  const baseDir = config.environments.client.build.outDir;\n  const { html, appRsc, deferRegistry } = await entry.build();\n\n  // Drain HTML stream to string (needed for placeholder replacement later)\n  const htmlContent = await drainStream(html);\n\n  // Process RSC components with content-based hashes for deterministic file names\n  const { components, appRscContent } = await processRscComponents(\n    deferRegistry.loadAll(),\n    appRsc,\n    context,\n  );\n\n  // Compute hash for main RSC payload and apply base path\n  const mainPayloadHash = await computeContentHash(appRscContent);\n  const base = config.base.endsWith(\"/\")\n    ? config.base.slice(0, -1)\n    : config.base;\n  const mainPayloadPath =\n    base === \"/\"\n      ? getRscPayloadPath(mainPayloadHash)\n      : base + getRscPayloadPath(mainPayloadHash);\n\n  // Replace placeholder with final hashed path (including base path)\n  const finalHtmlContent = htmlContent.replaceAll(\n    rscPayloadPlaceholder,\n    mainPayloadPath,\n  );\n\n  // Write HTML with replaced path\n  await writeFileNormal(\n    path.join(baseDir, \"index.html\"),\n    finalHtmlContent,\n    context,\n  );\n\n  // Write main RSC payload with hashed filename\n  await writeFileNormal(\n    path.join(baseDir, getRscPayloadPath(mainPayloadHash).replace(/^\\//, \"\")),\n    appRscContent,\n    context,\n  );\n\n  // Write processed components with hash-based IDs\n  for (const { finalId, finalContent, name } of components) {\n    const filePath = path.join(\n      baseDir,\n      getModulePathFor(finalId).replace(/^\\//, \"\"),\n    );\n    await writeFileNormal(filePath, finalContent, context, name);\n  }\n}\n\nasync function writeFileNormal(\n  filePath: string,\n  data: string,\n  context: MinimalPluginContextWithoutEnvironment,\n  name?: string,\n) {\n  await mkdir(path.dirname(filePath), { recursive: true });\n  const nameInfo = name ? ` (${name})` : \"\";\n  context.info(`[funstack] Writing ${filePath}${nameInfo}`);\n  await writeFile(filePath, data);\n}\n"],"mappings":";;;;;;;;;;AAUA,eAAsB,SACpB,SACA,SACA;CACA,MAAM,EAAE,WAAW;CAGnB,MAAM,QAAuC,MAAM,OACjD,cAFgB,KAAK,KAAK,OAAO,aAAa,IAAI,MAAM,QAAQ,WAAW,CAEnD,CAAC;CAI3B,MAAM,UAAU,OAAO,aAAa,OAAO,MAAM;CACjD,MAAM,EAAE,MAAM,QAAQ,kBAAkB,MAAM,MAAM,OAAO;CAG3D,MAAM,cAAc,MAAM,YAAY,KAAK;CAG3C,MAAM,EAAE,YAAY,kBAAkB,MAAM,qBAC1C,cAAc,SAAS,EACvB,QACA,QACD;CAGD,MAAM,kBAAkB,MAAM,mBAAmB,cAAc;CAC/D,MAAM,OAAO,OAAO,KAAK,SAAS,IAAI,GAClC,OAAO,KAAK,MAAM,GAAG,GAAG,GACxB,OAAO;CACX,MAAM,kBACJ,SAAS,MACL,kBAAkB,gBAAgB,GAClC,OAAO,kBAAkB,gBAAgB;CAG/C,MAAM,mBAAmB,YAAY,WACnC,uBACA,gBACD;AAGD,OAAM,gBACJ,KAAK,KAAK,SAAS,aAAa,EAChC,kBACA,QACD;AAGD,OAAM,gBACJ,KAAK,KAAK,SAAS,kBAAkB,gBAAgB,CAAC,QAAQ,OAAO,GAAG,CAAC,EACzE,eACA,QACD;AAGD,MAAK,MAAM,EAAE,SAAS,cAAc,UAAU,WAK5C,OAAM,gBAJW,KAAK,KACpB,SACA,iBAAiB,QAAQ,CAAC,QAAQ,OAAO,GAAG,CAC7C,EAC+B,cAAc,SAAS,KAAK;;AAIhE,eAAe,gBACb,UACA,MACA,SACA,MACA;AACA,OAAM,MAAM,KAAK,QAAQ,SAAS,EAAE,EAAE,WAAW,MAAM,CAAC;CACxD,MAAM,WAAW,OAAO,KAAK,KAAK,KAAK;AACvC,SAAQ,KAAK,sBAAsB,WAAW,WAAW;AACzD,OAAM,UAAU,UAAU,KAAK"}

package/dist/build/rscProcessor.mjs

@@ -13,7 +13,11 @@ import { findReferencedIds, topologicalSort } from "./dependencyGraph.mjs";
 */
 async function processRscComponents(deferRegistryIterator, appRscStream, context) {
 	const components = /* @__PURE__ */ new Map();
-	for await (const { id, data } of deferRegistryIterator) components.set(id, data);
+	const componentNames = /* @__PURE__ */ new Map();
+	for await (const { id, data, name } of deferRegistryIterator) {
+		components.set(id, data);
+		componentNames.set(id, name);
+	}
 	let appRscContent = await drainStream(appRscStream);
 	if (components.size === 0) return {
 		components: [],
@@ -42,7 +46,8 @@ async function processRscComponents(deferRegistryIterator, appRscStream, context
 		idMapping.set(tempId, finalId);
 		processedComponents.push({
 			finalId,
-			finalContent: content
+			finalContent: content,
+			name: componentNames.get(tempId)
 		});
 	}
 	for (const tempId of inCycle) {
@@ -50,7 +55,8 @@ async function processRscComponents(deferRegistryIterator, appRscStream, context
 		for (const [oldId, newId] of idMapping) if (oldId !== newId) content = content.replaceAll(oldId, newId);
 		processedComponents.push({
 			finalId: tempId,
-			finalContent: content
+			finalContent: content,
+			name: componentNames.get(tempId)
 		});
 	}
 	for (const [oldId, newId] of idMapping) if (oldId !== newId) appRscContent = appRscContent.replaceAll(oldId, newId);

package/dist/build/rscProcessor.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"rscProcessor.mjs","names":[],"sources":["../../src/build/rscProcessor.ts"],"sourcesContent":["import { drainStream } from \"../util/drainStream\";\nimport { getPayloadIDFor } from \"../rsc/rscModule\";\nimport { computeContentHash } from \"./contentHash\";\nimport { findReferencedIds, topologicalSort } from \"./dependencyGraph\";\n\nexport interface ProcessedComponent {\n  finalId: string;\n  finalContent: string;\n}\n\nexport interface ProcessResult {\n  components: ProcessedComponent[];\n  appRscContent: string;\n  idMapping: Map<string, string>;\n}\n\ninterface RawComponent {\n  id: string;\n  data: string;\n}\n\n/**\n * Processes RSC components by replacing temporary UUIDs with content-based hashes.\n *\n * @param deferRegistryIterator - Iterator yielding components with { id, data }\n * @param appRscStream - The main RSC stream\n * @param context - Optional context for logging warnings\n */\nexport async function processRscComponents(\n  deferRegistryIterator: AsyncIterable<RawComponent>,\n  appRscStream: ReadableStream,\n  context?: { warn: (message: string) => void },\n): Promise<ProcessResult> {\n  // Step 1: Collect all components from deferRegistry\n  const components = new Map<string, string>();\n  for await (const { id, data } of deferRegistryIterator) {\n    components.set(id, data);\n  }\n\n  // Step 2: Drain appRsc stream to string\n  let appRscContent = await drainStream(appRscStream);\n\n  // If no components, return early\n  if (components.size === 0) {\n    return {\n      components: [],\n      appRscContent,\n      idMapping: new Map(),\n    };\n  }\n\n  const allIds = new Set(components.keys());\n\n  // Step 3: Build dependency graph\n  // For each component, find which other component IDs appear in its content\n  const dependencies = new Map<string, Set<string>>();\n  for (const [id, content] of components) {\n    const otherIds = new Set(allIds);\n    otherIds.delete(id); // Don't include self-references\n    const refs = findReferencedIds(content, otherIds);\n    dependencies.set(id, refs);\n  }\n\n  // Step 4: Topologically sort components\n  const { sorted, inCycle } = topologicalSort(dependencies);\n\n  // Step 5: Handle cycles - warn and keep original temp IDs\n  const idMapping = new Map<string, string>();\n\n  if (inCycle.length > 0) {\n    context?.warn(\n      `[funstack] Warning: ${inCycle.length} RSC component(s) are in dependency cycles and will keep unstable IDs: ${inCycle.join(\", \")}`,\n    );\n    for (const id of inCycle) {\n      idMapping.set(id, id); // Map to itself (keep original ID)\n    }\n  }\n\n  // Step 6: Process sorted components in order\n  const processedComponents: ProcessedComponent[] = [];\n\n  for (const tempId of sorted) {\n    let content = components.get(tempId)!;\n\n    // Replace all already-finalized temp IDs with their hash-based IDs\n    for (const [oldId, newId] of idMapping) {\n      if (oldId !== newId) {\n        content = content.replaceAll(oldId, newId);\n      }\n    }\n\n    // Compute content hash for this component\n    const contentHash = await computeContentHash(content);\n    const finalId = getPayloadIDFor(contentHash);\n\n    // Create mapping\n    idMapping.set(tempId, finalId);\n\n    processedComponents.push({\n      finalId,\n      finalContent: content,\n    });\n  }\n\n  // Add cycle members to processed components (with original IDs)\n  for (const tempId of inCycle) {\n    let content = components.get(tempId)!;\n\n    // Replace finalized IDs in cycle member content\n    for (const [oldId, newId] of idMapping) {\n      if (oldId !== newId) {\n        content = content.replaceAll(oldId, newId);\n      }\n    }\n\n    processedComponents.push({\n      finalId: tempId, // Keep original temp ID\n      finalContent: content,\n    });\n  }\n\n  // Step 7: Process appRsc - replace all temp IDs with final IDs\n  for (const [oldId, newId] of idMapping) {\n    if (oldId !== newId) {\n      appRscContent = appRscContent.replaceAll(oldId, newId);\n    }\n  }\n\n  return {\n    components: processedComponents,\n    appRscContent,\n    idMapping,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;AA4BA,eAAsB,qBACpB,uBACA,cACA,SACwB;CAExB,MAAM,6BAAa,IAAI,KAAqB;AAC5C,YAAW,MAAM,EAAE,IAAI,UAAU,sBAC/B,YAAW,IAAI,IAAI,KAAK;CAI1B,IAAI,gBAAgB,MAAM,YAAY,aAAa;AAGnD,KAAI,WAAW,SAAS,EACtB,QAAO;EACL,YAAY,EAAE;EACd;EACA,2BAAW,IAAI,KAAK;EACrB;CAGH,MAAM,SAAS,IAAI,IAAI,WAAW,MAAM,CAAC;CAIzC,MAAM,+BAAe,IAAI,KAA0B;AACnD,MAAK,MAAM,CAAC,IAAI,YAAY,YAAY;EACtC,MAAM,WAAW,IAAI,IAAI,OAAO;AAChC,WAAS,OAAO,GAAG;EACnB,MAAM,OAAO,kBAAkB,SAAS,SAAS;AACjD,eAAa,IAAI,IAAI,KAAK;;CAI5B,MAAM,EAAE,QAAQ,YAAY,gBAAgB,aAAa;CAGzD,MAAM,4BAAY,IAAI,KAAqB;AAE3C,KAAI,QAAQ,SAAS,GAAG;AACtB,WAAS,KACP,uBAAuB,QAAQ,OAAO,yEAAyE,QAAQ,KAAK,KAAK,GAClI;AACD,OAAK,MAAM,MAAM,QACf,WAAU,IAAI,IAAI,GAAG;;CAKzB,MAAM,sBAA4C,EAAE;AAEpD,MAAK,MAAM,UAAU,QAAQ;EAC3B,IAAI,UAAU,WAAW,IAAI,OAAO;AAGpC,OAAK,MAAM,CAAC,OAAO,UAAU,UAC3B,KAAI,UAAU,MACZ,WAAU,QAAQ,WAAW,OAAO,MAAM;EAM9C,MAAM,UAAU,gBADI,MAAM,mBAAmB,QAAQ,CACT;AAG5C,YAAU,IAAI,QAAQ,QAAQ;AAE9B,sBAAoB,KAAK;GACvB;GACA,cAAc;GACf,CAAC;;AAIJ,MAAK,MAAM,UAAU,SAAS;EAC5B,IAAI,UAAU,WAAW,IAAI,OAAO;AAGpC,OAAK,MAAM,CAAC,OAAO,UAAU,UAC3B,KAAI,UAAU,MACZ,WAAU,QAAQ,WAAW,OAAO,MAAM;AAI9C,sBAAoB,KAAK;GACvB,SAAS;GACT,cAAc;GACf,CAAC;;AAIJ,MAAK,MAAM,CAAC,OAAO,UAAU,UAC3B,KAAI,UAAU,MACZ,iBAAgB,cAAc,WAAW,OAAO,MAAM;AAI1D,QAAO;EACL,YAAY;EACZ;EACA;EACD"}
+{"version":3,"file":"rscProcessor.mjs","names":[],"sources":["../../src/build/rscProcessor.ts"],"sourcesContent":["import { drainStream } from \"../util/drainStream\";\nimport { getPayloadIDFor } from \"../rsc/rscModule\";\nimport { computeContentHash } from \"./contentHash\";\nimport { findReferencedIds, topologicalSort } from \"./dependencyGraph\";\n\nexport interface ProcessedComponent {\n  finalId: string;\n  finalContent: string;\n  name?: string;\n}\n\nexport interface ProcessResult {\n  components: ProcessedComponent[];\n  appRscContent: string;\n  idMapping: Map<string, string>;\n}\n\ninterface RawComponent {\n  id: string;\n  data: string;\n  name?: string;\n}\n\n/**\n * Processes RSC components by replacing temporary UUIDs with content-based hashes.\n *\n * @param deferRegistryIterator - Iterator yielding components with { id, data }\n * @param appRscStream - The main RSC stream\n * @param context - Optional context for logging warnings\n */\nexport async function processRscComponents(\n  deferRegistryIterator: AsyncIterable<RawComponent>,\n  appRscStream: ReadableStream,\n  context?: { warn: (message: string) => void },\n): Promise<ProcessResult> {\n  // Step 1: Collect all components from deferRegistry\n  const components = new Map<string, string>();\n  const componentNames = new Map<string, string | undefined>();\n  for await (const { id, data, name } of deferRegistryIterator) {\n    components.set(id, data);\n    componentNames.set(id, name);\n  }\n\n  // Step 2: Drain appRsc stream to string\n  let appRscContent = await drainStream(appRscStream);\n\n  // If no components, return early\n  if (components.size === 0) {\n    return {\n      components: [],\n      appRscContent,\n      idMapping: new Map(),\n    };\n  }\n\n  const allIds = new Set(components.keys());\n\n  // Step 3: Build dependency graph\n  // For each component, find which other component IDs appear in its content\n  const dependencies = new Map<string, Set<string>>();\n  for (const [id, content] of components) {\n    const otherIds = new Set(allIds);\n    otherIds.delete(id); // Don't include self-references\n    const refs = findReferencedIds(content, otherIds);\n    dependencies.set(id, refs);\n  }\n\n  // Step 4: Topologically sort components\n  const { sorted, inCycle } = topologicalSort(dependencies);\n\n  // Step 5: Handle cycles - warn and keep original temp IDs\n  const idMapping = new Map<string, string>();\n\n  if (inCycle.length > 0) {\n    context?.warn(\n      `[funstack] Warning: ${inCycle.length} RSC component(s) are in dependency cycles and will keep unstable IDs: ${inCycle.join(\", \")}`,\n    );\n    for (const id of inCycle) {\n      idMapping.set(id, id); // Map to itself (keep original ID)\n    }\n  }\n\n  // Step 6: Process sorted components in order\n  const processedComponents: ProcessedComponent[] = [];\n\n  for (const tempId of sorted) {\n    let content = components.get(tempId)!;\n\n    // Replace all already-finalized temp IDs with their hash-based IDs\n    for (const [oldId, newId] of idMapping) {\n      if (oldId !== newId) {\n        content = content.replaceAll(oldId, newId);\n      }\n    }\n\n    // Compute content hash for this component\n    const contentHash = await computeContentHash(content);\n    const finalId = getPayloadIDFor(contentHash);\n\n    // Create mapping\n    idMapping.set(tempId, finalId);\n\n    processedComponents.push({\n      finalId,\n      finalContent: content,\n      name: componentNames.get(tempId),\n    });\n  }\n\n  // Add cycle members to processed components (with original IDs)\n  for (const tempId of inCycle) {\n    let content = components.get(tempId)!;\n\n    // Replace finalized IDs in cycle member content\n    for (const [oldId, newId] of idMapping) {\n      if (oldId !== newId) {\n        content = content.replaceAll(oldId, newId);\n      }\n    }\n\n    processedComponents.push({\n      finalId: tempId, // Keep original temp ID\n      finalContent: content,\n      name: componentNames.get(tempId),\n    });\n  }\n\n  // Step 7: Process appRsc - replace all temp IDs with final IDs\n  for (const [oldId, newId] of idMapping) {\n    if (oldId !== newId) {\n      appRscContent = appRscContent.replaceAll(oldId, newId);\n    }\n  }\n\n  return {\n    components: processedComponents,\n    appRscContent,\n    idMapping,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;AA8BA,eAAsB,qBACpB,uBACA,cACA,SACwB;CAExB,MAAM,6BAAa,IAAI,KAAqB;CAC5C,MAAM,iCAAiB,IAAI,KAAiC;AAC5D,YAAW,MAAM,EAAE,IAAI,MAAM,UAAU,uBAAuB;AAC5D,aAAW,IAAI,IAAI,KAAK;AACxB,iBAAe,IAAI,IAAI,KAAK;;CAI9B,IAAI,gBAAgB,MAAM,YAAY,aAAa;AAGnD,KAAI,WAAW,SAAS,EACtB,QAAO;EACL,YAAY,EAAE;EACd;EACA,2BAAW,IAAI,KAAK;EACrB;CAGH,MAAM,SAAS,IAAI,IAAI,WAAW,MAAM,CAAC;CAIzC,MAAM,+BAAe,IAAI,KAA0B;AACnD,MAAK,MAAM,CAAC,IAAI,YAAY,YAAY;EACtC,MAAM,WAAW,IAAI,IAAI,OAAO;AAChC,WAAS,OAAO,GAAG;EACnB,MAAM,OAAO,kBAAkB,SAAS,SAAS;AACjD,eAAa,IAAI,IAAI,KAAK;;CAI5B,MAAM,EAAE,QAAQ,YAAY,gBAAgB,aAAa;CAGzD,MAAM,4BAAY,IAAI,KAAqB;AAE3C,KAAI,QAAQ,SAAS,GAAG;AACtB,WAAS,KACP,uBAAuB,QAAQ,OAAO,yEAAyE,QAAQ,KAAK,KAAK,GAClI;AACD,OAAK,MAAM,MAAM,QACf,WAAU,IAAI,IAAI,GAAG;;CAKzB,MAAM,sBAA4C,EAAE;AAEpD,MAAK,MAAM,UAAU,QAAQ;EAC3B,IAAI,UAAU,WAAW,IAAI,OAAO;AAGpC,OAAK,MAAM,CAAC,OAAO,UAAU,UAC3B,KAAI,UAAU,MACZ,WAAU,QAAQ,WAAW,OAAO,MAAM;EAM9C,MAAM,UAAU,gBADI,MAAM,mBAAmB,QAAQ,CACT;AAG5C,YAAU,IAAI,QAAQ,QAAQ;AAE9B,sBAAoB,KAAK;GACvB;GACA,cAAc;GACd,MAAM,eAAe,IAAI,OAAO;GACjC,CAAC;;AAIJ,MAAK,MAAM,UAAU,SAAS;EAC5B,IAAI,UAAU,WAAW,IAAI,OAAO;AAGpC,OAAK,MAAM,CAAC,OAAO,UAAU,UAC3B,KAAI,UAAU,MACZ,WAAU,QAAQ,WAAW,OAAO,MAAM;AAI9C,sBAAoB,KAAK;GACvB,SAAS;GACT,cAAc;GACd,MAAM,eAAe,IAAI,OAAO;GACjC,CAAC;;AAIJ,MAAK,MAAM,CAAC,OAAO,UAAU,UAC3B,KAAI,UAAU,MACZ,iBAAgB,cAAc,WAAW,OAAO,MAAM;AAI1D,QAAO;EACL,YAAY;EACZ;EACA;EACD"}

package/dist/client/entry.d.mts

@@ -0,0 +1 @@
+import "virtual:funstack/client-init";

package/dist/client/entry.mjs

@@ -2,11 +2,13 @@ import { GlobalErrorBoundary } from "./error-boundary.mjs";
 import { devMainRscPath } from "../rsc/request.mjs";
 import { appClientManifestVar } from "./globals.mjs";
 import { withBasePath } from "../util/basePath.mjs";
+import "virtual:funstack/client-init";
 import { createFromFetch, createFromReadableStream } from "@vitejs/plugin-rsc/browser";
 import React, { startTransition, useEffect, useState } from "react";
 import { createRoot, hydrateRoot } from "react-dom/client";
 import { rscStream } from "rsc-html-stream/client";
 import { jsx } from "react/jsx-runtime";
+import { ssr } from "virtual:funstack/config";
 
 //#region src/client/entry.tsx
 async function devMain() {
@@ -25,7 +27,8 @@ async function devMain() {
 	}
 	const browserRoot = /* @__PURE__ */ jsx(React.StrictMode, { children: /* @__PURE__ */ jsx(GlobalErrorBoundary, { children: /* @__PURE__ */ jsx(BrowserRoot, {}) }) });
 	if (globalThis.__NO_HYDRATE) createRoot(document).render(browserRoot);
-	else hydrateRoot(document, browserRoot);
+	else if (ssr) hydrateRoot(document, browserRoot);
+	else createRoot(document).render(browserRoot);
 	if (import.meta.hot) import.meta.hot.on("rsc:update", () => {
 		fetchRscPayload();
 	});
@@ -36,14 +39,19 @@ async function prodMain() {
 	function BrowserRoot() {
 		return payload.root;
 	}
-	const browserRoot = /* @__PURE__ */ jsx(BrowserRoot, {});
-	const appRootId = manifest.marker;
-	const appMarker = document.getElementById(appRootId);
-	if (!appMarker) throw new Error(`Failed to find app root element by id "${appRootId}". This is likely a bug.`);
-	const appRoot = appMarker.parentElement;
-	if (!appRoot) throw new Error(`App root element has no parent element. This is likely a bug.`);
-	appMarker.remove();
-	createRoot(appRoot).render(browserRoot);
+	if (ssr) {
+		const browserRoot = /* @__PURE__ */ jsx(React.StrictMode, { children: /* @__PURE__ */ jsx(GlobalErrorBoundary, { children: /* @__PURE__ */ jsx(BrowserRoot, {}) }) });
+		hydrateRoot(document, browserRoot);
+	} else {
+		const browserRoot = /* @__PURE__ */ jsx(BrowserRoot, {});
+		const appRootId = manifest.marker;
+		const appMarker = document.getElementById(appRootId);
+		if (!appMarker) throw new Error(`Failed to find app root element by id "${appRootId}". This is likely a bug.`);
+		const appRoot = appMarker.parentElement;
+		if (!appRoot) throw new Error(`App root element has no parent element. This is likely a bug.`);
+		appMarker.remove();
+		createRoot(appRoot).render(browserRoot);
+	}
 }
 if (import.meta.env.DEV) devMain();
 else prodMain();

package/dist/client/entry.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"entry.mjs","names":[],"sources":["../../src/client/entry.tsx"],"sourcesContent":["import {\n  createFromReadableStream,\n  createFromFetch,\n} from \"@vitejs/plugin-rsc/browser\";\nimport React, { startTransition, useEffect, useState } from \"react\";\nimport { createRoot, hydrateRoot } from \"react-dom/client\";\nimport { rscStream } from \"rsc-html-stream/client\";\nimport { GlobalErrorBoundary } from \"./error-boundary\";\nimport type { RscPayload } from \"../rsc/entry\";\nimport { devMainRscPath } from \"../rsc/request\";\nimport { appClientManifestVar, type AppClientManifest } from \"./globals\";\nimport { withBasePath } from \"../util/basePath\";\n\nasync function devMain() {\n  let setPayload: (v: RscPayload) => void;\n\n  const initialPayload = await createFromReadableStream<RscPayload>(rscStream);\n\n  function BrowserRoot() {\n    const [payload, setPayload_] = useState(initialPayload);\n\n    useEffect(() => {\n      setPayload = (v) => startTransition(() => setPayload_(v));\n    }, [setPayload_]);\n\n    return payload.root;\n  }\n\n  // re-fetch RSC and trigger re-rendering\n  async function fetchRscPayload() {\n    const payload = await createFromFetch<RscPayload>(\n      fetch(withBasePath(devMainRscPath)),\n    );\n    setPayload(payload);\n  }\n  // hydration\n  const browserRoot = (\n    <React.StrictMode>\n      <GlobalErrorBoundary>\n        <BrowserRoot />\n      </GlobalErrorBoundary>\n    </React.StrictMode>\n  );\n\n  if (\n    // @ts-expect-error\n    globalThis.__NO_HYDRATE\n  ) {\n    // This happens when SSR failed on server\n    createRoot(document).render(browserRoot);\n  } else {\n    hydrateRoot(document, browserRoot);\n  }\n\n  // implement server HMR by triggering re-fetch/render of RSC upon server code change\n  if (import.meta.hot) {\n    import.meta.hot.on(\"rsc:update\", () => {\n      fetchRscPayload();\n    });\n  }\n}\n\nasync function prodMain() {\n  const manifest: AppClientManifest =\n    // @ts-expect-error\n    globalThis[appClientManifestVar];\n\n  const payload = await createFromFetch<RscPayload>(fetch(manifest.stream));\n\n  function BrowserRoot() {\n    return payload.root;\n  }\n  const browserRoot = <BrowserRoot />;\n  const appRootId: string = manifest.marker;\n\n  const appMarker = document.getElementById(appRootId);\n  if (!appMarker) {\n    throw new Error(\n      `Failed to find app root element by id \"${appRootId}\". This is likely a bug.`,\n    );\n  }\n  const appRoot = appMarker.parentElement;\n  if (!appRoot) {\n    throw new Error(\n      `App root element has no parent element. This is likely a bug.`,\n    );\n  }\n  appMarker.remove();\n\n  createRoot(appRoot).render(browserRoot);\n}\n\nif (import.meta.env.DEV) {\n  devMain();\n} else {\n  prodMain();\n}\n"],"mappings":";;;;;;;;;;;AAaA,eAAe,UAAU;CACvB,IAAI;CAEJ,MAAM,iBAAiB,MAAM,yBAAqC,UAAU;CAE5E,SAAS,cAAc;EACrB,MAAM,CAAC,SAAS,eAAe,SAAS,eAAe;AAEvD,kBAAgB;AACd,iBAAc,MAAM,sBAAsB,YAAY,EAAE,CAAC;KACxD,CAAC,YAAY,CAAC;AAEjB,SAAO,QAAQ;;CAIjB,eAAe,kBAAkB;EAC/B,MAAM,UAAU,MAAM,gBACpB,MAAM,aAAa,eAAe,CAAC,CACpC;AACD,aAAW,QAAQ;;CAGrB,MAAM,cACJ,oBAAC,MAAM,wBACL,oBAAC,iCACC,oBAAC,gBAAc,GACK,GACL;AAGrB,KAEE,WAAW,aAGX,YAAW,SAAS,CAAC,OAAO,YAAY;KAExC,aAAY,UAAU,YAAY;AAIpC,KAAI,OAAO,KAAK,IACd,QAAO,KAAK,IAAI,GAAG,oBAAoB;AACrC,mBAAiB;GACjB;;AAIN,eAAe,WAAW;CACxB,MAAM,WAEJ,WAAW;CAEb,MAAM,UAAU,MAAM,gBAA4B,MAAM,SAAS,OAAO,CAAC;CAEzE,SAAS,cAAc;AACrB,SAAO,QAAQ;;CAEjB,MAAM,cAAc,oBAAC,gBAAc;CACnC,MAAM,YAAoB,SAAS;CAEnC,MAAM,YAAY,SAAS,eAAe,UAAU;AACpD,KAAI,CAAC,UACH,OAAM,IAAI,MACR,0CAA0C,UAAU,0BACrD;CAEH,MAAM,UAAU,UAAU;AAC1B,KAAI,CAAC,QACH,OAAM,IAAI,MACR,gEACD;AAEH,WAAU,QAAQ;AAElB,YAAW,QAAQ,CAAC,OAAO,YAAY;;AAGzC,IAAI,OAAO,KAAK,IAAI,IAClB,UAAS;IAET,WAAU"}
+{"version":3,"file":"entry.mjs","names":["ssrEnabled"],"sources":["../../src/client/entry.tsx"],"sourcesContent":["// Client initialization - runs before React (side effects only)\nimport \"virtual:funstack/client-init\";\n\nimport {\n  createFromReadableStream,\n  createFromFetch,\n} from \"@vitejs/plugin-rsc/browser\";\nimport React, { startTransition, useEffect, useState } from \"react\";\nimport { createRoot, hydrateRoot } from \"react-dom/client\";\nimport { rscStream } from \"rsc-html-stream/client\";\nimport { GlobalErrorBoundary } from \"./error-boundary\";\nimport type { RscPayload } from \"../rsc/entry\";\nimport { devMainRscPath } from \"../rsc/request\";\nimport { appClientManifestVar, type AppClientManifest } from \"./globals\";\nimport { withBasePath } from \"../util/basePath\";\n\nimport { ssr as ssrEnabled } from \"virtual:funstack/config\";\n\nasync function devMain() {\n  let setPayload: (v: RscPayload) => void;\n\n  const initialPayload = await createFromReadableStream<RscPayload>(rscStream);\n\n  function BrowserRoot() {\n    const [payload, setPayload_] = useState(initialPayload);\n\n    useEffect(() => {\n      setPayload = (v) => startTransition(() => setPayload_(v));\n    }, [setPayload_]);\n\n    return payload.root;\n  }\n\n  // re-fetch RSC and trigger re-rendering\n  async function fetchRscPayload() {\n    const payload = await createFromFetch<RscPayload>(\n      fetch(withBasePath(devMainRscPath)),\n    );\n    setPayload(payload);\n  }\n\n  const browserRoot = (\n    <React.StrictMode>\n      <GlobalErrorBoundary>\n        <BrowserRoot />\n      </GlobalErrorBoundary>\n    </React.StrictMode>\n  );\n\n  if (\n    // @ts-expect-error\n    globalThis.__NO_HYDRATE\n  ) {\n    // This happens when SSR failed on server\n    createRoot(document).render(browserRoot);\n  } else if (ssrEnabled) {\n    hydrateRoot(document, browserRoot);\n  } else {\n    // SSR off: Root shell is static HTML, mount App client-side\n    createRoot(document).render(browserRoot);\n  }\n\n  // implement server HMR by triggering re-fetch/render of RSC upon server code change\n  if (import.meta.hot) {\n    import.meta.hot.on(\"rsc:update\", () => {\n      fetchRscPayload();\n    });\n  }\n}\n\nasync function prodMain() {\n  const manifest: AppClientManifest =\n    // @ts-expect-error\n    globalThis[appClientManifestVar];\n\n  const payload = await createFromFetch<RscPayload>(fetch(manifest.stream));\n\n  function BrowserRoot() {\n    return payload.root;\n  }\n\n  if (ssrEnabled) {\n    // SSR on: full tree was SSR'd, hydrate from RSC payload\n    const browserRoot = (\n      <React.StrictMode>\n        <GlobalErrorBoundary>\n          <BrowserRoot />\n        </GlobalErrorBoundary>\n      </React.StrictMode>\n    );\n\n    hydrateRoot(document, browserRoot);\n  } else {\n    // SSR off: Root shell only, mount App client-side\n    const browserRoot = <BrowserRoot />;\n    const appRootId = manifest.marker!;\n\n    const appMarker = document.getElementById(appRootId);\n    if (!appMarker) {\n      throw new Error(\n        `Failed to find app root element by id \"${appRootId}\". This is likely a bug.`,\n      );\n    }\n    const appRoot = appMarker.parentElement;\n    if (!appRoot) {\n      throw new Error(\n        `App root element has no parent element. This is likely a bug.`,\n      );\n    }\n    appMarker.remove();\n\n    createRoot(appRoot).render(browserRoot);\n  }\n}\n\nif (import.meta.env.DEV) {\n  devMain();\n} else {\n  prodMain();\n}\n"],"mappings":";;;;;;;;;;;;;AAkBA,eAAe,UAAU;CACvB,IAAI;CAEJ,MAAM,iBAAiB,MAAM,yBAAqC,UAAU;CAE5E,SAAS,cAAc;EACrB,MAAM,CAAC,SAAS,eAAe,SAAS,eAAe;AAEvD,kBAAgB;AACd,iBAAc,MAAM,sBAAsB,YAAY,EAAE,CAAC;KACxD,CAAC,YAAY,CAAC;AAEjB,SAAO,QAAQ;;CAIjB,eAAe,kBAAkB;EAC/B,MAAM,UAAU,MAAM,gBACpB,MAAM,aAAa,eAAe,CAAC,CACpC;AACD,aAAW,QAAQ;;CAGrB,MAAM,cACJ,oBAAC,MAAM,wBACL,oBAAC,iCACC,oBAAC,gBAAc,GACK,GACL;AAGrB,KAEE,WAAW,aAGX,YAAW,SAAS,CAAC,OAAO,YAAY;UAC/BA,IACT,aAAY,UAAU,YAAY;KAGlC,YAAW,SAAS,CAAC,OAAO,YAAY;AAI1C,KAAI,OAAO,KAAK,IACd,QAAO,KAAK,IAAI,GAAG,oBAAoB;AACrC,mBAAiB;GACjB;;AAIN,eAAe,WAAW;CACxB,MAAM,WAEJ,WAAW;CAEb,MAAM,UAAU,MAAM,gBAA4B,MAAM,SAAS,OAAO,CAAC;CAEzE,SAAS,cAAc;AACrB,SAAO,QAAQ;;AAGjB,KAAIA,KAAY;EAEd,MAAM,cACJ,oBAAC,MAAM,wBACL,oBAAC,iCACC,oBAAC,gBAAc,GACK,GACL;AAGrB,cAAY,UAAU,YAAY;QAC7B;EAEL,MAAM,cAAc,oBAAC,gBAAc;EACnC,MAAM,YAAY,SAAS;EAE3B,MAAM,YAAY,SAAS,eAAe,UAAU;AACpD,MAAI,CAAC,UACH,OAAM,IAAI,MACR,0CAA0C,UAAU,0BACrD;EAEH,MAAM,UAAU,UAAU;AAC1B,MAAI,CAAC,QACH,OAAM,IAAI,MACR,gEACD;AAEH,YAAU,QAAQ;AAElB,aAAW,QAAQ,CAAC,OAAO,YAAY;;;AAI3C,IAAI,OAAO,KAAK,IAAI,IAClB,UAAS;IAET,WAAU"}

package/dist/client/globals.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"globals.mjs","names":[],"sources":["../../src/client/globals.ts"],"sourcesContent":["// Prefix for global variables\nconst globalPrefix = \"FUNSTACK_STATIC_\";\n\n/**\n * Variable name for the app client manifest\n */\nexport const appClientManifestVar = `${globalPrefix}appClientManifest`;\n\nexport interface AppClientManifest {\n  marker: string;\n  stream: string;\n}\n"],"mappings":";AACA,MAAM,eAAe;;;;AAKrB,MAAa,uBAAuB,GAAG,aAAa"}
+{"version":3,"file":"globals.mjs","names":[],"sources":["../../src/client/globals.ts"],"sourcesContent":["// Prefix for global variables\nconst globalPrefix = \"FUNSTACK_STATIC_\";\n\n/**\n * Variable name for the app client manifest\n */\nexport const appClientManifestVar = `${globalPrefix}appClientManifest`;\n\nexport interface AppClientManifest {\n  marker?: string;\n  stream: string;\n}\n"],"mappings":";AACA,MAAM,eAAe;;;;AAKrB,MAAa,uBAAuB,GAAG,aAAa"}

package/dist/docs/FAQ.md

@@ -0,0 +1,5 @@
+# FAQ
+
+## I'm seeing a ``<link rel=preload> must have a valid `as` value`` warning
+
+This is a bug in React itself. Please wait for [the fix](https://github.com/facebook/react/pull/34760) to be released.

package/dist/docs/GettingStarted.md

@@ -0,0 +1,180 @@
+# Getting Started
+
+Welcome to **FUNSTACK Static**! Build high-performance Single Page Applications powered by React Server Components - no server required at runtime.
+
+## Installation
+
+Install `@funstack/static` and its peer dependencies:
+
+```bash
+npm install @funstack/static react react-dom
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @funstack/static react react-dom
+```
+
+## Quick Start
+
+### 1. Configure Vite
+
+Create or update your `vite.config.ts`:
+
+```typescript
+import { funstackStatic } from "@funstack/static";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    funstackStatic({
+      root: "./src/Root.tsx",
+      app: "./src/App.tsx",
+    }),
+    react(),
+  ],
+});
+```
+
+### 2. Create Your Root Component
+
+The Root component wraps your entire application and defines the HTML structure.
+
+```tsx
+// src/Root.tsx
+import type React from "react";
+
+export default function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>My App</title>
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+The Root component:
+
+- is responsible for defining the shell HTML structure of your app
+- is a server component
+- **CANNOT** import client components; you could, but they are fully rendered into static HTML and never hydrated
+
+### 3. Create Your App Component
+
+The App component defines what comes into the `children` of the Root. This is the entrypoint of your SPA.
+
+Since the App component is a server component, for interactivity you can import and use client components inside it.
+
+```tsx
+// src/App.tsx
+import Counter from "./Counter";
+
+export default function App() {
+  return (
+    <main>
+      <h1>Welcome to my site!</h1>
+      <Counter />
+    </main>
+  );
+}
+```
+
+```tsx
+// src/Counter.tsx
+"use client";
+
+import { useState } from "react";
+
+export default function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
+}
+```
+
+The App component:
+
+- is a server component
+- **CAN** import client components and use them within the app
+
+### 4. Add Routing (Optional)
+
+If you want routing, you can bring your favorite SPA router. Here, we use `@funstack/router` as an example:
+
+```tsx
+// src/App.tsx
+import { Router } from "@funstack/router";
+import { route } from "@funstack/router/server";
+
+const routes = [
+  route({
+    path: "/",
+    component: <h1>Welcome to my site!</h1>,
+  }),
+  route({
+    path: "/about",
+    component: <h1>About Us</h1>,
+  }),
+];
+
+export default function App() {
+  return <Router routes={routes} />;
+}
+```
+
+### 5. Start Development Server
+
+```bash
+npm run dev
+```
+
+Your site is now running at `http://localhost:5173`!
+
+### 6. Build for Production
+
+```bash
+npm run build
+```
+
+Your SPA is pre-rendered to static files in the `dist/public` directory, ready to deploy to any static hosting provider.
+
+Since FUNSTACK Static is built on top of Vite, any Vite configurations and plugins should work seamlessly.
+
+## Project Structure
+
+A typical FUNSTACK Static project looks like this:
+
+```
+my-site/
+├── src/
+│   ├── ...
+│   ├── Root.tsx        # HTML wrapper component
+│   └── App.tsx         # Routes and main app
+├── public/             # Static assets
+├── vite.config.ts      # Vite configuration
+└── package.json
+```
+
+Only two files are required: `Root.tsx` and `App.tsx`. The paths to these files can be customized in the `funstackStatic()` configuration.
+
+## AI-Assisted Development (Optional)
+
+If you use AI coding assistants like [Claude Code](https://docs.anthropic.com/en/docs/claude-code), you can install the FUNSTACK Static knowledge skill to help your AI assistant better understand the framework:
+
+```bash
+npx funstack-static-skill-installer
+```
+
+This registers the `funstack-static-knowledge` skill, which provides your AI assistant with API references, best practices, and architectural guidance for FUNSTACK Static.
+
+## What's Next?
+
+- Learn about the [funstackStatic() Plugin API](/funstack-static/api/funstack-static) for configuration options
+- Understand [defer()](/funstack-static/api/defer) for Server Component chunk splitting
+- Dive into [React Server Components](/funstack-static/learn/rsc) concepts

package/dist/docs/api/Defer.md

@@ -0,0 +1,110 @@
+# defer()
+
+The `defer()` function enables deferred rendering for React Server Components, reducing initial data load.
+
+You can think of this as React's `lazy` API but for Server Components.
+
+## Import
+
+```typescript
+// @funstack/static/server is where utilities for server components live
+import { defer } from "@funstack/static/server";
+```
+
+## Usage
+
+```tsx
+import { defer } from "@funstack/static/server";
+import { HeavyServerComponent } from "./HeavyServerComponent";
+
+function Page() {
+  return (
+    <details>
+      <summary>Very long description</summary>
+      <Suspense fallback={<p>Loading...</p>}>
+        {defer(<HeavyServerComponent />)}
+      </Suspense>
+    </details>
+  );
+}
+```
+
+By using `defer()`, the `HeavyServerComponent` will still be rendered on the server (during build), but its data will be sent to the client as a separate RSC payload.
+
+This means that:
+
+- Client can start rendering the rest of the page without waiting for `HeavyServerComponent`'s data
+- When the `defer(<HeavyServerComponent />)` part is rendered on the client, it will fetch the separate RSC payload and show the content.
+
+The key point is that `HeavyServerComponent` is still a Server Component, so only the rendered HTML (and usage of Client Components inside it) is sent to the client, not the component code itself.
+
+**Note:** `defer()` must be used inside a `Suspense` boundary since the content will be streamed in later.
+
+## Signature
+
+```typescript
+export function defer(element: ReactElement, options?: DeferOptions): ReactNode;
+```
+
+### Parameters
+
+- **element:** A JSX element (Server Component) to render with deferred loading.
+- **options:** (optional) Configuration options for the deferred payload.
+
+### DeferOptions
+
+```typescript
+interface DeferOptions {
+  /**
+   * Optional name for debugging purposes.
+   * In development: included in the RSC payload file name.
+   * In production: logged when the payload file is emitted.
+   */
+  name?: string;
+}
+```
+
+- **name:** An optional identifier to help with debugging. When provided:
+  - In development mode, the name is included in the RSC payload file name (e.g., `/funstack__/fun:rsc-payload/HomePage-b5698be72eea3c37`)
+  - In production mode, the name is logged when the payload file is emitted
+
+### Returns
+
+A React Node that will stream its content separately from the main entry point.
+
+## When to Use defer()
+
+Use `defer()` when you have components that:
+
+- Renders large HTML content
+- Is not immediately visible on page load (e.g., inside a collapsed section)
+
+Typically, you will want to wrap route components with `defer()` to improve initial load performance. Otherwise, user needs to wait for contents for all pages to arrive before seeing anything.
+
+```tsx
+import { defer } from "@funstack/static/server";
+import HomePage from "./HomePage";
+import AboutPage from "./AboutPage";
+
+const routes = [
+  route({
+    path: "/",
+    component: defer(<HomePage />, { name: "HomePage" }),
+  }),
+  route({
+    path: "/about",
+    component: defer(<AboutPage />, { name: "AboutPage" }),
+  }),
+  // ...
+];
+```
+
+Using the `name` option makes it easier to identify which deferred component corresponds to which payload file during development and in build logs.
+
+## How It Works
+
+By default, FUNSTACK Static puts the entire app (`<App />`) into one RSC payload (`/funstack__/index.txt`). The client fetches this payload to render your SPA.
+
+When you use `defer(<Component />)`, FUNSTACK Static creates **additional RSC payloads** for the rendering result of the element. This results in an additional emit of RSC payload files like `/funstack__/fun:rsc-payload/b5698be72eea3c37`. If you provide a `name` option, the file name will include it (e.g., `/funstack__/fun:rsc-payload/HomePage-b5698be72eea3c37`).
+
+In the main RSC payload, the `defer` call is replaced with a client component `<DeferredComponent moduleId="fun:rsc-payload/b5698be72eea3c37" />`. This component is responsible for fetching the additional RSC payload from client and renders it when it's ready.