Embed widget configuration

The embed script ( v1.js) reads window.textSenseConfig and runs initTextSense when it loads. Your config can be a single object or an array of objects. Each object is a separate rule block: every block whose pathFilter matches the current path runs on its own (so keep patterns disjoint, or use a single block, unless you intentionally want multiple toolbars).

For sites that need different toolbar placement or styles on different sections, you can use an array of blocks—typically one pathFilter per area—with shared options like languages and tailored styling per block.

Minimal shape

// Set before loading v1.js
window.textSenseConfig = {
    pathFilter: ".*",
    sourceLanguage: "en",
    targets: "body",
    actions: [
        { action: "SUMMARIZE", targetChildFilter: "", targetChildIgnoreFilter: "" },
        { action: "TRANSLATE", targetChildFilter: "", targetChildIgnoreFilter: "" }
    ]
};

// Or multiple URL-specific rules (array)
window.textSenseConfig = [
    { pathFilter: "/news/.*", /* ... */ },
    { pathFilter: "/about/?$", /* ... */ }
];

// Optional: keepSessionActive: true and id: "my-block" persist toolbar language + auto-actions in localStorage (see General options).

General options

pathFilterstring (RegExp)Default: ".*"

Tested against window.location.pathname. If it does not match, this configuration block is skipped entirely.

sourceLanguagestringDefault: document.documentElement.lang or "en"

ISO language code for the page source text. Used when calling the API and to detect when the user selects the source language in the dropdown—for TRANSLATE, that choice restores the original text instead of calling the server.

targetsstring (CSS selector)Default: "body"

Elements that receive the widget. For each match, a wrapper (toolbar + optional result area) is created. Often body once per page; use a narrower selector (e.g. article) if you only want certain regions.

urlMappingobjectDefault: { targetLanguage: "language", triggerActions: "actions" }

Maps query parameter names to behaviors. If set, ?language=de (by default) pre-selects German; ?actions=SUMMARIZE,TRANSLATE auto-clicks those buttons shortly after init (comma-separated, case-insensitive).

keepSessionActivebooleanDefault: false

When true, this block's activeLanguage and activeActions are read and written in localStorage under a key derived from id (if set) or the block's index, so full page reloads restore the toolbar and URL auto-triggers. Client-side navigations re-apply session only when this is true; when false, each navigation starts from defaults and current URL mapping.

idstring (optional)Default: — (use block index)

Stable segment for the session storage key when keepSessionActive is true. Non-empty string after trim; omit to use this block's position in textSenseConfig.

languagesstring[]Default: all built-in languages

