meno-core 1.0.4 → 1.0.6

package/build-static.ts

@@ -1,11 +1,13 @@
 /**
  * Static Site Generation Build Script
  * Pre-generates HTML files for all pages at build time
+ * CSP-compliant: Extracts JavaScript to external files
  */
 
 import { existsSync, readdirSync, mkdirSync, rmSync, statSync, copyFileSync } from "fs";
 import { writeFile } from "fs/promises";
 import { join } from "path";
+import { createHash } from "crypto";
 import {
   loadJSONFile,
   loadComponentDirectory,
@@ -14,6 +16,7 @@ import {
   loadI18nConfig
 } from "./lib/server/jsonLoader";
 import { generateSSRHTML } from "./lib/server/ssrRenderer";
+import type { SSRHTMLResult } from "./lib/server/ssr/htmlGenerator";
 import { projectPaths } from "./lib/server/projectContext";
 import { loadProjectConfig } from "./lib/shared/fontLoader";
 import { FileSystemCMSProvider } from "./lib/server/providers/fileSystemCMSProvider";
@@ -22,6 +25,48 @@ import { isI18nValue, resolveI18nValue } from "./lib/shared/i18n";
 import type { ComponentDefinition, JSONPage, CMSSchema, CMSItem, I18nConfig } from "./lib/shared/types";
 import type { SlugMap } from "./lib/shared/slugTranslator";
 
+/**
+ * Generate short hash from content for file naming
+ */
+function hashContent(content: string): string {
+  return createHash('sha256').update(content).digest('hex').slice(0, 8);
+}
+
+/**
+ * Track JavaScript files to avoid duplicates
+ * Maps content hash -> script path
+ */
+const jsFileCache = new Map<string, string>();
+
+/**
+ * Get or create script file path for given JS content
+ * Returns the path to reference in HTML
+ */
+async function getScriptPath(jsContent: string, distDir: string): Promise<string> {
+  const hash = hashContent(jsContent);
+
+  // Check if we already wrote this content
+  if (jsFileCache.has(hash)) {
+    return jsFileCache.get(hash)!;
+  }
+
+  // Create scripts directory if needed
+  const scriptsDir = join(distDir, '_scripts');
+  if (!existsSync(scriptsDir)) {
+    mkdirSync(scriptsDir, { recursive: true });
+  }
+
+  // Write script file
+  const scriptPath = `/_scripts/${hash}.js`;
+  const fullPath = join(distDir, '_scripts', `${hash}.js`);
+  await writeFile(fullPath, jsContent, 'utf-8');
+
+  // Cache for reuse
+  jsFileCache.set(hash, scriptPath);
+
+  return scriptPath;
+}
+
 /**
  * Recursively copy directory contents
  */
@@ -235,17 +280,26 @@ async function buildCMSTemplates(
           const baseUrl = "";
           const itemPath = buildCMSItemPath(cmsSchema.urlPattern, item, cmsSchema.slugField, locale, i18nConfig);
 
-          const html = await generateSSRHTML(
+          // Generate HTML with JS returned separately (CSP-compliant)
+          const result = await generateSSRHTML({
             pageData,
             globalComponents,
-            itemPath,
+            pagePath: itemPath,
             baseUrl,
-            true,
+            useBuiltBundle: true,
             locale,
             slugMappings,
-            { cms: item },
-            cmsService
-          );
+            cmsContext: { cms: item },
+            cmsService,
+            returnSeparateJS: true
+          }) as SSRHTMLResult;
+
+          // If there's JavaScript, write to external file and update HTML
+          let finalHtml = result.html;
+          if (result.javascript) {
+            const scriptPath = await getScriptPath(result.javascript, distDir);
+            finalHtml = finalHtml.replace('</body>', `  <script src="${scriptPath}"></script>\n</body>`);
+          }
 
           const outputPath = locale === i18nConfig.defaultLocale
             ? `${distDir}${itemPath}.html`
@@ -256,7 +310,7 @@ async function buildCMSTemplates(
             mkdirSync(outputDir, { recursive: true });
           }
 
-          await writeFile(outputPath, html, 'utf-8');
+          await writeFile(outputPath, finalHtml, 'utf-8');
 
           const displayPath = locale === i18nConfig.defaultLocale ? itemPath : `/${locale}${itemPath}`;
           console.log(`   ✅ ${displayPath}`);
@@ -397,7 +451,26 @@ async function buildStaticPages(): Promise<void> {
         // Build the URL path that will be used for this locale
         const urlPath = getDisplayPath(basePath, locale, i18nConfig.defaultLocale, slugs);
 
-        const html = await generateSSRHTML(pageData, globalComponents, urlPath, baseUrl, true, locale, slugMappings, undefined, cmsService);
+        // Generate HTML with JS returned separately (CSP-compliant)
+        const result = await generateSSRHTML({
+          pageData,
+          globalComponents,
+          pagePath: urlPath,
+          baseUrl,
+          useBuiltBundle: true,
+          locale,
+          slugMappings,
+          cmsService,
+          returnSeparateJS: true
+        }) as SSRHTMLResult;
+
+        // If there's JavaScript, write to external file and update HTML
+        let finalHtml = result.html;
+        if (result.javascript) {
+          const scriptPath = await getScriptPath(result.javascript, distDir);
+          // Insert script reference before </body>
+          finalHtml = finalHtml.replace('</body>', `  <script src="${scriptPath}"></script>\n</body>`);
+        }
 
         // Determine locale-specific output path with translated slug
         const outputPath = getLocalizedOutputPath(basePath, locale, i18nConfig.defaultLocale, distDir, slugs);
@@ -408,7 +481,7 @@ async function buildStaticPages(): Promise<void> {
           mkdirSync(outputDir, { recursive: true });
         }
 
-        await writeFile(outputPath, html, "utf-8");
+        await writeFile(outputPath, finalHtml, "utf-8");
 
         console.log(`✅ Built: ${urlPath} → ${outputPath}`);
         successCount++;

package/lib/client/index.ts

@@ -1,5 +1,5 @@
 /**
- * @meno/core/client exports
+ * meno-core/client exports
  * Core client-side utilities for page rendering and routing
  * Does NOT include editor-specific code (that's in @meno/studio)
  */

package/lib/client/scripts/ScriptExecutor.test.ts

@@ -8,13 +8,11 @@ describe("ScriptExecutor", () => {
   let componentRegistry: ComponentRegistry;
   let elementRegistry: ElementRegistry;
   let scriptExecutor: ScriptExecutor;
-  let injectedScripts: Map<string, { id: string; textContent: string }>;
-  let originalDocument: typeof document;
+  let executedCode: string[];
+  let originalFunction: typeof Function;
+  let functionSpy: ReturnType<typeof spyOn>;
 
   beforeEach(() => {
-    // Save original document
-    originalDocument = global.document;
-
     componentRegistry = new ComponentRegistry();
     elementRegistry = new ElementRegistry();
     scriptExecutor = new ScriptExecutor({
@@ -22,38 +20,25 @@ describe("ScriptExecutor", () => {
       elementRegistry,
     });
 
-    // Track injected script tags
-    injectedScripts = new Map();
-
-    // Mock document for script tag injection
-    global.document = {
-      createElement: mock((tag: string) => {
-        const element = {
-          tagName: tag.toUpperCase(),
-          id: '',
-          type: '',
-          textContent: '',
-        };
-        return element;
-      }),
-      getElementById: mock((id: string) => {
-        const script = injectedScripts.get(id);
-        return script ? { id: script.id, remove: () => injectedScripts.delete(id) } : null;
-      }),
-      body: {
-        appendChild: mock((script: any) => {
-          if (script.tagName === 'SCRIPT') {
-            injectedScripts.set(script.id, { id: script.id, textContent: script.textContent });
-          }
-        }),
-      },
-    } as any;
+    // Track executed code by intercepting Function constructor
+    executedCode = [];
+    originalFunction = global.Function;
+    functionSpy = spyOn(global, "Function").mockImplementation(((...args: any[]) => {
+      if (args.length > 0 && typeof args[args.length - 1] === 'string') {
+        const code = args[args.length - 1];
+        // Only track ScriptExecutor calls (they contain "Component:" comment)
+        if (code.includes('Component:')) {
+          executedCode.push(code);
+        }
+      }
+      // Return a function that executes the code
+      return originalFunction(...args) as any;
+    }) as unknown as FunctionConstructor);
   });
 
   afterEach(() => {
-    injectedScripts.clear();
-    // Restore original document
-    global.document = originalDocument;
+    functionSpy.mockRestore();
+    executedCode = [];
   });
 
   describe("constructor", () => {
@@ -80,7 +65,7 @@ describe("ScriptExecutor", () => {
 
       scriptExecutor.execute();
 
-      expect(injectedScripts.size).toBe(0);
+      expect(executedCode.length).toBe(0);
     });
 
     test("should execute JavaScript without templates once", () => {
@@ -97,11 +82,9 @@ describe("ScriptExecutor", () => {
 
       scriptExecutor.execute();
 
-      expect(injectedScripts.size).toBe(1);
-      const script = injectedScripts.get("meno-script-TestComponent");
-      expect(script).toBeDefined();
-      expect(script!.textContent).toContain("Component: TestComponent");
-      expect(script!.textContent).toContain("console.log('test');");
+      expect(executedCode.length).toBe(1);
+      expect(executedCode[0]).toContain("Component: TestComponent");
+      expect(executedCode[0]).toContain("console.log('test');");
     });
 
     // Template-based tests require full ElementRegistry from @meno/studio
@@ -118,8 +101,8 @@ describe("ScriptExecutor", () => {
       componentRegistry.register("TestComponent", componentDef);
 
       // Register component instances with props
-      const mockElement1 = originalDocument.createElement("div");
-      const mockElement2 = originalDocument.createElement("div");
+      const mockElement1 = document.createElement("div");
+      const mockElement2 = document.createElement("div");
       elementRegistry.register([0], mockElement1, "TestComponent", true, {
         name: "Instance1",
       });
@@ -129,8 +112,8 @@ describe("ScriptExecutor", () => {
 
       scriptExecutor.execute();
 
-      // Each instance gets its own script tag
-      expect(injectedScripts.size).toBe(2);
+      // Each instance gets its own execution
+      expect(executedCode.length).toBe(2);
     });
 
     test("should execute JavaScript without templates only once for multiple instances", () => {
@@ -146,8 +129,8 @@ describe("ScriptExecutor", () => {
       componentRegistry.register("TestComponent", componentDef);
 
       // Register multiple instances
-      const mockElement1 = originalDocument.createElement("div");
-      const mockElement2 = originalDocument.createElement("div");
+      const mockElement1 = document.createElement("div");
+      const mockElement2 = document.createElement("div");
       elementRegistry.register([0], mockElement1, "TestComponent", true, {
         name: "Instance1",
       });
@@ -157,12 +140,10 @@ describe("ScriptExecutor", () => {
 
       scriptExecutor.execute();
 
-      // Should only inject one script (no templates - executes once per component type)
-      expect(injectedScripts.size).toBe(1);
-      const script = injectedScripts.get("meno-script-TestComponent");
-      expect(script).toBeDefined();
-      expect(script!.textContent).toContain("Component: TestComponent");
-      expect(script!.textContent).toContain("console.log('test');");
+      // Should only execute once (no templates - executes once per component type)
+      expect(executedCode.length).toBe(1);
+      expect(executedCode[0]).toContain("Component: TestComponent");
+      expect(executedCode[0]).toContain("console.log('test');");
     });
 
     test.skip("should handle multiple components with mixed template/non-template JavaScript (requires @meno/studio ElementRegistry)", () => {
@@ -187,16 +168,16 @@ describe("ScriptExecutor", () => {
       componentRegistry.register("Component1", componentDef1);
       componentRegistry.register("Component2", componentDef2);
 
-      const mockElement = originalDocument.createElement("div");
+      const mockElement = document.createElement("div");
       elementRegistry.register([0], mockElement, "Component2", true, {
         name: "Component2Instance",
       });
 
       scriptExecutor.execute();
 
-      // Component1: 1 script tag (no templates)
-      // Component2: 1 script tag (with templates, 1 instance)
-      expect(injectedScripts.size).toBe(2);
+      // Component1: 1 execution (no templates)
+      // Component2: 1 execution (with templates, 1 instance)
+      expect(executedCode.length).toBe(2);
     });
 
     test("should handle fallback for components without instances", () => {
@@ -326,11 +307,9 @@ describe("ScriptExecutor", () => {
 
       scriptExecutor.execute();
 
-      expect(injectedScripts.size).toBe(1);
-      const script = injectedScripts.get("meno-script-TestComponent");
-      expect(script).toBeDefined();
-      expect(script!.textContent).toContain("(function()");
-      expect(script!.textContent).toContain("})();");
+      expect(executedCode.length).toBe(1);
+      expect(executedCode[0]).toContain("(function()");
+      expect(executedCode[0]).toContain("})();");
     });
   });
 
@@ -359,12 +338,10 @@ describe("ScriptExecutor", () => {
 
       scriptExecutor.executeForComponent("Component1");
 
-      // Only Component1 should be injected
-      expect(injectedScripts.size).toBe(1);
-      const script = injectedScripts.get("meno-script-Component1");
-      expect(script).toBeDefined();
-      expect(script!.textContent).toContain("Component: Component1");
-      expect(script!.textContent).toContain("console.log('Component1');");
+      // Only Component1 should be executed
+      expect(executedCode.length).toBe(1);
+      expect(executedCode[0]).toContain("Component: Component1");
+      expect(executedCode[0]).toContain("console.log('Component1');");
     });
 
     test.skip("should execute JavaScript with templates for specific component (requires @meno/studio ElementRegistry)", () => {
@@ -379,8 +356,8 @@ describe("ScriptExecutor", () => {
 
       componentRegistry.register("TestComponent", componentDef);
 
-      const mockElement1 = originalDocument.createElement("div");
-      const mockElement2 = originalDocument.createElement("div");
+      const mockElement1 = document.createElement("div");
+      const mockElement2 = document.createElement("div");
       elementRegistry.register([0], mockElement1, "TestComponent", true, {
         name: "Instance1",
       });
@@ -390,8 +367,8 @@ describe("ScriptExecutor", () => {
 
       scriptExecutor.executeForComponent("TestComponent");
 
-      // Each instance gets its own script tag
-      expect(injectedScripts.size).toBe(2);
+      // Each instance gets its own execution
+      expect(executedCode.length).toBe(2);
     });
 
     test("should skip if component has no JavaScript", () => {
@@ -407,7 +384,7 @@ describe("ScriptExecutor", () => {
 
       scriptExecutor.executeForComponent("TestComponent");
 
-      expect(injectedScripts.size).toBe(0);
+      expect(executedCode.length).toBe(0);
     });
 
     test("should handle non-existent component gracefully", () => {
@@ -468,8 +445,8 @@ describe("ScriptExecutor", () => {
       componentRegistry.register("DynamicComponent", componentDef2);
 
       // Register multiple instances of dynamic component
-      const mockElement1 = originalDocument.createElement("div");
-      const mockElement2 = originalDocument.createElement("div");
+      const mockElement1 = document.createElement("div");
+      const mockElement2 = document.createElement("div");
       elementRegistry.register([0], mockElement1, "DynamicComponent", true, {
         id: "1",
       });
@@ -479,9 +456,9 @@ describe("ScriptExecutor", () => {
 
       scriptExecutor.execute();
 
-      // StaticComponent: 1 script tag (no templates)
-      // DynamicComponent: 2 script tags (with templates, 2 instances)
-      expect(injectedScripts.size).toBe(3);
+      // StaticComponent: 1 execution (no templates)
+      // DynamicComponent: 2 executions (with templates, 2 instances)
+      expect(executedCode.length).toBe(3);
     });
   });
 });

package/lib/client/scripts/ScriptExecutor.ts

@@ -42,7 +42,6 @@ function generateDestructure(
 export class ScriptExecutor {
   private componentRegistry: ComponentRegistry;
   private elementRegistry: ElementRegistry;
-  private injectedScripts: Set<string> = new Set();
 
   constructor(config: ScriptExecutorConfig) {
     this.componentRegistry = config.componentRegistry;
@@ -50,54 +49,31 @@ export class ScriptExecutor {
   }
 
   /**
-   * Inject JavaScript as a separate script tag for browser-level isolation
-   * Each component gets its own script tag - syntax errors in one don't affect others
-   * @param jsCode - JavaScript code to inject
-   * @param componentName - Component name for identification
-   * @param instanceId - Optional instance ID for per-instance scripts
+   * Execute JavaScript code via new Function() with error isolation
+   * Uses new Function() instead of script tags to avoid CSP violations
+   * Each component is wrapped in try-catch for isolation
+   * @param jsCode - JavaScript code to execute
+   * @param componentName - Component name for error reporting
    * @private
    */
-  private injectScriptTag(jsCode: string, componentName: string, instanceId?: string): void {
+  private executeWrappedJS(jsCode: string, componentName: string): void {
     if (!jsCode || !jsCode.trim()) return;
-    if (typeof document === 'undefined') return;
 
-    const scriptId = instanceId
-      ? `meno-script-${componentName}-${instanceId}`
-      : `meno-script-${componentName}`;
+    const wrappedJS = `(function() {
+      // Component: ${componentName}
+      try {
+        ${jsCode}
+      } catch (e) {
+        console.error('[Meno] Runtime error in ' + ${JSON.stringify(componentName)} + ':', e);
+      }
+    })();`;
 
-    // Remove existing script with same ID to allow re-execution
-    const existing = document.getElementById(scriptId);
-    if (existing) {
-      existing.remove();
+    try {
+      new Function(wrappedJS)();
+    } catch (syntaxError) {
+      // Syntax errors caught here - doesn't affect other components
+      console.error(`[Meno] Syntax error in ${componentName}:`, syntaxError);
     }
-
-    const script = document.createElement('script');
-    script.id = scriptId;
-    script.type = 'text/javascript';
-    script.textContent = `(function() {
-  // Component: ${componentName}${instanceId ? ` (instance: ${instanceId})` : ''}
-  try {
-    ${jsCode}
-  } catch (e) {
-    console.error('[Meno] Error in ${componentName}:', e);
-  }
-})();`;
-
-    document.body.appendChild(script);
-    this.injectedScripts.add(scriptId);
-  }
-
-  /**
-   * Execute JavaScript code via script tag injection for browser-level isolation
-   * @param jsCode - JavaScript code to execute
-   * @param componentName - Component name for identification
-   * @param rootPath - Optional root path for instance-specific scripts
-   * @private
-   */
-  private executeWrappedJS(jsCode: string, componentName: string, rootPath?: string): void {
-    // Convert rootPath to a safe ID (replace special chars)
-    const instanceId = rootPath ? rootPath.replace(/[^a-zA-Z0-9]/g, '-') : undefined;
-    this.injectScriptTag(jsCode, componentName, instanceId);
   }
 
   /**
@@ -117,10 +93,10 @@ export class ScriptExecutor {
 
       try {
         const processedJS = processCodeTemplates(originalJS, props);
-        this.executeWrappedJS(processedJS, componentName, rootPath);
+        this.executeWrappedJS(processedJS, `${componentName} (instance: ${rootPath})`);
       } catch (templateError) {
         // Fallback to original JS if template processing fails (similar to StyleInjector)
-        this.executeWrappedJS(originalJS, componentName, rootPath);
+        this.executeWrappedJS(originalJS, `${componentName} (instance: ${rootPath})`);
       }
     } catch (e) {
       logRuntimeError('ScriptExecutor.executeInstanceJS', e, { componentName, rootPath });
@@ -144,17 +120,28 @@ export class ScriptExecutor {
   ): void {
     const destructure = generateDestructure(defineVars, interfaceDef);
 
-    const initJS = `var elements = document.querySelectorAll('[data-component="${componentName}"]');
-elements.forEach(function(el) {
-  var propsStr = el.getAttribute('data-props');
-  var props = propsStr ? JSON.parse(propsStr) : {};
-  (function(el, props) {
-    ${destructure}
-    ${js}
-  })(el, props);
-});`;
-
-    this.injectScriptTag(initJS, componentName + '-init');
+    const wrappedJS = `(function() {
+      // Component: ${componentName} (defineVars)
+      try {
+        var elements = document.querySelectorAll('[data-component="${componentName}"]');
+        elements.forEach(function(el) {
+          var propsStr = el.getAttribute('data-props');
+          var props = propsStr ? JSON.parse(propsStr) : {};
+          (function(el, props) {
+            ${destructure}
+            ${js}
+          })(el, props);
+        });
+      } catch (e) {
+        console.error('[Meno] Runtime error in ${componentName}:', e);
+      }
+    })();`;
+
+    try {
+      new Function(wrappedJS)();
+    } catch (syntaxError) {
+      console.error(`[Meno] Syntax error in ${componentName}:`, syntaxError);
+    }
   }
 
   /**
@@ -317,20 +304,5 @@ elements.forEach(function(el) {
       logRuntimeError('ScriptExecutor.executeForElement', e, { componentName });
     }
   }
-
-  /**
-   * Remove all injected script tags (for cleanup on unmount/navigation)
-   */
-  cleanup(): void {
-    if (typeof document === 'undefined') return;
-
-    for (const scriptId of this.injectedScripts) {
-      const script = document.getElementById(scriptId);
-      if (script) {
-        script.remove();
-      }
-    }
-    this.injectedScripts.clear();
-  }
 }
 

package/lib/server/createServer.ts

@@ -1,6 +1,6 @@
 /**
  * Server Factory
- * Creates a configurable Bun server for @meno/core
+ * Creates a configurable Bun server for meno-core
  * Can be extended by @meno/studio for editor functionality
  */
 

package/lib/server/index.ts

@@ -1,5 +1,5 @@
 /**
- * @meno/core/server exports
+ * meno-core/server exports
  * Core server-side utilities for SSR and read APIs
  * Does NOT include editor-specific routes (that's in @meno/studio)
  */

package/lib/server/routes/api/core-routes.ts

@@ -1,6 +1,6 @@
 /**
  * Core API Routes (Read-only)
- * These routes are part of @meno/core and handle read operations
+ * These routes are part of meno-core and handle read operations
  */
 
 import { API_ROUTES } from '../../../shared/constants';

package/lib/server/routes/api/index.ts

@@ -50,7 +50,7 @@ export async function handleApiRoutes(
 }
 
 /**
- * Handle only core API routes (for @meno/core without editor)
+ * Handle only core API routes (for meno-core without editor)
  */
 export async function handleCoreOnlyApiRoutes(
   req: Request,

package/lib/server/ssr/htmlGenerator.ts

@@ -1,6 +1,7 @@
 /**
  * HTML document generation for SSR
  * Generates complete HTML documents with SSR content
+ * Supports CSP-compliant external scripts for static builds
  */
 
 import type { ComponentDefinition, JSONPage } from '../../shared/types';
@@ -18,10 +19,80 @@ import { renderPageSSR } from './ssrRenderer';
 import type { CMSContext } from './cmsSSRProcessor';
 
 /**
- * Generate complete HTML document with SSR content
+ * Result of SSR HTML generation with separate JS for CSP compliance
+ */
+export interface SSRHTMLResult {
+  /** Complete HTML document */
+  html: string;
+  /** JavaScript code to be written to external file (for CSP compliance) */
+  javascript: string | null;
+}
+
+/**
+ * Options for SSR HTML generation
+ */
+export interface GenerateSSRHTMLOptions {
+  /** Page data to render */
+  pageData: JSONPage;
+  /** Global component definitions */
+  globalComponents?: Record<string, ComponentDefinition>;
+  /** URL path for the page */
+  pagePath?: string;
+  /** Base URL for assets */
+  baseUrl?: string;
+  /** Use built bundle (production) vs dev server */
+  useBuiltBundle?: boolean;
+  /** Locale for i18n */
+  locale?: string;
+  /** Slug mappings for locale switching */
+  slugMappings?: SlugMap[];
+  /** CMS context for template rendering */
+  cmsContext?: CMSContext;
+  /** CMS service for CMSList queries */
+  cmsService?: CMSService;
+  /**
+   * Path to external scripts file (for CSP compliance).
+   * When provided, JS is NOT inlined but referenced via this path.
+   * Example: "/_scripts/abc123.js"
+   */
+  externalScriptPath?: string;
+}
+
+/**
+ * Generate complete HTML document with SSR content (legacy positional args)
  */
 export async function generateSSRHTML(
   pageData: JSONPage,
+  globalComponents?: Record<string, ComponentDefinition>,
+  pagePath?: string,
+  baseUrl?: string,
+  useBuiltBundle?: boolean,
+  locale?: string,
+  slugMappings?: SlugMap[],
+  cmsContext?: CMSContext,
+  cmsService?: CMSService,
+  externalScriptPath?: string
+): Promise<string>;
+
+/**
+ * Generate complete HTML document with SSR content (options object, returns separate JS for CSP)
+ */
+export async function generateSSRHTML(
+  options: GenerateSSRHTMLOptions & { returnSeparateJS: true }
+): Promise<SSRHTMLResult>;
+
+/**
+ * Generate complete HTML document with SSR content (options object)
+ */
+export async function generateSSRHTML(
+  options: GenerateSSRHTMLOptions & { returnSeparateJS?: false }
+): Promise<string>;
+
+/**
+ * Generate complete HTML document with SSR content
+ */
+export async function generateSSRHTML(
+  pageDataOrOptions: JSONPage | (GenerateSSRHTMLOptions & { returnSeparateJS?: boolean }),
   globalComponents: Record<string, ComponentDefinition> = {},
   pagePath: string = '/',
   baseUrl: string = '',
@@ -29,28 +100,75 @@ export async function generateSSRHTML(
   locale?: string,
   slugMappings?: SlugMap[],
   cmsContext?: CMSContext,
-  cmsService?: CMSService
-): Promise<string> {
-  const rendered = await renderPageSSR(pageData, globalComponents, pagePath, baseUrl, locale, undefined, slugMappings, cmsContext, cmsService);
+  cmsService?: CMSService,
+  externalScriptPath?: string
+): Promise<string | SSRHTMLResult> {
+  // Handle options object vs legacy positional args
+  let options: GenerateSSRHTMLOptions & { returnSeparateJS?: boolean };
+
+  if ('pageData' in pageDataOrOptions) {
+    options = pageDataOrOptions;
+  } else {
+    options = {
+      pageData: pageDataOrOptions,
+      globalComponents,
+      pagePath,
+      baseUrl,
+      useBuiltBundle,
+      locale,
+      slugMappings,
+      cmsContext,
+      cmsService,
+      externalScriptPath,
+    };
+  }
+
+  const {
+    pageData,
+    globalComponents: components = {},
+    pagePath: path = '/',
+    baseUrl: base = '',
+    useBuiltBundle: useBundled = false,
+    locale: loc,
+    slugMappings: slugs,
+    cmsContext: cms,
+    cmsService: cmsServ,
+    externalScriptPath: extScriptPath,
+    returnSeparateJS = false,
+  } = options;
+  const rendered = await renderPageSSR(pageData, components, path, base, loc, undefined, slugs, cms, cmsServ);
 
   // Use built bundle in production, dev server in development
-  const clientScript = useBuiltBundle
+  const clientScript = useBundled
     ? '' // No client router in static build (true static HTML)
     : '<script type="module" src="/client-router.tsx"></script>'; // Dev server (development)
 
-  // Render component JavaScript if any
-  // Escape </script> sequences to prevent premature script tag closure
-  const escapedJavaScript = rendered.javascript
-    ? rendered.javascript.replace(/<\/script>/gi, '<\\/script>')
-    : '';
-  const componentScript = escapedJavaScript
-    ? `\n  <script>\n${escapedJavaScript}\n  </script>`
-    : '';
+  // Collect all JavaScript (component JS + form handler if needed)
+  const needsForm = needsFormHandler(rendered.html);
+  const allJavaScript = [
+    rendered.javascript || '',
+    needsForm ? formHandlerScript : ''
+  ].filter(Boolean).join('\n\n');
 
-  // Add form handler script if page contains fetch-handled forms
-  const formScript = needsFormHandler(rendered.html)
-    ? `\n  <script>\n${formHandlerScript}\n  </script>`
-    : '';
+  // Determine script output based on mode
+  let componentScript = '';
+  let externalJavaScript: string | null = null;
+
+  if (allJavaScript) {
+    if (extScriptPath) {
+      // CSP-compliant: reference external script file
+      componentScript = `\n  <script src="${extScriptPath}"></script>`;
+      externalJavaScript = allJavaScript;
+    } else if (returnSeparateJS) {
+      // Return JS separately (for build-static to write to file)
+      externalJavaScript = allJavaScript;
+    } else {
+      // Legacy inline mode (dev server)
+      // Escape </script> sequences to prevent premature script tag closure
+      const escapedJavaScript = allJavaScript.replace(/<\/script>/gi, '<\\/script>');
+      componentScript = `\n  <script>\n${escapedJavaScript}\n  </script>`;
+    }
+  }
 
   // Generate font CSS from project config
   const fontCSS = generateFontCSS();
@@ -83,9 +201,15 @@ export async function generateSSRHTML(
   const prefetchConfig = await loadPrefetchConfig();
   // Only include non-default values to minimize payload
   const menoConfig = prefetchConfig.enabled ? { prefetch: prefetchConfig } : {};
-  const configScript = Object.keys(menoConfig).length > 0
+  // Config script - inline for dev, include in external JS for static build
+  const hasConfig = Object.keys(menoConfig).length > 0;
+  const configInlineScript = hasConfig && !extScriptPath && !returnSeparateJS
     ? `<script>window.__MENO_CONFIG__=${JSON.stringify(menoConfig)}</script>\n  `
     : '';
+  // Add config to external JS if using external scripts
+  if (hasConfig && externalJavaScript !== null) {
+    externalJavaScript = `window.__MENO_CONFIG__=${JSON.stringify(menoConfig)};\n\n` + externalJavaScript;
+  }
 
   // Generate favicon and apple touch icon link tags
   const faviconTag = iconsConfig.favicon
@@ -96,13 +220,13 @@ export async function generateSSRHTML(
     : '';
   const iconTags = [faviconTag, appleTouchIconTag].filter(Boolean).join('\n  ');
 
-  return `<!DOCTYPE html>
+  const htmlDocument = `<!DOCTYPE html>
 <html lang="${rendered.locale}" theme="${themeConfig.default}">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   ${iconTags ? iconTags + '\n  ' : ''}${rendered.meta}
-  ${configScript}<style>
+  ${configInlineScript}<style>
     ${fontCSS ? fontCSS + '\n    ' : ''}${themeColorVariablesCSS ? themeColorVariablesCSS + '\n    ' : ''}* {
       margin: 0;
       padding: 0;
@@ -141,7 +265,17 @@ export async function generateSSRHTML(
   <div id="root">
     ${rendered.html}
   </div>
-  ${clientScript}${componentScript}${formScript}
+  ${clientScript}${componentScript}
 </body>
 </html>`;
+
+  // Return based on mode
+  if (returnSeparateJS) {
+    return {
+      html: htmlDocument,
+      javascript: externalJavaScript
+    };
+  }
+
+  return htmlDocument;
 }

package/lib/server/ssr/index.ts

@@ -17,6 +17,7 @@
 export { renderPageSSR, extractPageMeta, generateMetaTags } from './ssrRenderer';
 export type { CMSContext, PageMeta } from './ssrRenderer';
 export { generateSSRHTML } from './htmlGenerator';
+export type { SSRHTMLResult, GenerateSSRHTMLOptions } from './htmlGenerator';
 
 // Attribute utilities
 export { escapeHtml, buildAttributes, styleToString } from './attributeBuilder';

package/lib/shared/index.ts

@@ -1,5 +1,5 @@
 /**
- * @meno/core shared exports
+ * meno-core shared exports
  * Re-exports all types, constants, and utilities from shared modules
  */
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meno-core",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "type": "module",
   "bin": {
     "meno": "./bin/cli.ts"

package/tsconfig.json

@@ -5,8 +5,8 @@
     "outDir": "./dist",
     "baseUrl": ".",
     "paths": {
-      "@meno/core": ["./lib/shared/index.ts"],
-      "@meno/core/*": ["./lib/*"]
+      "meno-core": ["./lib/shared/index.ts"],
+      "meno-core/*": ["./lib/*"]
     }
   },
   "include": ["lib/**/*", "entries/**/*", "bin/**/*"],

package/vite.config.ts

@@ -37,7 +37,7 @@ export default defineConfig({
   },
   resolve: {
     alias: {
-      '@meno/core': path.resolve(__dirname, 'lib/shared/index.ts'),
+      'meno-core': path.resolve(__dirname, 'lib/shared/index.ts'),
     },
   },
 })