wyreframe 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -99,6 +99,8 @@ export interface SceneManager {
     /** Get all available scene IDs */
     getSceneIds: () => string[];
 }
+/** Scene change callback type */
+export type OnSceneChangeCallback = (fromScene: string | undefined, toScene: string) => void;
 /** Render options */
 export interface RenderOptions {
     /** Theme name */
@@ -109,6 +111,13 @@ export interface RenderOptions {
     injectStyles?: boolean;
     /** Additional CSS class for container */
     containerClass?: string;
+    /**
+     * Callback fired when navigating between scenes.
+     * Useful for implementing scene history, analytics, or state synchronization.
+     * @param fromScene - The scene ID navigating from (undefined if initial navigation)
+     * @param toScene - The scene ID navigating to
+     */
+    onSceneChange?: OnSceneChangeCallback;
 }
 /** Render result */
 export interface RenderResult {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH,wCAAwC;AACxC,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,kBAAkB,GAClB,QAAQ,GACR,kBAAkB,CAAC;AAEvB,0CAA0C;AAC1C,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,YAAY,GAAG,aAAa,GAAG,MAAM,CAAC;AAE5E,qBAAqB;AACrB,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpD,4BAA4B;AAC5B,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;AAE9D,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC;AAEhC,uBAAuB;AACvB,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,KAAK,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,QAAQ,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,OAAO,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,UAAU,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,SAAS,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,KAAK,CAAC;IACX,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,SAAS,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,OAAO,GACf,UAAU,GACV,aAAa,GACb,YAAY,GACZ,WAAW,GACX,WAAW,GACX,eAAe,GACf,cAAc,GACd,UAAU,GACV,cAAc,CAAC;AAEnB,uBAAuB;AACvB,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,cAAc,CAAC;IAC3B,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,2BAA2B;AAC3B,MAAM,WAAW,GAAG;IAClB,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,8BAA8B;AAC9B,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,+BAA+B;IAC/B,eAAe,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAC1C,kCAAkC;IAClC,WAAW,EAAE,MAAM,MAAM,EAAE,CAAC;CAC7B;AAED,iCAAiC;AACjC,MAAM,MAAM,qBAAqB,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAE7F,qBAAqB;AACrB,MAAM,WAAW,aAAa;IAC5B,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,qBAAqB,CAAC;CACvC;AAED,oBAAoB;AACpB,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,mCAAmC;IACnC,YAAY,EAAE,YAAY,CAAC;CAC5B;AAMD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,IAAI,CAAC;IACd,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,kBAAkB,GAAG,gBAAgB,CAAC;AAEhE,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,IAAI,CAAC;IACd,YAAY,EAAE,OAAO,EAAE,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,wBAAwB,GAAG,sBAAsB,CAAC;AAElF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,YAAY,CAAC;IAC3B,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,qBAAqB,GAAG,mBAAmB,CAAC;AAsBzE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAS/C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAW9C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAS7D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAQhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,CAqCtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,cAAc,CAgB9E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,aAAa,GACtB,YAAY,GAAG;IAAE,GAAG,EAAE,GAAG,CAAA;CAAE,CAK7B;AAGD,eAAO,MAAM,OAAO,EAAE,MAAuB,CAAC;AAC9C,eAAO,MAAM,cAAc,EAAE,MAA8B,CAAC;;;;;;;;;;;;AAG5D,wBAUE"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wyreframe",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "ASCII wireframe + interaction DSL to HTML converter with scene transitions",
   "author": "wickedev",
   "repository": {

package/src/index.test.ts

@@ -0,0 +1,252 @@
+/**
+ * Tests for TypeScript API wrapper input validation
+ *
+ * These tests verify that render() provides helpful error messages
+ * when called with incorrect arguments (Issue #1).
+ */
+
+import { describe, test, expect, vi } from 'vitest';
+import { parse, render, createUI } from './index';
+import type { AST, ParseResult, OnSceneChangeCallback } from './index';
+
+describe('render() input validation (Issue #1)', () => {
+  const validWireframe = `
+@scene: test
+
++-------+
+| Hello |
++-------+
+`;
+
+  test('throws descriptive error when passed successful ParseResult instead of AST', () => {
+    const result = parse(validWireframe);
+
+    // Verify we have a successful parse result
+    expect(result.success).toBe(true);
+
+    // This is the common mistake: passing result instead of result.ast
+    expect(() => {
+      render(result as unknown as AST);
+    }).toThrow('render() expects an AST object, but received a ParseResult');
+
+    expect(() => {
+      render(result as unknown as AST);
+    }).toThrow('Did you forget to extract .ast?');
+  });
+
+  test('throws descriptive error when passed failed ParseResult', () => {
+    // Invalid wireframe that will fail to parse
+    const invalidWireframe = '+--incomplete';
+    const result = parse(invalidWireframe);
+
+    // This should be a failed parse
+    expect(result.success).toBe(false);
+
+    expect(() => {
+      render(result as unknown as AST);
+    }).toThrow('render() received a failed ParseResult');
+
+    expect(() => {
+      render(result as unknown as AST);
+    }).toThrow('Check parse errors before calling render');
+  });
+
+  test('throws descriptive error when passed null or undefined', () => {
+    expect(() => {
+      render(null as unknown as AST);
+    }).toThrow('render() expects an AST object with a scenes array');
+
+    expect(() => {
+      render(undefined as unknown as AST);
+    }).toThrow('render() expects an AST object with a scenes array');
+  });
+
+  test('throws descriptive error when passed object without scenes array', () => {
+    const invalidAST = { foo: 'bar' };
+
+    expect(() => {
+      render(invalidAST as unknown as AST);
+    }).toThrow('render() expects an AST object with a scenes array');
+
+    expect(() => {
+      render(invalidAST as unknown as AST);
+    }).toThrow('Did you pass ParseResult instead of ParseResult.ast?');
+  });
+
+  // Note: DOM-dependent tests are skipped in Node.js environment
+  // The renderer requires a browser or jsdom environment
+  test.skip('works correctly when passed valid AST (requires DOM)', () => {
+    const result = parse(validWireframe);
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      // This is the correct usage
+      const { root, sceneManager } = render(result.ast);
+
+      expect(root).toBeDefined();
+      expect(root).toBeInstanceOf(HTMLElement);
+      expect(sceneManager).toBeDefined();
+      expect(sceneManager.getSceneIds()).toContain('test');
+    }
+  });
+});
+
+describe('createUI() convenience function', () => {
+  test('handles parse errors gracefully', () => {
+    const invalidWireframe = '+--incomplete';
+    const result = createUI(invalidWireframe);
+
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.errors).toBeDefined();
+      expect(result.errors.length).toBeGreaterThan(0);
+    }
+  });
+
+  // Note: DOM-dependent tests are skipped in Node.js environment
+  test.skip('works correctly with valid wireframe (requires DOM)', () => {
+    const validWireframe = `
+@scene: test
+
++-------+
+| Hello |
++-------+
+`;
+    const result = createUI(validWireframe);
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.root).toBeDefined();
+      expect(result.sceneManager).toBeDefined();
+      expect(result.ast).toBeDefined();
+    }
+  });
+});
+
+describe('onSceneChange callback (Issue #2)', () => {
+  const multiSceneWireframe = `
+@scene: login
+
++---------------+
+| Login Screen  |
++---------------+
+
+---
+
+@scene: dashboard
+
++---------------+
+| Dashboard     |
++---------------+
+`;
+
+  test('OnSceneChangeCallback type is exported', () => {
+    // Verify the type is exported by using it
+    const callback: OnSceneChangeCallback = (_from, _to) => {};
+    expect(typeof callback).toBe('function');
+  });
+
+  // Note: DOM-dependent tests are skipped in Node.js environment
+  test.skip('render accepts onSceneChange option without throwing (requires DOM)', () => {
+    const result = parse(multiSceneWireframe);
+    expect(result.success).toBe(true);
+
+    if (result.success) {
+      const callback = vi.fn();
+
+      // This should not throw - just verify the API accepts the option
+      expect(() => {
+        render(result.ast, {
+          onSceneChange: callback,
+        });
+      }).not.toThrow();
+    }
+  });
+
+  test.skip('createUI accepts onSceneChange option without throwing (requires DOM)', () => {
+    const callback = vi.fn();
+
+    // Verify the API accepts the option
+    expect(() => {
+      createUI(multiSceneWireframe, {
+        onSceneChange: callback,
+      });
+    }).not.toThrow();
+  });
+
+  // Note: DOM-dependent tests are skipped in Node.js environment
+  test.skip('onSceneChange is called on initial scene load (requires DOM)', () => {
+    const result = parse(multiSceneWireframe);
+    expect(result.success).toBe(true);
+
+    if (result.success) {
+      const callback = vi.fn();
+      render(result.ast, { onSceneChange: callback });
+
+      // Should be called once for initial scene
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(callback).toHaveBeenCalledWith(undefined, 'login');
+    }
+  });
+
+  test.skip('onSceneChange is called when navigating between scenes (requires DOM)', () => {
+    const result = parse(multiSceneWireframe);
+    expect(result.success).toBe(true);
+
+    if (result.success) {
+      const callback = vi.fn();
+      const { sceneManager } = render(result.ast, { onSceneChange: callback });
+
+      // Clear mock after initial call
+      callback.mockClear();
+
+      // Navigate to dashboard
+      sceneManager.goto('dashboard');
+
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(callback).toHaveBeenCalledWith('login', 'dashboard');
+    }
+  });
+
+  test.skip('onSceneChange is not called when navigating to the same scene (requires DOM)', () => {
+    const result = parse(multiSceneWireframe);
+    expect(result.success).toBe(true);
+
+    if (result.success) {
+      const callback = vi.fn();
+      const { sceneManager } = render(result.ast, { onSceneChange: callback });
+
+      // Clear mock after initial call
+      callback.mockClear();
+
+      // Navigate to the same scene
+      sceneManager.goto('login');
+
+      expect(callback).not.toHaveBeenCalled();
+    }
+  });
+
+  test.skip('onSceneChange receives correct fromScene and toScene values (requires DOM)', () => {
+    const result = parse(multiSceneWireframe);
+    expect(result.success).toBe(true);
+
+    if (result.success) {
+      const navigationHistory: Array<{ from: string | undefined; to: string }> = [];
+      const callback: OnSceneChangeCallback = (from, to) => {
+        navigationHistory.push({ from, to });
+      };
+
+      const { sceneManager } = render(result.ast, { onSceneChange: callback });
+
+      // Navigate through scenes
+      sceneManager.goto('dashboard');
+      sceneManager.goto('login');
+
+      expect(navigationHistory).toEqual([
+        { from: undefined, to: 'login' },  // Initial
+        { from: 'login', to: 'dashboard' },
+        { from: 'dashboard', to: 'login' },
+      ]);
+    }
+  });
+});

