@peter.naydenov/cuts 2.1.3 → 2.1.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@peter.naydenov/cuts",
   "description": "SPA scene manager",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "license": "MIT",
   "author": "Peter Naydenov",
   "main": "./src/main.js",

package/src/methods/hide.js

@@ -12,50 +12,51 @@ function hide ( dependencies, state ) {
 return function hide ( endSteps=1 ) {
     const
           { askForPromise, shortcutMngr, setInstruction } = dependencies
-        , { currentScene, currentParents, scenes } = state
+        , { currentScene, scenes } = state
         , hideTask = askForPromise ()
-        , instructions = []
-        , hasParents = currentParents.length > 0
+        , unloadTask = askForPromise ()
+        , hasBeforeHide = typeof scenes[currentScene].beforeHide === 'function'
         ;
 
-    shortcutMngr.pause ()   // Stop all shortcuts
-    instructions.push ( setInstruction ( scenes[currentScene].hide ))   // Set instruction to hide current scene
+    if ( hasBeforeHide ) { // Execute 'beforeHide' function if exists - same guard 'show' honors when navigating away
+                const closingFn = scenes[currentScene].beforeHide;
+                closingFn ({ done:unloadTask.done, dependencies: shortcutMngr.getDependencies() })
+        }
+    else  unloadTask.done ( true )
 
-    if ( !hasParents )    state.currentScene = null
+    unloadTask.onComplete ( continueHiding => {
+                    if ( !continueHiding ) {
+                                // 'beforeHide' returned false - cancel, nothing was torn down or changed
+                                hideTask.done ()
+                                return hideTask.promise
+                        }
 
-    let namesToHide = []
-    if ( hasParents && endSteps === '*' ) {
-                namesToHide = [...currentParents].reverse ()
-        }
-    if ( hasParents && ![ '*', 1].includes(endSteps) ) {
-                namesToHide = currentParents.slice ( `-${endSteps-1}` ).reverse ()
-        }
+                    const
+                          instructions = []
+                        // Work on a copy of the recorded ancestor chain - it's the source of truth for what to
+                        // climb back to, including for wildcard-overlay scenes ('*' itself is never stored here,
+                        // only the real scene name that was current when the overlay was shown).
+                        , remaining = [ ...state.currentParents ]
+                        ;
 
-    if ( hasParents && namesToHide.length === 0 && scenes[currentScene].parents[0] === '*' ) {
-                // A wildcard overlay has no fixed scene to 'stay pointed at' once hidden - unlike a
-                // regular single-step hide(), always climb back to whatever scene it was shown on top
-                // of, so the shortcuts context returns to the (still visible) underlying scene.
-                state.currentScene   = state.currentParents.pop ()
-                state.currentParents = state.currentScene ? [ ...scenes[state.currentScene].parents ] : []
-        }
+                    shortcutMngr.pause ()   // Stop all shortcuts
+                    instructions.push ( setInstruction ( scenes[currentScene].hide ))   // Hiding the current scene is always at least 1 step
+
+                    const ancestorsToHide = ( endSteps === '*' ) ? remaining.length : Math.min ( endSteps - 1, remaining.length )
+                    for ( let i = 0; i < ancestorsToHide; i++ ) {
+                                const name = remaining.pop ()
+                                instructions.push ( setInstruction ( scenes[name].hide ))
+                        }
 
-    namesToHide.forEach ( name => {
-                instructions.push ( setInstruction ( scenes[name].hide))
-                // Climb to the parent of the scene just hidden - same technique 'show' uses for its 'hide' steps.
-                // A wildcard overlay isn't climbing its own declared parent ('*' isn't a real scene) - and
-                // there's no reliable way to recover what it originally covered once it's this deep in the
-                // chain, so fall back to treating it as the end of the chain rather than crashing.
-                state.currentScene   = ( scenes[name].parents[0] === '*' )
-                                            ? null
-                                            : ( scenes[name].parents.at ( -1 ) ?? null )
-                state.currentParents = state.currentScene ? scenes[state.currentScene].parents : []
-        })
+                    state.currentScene   = remaining.length > 0 ? remaining.pop () : null
+                    state.currentParents = remaining
 
-    const goingTask = askForPromise.sequence ( instructions );
-    goingTask.onComplete ( () => {
-                    shortcutMngr.changeContext ( state.currentScene )   // If state.currentScene is null, then all shortcuts are switched off and currentContext is null
-                    hideTask.done ()
-            })
+                    const goingTask = askForPromise.sequence ( instructions );
+                    goingTask.onComplete ( () => {
+                                    shortcutMngr.changeContext ( state.currentScene )   // If state.currentScene is null, then all shortcuts are switched off and currentContext is null
+                                    hideTask.done ()
+                            })
+        }) // unloadTask onComplete
     return hideTask.promise
 }} // hide func.
 
