slicejs-web-framework 3.5.4 → 4.0.0

package/api/framework/devDepsOptimizer.js

@@ -0,0 +1,335 @@
+// api/framework/devDepsOptimizer.js
+//
+// Development-only resolution of bare package imports (node_modules) for the
+// Slice.js dev server. There is NO app bundling in dev: component files are
+// still served and executed as native ES modules. This optimizer only does two
+// small, Vite-style things so `import dayjs from 'dayjs'` works in the browser:
+//
+//   1. rewriteBareImports(code): rewrites bare specifiers in a served source
+//      file to a virtual URL under `/@slice-modules/…` that the browser can
+//      fetch as a normal ES module. Relative ('./'), absolute ('/…', served
+//      from src/public/), and URL/data imports are left untouched.
+//
+//   2. bundlePackage(spec): on demand, pre-bundles a single node_modules
+//      package with esbuild into a self-contained ESM file (CommonJS interop +
+//      transitive third-party graph resolved by esbuild) and caches it. This is
+//      the same esbuild resolver the production build uses, so a dependency
+//      behaves identically in dev and in `slice build` / `slice start`.
+//
+// This module is the ONLY place in the framework runtime allowed to import
+// esbuild / es-module-lexer (team rule: external libraries stay behind an
+// internal abstraction).
+
+import { init as lexerInit, parse as lexerParse } from 'es-module-lexer';
+import { build as esbuildBuild } from 'esbuild';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+export const MODULES_PREFIX = '/@slice-modules/';
+const URL_SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+
+// Non-JS assets a package may import are inlined as data URLs so each served
+// package module stays a single self-contained ESM file (matches the build).
+const ASSET_LOADERS = {
+  '.wasm': 'dataurl',
+  '.png': 'dataurl',
+  '.jpg': 'dataurl',
+  '.jpeg': 'dataurl',
+  '.gif': 'dataurl',
+  '.svg': 'dataurl',
+  '.webp': 'dataurl',
+  '.avif': 'dataurl',
+  '.woff': 'dataurl',
+  '.woff2': 'dataurl',
+  '.ttf': 'dataurl',
+  '.eot': 'dataurl',
+  // Text assets some packages import as strings (GLSL shaders, templates).
+  // Kept identical to the production bundler so dev and build behave the same.
+  '.txt': 'text',
+  '.glsl': 'text',
+  '.vert': 'text',
+  '.frag': 'text',
+  '.vs': 'text',
+  '.fs': 'text'
+};
+
+/**
+ * Minimal browser shims for the Node globals browser-targeted packages still
+ * touch at runtime: `process` (env/platform/nextTick) and `global`. NOT a Node
+ * polyfill (no Buffer/stream/fs) — it only prevents a ReferenceError on a
+ * dynamic `process.platform` / `process.env[key]` / free `global`. Idempotent
+ * and guarded; kept byte-identical to the production bundler's banner so a
+ * package behaves the same in dev and after `slice build`.
+ * @param {string} nodeEnv value exposed as process.env.NODE_ENV at runtime.
+ */
+function nodeGlobalsBanner(nodeEnv) {
+  return [
+    '(function(){',
+    '  if (typeof globalThis === "undefined") return;',
+    '  if (typeof globalThis.global === "undefined") globalThis.global = globalThis;',
+    '  if (typeof globalThis.process === "undefined") {',
+    `    globalThis.process = { env: { NODE_ENV: ${JSON.stringify(nodeEnv)} }, argv: [], platform: "browser", browser: true, version: "", versions: {}, cwd: function(){ return "/"; }, nextTick: function(cb){ Promise.resolve().then(cb); } };`,
+    '  } else if (typeof globalThis.process.env === "undefined") {',
+    `    globalThis.process.env = { NODE_ENV: ${JSON.stringify(nodeEnv)} };`,
+    '  }',
+    '})();'
+  ].join('\n');
+}
+
+function cssInjectionKey(css) {
+  let h = 5381;
+  for (let i = 0; i < css.length; i += 1) {
+    h = ((h << 5) + h + css.charCodeAt(i)) >>> 0;
+  }
+  return `ext-${h.toString(36)}`;
+}
+
+function buildCssInjectionSnippet(css) {
+  const key = cssInjectionKey(css);
+  return [
+    '(function(){',
+    '  if (typeof document === "undefined") return;',
+    `  var __k = ${JSON.stringify(key)};`,
+    "  if (document.querySelector('style[data-slice-external=\"' + __k + '\"]')) return;",
+    '  var __sliceStyle = document.createElement("style");',
+    '  __sliceStyle.setAttribute("data-slice-external", __k);',
+    `  __sliceStyle.textContent = ${JSON.stringify(css)};`,
+    '  document.head.appendChild(__sliceStyle);',
+    '})();'
+  ].join('\n');
+}
+
+function combineEsbuildOutputs(outputFiles = []) {
+  const jsOut = outputFiles.find((f) => /\.(js|mjs|cjs)$/.test(f.path)) || outputFiles[0];
+  const cssOut = outputFiles.find((f) => f.path.endsWith('.css'));
+  let code = jsOut?.text || '';
+  if (cssOut?.text && cssOut.text.trim()) {
+    code += `\n${buildCssInjectionSnippet(cssOut.text)}`;
+  }
+  return code;
+}
+
+function isBareSpecifier(spec) {
+  if (typeof spec !== 'string' || spec.length === 0) return false;
+  if (spec.startsWith('.')) return false;
+  if (spec.startsWith('/')) return false;
+  if (spec.startsWith('#')) return false;
+  if (URL_SCHEME_RE.test(spec)) return false;
+  return true;
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.projectRoot Root esbuild resolves node_modules from.
+ * @param {boolean} [options.enabled] Whether the feature is active.
+ * @param {string} [options.target] esbuild target (default 'es2020').
+ */
+export function createDevDepsOptimizer({ projectRoot, enabled = true, target = 'es2020' }) {
+  // spec -> Promise<{ code }>. Store the promise so concurrent first requests
+  // for the same package share a single esbuild run.
+  const cache = new Map();
+  let lexerReady = false;
+  const lexerReadyPromise = lexerInit
+    .then(() => { lexerReady = true; })
+    .catch(() => { /* lexer failed to init; rewrite becomes a no-op */ });
+
+  /**
+   * Rewrites bare import specifiers in `code` to `/@slice-modules/<spec>`.
+   * Returns the original code unchanged when there is nothing to rewrite.
+   * @param {string} code
+   * @returns {Promise<string>}
+   */
+  async function rewriteBareImports(code) {
+    if (!enabled || typeof code !== 'string' || code.length === 0) return code;
+    if (!lexerReady) await lexerReadyPromise;
+    if (!lexerReady) return code;
+
+    let imports;
+    try {
+      [imports] = lexerParse(code);
+    } catch {
+      return code; // unparseable → serve as-is
+    }
+    if (!imports || imports.length === 0) return code;
+
+    let out = '';
+    let cursor = 0;
+    for (const imp of imports) {
+      const spec = imp.n;
+      // imp.s/imp.e delimit the specifier. For STATIC imports the range is the
+      // inner text without quotes; for DYNAMIC imports (imp.d > -1) it includes
+      // the surrounding quotes/backticks. imp.s is -1 when the specifier is not
+      // a static string (e.g. import(variable)) — skip those.
+      if (imp.s < 0 || imp.e < 0) continue;
+      if (!spec || !isBareSpecifier(spec)) continue;
+
+      out += code.slice(cursor, imp.s);
+      if (imp.d > -1) {
+        // Dynamic import: preserve the original quote character.
+        const quote = code[imp.s];
+        out += `${quote}${MODULES_PREFIX}${spec}${quote}`;
+      } else {
+        out += `${MODULES_PREFIX}${spec}`;
+      }
+      cursor = imp.e;
+    }
+    out += code.slice(cursor);
+    return out;
+  }
+
+  async function runEsbuild(entryContents) {
+    const result = await esbuildBuild({
+      stdin: {
+        contents: entryContents,
+        resolveDir: projectRoot,
+        sourcefile: 'slice-dev-external-entry.js',
+        loader: 'js'
+      },
+      bundle: true,
+      format: 'esm',
+      platform: 'browser',
+      target,
+      write: false,
+      metafile: false,
+      legalComments: 'none',
+      logLevel: 'silent',
+      // Standard browser-build substitutions (matches the production bundler):
+      // packages that gate on NODE_ENV or reference `global` work without a
+      // polyfill. esbuild respects local shadowing.
+      define: {
+        'process.env.NODE_ENV': JSON.stringify('development'),
+        global: 'globalThis'
+      },
+      // Runtime shim for the Node globals `define` cannot fold statically; runs
+      // once, guarded, before the package body. Matches the production bundler.
+      banner: { js: nodeGlobalsBanner('development') },
+      // Required for esbuild to emit a CSS output file when a package imports
+      // CSS; nothing is written to disk (write:false).
+      outdir: 'slice-external-out',
+      // Inline WASM/images/fonts as data URLs and bundle imported CSS, so each
+      // served package is a single self-contained ESM file.
+      loader: ASSET_LOADERS
+    });
+    return combineEsbuildOutputs(result.outputFiles);
+  }
+
+  const diskCacheDir = path.join(projectRoot, 'node_modules', '.slice-deps');
+
+  async function esbuildPackage(spec) {
+    const quoted = JSON.stringify(spec);
+    // Try re-exporting the default too (works for CJS and ESM-with-default).
+    // Packages without a default export make esbuild fail on the explicit
+    // default re-export, so fall back to a namespace-only bundle.
+    try {
+      return await runEsbuild(`export * from ${quoted};\nexport { default } from ${quoted};`);
+    } catch {
+      return await runEsbuild(`export * from ${quoted};`);
+    }
+  }
+
+  /** Reads the installed version of a package so the disk cache invalidates on upgrade. */
+  async function packageVersion(spec) {
+    const root = spec.startsWith('@') ? spec.split('/').slice(0, 2).join('/') : spec.split('/')[0];
+    try {
+      const pkg = JSON.parse(await fsp.readFile(path.join(projectRoot, 'node_modules', root, 'package.json'), 'utf8'));
+      return pkg.version || '0.0.0';
+    } catch {
+      return '0.0.0';
+    }
+  }
+
+  /** Sanitized `<spec>@` prefix shared by every cached version of a package. */
+  function specCachePrefix(spec) {
+    return `${spec.replace(/[^a-zA-Z0-9._@-]/g, '_')}@`;
+  }
+
+  async function diskCacheFileFor(spec) {
+    const version = await packageVersion(spec);
+    const safe = `${spec}@${version}`.replace(/[^a-zA-Z0-9._@-]/g, '_');
+    return path.join(diskCacheDir, `${safe}.js`);
+  }
+
+  /**
+   * Removes stale cache files for a package after a new version is written, so
+   * `.slice-deps` doesn't accumulate one file per version across upgrades. The
+   * `<spec>@` prefix is version-independent and the trailing `@` prevents a
+   * package from matching another whose name is a prefix of it. Best-effort.
+   * @param {string} spec bare specifier
+   * @param {string} keepFileName basename of the just-written cache file
+   */
+  async function pruneOldCacheVersions(spec, keepFileName) {
+    const prefix = specCachePrefix(spec);
+    let entries;
+    try {
+      entries = await fsp.readdir(diskCacheDir);
+    } catch {
+      return; // dir missing → nothing to prune
+    }
+    await Promise.all(entries.map(async (name) => {
+      if (name === keepFileName) return;
+      if (!name.startsWith(prefix) || !name.endsWith('.js')) return;
+      try {
+        await fsp.unlink(path.join(diskCacheDir, name));
+      } catch { /* ignore: another process may have removed it */ }
+    }));
+  }
+
+  /**
+   * Pre-bundles a single node_modules package to a self-contained ESM string.
+   * Result is cached in memory (per process) and on disk (across dev-server
+   * restarts), keyed by the installed package version.
+   * @param {string} spec bare specifier (e.g. 'dayjs', '@scope/pkg', 'lodash/fp')
+   * @returns {Promise<{ code: string }>}
+   */
+  function bundlePackage(spec) {
+    if (!isBareSpecifier(spec)) {
+      return Promise.reject(new Error(`Not a bare package specifier: ${spec}`));
+    }
+    if (cache.has(spec)) return cache.get(spec);
+
+    const promise = (async () => {
+      const cacheFile = await diskCacheFileFor(spec);
+
+      // 1) Disk cache hit — skip esbuild entirely.
+      try {
+        const code = await fsp.readFile(cacheFile, 'utf8');
+        return { code };
+      } catch { /* miss → build */ }
+
+      // 2) Build, then populate the disk cache (best-effort) and drop any
+      // previously-cached versions of this same package.
+      const code = await esbuildPackage(spec);
+      try {
+        await fsp.mkdir(diskCacheDir, { recursive: true });
+        await fsp.writeFile(cacheFile, code);
+        await pruneOldCacheVersions(spec, path.basename(cacheFile));
+      } catch { /* cache is an optimization; ignore write failures */ }
+      return { code };
+    })();
+
+    // Cache the promise; on failure, evict so a later request can retry.
+    promise.catch(() => cache.delete(spec));
+    cache.set(spec, promise);
+    return promise;
+  }
+
+  /**
+   * Extracts the package specifier from a `/@slice-modules/…` request path.
+   * @param {string} reqPath
+   * @returns {string|null}
+   */
+  function specifierFromRequest(reqPath) {
+    if (typeof reqPath !== 'string' || !reqPath.startsWith(MODULES_PREFIX)) return null;
+    const spec = reqPath.slice(MODULES_PREFIX.length);
+    return spec.length > 0 ? spec : null;
+  }
+
+  return {
+    enabled,
+    MODULES_PREFIX,
+    rewriteBareImports,
+    bundlePackage,
+    specifierFromRequest,
+    isBareSpecifier
+  };
+}

package/api/framework/precompressedStatic.js

@@ -0,0 +1,93 @@
+// api/framework/precompressedStatic.js
+//
+// Serves a precompressed `.br`/`.gz` sibling (produced by `slice build --compress`)
+// when the client accepts that encoding and the file exists, instead of
+// compressing on every request. Falls through to the normal static handlers
+// when there is no precompressed variant or the client doesn't accept one.
+//
+// Mounted before the runtime `compression` middleware short-circuits it: the
+// response ends here with Content-Encoding already set, so compression never
+// re-compresses an already-encoded body.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ENCODING_EXTENSION = { br: '.br', gzip: '.gz' };
+
+// Only known text types are served pre-encoded; the Content-Type is taken from
+// the ORIGINAL extension (the browser must not see `.br` as the type).
+const CONTENT_TYPES = {
+  '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
+  '.cjs': 'application/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.xml': 'application/xml; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.webmanifest': 'application/manifest+json; charset=utf-8'
+};
+
+/** Encodings the client accepts, most-preferred first (brotli over gzip). */
+function preferredEncodings(acceptEncoding) {
+  const accepts = String(acceptEncoding || '').toLowerCase();
+  const list = [];
+  if (accepts.includes('br')) list.push('br');
+  if (accepts.includes('gzip')) list.push('gzip');
+  return list;
+}
+
+/**
+ * @param {string[]} roots Absolute directories to resolve `req.path` against,
+ *   in priority order (e.g. [dist/public, dist]).
+ * @returns {import('express').RequestHandler}
+ */
+export function createPrecompressedStatic(roots = []) {
+  const resolvedRoots = roots.filter(Boolean).map((r) => path.resolve(r));
+
+  return function precompressedStatic(req, res, next) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') return next();
+
+    const encodings = preferredEncodings(req.headers['accept-encoding']);
+    if (encodings.length === 0) return next();
+
+    let rel;
+    try {
+      rel = decodeURIComponent(req.path).replace(/^\/+/, '');
+    } catch {
+      return next();
+    }
+    if (!rel || rel.includes('\0')) return next();
+
+    const ext = path.extname(rel).toLowerCase();
+    const contentType = CONTENT_TYPES[ext];
+    if (!contentType) return next();
+
+    for (const root of resolvedRoots) {
+      const target = path.normalize(path.join(root, rel));
+      // Path traversal guard: the resolved file must stay under the root.
+      if (target !== root && !target.startsWith(root + path.sep)) continue;
+
+      for (const enc of encodings) {
+        const encodedPath = target + ENCODING_EXTENSION[enc];
+        try {
+          if (fs.existsSync(encodedPath) && fs.statSync(encodedPath).isFile()) {
+            res.setHeader('Content-Type', contentType);
+            res.setHeader('Content-Encoding', enc);
+            res.setHeader('Vary', 'Accept-Encoding');
+            return res.send(fs.readFileSync(encodedPath));
+          }
+        } catch {
+          // Unreadable candidate — try the next encoding/root.
+        }
+      }
+    }
+
+    return next();
+  };
+}
+
+export default createPrecompressedStatic;

