slicejs-web-framework 3.3.4 → 3.3.6

package/.opencode/opencode.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://app.kilo.ai/config.json",
   "mcp": {
     "thinking": {
       "type": "local",

package/Slice/Components/Structural/Controller/Controller.js

@@ -20,6 +20,11 @@ export default class Controller {
       this.bundleImportPromises = new Map();
       this.bundleLoadPromises = new Map();
 
+      // 🔁 Singleton builds in flight: sliceId → Promise<instance>.
+      // Lets concurrent build({singleton:true}) calls share one build instead
+      // of racing on a duplicate sliceId. Entries are transient (deleted on settle).
+      this._pendingBuilds = new Map();
+
       this.idCounter = 0;
    }
 
@@ -711,6 +716,11 @@ export default class Controller {
       // Registrar en activeComponents
       this.activeComponents.set(component.sliceId, component);
 
+      // Exponer sliceId como atributo HTML para búsqueda por DOM (destroyByContainer, etc.)
+      if (typeof component.setAttribute === 'function') {
+         component.setAttribute('slice-id', component.sliceId);
+      }
+
       // 🚀 OPTIMIZACIÓN: Actualizar índice inverso de hijos
       if (parent) {
          if (!this.childrenIndex.has(parent.sliceId)) {
@@ -731,8 +741,23 @@ export default class Controller {
       // Recursively assign parent to children
       component.querySelectorAll('*').forEach((child) => {
          if (child.tagName.startsWith('SLICE-')) {
+            // Only the call that establishes the DIRECT parent link feeds the
+            // index — the depth-first recursion sets a node's parent before an
+            // outer ancestor's forEach reaches it, so `component` here is the
+            // immediate enclosing component.
             if (!child.parentComponent) {
                child.parentComponent = component;
+               // 🔁 Maintain childrenIndex so destroyComponent(parent) cascades
+               // to children built via slice.build (which registers them WITHOUT
+               // a parent, leaving the index otherwise empty). Without this, a
+               // parent's destroy never finds — and never cleans up — its children.
+               if (child.sliceId && component.sliceId) {
+                  if (!this.childrenIndex.has(component.sliceId)) {
+                     this.childrenIndex.set(component.sliceId, new Set());
+                  }
+                  this.childrenIndex.get(component.sliceId).add(child.sliceId);
+                  child._depth = (component._depth || 0) + 1;
+               }
             }
             this.registerComponentsRecursively(child, component);
          }
@@ -748,6 +773,33 @@ export default class Controller {
       return this.activeComponents.get(sliceId);
    }
 
+   /**
+    * Get-or-create a single instance keyed by sliceId, deduplicating concurrent
+    * builds. Returns the existing instance if already registered, the in-flight
+    * promise if a build is underway, or otherwise memoizes a fresh build via
+    * `builder` (an injected closure — the controller never builds by itself).
+    *
+    * The in-flight promise is removed once it settles, so a failed build (which
+    * resolves to `null` and never registers in activeComponents) can be retried
+    * by a later call and never poisons the registry.
+    *
+    * @param {string} sliceId
+    * @param {() => Promise<any>} builder
+    * @returns {any|Promise<any>} instance (sync) or Promise<instance>
+    */
+   getOrCreate(sliceId, builder) {
+      const existing = this.activeComponents.get(sliceId);
+      if (existing) return existing;
+
+      const pending = this._pendingBuilds.get(sliceId);
+      if (pending) return pending;
+
+      const promise = Promise.resolve(builder())
+         .finally(() => this._pendingBuilds.delete(sliceId));
+      this._pendingBuilds.set(sliceId, promise);
+      return promise;
+   }
+
    loadTemplateToComponent(component) {
       const className = component.constructor.name;
       const template = this.templates.get(className);

package/Slice/Slice.js

@@ -90,11 +90,54 @@ export default class Slice {
 
    /**
     * Build a component instance and run init.
+    *
+    * Pass `{ singleton: true }` to get-or-create one shared instance keyed by
+    * `sliceId` (defaults to `componentName`). Concurrent singleton builds of the
+    * same id share a single in-flight build, so they never race on a duplicate
+    * sliceId. Singletons are only supported for Service components — for app-wide
+    * UI build a Provider Service that manages the Visual (see ToastProvider /
+    * ToolTipProvider), because a DOM node can only live in one place.
+    *
+    * Note: `props` only apply on the first (creating) call; later calls return
+    * the existing instance and ignore them.
+    *
     * @param {string} componentName
     * @param {Object} [props]
+    * @param {boolean} [props.singleton] Reuse a single instance per sliceId.
     * @returns {Promise<HTMLElement|Object|null>}
     */
    async build(componentName, props = {}) {
+      if (!props || props.singleton !== true) {
+         return this._build(componentName, props);
+      }
+
+      const { singleton, ...rest } = props;
+      const sliceId = rest.sliceId || componentName;
+
+      const category = this.controller.componentCategories.get(componentName);
+      if (category !== 'Service') {
+         this.logger.logError(
+            'Slice',
+            `singleton:true is only supported for Service components ('${componentName}' is ${category || 'unknown'}). ` +
+               `For app-wide UI build a Provider Service that manages the Visual (see ToastProvider/ToolTipProvider).`
+         );
+         return null;
+      }
+
+      return this.controller.getOrCreate(sliceId, () =>
+         this._build(componentName, { ...rest, sliceId })
+      );
+   }
+
+   /**
+    * Internal build: load resources, construct, run init, register. Always
+    * creates a new instance. Public `build` delegates here (and wraps it with
+    * get-or-create when `singleton:true`).
+    * @param {string} componentName
+    * @param {Object} [props]
+    * @returns {Promise<HTMLElement|Object|null>}
+    */
+   async _build(componentName, props = {}) {
       if (!componentName) {
          this.logger.logError('Slice', null, `Component name is required to build a component`);
          return null;
@@ -193,6 +236,10 @@ export default class Slice {
 
          delete props.id;
          delete props.sliceId;
+         // `singleton` is a build directive (handled in the public build()
+         // wrapper). Strip it here too so it is consistently reserved and never
+         // leaks into a component's props on the non-singleton path.
+         delete props.singleton;
 
        const ComponentClass = this.controller.classes.get(componentName);
        this.logger.logInfo(

package/Slice/tests/build-singleton.test.js

@@ -0,0 +1,221 @@
+// Real-runtime integration tests for build({ singleton: true }).
+//
+// These load the REAL Slice + REAL Controller (no FakeController): the only
+// fixture is the components map, injected via a resolve hook because Controller
+// imports a browser-absolute '/Components/components.js'. Singletons are
+// Service-only (no DOM), so the full build → getOrCreate → _build →
+// registerComponent path runs end-to-end under node, exercising the actual
+// shipped code.
+import { register } from 'node:module';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+globalThis.alert = () => {};
+register(new URL('./fixtures/real-runtime-loader.mjs', import.meta.url));
+
+const { default: Slice } = await import('../Slice.js');
+const { default: Controller } = await import('../Components/Structural/Controller/Controller.js');
+
+// A real Service-shaped class. The components fixture registers 'Probe' as a
+// Service and 'ModalProbe' as a Visual.
+let constructCount = 0;
+let failNext = false;
+
+class Probe {
+  constructor(props) {
+    constructCount += 1;
+    if (failNext) {
+      failNext = false;
+      throw new Error('boom'); // simulate a failed build on first attempt
+    }
+    this.props = props;
+  }
+  async init() {}
+}
+
+class FakeStylesManager {
+  registerComponentStyles() {}
+}
+
+function createSlice() {
+  const instance = new Slice(
+    {
+      paths: {
+        components: {
+          Service: { path: '/Components/Service', type: 'Service' },
+          Visual: { path: '/Components/Visual', type: 'Visual' }
+        }
+      },
+      themeManager: {},
+      stylesManager: {},
+      logger: {},
+      debugger: { enabled: false },
+      loading: {},
+      events: {}
+    },
+    { Controller, StylesManager: FakeStylesManager }
+  );
+
+  instance.logger = { logError() {}, logWarning() {}, logInfo() {} };
+  // Pre-seed the class so _build skips the network fetch (the real path for a
+  // class already cached by the controller). Everything else is real.
+  instance.controller.classes.set('Probe', Probe);
+  return instance;
+}
+
+function withSlice(fn) {
+  return async () => {
+    const original = globalThis.slice;
+    constructCount = 0;
+    failNext = false;
+    const slice = createSlice();
+    globalThis.slice = slice;
+    try {
+      await fn(slice);
+    } finally {
+      globalThis.slice = original;
+    }
+  };
+}
+
+test(
+  'singleton returns the same instance across awaited calls and builds once',
+  withSlice(async (slice) => {
+    const a = await slice.build('Probe', { singleton: true });
+    const b = await slice.build('Probe', { singleton: true });
+
+    assert.ok(a, 'first call returns an instance');
+    assert.equal(a, b, 'same instance reference');
+    assert.equal(constructCount, 1, 'constructed exactly once');
+    assert.equal(a.sliceId, 'Probe', 'sliceId defaults to component name');
+    assert.equal(slice.controller.activeComponents.get('Probe'), a, 'registered in activeComponents');
+  })
+);
+
+test(
+  'concurrent singleton builds share one in-flight build (race-safe)',
+  withSlice(async (slice) => {
+    const [a, b] = await Promise.all([
+      slice.build('Probe', { singleton: true }),
+      slice.build('Probe', { singleton: true })
+    ]);
+
+    assert.equal(a, b, 'both callers get the same instance');
+    assert.equal(constructCount, 1, 'deduped to a single construction');
+  })
+);
+
+test(
+  'named singletons via distinct sliceId are separate instances',
+  withSlice(async (slice) => {
+    const a = await slice.build('Probe', { singleton: true, sliceId: 'probeA' });
+    const b = await slice.build('Probe', { singleton: true, sliceId: 'probeB' });
+
+    assert.notEqual(a, b);
+    assert.equal(a.sliceId, 'probeA');
+    assert.equal(b.sliceId, 'probeB');
+    assert.equal(constructCount, 2);
+  })
+);
+
+test(
+  'a failed singleton build is not cached and the next call retries',
+  withSlice(async (slice) => {
+    failNext = true;
+    const first = await slice.build('Probe', { singleton: true });
+    assert.equal(first, null, 'failed build resolves to null');
+    assert.equal(
+      slice.controller._pendingBuilds.has('Probe'),
+      false,
+      'pending entry cleared after settle'
+    );
+    assert.equal(
+      slice.controller.activeComponents.has('Probe'),
+      false,
+      'failed build never registered'
+    );
+
+    const second = await slice.build('Probe', { singleton: true });
+    assert.ok(second, 'retry succeeds');
+    assert.equal(constructCount, 2, 'retried construction');
+  })
+);
+
+test(
+  'singleton:true is rejected for non-Service components',
+  withSlice(async (slice) => {
+    let errored = false;
+    slice.logger.logError = () => {
+      errored = true;
+    };
+
+    const result = await slice.build('ModalProbe', { singleton: true });
+
+    assert.equal(result, null, 'returns null for a Visual');
+    assert.equal(errored, true, 'logs an error');
+    assert.equal(constructCount, 0, 'never constructed');
+  })
+);
+
+test(
+  'default (non-singleton) build path is unchanged',
+  withSlice(async (slice) => {
+    const a = await slice.build('Probe');
+    const b = await slice.build('Probe');
+
+    assert.ok(a);
+    assert.ok(b);
+    assert.notEqual(a, b, 'each non-singleton build is a fresh instance');
+    assert.equal(constructCount, 2);
+  })
+);
+
+test(
+  'props only apply on the first (creating) call',
+  withSlice(async (slice) => {
+    const a = await slice.build('Probe', { singleton: true, tag: 'first' });
+    const b = await slice.build('Probe', { singleton: true, tag: 'second' });
+
+    assert.equal(a, b, 'same instance');
+    assert.equal(constructCount, 1, 'not rebuilt');
+    assert.equal(a.props.tag, 'first', 'later props are ignored');
+  })
+);
+
+test(
+  'the singleton/sliceId directives are not forwarded to the component props',
+  withSlice(async (slice) => {
+    const a = await slice.build('Probe', { singleton: true, sliceId: 'probeX', tag: 'keep' });
+
+    assert.equal(a.props.tag, 'keep', 'real props pass through');
+    assert.equal('singleton' in a.props, false, 'singleton flag stripped');
+    assert.equal('sliceId' in a.props, false, 'sliceId directive stripped');
+  })
+);
+
+test(
+  'singleton is stripped from props even on a non-singleton build',
+  withSlice(async (slice) => {
+    const a = await slice.build('Probe', { singleton: false, tag: 'keep' });
+
+    assert.ok(a);
+    assert.equal(a.props.tag, 'keep', 'real props pass through');
+    assert.equal('singleton' in a.props, false, 'singleton key never reaches the component');
+  })
+);
+
+test(
+  'singleton:true on an unregistered component is rejected (unknown category)',
+  withSlice(async (slice) => {
+    let errored = false;
+    slice.logger.logError = () => {
+      errored = true;
+    };
+
+    const result = await slice.build('NotRegistered', { singleton: true });
+
+    assert.equal(result, null, 'returns null');
+    assert.equal(errored, true, 'logs an error');
+    assert.equal(constructCount, 0, 'never constructed');
+  })
+);

package/Slice/tests/destroy-cascade.test.js

@@ -0,0 +1,215 @@
+// Real-Controller tests for destroyComponent cascading to children.
+//
+// Loads the REAL Controller (via the resolve hook that stubs its
+// '/Components/components.js' import) and drives it with a minimal fake DOM, so
+// the actual registerComponentsRecursively + destroyComponent code runs. This
+// reproduces the childrenIndex bug and verifies the fix: destroyComponent(parent)
+// must cascade to nested Visual children, running their beforeDestroy.
+import { register } from 'node:module';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+globalThis.alert = () => {};
+register(new URL('./fixtures/real-runtime-loader.mjs', import.meta.url));
+
+// The controller references the `slice` global for logging / events.
+globalThis.slice = {
+  logger: { logError() {}, logWarning() {}, logInfo() {} },
+  events: null
+};
+
+const { default: Controller } = await import('../Components/Structural/Controller/Controller.js');
+
+// --- minimal fake DOM ----------------------------------------------------
+// Each node is a SLICE-* element with querySelectorAll('*') returning all of
+// its descendants in document (pre) order — enough for registerComponentsRecursively.
+let destroyLog = [];
+
+function mkEl(sliceId, children = []) {
+  const node = {
+    sliceId,
+    tagName: 'SLICE-X',
+    isConnected: true,
+    parentComponent: null,
+    _children: children,
+    querySelectorAll() {
+      const out = [];
+      const walk = (n) => {
+        for (const c of n._children) {
+          out.push(c);
+          walk(c);
+        }
+      };
+      walk(node);
+      return out;
+    },
+    remove() {
+      this.isConnected = false;
+    },
+    beforeDestroy() {
+      destroyLog.push(this.sliceId);
+    }
+  };
+  return node;
+}
+
+// Collect every node in a tree (pre-order).
+function flatten(root) {
+  const out = [root];
+  for (const c of root._children) out.push(...flatten(c));
+  return out;
+}
+
+// Simulate slice.build's registration: registerComponent WITHOUT a parent for
+// every node, then registerComponentsRecursively on the root (what _build does
+// for a Visual once its subtree is in the DOM).
+function buildTree(controller, root) {
+  for (const node of flatten(root)) controller.registerComponent(node);
+  controller.registerComponentsRecursively(root);
+}
+
+function setup() {
+  destroyLog = [];
+  return new Controller();
+}
+
+test('destroyComponent(parent) cascades to a nested child', () => {
+  const c = setup();
+  const child = mkEl('child');
+  const parent = mkEl('parent', [child]);
+  buildTree(c, parent);
+
+  assert.equal(c.activeComponents.has('child'), true, 'child registered');
+
+  const count = c.destroyComponent(parent);
+
+  assert.equal(c.activeComponents.has('parent'), false, 'parent removed');
+  assert.equal(c.activeComponents.has('child'), false, 'child removed (cascaded)');
+  assert.ok(destroyLog.includes('child'), 'child beforeDestroy ran');
+  assert.equal(count, 2, 'reported 2 destroyed');
+});
+
+test('cascade reaches deep descendants, deepest beforeDestroy first', () => {
+  const c = setup();
+  const grandchild = mkEl('grandchild');
+  const child = mkEl('child', [grandchild]);
+  const parent = mkEl('parent', [child]);
+  buildTree(c, parent);
+
+  c.destroyComponent(parent);
+
+  assert.equal(c.activeComponents.size, 0, 'all three destroyed');
+  // deepest-first ordering (children before their parents)
+  assert.ok(
+    destroyLog.indexOf('grandchild') < destroyLog.indexOf('child'),
+    'grandchild before child'
+  );
+  assert.ok(destroyLog.indexOf('child') < destroyLog.indexOf('parent'), 'child before parent');
+});
+
+test('childrenIndex records DIRECT parents, not ancestors', () => {
+  const c = setup();
+  const grandchild = mkEl('grandchild');
+  const child = mkEl('child', [grandchild]);
+  const parent = mkEl('parent', [child]);
+  buildTree(c, parent);
+
+  assert.deepEqual([...(c.childrenIndex.get('parent') || [])], ['child'], 'parent -> child');
+  assert.deepEqual([...(c.childrenIndex.get('child') || [])], ['grandchild'], 'child -> grandchild');
+  assert.equal(child.parentComponent.sliceId, 'parent');
+  assert.equal(grandchild.parentComponent.sliceId, 'child', 'direct parent, not the root');
+});
+
+test('destroying a subtree leaves no stale childrenIndex entries', () => {
+  const c = setup();
+  const child = mkEl('child');
+  const parent = mkEl('parent', [child]);
+  buildTree(c, parent);
+
+  c.destroyComponent(parent);
+
+  assert.equal(c.childrenIndex.has('parent'), false, 'parent index entry cleared');
+  assert.equal(c.childrenIndex.has('child'), false, 'child index entry cleared');
+});
+
+test('a Service (no DOM element) is NOT cascaded — still needs explicit destroy', () => {
+  const c = setup();
+  const child = mkEl('child');
+  const parent = mkEl('parent', [child]);
+  buildTree(c, parent);
+  // A Service built by the parent: registered, but not part of any DOM subtree.
+  const service = { sliceId: 'svc', isConnected: false, beforeDestroy() { destroyLog.push('svc'); } };
+  c.registerComponent(service);
+
+  c.destroyComponent(parent);
+
+  assert.equal(c.activeComponents.has('svc'), true, 'service survives parent destroy');
+  assert.equal(destroyLog.includes('svc'), false, 'service beforeDestroy did NOT run');
+});
+
+test('all siblings under one parent cascade', () => {
+  const c = setup();
+  const a = mkEl('a');
+  const b = mkEl('b');
+  const parent = mkEl('parent', [a, b]);
+  buildTree(c, parent);
+
+  assert.deepEqual([...c.childrenIndex.get('parent')].sort(), ['a', 'b']);
+
+  c.destroyComponent(parent);
+  assert.equal(c.activeComponents.size, 0, 'parent and both siblings destroyed');
+});
+
+test('destroying a mid-level child destroys only its subtree', () => {
+  const c = setup();
+  const grandchild = mkEl('grandchild');
+  const child = mkEl('child', [grandchild]);
+  const parent = mkEl('parent', [child]);
+  buildTree(c, parent);
+
+  const count = c.destroyComponent(child);
+
+  assert.equal(count, 2, 'child + grandchild');
+  assert.equal(c.activeComponents.has('parent'), true, 'parent survives');
+  assert.equal(c.activeComponents.has('child'), false);
+  assert.equal(c.activeComponents.has('grandchild'), false);
+  assert.equal(
+    c.childrenIndex.has('parent') && c.childrenIndex.get('parent').has('child'),
+    false,
+    "parent's index no longer points to the destroyed child"
+  );
+});
+
+test('re-running registerComponentsRecursively is idempotent', () => {
+  const c = setup();
+  const child = mkEl('child');
+  const parent = mkEl('parent', [child]);
+  buildTree(c, parent);
+  c.registerComponentsRecursively(parent); // walk again
+
+  assert.deepEqual([...c.childrenIndex.get('parent')], ['child'], 'no duplicate edges');
+
+  c.destroyComponent(parent);
+  assert.equal(c.activeComponents.size, 0, 'still cascades cleanly');
+});
+
+test('destroyByContainer also collects the whole DOM subtree', () => {
+  const c = setup();
+  const grandchild = mkEl('grandchild');
+  const child = mkEl('child', [grandchild]);
+  const parent = mkEl('parent', [child]);
+  buildTree(c, parent);
+
+  // destroyByContainer queries [slice-id] on the container; emulate that query.
+  const container = {
+    querySelectorAll() {
+      return flatten(parent).map((n) => ({
+        getAttribute: () => n.sliceId,
+        sliceId: n.sliceId
+      }));
+    }
+  };
+
+  const count = c.destroyByContainer(container);
+  assert.equal(count, 3, 'all three destroyed via DOM discovery');
+});

package/Slice/tests/fixtures/real-runtime-loader.mjs

@@ -0,0 +1,19 @@
+// Node ESM resolve hook so the REAL Controller can load under `node --test`.
+//
+// Controller.js does `import components from '/Components/components.js'` — a
+// browser-absolute path that the dev server serves but node can't resolve. We
+// map only that exact specifier to a small fixture components map (just data,
+// the same shape the real components.js exports). Everything else resolves
+// normally, so the tests exercise the real Slice + Controller code, not mocks.
+const COMPONENTS = { Probe: 'Service', ModalProbe: 'Visual' };
+const STUB = `export default ${JSON.stringify(COMPONENTS)};`;
+
+export async function resolve(specifier, context, nextResolve) {
+   if (specifier === '/Components/components.js') {
+      return {
+         url: `data:text/javascript,${encodeURIComponent(STUB)}`,
+         shortCircuit: true
+      };
+   }
+   return nextResolve(specifier, context);
+}

package/package.json

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