@@ -63,4 +64,3 @@ return function hide ( endSteps=1 ) {
 
 export default hide
 
-

package/src/methods/jump.js

@@ -8,8 +8,13 @@ function jump ( state, show ) {
      * @returns {Promise} - promise that resolves when the jump is completed
      */
     function jump ( { scene }, ...args ) {
-            state.jumpStack.push ( state.currentScene )
-            return show ( { scene }, ...args )
+            const previousScene = state.currentScene
+            return show ( { scene }, ...args ).then ( () => {
+                        // Only record the jump if it actually landed - 'show' silently no-ops on a
+                        // blocked (beforeHide) or invalid navigation, and pushing anyway would leave
+                        // a phantom entry that desyncs jumpBack() from what actually happened.
+                        if ( state.currentScene === scene )   state.jumpStack.push ( previousScene )
+                })
         }
     return jump
 } // jump func.

package/src/methods/setScenes.js

@@ -8,7 +8,7 @@
 /**
  * @typedef {Object} SceneObject
  * @property {function({task: AskObject, dependencies: *}): void} show - load interface and prerequisites for the scene;
- * @property {function():boolean} [afterShow] - run after scene is loaded. Optional. Returns true to continue loading, false to cancel;
+ * @property {function({dependencies: *, done: function}):void} [afterShow] - run after the scene is shown. Optional. Fire-and-forget - its return value is not used, and it cannot cancel or affect the already-completed 'show';
  * @property {function({task: AskObject, dependencies: *}): void} hide - Reverse the settings from 'show';
  * @property {function():void} [beforeHide] - Run before scene is hidden. Optional;
  * @property {Array.<string>} [parents] - list of parent scene names.

package/src/methods/show.js

@@ -53,6 +53,9 @@ function show ( dependencies, state ) {
                                 // Executes only once when the scene manager is started
                                 state.opened = true
                                 state.currentScene = requestedScene
+                                // The server-rendered scene's ancestors are assumed already rendered too -
+                                // record them, or navigating away later won't know to hide them.
+                                state.currentParents = scenes[requestedScene].parents ? [ ...scenes[requestedScene].parents ] : []
                                 shortcutMngr.changeContext ( requestedScene )
                                 showTask.done ()
                                 return showTask.promise
@@ -65,7 +68,11 @@ function show ( dependencies, state ) {
                      if ( parents[0] === '*' ) {
                                  const overlayTask = setInstruction(show, ...args)()
                                  overlayTask.then ( () => showTask.done ()   )
-                                 state.currentParents.push ( state.currentScene )
+                                 // Only remember a real underlying scene - pushing 'null' as a placeholder
+                                 // makes later navigation treat it as a scene name to hide, and crash.
+                                 // Re-showing the SAME overlay that's already current must not push it onto
+                                 // its own ancestor chain either, or hide() later climbs back onto itself.
+                                 if ( state.currentScene && state.currentScene !== requestedScene )   state.currentParents.push ( state.currentScene )
                                  state.currentScene = requestedScene
                                  shortcutMngr.changeContext ( requestedScene )   // Activate the overlay scene's own shortcuts
                                  return showTask.promise
@@ -101,7 +108,10 @@ function show ( dependencies, state ) {
                         } // getStep func.
 
                     const
-                          g = findInstructions ( state.currentScene, state.currentParents, requestedScene, parents )
+                          // Snapshot - findInstructions is a lazy generator, and getStep (in the loop below)
+                          // mutates state.currentParents in place; without a copy, that mutation corrupts
+                          // the generator's still-pending reads of the very array it was given.
+                          g = findInstructions ( state.currentScene, [ ...state.currentParents ], requestedScene, parents )
                         , instructions = []
                         ;
 

package/test/02-cuts.test.js

@@ -455,7 +455,7 @@ describe ( 'Cuts integration', () => {
                      await script.show ({ scene: 'overlay' });
                      expect ( calls ).toEqual (['show overlay']);
                      expect ( script.getState().scene ).toEqual ( 'overlay' );
-                     expect ( script.getState().parents ).toEqual ( [null] ); // No previous scene, saved as null
+                     expect ( script.getState().parents ).toEqual ( [] ); // No underlying scene to remember
          }) // it Show scene with wildcard parent as the very first scene
 
 
@@ -658,4 +658,273 @@ describe ( 'Cuts integration', () => {
 
 
 
+     it ( 'hide() with the default single step climbs to the parent and restores its shortcuts context', async () => {
+                     // Regression test: hide() used to leave currentScene/currentParents pointing at
+                     // the just-hidden scene instead of climbing to its (still visible) parent, so
+                     // NEITHER scene's shortcuts context was active afterward.
+                     const seen = [];
+                     const script = cuts();
+                     const scenes = [
+                                     {
+                                           name: 'A'
+                                         , scene: {
+                                                     show : ({task}) => task.done(),
+                                                     hide : ({task}) => task.done(),
+                                                     '@ping' : () => seen.push ( 'A' )
+                                             }
+                                         },
+                                         {
+                                           name: 'B'
+                                         , scene: {
+                                                     show : ({task}) => task.done(),
+                                                     hide : ({task}) => task.done(),
+                                                     parents: ['A'],
+                                                     '@ping' : () => seen.push ( 'B' )
+                                             }
+                                         }
+                                 ];
+
+                     script.setScenes ( scenes );
+                     await script.show ({ scene: 'A' });
+                     await script.show ({ scene: 'B' });
+
+                     await script.hide (); // default endSteps = 1
+                     expect ( script.getState() ).toEqual ({ scene: 'A', parents: [], opened: true });
+
+                     script.emit ( '@ping' );
+                     expect ( seen ).toEqual ([ 'A' ]);
+         }) // it hide() with the default single step climbs to the parent and restores its shortcuts context
+
+
+
+     it ( 'hide(n) climbs exactly n levels', async () => {
+                     const calls = [];
+                     const script = cuts();
+                     const scenes = [
+                                     { name: 'top' , scene: { show: ({task}) => { calls.push('show top');  task.done() }, hide: ({task}) => { calls.push('hide top');  task.done() } } },
+                                     { name: 'mid' , scene: { show: ({task}) => { calls.push('show mid');  task.done() }, hide: ({task}) => { calls.push('hide mid');  task.done() }, parents: ['top'] } },
+                                     { name: 'deep', scene: { show: ({task}) => { calls.push('show deep'); task.done() }, hide: ({task}) => { calls.push('hide deep'); task.done() }, parents: ['top', 'mid'] } }
+                                 ];
+
+                     script.setScenes ( scenes );
+                     await script.show ({ scene: 'deep' });
+                     calls.length = 0;
+
+                     await script.hide ( 2 );
+                     expect ( calls ).toEqual ([ 'hide deep', 'hide mid' ]);
+                     expect ( script.getState() ).toEqual ({ scene: 'top', parents: [], opened: true });
+         }) // it hide(n) climbs exactly n levels
+
+
+
+     it ( 'SSR first load records the scene\'s parents, so leaving it hides them too', async () => {
+                     // Regression test: the SSR branch of show() set currentScene but never
+                     // currentParents, so navigating away from a deep SSR-loaded scene skipped
+                     // hiding its ancestors entirely, leaving them stale in the DOM.
+                     const calls = [];
+                     const script = cuts();
+                     const scenes = [
+                                     { name: 'top' , scene: { show: ({task}) => { calls.push('show top');  task.done() }, hide: ({task}) => { calls.push('hide top');  task.done() } } },
+                                     { name: 'mid' , scene: { show: ({task}) => { calls.push('show mid');  task.done() }, hide: ({task}) => { calls.push('hide mid');  task.done() }, parents: ['top'] } },
+                                     { name: 'deep', scene: { show: ({task}) => { calls.push('show deep'); task.done() }, hide: ({task}) => { calls.push('hide deep'); task.done() }, parents: ['top', 'mid'] } },
+                                     { name: 'other', scene: { show: ({task}) => { calls.push('show other'); task.done() }, hide: ({task}) => { calls.push('hide other'); task.done() } } }
+                                 ];
+
+                     script.setScenes ( scenes );
+                     await script.show ({ scene: 'deep', options: { ssr: true } });
+                     expect ( script.getState() ).toEqual ({ scene: 'deep', parents: [ 'top', 'mid' ], opened: true });
+
+                     calls.length = 0;
+                     await script.show ({ scene: 'other' });
+                     expect ( calls ).toEqual ([ 'hide deep', 'hide mid', 'hide top', 'show other' ]);
+         }) // it SSR first load records the scene's parents, so leaving it hides them too
+
+
+
+     it ( 'afterShow return value has no effect on the completed show()', async () => {
+                     // Regression test: setScenes.js's typedef documented afterShow as
+                     // 'returns false to cancel', but show() never read its return value, so
+                     // the scene was always shown regardless. The typedef is now corrected to
+                     // describe the actual (README-documented) fire-and-forget behavior.
+                     const calls = [];
+                     const script = cuts();
+                     const scenes = [
+                                     {
+                                           name: 'top'
+                                         , scene: {
+                                                     show      : ({task}) => { calls.push('show'); task.done() },
+                                                     hide      : ({task}) => task.done(),
+                                                     afterShow : () => { calls.push('afterShow'); return false }
+                                             }
+                                         }
+                                 ];
+
+                     script.setScenes ( scenes );
+                     await script.show ({ scene: 'top' });
+
+                     expect ( calls ).toEqual ([ 'show', 'afterShow' ]);
+                     expect ( script.getState() ).toEqual ({ scene: 'top', parents: [], opened: true });
+         }) // it afterShow return value has no effect on the completed show()
+
+
+
+     it ( 'hide() honors beforeHide, same as show() does', async () => {
+                     // Regression test: hide() used to ignore beforeHide entirely, so it could
+                     // never be blocked - even though show() already respected it when navigating
+                     // away to a different scene.
+                     const calls = [];
+                     const script = cuts();
+                     const scenes = [
+                                     {
+                                           name: 'top'
+                                         , scene: {
+                                                     show       : ({task}) => { calls.push('show top'); task.done() },
+                                                     hide       : ({task}) => { calls.push('hide top'); task.done() },
+                                                     beforeHide : ({ done }) => { calls.push('beforeHide'); done ( false ) }
+                                             }
+                                         }
+                                 ];
+
+                     script.setScenes ( scenes );
+                     await script.show ({ scene: 'top' });
+                     calls.length = 0;
+
+                     await script.hide ();
+                     expect ( calls ).toEqual ([ 'beforeHide' ]); // hide() never actually ran
+                     expect ( script.getState() ).toEqual ({ scene: 'top', parents: [], opened: true });
+         }) // it hide() honors beforeHide, same as show() does
+
+
+
+     it ( 'jump() does not record a jump-stack entry when the navigation is blocked', async () => {
+                     // Regression test: jump() pushed onto the jump stack unconditionally, even when
+                     // the underlying show() was blocked (eg. by beforeHide) and nothing actually
+                     // changed - leaving a phantom entry that desynced jumpBack() from real history.
+                     const calls = [];
+                     const script = cuts();
+                     let block = true;
+                     const scenes = [
+                                     {
+                                           name: 'home'
+                                         , scene: {
+                                                     show       : ({task}) => { calls.push('show home'); task.done() },
+                                                     hide       : ({task}) => { calls.push('hide home'); task.done() },
+                                                     beforeHide : ({ done }) => done ( !block )
+                                             }
+                                         },
+                                         {
+                                           name: 'settings'
+                                         , scene: {
+                                                     show : ({task}) => { calls.push('show settings'); task.done() },
+                                                     hide : ({task}) => { calls.push('hide settings'); task.done() }
+                                             }
+                                         },
+                                         {
+                                           name: 'other'
+                                         , scene: {
+                                                     show : ({task}) => { calls.push('show other'); task.done() },
+                                                     hide : ({task}) => { calls.push('hide other'); task.done() }
+                                             }
+                                         }
+                                 ];
+
+                     script.setScenes ( scenes );
+                     await script.show ({ scene: 'home' });
+
+                     await script.jump ({ scene: 'settings' }); // blocked by beforeHide - no stack entry
+                     expect ( script.getState().scene ).toEqual ( 'home' );
+
+                     block = false;
+                     await script.jump ({ scene: 'other' }); // succeeds - exactly one real stack entry
+                     expect ( script.getState().scene ).toEqual ( 'other' );
+
+                     calls.length = 0;
+                     await script.jumpBack ();
+                     expect ( calls ).toEqual ([ 'hide other', 'show home' ]);
+                     expect ( script.getState().scene ).toEqual ( 'home' );
+
+                     calls.length = 0;
+                     await script.jumpBack (); // stack should already be empty - true no-op
+                     expect ( calls ).toEqual ([]);
+                     expect ( script.getState().scene ).toEqual ( 'home' );
+         }) // it jump() does not record a jump-stack entry when the navigation is blocked
+
+
+
+     it ( 'Navigating from a wildcard overlay to an unrelated scene hides the scene it was covering', async () => {
+                     // Regression test: findInstructions is a lazy generator, and show() passed it
+                     // state.currentParents by reference. getStep's wildcard climb (state.currentParents.pop())
+                     // mutated that same array mid-iteration, corrupting the generator's still-pending reads
+                     // and silently dropping the 'hide' instruction for the scene the overlay was covering -
+                     // leaking it as permanently visible.
+                     const calls = [];
+                     const script = cuts();
+                     const scenes = [
+                                     { name: 'G', scene: { show: ({task}) => { calls.push('show G'); task.done() }, hide: ({task}) => { calls.push('hide G'); task.done() } } },
+                                     { name: 'OV', scene: { show: ({task}) => { calls.push('show OV'); task.done() }, hide: ({task}) => { calls.push('hide OV'); task.done() }, parents: ['*'] } },
+                                     { name: 'D', scene: { show: ({task}) => { calls.push('show D'); task.done() }, hide: ({task}) => { calls.push('hide D'); task.done() } } }
+                                 ];
+
+                     script.setScenes ( scenes );
+                     await script.show ({ scene: 'G' });
+                     await script.show ({ scene: 'OV' });
+                     calls.length = 0;
+
+                     await script.show ({ scene: 'D' });
+                     expect ( calls ).toEqual ([ 'hide OV', 'hide G', 'show D' ]);
+                     expect ( script.getState() ).toEqual ({ scene: 'D', parents: [], opened: true });
+         }) // it Navigating from a wildcard overlay to an unrelated scene hides the scene it was covering
+
+
+
+     it ( 'Showing a wildcard overlay with no underlying scene does not crash later navigation', async () => {
+                     // Regression test: showing an overlay when state.currentScene was null recorded a
+                     // literal 'null' placeholder in currentParents. Navigating away from it later crashed,
+                     // because findInstructions/getStep treated that placeholder as a real scene name to hide.
+                     const script = cuts();
+                     const scenes = [
+                                     { name: 'F', scene: { show: ({task}) => task.done(), hide: ({task}) => task.done() } },
+                                     { name: 'OV', scene: { show: ({task}) => task.done(), hide: ({task}) => task.done(), parents: ['*'] } },
+                                     { name: 'A', scene: { show: ({task}) => task.done(), hide: ({task}) => task.done() } }
+                                 ];
+
+                     script.setScenes ( scenes );
+                     await script.show ({ scene: 'F' });
+                     await script.hide ( 1 ); // back to nothing - currentScene becomes null
+                     await script.show ({ scene: 'OV' }); // overlay with no underlying scene
+
+                     expect ( script.getState() ).toEqual ({ scene: 'OV', parents: [], opened: true });
+
+                     await script.show ({ scene: 'A' }); // used to throw
+                     expect ( script.getState() ).toEqual ({ scene: 'A', parents: [], opened: true });
+         }) // it Showing a wildcard overlay with no underlying scene does not crash later navigation
+
+
+
+     it ( 'Re-showing the same wildcard overlay does not push it onto its own ancestor chain', async () => {
+                     // Regression test: showing an overlay while it was ALREADY the current scene pushed
+                     // it onto its own currentParents (self-reference). A later hide() would then pop that
+                     // self-reference and report the overlay as still current, even though it had just been
+                     // hidden - a state/reality desync.
+                     const script = cuts();
+                     const visible = new Set();
+                     const scenes = [
+                                     { name: 'C', scene: { show: ({task}) => { visible.add('C'); task.done() }, hide: ({task}) => { visible.delete('C'); task.done() } } },
+                                     { name: 'OV', scene: { show: ({task}) => { visible.add('OV'); task.done() }, hide: ({task}) => { visible.delete('OV'); task.done() }, parents: ['*'] } }
+                                 ];
+
+                     script.setScenes ( scenes );
+                     await script.show ({ scene: 'C' });
+                     await script.show ({ scene: 'OV' });
+                     await script.show ({ scene: 'OV' }); // show the same overlay again while already current
+
+                     expect ( script.getState() ).toEqual ({ scene: 'OV', parents: [ 'C' ], opened: true });
+
+                     await script.hide ( 1 );
+                     expect ( script.getState() ).toEqual ({ scene: 'C', parents: [], opened: true });
+                     expect ( [...visible] ).toEqual ([ 'C' ]); // OV must actually be gone, matching reported state
+         }) // it Re-showing the same wildcard overlay does not push it onto its own ancestor chain
+
+
+
  }) // describe

package/vitest.config.js

@@ -3,7 +3,7 @@ import { defineConfig } from 'vitest/config'
 export default defineConfig({
   test: {
     environment: 'node',
-    exclude: ['test-e2e/**', 'node_modules/**'],
+    exclude: ['test-e2e/**', '**/node_modules/**'],
     coverage: {
       provider: 'v8',
       reporter: ['lcov', 'text-summary'],