ui-soxo-bootstrap-core 2.6.32-dev.6 → 2.6.32-dev.8

package/.github/workflows/npm-publish.yml

@@ -1,59 +1,40 @@
-name: Node.js Package
-
-on:
-  release:
-    types: [created]
-
-jobs:
-  publish-npm:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
-      - run: npm install -g npm@latest
-      - run: npm install
-
-      - name: Determine npm dist-tag
-        id: dist_tag
-        shell: bash
-        run: |
-          VERSION=$(node -p "require('./package.json').version")
-          echo "package.json version: $VERSION"
-          echo "release tag:          ${GITHUB_REF_NAME}"
-          if [[ "v${VERSION}" != "${GITHUB_REF_NAME}" ]]; then
-            echo "::error::Release tag '${GITHUB_REF_NAME}' does not match package.json version 'v${VERSION}'."
-            echo "::error::Bump the version with 'npm version' and re-create the release."
-            exit 1
-          fi
-          if [[ "$VERSION" == *-dev* ]]; then
-            echo "tag=dev" >> "$GITHUB_OUTPUT"
-            echo "Will publish with dist-tag: dev"
-          else
-            echo "tag=latest" >> "$GITHUB_OUTPUT"
-            echo "Will publish with dist-tag: latest"
-          fi
-
-      - name: Diagnose npm + OIDC environment
-        shell: bash
-        run: |
-          echo "--- versions ---"
-          node --version
-          npm --version
-          echo "--- OIDC env presence (must both be 'yes' for trusted publishing) ---"
-          echo "ACTIONS_ID_TOKEN_REQUEST_URL set:   ${ACTIONS_ID_TOKEN_REQUEST_URL:+yes}"
-          echo "ACTIONS_ID_TOKEN_REQUEST_TOKEN set: ${ACTIONS_ID_TOKEN_REQUEST_TOKEN:+yes}"
-          echo "--- effective .npmrc (user) ---"
-          cat ~/.npmrc 2>/dev/null || echo "(none)"
-          echo "--- effective .npmrc (project) ---"
-          cat .npmrc 2>/dev/null || echo "(none)"
-          echo "--- npm config (auth-related) ---"
-          npm config get registry
-          npm config get //registry.npmjs.org/:_authToken || true
-
-      - run: npm publish --provenance --access public --tag ${{ steps.dist_tag.outputs.tag }} --loglevel=verbose
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm install
+
+      - name: Determine npm dist-tag
+        id: dist_tag
+        shell: bash
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          echo "package.json version: $VERSION"
+          echo "release tag:          ${GITHUB_REF_NAME}"
+          if [[ "v${VERSION}" != "${GITHUB_REF_NAME}" ]]; then
+            echo "::error::Release tag '${GITHUB_REF_NAME}' does not match package.json version 'v${VERSION}'."
+            echo "::error::Bump the version with 'npm version' and re-create the release."
+            exit 1
+          fi
+          if [[ "$VERSION" == *-dev* ]]; then
+            echo "tag=dev" >> "$GITHUB_OUTPUT"
+            echo "Will publish with dist-tag: dev"
+          else
+            echo "tag=latest" >> "$GITHUB_OUTPUT"
+            echo "Will publish with dist-tag: latest"
+          fi
+
+      - run: npm publish --access public --tag ${{ steps.dist_tag.outputs.tag }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/DEVELOPER_GUIDE.md

@@ -17,7 +17,7 @@ Incorrect versioning or incorrect tags will break the publish pipeline — follo
 - Publishing via GitHub Release UI
 - How GitHub Action Detects Release Type
 - Summary Table
-- CI/CD Authentication (Trusted Publishing)
+- CI/CD Authentication (Granular Access Token)
 - Common Mistakes & Fixes
 
 ---
@@ -258,10 +258,10 @@ npm publish --tag dev
 
 The workflow reads the `version` field from `package.json` at publish time:
 
-| Condition                    | Command                                                 | Result                             |
-| ---------------------------- | ------------------------------------------------------- | ---------------------------------- |
-| Version contains `-dev`      | `npm publish --provenance --access public --tag dev`    | Publishes to the `dev` dist-tag    |
-| Version has no `-dev` suffix | `npm publish --provenance --access public --tag latest` | Publishes to the `latest` dist-tag |
+| Condition                    | Command                                    | Result                             |
+| ---------------------------- | ------------------------------------------ | ---------------------------------- |
+| Version contains `-dev`      | `npm publish --access public --tag dev`    | Publishes to the `dev` dist-tag    |
+| Version has no `-dev` suffix | `npm publish --access public --tag latest` | Publishes to the `latest` dist-tag |
 
 The workflow also enforces that the GitHub release tag matches `v<version>` from `package.json` and fails the run immediately if they diverge — this prevents the most common publish failure described below.
 
@@ -281,9 +281,9 @@ The workflow also enforces that the GitHub release tag matches `v<version>` from
 
 ---
 
-# 🔐 CI/CD Authentication (Trusted Publishing)
+# 🔐 CI/CD Authentication (Granular Access Token)
 
-As of npm's 2025 policy changes, classic automation tokens (`NPM_TOKEN`) are deprecated. This repo now authenticates to npm via **OIDC Trusted Publishing** — GitHub Actions exchanges a short-lived OIDC token for a publish token at run time, so **no secret is stored in the repository**.
+As of npm's 2025 policy changes, **classic automation tokens** (`npm_xxx` legacy tokens) are deprecated. This repo authenticates to npm using a **Granular Access Token (GAT)** — npm's current recommended token type for CI/CD. The token is stored as a GitHub repository secret named `NPM_TOKEN`.
 
 ## What this means for developers
 
@@ -291,24 +291,34 @@ Nothing. You still follow the same flow: `npm version` → push tag → create G
 
 ## What this means for maintainers
 
-The first-time setup on npmjs.com must be done once per package:
+The first-time setup must be done once per package:
 
-1. Log in to [npmjs.com](https://www.npmjs.com) → open the package (`ui-soxo-bootstrap-core`) → **Settings**.
-2. Under **Trusted Publisher**, click **Add trusted publisher** and fill in:
-   - Publisher: **GitHub Actions**
-   - Organization or user: `soxo-tech`
-   - Repository: `bootstrap-core`
-   - Workflow filename: `npm-publish.yml`
-   - Environment name: *(leave blank)*
-3. Save. Any old `NPM_TOKEN` repository secret can be removed.
+1. Log in to [npmjs.com](https://www.npmjs.com) as a user with publish rights to `ui-soxo-bootstrap-core`.
+2. Top-right avatar → **Access Tokens** → **Generate New Token** → **Granular Access Token**.
+3. Configure the token:
+   - **Name**: `ui-soxo-bootstrap-core CI publish`
+   - **Expiration**: 1 year (set a calendar reminder to rotate)
+   - **Packages and scopes**: Select **Only select packages and scopes** → choose `ui-soxo-bootstrap-core` → permission **Read and write**
+   - **IP allowlist**: leave blank (GitHub Actions runner IPs rotate)
+4. Generate and **copy the token immediately** — npm only shows it once.
+5. In GitHub: repo **Settings** → **Secrets and variables** → **Actions** → **New repository secret**:
+   - Name: `NPM_TOKEN`
+   - Secret: paste the token from step 4
+
+When the token expires, repeat steps 2–5 and replace the `NPM_TOKEN` secret.
 
 ## Runtime requirements
 
-The workflow runs on Node 20 and upgrades npm to the latest CLI (`npm install -g npm@latest`) because OIDC trusted publishing requires **npm ≥ 11.5.1**. The `--provenance` flag attaches a verifiable build attestation to every published version, visible on the npmjs.com package page.
+The workflow runs on Node 20. The token is passed to `npm publish` via the `NODE_AUTH_TOKEN` environment variable, which `actions/setup-node` wires into `~/.npmrc` automatically when `registry-url` is set.
 
-## If publish fails with `403 Forbidden` or `ENEEDAUTH`
+## If publish fails
 
-The trusted publisher config on npmjs.com no longer matches the workflow. Check that org, repo, and workflow filename match exactly — including case.
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `404 Not Found - PUT https://registry.npmjs.org/...` with no auth-related notices | `NPM_TOKEN` secret is missing, expired, or revoked | Re-create the GAT (steps 2–5) and re-publish |
+| `403 Forbidden` | The GAT exists but doesn't have write access to this package | Recreate the token with **Read and write** on `ui-soxo-bootstrap-core` |
+| `EOTP` / `ENEEDOTP` | The npm user enforces 2FA on writes and the token isn't allowed to bypass it | Recreate as a GAT (GATs bypass 2FA for their selected packages by design) |
+| `Tag does not match package.json version` (workflow error) | Release tag and `package.json` version diverge | Always bump with `npm version` — never tag manually |
 
 ---
 

package/core/lib/components/global-header/global-header.js

@@ -79,6 +79,7 @@ function GlobalHeaderContent({ loading, appSettings, children, isConnected, hist
   }, []);
   useEffect(() => {}, [state.theme]);
   return (
+    <>
     <div
       className={`global-header ${process.env.REACT_APP_THEME}  ${isConnected && !kiosk ? 'connected' : ''}`}
       style={{
@@ -236,7 +237,8 @@ function GlobalHeaderContent({ loading, appSettings, children, isConnected, hist
         </div>
         {/* Right Section of the Component Loader Ends */}
       </div>
-      {licAlert && licenseData && (
+    </div>
+     {licAlert && licenseData && (
         <div
           style={{
             top: 0,
@@ -249,7 +251,7 @@ function GlobalHeaderContent({ loading, appSettings, children, isConnected, hist
           <LicenseAlert data={licenseData} />
         </div>
       )}
-    </div>
+   </>
   );
 }
 export default function GlobalHeader(props) {

package/core/modules/steps/narration.js

@@ -0,0 +1,192 @@
+/**
+ * Narration helpers for ProcessStepsPage.
+ *
+ * Owns the per-step "guest guide" copy plus the credential lookup, audio
+ * decoding, and seed-based content picking used by the TTS providers. The
+ * step component imports from here so that file can stay focused on
+ * component lifecycle and layout.
+ */
+
+const STEP_WELCOME_LINES = [
+  'Welcome to your AI Automated Consultation process.',
+  'You are in the right place for a smooth and guided health journey.',
+  'This experience is designed to keep your consultation easy and stress-free.',
+];
+
+const STEP_INTRO_LINES = [
+  'In this process, we will walk you through a seamless and friendly AI interaction experience.',
+  'Each step is simple, guided, and focused on helping you feel prepared.',
+  'We will guide you through each stage so you always know what happens next.',
+];
+
+const STEP_EXPECTATION_LINES = [
+  'A care specialist may ask quick clarification questions to ensure your details are accurate.',
+  'This step focuses on collecting clear inputs so the care team can support you faster.',
+  'You can expect a guided workflow with minimal waiting and clear instructions.',
+  'The goal in this step is to keep your consultation organized and easy to follow.',
+];
+
+const STEP_COMFORT_LINES = [
+  'Take your time. There is no rush and assistance is always available nearby.',
+  'If anything feels unclear, the next prompt will guide you before you continue.',
+  'You can pause and review information before moving to the next stage.',
+  'Your responses here help personalize the rest of your consultation flow.',
+];
+
+const STEP_TIP_LINES = [
+  'Tip: Keep your previous reports or test details ready for quicker progress.',
+  'Tip: Follow on-screen prompts one at a time for the smoothest experience.',
+  'Tip: If you are unsure about a question, answer what you know and continue.',
+  'Tip: Stay relaxed; this process is built to be simple and patient-friendly.',
+];
+
+function getFromStorage(storageKey) {
+  if (typeof window === 'undefined' || !window.localStorage) {
+    return null;
+  }
+
+  try {
+    return window.localStorage.getItem(storageKey);
+  } catch (error) {
+    return null;
+  }
+}
+
+export function getElevenLabsApiKey() {
+  return (
+    process.env.ELEVEN_LABS_KEY ||
+    process.env.ELEVENLABS_API_KEY ||
+    process.env.REACT_APP_ELEVEN_LABS_KEY ||
+    process.env.REACT_APP_ELEVENLABS_API_KEY ||
+    getFromStorage('eleven_labs_key') ||
+    getFromStorage('elevenlabs_api_key') ||
+    getFromStorage('ELEVEN_LABS_KEY') ||
+    getFromStorage('REACT_APP_ELEVEN_LABS_KEY') ||
+    getFromStorage('REACT_APP_ELEVENLABS_API_KEY')
+  );
+}
+
+export function getGeminiApiKey() {
+  return (
+    process.env.GEMINI_API_KEY ||
+    process.env.REACT_APP_GEMINI_API_KEY ||
+    getFromStorage('gemini_api_key') ||
+    getFromStorage('GEMINI_API_KEY') ||
+    getFromStorage('REACT_APP_GEMINI_API_KEY')
+  );
+}
+
+export function getOpenAIApiKey() {
+  return (
+    process.env.OPEN_AI_KEY ||
+    process.env.OPENAI_API_KEY ||
+    process.env.REACT_APP_OPEN_AI_KEY ||
+    process.env.REACT_APP_OPENAI_API_KEY ||
+    getFromStorage('open_ai_key') ||
+    getFromStorage('openai_api_key') ||
+    getFromStorage('OPEN_AI_KEY') ||
+    getFromStorage('OPENAI_API_KEY') ||
+    getFromStorage('REACT_APP_OPEN_AI_KEY') ||
+    getFromStorage('REACT_APP_OPENAI_API_KEY')
+  );
+}
+
+export function getSarvamApiKey() {
+  return (
+    process.env.SARVAM_API_KEY ||
+    process.env.REACT_APP_SARVAM_API_KEY ||
+    getFromStorage('sarvam_api_key') ||
+    getFromStorage('REACT_APP_SARVAM_API_KEY')
+  );
+}
+
+export function base64AudioToBlob(base64Audio = '', mimeType = 'audio/wav') {
+  const cleanedBase64 = base64Audio.includes(',') ? base64Audio.split(',').pop() : base64Audio;
+  const binaryString = typeof window !== 'undefined' && window.atob ? window.atob(cleanedBase64) : atob(cleanedBase64);
+  const bytes = new Uint8Array(binaryString.length);
+
+  for (let index = 0; index < binaryString.length; index += 1) {
+    bytes[index] = binaryString.charCodeAt(index);
+  }
+
+  return new Blob([bytes], { type: mimeType });
+}
+
+export function extractGeminiAudio(payload) {
+  const candidates = payload && payload.candidates ? payload.candidates : [];
+
+  for (const candidate of candidates) {
+    const parts = candidate && candidate.content && candidate.content.parts ? candidate.content.parts : [];
+
+    for (const part of parts) {
+      const inlineData = part.inlineData || part.inline_data || part.audio;
+
+      if (inlineData && inlineData.data) {
+        return {
+          mimeType: inlineData.mimeType || inlineData.mime_type || 'audio/wav',
+          data: inlineData.data,
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+function hashText(value = '') {
+  let hash = 0;
+
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash << 5) - hash + value.charCodeAt(index);
+    hash |= 0;
+  }
+
+  return Math.abs(hash);
+}
+
+function pickBySeed(items = [], seed = 0) {
+  if (!items.length) {
+    return '';
+  }
+
+  return items[seed % items.length];
+}
+
+export function buildGuestStepGuide(step, index, total) {
+  if (!step) {
+    return {
+      welcome: STEP_WELCOME_LINES[0],
+      intro: STEP_INTRO_LINES[0],
+      expectation: 'We are preparing your consultation journey.',
+      comfort: STEP_COMFORT_LINES[0],
+      tip: STEP_TIP_LINES[0],
+      narration: '',
+    };
+  }
+
+  const stepName = step.step_name || `Step ${index + 1}`;
+  const seedSource = `${step.step_id || step.id || index}-${stepName}`;
+  const seed = hashText(seedSource);
+
+  const welcome = index === 0 ? STEP_WELCOME_LINES[0] : `Now entering ${stepName}.`;
+  const intro = index === 0 ? STEP_INTRO_LINES[0] : pickBySeed(STEP_INTRO_LINES, seed + 1);
+  const expectation = step.step_description || pickBySeed(STEP_EXPECTATION_LINES, seed + 2);
+  const comfort = pickBySeed(STEP_COMFORT_LINES, seed + 3);
+  const tip = pickBySeed(STEP_TIP_LINES, seed + 4);
+
+  return {
+    welcome,
+    intro,
+    expectation,
+    comfort,
+    tip,
+    narration: [
+      `Step ${index + 1} of ${total}. ${stepName}.`,
+      welcome,
+      intro,
+      `What to expect: ${expectation}`,
+      `Comfort note: ${comfort}`,
+      `Helpful tip: ${tip}`,
+    ].join(' '),
+  };
+}

package/core/modules/steps/progress-storage.js

@@ -0,0 +1,140 @@
+/**
+ * Per-guest progress persistence helpers for ProcessStepsPage.
+ *
+ * Storage shape:
+ *   key   = `processTimings_<processId>_<guestRef>` or
+ *           `processActiveStep_<processId>_<guestRef>`
+ *   value = `{ savedAt: <ms>, value: { guestRef, ... } }`
+ *
+ * The key scopes by guest AND the inner value carries the guest reference,
+ * so reads can reject any entry that does not belong to the current guest —
+ * guest A's progress can never be applied to guest B even if a key collision
+ * somehow occurred.
+ *
+ * The TTL covers a working shift: a guest who walks away in the morning is
+ * not coming back the same evening to resume. The sweep on mount drops any
+ * entry past the TTL or stored in the legacy unwrapped shape.
+ */
+
+export const PROGRESS_STORAGE_TTL_MS = 12 * 60 * 60 * 1000;
+export const PROGRESS_STORAGE_PREFIXES = ['processTimings_', 'processActiveStep_'];
+
+function hasLocalStorage() {
+  return typeof window !== 'undefined' && !!window.localStorage;
+}
+
+/**
+ * Drop progress keys that are past their TTL or stored in the legacy shape
+ * (which has no `savedAt` and therefore an unknowable age). Safe to call
+ * during mount and again after a quota error to free room for a retry.
+ */
+export function sweepStaleProgressKeys() {
+  if (!hasLocalStorage()) {
+    return;
+  }
+
+  try {
+    const cutoff = Date.now() - PROGRESS_STORAGE_TTL_MS;
+    const toRemove = [];
+
+    for (let index = 0; index < window.localStorage.length; index += 1) {
+      const key = window.localStorage.key(index);
+      if (!key) {
+        continue;
+      }
+      if (!PROGRESS_STORAGE_PREFIXES.some((prefix) => key.startsWith(prefix))) {
+        continue;
+      }
+
+      try {
+        const raw = window.localStorage.getItem(key);
+        if (!raw) {
+          continue;
+        }
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || typeof parsed.savedAt !== 'number' || parsed.savedAt < cutoff) {
+          toRemove.push(key);
+        }
+      } catch (parseError) {
+        toRemove.push(key);
+      }
+    }
+
+    toRemove.forEach((key) => window.localStorage.removeItem(key));
+  } catch (error) {
+    console.warn('Unable to sweep stale progress keys from local storage.', error);
+  }
+}
+
+/**
+ * Read a stored progress entry. Returns the unwrapped inner `value` only
+ * when the entry is present, well-formed, and within TTL; otherwise returns
+ * `null` and removes the bad key as a side effect.
+ *
+ * Callers must additionally verify `value.guestRef === currentGuestRef`
+ * before applying the result — the helper does not know the current guest.
+ */
+export function readProgressEntry(key) {
+  if (!hasLocalStorage()) {
+    return null;
+  }
+
+  try {
+    const raw = window.localStorage.getItem(key);
+    if (!raw) {
+      return null;
+    }
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.savedAt !== 'number') {
+      window.localStorage.removeItem(key);
+      return null;
+    }
+    if (Date.now() - parsed.savedAt > PROGRESS_STORAGE_TTL_MS) {
+      window.localStorage.removeItem(key);
+      return null;
+    }
+    return parsed.value;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Write a stored progress entry with the current timestamp. On
+ * `QuotaExceededError`, sweep stale keys once and retry — that keeps the
+ * write path resilient on long-running kiosks without surfacing the error
+ * to the user.
+ */
+export function writeProgressEntry(key, value) {
+  if (!hasLocalStorage()) {
+    return;
+  }
+
+  const payload = JSON.stringify({ savedAt: Date.now(), value });
+
+  try {
+    window.localStorage.setItem(key, payload);
+  } catch (error) {
+    sweepStaleProgressKeys();
+    try {
+      window.localStorage.setItem(key, payload);
+    } catch (retryError) {
+      console.warn('Unable to persist progress to local storage.', retryError);
+    }
+  }
+}
+
+/**
+ * Remove a progress entry. Safe to call when the entry does not exist.
+ */
+export function clearProgressEntry(key) {
+  if (!hasLocalStorage()) {
+    return;
+  }
+
+  try {
+    window.localStorage.removeItem(key);
+  } catch (error) {
+    console.warn('Unable to clear progress entry from local storage.', error);
+  }
+}

package/core/modules/steps/steps.js

@@ -18,7 +18,17 @@ import { ExternalWindow } from '../../components';
 import { Dashboard } from '../../models';
 import * as genericComponents from './../../lib';
 import { Button, Card, Location } from './../../lib';
+import {
+  base64AudioToBlob,
+  buildGuestStepGuide,
+  extractGeminiAudio,
+  getElevenLabsApiKey,
+  getGeminiApiKey,
+  getOpenAIApiKey,
+  getSarvamApiKey,
+} from './narration';
 import { createOpenAIRealtimeSession, hasOpenAIRealtimeCredentials } from './openai-realtime';
+import { clearProgressEntry, readProgressEntry, sweepStaleProgressKeys, writeProgressEntry } from './progress-storage';
 import './steps.scss';
 
 const TOUCH_NAV_HIDE_DELAY = 2800;
@@ -36,39 +46,6 @@ const FIRST_STEP_LABELS = Object.freeze({
   consultation: 'Start Consultation',
 });
 
-const STEP_WELCOME_LINES = [
-  'Welcome to your AI Automated Consultation process.',
-  'You are in the right place for a smooth and guided health journey.',
-  'This experience is designed to keep your consultation easy and stress-free.',
-];
-
-const STEP_INTRO_LINES = [
-  'In this process, we will walk you through a seamless and friendly AI interaction experience.',
-  'Each step is simple, guided, and focused on helping you feel prepared.',
-  'We will guide you through each stage so you always know what happens next.',
-];
-
-const STEP_EXPECTATION_LINES = [
-  'A care specialist may ask quick clarification questions to ensure your details are accurate.',
-  'This step focuses on collecting clear inputs so the care team can support you faster.',
-  'You can expect a guided workflow with minimal waiting and clear instructions.',
-  'The goal in this step is to keep your consultation organized and easy to follow.',
-];
-
-const STEP_COMFORT_LINES = [
-  'Take your time. There is no rush and assistance is always available nearby.',
-  'If anything feels unclear, the next prompt will guide you before you continue.',
-  'You can pause and review information before moving to the next stage.',
-  'Your responses here help personalize the rest of your consultation flow.',
-];
-
-const STEP_TIP_LINES = [
-  'Tip: Keep your previous reports or test details ready for quicker progress.',
-  'Tip: Follow on-screen prompts one at a time for the smoothest experience.',
-  'Tip: If you are unsure about a question, answer what you know and continue.',
-  'Tip: Stay relaxed; this process is built to be simple and patient-friendly.',
-];
-
 const VOICE_PROVIDER_OPTIONS = [
   { label: 'Gemini', value: 'gemini' },
   { label: 'ElevenLabs', value: 'elevenlabs' },
@@ -133,157 +110,6 @@ const SARVAM_TARGET_LANGUAGE_CODE = process.env.SARVAM_TARGET_LANGUAGE_CODE || p
 const SARVAM_OUTPUT_AUDIO_CODEC = process.env.SARVAM_OUTPUT_AUDIO_CODEC || process.env.REACT_APP_SARVAM_OUTPUT_AUDIO_CODEC || 'wav';
 const NARRATION_CONTROLS_ENABLED = false;
 
-function getFromStorage(storageKey) {
-  if (typeof window === 'undefined' || !window.localStorage) {
-    return null;
-  }
-
-  try {
-    return window.localStorage.getItem(storageKey);
-  } catch (error) {
-    return null;
-  }
-}
-
-function getElevenLabsApiKey() {
-  return (
-    process.env.ELEVEN_LABS_KEY ||
-    process.env.ELEVENLABS_API_KEY ||
-    process.env.REACT_APP_ELEVEN_LABS_KEY ||
-    process.env.REACT_APP_ELEVENLABS_API_KEY ||
-    getFromStorage('eleven_labs_key') ||
-    getFromStorage('elevenlabs_api_key') ||
-    getFromStorage('ELEVEN_LABS_KEY') ||
-    getFromStorage('REACT_APP_ELEVEN_LABS_KEY') ||
-    getFromStorage('REACT_APP_ELEVENLABS_API_KEY')
-  );
-}
-
-function getGeminiApiKey() {
-  return (
-    process.env.GEMINI_API_KEY ||
-    process.env.REACT_APP_GEMINI_API_KEY ||
-    getFromStorage('gemini_api_key') ||
-    getFromStorage('GEMINI_API_KEY') ||
-    getFromStorage('REACT_APP_GEMINI_API_KEY')
-  );
-}
-
-function getOpenAIApiKey() {
-  return (
-    process.env.OPEN_AI_KEY ||
-    process.env.OPENAI_API_KEY ||
-    process.env.REACT_APP_OPEN_AI_KEY ||
-    process.env.REACT_APP_OPENAI_API_KEY ||
-    getFromStorage('open_ai_key') ||
-    getFromStorage('openai_api_key') ||
-    getFromStorage('OPEN_AI_KEY') ||
-    getFromStorage('OPENAI_API_KEY') ||
-    getFromStorage('REACT_APP_OPEN_AI_KEY') ||
-    getFromStorage('REACT_APP_OPENAI_API_KEY')
-  );
-}
-
-function getSarvamApiKey() {
-  return (
-    process.env.SARVAM_API_KEY ||
-    process.env.REACT_APP_SARVAM_API_KEY ||
-    getFromStorage('sarvam_api_key') ||
-    getFromStorage('REACT_APP_SARVAM_API_KEY')
-  );
-}
-
-function base64AudioToBlob(base64Audio = '', mimeType = 'audio/wav') {
-  const cleanedBase64 = base64Audio.includes(',') ? base64Audio.split(',').pop() : base64Audio;
-  const binaryString = typeof window !== 'undefined' && window.atob ? window.atob(cleanedBase64) : atob(cleanedBase64);
-  const bytes = new Uint8Array(binaryString.length);
-
-  for (let index = 0; index < binaryString.length; index += 1) {
-    bytes[index] = binaryString.charCodeAt(index);
-  }
-
-  return new Blob([bytes], { type: mimeType });
-}
-
-function extractGeminiAudio(payload) {
-  const candidates = payload && payload.candidates ? payload.candidates : [];
-
-  for (const candidate of candidates) {
-    const parts = candidate && candidate.content && candidate.content.parts ? candidate.content.parts : [];
-
-    for (const part of parts) {
-      const inlineData = part.inlineData || part.inline_data || part.audio;
-
-      if (inlineData && inlineData.data) {
-        return {
-          mimeType: inlineData.mimeType || inlineData.mime_type || 'audio/wav',
-          data: inlineData.data,
-        };
-      }
-    }
-  }
-
-  return null;
-}
-
-function hashText(value = '') {
-  let hash = 0;
-
-  for (let index = 0; index < value.length; index += 1) {
-    hash = (hash << 5) - hash + value.charCodeAt(index);
-    hash |= 0;
-  }
-
-  return Math.abs(hash);
-}
-
-function pickBySeed(items = [], seed = 0) {
-  if (!items.length) {
-    return '';
-  }
-
-  return items[seed % items.length];
-}
-
-function buildGuestStepGuide(step, index, total) {
-  if (!step) {
-    return {
-      welcome: STEP_WELCOME_LINES[0],
-      intro: STEP_INTRO_LINES[0],
-      expectation: 'We are preparing your consultation journey.',
-      comfort: STEP_COMFORT_LINES[0],
-      tip: STEP_TIP_LINES[0],
-      narration: '',
-    };
-  }
-
-  const stepName = step.step_name || `Step ${index + 1}`;
-  const seedSource = `${step.step_id || step.id || index}-${stepName}`;
-  const seed = hashText(seedSource);
-
-  const welcome = index === 0 ? STEP_WELCOME_LINES[0] : `Now entering ${stepName}.`;
-  const intro = index === 0 ? STEP_INTRO_LINES[0] : pickBySeed(STEP_INTRO_LINES, seed + 1);
-  const expectation = step.step_description || pickBySeed(STEP_EXPECTATION_LINES, seed + 2);
-  const comfort = pickBySeed(STEP_COMFORT_LINES, seed + 3);
-  const tip = pickBySeed(STEP_TIP_LINES, seed + 4);
-
-  return {
-    welcome,
-    intro,
-    expectation,
-    comfort,
-    tip,
-    narration: [
-      `Step ${index + 1} of ${total}. ${stepName}.`,
-      welcome,
-      intro,
-      `What to expect: ${expectation}`,
-      `Comfort note: ${comfort}`,
-      `Helpful tip: ${tip}`,
-    ].join(' '),
-  };
-}
-
 export default function ProcessStepsPage({ match, CustomComponents = {}, ...props }) {
   const allComponents = { ...genericComponents, ...CustomComponents };
   const GuestInfoComponent = allComponents.EntryInfo;
@@ -296,6 +122,7 @@ export default function ProcessStepsPage({ match, CustomComponents = {}, ...prop
   const [isStepCompleted, setIsStepCompleted] = useState(false);
 
   const [nextProcessId, setNextProcessId] = useState(null);
+  const [previousProcessId, setPreviousProcessId] = useState(null);
   const [stepStartTime, setStepStartTime] = useState(null);
   const [processStartTime, setProcessStartTime] = useState(null);
   const [processTimings, setProcessTimings] = useState([]);
@@ -335,64 +162,74 @@ export default function ProcessStepsPage({ match, CustomComponents = {}, ...prop
   const isConsultationMode = String(urlParams?.consultation).toLowerCase() === 'true';
   let processId = urlParams.processId;
   const [currentProcessId, setCurrentProcessId] = useState(processId);
+
+  /**
+   * Storage scope for per-guest progress.
+   * - The localStorage keys combine the process and the guest reference so
+   *   guest A's resume marker cannot appear for guest B.
+   * - Sources tried in order: query params (`opb_id`, `reference_id`, `opno`,
+   *   `reference_number`), then React Router `match.params`, then the final
+   *   pathname segment. Only when none produce a non-empty value does the
+   *   scope collapse to `anonymous` — which is the symptom of "stores step
+   *   but not per guest" because all guests then share one key.
+   */
+  const guestReference = (() => {
+    const fromQuery = urlParams?.opb_id || urlParams?.reference_id || urlParams?.opno || urlParams?.reference_number;
+    if (fromQuery) return String(fromQuery);
+
+    const params = match?.params || {};
+    const paramCandidates = [params.opb_id, params.reference_id, params.opno, params.reference_number, params.id];
+    const fromRoute = paramCandidates.find((value) => value != null && value !== '');
+    if (fromRoute) return String(fromRoute);
+
+    if (typeof window !== 'undefined' && window.location?.pathname) {
+      const segments = window.location.pathname.split('/').filter(Boolean);
+      const last = segments[segments.length - 1];
+      if (last) return String(last);
+    }
+
+    return 'anonymous';
+  })();
+  const timingsStorageKey = `processTimings_${currentProcessId}_${guestReference}`;
+  const activeStepStorageKey = `processActiveStep_${currentProcessId}_${guestReference}`;
+
   // Load process details based on the current process ID
   useEffect(() => {
-    loadProcess(currentProcessId);
+    sweepStaleProgressKeys();
 
-    let savedTimings = [];
-    try {
-      const saved = localStorage.getItem(`processTimings_${currentProcessId}`);
-      if (saved) {
-        const parsed = JSON.parse(saved);
-        if (Array.isArray(parsed)) {
-          savedTimings = parsed;
-        }
-      }
-    } catch (error) {
-      console.warn('Unable to restore process timings from local storage.', error);
-    }
+    loadProcess(currentProcessId);
 
+    /**
+     * Both the key AND the stored value are scoped to the guest. A read is
+     * only accepted when the value's `guestRef` matches the current guest;
+     * any mismatch (or a legacy unwrapped value from before this change) is
+     * treated as "no saved progress" so guest A's data can never appear for
+     * guest B even if a key collision somehow occurred.
+     */
+    const savedTimingsEntry = readProgressEntry(timingsStorageKey);
+    const savedTimings =
+      savedTimingsEntry && savedTimingsEntry.guestRef === guestReference && Array.isArray(savedTimingsEntry.timings) ? savedTimingsEntry.timings : [];
     setProcessTimings(savedTimings);
 
-    let savedActiveStep = 0;
-    try {
-      const rawStep = localStorage.getItem(`processActiveStep_${currentProcessId}`);
-      const parsedStep = rawStep == null ? NaN : parseInt(rawStep, 10);
-      if (Number.isFinite(parsedStep) && parsedStep > 0) {
-        savedActiveStep = parsedStep;
-      }
-    } catch (error) {
-      console.warn('Unable to restore active step from local storage.', error);
-    }
+    const savedStepEntry = readProgressEntry(activeStepStorageKey);
+    const parsedStep = savedStepEntry && savedStepEntry.guestRef === guestReference ? Number(savedStepEntry.step) : NaN;
+    const savedActiveStep = Number.isFinite(parsedStep) && parsedStep > 0 ? parsedStep : 0;
     setResumableStep(savedActiveStep > 0 ? savedActiveStep : null);
 
     setProcessStartTime(Date.now());
     setStepStartTime(Date.now());
     setShowNextProcessAction(false);
-  }, [currentProcessId]);
+    setActiveStep(0);
+  }, [currentProcessId, guestReference]);
 
   /**
-   * Persist the active step so an unexpected exit (refresh, tab close, crash)
-   * can offer a Resume action on the next mount. Only steps beyond the first
-   * are persisted — step 0 is the natural entry point and does not need a
-   * resume marker. The marker is cleared on successful process submission and
-   * when the user explicitly dismisses the resume banner.
+   * The active step is persisted inline in `gotoStep` rather than via a
+   * useEffect — running it as an effect captured `activeStepStorageKey` from
+   * a closure that could go stale during URL changes, allowing one guest's
+   * progress to be written under another guest's key. Writing in `gotoStep`
+   * happens synchronously with the user action using the current render's
+   * key, so it can never target a different guest than the one interacting.
    */
-  useEffect(() => {
-    if (typeof window === 'undefined' || !window.localStorage || !currentProcessId) {
-      return;
-    }
-
-    if (activeStep <= 0) {
-      return;
-    }
-
-    try {
-      localStorage.setItem(`processActiveStep_${currentProcessId}`, String(activeStep));
-    } catch (error) {
-      console.warn('Unable to persist active step to local storage.', error);
-    }
-  }, [activeStep, currentProcessId]);
 
   /**
    * Sync the loaded process name into the address bar.
@@ -409,24 +246,45 @@ export default function ProcessStepsPage({ match, CustomComponents = {}, ...prop
     }
 
     const params = new URLSearchParams(window.location.search);
-    const trimmedName = typeof processName === 'string' ? processName.trim() : '';
+    let changed = false;
 
+    const trimmedName = typeof processName === 'string' ? processName.trim() : '';
     if (trimmedName) {
-      if (params.get('process') === trimmedName) {
-        return;
-      }
-      params.set('process', trimmedName);
-    } else {
-      if (!params.has('process')) {
-        return;
+      if (params.get('process') !== trimmedName) {
+        params.set('process', trimmedName);
+        changed = true;
       }
+    } else if (params.has('process')) {
       params.delete('process');
+      changed = true;
+    }
+
+    /**
+     * Mirror `currentProcessId` to the `processId` query param so previous /
+     * next process navigation reflects in the URL (e.g. when jumping from
+     * Verification → Consultation, the address bar should switch from
+     * `processId=1` to `processId=2`). Without this, deep-links and refreshes
+     * would still resolve to the originally loaded process.
+     */
+    const processIdString = currentProcessId != null ? String(currentProcessId) : '';
+    if (processIdString) {
+      if (params.get('processId') !== processIdString) {
+        params.set('processId', processIdString);
+        changed = true;
+      }
+    } else if (params.has('processId')) {
+      params.delete('processId');
+      changed = true;
+    }
+
+    if (!changed) {
+      return;
     }
 
     const search = params.toString();
     const newUrl = `${window.location.pathname}${search ? `?${search}` : ''}${window.location.hash || ''}`;
     window.history.replaceState(window.history.state, '', newUrl);
-  }, [processName]);
+  }, [processName, currentProcessId]);
 
   //// Reset step start time whenever the active step changes
 
@@ -539,12 +397,7 @@ export default function ProcessStepsPage({ match, CustomComponents = {}, ...prop
   const saveTimings = (updated) => {
     const safeTimings = Array.isArray(updated) ? updated : [];
     setProcessTimings(safeTimings);
-
-    try {
-      localStorage.setItem(`processTimings_${currentProcessId}`, JSON.stringify(safeTimings));
-    } catch (error) {
-      console.warn('Unable to persist process timings to local storage.', error);
-    }
+    writeProgressEntry(timingsStorageKey, { guestRef: guestReference, timings: safeTimings });
   };
   // Record time spent on the current step
 
@@ -593,6 +446,7 @@ export default function ProcessStepsPage({ match, CustomComponents = {}, ...prop
   async function loadProcess(processId) {
     setLoading(true);
     setNextProcessId(null);
+    setPreviousProcessId(null);
 
     try {
       const result = await Dashboard.loadProcess(processId);
@@ -600,6 +454,7 @@ export default function ProcessStepsPage({ match, CustomComponents = {}, ...prop
       setSteps(result?.data?.steps || []);
       setProcessName(result?.data?.process_name ?? null);
       if (result?.data?.next_process_id) setNextProcessId(result.data);
+      if (result?.data?.previous_process_id) setPreviousProcessId(result.data);
     } catch (e) {
       console.error('Error loading process steps:', e);
     } finally {
@@ -633,12 +488,8 @@ export default function ProcessStepsPage({ match, CustomComponents = {}, ...prop
       const response = await Dashboard.processLog(payload);
 
       if (response.success) {
-        try {
-          localStorage.removeItem(`processTimings_${currentProcessId}`);
-          localStorage.removeItem(`processActiveStep_${currentProcessId}`);
-        } catch (error) {
-          console.warn('Unable to clear process timings from local storage.', error);
-        }
+        clearProgressEntry(timingsStorageKey);
+        clearProgressEntry(activeStepStorageKey);
         setProcessTimings([]);
         setResumableStep(null);
         return true;
@@ -674,6 +525,19 @@ export default function ProcessStepsPage({ match, CustomComponents = {}, ...prop
     const updated = recordStepTime(status);
     saveTimings(updated);
     setActiveStep(nextIndex);
+
+    /**
+     * Persist the resume marker synchronously here, not in a useEffect. The
+     * current render's `activeStepStorageKey` is guaranteed to belong to the
+     * guest the user is interacting with, so the write cannot leak to a
+     * different guest's key. Step 0 is the entry point — clear any marker
+     * so a returning visitor at step 0 does not see a stale banner.
+     */
+    if (nextIndex > 0 && currentProcessId) {
+      writeProgressEntry(activeStepStorageKey, { guestRef: guestReference, step: nextIndex });
+    } else if (nextIndex === 0) {
+      clearProgressEntry(activeStepStorageKey);
+    }
   };
   /**
    * Navigate to the next step
@@ -717,9 +581,7 @@ export default function ProcessStepsPage({ match, CustomComponents = {}, ...prop
   const dismissResume = () => {
     setResumableStep(null);
     try {
-      if (typeof window !== 'undefined' && window.localStorage && currentProcessId) {
-        localStorage.removeItem(`processActiveStep_${currentProcessId}`);
-      }
+      clearProgressEntry(activeStepStorageKey);
     } catch (error) {
       console.warn('Unable to clear resume marker from local storage.', error);
     }
@@ -751,6 +613,23 @@ export default function ProcessStepsPage({ match, CustomComponents = {}, ...prop
       setShowExternalWindow(true);
     }
   };
+  /**
+   * Go Back to Previous Process
+   * - Loads the previously linked process for the current guest.
+   * - Does NOT submit the current process; this is a "go back" navigation,
+   *   not a completion. Step timings collected so far stay in localStorage
+   *   under the current process's scoped key in case the user returns.
+   * - Updates `currentProcessId` which triggers the load effect to refresh
+   *   process data, reset `activeStep` to 0, and re-derive storage scope.
+   */
+  const handleStartPreviousProcess = async () => {
+    if (!previousProcessId?.previous_process_id) {
+      return;
+    }
+    await loadProcess(previousProcessId.previous_process_id);
+    setCurrentProcessId(previousProcessId.previous_process_id);
+    setActiveStep(0);
+  };
 
   function clearNarrationAudio() {
     if (narrationAudioRef.current) {
@@ -1440,6 +1319,19 @@ export default function ProcessStepsPage({ match, CustomComponents = {}, ...prop
                   {isStepFullscreen ? 'Exit Full Screen' : 'Full Screen'}
                 </Button>
 
+                {/*
+                  Previous-process button.
+                  - Only relevant at the start of a process (`activeStep === 0`)
+                    AND when the backend signalled a `previous_process_id`. Mid-
+                    process the in-step Back button handles intra-process
+                    navigation, so showing this here would be ambiguous.
+                */}
+                {activeStep === 0 && previousProcessId?.previous_process_id && (
+                  <Button type="default" icon={<ArrowLeftOutlined />} onClick={handleStartPreviousProcess}>
+                    {previousProcessId.previous_process_name ? `Back to ${previousProcessId.previous_process_name}` : 'Previous Process'}
+                  </Button>
+                )}
+
                 {activeStep > 0 && (
                   <Button type="default" icon={<ArrowLeftOutlined />} onClick={handlePrevious}>
                     Back
@@ -1483,8 +1375,7 @@ export default function ProcessStepsPage({ match, CustomComponents = {}, ...prop
                       generic "Next" label. All non-first steps always render
                       "Next".
                     */}
-                    {activeStep === 0 ? (FIRST_STEP_LABELS[processName?.trim().toLowerCase()] ?? 'Next') : 'Next'}{' '}
-                    <ArrowRightOutlined />
+                    {activeStep === 0 ? (FIRST_STEP_LABELS[processName?.trim().toLowerCase()] ?? 'Next') : 'Next'} <ArrowRightOutlined />
                   </Button>
                 )}
               </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ui-soxo-bootstrap-core",
-  "version": "2.6.32-dev.6",
+  "version": "2.6.32-dev.8",
   "description": "All the Core Components for you to start",
   "keywords": [
     "all in one"