Advanced Configuration

Stability Tuning

Before capturing page context, the SDK waits for the page to stabilize. This avoids sending incomplete or mid-render snapshots to the AI. The stability system runs a sequence of detection layers, each of which can be toggled independently:

Layer	What It Detects	Default
Network Idle	Pending fetch/XHR requests	Enabled
DOM Mutations	DOM changes (via MutationObserver)	Enabled
Loading Indicators	Spinners, skeletons, `[aria-busy]`	Disabled
Frame Readiness	Same-origin frame documents reaching `readyState: 'complete'`	Enabled
Resource Quiet	Resource Timing entries settling after the newest completion	Enabled
Layout Shifts	Visual layout changes (via PerformanceObserver)	Disabled
Browser Idle	CPU idle (via requestIdleCallback)	Enabled
Final Frame	One requestAnimationFrame	Enabled

Loading indicators and layout shift layers are disabled by default because many sites have persistent loading animations that would cause unnecessary delays. Enable them if your application uses skeleton screens that reliably disappear.

Enabling Additional Layers

<AgentProvider config={{
  // ...
  stability: {
    layers: {
      loadingIndicators: true,  // Enable loading indicator detection
      layoutShift: true,        // Enable layout shift detection
    },
  },
}}>

Layer-Specific Configuration

Each layer can be configured individually:

stability: {
  // Global timeouts
  maxTotalWaitMs: 15000,       // Max total time across all layers (default: 15s)
  networkTimeoutMs: 10000,     // Network idle timeout (default: 10s)
  browserIdleTimeoutMs: 500,   // Browser idle timeout (default: 500ms)

  // DOM mutations layer
  domMutations: {
    quietPeriodMs: 800,        // No mutations for this long = stable (default: 800ms)
    excludeSelectors: ['.live-clock', '.notification-badge'],
  },

  // Loading indicators layer (must also enable via layers.loadingIndicators)
  loadingIndicators: {
    selectors: ['[class*="skeleton"]', '.spinner', '[aria-busy="true"]'],
    excludeSelectors: ['.permanent-loader'],
    timeoutMs: 5000,
  },

  // Layout shift layer (must also enable via layers.layoutShift)
  layoutShift: {
    quietPeriodMs: 200,        // No shifts for this long = stable (default: 200ms)
    ignoreThreshold: 0.01,     // Ignore tiny shifts (default: 0.01)
  },
}

Disabling Stability Checks

For testing or very simple pages, you can disable layers:

stability: {
  layers: {
    networkIdle: false,
    domMutations: false,
    browserIdle: false,
    finalFrame: false,
  },
}

Disabling stability layers may cause the AI to receive incomplete page context. Only disable for testing or if you’re certain the page is fully rendered.

After Reload Handling

If your application triggers full page reloads during guided steps, enable the afterReload option to preserve state:

stability: {
  afterReload: {
    enabled: true,          // Off unless explicitly enabled
    pendingTTL: 30000,      // How long pending state stays valid (default: 30000ms)
    storageKey: 'my-app-moss-pending',  // Override the storage key holding pending state
  },
}

Field	Type	Default	Description
`enabled`	`boolean`	`false`	Preserve pending guide state across a full page reload
`pendingTTL`	`number`	`30000`	Milliseconds a pending marker stays valid before it is discarded
`storageKey`	`string`	SDK default	Storage key used to hold the pending marker

Shadow DOM

The SDK renders all UI inside a Shadow DOM attached to document.body. This means:

Your CSS cannot affect Moss UI — styles are fully encapsulated
Moss CSS cannot affect your app — no style leakage
DOM queries from your app won’t find Moss elements — document.querySelector won’t match elements inside the shadow root

If you’re using automated testing tools (Cypress, Playwright, etc.), you’ll need to pierce the shadow DOM to interact with Moss elements. Look for the #moss-shadow-host host element (#clippy-shadow-host in SDK versions up to 0.16).

