slicejs-web-framework 4.0.0 → 4.0.2

package/Slice/Components/Structural/Router/Router.js

@@ -466,6 +466,11 @@ export default class Router {
       const componentName = route.parentRoute ? route.parentRoute.component : route.component;
       const sliceId = `route-${componentName}`;
 
+      if (!targetElement) {
+         slice.logger.logError('Router', `Cannot render route "${route?.path ?? componentName}": no #app element in the document`);
+         return;
+      }
+
       const existingComponent = slice.controller.getComponent(sliceId);
 
       if (slice.loading) {
@@ -487,6 +492,18 @@ export default class Router {
                sliceId: sliceId,
             });
 
+            // build() returns null whenever the component could not be produced
+            // (not registered, a resource fetch failed or was aborted, init()
+            // threw). Appending null raises "parameter 1 is not of type 'Node'",
+            // which buries the real cause. Report it and keep the current view.
+            if (!component) {
+               slice.logger.logError(
+                  'Router',
+                  `Cannot render route "${route?.path ?? componentName}": slice.build('${componentName}') returned null`
+               );
+               return;
+            }
+
             targetElement.innerHTML = '';
             targetElement.appendChild(component);
 

package/Slice/Components/Structural/StylesManager/ThemeManager/ThemeManager.js

@@ -50,8 +50,21 @@ export default class ThemeManager {
     * @returns {Promise<void>}
     */
    async loadThemeCSS(themeName) {
-      let themeContent =
-         localStorage.getItem(`sliceTheme-${themeName}`) || (await slice.controller.fetchText(themeName, 'theme'));
+      let themeContent = localStorage.getItem(`sliceTheme-${themeName}`);
+
+      if (!themeContent) {
+         try {
+            themeContent = await slice.controller.fetchText(themeName, 'theme');
+         } catch (error) {
+            // A theme that fails to fetch must not abort framework init.
+            // applyTheme() is awaited from StylesManager.init(), which runs
+            // inside Slice.js init() — letting this throw leaves the runtime
+            // half-built (no slice.router). An unstyled app is recoverable;
+            // no app at all is not. fetchText already logged the cause.
+            slice.logger.logError('ThemeManager', `Failed to load theme: ${themeName}`, error);
+            return;
+         }
+      }
 
       if (!themeContent) {
          slice.logger.logError('ThemeManager', `Failed to load theme: ${themeName}`);

package/Slice/Slice.js

@@ -311,40 +311,27 @@ export default class Slice {
          if (componentIds.id && isVisual) componentInstance.id = componentIds.id;
          if (componentIds.sliceId) componentInstance.sliceId = componentIds.sliceId;
 
-         if (!this.controller.verifyComponentIds(componentInstance)) {
-            this.logger.logError('Slice', `Error registering instance ${componentName} ${componentInstance.sliceId}`);
-            return null;
-         }
-
-         // Dev guard: update() called during init() runs BEFORE the component is
-         // registered, so the framework's update() wrapper (serialization +
-         // liveness) isn't installed yet and the call misbehaves silently. Warn
-         // instead. Restored right after init() so registerComponent →
-         // installUpdate wraps the real method, not this guard.
-         let _rawUpdate = null;
-         if (typeof componentInstance.update === 'function') {
-            _rawUpdate = componentInstance.update;
-            componentInstance.update = function (...args) {
-               slice.logger.logWarning(
-                  componentInstance.constructor?.name || 'Component',
-                  'update() was called during init() (before registration). Run your render logic directly from init(); the update() wrapper (serialization + liveness) is not active until the component is registered.'
-               );
-               return _rawUpdate.apply(this, args);
-            };
-         }
+          if (!this.controller.verifyComponentIds(componentInstance)) {
+             this.logger.logError('Slice', `Error registering instance ${componentName} ${componentInstance.sliceId}`);
+             return null;
+          }
 
-         if (componentInstance.init) await componentInstance.init();
+          // Register before init so the component is visible in activeComponents
+          // during init(). This lets slice.router.navigate() work from inside
+          // init() without the Router creating a duplicate instance (the Router
+          // finds the existing component via getComponent). Calling update()
+          // from init() is safe because installUpdate already wrapped it.
+          this.controller.registerComponent(componentInstance);
 
-         if (_rawUpdate) componentInstance.update = _rawUpdate;
+          if (componentInstance.init) await componentInstance.init();
 
-         if (slice.debuggerConfig.enabled && isVisual) {
-            this.debugger.attachDebugMode(componentInstance);
-         }
+          if (slice.debuggerConfig.enabled && isVisual) {
+             this.debugger.attachDebugMode(componentInstance);
+          }
 
-         this.controller.registerComponent(componentInstance);
-         if (isVisual) {
-            this.controller.registerComponentsRecursively(componentInstance);
-         }
+          if (isVisual) {
+             this.controller.registerComponentsRecursively(componentInstance);
+          }
 
          this.logger.logInfo('Slice', `Instance ${componentInstance.sliceId} created`);
          return componentInstance;
@@ -457,77 +444,19 @@ async function init() {
         }
      }
 
-    // 5. Create Slice instance and set resolved mode
-    window.slice = new Slice(sliceConfig, frameworkClasses);
-    window.slice._mode = resolvedMode;
-    window.slice.setPublicEnv(envResult?.env || {});
-
-     const createBundlingInitError = (step, error) => {
-        const detail = error instanceof Error ? error.message : String(error);
-        return new Error(`Bundling V2 initialization failed (${step}): ${detail}`, { cause: error });
-     };
-
-     // Initialize bundles before building components.
-     // Only in production — dev mode loads each component individually from source.
-     // bundleConfigJson was already fetched above (step 2); reuse it.
-     if (resolvedMode === 'production' && bundleConfigJson) {
-        window.slice.controller.bundleConfig = bundleConfigJson;
-     }
-
-     if (resolvedMode === 'production' && window.slice.controller.bundleConfig) {
-        const config = window.slice.controller.bundleConfig;
-        if (!window.__SLICE_SHARED_DEPS__ || typeof window.__SLICE_SHARED_DEPS__ !== 'object') {
-           window.__SLICE_SHARED_DEPS__ = {};
-        }
-        const criticalFile = config?.bundles?.critical?.file;
-        if (criticalFile) {
-           try {
-              await window.slice.controller.loadBundle('critical');
-           } catch (error) {
-              throw createBundlingInitError(`critical bundle "${criticalFile}"`, error);
-           }
-        }
-
-        const routeBundles = config?.routeBundles || {};
-        const initialPath = window.location.pathname || '/';
-        const bundlesForRoute = routeBundles[initialPath] || [];
-
-        const loadRouteBundles = async () => {
-           for (const bundleName of bundlesForRoute) {
-              if (bundleName === 'critical') continue;
-              const bundleInfo = config?.bundles?.routes?.[bundleName];
-              if (!bundleInfo?.file) continue;
-              await window.slice.controller.loadBundle(bundleName);
-           }
-        };
-
-        const preloadRouteBundles = () => {
-           loadRouteBundles().catch((error) => {
-              window.slice?.logger?.error('Slice', `Idle route preload failed for "${initialPath}"`, error);
-           });
-        };
-
-        const safePreload = () => {
-           try {
-              preloadRouteBundles();
-           } catch (error) {
-              window.slice?.logger?.error('Slice', 'Error in route preload callback', error);
-           }
-        };
-
-        if (typeof requestIdleCallback === 'function') {
-           requestIdleCallback(() => safePreload());
-        } else {
-           setTimeout(() => safePreload(), 0);
-        }
-     }
+     // 5. Create Slice instance and set resolved mode
+     window.slice = new Slice(sliceConfig, frameworkClasses);
+     window.slice._mode = resolvedMode;
+     window.slice.setPublicEnv(envResult?.env || {});
 
    slice.paths.structuralComponentFolderPath = '/Slice/Components/Structural';
 
-    if (sliceConfig.logger.enabled) {
-       const LoggerModule = window.slice.frameworkClasses?.Logger
-         || await window.slice.getClass(`${slice.paths.structuralComponentFolderPath}/Logger/Logger.js`);
-       window.slice.logger = new LoggerModule();
+   // Logger must be available before bundle loading — Controller internally calls
+   // slice.logger.* methods during loadBundle/registerBundle.
+   if (sliceConfig.logger.enabled) {
+      const LoggerModule = window.slice.frameworkClasses?.Logger
+        || await window.slice.getClass(`${slice.paths.structuralComponentFolderPath}/Logger/Logger.js`);
+      window.slice.logger = new LoggerModule();
    } else {
       const noop = () => {};
       window.slice.logger = {
@@ -536,6 +465,66 @@ async function init() {
       };
    }
 
+      const createBundlingInitError = (step, error) => {
+         const detail = error instanceof Error ? error.message : String(error);
+         return new Error(`Bundling V2 initialization failed (${step}): ${detail}`, { cause: error });
+      };
+
+      // Initialize bundles before building components.
+      // Only in production — dev mode loads each component individually from source.
+      // bundleConfigJson was already fetched above (step 2); reuse it.
+      if (resolvedMode === 'production' && bundleConfigJson) {
+         window.slice.controller.bundleConfig = bundleConfigJson;
+      }
+
+      if (resolvedMode === 'production' && window.slice.controller.bundleConfig) {
+         const config = window.slice.controller.bundleConfig;
+         if (!window.__SLICE_SHARED_DEPS__ || typeof window.__SLICE_SHARED_DEPS__ !== 'object') {
+            window.__SLICE_SHARED_DEPS__ = {};
+         }
+         const criticalFile = config?.bundles?.critical?.file;
+         if (criticalFile) {
+            try {
+               await window.slice.controller.loadBundle('critical');
+            } catch (error) {
+               throw createBundlingInitError(`critical bundle "${criticalFile}"`, error);
+            }
+         }
+
+         const routeBundles = config?.routeBundles || {};
+         const initialPath = window.location.pathname || '/';
+         const bundlesForRoute = routeBundles[initialPath] || [];
+
+         const loadRouteBundles = async () => {
+            for (const bundleName of bundlesForRoute) {
+               if (bundleName === 'critical') continue;
+               const bundleInfo = config?.bundles?.routes?.[bundleName];
+               if (!bundleInfo?.file) continue;
+               await window.slice.controller.loadBundle(bundleName);
+            }
+         };
+
+         const preloadRouteBundles = () => {
+            loadRouteBundles().catch((error) => {
+               window.slice?.logger?.error('Slice', `Idle route preload failed for "${initialPath}"`, error);
+            });
+         };
+
+         const safePreload = () => {
+            try {
+               preloadRouteBundles();
+            } catch (error) {
+               window.slice?.logger?.error('Slice', 'Error in route preload callback', error);
+            }
+         };
+
+         if (typeof requestIdleCallback === 'function') {
+            requestIdleCallback(() => safePreload());
+         } else {
+            setTimeout(() => safePreload(), 0);
+         }
+      }
+
     if (sliceConfig.debugger.enabled) {
         const DebuggerModule = window.slice.frameworkClasses?.Debugger
            || await window.slice.getClass(`${slice.paths.structuralComponentFolderPath}/Debugger/Debugger.js`);
@@ -691,8 +680,31 @@ async function init() {
    await window.slice.router.init();
 }
 
- try {
-   await init();
-} catch (initError) {
-   console.error('[Slice.js] Initialization failed:', initError);
- }
+// Booting requires a DOM. Under node — where this module is imported for the
+// Slice class alone (see Slice/tests) — there is nothing to initialize, so skip
+// it rather than starting an init() that can only fail.
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+   // Exposed so callers that cannot rely on module import order — test
+   // harnesses, embedders, anything loaded via a plain <script> — have a real
+   // readiness signal. It settles exactly when init() does. Note that
+   // `window.slice` and `slice.build` exist well before init() finishes, so
+   // checking for those is NOT a readiness test; await this (or check
+   // `slice.router`) instead.
+   window.__SLICE_READY__ = init();
+
+   try {
+      await window.__SLICE_READY__;
+      if (window.slice) window.slice.initError = null;
+   } catch (initError) {
+      // Deliberately not swallowed. A half-initialized runtime (no
+      // slice.router, no registered components) makes every downstream call
+      // fail with its own unrelated-looking TypeError — "Cannot read
+      // properties of undefined (reading 'afterEach')", "appendChild:
+      // parameter 1 is not of type 'Node'" — each of which hides this, the
+      // actual cause. Record it, then rethrow so that importing this module
+      // fails loudly and on the real error.
+      if (window.slice) window.slice.initError = initError;
+      console.error('[Slice.js] Initialization failed:', initError);
+      throw initError;
+   }
+}

package/Slice/tests/bundle-v2-runtime-contract.test.js

@@ -707,7 +707,16 @@ test('Slice init fails fast with contextual error on invalid Bundling V2 contrac
 
       const sliceModuleUrl = new URL(`../Slice.js?fail-fast-test=${Date.now()}`, import.meta.url).href;
 
-      await import(sliceModuleUrl);
+      // Failing fast means the failure propagates: a rejected import stops
+      // consumers from running against a runtime that has no router and no
+      // registered components. Previously init() logged and resolved anyway,
+      // so the first symptom a developer saw was an unrelated TypeError
+      // further downstream rather than this contextual error.
+      await assert.rejects(
+         () => import(sliceModuleUrl),
+         /Bundling V2 initialization failed/,
+         'a failed init must reject the module import, not resolve a half-built runtime'
+      );
 
       assert.ok(
          loggedMessages.some((message) => /Bundling V2 initialization failed/i.test(message)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slicejs-web-framework",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "",
   "engines": {
     "node": ">=20"

package/tests/router-build-failure.test.js

@@ -0,0 +1,125 @@
+// Regression test: handleRoute() must not append a failed build to the DOM.
+//
+// slice.build() returns null on any unrecoverable path (component not
+// registered, a resource fetch failed or was aborted mid-flight, init() threw).
+// Passing that null straight to appendChild() raised
+//   TypeError: Failed to execute 'appendChild' on 'Node': parameter 1 is not of type 'Node'
+// which surfaced far from the real cause and made the failure look like a DOM
+// bug. handleRoute() now reports the build failure and leaves the current view
+// in place.
+//
+// Router has no imports and no module-level DOM access, so its prototype can be
+// exercised directly against stubs (same approach as router-emit-ordering).
+//
+// Run: node --test tests/router-build-failure.test.js
+
+import { test, describe, before, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+
+describe('Router.handleRoute — failed component build', () => {
+  let Router;
+  let appended;
+  let loggedErrors;
+  let appElement;
+
+  before(async () => {
+    globalThis.window = globalThis.window || { location: { pathname: '/' } };
+    globalThis.slice = globalThis.slice || {};
+    ({ default: Router } = await import('../Slice/Components/Structural/Router/Router.js'));
+  });
+
+  beforeEach(() => {
+    appended = [];
+    loggedErrors = [];
+    appElement = {
+      innerHTML: 'previous view',
+      appendChild(node) {
+        // Mirror the real DOM contract: appending a non-Node is a TypeError.
+        if (!node || typeof node !== 'object') {
+          throw new TypeError(
+            "Failed to execute 'appendChild' on 'Node': parameter 1 is not of type 'Node'."
+          );
+        }
+        appended.push(node);
+      },
+    };
+
+    globalThis.document = { querySelector: (sel) => (sel === '#app' ? appElement : null) };
+    globalThis.slice = {
+      logger: { logError: (...args) => loggedErrors.push(args) },
+      controller: { getComponent: () => null },
+      router: {},
+      loading: null,
+      build: async () => null, // the failure under test
+    };
+  });
+
+  const makeRouter = () => {
+    const r = Object.create(Router.prototype);
+    r.renderRoutesInComponent = async () => {};
+    r.invalidateCache = () => {};
+    return r;
+  };
+
+  test('does not throw when slice.build() returns null', async () => {
+    const r = makeRouter();
+    await r.handleRoute({ path: '/broken', component: 'Broken' }, {});
+    assert.equal(appended.length, 0, 'nothing should be appended');
+  });
+
+  test('logs the build failure naming the route and component', async () => {
+    const r = makeRouter();
+    await r.handleRoute({ path: '/broken', component: 'Broken' }, {});
+
+    assert.equal(loggedErrors.length, 1, 'exactly one error should be reported');
+    const [scope, message] = loggedErrors[0];
+    assert.equal(scope, 'Router');
+    assert.match(message, /\/broken/);
+    assert.match(message, /Broken/);
+  });
+
+  test('leaves the current view untouched instead of blanking it', async () => {
+    const r = makeRouter();
+    await r.handleRoute({ path: '/broken', component: 'Broken' }, {});
+    assert.equal(appElement.innerHTML, 'previous view');
+  });
+
+  test('does not mark the failed route as active', async () => {
+    const r = makeRouter();
+    await r.handleRoute({ path: '/broken', component: 'Broken' }, {});
+    assert.equal(slice.router.activeRoute, undefined);
+  });
+
+  test('still stops the loading indicator', async () => {
+    const stops = [];
+    slice.loading = { start() {}, stop() { stops.push(1); } };
+
+    const r = makeRouter();
+    await r.handleRoute({ path: '/broken', component: 'Broken' }, {});
+    assert.equal(stops.length, 1, 'loading.stop() must run even on the failure path');
+  });
+
+  test('a successful build still renders and activates the route', async () => {
+    const component = { tagName: 'DIV' };
+    slice.build = async () => component;
+
+    const r = makeRouter();
+    const route = { path: '/ok', component: 'Ok' };
+    await r.handleRoute(route, {});
+
+    assert.deepEqual(appended, [component]);
+    assert.equal(appElement.innerHTML, '');
+    assert.equal(slice.router.activeRoute, route);
+    assert.equal(loggedErrors.length, 0);
+  });
+
+  test('reports instead of throwing when #app is missing', async () => {
+    globalThis.document = { querySelector: () => null };
+
+    const r = makeRouter();
+    await r.handleRoute({ path: '/ok', component: 'Ok' }, {});
+
+    assert.equal(loggedErrors.length, 1);
+    assert.match(loggedErrors[0][1], /#app/);
+  });
+});