robobyte-front-builder 1.0.24 → 1.0.26

package/INTEGRATION.md

@@ -173,6 +173,9 @@ function RoboByteBridge({ children }) {
       user={auth.user}
       accessToken={auth.accessToken}
       agGridLicenseKey={process.env.NEXT_PUBLIC_AG_GRID_LICENSE_KEY}
+      // Optional — Quartz theme overrides for every <AgGridReact> in the
+      // package. Merged on top of the package defaults.
+      // agGridTheme={{ accentColor: '#3b82f6', headerHeight: 32 }}
     >
       {children}
     </RoboByteFrontBuilderProvider>
@@ -200,11 +203,15 @@ export default function App({ Component, pageProps }) {
 | `user`             | object   | Current user object from your auth context |
 | `accessToken`      | string   | Bearer token — attached to every robobyte service call |
 | `agGridLicenseKey` | string   | AG Grid Enterprise license key. The provider calls `LicenseManager.setLicenseKey()` and registers `AllEnterpriseModule` + `IntegratedChartsModule.with(AgChartsEnterpriseModule)` internally. |
+| `agGridTheme`      | object   | Optional. Quartz theme overrides applied to every `<AgGridReact>` in the package. Merged on top of `DEFAULT_AG_THEME_PARAMS` (see [`src/lib/agGridTheme.js`](src/lib/agGridTheme.js)). Example: `{ accentColor: '#3b82f6', headerHeight: 32 }`. |
 | `navExtensions`    | array    | Static nav items to inject into the sidebar (optional) |
 | `endpoints`        | object   | Full-URL overrides per endpoint group + name (optional) |
 
 > **AG Grid note:** Do not call `LicenseManager` or `ModuleRegistry` in the
-> host app — the provider handles it entirely via `agGridLicenseKey`.
+> host app — the provider handles it entirely via `agGridLicenseKey`. The
+> theme is also handled internally — do not pass `theme={...}` to
+> individual `<AgGridReact>` instances rendered by the package; the
+> `agGridTheme` prop is the single source of truth.
 
 ---
 
@@ -308,17 +315,35 @@ Paths to stub out:
 Fetches report data by `pageId` without any AG Grid dependency. The canonical
 implementation lives in the package at `services/reportData/fetchReportData`.
 
-### Sourcing — always from the package
+For the full host-app reference (cancellation in `useEffect`, memoizing
+filters, paginated cursor hook, exporting to XLSX, all recipes and pitfalls),
+see **[`docs/fetchReportData.md`](docs/fetchReportData.md)**. The companion
+in-builder Calculation manual is **[`training/48-fetchReportData.md`](training/48-fetchReportData.md)**
+(the auto-injected `fetchReportData` symbol).
 
-The `packageOwnedServices` entry in `next.config.js` (§4) routes every import
-of `services/reportData/fetchReportData` — from any file, host or package — to
-the package's copy via `NormalModuleReplacementPlugin`. The host app's local
-copy (if any) should be emptied out and never executed.
+### Sourcing — both import paths work
 
-### Usage
+Since v1.0.23, the recommended import is the package surface:
+
+```js
+import { fetchReportDataByPageId } from 'robobyte-front-builder'
+```
+
+The legacy bare-alias path also still works and resolves to the same module
+via the `NormalModuleReplacementPlugin` rule:
 
 ```js
 import fetchReportDataByPageId from 'services/reportData/fetchReportData'
+```
+
+Both paths point to the same file, so the in-memory `builderModelCache` is
+shared. Pick the package import for new code — it doesn't depend on the
+webpack rule.
+
+### Usage
+
+```js
+import { fetchReportDataByPageId } from 'robobyte-front-builder'
 
 const result = await fetchReportDataByPageId({
   pageId,            // string | number — required
@@ -374,9 +399,18 @@ import { ReportViewer } from 'robobyte-front-builder'
   noHeader={true}
   filter={{ Tfilter: [...] }}
   height="400px"
+  title="Q1 Orders"            // toolbar title (left side)
+  caption="2026-01-01 → 2026-03-31"
 />
 ```
 
+For the complete host-app reference — every prop, the new `viewerActions` /
+`title` / `caption` / `debug` props, `setOutGridApi` for raw AG Grid API
+access, building filters from React state, master/detail patterns, dialog
+embedding, all pitfalls — see **[`docs/ReportViewer.md`](docs/ReportViewer.md)**.
+The schema-side AI manual for the same component is
+**[`training/35-reportViewer.md`](training/35-reportViewer.md)**.
+
 ### Props
 
 | Prop            | Type     | Description |
@@ -858,9 +892,9 @@ The print builder persists layouts via four REST endpoints. The host API must im
 
 The `value` field is the schema serialised with `JSON.stringify`. The print builder deserialises it with `JSON.parse` after fetching.
 
-### Step 3 — Trigger print from a view
+### Step 3 — Trigger print from a view (inside the builder)
 
-Inside any action code (button `onClick`, row action, etc.) in a UI Builder view:
+Inside any action code (button `onClick`, row action, viewer action, form `onSubmit`, etc.) in a UI Builder view:
 
 ```js
 openPrintLayout('your-layout-id', {
@@ -871,7 +905,57 @@ openPrintLayout('your-layout-id', {
 })
 ```
 
-`openPrintLayout` is injected into every action's execution scope automatically by `ProductionViewer`. No import is needed.
+`openPrintLayout` is injected into every action's execution scope automatically by `ProductionViewer`. No import is needed. The companion helper `closePrintLayout()` dismisses the dialog programmatically.
+
+For the full Calculation-scope reference (data shape, all trigger points, recipes for row actions / viewer actions / form submits, pitfalls), see **[`training/49-printLayout.md`](training/49-printLayout.md)**.
+
+### Step 3b — Trigger print from host-app code (outside the builder)
+
+When you need to print from regular host-app React code — a custom page, an action handler, a dialog, a hook, anywhere outside a builder Calculation — use the imperative `PrintDialog` API.
+
+The pattern, condensed:
+
+```jsx
+// host-app/pages/invoices.jsx (or any host React file)
+import { useRef } from 'react'
+import PrintDialog from 'views/builder/viewer/PrintDialog'  // bare-aliased import
+
+export default function InvoicesPage() {
+  const printDialogRef = useRef(null)
+
+  const viewerContext = {
+    printDialogRef,
+    data: {}, setData: () => {}, form: {}, setForm: () => {},
+    mode: 'preview', isEditMode: false, isPreviewMode: true, isPrintContext: true,
+  }
+
+  return (
+    <>
+      <Button
+        onClick={() => printDialogRef.current?.open('invoice-layout-id', {
+          invoiceNumber: 'INV-1042',
+          customerName:  'Acme Corp',
+          lines:         [{ sku: 'A', qty: 2 }],
+        })}
+      >
+        Print Invoice
+      </Button>
+
+      <PrintDialog viewerContext={viewerContext} />
+    </>
+  )
+}
+```
+
+Three things to know:
+
+1. **The `PrintDialog` import is bare-aliased.** Either add `views/builder/viewer/PrintDialog` to your `packageOwnedServices` array in `next.config.js` (next to the existing `services/reportData/fetchReportData` entry), or use the longer path `'robobyte-front-builder/src/views/builder/viewer/PrintDialog'`. Both resolve to the same file.
+
+2. **The dialog is mounted-but-hidden.** It registers itself on `printDialogRef.current` after first render and exposes `{ open(layoutId, data), openWithSchema(schema, data), close() }`.
+
+3. **For multi-page apps, prefer a `PrintProvider` pattern** — mount the dialog once at `_app.js` level and expose `usePrintLayout()` from a React context so every page gets `openPrintLayout(id, data)` without re-mounting. The full pattern is in **[`docs/printLayout.md`](docs/printLayout.md)**.
+
+For the complete host-app reference (the three mounting patterns, listing layouts, recipes for printing from a `<ReportViewer>` viewer action, all pitfalls), see **[`docs/printLayout.md`](docs/printLayout.md)**.
 
 ### Step 4 — Build the layout
 

package/README.md

@@ -17,27 +17,28 @@ A low-code **UI Builder**, **Report Builder**, **Print Layout Designer**, and **
 7. [Builder pages](#builder-pages)
 8. [Navigation Extension API](#navigation-extension-api)
 9. [Provider props reference](#provider-props-reference)
-10. [fetchReportDataByPageId](#fetchreportdatabypageid)
-11. [ReportViewer as a component](#reportviewer-as-a-component)
-12. [Data Grid component](#data-grid-component)
-13. [Dialog component](#dialog-component)
-14. [Popover component](#popover-component)
-15. [Excel Upload component](#excel-upload-component)
-16. [Wizard component](#wizard-component)
-17. [Repeater component](#repeater-component)
-18. [Menu component](#menu-component)
-19. [View Renderer component](#view-renderer-component)
-20. [Layout Grid component](#layout-grid-component)
-21. [Breadcrumb component](#breadcrumb-component)
-22. [Print Layout Builder](#print-layout-builder)
-23. [Calculation Scope Reference](#calculation-scope-reference)
-24. [KPI Component Actions](#kpi-component-actions)
-25. [Global Data Store](#global-data-store)
-26. [Dark / Light theme](#dark--light-theme)
-27. [Syncing local changes](#syncing-local-changes)
-28. [Troubleshooting](#troubleshooting)
-29. [Publishing](#publishing)
-30. [Changelog](#changelog)
+10. [AG Grid theme](#ag-grid-theme)
+11. [fetchReportDataByPageId](#fetchreportdatabypageid)
+12. [ReportViewer as a component](#reportviewer-as-a-component)
+13. [Data Grid component](#data-grid-component)
+14. [Dialog component](#dialog-component)
+15. [Popover component](#popover-component)
+16. [Excel Upload component](#excel-upload-component)
+17. [Wizard component](#wizard-component)
+18. [Repeater component](#repeater-component)
+19. [Menu component](#menu-component)
+20. [View Renderer component](#view-renderer-component)
+21. [Layout Grid component](#layout-grid-component)
+22. [Breadcrumb component](#breadcrumb-component)
+23. [Print Layout Builder](#print-layout-builder)
+24. [Calculation Scope Reference](#calculation-scope-reference)
+25. [KPI Component Actions](#kpi-component-actions)
+26. [Global Data Store](#global-data-store)
+27. [Dark / Light theme](#dark--light-theme)
+28. [Syncing local changes](#syncing-local-changes)
+29. [Troubleshooting](#troubleshooting)
+30. [Publishing](#publishing)
+31. [Changelog](#changelog)
 
 ---
 
@@ -171,6 +172,11 @@ function RoboByteBridge({ children }) {
       user={auth.user}
       accessToken={auth.accessToken}
       agGridLicenseKey={process.env.NEXT_PUBLIC_AG_GRID_LICENSE_KEY}
+      // Optional: Quartz theme overrides applied to every <AgGridReact>
+      // in the package. Merged on top of the package defaults — see the
+      // "AG Grid theme" section for the full list of params and the
+      // programmatic API. Omit to use the package defaults.
+      agGridTheme={{ accentColor: '#3b82f6' }}
     >
       {children}
     </RoboByteFrontBuilderProvider>
@@ -316,6 +322,7 @@ function MyFeaturePlugin() {
 | `user` | object | Current user object from your auth context |
 | `accessToken` | string | Bearer token attached to every service call |
 | `agGridLicenseKey` | string | AG Grid Enterprise license key — the provider calls `LicenseManager.setLicenseKey()` and registers all enterprise modules internally |
+| `agGridTheme` | object | Quartz theme overrides applied to every `<AgGridReact>` in the package. Merged on top of `DEFAULT_AG_THEME_PARAMS`. Example: `{ accentColor: '#3b82f6', headerHeight: 32 }`. See [AG Grid theme](#ag-grid-theme). |
 | `navExtensions` | array | Static nav items to inject into the sidebar |
 | `endpoints` | object | Full-URL overrides per endpoint group + name |
 
@@ -323,6 +330,58 @@ function MyFeaturePlugin() {
 
 ---
 
+## AG Grid theme
+
+Every `<AgGridReact>` in the package — `reportViewer`, `dataGrid`, the role-permission editor, the navigator picker — reads its theme from a single context. The default lives in code at [`src/lib/agGridTheme.js`](src/lib/agGridTheme.js) and can be overridden in two places:
+
+### 1. Host-app override via the provider
+
+Pass an object of Quartz params to `agGridTheme`. The object is merged on top of the package defaults — keys you set win, everything else falls back.
+
+```jsx
+<RoboByteFrontBuilderProvider
+  agGridTheme={{
+    accentColor:  '#3b82f6',
+    headerHeight: 32,
+    fontFamily:   'inherit',
+  }}
+  /* …other props… */
+>
+  <App />
+</RoboByteFrontBuilderProvider>
+```
+
+See the [AG Grid Quartz theming reference](https://www.ag-grid.com/react-data-grid/theming/) for the full list of params.
+
+### 2. Package-wide default
+
+Open [`src/lib/agGridTheme.js`](src/lib/agGridTheme.js) and edit `DEFAULT_AG_THEME_PARAMS`. Affects every consumer of `robobyte-front-builder` that doesn't supply its own `agGridTheme`.
+
+### Programmatic use
+
+```js
+import {
+  DEFAULT_AG_THEME_PARAMS,   // frozen params object
+  DEFAULT_AG_THEME,          // pre-built Quartz theme
+  buildAgGridTheme,          // (overrides) => Quartz theme
+  AgGridThemeProvider,       // standalone provider (no other dependencies)
+  useAgGridTheme,            // hook returning the resolved theme
+} from 'robobyte-front-builder'
+
+// In a host component that renders its own AG Grid:
+import { AgGridReact } from 'ag-grid-react'
+function MyGrid() {
+  const theme = useAgGridTheme()
+  return <AgGridReact theme={theme} columnDefs={[...]} />
+}
+```
+
+The hook falls back to `DEFAULT_AG_THEME` when called outside `RoboByteFrontBuilderProvider`, so isolated grids still render correctly.
+
+> **Future plan.** A "system settings" path will eventually layer between `DEFAULT_AG_THEME_PARAMS` and the host's `agGridTheme` prop, letting admins customize the theme without a code change. The provider API will stay the same.
+
+---
+
 ## `fetchReportDataByPageId`
 
 Fetches report data by `pageId` without any AG Grid dependency. Always imported from the package path — the `NormalModuleReplacementPlugin` in `next.config.js` routes it to the package's canonical implementation.
@@ -868,6 +927,9 @@ Hot-reload picks up all file changes automatically. Only `next.config.js` change
 **AG Grid error #200 — IntegratedChartsModule not registered**  
 → The provider registers `IntegratedChartsModule.with(AgChartsEnterpriseModule)` automatically. Ensure `ag-charts-enterprise` is installed in the package.
 
+**AG Grid theme override not applying**  
+→ Pass it via `<RoboByteFrontBuilderProvider agGridTheme={{ … }}>`, not as a `theme={…}` prop on individual `<AgGridReact>` instances rendered by the package. Internal grids ignore per-instance themes; the provider's context is the single source of truth. See the *AG Grid theme* section.
+
 **ReportViewer renders at half width**  
 → The outer `Box` in `reportViewer/index.js` must use `display: 'block'`, not `display: 'flex'`.
 
@@ -903,6 +965,15 @@ npm publish --dry-run
 
 ## Changelog
 
+### 1.0.25
+- **Centralized AG Grid theme.** Every `<AgGridReact>` in the package (`reportViewer`, `dataGrid`, role-permission editor, navigator picker) now reads its Quartz theme from a single context. Host apps can override package-wide theme params (accent color, header height, fonts, border radius, etc.) via the new `agGridTheme` prop on `RoboByteFrontBuilderProvider`. Defaults live in [`src/lib/agGridTheme.js`](src/lib/agGridTheme.js). New exports: `DEFAULT_AG_THEME_PARAMS`, `DEFAULT_AG_THEME`, `buildAgGridTheme`, `AgGridThemeProvider`, `useAgGridTheme`.
+- **`<ReportViewer>` redesigned toolbar.** Single-row toolbar: title + caption on the left; collapsible search, Filter (outlined button), Refresh (outlined button), and configurable viewer actions on the right. Auto-refresh interval, "Load all data" toggle, and Excel export moved into the side tool panel under *Display Settings*. Search popover navigable by keyboard (↑ ↓ Home End Enter Esc).
+- **`<ReportViewer>` new inspector fields.** `title`, `caption`, `viewerActions` (array of page-level action buttons appended after Filter/Refresh), `debug` (renders a floating bug icon with a popover showing resolved `pageId`/`id`/builder model id/etc. — hidden in production by default).
+- **Print Layout integration.** Host apps can now trigger print layouts directly via the imperative `PrintDialog` ref API — see [docs/printLayout.md](./docs/printLayout.md) for the recommended `PrintProvider` pattern with `usePrintLayout()`.
+- **Public exports expanded.** `fetchReportDataByPageId` now exported from the package surface (`import { fetchReportDataByPageId } from 'robobyte-front-builder'`); the legacy bare-alias path still works.
+- **Unsaved changes guard.** Builder pages now warn on tab close / refresh / in-app navigation when the schema has unsaved edits. `BuilderProvider` exposes `loadSchema(schema)` (clears history baseline), `markClean()` (post-save reset), and `isDirty`.
+- **Session log + AI fine-tune pipeline.** Every successful save (UI Builder + Print Builder) is auto-logged to localStorage with the full schema. New *Session Logs* toolbar dialog lets developers add training prompts to entries and export a Together AI-ready JSONL. Together is now a first-class AI provider in `/api/ai`.
+
 ### 1.0.21
 - Added Timer Engine — configurable auto-refresh timers per view
 - Added full Undo / Redo history with keyboard shortcuts (Ctrl+Z / Ctrl+Y)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robobyte-front-builder",
-  "version": "1.0.24",
+  "version": "1.0.26",
   "description": "RoboByte low-code UI builder, Report builder, and navigation extension system",
   "main": "src/lib/index.js",
   "files": [

package/src/lib/agGridTheme.js

@@ -0,0 +1,58 @@
+/**
+ * Centralized AG Grid theme configuration.
+ *
+ * Every <AgGridReact> in the package reads its theme from a single source —
+ * the React context provided by `AgGridThemeProvider` (wrapped automatically
+ * inside RoboByteFrontBuilderProvider). The default lives here, in code.
+ *
+ * Host apps can override theme params by passing `agGridTheme` to
+ * RoboByteFrontBuilderProvider:
+ *
+ *   <RoboByteFrontBuilderProvider
+ *     agGridTheme={{ accentColor: '#3b82f6', headerHeight: 32 }}
+ *     ...
+ *   />
+ *
+ * The override object is merged on top of DEFAULT_AG_THEME_PARAMS — host
+ * params win for the keys they set, and fall back to defaults otherwise.
+ *
+ * Future: this default will be replaced with a system-settings fetch so
+ * theme params can be tweaked at runtime without a code change. Until then,
+ * editing this file is the way to change the package-wide default.
+ */
+
+import { themeQuartz } from 'ag-grid-community'
+
+/**
+ * Default Quartz theme parameters used across the package.
+ * See https://www.ag-grid.com/react-data-grid/theming/ for the full list.
+ *
+ * Add new keys here as the package grows. Host apps can override any of
+ * them by passing `agGridTheme={{ <key>: <value> }}` to the provider.
+ */
+export const DEFAULT_AG_THEME_PARAMS = Object.freeze({
+  accentColor: '#FF1185',
+  // headerHeight: 28,
+  // rowHeight:    34,
+  // fontFamily:   'inherit',
+  // fontSize:     13,
+  // borderRadius: 4,
+})
+
+/**
+ * Build a Quartz theme from optional overrides. Returns a fresh theme object
+ * (Quartz themes are immutable). Safe to call on every render — `withParams`
+ * caches by params identity.
+ *
+ * @param {Object} [overrides] - Quartz theme params to merge over the defaults.
+ * @returns {object} A ready-to-use AG Grid theme.
+ */
+export function buildAgGridTheme(overrides) {
+  return themeQuartz.withParams({
+    ...DEFAULT_AG_THEME_PARAMS,
+    ...(overrides ?? {}),
+  })
+}
+
+/** Pre-built default theme — convenient when no override is in play. */
+export const DEFAULT_AG_THEME = buildAgGridTheme()

package/src/lib/agGridThemeContext.jsx

@@ -0,0 +1,42 @@
+/**
+ * AgGridThemeContext — single source of truth for the package-wide AG Grid
+ * theme. Wrapped automatically inside RoboByteFrontBuilderProvider.
+ *
+ * Consumers call `useAgGridTheme()` to get the resolved Quartz theme and pass
+ * it to <AgGridReact theme={agTheme} />.
+ */
+
+import { createContext, useContext, useMemo } from 'react'
+import { buildAgGridTheme, DEFAULT_AG_THEME } from './agGridTheme'
+
+const AgGridThemeContext = createContext(DEFAULT_AG_THEME)
+
+/**
+ * Wraps children with the AG Grid theme context.
+ *
+ * @param {Object} [params]  - Quartz theme overrides (merged over defaults).
+ * @param {ReactNode} children
+ */
+export function AgGridThemeProvider({ params, children }) {
+  // JSON.stringify on the params object is intentional — host apps that pass
+  // an inline object literal would otherwise rebuild the theme on every
+  // parent render. Stringify keys the memo by the actual params content.
+  const theme = useMemo(
+    () => buildAgGridTheme(params),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(params ?? null)]
+  )
+  return (
+    <AgGridThemeContext.Provider value={theme}>
+      {children}
+    </AgGridThemeContext.Provider>
+  )
+}
+
+/**
+ * Returns the live AG Grid theme. Falls back to the default theme when
+ * called outside RoboByteFrontBuilderProvider, so isolated grids still work.
+ */
+export function useAgGridTheme() {
+  return useContext(AgGridThemeContext)
+}

package/src/lib/index.js

@@ -106,3 +106,10 @@ export { AuthContext } from '../context/AuthContext'
 // — both resolve to the same module thanks to the NormalModuleReplacementPlugin
 // in next.config.js, so the in-memory builderModelCache is shared.
 export { default as fetchReportDataByPageId } from '../services/reportData/fetchReportData'
+
+// ── AG Grid theme ────────────────────────────────────────────────────────────
+// Default theme params (host can override via RoboByteFrontBuilderProvider's
+// `agGridTheme` prop), a builder function for ad-hoc themes, and the hook
+// every internal grid uses to read the live theme.
+export { DEFAULT_AG_THEME_PARAMS, buildAgGridTheme, DEFAULT_AG_THEME } from './agGridTheme'
+export { AgGridThemeProvider, useAgGridTheme } from './agGridThemeContext'

package/src/lib/providers/RoboByteFrontBuilderProvider.jsx

@@ -49,6 +49,7 @@ import { Toaster } from 'react-hot-toast'
 import { ModuleRegistry } from 'ag-grid-community'
 import { AllEnterpriseModule, LicenseManager } from 'ag-grid-enterprise'
 import { NavigationExtensionProvider } from '../navigation/NavigationExtensionContext'
+import { AgGridThemeProvider } from '../agGridThemeContext'
 import { configureRoboByte } from '../../services/config'
 import { AuthContext } from '../../context/AuthContext'
 import { setRouter } from '../../services/routerRef'
@@ -95,6 +96,17 @@ const RoboByteFrontBuilderProvider = ({
   navExtensions = [],
   endpoints = null,
   agGridLicenseKey = null,
+  /**
+   * Optional Quartz theme overrides applied to every <AgGridReact> in the
+   * package. Merged on top of DEFAULT_AG_THEME_PARAMS in `lib/agGridTheme.js`.
+   *
+   * Example:
+   *   agGridTheme={{ accentColor: '#3b82f6', headerHeight: 32 }}
+   *
+   * Future: this will accept a "load from system settings" mode. For now
+   * pass a plain params object.
+   */
+  agGridTheme = null,
   toasterProps = {},
 }) => {
   // Apply URL + endpoint config synchronously before any child renders.
@@ -121,6 +133,7 @@ const RoboByteFrontBuilderProvider = ({
   return (
     <AuthContext.Provider value={authValue}>
       <NavigationExtensionProvider items={navExtensions}>
+        <AgGridThemeProvider params={agGridTheme}>
         <RouterSync />
         {children}
         {/* Package-owned Toaster — same react-hot-toast instance used by all
@@ -157,6 +170,7 @@ const RoboByteFrontBuilderProvider = ({
           }}
           {...toasterProps}
         />
+        </AgGridThemeProvider>
       </NavigationExtensionProvider>
     </AuthContext.Provider>
   )

package/src/pages/reportModule/reportBuilder/reportViewer/index.js

@@ -1,5 +1,5 @@
 import React, {useEffect, useState} from 'react'
-import {Box, CircularProgress, Typography, Paper, IconButton, CardContent, Tooltip} from '@mui/material'
+import {Box, CircularProgress, Typography, Paper, IconButton, CardContent, Tooltip, Popover, Chip} from '@mui/material'
 import {useRouter} from 'next/router'
 import SGrid from 'views/genericTable/SGrid'
 import {Endpoints, Services} from 'services/Endpoints'
@@ -8,7 +8,7 @@ import CardHeader from "@mui/material/CardHeader";
 import Grid from "@mui/material/Grid";
 import {Plus} from "mdi-material-ui";
 import TAGGrid from "views/genericTable/TAGGrid";
-import {SettingsOutlined, AssessmentOutlined} from "@mui/icons-material";
+import {SettingsOutlined, AssessmentOutlined, BugReportOutlined, ContentCopyOutlined} from "@mui/icons-material";
 import UpdateReportPermissionDialog from "views/rolePermissions/UpdateReportPermissionDialog";
 import {getReportSession} from 'src/services/helper/reportSessionHelper'
 import BlankLayout from '../../../../lib/layouts/BlankLayout';
@@ -48,6 +48,12 @@ const ReportViewer = (params) => {
     // Page-level toolbar buttons rendered after Filter / Refresh.
     // Built by ReportViewerRenderer with bound onClick handlers.
     viewerActions,
+    // Debug — when truthy, renders a small floating BugReport icon at the
+    // top-right corner of the report area. Clicking it opens a popover
+    // showing the resolved ids (pageId, id, builderMetadata.id) and other
+    // useful runtime info. Hidden entirely when `debug` is falsy, so
+    // production builds incur zero cost.
+    debug,
     // nodeId / reportRefs are injected by the UI builder's ReportViewerRenderer.
     // nodeId    — the builder schema node ID for this ReportViewer instance
     // reportRefs — the shared registry { [nodeId]: updateRef } for all reports on the page
@@ -64,6 +70,8 @@ const ReportViewer = (params) => {
   const [builderMetadata, setBuilderMetadata] = useState(null)
   const [sessionPayload, setSessionPayload] = useState(null)
   const [payloadVersion, setPayloadVersion] = useState(0)
+  // Debug popover anchor — only used when `debug` prop is truthy.
+  const [debugAnchor, setDebugAnchor] = useState(null)
 
   useEffect(() => {
     // Prefer localStorage payload via sessionId (set by SGrid)
@@ -176,13 +184,137 @@ const ReportViewer = (params) => {
     setPayloadVersion(v => v + 1);
   }, [id, router.query?.id, pageId, router.query?.pageId, sessionPayload])
 
+  // ── Debug snapshot — gathered fresh on every render so the popover always
+  //    reflects the current resolved state. Cheap to build (just reads
+  //    existing state / props) so no memo needed.
+  const resolvedPageId = pageId ?? sessionPayload?.pageId ?? router.query?.pageId
+  const resolvedId     = id     ?? sessionPayload?.id     ?? router.query?.id
+  const debugFields = debug ? [
+    { label: 'pageId',           value: resolvedPageId },
+    { label: 'id (prop)',        value: resolvedId },
+    { label: 'builder model id', value: builderModel?.id },
+    { label: 'report name',      value: builderMetadata?.name },
+    { label: 'nodeId',           value: nodeId },
+    { label: 'sessionId',        value: sessionId },
+    { label: 'payload version',  value: payloadVersion },
+    { label: 'session payload',  value: sessionPayload ? '✓ loaded' : '—' },
+    { label: 'isSingle',         value: String(Boolean(isSingle)) },
+    { label: 'dataAsObject',     value: String(Boolean(dataAsObject)) },
+    { label: 'isRerender',       value: String(Boolean(isRerender)) },
+    { label: 'externalTimer',    value: externalTimer ?? '—' },
+    { label: 'height',           value: height ?? '85vh' },
+    { label: 'globalParams',     value: globalParams ? JSON.stringify(globalParams) : '—' },
+  ] : []
+
+  const copyToClipboard = (value) => {
+    if (value == null) return
+    try { navigator.clipboard?.writeText(String(value)) } catch (_) {}
+  }
+
   return (
     <Box
       sx={{
         display: 'block',
         width: '100%',
+        position: 'relative',
       }}
     >
+      {/* ── Debug floater ────────────────────────────────────────────────────
+          Renders only when the `debug` prop is truthy. A small icon button at
+          the top-right corner that opens a key/value popover. Useful when a
+          report appears broken — confirm pageId/id resolved correctly, the
+          builder model loaded, the right sessionPayload was picked, etc. */}
+      {debug && (
+        <>
+          <Tooltip title='Report debug info' placement='left'>
+            <IconButton
+              size='small'
+              onClick={(e) => setDebugAnchor(e.currentTarget)}
+              sx={{
+                position: 'absolute',
+                top: 4,
+                insetInlineEnd: 4,
+                zIndex: 10,
+                bgcolor: 'warning.light',
+                color: 'warning.contrastText',
+                opacity: 0.9,
+                '&:hover': { bgcolor: 'warning.main', opacity: 1 },
+                boxShadow: 1,
+              }}
+            >
+              <BugReportOutlined fontSize='small' />
+            </IconButton>
+          </Tooltip>
+
+          <Popover
+            open={Boolean(debugAnchor)}
+            anchorEl={debugAnchor}
+            onClose={() => setDebugAnchor(null)}
+            anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+            transformOrigin={{ vertical: 'top', horizontal: 'right' }}
+            PaperProps={{ sx: { p: 0, minWidth: 320, maxWidth: 480 } }}
+          >
+            <Box sx={{ px: 2, py: 1, bgcolor: 'warning.light', display: 'flex', alignItems: 'center', gap: 1 }}>
+              <BugReportOutlined fontSize='small' sx={{ color: 'warning.contrastText' }} />
+              <Typography variant='subtitle2' sx={{ color: 'warning.contrastText', fontWeight: 700, flex: 1 }}>
+                Report Debug
+              </Typography>
+              <Chip
+                size='small'
+                label={isLoading ? 'loading' : builderModel ? 'ready' : 'idle'}
+                color={isLoading ? 'info' : builderModel ? 'success' : 'default'}
+                sx={{ height: 18, fontSize: 10 }}
+              />
+            </Box>
+            <Box sx={{ p: 1.5, display: 'flex', flexDirection: 'column', gap: 0.5 }}>
+              {debugFields.map(({ label, value }) => (
+                <Box
+                  key={label}
+                  sx={{
+                    display: 'grid',
+                    gridTemplateColumns: '130px 1fr auto',
+                    alignItems: 'center',
+                    gap: 1,
+                    px: 1,
+                    py: 0.5,
+                    borderRadius: 0.5,
+                    '&:hover': { bgcolor: 'action.hover' },
+                  }}
+                >
+                  <Typography variant='caption' sx={{ color: 'text.secondary', fontFamily: 'monospace' }}>
+                    {label}
+                  </Typography>
+                  <Typography
+                    variant='body2'
+                    sx={{
+                      fontFamily: 'monospace',
+                      fontSize: 12,
+                      color: value == null || value === '—' ? 'text.disabled' : 'text.primary',
+                      overflow: 'hidden',
+                      textOverflow: 'ellipsis',
+                      whiteSpace: 'nowrap',
+                    }}
+                    title={String(value ?? '')}
+                  >
+                    {value ?? '—'}
+                  </Typography>
+                  <Tooltip title='Copy' placement='left'>
+                    <IconButton
+                      size='small'
+                      onClick={() => copyToClipboard(value)}
+                      disabled={value == null || value === '—'}
+                      sx={{ p: 0.25 }}
+                    >
+                      <ContentCopyOutlined sx={{ fontSize: 13 }} />
+                    </IconButton>
+                  </Tooltip>
+                </Box>
+              ))}
+            </Box>
+          </Popover>
+        </>
+      )}
+
       {isLoading ? (
         <Box
           sx={{

package/src/views/builder/inspector/definitions/reportViewer/main.js

@@ -9,6 +9,11 @@ export const REPORT_VIEWER_MAIN_FIELDS = [
   { name: 'title',   label: 'Title',   type: 'expression' },
   { name: 'caption', label: 'Caption', type: 'expression' },
 
+  // Debug — when true, a small BugReport icon appears at the report's
+  // top-right corner; clicking it opens a popover listing the resolved
+  // pageId / id / builder model id / sessionId / and other runtime info.
+  // Hidden entirely when false / unset — zero cost in production schemas.
+  { name: 'debug', label: 'Debug', type: 'boolean' },
   { name: 'minimized', label: 'Minimized', type: 'boolean' },
   { name: 'isRerender', label: 'Is Rerender', type: 'boolean' },
   { name: 'height', label: 'Height', type: 'expression' },

package/src/views/builder/viewer/renderers/DataGridRenderer.jsx

@@ -1,7 +1,6 @@
 import { Box, Button, IconButton, Tooltip, Typography } from '@mui/material'
 import { useRef, useMemo, useCallback, useEffect } from 'react'
 import { AgGridReact } from 'ag-grid-react'
-import { themeQuartz } from 'ag-grid-community'
 import { AddOutlined, DeleteOutlined, TableChartOutlined } from '@mui/icons-material'
 import ViewerComponentWrapper from '../ViewerComponentWrapper'
 import RowActionsCell from './RowActionsCell'
@@ -9,9 +8,7 @@ import { resolveProps } from 'services/builderHelper/resolveProps'
 import { executeJSCode } from 'services/builderHelper/jsExecutor'
 import { processColumnDefinitions, processColumnsConfig } from 'views/genericTable/convertStringFunctions'
 import { AG_COMPONENTS } from './dataGridComponents'
-
-// ── Shared AG Grid theme (same as SGrid) ──────────────────────────────────────
-const agTheme = themeQuartz.withParams({ accentColor: '#FF1185' })
+import { useAgGridTheme } from 'src/lib/agGridThemeContext'
 
 // ── Delete-column cell renderer ───────────────────────────────────────────────
 // Defined at module level so AG Grid never receives a new component reference.
@@ -49,6 +46,9 @@ export default function DataGridRenderer({ node, viewerContext }) {
     form, data, setData, dataRef, reportRefs, openDialog, closeDialog, isEditMode,
   } = viewerContext
 
+  // Centralized AG Grid theme — see lib/agGridTheme.js / RoboByteFrontBuilderProvider.
+  const agTheme = useAgGridTheme()
+
   const main = resolveProps(node, 'main', viewerContext)
 
   const {

package/src/views/genericTable/SGrid.js

@@ -115,7 +115,7 @@ import numeral from 'numeral'
 import CustomFilterDialog from "views/customFilter/CustomFilterDialog";
 import CustomStatusBar from "views/genericTable/statusBar/rowCountStatusBar";
 import StreamService from "services/StreamService";
-import {themeQuartz} from 'ag-grid-community';
+import { useAgGridTheme } from 'src/lib/agGridThemeContext'
 import {ReportBuilderEndpoints} from "services/Endpoints/ReportBuilderEndpoints";
 import {debounce} from "lodash";
 import jsPDF from "jspdf";
@@ -330,10 +330,10 @@ const SGrid = props => {
   // ** State
   const appContext = useContext(SystemContext);
   const imageBaseUrl = appContext?.settings?.imagesStorageServer;
-  const agTheme = themeQuartz
-    .withParams({
-      accentColor: "#FF1185"
-    });
+  // Theme comes from RoboByteFrontBuilderProvider's agGridTheme prop, merged
+  // with DEFAULT_AG_THEME_PARAMS in lib/agGridTheme.js. Falls back to the
+  // bare default when used outside the provider.
+  const agTheme = useAgGridTheme()
 
   const {
     externalTimer,

package/src/views/genericTable/TAGGrid.js

@@ -37,7 +37,7 @@ import numeral from 'numeral'
 import CustomFilterDialog from "views/customFilter/CustomFilterDialog";
 import CustomStatusBar from "views/genericTable/statusBar/rowCountStatusBar";
 import StreamService from "services/StreamService";
-import {themeQuartz} from 'ag-grid-community';
+import { useAgGridTheme } from 'src/lib/agGridThemeContext'
 
 // ** Utils Import
 
@@ -52,10 +52,8 @@ const defaultFinalRequest = {
 }
 const TAGGrid = props => {
   // ** State
-  const agTheme = themeQuartz
-    .withParams({
-      accentColor: "#FF1185"
-    });
+  // Theme comes from RoboByteFrontBuilderProvider's agGridTheme prop.
+  const agTheme = useAgGridTheme()
   const {
     groupEndPoint,
     streamEndPoint,

package/src/views/rolePermissions/UpdateReportPermissionDialog.js

@@ -21,8 +21,11 @@ import {Endpoints, Services} from 'src/services/Endpoints'
 import {toast} from 'react-hot-toast'
 import {AgGridReact} from "ag-grid-react";
 import {AutocompleteEditorWrapper} from "views/genericTable/cellEditors/autocompleteEditor";
+import { useAgGridTheme } from 'src/lib/agGridThemeContext'
 
 const UpdateReportPermissionsDialog = props => {
+  // Centralized AG Grid theme.
+  const agTheme = useAgGridTheme()
   // ** Props
   const {handleToggleDialogs, report, dialog, setRefresh} = props
   const [IsSubmitting, setIsSubmitting] = useState(false)
@@ -266,6 +269,7 @@ const UpdateReportPermissionsDialog = props => {
           <Grid container size={{ xs: 12 }}>
             <div style={{width: "100%", height: "40vh", direction: 'ltr'}}>
               <AgGridReact
+                theme={agTheme}
                 enableRtl={true}
                 columnDefs={colDefs}
                 rowData={ReportPermissions}