package/api/framework/securityMiddleware.js

@@ -46,7 +46,7 @@ export function securityMiddleware(options = {}) {
       });
     }
 
-    // 2. Permitir acceso a assets públicos (según sliceConfig.publicFolders)
+    // 2. Permitir acceso a assets públicos (servidos desde src/public/)
     if (allowPublicAssets) {
       const isPublicAsset = publicPaths.some(publicPath => 
         requestPath.startsWith(publicPath)

package/api/framework/server.js

@@ -9,6 +9,8 @@ import {
   suspiciousRequestLogger
 } from './securityMiddleware.js';
 import { createPublicEnvProvider } from './publicEnvResolver.js';
+import { createDevDepsOptimizer } from './devDepsOptimizer.js';
+import { createPrecompressedStatic } from './precompressedStatic.js';
 
 export function createSliceServer(options = {}) {
   const projectRoot = options.projectRoot || process.cwd();
@@ -35,12 +37,6 @@ export function createSliceServer(options = {}) {
 
   const PORT = process.env.PORT || sliceConfig.server?.port || 3001;
 
-  const normalizedPublicFolders = (Array.isArray(sliceConfig.publicFolders) ? sliceConfig.publicFolders : [])
-    .filter((entry) => typeof entry === 'string')
-    .map((entry) => entry.trim())
-    .filter((entry) => entry.length > 0)
-    .map((entry) => (entry.startsWith('/') ? entry : `/${entry}`));
-
   const publicEnvProvider = createPublicEnvProvider({
     mode: runMode,
     envFilePath: path.join(projectRoot, '.env')
@@ -58,9 +54,7 @@ export function createSliceServer(options = {}) {
   // 2. Protección del framework - TOTALMENTE AUTOMÁTICA
   app.use(sliceFrameworkProtection({ port: PORT }));
 
-  app.use(securityMiddleware({
-    publicPaths: normalizedPublicFolders
-  }));
+  app.use(securityMiddleware());
 
   // ==============================================
   // MIDDLEWARES DE APLICACIÓN
@@ -118,8 +112,15 @@ export function createSliceServer(options = {}) {
   // PWA — manifest + service worker (dev y prod)
   // ==============================================
 
+  // Resolve a deployed asset preferring the public/ folder (the convention),
+  // falling back to the deploy root for pre-`public/` projects.
+  const resolveDeployedFile = (fileName) => {
+    const inPublic = path.join(projectRoot, folderDeployed, 'public', fileName);
+    return fs.existsSync(inPublic) ? inPublic : path.join(projectRoot, folderDeployed, fileName);
+  };
+
   const servePwaFile = (res, fileName, contentType, extraHeaders = {}) => {
-    const filePath = path.join(projectRoot, folderDeployed, fileName);
+    const filePath = resolveDeployedFile(fileName);
     try {
       if (fs.existsSync(filePath)) {
         res.setHeader('Content-Type', contentType);
@@ -174,6 +175,15 @@ export function createSliceServer(options = {}) {
     app.use('/Components', (req, res) => res.status(404).send('Not found'));
   }
 
+  // Serve precompressed .br/.gz siblings (from `slice build --compress`) when the
+  // client accepts them. Mounted before the bundle handler and static serves so
+  // it wins, and its Content-Encoding makes the runtime `compression` middleware
+  // skip re-compressing. Production only (dist holds the precompressed files).
+  if (runMode === 'production') {
+    const distRoot = path.join(projectRoot, folderDeployed);
+    app.use(createPrecompressedStatic([path.join(distRoot, 'public'), distRoot]));
+  }
+
   // Middleware personalizado para archivos de bundles con MIME types correctos
   app.use('/bundles/', (req, res, next) => {
     if (req.path.endsWith('.js')) {
@@ -211,8 +221,72 @@ export function createSliceServer(options = {}) {
   }
 
   if (runMode === 'development') {
+    // External (node_modules) dependency support in dev — always on, no app
+    // bundling. Rewrites bare imports in served src modules to /@slice-modules/…
+    // and serves each package pre-bundled on demand with esbuild (same resolver
+    // as the production build → dev/prod parity for CommonJS and ESM packages).
+    const devDeps = createDevDepsOptimizer({ projectRoot });
+
+    if (devDeps.enabled) {
+      const srcRoot = path.join(projectRoot, folderDeployed);
+
+      // Serve a node_modules package pre-bundled as a single ESM module.
+      app.get(/^\/@slice-modules\/(.+)$/, async (req, res) => {
+        const spec = req.params[0];
+        try {
+          const { code } = await devDeps.bundlePackage(spec);
+          res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+          res.setHeader('Cache-Control', 'no-cache');
+          return res.send(code);
+        } catch (error) {
+          const message = `Failed to load external dependency "${spec}": ${error.message}`;
+          console.error(`[slice:dev] ${message}`);
+          res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+          return res
+            .status(502)
+            .send(`throw new Error(${JSON.stringify(message)});`);
+        }
+      });
+
+      // Rewrite bare imports in served src JavaScript to the virtual endpoint.
+      app.use(async (req, res, next) => {
+        if (req.method !== 'GET' && req.method !== 'HEAD') return next();
+        const reqPath = req.path;
+        if (!(reqPath.endsWith('.js') || reqPath.endsWith('.mjs'))) return next();
+        // Framework internals, generated bundles and the virtual endpoint are
+        // served elsewhere and must not be rewritten.
+        if (reqPath.startsWith('/@slice-modules/') || reqPath.startsWith('/bundles/') || reqPath.startsWith('/Slice/')) {
+          return next();
+        }
+
+        const filePath = path.join(srcRoot, decodeURIComponent(reqPath));
+        const normalized = path.normalize(filePath);
+        if (normalized !== srcRoot && !normalized.startsWith(srcRoot + path.sep)) {
+          return next(); // path traversal guard
+        }
+        if (!fs.existsSync(normalized) || !fs.statSync(normalized).isFile()) {
+          return next();
+        }
+
+        try {
+          const original = fs.readFileSync(normalized, 'utf8');
+          const rewritten = await devDeps.rewriteBareImports(original);
+          res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+          return res.send(rewritten);
+        } catch (error) {
+          console.error(`[slice:dev] Failed to rewrite ${reqPath}: ${error.message}`);
+          return next();
+        }
+      });
+    }
+
+    // Centralized public/ folder served at the root URL (Themes, Styles,
+    // images…). Mounted before the general src static so its files win.
+    app.use(express.static(path.join(projectRoot, folderDeployed, 'public')));
     app.use(express.static(path.join(projectRoot, folderDeployed)));
   } else {
+    // Serve the built public/ assets at the root URL.
+    app.use(express.static(path.join(projectRoot, folderDeployed, 'public')));
     app.use('/App', express.static(path.join(projectRoot, folderDeployed, 'App')));
     const serveStaticFile = (req, res, filePath, contentType, fileName) => {
       try {
@@ -235,9 +309,6 @@ export function createSliceServer(options = {}) {
       const configPath = path.join(projectRoot, folderDeployed, 'sliceConfig.json');
       serveStaticFile(req, res, configPath, 'application/json; charset=utf-8', 'sliceConfig.json');
     });
-    for (const folder of normalizedPublicFolders) {
-      app.use(folder, express.static(path.join(projectRoot, folderDeployed, folder)));
-    }
     app.use('/bundles/', express.static(path.join(projectRoot, folderDeployed, 'bundles')));
     app.use('/dist/', express.static(path.join(projectRoot, 'dist')));
   }
@@ -268,11 +339,11 @@ export function createSliceServer(options = {}) {
   // ==============================================
 
   app.get('/robots.txt', (req, res) => {
-    res.sendFile(path.join(projectRoot, folderDeployed, 'robots.txt'));
+    res.sendFile(resolveDeployedFile('robots.txt'));
   });
 
   app.get('/sitemap.xml', (req, res) => {
-    res.sendFile(path.join(projectRoot, folderDeployed, 'sitemap.xml'));
+    res.sendFile(resolveDeployedFile('sitemap.xml'));
   });
 
   // ==============================================

package/api/tests/dev-deps-optimizer.test.js

@@ -0,0 +1,137 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { createDevDepsOptimizer, MODULES_PREFIX } from '../framework/devDepsOptimizer.js';
+
+// projectRoot for esbuild resolution: this framework package's own root, whose
+// node_modules contains es-module-lexer (used here as a real ESM package to
+// bundle). Two dirs up from api/tests/.
+const projectRoot = new URL('../../', import.meta.url).pathname;
+
+test('rewriteBareImports rewrites bare specifiers to the virtual endpoint', async () => {
+  const opt = createDevDepsOptimizer({ projectRoot, enabled: true });
+  const code = [
+    "import dayjs from 'dayjs';",
+    "import { a, b } from '@scope/pkg';",
+    "import './local.js';",
+    "import '/libs/x.js';",
+    "import x from 'https://cdn/x.js';",
+    "const d = import('lodash/fp');"
+  ].join('\n');
+
+  const out = await opt.rewriteBareImports(code);
+
+  assert.match(out, new RegExp(`from '${MODULES_PREFIX}dayjs'`));
+  assert.match(out, new RegExp(`from '${MODULES_PREFIX}@scope/pkg'`));
+  assert.match(out, new RegExp(`import\\('${MODULES_PREFIX}lodash/fp'\\)`));
+  // Relative, absolute (public/) and URL imports are untouched.
+  assert.match(out, /import '\.\/local\.js'/);
+  assert.match(out, /import '\/libs\/x\.js'/);
+  assert.match(out, /from 'https:\/\/cdn\/x\.js'/);
+});
+
+test('rewriteBareImports is a no-op when disabled', async () => {
+  const opt = createDevDepsOptimizer({ projectRoot, enabled: false });
+  const code = "import dayjs from 'dayjs';";
+  assert.equal(await opt.rewriteBareImports(code), code);
+});
+
+test('rewriteBareImports returns source unchanged when there is nothing bare', async () => {
+  const opt = createDevDepsOptimizer({ projectRoot, enabled: true });
+  const code = "import './a.js';\nexport const x = 1;\n";
+  assert.equal(await opt.rewriteBareImports(code), code);
+});
+
+test('specifierFromRequest extracts the package from the virtual path', () => {
+  const opt = createDevDepsOptimizer({ projectRoot, enabled: true });
+  assert.equal(opt.specifierFromRequest(`${MODULES_PREFIX}dayjs`), 'dayjs');
+  assert.equal(opt.specifierFromRequest(`${MODULES_PREFIX}@scope/pkg/sub`), '@scope/pkg/sub');
+  assert.equal(opt.specifierFromRequest('/Components/x.js'), null);
+});
+
+test('bundlePackage resolves a real ESM package to self-contained ESM', async () => {
+  const opt = createDevDepsOptimizer({ projectRoot, enabled: true });
+  // es-module-lexer is a named-export ESM package (no default) — exercises the
+  // namespace-only fallback path in bundlePackage.
+  const { code } = await opt.bundlePackage('es-module-lexer');
+  assert.ok(code.length > 0, 'expected bundled code');
+  // Self-contained: no bare imports left to resolve at runtime.
+  assert.doesNotMatch(code, /^\s*import\s+.*from\s+['"][^./]/m);
+  // Exposes the package's named API.
+  assert.match(code, /\bparse\b/);
+  assert.match(code, /export\s*\{/);
+});
+
+test('bundlePackage caches and shares a single build per specifier', async () => {
+  const opt = createDevDepsOptimizer({ projectRoot, enabled: true });
+  const [a, b] = await Promise.all([
+    opt.bundlePackage('es-module-lexer'),
+    opt.bundlePackage('es-module-lexer')
+  ]);
+  assert.equal(a, b, 'concurrent requests should share the same cached result');
+});
+
+test('bundlePackage persists a disk cache keyed by version, reused by a fresh optimizer', async () => {
+  const tmp = await fsp.mkdtemp(path.join(os.tmpdir(), 'slice-devcache-'));
+  try {
+    // Minimal installed package in the temp project's node_modules.
+    const pkgDir = path.join(tmp, 'node_modules', 'mini-pkg');
+    await fsp.mkdir(pkgDir, { recursive: true });
+    await fsp.writeFile(path.join(pkgDir, 'package.json'),
+      JSON.stringify({ name: 'mini-pkg', version: '2.3.4', type: 'module', main: 'index.js' }));
+    await fsp.writeFile(path.join(pkgDir, 'index.js'), 'export const hi = () => "hi";');
+
+    const opt1 = createDevDepsOptimizer({ projectRoot: tmp, enabled: true });
+    const first = await opt1.bundlePackage('mini-pkg');
+    assert.match(first.code, /hi/);
+
+    // A cache file keyed by the installed version must now exist.
+    const cacheFile = path.join(tmp, 'node_modules', '.slice-deps', 'mini-pkg@2.3.4.js');
+    const cached = await fsp.readFile(cacheFile, 'utf8');
+    assert.equal(cached, first.code);
+
+    // A brand-new optimizer (empty in-memory cache) reads the same bytes from disk.
+    const opt2 = createDevDepsOptimizer({ projectRoot: tmp, enabled: true });
+    const second = await opt2.bundlePackage('mini-pkg');
+    assert.equal(second.code, first.code);
+  } finally {
+    await fsp.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('bundlePackage prunes stale cache files when a package version changes', async () => {
+  const tmp = await fsp.mkdtemp(path.join(os.tmpdir(), 'slice-devcache-gc-'));
+  try {
+    const pkgDir = path.join(tmp, 'node_modules', 'mini-pkg');
+    const pkgJson = path.join(pkgDir, 'package.json');
+    const cacheDir = path.join(tmp, 'node_modules', '.slice-deps');
+    await fsp.mkdir(pkgDir, { recursive: true });
+    await fsp.writeFile(pkgJson, JSON.stringify({ name: 'mini-pkg', version: '1.0.0', type: 'module', main: 'index.js' }));
+    await fsp.writeFile(path.join(pkgDir, 'index.js'), 'export const v = 1;');
+
+    // A sibling package must survive the prune (its name is not a prefix match).
+    const otherDir = path.join(tmp, 'node_modules', 'mini-pkg-extra');
+    await fsp.mkdir(otherDir, { recursive: true });
+    await fsp.writeFile(path.join(otherDir, 'package.json'), JSON.stringify({ name: 'mini-pkg-extra', version: '9.0.0', type: 'module', main: 'index.js' }));
+    await fsp.writeFile(path.join(otherDir, 'index.js'), 'export const e = 1;');
+
+    await createDevDepsOptimizer({ projectRoot: tmp, enabled: true }).bundlePackage('mini-pkg');
+    await createDevDepsOptimizer({ projectRoot: tmp, enabled: true }).bundlePackage('mini-pkg-extra');
+    assert.ok(await fsp.stat(path.join(cacheDir, 'mini-pkg@1.0.0.js')).then(() => true));
+
+    // Simulate an upgrade: bump the installed version, then rebundle.
+    await fsp.writeFile(pkgJson, JSON.stringify({ name: 'mini-pkg', version: '1.1.0', type: 'module', main: 'index.js' }));
+    await fsp.writeFile(path.join(pkgDir, 'index.js'), 'export const v = 2;');
+    await createDevDepsOptimizer({ projectRoot: tmp, enabled: true }).bundlePackage('mini-pkg');
+
+    const remaining = (await fsp.readdir(cacheDir)).sort();
+    // Old version gone, new version present, sibling untouched.
+    assert.ok(!remaining.includes('mini-pkg@1.0.0.js'), 'stale version should be pruned');
+    assert.ok(remaining.includes('mini-pkg@1.1.0.js'), 'new version should be cached');
+    assert.ok(remaining.includes('mini-pkg-extra@9.0.0.js'), 'sibling package must not be pruned');
+  } finally {
+    await fsp.rm(tmp, { recursive: true, force: true });
+  }
+});

package/api/tests/dev-server-external.test.js

@@ -0,0 +1,56 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+// Boots the real dev server against a temp project and checks the two moving
+// parts of external-dependency support in development: bare-import rewriting of
+// served src modules, and on-demand esbuild bundling at /@slice-modules/.
+test('dev server rewrites bare imports and serves bundled packages', async () => {
+  process.env.NODE_ENV = 'development';
+  const frameworkRoot = new URL('../../', import.meta.url).pathname; // slice.js root
+  const tmp = await fsp.mkdtemp(path.join(os.tmpdir(), 'slice-dev-'));
+
+  try {
+    await fsp.mkdir(path.join(tmp, 'src', 'Components', 'Demo'), { recursive: true });
+    await fsp.writeFile(
+      path.join(tmp, 'src', 'sliceConfig.json'),
+      JSON.stringify({ externalDependencies: { enabled: true } })
+    );
+    await fsp.writeFile(
+      path.join(tmp, 'src', 'Components', 'Demo', 'Demo.js'),
+      "import { parse } from 'es-module-lexer';\nimport './local.js';\nexport default class Demo { run(){ return typeof parse; } }\n"
+    );
+    // Make es-module-lexer resolvable from the temp project for esbuild.
+    fs.symlinkSync(path.join(frameworkRoot, 'node_modules'), path.join(tmp, 'node_modules'), 'dir');
+
+    const { createSliceServer } = await import('../framework/server.js');
+    const { app } = createSliceServer({ projectRoot: tmp });
+    const server = app.listen(0);
+    await new Promise((resolve) => server.once('listening', resolve));
+    const base = `http://127.0.0.1:${server.address().port}`;
+
+    try {
+      // 1. The component's bare import is rewritten; the relative one is not.
+      const compRes = await fetch(`${base}/Components/Demo/Demo.js`);
+      const compText = await compRes.text();
+      assert.equal(compRes.status, 200);
+      assert.match(compText, /from ['"]\/@slice-modules\/es-module-lexer['"]/);
+      assert.match(compText, /import ['"]\.\/local\.js['"]/);
+
+      // 2. The virtual endpoint returns a self-contained ESM bundle of the pkg.
+      const modRes = await fetch(`${base}/@slice-modules/es-module-lexer`);
+      const modText = await modRes.text();
+      assert.equal(modRes.status, 200);
+      assert.match(modRes.headers.get('content-type') || '', /javascript/);
+      assert.match(modText, /export\s*\{/);
+      assert.doesNotMatch(modText, /^\s*import\s+.*from\s+['"][^./]/m);
+    } finally {
+      await new Promise((resolve) => server.close(resolve));
+    }
+  } finally {
+    await fsp.rm(tmp, { recursive: true, force: true });
+  }
+});

package/api/tests/precompressed-static.test.js

@@ -0,0 +1,119 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { createPrecompressedStatic } from '../framework/precompressedStatic.js';
+
+function fakeRes() {
+  return {
+    headers: {},
+    body: null,
+    sent: false,
+    setHeader(k, v) { this.headers[k.toLowerCase()] = v; },
+    send(body) { this.body = body; this.sent = true; return this; }
+  };
+}
+
+function run(mw, req) {
+  const res = fakeRes();
+  let nextCalled = false;
+  mw(req, res, () => { nextCalled = true; });
+  return { res, nextCalled };
+}
+
+async function withRoot(fn) {
+  const tmp = await fsp.mkdtemp(path.join(os.tmpdir(), 'slice-precomp-'));
+  try {
+    await fn(tmp);
+  } finally {
+    await fsp.rm(tmp, { recursive: true, force: true });
+  }
+}
+
+test('serves the .br variant when the client accepts brotli', async () => {
+  await withRoot(async (root) => {
+    await fsp.mkdir(path.join(root, 'bundles'), { recursive: true });
+    await fsp.writeFile(path.join(root, 'bundles', 'app.js'), 'ORIGINAL');
+    await fsp.writeFile(path.join(root, 'bundles', 'app.js.br'), 'BROTLI-BYTES');
+    await fsp.writeFile(path.join(root, 'bundles', 'app.js.gz'), 'GZIP-BYTES');
+
+    const mw = createPrecompressedStatic([root]);
+    const { res, nextCalled } = run(mw, {
+      method: 'GET', path: '/bundles/app.js', headers: { 'accept-encoding': 'gzip, br' }
+    });
+
+    assert.equal(nextCalled, false);
+    assert.equal(res.sent, true);
+    assert.equal(res.body.toString(), 'BROTLI-BYTES'); // brotli preferred over gzip
+    assert.equal(res.headers['content-encoding'], 'br');
+    assert.equal(res.headers['content-type'], 'application/javascript; charset=utf-8');
+    assert.equal(res.headers['vary'], 'Accept-Encoding');
+  });
+});
+
+test('falls back to gzip when brotli is not accepted', async () => {
+  await withRoot(async (root) => {
+    await fsp.writeFile(path.join(root, 'style.css'), 'ORIGINAL');
+    await fsp.writeFile(path.join(root, 'style.css.gz'), 'GZIP-BYTES');
+
+    const mw = createPrecompressedStatic([root]);
+    const { res } = run(mw, { method: 'GET', path: '/style.css', headers: { 'accept-encoding': 'gzip' } });
+    assert.equal(res.headers['content-encoding'], 'gzip');
+    assert.equal(res.headers['content-type'], 'text/css; charset=utf-8');
+    assert.equal(res.body.toString(), 'GZIP-BYTES');
+  });
+});
+
+test('passes through when the client accepts no encoding', async () => {
+  await withRoot(async (root) => {
+    await fsp.writeFile(path.join(root, 'app.js'), 'ORIGINAL');
+    await fsp.writeFile(path.join(root, 'app.js.br'), 'BROTLI-BYTES');
+    const mw = createPrecompressedStatic([root]);
+    const { res, nextCalled } = run(mw, { method: 'GET', path: '/app.js', headers: {} });
+    assert.equal(nextCalled, true);
+    assert.equal(res.sent, false);
+  });
+});
+
+test('passes through when no precompressed variant exists', async () => {
+  await withRoot(async (root) => {
+    await fsp.writeFile(path.join(root, 'app.js'), 'ORIGINAL'); // no .br/.gz
+    const mw = createPrecompressedStatic([root]);
+    const { res, nextCalled } = run(mw, { method: 'GET', path: '/app.js', headers: { 'accept-encoding': 'br' } });
+    assert.equal(nextCalled, true);
+    assert.equal(res.sent, false);
+  });
+});
+
+test('passes through for non-text extensions', async () => {
+  await withRoot(async (root) => {
+    await fsp.writeFile(path.join(root, 'img.png.br'), 'X');
+    const mw = createPrecompressedStatic([root]);
+    const { nextCalled } = run(mw, { method: 'GET', path: '/img.png', headers: { 'accept-encoding': 'br' } });
+    assert.equal(nextCalled, true);
+  });
+});
+
+test('honors root priority (public over dist root)', async () => {
+  await withRoot(async (root) => {
+    const pub = path.join(root, 'public');
+    await fsp.mkdir(pub, { recursive: true });
+    await fsp.writeFile(path.join(pub, 'theme.css.br'), 'PUBLIC');
+    await fsp.writeFile(path.join(root, 'theme.css.br'), 'ROOT');
+    const mw = createPrecompressedStatic([pub, root]);
+    const { res } = run(mw, { method: 'GET', path: '/theme.css', headers: { 'accept-encoding': 'br' } });
+    assert.equal(res.body.toString(), 'PUBLIC');
+  });
+});
+
+test('blocks path traversal', async () => {
+  await withRoot(async (root) => {
+    const mw = createPrecompressedStatic([path.join(root, 'public')]);
+    const { nextCalled, res } = run(mw, {
+      method: 'GET', path: '/../secret.js', headers: { 'accept-encoding': 'br' }
+    });
+    assert.equal(nextCalled, true);
+    assert.equal(res.sent, false);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slicejs-web-framework",
-  "version": "3.5.4",
+  "version": "4.0.0",
   "description": "",
   "engines": {
     "node": ">=20"
@@ -26,11 +26,14 @@
   "exports": {
     ".": "./Slice/Slice.js",
     "./api/framework/express.js": "./api/framework/express.js",
-    "./api/framework/server.js": "./api/framework/server.js"
+    "./api/framework/server.js": "./api/framework/server.js",
+    "./api/framework/devDepsOptimizer.js": "./api/framework/devDepsOptimizer.js"
   },
   "types": "./types/index.d.ts",
   "dependencies": {
     "compression": "^1.8.1",
+    "es-module-lexer": "^2.3.0",
+    "esbuild": "^0.28.1",
     "express": "^4.19.2"
   },
   "devDependencies": {

package/sliceConfig.schema.json

@@ -110,10 +110,6 @@
         "enabled": { "type": "boolean" }
       }
     },
-    "publicFolders": {
-      "type": "array",
-      "items": { "type": "string" }
-    },
     "server": {
       "type": "object",
       "additionalProperties": true,

package/src/sliceConfig.json

@@ -68,11 +68,5 @@
    },
   "loading": {
      "enabled": true
-  },
-  "publicFolders": [
-     "/Themes",
-     "/Styles",
-     "/assets",
-     "/images"
-  ]
+  }
 }