Content Security Policy (CSP)

If your application uses strict CSP headers, you may need to allow:

Directive	Value	Reason
`connect-src`	Your Moss backend URL	API requests
`script-src`	CDN URL (if using script tag)	SDK script
`style-src`	`'unsafe-inline'`	Shadow DOM styles
`img-src`	`blob:` `data:`	Screenshot processing

Example CSP header:

Content-Security-Policy:
  connect-src 'self' https://moss-api.viamoss.ai;
  style-src 'self' 'unsafe-inline';
  img-src 'self' blob: data:;

DOM Observation Scope

By default, the SDK observes document.body for changes. To limit observation to a specific part of your page:

<AgentProvider config={{
  // ...
  observeTargetSelector: '#main-content',
}}>

This is useful when:

Your app has a complex sidebar or header that shouldn’t trigger re-captures
You want to reduce noise from unrelated DOM changes
The assistant should only help with a specific section of the page

When your application opens a native <dialog> with showModal(), the browser makes everything outside the dialog inert — including the Moss widget. The user can’t click the assistant, and an in-progress guide can’t continue. If your application uses showModal(), install the modal dialog escape with the element your integration mounts the widget into:

import { installModalDialogEscape } from '@viamoss/moss-sdk';

const uninstall = installModalDialogEscape(widgetMountElement);

// Later, if you tear the widget down:
uninstall();

While a modal dialog is open, the SDK host is temporarily moved into the dialog’s tree (and promoted above it) so the widget stays interactive and keeps its viewport position. When the dialog closes, the host is restored to its original place in the DOM. The returned function uninstalls the listeners and restores the host.

Pass an element your integration owns outright — the container you mounted the Moss widget into. Never pass a node managed by your application’s framework: the escape re-parents the element, which would fight the framework’s own rendering.

Limitations:

Dialogs rendered inside shadow roots are not tracked.
In browsers without the Popover API, the widget stays interactive but may render clipped inside dialogs that have overflow: hidden or a transform.

Redacting Sensitive Content

Declarative Redaction with `data-moss-redact`

Mark any HTML element with the data-moss-redact attribute to redact it from all data sent to the Moss backend. This is the simplest way to protect sensitive content.

<div data-moss-redact>
  <p>Account balance: $12,340.56</p>
  <p>SSN: 123-45-6789</p>
</div>

What gets redacted:

Text content — replaced with [REDACTED] in the structured context sent to the backend
Sensitive attributes — value, placeholder, title, alt, aria-label, href, src, and name are all redacted
Child elements — all descendants of a redacted element are excluded

Redaction applies to the marked element and any of its ancestors up to 10 levels deep, so you can mark a container to redact everything inside it.

<!-- All form fields inside this section are redacted -->
<section data-moss-redact>
  <input type="text" placeholder="Card number" />
  <input type="text" placeholder="CVV" />
</section>

Input Redaction (default on)

All input-type elements — input, textarea, select, and contenteditable regions — have their values redacted by default. What a user has typed into a form never leaves the browser as page context. To opt a specific field out when its content is known to be safe and useful to the assistant (for example, a search box), mark it with data-moss-unredact:

<input type="search" data-moss-unredact placeholder="Search products…" />

To disable input redaction entirely, set redactAllInputs: false:

<AgentProvider config={{
  // ...
  redactAllInputs: false,  // default: true
}}>

Keep redactAllInputs enabled unless you have reviewed every form in your application. With it disabled, typed form values are included in the page context sent to Moss.

Redaction by CSS Selector

If your application already marks sensitive elements for another tool (for example FullStory’s .fs-exclude / .fs-mask classes), reuse those markers instead of adding data-moss-redact everywhere. Elements matching redactionSelectors are redacted identically to data-moss-redact:

<AgentProvider config={{
  // ...
  redactionSelectors: ['.fs-exclude', '.fs-mask', '[data-private]'],
}}>