Restricts the language dropdown to these codes (must exist in the script's built-in list). Order is preserved.

defaultLanguagestringDefault: browser / page lang

Initial selection for the dropdown when no URL override is present. Normalized to two-letter codes.

commentstring (any)

Not used by the script. You can use it as a private note in your own config source.

onAfterInitialize(initializationContext?) => voidDefault: no-op

Called after all targets for this block have been processed and panels attached. Receives { activeActions, activeLanguage }—the merged URL + SPA session used for auto-actions and the language selector (useful when you override addTextSenseToTarget and still need to re-run translation after client navigations).

Actions

actions is an array of action objects. Each entry can include a pathFilter if you want that button to appear only on certain paths (regex on pathname). If every action is filtered out for the current URL, no panel is added.

actionstringDefault: —

Action name sent to the API (for example SUMMARIZE, TRANSLATE). Must be supported by your backend. Built-in button labeling uses translations only for SUMMARIZE and TRANSLATE.

targetChildFilterstring (CSS selector)Default: "" (empty)

When non-empty, only descendants of each target matching this selector contribute text. When empty, the target element itself is used as the root for text collection.

targetChildIgnoreFilterstring (CSS selector)Default: ""

Elements to exclude (and all text inside them). Applied after targetChildFilter. Prefer this over trying to encode exclusions only in :not() on the include filter—parent nodes may still pull excluded areas in.

pathFilterstring (RegExp)Default: —

Optional per-action pathname filter; if present, the action is omitted when it does not match.

getButtonHTML({ currentlySelectedLanguage, translatedLabel }) => stringDefault: star icon + label (summarize) / globe icon + label (translate)

Returns the button's inner HTML. For summarize and translate, translatedLabel is already localized.

onActionStart / onActionFinishasync callbacksDefault: spinner on default actions

Receives { target, actions, action, languageDropdown, currentlySelectedLanguage, translatedLabel }. Use to customize loading states; defaults add a spinning icon around the label.

Where the toolbar is inserted

By default the wrapper is placed before or after each target node. If you set an anchor, it is inserted relative to that element instead. Older names panelAnchor / panelPosition still work as aliases.

wrapperAnchorstring (CSS selector)Default: ""

First matching element on the page; the wrapper is inserted before or after it (not inside it).

wrapperPositioning"before" | "after"Default: "before"

Insert the wrapper before or after the anchor (or the target if no anchor).

getWrapperLeadingHTML / getWrapperTrailingHTML({ currentlySelectedLanguage }) => stringDefault: ""

Extra HTML injected inside the wrapper, before or after the toolbar row. Useful for disclaimers or links.

Styling hooks

Most elements combine a base *Style string with an optional *AdditionalStyle string and a *Class class name. Defaults favor a compact flex toolbar and a light gray result panel.

Wrapper: wrapperStyle, wrapperAdditionalStyle, wrapperClass
Toolbar row: panelStyle, panelAdditionalStyle, panelClass
Action buttons: buttonStyle, buttonAdditionalStyle, buttonClass
Language select: selectStyle, selectAdditionalStyle, selectClass
“In” label between buttons and dropdown: inBetweenTextStyle, inBetweenTextAdditionalStyle, inBetweenTextClass (hidden in many site configs via display: none;)
Result panel (summary / non-replacing stream): resultPanelStyle, resultPanelAdditionalStyle, resultPanelClass
Translated text restoration: originalTextElementClass marks hidden spans that store original text when the server uses the replace-in-place strategy.

Language dropdown

getLanguageOptionHTML({ languageCode, languageLabel, currentlySelectedLanguage }) => stringDefault: languageLabel only

Customizes each <option> body.

onLanguageChange({ language, previousLanguage, languageDropdown, actions }) => voidDefault: no-op

Fires when the user changes the select; you can inspect actions (each has a button reference after init) to trigger work.

Examples

Walkthroughs for common setups. Each tab shows a full config, a short overview, then what each important setting does.

window.textSenseConfig = {
    pathFilter: ".*",
    sourceLanguage: "en",
    targets: "body",
    actions: [
        {
            action: "SUMMARIZE",
            targetChildFilter: "",
            targetChildIgnoreFilter: "",
        },
        {
            action: "TRANSLATE",
            targetChildFilter: "",
            targetChildIgnoreFilter: "",
        },
    ],
};

Runs the summarize and translate toolbar on every page whose path matches the filter. Text is collected from the full document body, and both actions apply to the same scope.

Settings in this example

pathFilter: ".*"Regular expression tested against the pathname. ".*" matches all paths so this block runs site-wide.
sourceLanguage: "en"Declares the language of the original page. The API uses it for requests; choosing this language in the dropdown restores original text instead of translating again.
targets: "body"One widget is mounted per matching element—here, the document body, so typically a single toolbar on the page.
actions: [ ... ]Each entry becomes a button. Order in the array is left-to-right in the toolbar.
action: "SUMMARIZE"Button label and API action name for summarization (backend must support it).
targetChildFilter: ""Empty means: treat each target element itself as the root for gathering text, not a narrower child selector.
targetChildIgnoreFilter: ""Empty means: do not skip any subtrees; navigation and footer text are included unless you add selectors here.
action: "TRANSLATE"Second button for full translation into the language chosen in the dropdown.

Advanced: full placement override

Replacing addTextSenseToTarget lets you control mounting entirely. The default implementation creates the wrapper, wires buttons to processTarget / restoreTarget, and respects filters and URL auto-actions. Only override if you need behavior that cannot be expressed with anchors and styles.

How results appear

The client streams Server-Sent Events from your API. An early UI Strategy event tells the widget whether to stream into the result panel below the toolbar (show_in_panel) or replace original text nodes in place (replace_original_text). That choice comes from the server, not from the static config file.