package/src/index.ts

@@ -146,6 +146,9 @@ export interface SceneManager {
   getSceneIds: () => string[];
 }
 
+/** Scene change callback type */
+export type OnSceneChangeCallback = (fromScene: string | undefined, toScene: string) => void;
+
 /** Render options */
 export interface RenderOptions {
   /** Theme name */
@@ -156,6 +159,13 @@ export interface RenderOptions {
   injectStyles?: boolean;
   /** Additional CSS class for container */
   containerClass?: string;
+  /**
+   * Callback fired when navigating between scenes.
+   * Useful for implementing scene history, analytics, or state synchronization.
+   * @param fromScene - The scene ID navigating from (undefined if initial navigation)
+   * @param toScene - The scene ID navigating to
+   */
+  onSceneChange?: OnSceneChangeCallback;
 }
 
 /** Render result */

package/src/parser/Errors/ErrorTypes.mjs

@@ -178,15 +178,12 @@ function adjustCodeLineOffset(code, offset) {
 }
 
 function adjustLineOffset(error, offset) {
-  if (offset === 0) {
-    return error;
-  } else {
-    return {
-      code: adjustCodeLineOffset(error.code, offset),
-      severity: error.severity,
-      context: error.context
-    };
-  }
+  let totalOffset = offset + 1 | 0;
+  return {
+    code: adjustCodeLineOffset(error.code, totalOffset),
+    severity: error.severity,
+    context: error.context
+  };
 }
 
 export {

package/src/parser/Errors/ErrorTypes.res

@@ -217,18 +217,21 @@ let adjustCodeLineOffset = (code: errorCode, offset: int): errorCode => {
  * Adjust the line offset in an error's position.
  * Creates a new error with the position adjusted by the given offset.
  *
+ * This function always adds +1 to convert from 0-indexed grid rows
+ * to 1-indexed file line numbers, plus any offset for stripped directive lines.
+ *
  * @param error - The error to adjust
- * @param offset - The number of lines to add to the row
- * @returns A new error with adjusted position
+ * @param offset - The number of directive lines stripped before grid processing
+ * @returns A new error with 1-indexed line position
  */
 let adjustLineOffset = (error: t, offset: int): t => {
-  if offset === 0 {
-    error
-  } else {
-    {
-      code: adjustCodeLineOffset(error.code, offset),
-      severity: error.severity,
-      context: error.context,
-    }
+  // Always add 1 to convert from 0-indexed to 1-indexed line numbers
+  // offset accounts for stripped directive lines (e.g., @scene: login)
+  // +1 converts from 0-indexed grid rows to 1-indexed file lines
+  let totalOffset = offset + 1
+  {
+    code: adjustCodeLineOffset(error.code, totalOffset),
+    severity: error.severity,
+    context: error.context,
   }
 }

package/src/renderer/Renderer.gen.tsx

@@ -11,12 +11,19 @@ import type {t as ErrorTypes_t} from '../../src/parser/Errors/ErrorTypes.gen';
 
 export abstract class DomBindings_element { protected opaque!: any }; /* simulate opaque types */
 
+/** * Scene change callback type.
+ * Called when navigating between scenes.
+ * @param fromScene The scene ID navigating from (None if initial)
+ * @param toScene The scene ID navigating to */
+export type onSceneChangeCallback = (_1:(undefined | string), _2:string) => void;
+
 /** * Configuration for the rendering process. */
 export type renderOptions = {
   readonly theme: (undefined | string); 
   readonly interactive: boolean; 
   readonly injectStyles: boolean; 
-  readonly containerClass: (undefined | string)
+  readonly containerClass: (undefined | string); 
+  readonly onSceneChange: (undefined | onSceneChangeCallback)
 };
 
 /** * Scene management interface returned by render function. */

package/src/renderer/Renderer.mjs

@@ -12,7 +12,8 @@ let defaultOptions = {
   theme: undefined,
   interactive: true,
   injectStyles: true,
-  containerClass: undefined
+  containerClass: undefined,
+  onSceneChange: undefined
 };
 
 let defaultStyles = `
@@ -280,7 +281,7 @@ function renderScene(scene, onAction) {
   return sceneEl;
 }
 
-function createSceneManager(scenes) {
+function createSceneManager(scenes, onSceneChange) {
   let currentScene = {
     contents: undefined
   };
@@ -290,10 +291,11 @@ function createSceneManager(scenes) {
   let forwardStack = {
     contents: []
   };
-  let switchToScene = id => {
-    let currentId = currentScene.contents;
-    if (currentId !== undefined) {
-      let el = scenes.get(currentId);
+  let switchToScene = (id, notifyOpt) => {
+    let notify = notifyOpt !== undefined ? notifyOpt : true;
+    let previousScene = currentScene.contents;
+    if (previousScene !== undefined) {
+      let el = scenes.get(previousScene);
       if (el !== undefined) {
         Primitive_option.valFromOption(el).classList.remove("active");
       }
@@ -302,7 +304,15 @@ function createSceneManager(scenes) {
     if (el$1 !== undefined) {
       Primitive_option.valFromOption(el$1).classList.add("active");
       currentScene.contents = id;
-      return;
+      if (notify && (previousScene === undefined || previousScene !== id)) {
+        if (onSceneChange !== undefined) {
+          return onSceneChange(previousScene, id);
+        } else {
+          return;
+        }
+      } else {
+        return;
+      }
     }
   };
   let goto = id => {
@@ -311,7 +321,7 @@ function createSceneManager(scenes) {
       historyStack.contents = historyStack.contents.concat([currentId]);
       forwardStack.contents = [];
     }
-    switchToScene(id);
+    switchToScene(id, undefined);
   };
   let back = () => {
     let history = historyStack.contents;
@@ -328,7 +338,7 @@ function createSceneManager(scenes) {
       forwardStack.contents = forwardStack.contents.concat([currentId]);
     }
     historyStack.contents = history.slice(0, len - 1 | 0);
-    switchToScene(prevId);
+    switchToScene(prevId, undefined);
   };
   let forward = () => {
     let fwdStack = forwardStack.contents;
@@ -345,7 +355,7 @@ function createSceneManager(scenes) {
       historyStack.contents = historyStack.contents.concat([currentId]);
     }
     forwardStack.contents = fwdStack.slice(0, len - 1 | 0);
-    switchToScene(nextId);
+    switchToScene(nextId, undefined);
   };
   let refresh = () => {
     let id = currentScene.contents;
@@ -451,7 +461,7 @@ function render(ast, options) {
     app.appendChild(sceneEl);
     sceneMap.set(scene.id, sceneEl);
   });
-  let manager = createSceneManager(sceneMap);
+  let manager = createSceneManager(sceneMap, opts.onSceneChange);
   gotoRef.contents = manager.goto;
   backRef.contents = manager.back;
   forwardRef.contents = manager.forward;

package/src/renderer/Renderer.res

@@ -48,6 +48,14 @@ module DomBindings = {
 // Render Options
 // ============================================================================
 
+/**
+ * Scene change callback type.
+ * Called when navigating between scenes.
+ * @param fromScene The scene ID navigating from (None if initial)
+ * @param toScene The scene ID navigating to
+ */
+type onSceneChangeCallback = (option<string>, string) => unit
+
 /**
  * Configuration for the rendering process.
  */
@@ -56,6 +64,7 @@ type renderOptions = {
   interactive: bool,
   injectStyles: bool,
   containerClass: option<string>,
+  onSceneChange: option<onSceneChangeCallback>,
 }
 
 /**
@@ -66,6 +75,7 @@ let defaultOptions: renderOptions = {
   interactive: true,
   injectStyles: true,
   containerClass: None,
+  onSceneChange: None,
 }
 
 // ============================================================================
@@ -418,14 +428,27 @@ let renderScene = (scene: scene, ~onAction: option<actionHandler>=?): DomBinding
 // Scene Manager Implementation
 // ============================================================================
 
-let createSceneManager = (scenes: Map.t<string, DomBindings.element>): sceneManager => {
+let createSceneManager = (
+  scenes: Map.t<string, DomBindings.element>,
+  ~onSceneChange: option<onSceneChangeCallback>=?,
+): sceneManager => {
   let currentScene = ref(None)
   let historyStack: ref<array<string>> = ref([])
   let forwardStack: ref<array<string>> = ref([])
 
+  // Helper to call onSceneChange callback if provided
+  let notifySceneChange = (fromScene: option<string>, toScene: string): unit => {
+    switch onSceneChange {
+    | Some(callback) => callback(fromScene, toScene)
+    | None => ()
+    }
+  }
+
   // Internal function to switch scenes without affecting history
-  let switchToScene = (id: string): unit => {
-    switch currentScene.contents {
+  let switchToScene = (id: string, ~notify: bool=true): unit => {
+    let previousScene = currentScene.contents
+
+    switch previousScene {
     | Some(currentId) => {
         switch scenes->Map.get(currentId) {
         | Some(el) => el->DomBindings.classList->DomBindings.remove("active")
@@ -439,6 +462,13 @@ let createSceneManager = (scenes: Map.t<string, DomBindings.element>): sceneMana
     | Some(el) => {
         el->DomBindings.classList->DomBindings.add("active")
         currentScene := Some(id)
+        // Notify callback if enabled and scene actually changed
+        if notify {
+          switch previousScene {
+          | Some(prevId) if prevId == id => () // Same scene, no notification
+          | _ => notifySceneChange(previousScene, id)
+          }
+        }
       }
     | None => ()
     }
@@ -634,7 +664,7 @@ let render = (ast: ast, options: option<renderOptions>): renderResult => {
     sceneMap->Map.set(scene.id, sceneEl)
   })
 
-  let manager = createSceneManager(sceneMap)
+  let manager = createSceneManager(sceneMap, ~onSceneChange=?opts.onSceneChange)
 
   // Now that sceneManager is created, set the refs
   gotoRef := Some(manager.goto)