robobyte-front-builder 1.0.19 → 1.0.23

package/next.config.js

@@ -1,33 +1,36 @@
 const path = require('path');
-const withTM = require('next-transpile-modules')([
-  '@fullcalendar/common',
-  '@fullcalendar/react',
-  '@fullcalendar/daygrid',
-  '@fullcalendar/list',
-  '@fullcalendar/timegrid',
-  '@mui/x-data-grid',
-  '@mui/material',
-  '@mui/utils',
-  'suneditor',
-  'suneditor-react',
-]);
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {
+  // Next.js 13+ has built-in transpilePackages — no need for next-transpile-modules
+  transpilePackages: [
+    '@mui/x-data-grid',
+    '@mui/material',
+    '@mui/utils',
+    'suneditor',
+    'suneditor-react',
+  ],
   trailingSlash: true,
   reactStrictMode: false,
   eslint: {
     ignoreDuringBuilds: true,
   },
   async rewrites() {
-    // Dynamic rewrites for friendly URLs - handled by [slug].js
-    // This allows /reports to internally route to /viewer/22
     return []
   },
   webpack: (config) => {
+    const src = path.resolve(__dirname, 'src');
+
+    // Resolve bare imports (pages/*, services/*, views/*, context/*, src/*)
+    // to the local src/ directory — same as the host app would do via
+    // NormalModuleReplacementPlugin, but simpler for standalone dev mode.
     config.resolve.alias = {
       ...config.resolve.alias,
-      apexcharts: path.resolve(__dirname, './node_modules/apexcharts-clevision'),
+      pages:   path.join(src, 'pages'),
+      services: path.join(src, 'services'),
+      views:   path.join(src, 'views'),
+      context: path.join(src, 'context'),
+      src:     src,
     };
 
     config.module.rules.push({
@@ -40,36 +43,4 @@ const nextConfig = {
   },
 };
 
-module.exports = withTM(nextConfig);
-
-
-
-
-
-// const path = require('path');
-// const withTM = require('next-transpile-modules')([
-//   '@fullcalendar/common',
-//   '@fullcalendar/react',
-//   '@fullcalendar/daygrid',
-//   '@fullcalendar/list',
-//   '@fullcalendar/timegrid',
-//   '@mui/x-data-grid',
-// ]);
-
-// /** @type {import('next').NextConfig} */
-// const nextConfig = {
-//   trailingSlash: true,
-//   reactStrictMode: false,
-//   eslint: {
-//     ignoreDuringBuilds: true,
-//   },
-//   webpack: config => {
-//     config.resolve.alias = {
-//       ...config.resolve.alias,
-//       apexcharts: path.resolve(__dirname, './node_modules/apexcharts-clevision'),
-//     };
-//     return config;
-//   },
-// };
-
-// module.exports = withTM(nextConfig);
+module.exports = nextConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robobyte-front-builder",
-  "version": "1.0.19",
+  "version": "1.0.23",
   "description": "RoboByte low-code UI builder, Report builder, and navigation extension system",
   "main": "src/lib/index.js",
   "files": [
@@ -8,7 +8,9 @@
     "public",
     "styles",
     "next.config.js",
-    "jsconfig.json"
+    "jsconfig.json",
+    "INTEGRATION.md",
+    "RoboByteBuilder_User_Manual.docx"
   ],
   "exports": {
     ".": "./src/lib/index.js",
@@ -21,133 +23,87 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "export": "next export",
     "lint": "eslint --fix \"src/**/*.{js,jsx}\"",
     "format": "prettier --write \"src/**/*.{js,jsx}\"",
-    "prepublishOnly": "echo 'Publishing @robobyte/front-builder — source-first package, no build step required'"
+    "prepublishOnly": "echo 'Publishing robobyte-front-builder — source-first package, no build step required'"
   },
   "peerDependencies": {
+    "@emotion/react": "^11",
+    "@emotion/styled": "^11",
+    "@mui/icons-material": "^7",
+    "@mui/lab": "^7",
+    "@mui/material": "^7",
+    "@mui/system": "^7",
+    "@mui/x-data-grid": "^7",
+    "@mui/x-date-pickers": "^7",
+    "@mui/x-internals": "^7",
+    "@mui/x-virtualizer": "^7",
+    "ag-grid-community": "^33",
+    "ag-grid-enterprise": "^33",
+    "ag-grid-react": "^33",
+    "next": ">=13",
     "react": ">=18",
     "react-dom": ">=18",
-    "next": ">=13",
-    "@mui/material": ">=7",
-    "@mui/icons-material": ">=7",
-    "@mui/lab": ">=7",
-    "@mui/system": ">=7",
-    "@mui/x-data-grid": ">=7",
-    "@mui/x-date-pickers": ">=7",
-    "@mui/x-tree-view": ">=7",
-    "@emotion/cache": ">=11",
-    "@emotion/react": ">=11",
-    "@emotion/server": ">=11",
-    "@emotion/styled": ">=11",
-    "axios": ">=1"
+    "xlsx": ">=0.18",
+    "react-hot-toast": ">=2"
   },
   "dependencies": {
-    "@auth0/auth0-react": "2.1.0",
-    "@aws-amplify/auth": "5.3.6",
-    "@aws-amplify/ui-react": "4.6.3",
-    "@babel/eslint-parser": "7.21.8",
-    "@casl/ability": "6.5.0",
-    "@casl/react": "3.1.0",
-    "@date-io/date-fns": "^2.16.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@fullcalendar/common": "5.11.5",
-    "@fullcalendar/core": "6.1.7",
-    "@fullcalendar/daygrid": "6.1.7",
-    "@fullcalendar/interaction": "6.1.7",
-    "@fullcalendar/list": "6.1.7",
-    "@fullcalendar/react": "6.1.7",
-    "@fullcalendar/timegrid": "6.1.7",
     "@hookform/resolvers": "3.1.0",
-    "@microsoft/signalr": "^8.0.0",
     "@monaco-editor/react": "^4.7.0",
-    "@popperjs/core": "2.11.7",
     "@react-google-maps/api": "^2.19.2",
-    "@reduxjs/toolkit": "1.9.5",
-    "@unicef/material-ui-currency-textfield": "^0.8.6",
-    "ag-grid-community": "^33.3.2",
-    "ag-grid-enterprise": "^33.3.2",
-    "ag-grid-react": "^33.3.2",
-    "apexcharts-clevision": "3.28.5",
-    "aws-amplify": "^5.3.13",
-    "axios-mock-adapter": "1.21.4",
-    "babel-eslint": "10.1.0",
-    "chart.js": "4.3.0",
+    "axios": "^1.6.0",
     "classnames": "2.5.1",
-    "cleave.js": "1.6.0",
-    "clipboard-copy": "4.0.1",
-    "clsx": "1.2.1",
-    "date-fns": "^2.30.0",
     "dayjs": "^1.11.9",
     "draft-js": "0.11.7",
-    "firebase": "9.22.0",
-    "hls.js": "^1.0.3-0.canary.7275",
-    "https": "^1.0.0",
-    "i18next": "22.5.0",
-    "i18next-browser-languagedetector": "7.0.1",
-    "i18next-http-backend": "2.2.1",
-    "jsonwebtoken": "9.0.0",
     "jspdf": "^3.0.3",
-    "jspdf-autotable": "^5.0.2",
-    "jwt-decode": "^4.0.0",
-    "keen-slider": "6.8.5",
+    "jspdf-autotable": "^5.0.7",
     "list": "^2.0.19",
+    "lodash": "^4.17.21",
     "mdi-material-ui": "7.7.0",
     "moment": "^2.30.1",
     "moment-timezone": "^0.5.47",
-    "notistack": "^3.0.2",
-    "nprogress": "0.2.0",
     "numeral": "^2.0.6",
-    "payment": "2.4.6",
-    "prismjs": "1.29.0",
-    "prop-types": "^15.8.1",
-    "react-apexcharts": "1.4.0",
     "react-beautiful-dnd": "13.1.1",
-    "react-chartjs-2": "5.2.0",
-    "react-colorful": "^5.6.1",
-    "react-credit-cards": "0.8.3",
     "react-datepicker": "4.11.0",
-    "react-draft-wysiwyg": "1.15.0",
-    "react-dropzone": "14.2.3",
     "react-hook-form": "7.43.9",
-    "react-hot-toast": "2.4.1",
-    "react-i18next": "12.3.1",
-    "react-multi-date-picker": "^4.5.2",
     "react-number-format": "^5.4.0",
     "react-perfect-scrollbar": "1.5.8",
-    "react-popper": "2.3.0",
-    "react-quill": "^2.0.0",
-    "react-redux": "8.0.5",
     "react-signature-canvas": "^1.1.0-alpha.2",
-    "react-to-pdf": "0.0.14",
     "react-use": "^17.6.0",
-    "react-viewer": "^3.2.2",
     "recharts": "2.6.2",
-    "rsuite": "^5.60.1",
-    "sass": "^1.77.8",
-    "styled-components": "^6.1.10",
-    "stylelint": "16.6.1",
-    "stylis": "4.2.0",
-    "stylis-plugin-rtl": "2.1.1",
     "suneditor": "^2.47.5",
     "suneditor-react": "^3.6.1",
-    "sweetalert2": "^11.17.2",
-    "swiper": "^11.2.5",
     "uuid": "^11.1.0",
+    "xlsx": "^0.18.5",
     "yup": "1.1.1"
   },
   "devDependencies": {
     "@babel/core": "^7.22.0",
+    "@emotion/react": "^11",
+    "@emotion/styled": "^11",
+    "@mui/icons-material": "^7",
+    "@mui/lab": "^7",
+    "@mui/material": "^7",
+    "@mui/system": "^7",
+    "@mui/x-data-grid": "^7",
+    "@mui/x-date-pickers": "^7",
+    "ag-charts-enterprise": "latest",
+    "ag-grid-community": "^33",
+    "ag-grid-enterprise": "^33",
+    "ag-grid-react": "^33",
     "eslint": "8.41.0",
     "eslint-config-next": "13.4.3",
     "eslint-config-prettier": "8.8.0",
     "eslint-import-resolver-alias": "1.1.2",
     "eslint-import-resolver-typescript": "3.5.5",
     "eslint-plugin-import": "2.27.5",
-    "next-transpile-modules": "^10.0.0",
-    "prettier": "2.8.8"
+    "next": "^13",
+    "next-transpile-modules": "^9",
+    "prettier": "2.8.8",
+    "react": "^18",
+    "react-dom": "^18"
   }
 }

package/src/context/BuilderContext.jsx

@@ -1,7 +1,10 @@
-import { createContext, useContext, useEffect, useState } from 'react'
+import { createContext, useCallback, useContext, useEffect, useReducer, useRef, useState } from 'react'
 import { executeActionsByEvent } from 'services/builderHelper/actionExecutor'
 import { findNode } from 'services/builderHelper'
 import { executeJSCode } from 'services/builderHelper/jsExecutor'
+import UnsavedChangesGuard from 'views/builder/UnsavedChangesGuard'
+import SessionLogDialog from 'views/builder/SessionLogDialog'
+import { logSchema as logSchemaToStore } from 'services/sessionLog'
 
 const BuilderContext = createContext(null)
 
@@ -88,11 +91,89 @@ const initialSchema = {
     className: '',
     children: []
   },
-  actions: []
+  dialogs: [],
+  actions: [],
+  timers: []
+}
+
+// ── History reducer (undo / redo) ─────────────────────────────────────────────
+//
+//  State shape:  { past: Schema[], present: Schema, future: Schema[] }
+//
+//  SET   — normal edit: discard redo stack, push present → past, apply new state
+//  UNDO  — move one step back in history
+//  REDO  — move one step forward in history
+//
+//  History is capped at 100 entries per direction to bound memory usage.
+//
+const HISTORY_LIMIT = 100
+
+function historyReducer(state, action) {
+  switch (action.type) {
+    case 'SET': {
+      const next = typeof action.payload === 'function'
+        ? action.payload(state.present)
+        : action.payload
+      if (next === state.present) return state
+      return {
+        past:    [...state.past, state.present].slice(-HISTORY_LIMIT),
+        present: next,
+        future:  []
+      }
+    }
+    case 'UNDO': {
+      if (state.past.length === 0) return state
+      const prev = state.past[state.past.length - 1]
+      return {
+        past:    state.past.slice(0, -1),
+        present: prev,
+        future:  [state.present, ...state.future].slice(0, HISTORY_LIMIT)
+      }
+    }
+    case 'REDO': {
+      if (state.future.length === 0) return state
+      const next = state.future[0]
+      return {
+        past:    [...state.past, state.present].slice(-HISTORY_LIMIT),
+        present: next,
+        future:  state.future.slice(1)
+      }
+    }
+    // LOAD — replace the schema without marking it as a user edit (e.g. fetched
+    // from server). Clears history so the freshly loaded state is the new baseline.
+    case 'LOAD': {
+      return { past: [], present: action.payload, future: [] }
+    }
+    // MARK_CLEAN — keep the present schema but reset history so isDirty becomes
+    // false. Used after a successful save.
+    case 'MARK_CLEAN': {
+      return { past: [], present: state.present, future: [] }
+    }
+    default:
+      return state
+  }
 }
 
 export function BuilderProvider({ children }) {
-  const [schema, setSchema] = useState(initialSchema)
+  const [historyState, dispatch] = useReducer(historyReducer, {
+    past:    [],
+    present: initialSchema,
+    future:  []
+  })
+
+  // Convenience aliases — schema reads the present snapshot;
+  // setSchema dispatches a SET action (automatically tracked in history).
+  const schema      = historyState.present
+  const setSchema   = useCallback((updater) => dispatch({ type: 'SET', payload: updater }), [])
+  const loadSchema  = useCallback((next) => dispatch({ type: 'LOAD', payload: next }), [])
+  const markClean   = useCallback(() => dispatch({ type: 'MARK_CLEAN' }), [])
+  const undo        = useCallback(() => dispatch({ type: 'UNDO' }), [])
+  const redo        = useCallback(() => dispatch({ type: 'REDO' }), [])
+  const canUndo     = historyState.past.length > 0
+  const canRedo     = historyState.future.length > 0
+  // isDirty — present schema differs from the last loaded/saved baseline.
+  // Equivalent to canUndo because LOAD and MARK_CLEAN both reset past to [].
+  const isDirty     = canUndo
   const [selectedId, setSelectedId] = useState(null)
   const [viewMetaData, setViewMetaData] = useState({
     id: null,
@@ -105,7 +186,7 @@ export function BuilderProvider({ children }) {
   })
 
   // ✅ NEW: editor mode
-  const [mode, setMode] = useState('edit') // 'edit' | 'preview'
+  const [mode, setMode] = useState('edit') // 'edit' | 'preview' | 'print'
 
   // ✅ NEW: global data object for action results
   const [data, setData] = useState({})
@@ -116,6 +197,63 @@ export function BuilderProvider({ children }) {
   // ✅ NEW: validation errors
   const [validationErrors, setValidationErrors] = useState({})
   const [draggingNodeId, setDraggingNodeId] = useState(null)
+  const [clipboard, setClipboard] = useState(null)  // copy/paste clipboard
+
+  // ── Session log dialog (training-data capture) ───────────────────────────
+  const [sessionLogOpen, setSessionLogOpen] = useState(false)
+  const openSessionLog  = useCallback(() => setSessionLogOpen(true),  [])
+  const closeSessionLog = useCallback(() => setSessionLogOpen(false), [])
+
+  /**
+   * Append a schema snapshot to the session log. Call this from save handlers
+   * so every successful save becomes a labelable training example.
+   * `prompt` is intentionally left empty — developers fill it in later via
+   * the Session Logs dialog.
+   */
+  const logSchema = useCallback(({ builder, trigger = 'save', title = '', viewMetaData = {}, schema: schemaArg }) => {
+    return logSchemaToStore({
+      builder,
+      trigger,
+      title,
+      viewMetaData,
+      schema: schemaArg ?? schema,
+      prompt: ''
+    })
+  // schema is captured at call time when omitted; keep deps minimal
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [schema])
+
+  // ── Unified ref storage ────────────────────────────────────────────────────
+  // dataRef    : mutable non-reactive store; read/write from any function
+  //              without triggering re-renders. Access via dataRef.current.
+  // reportRefs : registry of { [nodeId]: updateRef } for every ReportViewer.
+  //              Each report registers itself; access from JS functions via
+  //              reportRefs['nodeId'].current (the updateRef array).
+  const dataRef       = useRef({})
+  const reportRefs    = useRef({})
+  const dialogRefs    = useRef({})
+  const printDialogRef = useRef(null) // { open: (data?) => void, close: () => void }
+
+  const openDialog = useCallback((key, data) => {
+    const ref = dialogRefs.current[key]
+    if (ref) ref.open(data)
+    else console.warn(`[openDialog] No dialog registered with key "${key}"`)
+  }, [])
+
+  const closeDialog = useCallback((key) => {
+    const ref = dialogRefs.current[key]
+    if (ref) ref.close()
+    else console.warn(`[closeDialog] No dialog registered with key "${key}"`)
+  }, [])
+
+  const openPrintLayout = useCallback((data) => {
+    if (printDialogRef.current) printDialogRef.current.open(data)
+    else console.warn('[openPrintLayout] PrintDialog is not mounted')
+  }, [])
+
+  const closePrintLayout = useCallback(() => {
+    if (printDialogRef.current) printDialogRef.current.close()
+  }, [])
 
   useEffect(() => {
     console.log('BUILDER SCHEMA:', schema)
@@ -131,7 +269,10 @@ export function BuilderProvider({ children }) {
 
       // Execute onLoad actions with fresh context
       if (schema.actions && schema.actions.length > 0) {
-        executeActionsByEvent(schema.actions, 'onLoad', { form: {}, data: {} }, setData).catch(err => {
+        executeActionsByEvent(schema.actions, 'onLoad', {
+          form: {}, data: {}, setData,
+          dataRef: dataRef.current, reportRefs: reportRefs.current,
+        }).catch(err => {
           console.error('onLoad actions error:', err)
         })
       }
@@ -154,7 +295,10 @@ export function BuilderProvider({ children }) {
 
     // If validation passes, execute onSubmit actions
     if (Object.keys(errors).length === 0) {
-      await executeActionsByEvent(schema.actions, 'onSubmit', { form, data }, setData)
+      await executeActionsByEvent(schema.actions, 'onSubmit', {
+        form, data, setData,
+        dataRef: dataRef.current, reportRefs: reportRefs.current,
+      })
       return true
     }
     return false
@@ -171,6 +315,15 @@ export function BuilderProvider({ children }) {
       value={{
         schema,
         setSchema,
+        loadSchema,
+        markClean,
+        isDirty,
+
+        // ── Undo / redo ──────────────────────────────────────────────────────
+        undo,
+        redo,
+        canUndo,
+        canRedo,
 
         viewMetaData,
         setViewMetaData,
@@ -181,6 +334,12 @@ export function BuilderProvider({ children }) {
         draggingNodeId,
         setDraggingNodeId,
 
+        // ── Copy/paste clipboard ─────────────────────────────────────────────
+        // clipboard — the last copied node (plain object, not cloned yet)
+        // setClipboard — store a node reference for later paste
+        clipboard,
+        setClipboard,
+
         // ✅ mode API
         mode,
         setMode,
@@ -191,6 +350,20 @@ export function BuilderProvider({ children }) {
         data,
         setData,
 
+        // ── Unified ref storage ──────────────────────────────────────────────
+        // dataRef       — mutable non-reactive store (useRef({})); mutate via dataRef.current
+        // reportRefs    — registry of { [nodeId]: updateRef } for all ReportViewers
+        // dialogRefs    — registry of { [key]: { open, close } } for all Dialogs
+        // printDialogRef — ref to the single PrintDialog { open, close }
+        dataRef,
+        reportRefs,
+        dialogRefs,
+        openDialog,
+        closeDialog,
+        printDialogRef,
+        openPrintLayout,
+        closePrintLayout,
+
         // ✅ form state and handlers
         form,
         setForm,
@@ -198,9 +371,20 @@ export function BuilderProvider({ children }) {
         validationErrors,
         setValidationErrors,
         submitForm,
-        resetForm
+        resetForm,
+
+        // ── Session log (AI training-data capture) ───────────────────────────
+        // logSchema({ builder, trigger?, title?, viewMetaData?, schema? })
+        //   appends an entry to localStorage. Schema defaults to the current
+        //   builder schema if not provided.
+        // openSessionLog / closeSessionLog control the review dialog.
+        logSchema,
+        openSessionLog,
+        closeSessionLog
       }}
     >
+      <UnsavedChangesGuard isDirty={isDirty} />
+      <SessionLogDialog open={sessionLogOpen} onClose={closeSessionLog} />
       {children}
     </BuilderContext.Provider>
   )

package/src/context/SystemContext.js

@@ -7,7 +7,7 @@ import axios from 'axios'
 
 // ** Config
 import {Endpoints, Services} from 'services/Endpoints'
-import {getBaseURL} from 'services/config'
+import {getBaseURL, getAccessToken} from 'services/config'
 import {useJsApiLoader} from '@react-google-maps/api'
 import {AuthContext} from './AuthContext'
 import handleChange from 'services/helper/handleChange'
@@ -44,7 +44,7 @@ const SystemProvider = ({children}) => {
   const auth = useContext(AuthContext)
   //
   useEffect(() => {
-    if (localStorage.getItem('accessToken') != null) {
+    if (getAccessToken() != null) {
       handleGetNavigationSettings()
       console.log(navigation)
     }

package/src/hooks/useGlobalStore.js

@@ -0,0 +1,36 @@
+import { useState, useEffect } from 'react'
+import { getGlobalData, setGlobalData, subscribeGlobal } from '../services/globalStore'
+
+/**
+ * React hook for consuming and updating the cross-route global store.
+ *
+ * Components that call this hook will re-render whenever any part of
+ * globalData changes (via setGlobalData from any Calculation, renderer,
+ * or component anywhere in the app).
+ *
+ * @returns {{ globalData: object, setGlobalData: (updater: object | Function) => void }}
+ *
+ * @example
+ *   function MyComponent() {
+ *     const { globalData, setGlobalData } = useGlobalStore()
+ *
+ *     return (
+ *       <div>
+ *         Selected: {globalData.selectedUser?.name}
+ *         <button onClick={() => setGlobalData({ selectedUser: null })}>Clear</button>
+ *       </div>
+ *     )
+ *   }
+ */
+export function useGlobalStore() {
+  const [state, setState] = useState(getGlobalData)
+
+  useEffect(() => {
+    // Sync with any changes that happened between render and effect
+    setState(getGlobalData())
+    // Subscribe for future updates
+    return subscribeGlobal(setState)
+  }, [])
+
+  return { globalData: state, setGlobalData }
+}

package/src/hooks/useTimerEngine.js

@@ -0,0 +1,54 @@
+import { useEffect, useRef } from 'react'
+import { executeJSCode } from 'services/builderHelper/jsExecutor'
+
+/**
+ * useTimerEngine
+ *
+ * Starts client-side timers (setInterval / setTimeout) for each enabled timer
+ * in the schema, executes their Calculation code via executeJSCode, and cleans
+ * up all handles when the component unmounts or the timer configuration changes.
+ *
+ * IMPORTANT — context is read through a ref, NOT a dep:
+ *   The effect only re-registers when `timers` config changes, not on every
+ *   render caused by data/form state updates. This prevents runaway re-mounts
+ *   while still ensuring each tick uses the freshest data/setData values.
+ *
+ * @param {object[]} timers     - schema.timers array
+ * @param {object}   context    - Execution context (data, setData, dataRef, …)
+ *                                Caller must update this object on every render.
+ */
+export function useTimerEngine({ timers, context }) {
+  // Always hold a ref to the latest context so timer callbacks see fresh state
+  // without adding context to the effect dependency array.
+  const contextRef = useRef(context)
+  useEffect(() => { contextRef.current = context }) // sync every render
+
+  useEffect(() => {
+    const active = (timers ?? []).filter(t => t.enabled && t.code?.trim())
+    if (!active.length) return
+
+    const cleanups = []
+
+    for (const timer of active) {
+      // Enforce a 1 s minimum to avoid accidental tight loops
+      const ms = Math.max(Number(timer.interval) || 5000, 1000)
+
+      const run = () => {
+        executeJSCode(timer.code, contextRef.current).catch(err =>
+          console.error(`[Timer "${timer.name ?? timer.id}"]`, err)
+        )
+      }
+
+      if (timer.type === 'interval') {
+        if (timer.runOnLoad) run()              // fire immediately if requested
+        const id = setInterval(run, ms)
+        cleanups.push(() => clearInterval(id))
+      } else if (timer.type === 'delay') {
+        const id = setTimeout(run, ms)
+        cleanups.push(() => clearTimeout(id))
+      }
+    }
+
+    return () => cleanups.forEach(fn => fn())
+  }, [timers]) // re-registers only when timer config (name/type/interval/code) changes
+}