data-moss-redact is always recognized regardless of this setting. If an element matches both an allow rule and a redact rule, the redact rule wins.

What redaction covers

Redaction applies to the page text and structure sent as context and to the interaction reports recorded during step-by-step guidance. It does not alter chat messages the user types, screenshots, session recordings, or screen history — disable those features individually if their output is not permitted in your environment.

Programmatic Sanitization

For more complex sanitization logic, use pageSanitizationScript to modify a cloned copy of the DOM before capture:

<AgentProvider config={{
  // ...
  pageSanitizationScript: (doc) => {
    // Remove credit card fields
    doc.querySelectorAll('[data-sensitive]').forEach(el => {
      el.textContent = '[REDACTED]';
    });
    // Remove tracking pixels
    doc.querySelectorAll('img[width="1"]').forEach(el => el.remove());
  },
}}>

Both methods only affect what the AI sees. The live DOM is never modified — your users won’t see any changes.

Troubleshooting

Assistant button doesn’t appear

Check the browser console for [MossSDK] errors
Verify applicationId matches a valid application in the Dashboard
Confirm apiUrl is reachable from the browser
Check that your JWT signing key is active and not revoked

”Failed to fetch config” error

The SDK couldn’t reach the backend. Check apiUrl and network/CORS settings.
If using CSP, ensure connect-src includes the backend URL.

Screenshots are blank or incomplete

Try switching screenshotMode to 'viewport'
Increase stability.domMutations.quietPeriodMs if the page has slow animations
Check if iframes or cross-origin content is blocking capture

Styles conflict with host application

This shouldn’t happen — the SDK uses Shadow DOM isolation. If you see conflicts:

Check if your app is using !important on * or body selectors
Verify no JavaScript is modifying the shadow root

Debug mode

Enable verbose logging to diagnose issues:

import { LogLevel } from '@viamoss/moss-sdk';

<AgentProvider config={{
  // ...
  debugMode: true,
  logLevel: LogLevel.DEBUG,
}}>

This logs stability layer timing, network requests, context capture details, and API responses to the browser console.

Getting Started

SDK

Dashboard

Configuration

Security

Guides

Resources

Advanced

Advanced Configuration

Stability Tuning

Enabling Additional Layers

Layer-Specific Configuration

Disabling Stability Checks

After Reload Handling

Shadow DOM

Content Security Policy (CSP)

DOM Observation Scope

Redacting Sensitive Content

Declarative Redaction with `data-moss-redact`

Input Redaction (default on)

Redaction by CSS Selector

What redaction covers

Programmatic Sanitization

Troubleshooting

Assistant button doesn’t appear

”Failed to fetch config” error

Screenshots are blank or incomplete

Styles conflict with host application

Debug mode

​Advanced Configuration

​Stability Tuning

​Enabling Additional Layers

​Layer-Specific Configuration

​Disabling Stability Checks

​After Reload Handling

​Shadow DOM

​Content Security Policy (CSP)

​DOM Observation Scope

​Native Modal Dialogs

​Redacting Sensitive Content

​Declarative Redaction with data-moss-redact

​Input Redaction (default on)

​Redaction by CSS Selector

​What redaction covers

​Programmatic Sanitization

​Troubleshooting

​Assistant button doesn’t appear

​”Failed to fetch config” error

​Screenshots are blank or incomplete

​Styles conflict with host application

​Debug mode

Advanced Configuration

Stability Tuning

Enabling Additional Layers

Layer-Specific Configuration

Disabling Stability Checks

After Reload Handling

Shadow DOM

Content Security Policy (CSP)

DOM Observation Scope

Native Modal Dialogs

Redacting Sensitive Content

Declarative Redaction with `data-moss-redact`

Input Redaction (default on)

Redaction by CSS Selector

What redaction covers

Programmatic Sanitization

Troubleshooting

Assistant button doesn’t appear

”Failed to fetch config” error

Screenshots are blank or incomplete

Styles conflict with host application

Debug mode