ai.facesign/facesign-mcp

Official5 tools

by facesign

Build and test FaceSign step-up verification flows from your AI coding tool

The ai.facesign/facesign-mcp MCP server supports building and testing FaceSign step-up verification flows from within an AI coding tool. It is identified by the slug ai-facesign-facesign-mcp and exposes 5 tools. The server description focuses on FaceSign verification workflow development and testing.

🛠️ Key Features

Build and test FaceSign step-up verification flows
Integrates with an AI coding tool
5 available tools

🚀 Use Cases

Developing FaceSign step-up verification flows
Testing those flows directly from an AI coding workflow

⚡ Developer Benefits

Workflow support for FaceSign step-up verification development
Tool-based access count: 5 tools

⚠️ Limitations

Limited details available beyond FaceSign step-up verification flow build/test and tool count

Captured live from the server via tools/list.

set_api_key

Set your FaceSign API key for this session. This must be called before any other FaceSign tools. Get your API key from the FaceSign dashboard. The key starts with sk_live_... or sk_test_... Optionally override the API server URL via `serverUrl` — intended for FaceSign developers pointing the SDK at a non-production backend (e.g. a dev server). Leave unset to use the default production API.

Parameters2

apiKey	string	required	Your FaceSign API key (sk_live_... or sk_test_...)
serverUrl	string	optional	Optional FaceSign API server URL override. Only set this if the user explicitly asks to target a non-default server (e.g. a dev backend). Omit otherwise to use the production API.

Raw schema

{
  "type": "object",
  "properties": {
    "apiKey": {
      "type": "string",
      "description": "Your FaceSign API key (sk_live_... or sk_test_...)"
    },
    "serverUrl": {
      "type": "string",
      "format": "uri",
      "description": "Optional FaceSign API server URL override. Only set this if the user explicitly asks to target a non-default server (e.g. a dev backend). Omit otherwise to use the production API."
    }
  },
  "required": [
    "apiKey"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_session

Retrieve detailed information about a FaceSign session including status, transcript, AI analysis, node reports, video AI analysis, and asynchronous analysis lifecycle states.

Parameters1

sessionId

string

required

The session ID to retrieve

Raw schema

{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "description": "The session ID to retrieve"
    }
  },
  "required": [
    "sessionId"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_sessions

List FaceSign sessions with optional filtering by status, date range, and search term. Supports pagination via cursor.

Parameters9

status	any	optional	Filter by session status
fromDate	number	optional	Start of date range (Unix timestamp in ms)
toDate	number	optional	End of date range (Unix timestamp in ms)
search	string	optional	Search term to filter sessions
sortBy	string	optional	Field to sort by
sortOrder	string	optional	Sort direction
limit	number	optional	Max sessions to return (1-100, default 10)
cursor	string	optional	Pagination cursor from a previous response
clientReferenceId	string	optional	Filter by client reference ID

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "created",
            "inProgress",
            "incomplete",
            "complete"
          ]
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/properties/status/anyOf/0"
          }
        }
      ],
      "description": "Filter by session status"
    },
    "fromDate": {
      "type": "number",
      "description": "Start of date range (Unix timestamp in ms)"
    },
    "toDate": {
      "type": "number",
      "description": "End of date range (Unix timestamp in ms)"
    },
    "search": {
      "type": "string",
      "description": "Search term to filter sessions"
    },
    "sortBy": {
      "type": "string",
      "enum": [
        "createdAt",
        "status",
        "finishedAt"
      ],
      "description": "Field to sort by"
    },
    "sortOrder": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "Sort direction"
    },
    "limit": {
      "type": "number",
      "description": "Max sessions to return (1-100, default 10)"
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor from a previous response"
    },
    "clientReferenceId": {
      "type": "string",
      "description": "Filter by client reference ID"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

launch_session_ui

REQUIRES set_api_key to be called first. Launch a local web page in the browser for a FaceSign session. You MUST supply `landingHtml` (the pre-session page shown before the iframe), `recapHtml` (the results page shown after the session finishes), and `uiStrings` (a per-language dictionary whose keys are invented by you to match placeholders in the HTML). The MCP server provides NO default chrome — every visible string comes from you. Each page load / refresh creates a fresh session.

Parameters14

flow	array	required	Array of nodes forming the session's directed graph
avatarId	string	optional	Avatar ID from the facesign://catalog resource.
langs	array	optional	Optional whitelist of BCP-47 language codes (from facesign://catalog) the session may use. DEFAULT BEHAVIOUR (recommended): OMIT this parameter entirely — the session then supports every language in the FaceSign catalog, and `uiStrings` must cover every catalog language. ONLY set `langs` when the user EXPLICITLY restricts the language set (e.g. 'Spanish-only demo', 'support English and Russian'). Do NOT narrow to `['en']` just because the user described the demo in English or did not mention languages — that would silently drop multilingual support. Example (explicit restriction): ["en", "es", "ru"]. The set of target languages for `uiStrings` is derived from this list (or the full catalog if omitted).
defaultLang	string	optional	Optional fallback BCP-47 language code used when the end-user's browser language is not in `langs`. DEFAULT BEHAVIOUR: OMIT this parameter. The MCP server falls back to 'en' internally only as a last-resort for UI string lookup; you should not hardcode a default language here unless the user explicitly asks for one. When set, must be one of the codes in `langs` (if `langs` is also set).
zone	string	optional	Data processing zone
metadata	object	optional	Arbitrary metadata to attach
clientReferenceId	string	optional	Your own reference ID for this session
providedData	object	optional	Pre-known user data
videoAIAnalysisEnabled	boolean	optional	Enable video AI fraud analysis
extractionSchema	array	optional	Optional schema describing fields the FaceSign backend should extract from the session transcript using an LLM. Results are populated post-session at `session.report.extractedData` as `{ [fieldName]: string \| number \| boolean \| null }` (null when the transcript did not contain the data — every field is treated as optional). Use this for structured data collection that does NOT need its own dedicated node — e.g. follow-up questions in a single CONVERSATION node where you'd otherwise have to author multiple branching outcomes. The conversation flow itself is unaffected; extraction runs on the final transcript. Render the results in your recapHtml when present.
customization	object	optional	UI customization
landingHtml	string	required	REQUIRED. Raw HTML/JS for the pre-session landing page. NO CDATA, NO markdown fences. Every visible string MUST come from `uiStrings` — reference them via {{KEY}} placeholders (interpolated at inject time) or via window.t('KEY') (dynamic at runtime). Contract: reads window.__FACESIGN_FLOW__ (the flow array). MUST call window.__startSession(updatedFlow?) to launch the session. The session iframe has its own Start button for audio/video autoplay gesture — the landing page does NOT need one for that purpose. STYLE GUIDE (Pre-Session Page): Match this visual style for consistency with the FaceSign UI. Background: Light gray #f5f7fa. Full-viewport centered layout (flexbox, min-height: 100vh; min-height: 100dvh — always use dvh with vh fallback for iOS compatibility). Card: White, border-radius 16px, box-shadow 0 4px 24px rgba(0,0,0,.08), padding 2.5-3rem, max-width 480-600px, centered. Headings: Bold, 1.4-1.8rem, color #1a1a2e, centered in card. Inputs: Full-width, padding 14px 16px, border 2px solid #d1d5db, border-radius 12px, font-size 1rem. Focus: border-color #5b7bab. Placeholder color #9ca3af. Primary buttons: Background #7b8fb5 (steel-blue), color white, font-weight 600, font-size 1.05rem, border-radius 50px (pill shape), padding 14px, full-width in card. Hover: background #6a7fa5. Disabled: background #c5cdd8, cursor not-allowed. Links: Color #4573b8, no underline, underline on hover. Back navigation: "← Back" at top-left of card, color #4573b8, font-size 0.95rem. Profile images: Circular (border-radius 50%), 120-150px diameter, centered, subtle box-shadow. Spacing: 2.5-3rem card padding, 1.5rem between form groups, 1rem between label and input, 2rem above primary button. Font: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif. COMMON MISTAKES TO AVOID (UI/CSS): 1. Never set padding or margin on body The custom HTML is injected into a host page that controls its own layout. Setting padding, margin, or min-height on body will conflict with the host page styles and create unwanted spacing. Wrong: body { padding: 2rem; min-height: 100vh; } (Also wrong — using only 100vh without dvh fallback. Always add min-height: 100dvh after 100vh for iOS Safari.) Right — use a wrapper element instead: body { margin: 0; padding: 0; } .wrap { max-width: 860px; margin: 0 auto; padding: 2rem; } The same applies to background on body — avoid it unless you are certain the host page does not set its own background. 2. Use HTML entities for emoji, not JS unicode escapes When building HTML strings in JavaScript (via innerHTML, string concatenation, etc.), JS unicode escapes like \ud83c\udfa5 will NOT render as emoji. They only work inside JS string literals that are directly displayed via textContent or similar APIs. Wrong — renders as garbled text: h += '<div class="title">\ud83c\udfa5 Video AI Analysis</div>'; Right — use HTML numeric entities: h += '<div class="title">🎥 Video AI Analysis</div>'; Also right — use emoji directly in static HTML (outside of JS): <div class="title">🎥 Video AI Analysis</div> Common emoji HTML entities reference: 👤 👤 User/person 🎂 🎂 Birthday cake 📍 📍 Pin/location 💻 💻 Computer ✨ ✨ Sparkles 🔍 🔍 Search 🎥 🎥 Camera 🎬 🎬 Clapper board 📋 📋 Clipboard ⚧ ⚧ Gender symbol ✓ ✓ Checkmark 3. CSS class name collision between landingHtml and recapHtml CRITICAL: landingHtml and recapHtml are injected into the SAME host document. If both fragments use the same class names (e.g., .card, .container, .header), styles from one will leak into the other, causing layout breakage. ALWAYS use unique prefixed class names: - landingHtml (pre-session/landing page): prefix all classes with .lp- (e.g., .lp-card, .lp-header, .lp-btn) - recapHtml (results page): prefix all classes with .r- (e.g., .r-card, .r-header, .r-wrap) Wrong — causes collisions: /* in landingHtml / .card { max-width: 460px; } / in recapHtml / .card { max-width: 900px; } Right — namespaced: / in landingHtml / .lp-card { max-width: 460px; } / in recapHtml / .r-card { max-width: 900px; } COMMON MISTAKES TO AVOID (Code/API): 4. window.__startSession race condition NEVER call window.__startSession() synchronously in a click handler. The host page may not have injected the function yet. ALWAYS use polling: function waitAndStart(input) { var n = 0; var iv = setInterval(function() { n++; if (typeof window.__startSession === 'function') { clearInterval(iv); window.__startSession(input); } else if (n > 100) { clearInterval(iv); document.body.innerHTML = '<p style="text-align:center;padding:2rem;color:red;">Failed to initialize session. Please refresh.</p>'; } }, 100); } Wrong: startBtn.addEventListener('click', function() { window.__startSession(); }); Right: startBtn.addEventListener('click', function() { waitAndStart(); }); For exported apps, NEVER send window.__FACESIGN_FLOW__ or another graph back to the server. To select a flow declared in export_app, pass its ID: waitAndStart({ flowId: 'enhanced', providedData: { name: nameInput.value } }); 5. Permissions are automatic — do NOT add a permissions node by default FaceSign automatically requests camera and microphone permissions at session start. Most flows do NOT need a PERMISSIONS node. Only add one in these specific cases: (a) The user wants to request microphone and camera permissions separately at different times during the flow (instead of both at once at session start). (b) The user wants to move the permission request to the initial page (landingHtml), outside the FaceSign flow itself. 6. nodeReport.type values are lowercase snake_case The API returns nodeReport.type in lowercase snake_case: "face_compare", "document_scan", "conversation", "permissions", "liveness_detection", etc. — NOT uppercase like "FACE_COMPARE". ALWAYS use case-insensitive comparison when looking up node reports: function getNode(r, type) { var rr = (r && r.nodeReports) \|\| []; var tl = type.toLowerCase(); for (var i = 0; i < rr.length; i++) { if (rr[i].type && rr[i].type.toLowerCase() === tl) return rr[i]; } return null; } // Usage: getNode(report, 'face_compare'), getNode(report, 'document_scan') 7. Microblink document report — nested field structure DOCUMENT_SCAN nodeReport.report fields are NOT plain strings. They use Microblink's nested structure: firstName: { latin: { value: "JANICE" } } dateOfBirth: { originalString: { latin: { value: "04/30/1970" } } } — OR — dateOfBirth: { day: 30, month: 4, year: 1970 } NEVER read fields directly as strings (e.g., dr.firstName will be an object, not "JANICE"). ALWAYS use this safe-value extractor: function sv(v) { if (v == null) return ''; if (typeof v === 'string') return v; if (v.latin && v.latin.value != null) return String(v.latin.value); if (v.originalString) return sv(v.originalString); if (v.day != null && v.month != null && v.year != null) return v.month + '/' + v.day + '/' + v.year; return ''; } // Usage: sv(dr.firstName) → "JANICE", sv(dr.dateOfBirth) → "04/30/1970" 8. videoAIAnalysis criterion is camelCase — format for display The criterion field (e.g., "facialExpressionAndMovement", "useOfExternalDevices") comes in camelCase. Convert to human-readable format: function toStartCase(s) { if (!s) return ''; return s.replace(/([A-Z]+)/g, function(m) { return ' ' + m.toLowerCase(); }) .trim().replace(/^./, function(c) { return c.toUpperCase(); }); } // "facialExpressionAndMovement" → "Facial expression and movement" 9. Conversation node: condition vs prompt In CONVERSATION nodes: - "condition" (in outcomes) = ONLY describes the trigger event for transitioning to the next node (e.g., "User explicitly agrees to proceed") - "prompt" = ALL instructions for the avatar's behavior, including how to greet, how to respond to questions, how to handle objections, and how to persuade - User questions or objections during the conversation are handled within the SAME node (continued dialog), NOT via separate outcomes - Conversation nodes can have any number of outcomes depending on the use case: Branching nodes (e.g., "what color?") → one outcome per branch + a fallback * Consent/agreement nodes → typically 2: agreement + fallback after N attempts - ALWAYS include a fallback outcome for when the conversation stalls (e.g., "conversation exceeded N exchanges with no condition met" or "user does not want to reply") Wrong — putting behavior instructions in condition: "condition": "User agrees. If they ask questions, answer warmly and ask again" Right — behavior in prompt, condition is just the trigger: "prompt": "Explain the process. If the user has questions, answer them warmly. Once they're ready, confirm." "condition": "User explicitly agrees or says they are ready"
recapHtml	string	required	REQUIRED. Raw HTML/JS for the results/recap page. NO CDATA, NO markdown fences. Every visible string MUST come from `uiStrings` (via {{KEY}} or window.t('KEY')). Contract: reads window.__FACESIGN_SESSION__ (session data, re-populated on each poll), window.__FACESIGN_SESSION_ID__, window.__refetchSession() (returns Promise with updated data). The COMMON MISTAKES sections from the `landingHtml` field description apply here too — read them once and follow for both fields. For the complete session data shape (Session, SessionReport, NodeReport types, delayed vs immediate fields), read the `facesign://session-data-types` MCP resource. STYLE GUIDE (Results/Recap Page): Match this visual style for consistency with the FaceSign UI. Background: Light gray #f5f7fa with subtle gradient to light blue at top. Layout: Single-column, max-width 900px, centered (margin 0 auto), padding 2rem. Page header: "Session summary" bold 1.6rem. Subtitle with date/time and duration in muted color #888, font-size 0.9rem. User info card: White card with rounded photo (80-100px), grid of icon+text pairs for age, gender, location, device. Icons in muted blue #6b7faa. Section cards: White background, border-radius 12px, box-shadow 0 2px 12px rgba(0,0,0,.05), padding 1.5rem, margin-bottom 1.5rem. Section headings: Bold 1.15rem, color #1a1a2e, with small emoji/icon prefix (e.g. ✨ AI Analysis, 🔍 Detected Signals, 📋 Transcript). Margin-bottom 1rem. Status banners (full-width within card, border-radius 12px, padding 1rem 1.5rem, white text, bold): - Verified/success: background #4a9d6e, shield ✓ icon - High-risk/warning: background #d97b30, ⚠ warning icon Signal items: Left border 4px solid, padding-left 1rem, margin-bottom 1rem, background white or tinted. - Normal: border-color #059669, light green tint background #f0fdf4 - Suspicious: border-color #f59e0b, light yellow tint background #fefce8 - High-risk: border-color #ef4444, light red tint background #fef2f2 Status badges (inline, pill): border-radius 6px, padding 2px 10px, font-weight 700, font-size 0.8rem, uppercase. - RECOGNIZED/NORMAL: background #d1fae5, color #065f46 - SUSPICIOUS: background #fef3c7, color #92400e Confidence scores: Right-aligned, font-size 0.85rem, color #aaa. Key-value grid: Two-column layout. Label: small text, color #888, font-size 0.8rem, uppercase. Value: font-size 0.95rem, color #1a1a2e, below label. Transcript: Dark background #1e2a3a, border-radius 10px, padding 1.5rem, monospace font. "CONVERSATION LOG" header uppercase, small, muted. Each line: timestamp (gray #777), speaker label (FACESIGN: in teal #4db8a4, USER: in green #6bc96f), message text white. Line-height 1.8. Video: Centered, border-radius 8px, max-width 100%, dark container background. Font: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif. BEST PRACTICES FOR STABLE RENDERING (recapHtml): Session data arrives in two stages: some fields are available immediately when the session ends (user info, AI analysis, transcript), while others require polling. Video AI analysis may take up to 60 seconds; media usually arrives sooner. Naive implementations cause layout jumping (DOM rebuild on each poll) and duplicate network requests. ARCHITECTURE: Split Static vs Dynamic Rendering. renderStatic(data) — called ONCE: Renders all sections that won't change: user info (age, sex, location, device), aiAnalysis.overallSummary, aiAnalysis.analysis list, transcript, documentImages. updateDynamic(data) — called on each poll: Updates ONLY sections whose data arrives asynchronously: nodeReports, videoAIAnalysis, deepfakeDetection, and media (avatarVideo, screenshots). IMPORTANT: nodeReports is DELAYED — do NOT render node report data (face compare results, document scan results, etc.) in renderStatic(). Each dynamic section has its own wrapper element (e.g. <div id="video-ai-content">, <div id="node-reports-content">) so updates replace only that element's innerHTML, leaving the rest untouched. Track completion with boolean flags (videoAIDone, recordingDone, nodeReportsDone). Once a section is populated, skip further updates. Set videoAIDone when videoAIAnalysisStatus is either `succeeded` or `failed`. A failed analysis is terminal: replace the spinner with an unavailable message and do not interpret the missing result as clean evidence. If the status is absent, analysis was not requested, so omit the section. HTML STRUCTURE: <!-- Static sections: rendered once --> <div id="userinfo-card"></div> <div id="summary-card"></div> <div id="analysis-card"></div> <!-- Dynamic sections: inner content updated by polling --> <div id="video-ai-card"> <div class="card"> <div class="card-title">Video AI Analysis</div> <div id="video-ai-content"><!-- spinner initially, replaced when data arrives --></div> </div> </div> <div id="recording-card"> <div class="card"> <div class="card-title">Session Recording</div> <div id="recording-content"><!-- spinner initially, replaced when data arrives --></div> </div> </div> <!-- Static section: rendered once --> <div id="transcript-card"></div> POLLING: Single Entry Point with Guard (IIFE pattern): IMPORTANT: Polling MUST be limited — max 30 attempts, max 2 minutes total. Stop polling when limits are reached even if some data hasn't arrived. (function() { var polling = false; var pollCount = 0; var MAX_POLLS = 30; var startTime = Date.now(); var MAX_DURATION = 2 * 60 * 1000; // 2 minutes var videoAIDone = false; var recordingDone = false; var nodeReportsDone = false; function shouldStop() { return pollCount >= MAX_POLLS \|\| (Date.now() - startTime) >= MAX_DURATION; } function poll() { if (polling) return; if (shouldStop()) return; polling = true; pollCount++; if (typeof window.__refetchSession !== 'function') { polling = false; setTimeout(poll, 2000); return; } window.__refetchSession() .then(function(data) { polling = false; updateDynamic(data); if ((!videoAIDone \|\| !recordingDone \|\| !nodeReportsDone) && !shouldStop()) setTimeout(poll, 4000); }) .catch(function() { polling = false; if (!shouldStop()) setTimeout(poll, 4000); }); } function init() { var data = window.__FACESIGN_SESSION__; if (!data) return; renderStatic(data); var needMore = updateDynamic(data); if (needMore) setTimeout(poll, 4000); } if (window.__FACESIGN_SESSION__) { init(); } else { var chk = setInterval(function() { if (window.__FACESIGN_SESSION__) { clearInterval(chk); init(); } }, 500); } })(); KEY RULES: - Call renderStatic() exactly once — avoids DOM rebuild and layout jumps - updateDynamic() only touches dedicated container elements — no reflow outside the updated section - Use a polling boolean guard — prevents concurrent __refetchSession() calls - ALWAYS limit polling — max 30 attempts AND max 2 minutes total. Never poll indefinitely. - Use videoAIDone / recordingDone / nodeReportsDone flags — stops updating a section once its data has been rendered - For video AI, derive videoAIDone from videoAIAnalysisStatus, not from the presence of videoAIAnalysis alone - nodeReports is DELAYED — always render node report data (face compare, document scan, etc.) in updateDynamic(), never in renderStatic() - Single init() entry point via IIFE — eliminates duplicate initialization paths - Check typeof __refetchSession === 'function' before calling — handles the case where the API isn't injected yet - Use setTimeout not setInterval for polling — ensures the next poll starts only after the previous one completes - nodeReport.type is lowercase snake_case ("face_compare", "document_scan") — use case-insensitive comparison - Document scan report fields are Microblink nested objects — use a safe-value extractor function (see COMMON MISTAKES) - videoAIAnalysis criterion is camelCase — convert to human-readable with toStartCase() (see COMMON MISTAKES) SUMMARY: Render once, patch selectively, poll safely with limits. Static content is written to the DOM a single time. Dynamic content (nodeReports, videoAIAnalysis, media) targets specific container elements. Polling is serialized with a guard flag and stops as soon as all async data has arrived or limits are reached (max 30 attempts / 2 minutes).
uiStrings	object	required	REQUIRED. Per-language UI string dictionary: { langId: { key: translatedString } }. You invent the keys to match the {{KEY}} placeholders / window.t('KEY') calls in your landingHtml and recapHtml. Must contain an entry for `en` (ultimate runtime fallback) and for every language in `langs` (or every catalog language if `langs` is omitted). Every per-language dict must share the IDENTICAL set of keys. Example: { "en": { "START": "Start", "LOADING": "Loading..." }, "fr": { "START": "Commencer", "LOADING": "Chargement..." } }.

Raw schema

{
  "type": "object",
  "properties": {
    "flow": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "start"
              },
              "outcome": {
                "type": "string",
                "description": "The id of the next node"
              }
            },
            "required": [
              "id",
              "type",
              "outcome"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "end"
              }
            },
            "required": [
              "id",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "conversation"
              },
              "prompt": {
                "type": "string",
                "description": "What the avatar says to the user"
              },
              "doesNotRequireReply": {
                "type": "boolean",
                "description": "If true, avatar speaks without waiting for user reply"
              },
              "outcomes": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "targetNodeId": {
                      "type": "string",
                      "description": "The id of the node to route to"
                    },
                    "condition": {
                      "type": "string",
                      "description": "Condition description, e.g. \"default\", \"user says yes\""
                    }
                  },
                  "required": [
                    "id",
                    "targetNodeId",
                    "condition"
                  ],
                  "additionalProperties": false
                },
                "minItems": 1,
                "description": "Array of {id, targetNodeId, condition} routing entries"
              },
              "awaitExternal": {
                "type": "object",
                "properties": {
                  "request": {
                    "type": "object",
                    "properties": {
                      "url": {
                        "type": "string",
                        "description": "Endpoint to call (must pass the server-side allowlist). The current sessionId is appended automatically as a query parameter"
                      },
                      "method": {
                        "type": "string",
                        "enum": [
                          "GET",
                          "POST"
                        ],
                        "description": "HTTP method. Defaults to POST (JSON body); GET sends vars as query params"
                      },
                      "vars": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string",
                              "description": "Key under which the value is placed in the request payload"
                            },
                            "value": {
                              "anyOf": [
                                {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "const": "literal"
                                    },
                                    "value": {
                                      "type": [
                                        "string",
                                        "number",
                                        "boolean"
                                      ],
                                      "description": "The literal scalar value"
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "value"
                                  ],
                                  "additionalProperties": false
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "const": "ref"
                                    },
                                    "source": {
                                      "type": "string",
                                      "enum": [
                                        "extractedData",
                                        "providedData"
                                      ],
                                      "description": "Source to resolve the referenced value from"
                                    },
                                    "field": {
                                      "type": "string",
                                      "description": "The field/key name within the source"
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "source",
                                    "field"
                                  ],
                                  "additionalProperties": false
                                }
                              ],
                              "description": "Literal value or a reference resolved from session data"
                            }
                          },
                          "required": [
                            "name",
                            "value"
                          ],
                          "additionalProperties": false
                        },
                        "description": "Payload variables, each resolving to a literal or a session value"
                      }
                    },
                    "required": [
                      "url"
                    ],
                    "additionalProperties": false,
                    "description": "The endpoint to poll in the background"
                  },
                  "poll": {
                    "type": "object",
                    "properties": {
                      "intervalMs": {
                        "type": "number",
                        "description": "Delay between polls in milliseconds"
                      },
                      "timeoutMs": {
                        "type": "number",
                        "description": "Total time to keep polling before giving up"
                      }
                    },
                    "required": [
                      "intervalMs",
                      "timeoutMs"
                    ],
                    "additionalProperties": false,
                    "description": "Polling cadence and overall timeout"
                  },
                  "exits": {
                    "type": "object",
                    "properties": {
                      "onDataReady": {
                        "type": "string",
                        "description": "Node id when the endpoint returns HTTP 200 (result ready)"
                      },
                      "onTimeout": {
                        "type": "string",
                        "description": "Node id when poll.timeoutMs elapses first"
                      },
                      "onError": {
                        "type": "string",
                        "description": "Node id when the call errors"
                      }
                    },
                    "required": [
                      "onDataReady",
                      "onTimeout",
                      "onError"
                    ],
                    "additionalProperties": false,
                    "description": "Where to route when the background poll resolves"
                  }
                },
                "required": [
                  "request",
                  "poll",
                  "exits"
                ],
                "additionalProperties": false,
                "description": "Optional background poll: the avatar keeps talking (normal outcomes stay active) while an external result becomes ready; exits via onDataReady/onTimeout/onError"
              }
            },
            "required": [
              "id",
              "type",
              "prompt",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "liveness_detection"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "livenessDetected": {
                    "type": "string",
                    "description": "Node id when liveness is confirmed"
                  },
                  "deepfakeDetected": {
                    "type": "string",
                    "description": "Node id when deepfake is detected"
                  },
                  "noFace": {
                    "type": "string",
                    "description": "Node id when frames were captured but no face is on them"
                  },
                  "inconclusive": {
                    "type": "string",
                    "description": "Node id when the check produced no verdict — the detector could not decide, did not run, or there was nothing to analyse. This is our failure, not the user's: route it to a retry, a step-up or a manual review, never to the happy path by default"
                  }
                },
                "required": [
                  "livenessDetected",
                  "deepfakeDetected",
                  "noFace",
                  "inconclusive"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id. All four are required"
              }
            },
            "required": [
              "id",
              "type",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "enter_email"
              },
              "prompt": {
                "type": "string",
                "description": "Optional phrase the avatar says at the moment the email input field appears (direct speech, e.g. \"Could you please enter your email address?\"). Keep it short — one sentence. Omit to let the avatar stay silent while the field is shown."
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "emailEntered": {
                    "type": "string",
                    "description": "Node id when email is provided"
                  },
                  "canceled": {
                    "type": "string",
                    "description": "Node id when user cancels"
                  }
                },
                "required": [
                  "emailEntered",
                  "canceled"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "data_validation"
              },
              "validation": {
                "type": "object",
                "properties": {
                  "field": {
                    "type": "string"
                  },
                  "action": {
                    "type": "string"
                  },
                  "value": {
                    "type": "string"
                  }
                },
                "required": [
                  "field",
                  "action"
                ],
                "additionalProperties": false
              },
              "outcomes": {
                "type": "array",
                "items": {
                  "$ref": "#/properties/flow/items/anyOf/2/properties/outcomes/items"
                },
                "minItems": 1,
                "description": "Array of {id, targetNodeId, condition} routing entries"
              }
            },
            "required": [
              "id",
              "type",
              "validation",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "document_scan"
              },
              "scanningMode": {
                "type": "string",
                "enum": [
                  "single",
                  "automatic"
                ],
                "description": "Scanning mode"
              },
              "allowedDocumentTypes": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minItems": 1,
                "description": "Allowed document types, e.g. [\"id\", \"passport\", \"dl\"]"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "scanSuccess": {
                    "type": "string",
                    "description": "Node id on successful scan"
                  },
                  "userCancelled": {
                    "type": "string",
                    "description": "Node id when user cancels"
                  },
                  "scanTimeout": {
                    "type": "string",
                    "description": "Node id on scan timeout"
                  }
                },
                "required": [
                  "scanSuccess",
                  "userCancelled",
                  "scanTimeout"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "scanningMode",
              "allowedDocumentTypes",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "recognition"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "recognized": {
                    "type": "string",
                    "description": "Node id when user is recognized"
                  },
                  "newUser": {
                    "type": "string",
                    "description": "Node id when user is new"
                  },
                  "noFace": {
                    "type": "string",
                    "description": "Node id when no face is found"
                  }
                },
                "required": [
                  "recognized",
                  "newUser",
                  "noFace"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "face_scan"
              },
              "captureInstructions": {
                "type": "string"
              },
              "requireLivenessChallenge": {
                "type": "boolean"
              },
              "requireAILivenessCheck": {
                "type": "boolean"
              },
              "similarityThreshold": {
                "type": "number",
                "description": "0-1, how similar faces must be"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "passed": {
                    "type": "string",
                    "description": "Node id when face scan passes"
                  },
                  "notPassed": {
                    "type": "string",
                    "description": "Node id when face scan fails"
                  },
                  "cancelled": {
                    "type": "string",
                    "description": "Node id when user cancels"
                  },
                  "error": {
                    "type": "string",
                    "description": "Node id on error"
                  }
                },
                "required": [
                  "passed",
                  "notPassed",
                  "cancelled",
                  "error"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "two_factor_email"
              },
              "otpLength": {
                "type": "number",
                "description": "OTP length 4-8, default 6"
              },
              "expirySeconds": {
                "type": "number",
                "description": "OTP expiry in seconds, default 300"
              },
              "maxAttempts": {
                "type": "number",
                "description": "Max verification attempts, default 3"
              },
              "resendAfterSeconds": {
                "type": "number",
                "description": "Seconds before allowing OTP resend"
              },
              "showUI": {
                "type": "boolean",
                "description": "Whether to show the OTP input UI"
              },
              "emailTemplate": {
                "type": "string"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "verified": {
                    "type": "string",
                    "description": "Node id when OTP verified"
                  },
                  "delivery_failed": {
                    "type": "string",
                    "description": "Node id when delivery fails"
                  },
                  "failed_unverified": {
                    "type": "string",
                    "description": "Node id when max attempts exhausted"
                  },
                  "cancelled": {
                    "type": "string",
                    "description": "Node id when user cancels"
                  },
                  "error": {
                    "type": "string",
                    "description": "Node id on error"
                  }
                },
                "required": [
                  "verified",
                  "delivery_failed",
                  "failed_unverified",
                  "cancelled",
                  "error"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "two_factor_sms"
              },
              "otpLength": {
                "type": "number",
                "description": "OTP length 4-8, default 6"
              },
              "expirySeconds": {
                "type": "number",
                "description": "OTP expiry in seconds, default 300"
              },
              "maxAttempts": {
                "type": "number",
                "description": "Max verification attempts, default 3"
              },
              "resendAfterSeconds": {
                "type": "number",
                "description": "Seconds before allowing OTP resend"
              },
              "showUI": {
                "type": "boolean",
                "description": "Whether to show the OTP input UI"
              },
              "smsTemplate": {
                "type": "string"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "verified": {
                    "type": "string",
                    "description": "Node id when OTP verified"
                  },
                  "delivery_failed": {
                    "type": "string",
                    "description": "Node id when delivery fails"
                  },
                  "failed_unverified": {
                    "type": "string",
                    "description": "Node id when max attempts exhausted"
                  },
                  "cancelled": {
                    "type": "string",
                    "description": "Node id when user cancels"
                  },
                  "error": {
                    "type": "string",
                    "description": "Node id on error"
                  }
                },
                "required": [
                  "verified",
                  "delivery_failed",
                  "failed_unverified",
                  "cancelled",
                  "error"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "permissions"
              },
              "prompt": {
                "type": "string",
                "description": "Optional message the avatar says (direct speech mode, e.g. 'Say: Please enable your camera.')"
              },
              "permissions": {
                "type": "object",
                "properties": {
                  "camera": {
                    "type": "boolean",
                    "description": "Request camera access"
                  },
                  "microphone": {
                    "type": "boolean",
                    "description": "Request microphone access"
                  }
                },
                "additionalProperties": false,
                "description": "Which permissions to request"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "permissionsGranted": {
                    "type": "string",
                    "description": "Node id when permissions are granted"
                  },
                  "permissionsDenied": {
                    "type": "string",
                    "description": "Node id when permissions are denied"
                  }
                },
                "required": [
                  "permissionsGranted",
                  "permissionsDenied"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "permissions",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "face_compare"
              },
              "sourceA": {
                "type": "object",
                "properties": {
                  "source": {
                    "type": "string",
                    "enum": [
                      "sessionVideo",
                      "faceScan",
                      "providedData",
                      "documentPhoto"
                    ],
                    "description": "Source of the face image"
                  },
                  "providedDataKey": {
                    "type": "string",
                    "description": "Required when source is 'providedData' — the key in providedData that holds the image URL"
                  }
                },
                "required": [
                  "source"
                ],
                "additionalProperties": false,
                "description": "First face image source"
              },
              "sourceB": {
                "type": "object",
                "properties": {
                  "source": {
                    "$ref": "#/properties/flow/items/anyOf/12/properties/sourceA/properties/source"
                  },
                  "providedDataKey": {
                    "$ref": "#/properties/flow/items/anyOf/12/properties/sourceA/properties/providedDataKey"
                  }
                },
                "required": [
                  "source"
                ],
                "additionalProperties": false,
                "description": "Second face image source"
              },
              "similarityThreshold": {
                "type": "number",
                "description": "0-1, minimum similarity score required for a match"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "match": {
                    "type": "string",
                    "description": "Node id when faces match"
                  },
                  "noMatch": {
                    "type": "string",
                    "description": "Node id when faces do not match"
                  },
                  "imageUnavailable": {
                    "type": "string",
                    "description": "Node id when one or both images could not be obtained"
                  }
                },
                "required": [
                  "match",
                  "noMatch",
                  "imageUnavailable"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "sourceA",
              "sourceB",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "external_call"
              },
              "request": {
                "type": "object",
                "properties": {
                  "url": {
                    "$ref": "#/properties/flow/items/anyOf/2/properties/awaitExternal/properties/request/properties/url"
                  },
                  "method": {
                    "$ref": "#/properties/flow/items/anyOf/2/properties/awaitExternal/properties/request/properties/method"
                  },
                  "vars": {
                    "$ref": "#/properties/flow/items/anyOf/2/properties/awaitExternal/properties/request/properties/vars"
                  }
                },
                "required": [
                  "url"
                ],
                "additionalProperties": false,
                "description": "The external endpoint to call and the payload to send"
              },
              "outcome": {
                "type": "string",
                "description": "Node id to advance to after the response is merged into providedData (never branches)"
              }
            },
            "required": [
              "id",
              "type",
              "request",
              "outcome"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "field_condition"
              },
              "rules": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "left": {
                      "type": "object",
                      "properties": {
                        "source": {
                          "type": "string",
                          "enum": [
                            "extractedData",
                            "providedData"
                          ],
                          "description": "Where the value is read from: 'extractedData' (a field from extractionSchema, extracted on demand from the transcript) or 'providedData' (a key set at creation or written by a prior external_call)"
                        },
                        "field": {
                          "type": "string",
                          "description": "The field/key name within the source"
                        }
                      },
                      "required": [
                        "source",
                        "field"
                      ],
                      "additionalProperties": false,
                      "description": "Reference to the session value to test"
                    },
                    "operator": {
                      "type": "string",
                      "enum": [
                        "equals",
                        "notEquals",
                        "gt",
                        "lt",
                        "gte",
                        "lte",
                        "exists",
                        "notExists"
                      ],
                      "description": "Comparison operator (omit 'right' for 'exists'/'notExists')"
                    },
                    "right": {
                      "anyOf": [
                        {
                          "$ref": "#/properties/flow/items/anyOf/2/properties/awaitExternal/properties/request/properties/vars/items/properties/value/anyOf/0"
                        },
                        {
                          "$ref": "#/properties/flow/items/anyOf/2/properties/awaitExternal/properties/request/properties/vars/items/properties/value/anyOf/1"
                        }
                      ],
                      "description": "Literal or reference to compare against; omit for 'exists'/'notExists'"
                    },
                    "outcome": {
                      "type": "string",
                      "description": "Node id to route to when this rule matches"
                    }
                  },
                  "required": [
                    "left",
                    "operator",
                    "outcome"
                  ],
                  "additionalProperties": false
                },
                "minItems": 1,
                "description": "Rules evaluated top-to-bottom; first match wins"
              },
              "default": {
                "type": "string",
                "description": "Node id to route to when no rule matches"
              }
            },
            "required": [
              "id",
              "type",
              "rules",
              "default"
            ],
            "additionalProperties": false
          }
        ]
      },
      "description": "Array of nodes forming the session's directed graph"
    },
    "avatarId": {
      "type": "string",
      "description": "Avatar ID from the facesign://catalog resource."
    },
    "langs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional whitelist of BCP-47 language codes (from facesign://catalog) the session may use. DEFAULT BEHAVIOUR (recommended): OMIT this parameter entirely — the session then supports every language in the FaceSign catalog, and `uiStrings` must cover every catalog language. ONLY set `langs` when the user EXPLICITLY restricts the language set (e.g. 'Spanish-only demo', 'support English and Russian'). Do NOT narrow to `['en']` just because the user described the demo in English or did not mention languages — that would silently drop multilingual support. Example (explicit restriction): [\"en\", \"es\", \"ru\"]. The set of target languages for `uiStrings` is derived from this list (or the full catalog if omitted)."
    },
    "defaultLang": {
      "type": "string",
      "description": "Optional fallback BCP-47 language code used when the end-user's browser language is not in `langs`. DEFAULT BEHAVIOUR: OMIT this parameter. The MCP server falls back to 'en' internally only as a last-resort for UI string lookup; you should not hardcode a default language here unless the user explicitly asks for one. When set, must be one of the codes in `langs` (if `langs` is also set)."
    },
    "zone": {
      "type": "string",
      "enum": [
        "us",
        "eu"
      ],
      "description": "Data processing zone"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Arbitrary metadata to attach"
    },
    "clientReferenceId": {
      "type": "string",
      "description": "Your own reference ID for this session"
    },
    "providedData": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "phone": {
          "type": "string"
        }
      },
      "additionalProperties": true,
      "description": "Pre-known user data"
    },
    "videoAIAnalysisEnabled": {
      "type": "boolean",
      "description": "Enable video AI fraud analysis"
    },
    "extractionSchema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fieldName": {
            "type": "string",
            "description": "Key under which the extracted value appears in session.report.extractedData."
          },
          "type": {
            "type": "string",
            "enum": [
              "string",
              "number",
              "boolean",
              "date"
            ],
            "description": "Expected value type. `date` is returned as an ISO 8601 string."
          },
          "description": {
            "type": "string",
            "description": "Natural-language hint for the LLM describing what to look for in the transcript. This is the primary extraction signal — be specific (e.g. \"the user's full legal name\" rather than \"name\")."
          },
          "enum": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional allowed string values. When set, the LLM normalizes free-form answers (e.g. \"yeah\", \"sure\") into one of the listed values. Recommended for yes/no or fixed-choice questions."
          }
        },
        "required": [
          "fieldName",
          "type",
          "description"
        ],
        "additionalProperties": false
      },
      "description": "Optional schema describing fields the FaceSign backend should extract from the session transcript using an LLM. Results are populated post-session at `session.report.extractedData` as `{ [fieldName]: string | number | boolean | null }` (null when the transcript did not contain the data — every field is treated as optional). Use this for structured data collection that does NOT need its own dedicated node — e.g. follow-up questions in a single CONVERSATION node where you'd otherwise have to author multiple branching outcomes. The conversation flow itself is unaffected; extraction runs on the final transcript. Render the results in your recapHtml when present."
    },
    "customization": {
      "type": "object",
      "properties": {
        "permissionsPage": {
          "type": "object",
          "properties": {
            "buttonText": {
              "type": "string"
            },
            "mainHeading": {
              "type": "string"
            },
            "subheading": {
              "type": "string"
            },
            "backgroundType": {
              "type": "string",
              "enum": [
                "AVATAR",
                "COLOR"
              ]
            },
            "backgroundColor": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "controls": {
          "type": "object",
          "properties": {
            "showUxControls": {
              "type": "boolean",
              "description": "Master switch for the in-session control panel. When false the panel is not rendered and every other controls.* setting has no effect"
            },
            "captionsOpenedByDefault": {
              "type": "boolean",
              "description": "Start the session with the closed-captions (transcript) panel open. Omitted or false keeps it closed. The user can toggle it with the CC button either way. Set it for accessibility, or when viewers may be reading along in a second language. Ignored when showUxControls is false"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false,
      "description": "UI customization"
    },
    "landingHtml": {
      "type": "string",
      "description": "REQUIRED. Raw HTML/JS for the pre-session landing page. NO CDATA, NO markdown fences. Every visible string MUST come from `uiStrings` — reference them via {{KEY}} placeholders (interpolated at inject time) or via window.t('KEY') (dynamic at runtime). Contract: reads window.__FACESIGN_FLOW__ (the flow array). MUST call window.__startSession(updatedFlow?) to launch the session. The session iframe has its own Start button for audio/video autoplay gesture — the landing page does NOT need one for that purpose.\n\nSTYLE GUIDE (Pre-Session Page):\nMatch this visual style for consistency with the FaceSign UI.\n\nBackground: Light gray #f5f7fa. Full-viewport centered layout (flexbox, min-height: 100vh; min-height: 100dvh — always use dvh with vh fallback for iOS compatibility).\n\nCard: White, border-radius 16px, box-shadow 0 4px 24px rgba(0,0,0,.08), padding 2.5-3rem, max-width 480-600px, centered.\n\nHeadings: Bold, 1.4-1.8rem, color #1a1a2e, centered in card.\n\nInputs: Full-width, padding 14px 16px, border 2px solid #d1d5db, border-radius 12px, font-size 1rem. Focus: border-color #5b7bab. Placeholder color #9ca3af.\n\nPrimary buttons: Background #7b8fb5 (steel-blue), color white, font-weight 600, font-size 1.05rem, border-radius 50px (pill shape), padding 14px, full-width in card. Hover: background #6a7fa5. Disabled: background #c5cdd8, cursor not-allowed.\n\nLinks: Color #4573b8, no underline, underline on hover. Back navigation: \"← Back\" at top-left of card, color #4573b8, font-size 0.95rem.\n\nProfile images: Circular (border-radius 50%), 120-150px diameter, centered, subtle box-shadow.\n\nSpacing: 2.5-3rem card padding, 1.5rem between form groups, 1rem between label and input, 2rem above primary button.\n\nFont: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif.\n\n\nCOMMON MISTAKES TO AVOID (UI/CSS):\n\n1. Never set padding or margin on body\nThe custom HTML is injected into a host page that controls its own layout. Setting padding, margin, or min-height on body will conflict with the host page styles and create unwanted spacing.\n\nWrong:\nbody { padding: 2rem; min-height: 100vh; }\n(Also wrong — using only 100vh without dvh fallback. Always add min-height: 100dvh after 100vh for iOS Safari.)\n\nRight — use a wrapper element instead:\nbody { margin: 0; padding: 0; }\n.wrap { max-width: 860px; margin: 0 auto; padding: 2rem; }\n\nThe same applies to background on body — avoid it unless you are certain the host page does not set its own background.\n\n2. Use HTML entities for emoji, not JS unicode escapes\nWhen building HTML strings in JavaScript (via innerHTML, string concatenation, etc.), JS unicode escapes like \\ud83c\\udfa5 will NOT render as emoji. They only work inside JS string literals that are directly displayed via textContent or similar APIs.\n\nWrong — renders as garbled text:\nh += '<div class=\"title\">\\ud83c\\udfa5 Video AI Analysis</div>';\n\nRight — use HTML numeric entities:\nh += '<div class=\"title\">&#127909; Video AI Analysis</div>';\n\nAlso right — use emoji directly in static HTML (outside of JS):\n<div class=\"title\">🎥 Video AI Analysis</div>\n\nCommon emoji HTML entities reference:\n&#128100; 👤 User/person\n&#127874; 🎂 Birthday cake\n&#128205; 📍 Pin/location\n&#128187; 💻 Computer\n&#10024;  ✨ Sparkles\n&#128269; 🔍 Search\n&#127909; 🎥 Camera\n&#127916; 🎬 Clapper board\n&#128203; 📋 Clipboard\n&#9895;   ⚧ Gender symbol\n&#10003;  ✓ Checkmark\n\n3. CSS class name collision between landingHtml and recapHtml\nCRITICAL: landingHtml and recapHtml are injected into the SAME host document. If both fragments use the same class names (e.g., .card, .container, .header), styles from one will leak into the other, causing layout breakage.\n\nALWAYS use unique prefixed class names:\n- landingHtml (pre-session/landing page): prefix all classes with .lp- (e.g., .lp-card, .lp-header, .lp-btn)\n- recapHtml (results page): prefix all classes with .r- (e.g., .r-card, .r-header, .r-wrap)\n\nWrong — causes collisions:\n/* in landingHtml */  .card { max-width: 460px; }\n/* in recapHtml */    .card { max-width: 900px; }\n\nRight — namespaced:\n/* in landingHtml */  .lp-card { max-width: 460px; }\n/* in recapHtml */    .r-card { max-width: 900px; }\n\n\nCOMMON MISTAKES TO AVOID (Code/API):\n\n4. window.__startSession race condition\nNEVER call window.__startSession() synchronously in a click handler. The host page may not have injected the function yet. ALWAYS use polling:\n\nfunction waitAndStart(input) {\n  var n = 0;\n  var iv = setInterval(function() {\n    n++;\n    if (typeof window.__startSession === 'function') {\n      clearInterval(iv);\n      window.__startSession(input);\n    } else if (n > 100) {\n      clearInterval(iv);\n      document.body.innerHTML = '<p style=\"text-align:center;padding:2rem;color:red;\">Failed to initialize session. Please refresh.</p>';\n    }\n  }, 100);\n}\n\nWrong:\nstartBtn.addEventListener('click', function() { window.__startSession(); });\n\nRight:\nstartBtn.addEventListener('click', function() { waitAndStart(); });\n\nFor exported apps, NEVER send window.__FACESIGN_FLOW__ or another graph back to\nthe server. To select a flow declared in export_app, pass its ID:\nwaitAndStart({ flowId: 'enhanced', providedData: { name: nameInput.value } });\n\n5. Permissions are automatic — do NOT add a permissions node by default\nFaceSign automatically requests camera and microphone permissions at session start. Most flows do NOT need a PERMISSIONS node. Only add one in these specific cases:\n(a) The user wants to request microphone and camera permissions separately at different times during the flow (instead of both at once at session start).\n(b) The user wants to move the permission request to the initial page (landingHtml), outside the FaceSign flow itself.\n\n6. nodeReport.type values are lowercase snake_case\nThe API returns nodeReport.type in lowercase snake_case: \"face_compare\", \"document_scan\", \"conversation\", \"permissions\", \"liveness_detection\", etc. — NOT uppercase like \"FACE_COMPARE\".\n\nALWAYS use case-insensitive comparison when looking up node reports:\n\nfunction getNode(r, type) {\n  var rr = (r && r.nodeReports) || [];\n  var tl = type.toLowerCase();\n  for (var i = 0; i < rr.length; i++) {\n    if (rr[i].type && rr[i].type.toLowerCase() === tl) return rr[i];\n  }\n  return null;\n}\n\n// Usage: getNode(report, 'face_compare'), getNode(report, 'document_scan')\n\n7. Microblink document report — nested field structure\nDOCUMENT_SCAN nodeReport.report fields are NOT plain strings. They use Microblink's nested structure:\n  firstName: { latin: { value: \"JANICE\" } }\n  dateOfBirth: { originalString: { latin: { value: \"04/30/1970\" } } }\n  — OR —\n  dateOfBirth: { day: 30, month: 4, year: 1970 }\n\nNEVER read fields directly as strings (e.g., dr.firstName will be an object, not \"JANICE\").\n\nALWAYS use this safe-value extractor:\n\nfunction sv(v) {\n  if (v == null) return '';\n  if (typeof v === 'string') return v;\n  if (v.latin && v.latin.value != null) return String(v.latin.value);\n  if (v.originalString) return sv(v.originalString);\n  if (v.day != null && v.month != null && v.year != null)\n    return v.month + '/' + v.day + '/' + v.year;\n  return '';\n}\n\n// Usage: sv(dr.firstName) → \"JANICE\", sv(dr.dateOfBirth) → \"04/30/1970\"\n\n8. videoAIAnalysis criterion is camelCase — format for display\nThe criterion field (e.g., \"facialExpressionAndMovement\", \"useOfExternalDevices\") comes in camelCase. Convert to human-readable format:\n\nfunction toStartCase(s) {\n  if (!s) return '';\n  return s.replace(/([A-Z]+)/g, function(m) { return ' ' + m.toLowerCase(); })\n    .trim().replace(/^./, function(c) { return c.toUpperCase(); });\n}\n// \"facialExpressionAndMovement\" → \"Facial expression and movement\"\n\n9. Conversation node: condition vs prompt\nIn CONVERSATION nodes:\n- \"condition\" (in outcomes) = ONLY describes the trigger event for transitioning to the next node (e.g., \"User explicitly agrees to proceed\")\n- \"prompt\" = ALL instructions for the avatar's behavior, including how to greet, how to respond to questions, how to handle objections, and how to persuade\n- User questions or objections during the conversation are handled within the SAME node (continued dialog), NOT via separate outcomes\n- Conversation nodes can have any number of outcomes depending on the use case:\n  * Branching nodes (e.g., \"what color?\") → one outcome per branch + a fallback\n  * Consent/agreement nodes → typically 2: agreement + fallback after N attempts\n- ALWAYS include a fallback outcome for when the conversation stalls (e.g., \"conversation exceeded N exchanges with no condition met\" or \"user does not want to reply\")\n\nWrong — putting behavior instructions in condition:\n\"condition\": \"User agrees. If they ask questions, answer warmly and ask again\"\n\nRight — behavior in prompt, condition is just the trigger:\n\"prompt\": \"Explain the process. If the user has questions, answer them warmly. Once they're ready, confirm.\"\n\"condition\": \"User explicitly agrees or says they are ready\""
    },
    "recapHtml": {
      "type": "string",
      "description": "REQUIRED. Raw HTML/JS for the results/recap page. NO CDATA, NO markdown fences. Every visible string MUST come from `uiStrings` (via {{KEY}} or window.t('KEY')). Contract: reads window.__FACESIGN_SESSION__ (session data, re-populated on each poll), window.__FACESIGN_SESSION_ID__, window.__refetchSession() (returns Promise with updated data). The COMMON MISTAKES sections from the `landingHtml` field description apply here too — read them once and follow for both fields. For the complete session data shape (Session, SessionReport, NodeReport types, delayed vs immediate fields), read the `facesign://session-data-types` MCP resource.\n\nSTYLE GUIDE (Results/Recap Page):\nMatch this visual style for consistency with the FaceSign UI.\n\nBackground: Light gray #f5f7fa with subtle gradient to light blue at top.\n\nLayout: Single-column, max-width 900px, centered (margin 0 auto), padding 2rem.\n\nPage header: \"Session summary\" bold 1.6rem. Subtitle with date/time and duration in muted color #888, font-size 0.9rem.\n\nUser info card: White card with rounded photo (80-100px), grid of icon+text pairs for age, gender, location, device. Icons in muted blue #6b7faa.\n\nSection cards: White background, border-radius 12px, box-shadow 0 2px 12px rgba(0,0,0,.05), padding 1.5rem, margin-bottom 1.5rem.\n\nSection headings: Bold 1.15rem, color #1a1a2e, with small emoji/icon prefix (e.g. ✨ AI Analysis, 🔍 Detected Signals, 📋 Transcript). Margin-bottom 1rem.\n\nStatus banners (full-width within card, border-radius 12px, padding 1rem 1.5rem, white text, bold):\n- Verified/success: background #4a9d6e, shield ✓ icon\n- High-risk/warning: background #d97b30, ⚠ warning icon\n\nSignal items: Left border 4px solid, padding-left 1rem, margin-bottom 1rem, background white or tinted.\n- Normal: border-color #059669, light green tint background #f0fdf4\n- Suspicious: border-color #f59e0b, light yellow tint background #fefce8\n- High-risk: border-color #ef4444, light red tint background #fef2f2\n\nStatus badges (inline, pill): border-radius 6px, padding 2px 10px, font-weight 700, font-size 0.8rem, uppercase.\n- RECOGNIZED/NORMAL: background #d1fae5, color #065f46\n- SUSPICIOUS: background #fef3c7, color #92400e\n\nConfidence scores: Right-aligned, font-size 0.85rem, color #aaa.\n\nKey-value grid: Two-column layout. Label: small text, color #888, font-size 0.8rem, uppercase. Value: font-size 0.95rem, color #1a1a2e, below label.\n\nTranscript: Dark background #1e2a3a, border-radius 10px, padding 1.5rem, monospace font. \"CONVERSATION LOG\" header uppercase, small, muted. Each line: timestamp (gray #777), speaker label (FACESIGN: in teal #4db8a4, USER: in green #6bc96f), message text white. Line-height 1.8.\n\nVideo: Centered, border-radius 8px, max-width 100%, dark container background.\n\nFont: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif.\n\n\nBEST PRACTICES FOR STABLE RENDERING (recapHtml):\n\nSession data arrives in two stages: some fields are available immediately when the session ends (user info, AI analysis, transcript), while others require polling. Video AI analysis may take up to 60 seconds; media usually arrives sooner. Naive implementations cause layout jumping (DOM rebuild on each poll) and duplicate network requests.\n\nARCHITECTURE: Split Static vs Dynamic Rendering.\n\nrenderStatic(data) — called ONCE:\nRenders all sections that won't change: user info (age, sex, location, device), aiAnalysis.overallSummary, aiAnalysis.analysis list, transcript, documentImages.\n\nupdateDynamic(data) — called on each poll:\nUpdates ONLY sections whose data arrives asynchronously: nodeReports, videoAIAnalysis, deepfakeDetection, and media (avatarVideo, screenshots).\nIMPORTANT: nodeReports is DELAYED — do NOT render node report data (face compare results, document scan results, etc.) in renderStatic().\nEach dynamic section has its own wrapper element (e.g. <div id=\"video-ai-content\">, <div id=\"node-reports-content\">) so updates replace only that element's innerHTML, leaving the rest untouched.\nTrack completion with boolean flags (videoAIDone, recordingDone, nodeReportsDone). Once a section is populated, skip further updates.\nSet videoAIDone when videoAIAnalysisStatus is either `succeeded` or `failed`. A failed analysis is terminal: replace the spinner with an unavailable message and do not interpret the missing result as clean evidence. If the status is absent, analysis was not requested, so omit the section.\n\nHTML STRUCTURE:\n<!-- Static sections: rendered once -->\n<div id=\"userinfo-card\"></div>\n<div id=\"summary-card\"></div>\n<div id=\"analysis-card\"></div>\n\n<!-- Dynamic sections: inner content updated by polling -->\n<div id=\"video-ai-card\">\n  <div class=\"card\">\n    <div class=\"card-title\">Video AI Analysis</div>\n    <div id=\"video-ai-content\"><!-- spinner initially, replaced when data arrives --></div>\n  </div>\n</div>\n\n<div id=\"recording-card\">\n  <div class=\"card\">\n    <div class=\"card-title\">Session Recording</div>\n    <div id=\"recording-content\"><!-- spinner initially, replaced when data arrives --></div>\n  </div>\n</div>\n\n<!-- Static section: rendered once -->\n<div id=\"transcript-card\"></div>\n\nPOLLING: Single Entry Point with Guard (IIFE pattern):\nIMPORTANT: Polling MUST be limited — max 30 attempts, max 2 minutes total. Stop polling when limits are reached even if some data hasn't arrived.\n(function() {\n  var polling = false;\n  var pollCount = 0;\n  var MAX_POLLS = 30;\n  var startTime = Date.now();\n  var MAX_DURATION = 2 * 60 * 1000; // 2 minutes\n  var videoAIDone = false;\n  var recordingDone = false;\n  var nodeReportsDone = false;\n\n  function shouldStop() {\n    return pollCount >= MAX_POLLS || (Date.now() - startTime) >= MAX_DURATION;\n  }\n\n  function poll() {\n    if (polling) return;\n    if (shouldStop()) return;\n    polling = true;\n    pollCount++;\n    if (typeof window.__refetchSession !== 'function') {\n      polling = false;\n      setTimeout(poll, 2000);\n      return;\n    }\n    window.__refetchSession()\n      .then(function(data) {\n        polling = false;\n        updateDynamic(data);\n        if ((!videoAIDone || !recordingDone || !nodeReportsDone) && !shouldStop()) setTimeout(poll, 4000);\n      })\n      .catch(function() {\n        polling = false;\n        if (!shouldStop()) setTimeout(poll, 4000);\n      });\n  }\n\n  function init() {\n    var data = window.__FACESIGN_SESSION__;\n    if (!data) return;\n    renderStatic(data);\n    var needMore = updateDynamic(data);\n    if (needMore) setTimeout(poll, 4000);\n  }\n\n  if (window.__FACESIGN_SESSION__) {\n    init();\n  } else {\n    var chk = setInterval(function() {\n      if (window.__FACESIGN_SESSION__) { clearInterval(chk); init(); }\n    }, 500);\n  }\n})();\n\nKEY RULES:\n- Call renderStatic() exactly once — avoids DOM rebuild and layout jumps\n- updateDynamic() only touches dedicated container elements — no reflow outside the updated section\n- Use a polling boolean guard — prevents concurrent __refetchSession() calls\n- ALWAYS limit polling — max 30 attempts AND max 2 minutes total. Never poll indefinitely.\n- Use videoAIDone / recordingDone / nodeReportsDone flags — stops updating a section once its data has been rendered\n- For video AI, derive videoAIDone from videoAIAnalysisStatus, not from the presence of videoAIAnalysis alone\n- nodeReports is DELAYED — always render node report data (face compare, document scan, etc.) in updateDynamic(), never in renderStatic()\n- Single init() entry point via IIFE — eliminates duplicate initialization paths\n- Check typeof __refetchSession === 'function' before calling — handles the case where the API isn't injected yet\n- Use setTimeout not setInterval for polling — ensures the next poll starts only after the previous one completes\n- nodeReport.type is lowercase snake_case (\"face_compare\", \"document_scan\") — use case-insensitive comparison\n- Document scan report fields are Microblink nested objects — use a safe-value extractor function (see COMMON MISTAKES)\n- videoAIAnalysis criterion is camelCase — convert to human-readable with toStartCase() (see COMMON MISTAKES)\n\nSUMMARY: Render once, patch selectively, poll safely with limits. Static content is written to the DOM a single time. Dynamic content (nodeReports, videoAIAnalysis, media) targets specific container elements. Polling is serialized with a guard flag and stops as soon as all async data has arrived or limits are reached (max 30 attempts / 2 minutes)."
    },
    "uiStrings": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        }
      },
      "description": "REQUIRED. Per-language UI string dictionary: { langId: { key: translatedString } }. You invent the keys to match the {{KEY}} placeholders / window.t('KEY') calls in your landingHtml and recapHtml. Must contain an entry for `en` (ultimate runtime fallback) and for every language in `langs` (or every catalog language if `langs` is omitted). Every per-language dict must share the IDENTICAL set of keys. Example: { \"en\": { \"START\": \"Start\", \"LOADING\": \"Loading...\" }, \"fr\": { \"START\": \"Commencer\", \"LOADING\": \"Chargement...\" } }."
    }
  },
  "required": [
    "flow",
    "landingHtml",
    "recapHtml",
    "uiStrings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

export_app

Export the current FaceSign session configuration as a standalone, deployable Next.js application. You MUST supply `landingHtml` (pre-session page), `recapHtml` (results page), and `uiStrings` (per-language dictionary whose keys are invented by you to match placeholders in the HTML). The exported app ships NO default chrome — every visible string comes from you. Run with `npm install && npm run dev` or deploy to Vercel after setting FACESIGN_API_KEY.

Parameters16

flow	array	required	Array of nodes forming the session's directed graph
flowVariants	object	optional	Optional additional flows declared at export time. The landing page selects one by calling window.__startSession({ flowId: 'variant-id' }); the browser never sends a graph.
avatarId	string	optional	Avatar ID from the facesign://catalog resource.
langs	array	optional	Optional whitelist of BCP-47 language codes (from facesign://catalog) the exported session may use. DEFAULT BEHAVIOUR (recommended): OMIT this parameter entirely — the app then supports every language in the FaceSign catalog, and `uiStrings` must cover every catalog language. ONLY set `langs` when the user EXPLICITLY restricts the language set (e.g. 'Spanish-only demo', 'support English and Russian'). Do NOT narrow to `['en']` just because the user described the demo in English or did not mention languages. Example (explicit restriction): ["en", "es", "ru"]. The set of target languages for `uiStrings` is derived from this list (or the full catalog if omitted).
defaultLang	string	optional	Optional fallback BCP-47 language code used when the end-user's browser language is not in `langs`. DEFAULT BEHAVIOUR: OMIT this parameter. When set, must be one of the codes in `langs` (if `langs` is also set).
zone	string	optional	Data processing zone
metadata	object	optional	Arbitrary metadata to attach
clientReferenceId	string	optional	Your own reference ID for this session
providedData	object	optional	Pre-known user data
videoAIAnalysisEnabled	boolean	optional	Enable video AI fraud analysis
extractionSchema	array	optional	Optional schema describing fields the FaceSign backend should extract from the session transcript using an LLM. Results are populated post-session at `session.report.extractedData` as `{ [fieldName]: string \| number \| boolean \| null }` (null when the transcript did not contain the data). Render results in your recapHtml when present.
customization	object	optional	UI customization
landingHtml	string	required	REQUIRED. Raw HTML/JS for the pre-session landing page. NO CDATA, NO markdown fences. Every visible string MUST come from `uiStrings` — reference them via {{KEY}} placeholders (interpolated at inject time) or via window.t('KEY') (dynamic at runtime). Contract: reads window.__FACESIGN_FLOW__ (the default flow, for display only). MUST call window.__startSession(input?) to launch the session. input may contain only a declared flowId and/or providedData collected by the form; never pass a flow graph from the browser. STYLE GUIDE (Pre-Session Page): Match this visual style for consistency with the FaceSign UI. Background: Light gray #f5f7fa. Full-viewport centered layout (flexbox, min-height: 100vh; min-height: 100dvh — always use dvh with vh fallback for iOS compatibility). Card: White, border-radius 16px, box-shadow 0 4px 24px rgba(0,0,0,.08), padding 2.5-3rem, max-width 480-600px, centered. Headings: Bold, 1.4-1.8rem, color #1a1a2e, centered in card. Inputs: Full-width, padding 14px 16px, border 2px solid #d1d5db, border-radius 12px, font-size 1rem. Focus: border-color #5b7bab. Placeholder color #9ca3af. Primary buttons: Background #7b8fb5 (steel-blue), color white, font-weight 600, font-size 1.05rem, border-radius 50px (pill shape), padding 14px, full-width in card. Hover: background #6a7fa5. Disabled: background #c5cdd8, cursor not-allowed. Links: Color #4573b8, no underline, underline on hover. Back navigation: "← Back" at top-left of card, color #4573b8, font-size 0.95rem. Profile images: Circular (border-radius 50%), 120-150px diameter, centered, subtle box-shadow. Spacing: 2.5-3rem card padding, 1.5rem between form groups, 1rem between label and input, 2rem above primary button. Font: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif. COMMON MISTAKES TO AVOID (UI/CSS): 1. Never set padding or margin on body The custom HTML is injected into a host page that controls its own layout. Setting padding, margin, or min-height on body will conflict with the host page styles and create unwanted spacing. Wrong: body { padding: 2rem; min-height: 100vh; } (Also wrong — using only 100vh without dvh fallback. Always add min-height: 100dvh after 100vh for iOS Safari.) Right — use a wrapper element instead: body { margin: 0; padding: 0; } .wrap { max-width: 860px; margin: 0 auto; padding: 2rem; } The same applies to background on body — avoid it unless you are certain the host page does not set its own background. 2. Use HTML entities for emoji, not JS unicode escapes When building HTML strings in JavaScript (via innerHTML, string concatenation, etc.), JS unicode escapes like \ud83c\udfa5 will NOT render as emoji. They only work inside JS string literals that are directly displayed via textContent or similar APIs. Wrong — renders as garbled text: h += '<div class="title">\ud83c\udfa5 Video AI Analysis</div>'; Right — use HTML numeric entities: h += '<div class="title">🎥 Video AI Analysis</div>'; Also right — use emoji directly in static HTML (outside of JS): <div class="title">🎥 Video AI Analysis</div> Common emoji HTML entities reference: 👤 👤 User/person 🎂 🎂 Birthday cake 📍 📍 Pin/location 💻 💻 Computer ✨ ✨ Sparkles 🔍 🔍 Search 🎥 🎥 Camera 🎬 🎬 Clapper board 📋 📋 Clipboard ⚧ ⚧ Gender symbol ✓ ✓ Checkmark 3. CSS class name collision between landingHtml and recapHtml CRITICAL: landingHtml and recapHtml are injected into the SAME host document. If both fragments use the same class names (e.g., .card, .container, .header), styles from one will leak into the other, causing layout breakage. ALWAYS use unique prefixed class names: - landingHtml (pre-session/landing page): prefix all classes with .lp- (e.g., .lp-card, .lp-header, .lp-btn) - recapHtml (results page): prefix all classes with .r- (e.g., .r-card, .r-header, .r-wrap) Wrong — causes collisions: /* in landingHtml / .card { max-width: 460px; } / in recapHtml / .card { max-width: 900px; } Right — namespaced: / in landingHtml / .lp-card { max-width: 460px; } / in recapHtml / .r-card { max-width: 900px; } COMMON MISTAKES TO AVOID (Code/API): 4. window.__startSession race condition NEVER call window.__startSession() synchronously in a click handler. The host page may not have injected the function yet. ALWAYS use polling: function waitAndStart(input) { var n = 0; var iv = setInterval(function() { n++; if (typeof window.__startSession === 'function') { clearInterval(iv); window.__startSession(input); } else if (n > 100) { clearInterval(iv); document.body.innerHTML = '<p style="text-align:center;padding:2rem;color:red;">Failed to initialize session. Please refresh.</p>'; } }, 100); } Wrong: startBtn.addEventListener('click', function() { window.__startSession(); }); Right: startBtn.addEventListener('click', function() { waitAndStart(); }); For exported apps, NEVER send window.__FACESIGN_FLOW__ or another graph back to the server. To select a flow declared in export_app, pass its ID: waitAndStart({ flowId: 'enhanced', providedData: { name: nameInput.value } }); 5. Permissions are automatic — do NOT add a permissions node by default FaceSign automatically requests camera and microphone permissions at session start. Most flows do NOT need a PERMISSIONS node. Only add one in these specific cases: (a) The user wants to request microphone and camera permissions separately at different times during the flow (instead of both at once at session start). (b) The user wants to move the permission request to the initial page (landingHtml), outside the FaceSign flow itself. 6. nodeReport.type values are lowercase snake_case The API returns nodeReport.type in lowercase snake_case: "face_compare", "document_scan", "conversation", "permissions", "liveness_detection", etc. — NOT uppercase like "FACE_COMPARE". ALWAYS use case-insensitive comparison when looking up node reports: function getNode(r, type) { var rr = (r && r.nodeReports) \|\| []; var tl = type.toLowerCase(); for (var i = 0; i < rr.length; i++) { if (rr[i].type && rr[i].type.toLowerCase() === tl) return rr[i]; } return null; } // Usage: getNode(report, 'face_compare'), getNode(report, 'document_scan') 7. Microblink document report — nested field structure DOCUMENT_SCAN nodeReport.report fields are NOT plain strings. They use Microblink's nested structure: firstName: { latin: { value: "JANICE" } } dateOfBirth: { originalString: { latin: { value: "04/30/1970" } } } — OR — dateOfBirth: { day: 30, month: 4, year: 1970 } NEVER read fields directly as strings (e.g., dr.firstName will be an object, not "JANICE"). ALWAYS use this safe-value extractor: function sv(v) { if (v == null) return ''; if (typeof v === 'string') return v; if (v.latin && v.latin.value != null) return String(v.latin.value); if (v.originalString) return sv(v.originalString); if (v.day != null && v.month != null && v.year != null) return v.month + '/' + v.day + '/' + v.year; return ''; } // Usage: sv(dr.firstName) → "JANICE", sv(dr.dateOfBirth) → "04/30/1970" 8. videoAIAnalysis criterion is camelCase — format for display The criterion field (e.g., "facialExpressionAndMovement", "useOfExternalDevices") comes in camelCase. Convert to human-readable format: function toStartCase(s) { if (!s) return ''; return s.replace(/([A-Z]+)/g, function(m) { return ' ' + m.toLowerCase(); }) .trim().replace(/^./, function(c) { return c.toUpperCase(); }); } // "facialExpressionAndMovement" → "Facial expression and movement" 9. Conversation node: condition vs prompt In CONVERSATION nodes: - "condition" (in outcomes) = ONLY describes the trigger event for transitioning to the next node (e.g., "User explicitly agrees to proceed") - "prompt" = ALL instructions for the avatar's behavior, including how to greet, how to respond to questions, how to handle objections, and how to persuade - User questions or objections during the conversation are handled within the SAME node (continued dialog), NOT via separate outcomes - Conversation nodes can have any number of outcomes depending on the use case: Branching nodes (e.g., "what color?") → one outcome per branch + a fallback * Consent/agreement nodes → typically 2: agreement + fallback after N attempts - ALWAYS include a fallback outcome for when the conversation stalls (e.g., "conversation exceeded N exchanges with no condition met" or "user does not want to reply") Wrong — putting behavior instructions in condition: "condition": "User agrees. If they ask questions, answer warmly and ask again" Right — behavior in prompt, condition is just the trigger: "prompt": "Explain the process. If the user has questions, answer them warmly. Once they're ready, confirm." "condition": "User explicitly agrees or says they are ready"
recapHtml	string	required	REQUIRED. Raw HTML/JS for the results/recap page. NO CDATA, NO markdown fences. Every visible string MUST come from `uiStrings` (via {{KEY}} or window.t('KEY')). Contract: reads window.__FACESIGN_SESSION__, window.__FACESIGN_SESSION_ID__, window.__refetchSession() (returns Promise with updated session data). The COMMON MISTAKES sections from the `landingHtml` field description apply here too — read them once and follow for both fields. For the complete session data shape (Session, SessionReport, NodeReport types, delayed vs immediate fields), read the `facesign://session-data-types` MCP resource. STYLE GUIDE (Results/Recap Page): Match this visual style for consistency with the FaceSign UI. Background: Light gray #f5f7fa with subtle gradient to light blue at top. Layout: Single-column, max-width 900px, centered (margin 0 auto), padding 2rem. Page header: "Session summary" bold 1.6rem. Subtitle with date/time and duration in muted color #888, font-size 0.9rem. User info card: White card with rounded photo (80-100px), grid of icon+text pairs for age, gender, location, device. Icons in muted blue #6b7faa. Section cards: White background, border-radius 12px, box-shadow 0 2px 12px rgba(0,0,0,.05), padding 1.5rem, margin-bottom 1.5rem. Section headings: Bold 1.15rem, color #1a1a2e, with small emoji/icon prefix (e.g. ✨ AI Analysis, 🔍 Detected Signals, 📋 Transcript). Margin-bottom 1rem. Status banners (full-width within card, border-radius 12px, padding 1rem 1.5rem, white text, bold): - Verified/success: background #4a9d6e, shield ✓ icon - High-risk/warning: background #d97b30, ⚠ warning icon Signal items: Left border 4px solid, padding-left 1rem, margin-bottom 1rem, background white or tinted. - Normal: border-color #059669, light green tint background #f0fdf4 - Suspicious: border-color #f59e0b, light yellow tint background #fefce8 - High-risk: border-color #ef4444, light red tint background #fef2f2 Status badges (inline, pill): border-radius 6px, padding 2px 10px, font-weight 700, font-size 0.8rem, uppercase. - RECOGNIZED/NORMAL: background #d1fae5, color #065f46 - SUSPICIOUS: background #fef3c7, color #92400e Confidence scores: Right-aligned, font-size 0.85rem, color #aaa. Key-value grid: Two-column layout. Label: small text, color #888, font-size 0.8rem, uppercase. Value: font-size 0.95rem, color #1a1a2e, below label. Transcript: Dark background #1e2a3a, border-radius 10px, padding 1.5rem, monospace font. "CONVERSATION LOG" header uppercase, small, muted. Each line: timestamp (gray #777), speaker label (FACESIGN: in teal #4db8a4, USER: in green #6bc96f), message text white. Line-height 1.8. Video: Centered, border-radius 8px, max-width 100%, dark container background. Font: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif. BEST PRACTICES FOR STABLE RENDERING (recapHtml): Session data arrives in two stages: some fields are available immediately when the session ends (user info, AI analysis, transcript), while others require polling. Video AI analysis may take up to 60 seconds; media usually arrives sooner. Naive implementations cause layout jumping (DOM rebuild on each poll) and duplicate network requests. ARCHITECTURE: Split Static vs Dynamic Rendering. renderStatic(data) — called ONCE: Renders all sections that won't change: user info (age, sex, location, device), aiAnalysis.overallSummary, aiAnalysis.analysis list, transcript, documentImages. updateDynamic(data) — called on each poll: Updates ONLY sections whose data arrives asynchronously: nodeReports, videoAIAnalysis, deepfakeDetection, and media (avatarVideo, screenshots). IMPORTANT: nodeReports is DELAYED — do NOT render node report data (face compare results, document scan results, etc.) in renderStatic(). Each dynamic section has its own wrapper element (e.g. <div id="video-ai-content">, <div id="node-reports-content">) so updates replace only that element's innerHTML, leaving the rest untouched. Track completion with boolean flags (videoAIDone, recordingDone, nodeReportsDone). Once a section is populated, skip further updates. Set videoAIDone when videoAIAnalysisStatus is either `succeeded` or `failed`. A failed analysis is terminal: replace the spinner with an unavailable message and do not interpret the missing result as clean evidence. If the status is absent, analysis was not requested, so omit the section. HTML STRUCTURE: <!-- Static sections: rendered once --> <div id="userinfo-card"></div> <div id="summary-card"></div> <div id="analysis-card"></div> <!-- Dynamic sections: inner content updated by polling --> <div id="video-ai-card"> <div class="card"> <div class="card-title">Video AI Analysis</div> <div id="video-ai-content"><!-- spinner initially, replaced when data arrives --></div> </div> </div> <div id="recording-card"> <div class="card"> <div class="card-title">Session Recording</div> <div id="recording-content"><!-- spinner initially, replaced when data arrives --></div> </div> </div> <!-- Static section: rendered once --> <div id="transcript-card"></div> POLLING: Single Entry Point with Guard (IIFE pattern): IMPORTANT: Polling MUST be limited — max 30 attempts, max 2 minutes total. Stop polling when limits are reached even if some data hasn't arrived. (function() { var polling = false; var pollCount = 0; var MAX_POLLS = 30; var startTime = Date.now(); var MAX_DURATION = 2 * 60 * 1000; // 2 minutes var videoAIDone = false; var recordingDone = false; var nodeReportsDone = false; function shouldStop() { return pollCount >= MAX_POLLS \|\| (Date.now() - startTime) >= MAX_DURATION; } function poll() { if (polling) return; if (shouldStop()) return; polling = true; pollCount++; if (typeof window.__refetchSession !== 'function') { polling = false; setTimeout(poll, 2000); return; } window.__refetchSession() .then(function(data) { polling = false; updateDynamic(data); if ((!videoAIDone \|\| !recordingDone \|\| !nodeReportsDone) && !shouldStop()) setTimeout(poll, 4000); }) .catch(function() { polling = false; if (!shouldStop()) setTimeout(poll, 4000); }); } function init() { var data = window.__FACESIGN_SESSION__; if (!data) return; renderStatic(data); var needMore = updateDynamic(data); if (needMore) setTimeout(poll, 4000); } if (window.__FACESIGN_SESSION__) { init(); } else { var chk = setInterval(function() { if (window.__FACESIGN_SESSION__) { clearInterval(chk); init(); } }, 500); } })(); KEY RULES: - Call renderStatic() exactly once — avoids DOM rebuild and layout jumps - updateDynamic() only touches dedicated container elements — no reflow outside the updated section - Use a polling boolean guard — prevents concurrent __refetchSession() calls - ALWAYS limit polling — max 30 attempts AND max 2 minutes total. Never poll indefinitely. - Use videoAIDone / recordingDone / nodeReportsDone flags — stops updating a section once its data has been rendered - For video AI, derive videoAIDone from videoAIAnalysisStatus, not from the presence of videoAIAnalysis alone - nodeReports is DELAYED — always render node report data (face compare, document scan, etc.) in updateDynamic(), never in renderStatic() - Single init() entry point via IIFE — eliminates duplicate initialization paths - Check typeof __refetchSession === 'function' before calling — handles the case where the API isn't injected yet - Use setTimeout not setInterval for polling — ensures the next poll starts only after the previous one completes - nodeReport.type is lowercase snake_case ("face_compare", "document_scan") — use case-insensitive comparison - Document scan report fields are Microblink nested objects — use a safe-value extractor function (see COMMON MISTAKES) - videoAIAnalysis criterion is camelCase — convert to human-readable with toStartCase() (see COMMON MISTAKES) SUMMARY: Render once, patch selectively, poll safely with limits. Static content is written to the DOM a single time. Dynamic content (nodeReports, videoAIAnalysis, media) targets specific container elements. Polling is serialized with a guard flag and stops as soon as all async data has arrived or limits are reached (max 30 attempts / 2 minutes).
uiStrings	object	required	REQUIRED. Per-language UI string dictionary: { langId: { key: translatedString } }. You invent the keys to match {{KEY}} / window.t('KEY') in landingHtml and recapHtml. Must contain `en` plus every language in `langs` (or every catalog language if `langs` is omitted). All per-language dicts must share the IDENTICAL key set.
appName	string	optional	Name for the generated app (used in package.json, defaults to 'facesign-app')

Raw schema

{
  "type": "object",
  "properties": {
    "flow": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "start"
              },
              "outcome": {
                "type": "string",
                "description": "The id of the next node"
              }
            },
            "required": [
              "id",
              "type",
              "outcome"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "end"
              }
            },
            "required": [
              "id",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "conversation"
              },
              "prompt": {
                "type": "string",
                "description": "What the avatar says to the user"
              },
              "doesNotRequireReply": {
                "type": "boolean",
                "description": "If true, avatar speaks without waiting for user reply"
              },
              "outcomes": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "targetNodeId": {
                      "type": "string",
                      "description": "The id of the node to route to"
                    },
                    "condition": {
                      "type": "string",
                      "description": "Condition description, e.g. \"default\", \"user says yes\""
                    }
                  },
                  "required": [
                    "id",
                    "targetNodeId",
                    "condition"
                  ],
                  "additionalProperties": false
                },
                "minItems": 1,
                "description": "Array of {id, targetNodeId, condition} routing entries"
              },
              "awaitExternal": {
                "type": "object",
                "properties": {
                  "request": {
                    "type": "object",
                    "properties": {
                      "url": {
                        "type": "string",
                        "description": "Endpoint to call (must pass the server-side allowlist). The current sessionId is appended automatically as a query parameter"
                      },
                      "method": {
                        "type": "string",
                        "enum": [
                          "GET",
                          "POST"
                        ],
                        "description": "HTTP method. Defaults to POST (JSON body); GET sends vars as query params"
                      },
                      "vars": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string",
                              "description": "Key under which the value is placed in the request payload"
                            },
                            "value": {
                              "anyOf": [
                                {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "const": "literal"
                                    },
                                    "value": {
                                      "type": [
                                        "string",
                                        "number",
                                        "boolean"
                                      ],
                                      "description": "The literal scalar value"
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "value"
                                  ],
                                  "additionalProperties": false
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "type": {
                                      "type": "string",
                                      "const": "ref"
                                    },
                                    "source": {
                                      "type": "string",
                                      "enum": [
                                        "extractedData",
                                        "providedData"
                                      ],
                                      "description": "Source to resolve the referenced value from"
                                    },
                                    "field": {
                                      "type": "string",
                                      "description": "The field/key name within the source"
                                    }
                                  },
                                  "required": [
                                    "type",
                                    "source",
                                    "field"
                                  ],
                                  "additionalProperties": false
                                }
                              ],
                              "description": "Literal value or a reference resolved from session data"
                            }
                          },
                          "required": [
                            "name",
                            "value"
                          ],
                          "additionalProperties": false
                        },
                        "description": "Payload variables, each resolving to a literal or a session value"
                      }
                    },
                    "required": [
                      "url"
                    ],
                    "additionalProperties": false,
                    "description": "The endpoint to poll in the background"
                  },
                  "poll": {
                    "type": "object",
                    "properties": {
                      "intervalMs": {
                        "type": "number",
                        "description": "Delay between polls in milliseconds"
                      },
                      "timeoutMs": {
                        "type": "number",
                        "description": "Total time to keep polling before giving up"
                      }
                    },
                    "required": [
                      "intervalMs",
                      "timeoutMs"
                    ],
                    "additionalProperties": false,
                    "description": "Polling cadence and overall timeout"
                  },
                  "exits": {
                    "type": "object",
                    "properties": {
                      "onDataReady": {
                        "type": "string",
                        "description": "Node id when the endpoint returns HTTP 200 (result ready)"
                      },
                      "onTimeout": {
                        "type": "string",
                        "description": "Node id when poll.timeoutMs elapses first"
                      },
                      "onError": {
                        "type": "string",
                        "description": "Node id when the call errors"
                      }
                    },
                    "required": [
                      "onDataReady",
                      "onTimeout",
                      "onError"
                    ],
                    "additionalProperties": false,
                    "description": "Where to route when the background poll resolves"
                  }
                },
                "required": [
                  "request",
                  "poll",
                  "exits"
                ],
                "additionalProperties": false,
                "description": "Optional background poll: the avatar keeps talking (normal outcomes stay active) while an external result becomes ready; exits via onDataReady/onTimeout/onError"
              }
            },
            "required": [
              "id",
              "type",
              "prompt",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "liveness_detection"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "livenessDetected": {
                    "type": "string",
                    "description": "Node id when liveness is confirmed"
                  },
                  "deepfakeDetected": {
                    "type": "string",
                    "description": "Node id when deepfake is detected"
                  },
                  "noFace": {
                    "type": "string",
                    "description": "Node id when frames were captured but no face is on them"
                  },
                  "inconclusive": {
                    "type": "string",
                    "description": "Node id when the check produced no verdict — the detector could not decide, did not run, or there was nothing to analyse. This is our failure, not the user's: route it to a retry, a step-up or a manual review, never to the happy path by default"
                  }
                },
                "required": [
                  "livenessDetected",
                  "deepfakeDetected",
                  "noFace",
                  "inconclusive"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id. All four are required"
              }
            },
            "required": [
              "id",
              "type",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "enter_email"
              },
              "prompt": {
                "type": "string",
                "description": "Optional phrase the avatar says at the moment the email input field appears (direct speech, e.g. \"Could you please enter your email address?\"). Keep it short — one sentence. Omit to let the avatar stay silent while the field is shown."
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "emailEntered": {
                    "type": "string",
                    "description": "Node id when email is provided"
                  },
                  "canceled": {
                    "type": "string",
                    "description": "Node id when user cancels"
                  }
                },
                "required": [
                  "emailEntered",
                  "canceled"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "data_validation"
              },
              "validation": {
                "type": "object",
                "properties": {
                  "field": {
                    "type": "string"
                  },
                  "action": {
                    "type": "string"
                  },
                  "value": {
                    "type": "string"
                  }
                },
                "required": [
                  "field",
                  "action"
                ],
                "additionalProperties": false
              },
              "outcomes": {
                "type": "array",
                "items": {
                  "$ref": "#/properties/flow/items/anyOf/2/properties/outcomes/items"
                },
                "minItems": 1,
                "description": "Array of {id, targetNodeId, condition} routing entries"
              }
            },
            "required": [
              "id",
              "type",
              "validation",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "document_scan"
              },
              "scanningMode": {
                "type": "string",
                "enum": [
                  "single",
                  "automatic"
                ],
                "description": "Scanning mode"
              },
              "allowedDocumentTypes": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minItems": 1,
                "description": "Allowed document types, e.g. [\"id\", \"passport\", \"dl\"]"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "scanSuccess": {
                    "type": "string",
                    "description": "Node id on successful scan"
                  },
                  "userCancelled": {
                    "type": "string",
                    "description": "Node id when user cancels"
                  },
                  "scanTimeout": {
                    "type": "string",
                    "description": "Node id on scan timeout"
                  }
                },
                "required": [
                  "scanSuccess",
                  "userCancelled",
                  "scanTimeout"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "scanningMode",
              "allowedDocumentTypes",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "recognition"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "recognized": {
                    "type": "string",
                    "description": "Node id when user is recognized"
                  },
                  "newUser": {
                    "type": "string",
                    "description": "Node id when user is new"
                  },
                  "noFace": {
                    "type": "string",
                    "description": "Node id when no face is found"
                  }
                },
                "required": [
                  "recognized",
                  "newUser",
                  "noFace"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "face_scan"
              },
              "captureInstructions": {
                "type": "string"
              },
              "requireLivenessChallenge": {
                "type": "boolean"
              },
              "requireAILivenessCheck": {
                "type": "boolean"
              },
              "similarityThreshold": {
                "type": "number",
                "description": "0-1, how similar faces must be"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "passed": {
                    "type": "string",
                    "description": "Node id when face scan passes"
                  },
                  "notPassed": {
                    "type": "string",
                    "description": "Node id when face scan fails"
                  },
                  "cancelled": {
                    "type": "string",
                    "description": "Node id when user cancels"
                  },
                  "error": {
                    "type": "string",
                    "description": "Node id on error"
                  }
                },
                "required": [
                  "passed",
                  "notPassed",
                  "cancelled",
                  "error"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "two_factor_email"
              },
              "otpLength": {
                "type": "number",
                "description": "OTP length 4-8, default 6"
              },
              "expirySeconds": {
                "type": "number",
                "description": "OTP expiry in seconds, default 300"
              },
              "maxAttempts": {
                "type": "number",
                "description": "Max verification attempts, default 3"
              },
              "resendAfterSeconds": {
                "type": "number",
                "description": "Seconds before allowing OTP resend"
              },
              "showUI": {
                "type": "boolean",
                "description": "Whether to show the OTP input UI"
              },
              "emailTemplate": {
                "type": "string"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "verified": {
                    "type": "string",
                    "description": "Node id when OTP verified"
                  },
                  "delivery_failed": {
                    "type": "string",
                    "description": "Node id when delivery fails"
                  },
                  "failed_unverified": {
                    "type": "string",
                    "description": "Node id when max attempts exhausted"
                  },
                  "cancelled": {
                    "type": "string",
                    "description": "Node id when user cancels"
                  },
                  "error": {
                    "type": "string",
                    "description": "Node id on error"
                  }
                },
                "required": [
                  "verified",
                  "delivery_failed",
                  "failed_unverified",
                  "cancelled",
                  "error"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "two_factor_sms"
              },
              "otpLength": {
                "type": "number",
                "description": "OTP length 4-8, default 6"
              },
              "expirySeconds": {
                "type": "number",
                "description": "OTP expiry in seconds, default 300"
              },
              "maxAttempts": {
                "type": "number",
                "description": "Max verification attempts, default 3"
              },
              "resendAfterSeconds": {
                "type": "number",
                "description": "Seconds before allowing OTP resend"
              },
              "showUI": {
                "type": "boolean",
                "description": "Whether to show the OTP input UI"
              },
              "smsTemplate": {
                "type": "string"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "verified": {
                    "type": "string",
                    "description": "Node id when OTP verified"
                  },
                  "delivery_failed": {
                    "type": "string",
                    "description": "Node id when delivery fails"
                  },
                  "failed_unverified": {
                    "type": "string",
                    "description": "Node id when max attempts exhausted"
                  },
                  "cancelled": {
                    "type": "string",
                    "description": "Node id when user cancels"
                  },
                  "error": {
                    "type": "string",
                    "description": "Node id on error"
                  }
                },
                "required": [
                  "verified",
                  "delivery_failed",
                  "failed_unverified",
                  "cancelled",
                  "error"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "permissions"
              },
              "prompt": {
                "type": "string",
                "description": "Optional message the avatar says (direct speech mode, e.g. 'Say: Please enable your camera.')"
              },
              "permissions": {
                "type": "object",
                "properties": {
                  "camera": {
                    "type": "boolean",
                    "description": "Request camera access"
                  },
                  "microphone": {
                    "type": "boolean",
                    "description": "Request microphone access"
                  }
                },
                "additionalProperties": false,
                "description": "Which permissions to request"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "permissionsGranted": {
                    "type": "string",
                    "description": "Node id when permissions are granted"
                  },
                  "permissionsDenied": {
                    "type": "string",
                    "description": "Node id when permissions are denied"
                  }
                },
                "required": [
                  "permissionsGranted",
                  "permissionsDenied"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "permissions",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "face_compare"
              },
              "sourceA": {
                "type": "object",
                "properties": {
                  "source": {
                    "type": "string",
                    "enum": [
                      "sessionVideo",
                      "faceScan",
                      "providedData",
                      "documentPhoto"
                    ],
                    "description": "Source of the face image"
                  },
                  "providedDataKey": {
                    "type": "string",
                    "description": "Required when source is 'providedData' — the key in providedData that holds the image URL"
                  }
                },
                "required": [
                  "source"
                ],
                "additionalProperties": false,
                "description": "First face image source"
              },
              "sourceB": {
                "type": "object",
                "properties": {
                  "source": {
                    "$ref": "#/properties/flow/items/anyOf/12/properties/sourceA/properties/source"
                  },
                  "providedDataKey": {
                    "$ref": "#/properties/flow/items/anyOf/12/properties/sourceA/properties/providedDataKey"
                  }
                },
                "required": [
                  "source"
                ],
                "additionalProperties": false,
                "description": "Second face image source"
              },
              "similarityThreshold": {
                "type": "number",
                "description": "0-1, minimum similarity score required for a match"
              },
              "outcomes": {
                "type": "object",
                "properties": {
                  "match": {
                    "type": "string",
                    "description": "Node id when faces match"
                  },
                  "noMatch": {
                    "type": "string",
                    "description": "Node id when faces do not match"
                  },
                  "imageUnavailable": {
                    "type": "string",
                    "description": "Node id when one or both images could not be obtained"
                  }
                },
                "required": [
                  "match",
                  "noMatch",
                  "imageUnavailable"
                ],
                "additionalProperties": false,
                "description": "Record mapping each outcome to a target node id"
              }
            },
            "required": [
              "id",
              "type",
              "sourceA",
              "sourceB",
              "outcomes"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "external_call"
              },
              "request": {
                "type": "object",
                "properties": {
                  "url": {
                    "$ref": "#/properties/flow/items/anyOf/2/properties/awaitExternal/properties/request/properties/url"
                  },
                  "method": {
                    "$ref": "#/properties/flow/items/anyOf/2/properties/awaitExternal/properties/request/properties/method"
                  },
                  "vars": {
                    "$ref": "#/properties/flow/items/anyOf/2/properties/awaitExternal/properties/request/properties/vars"
                  }
                },
                "required": [
                  "url"
                ],
                "additionalProperties": false,
                "description": "The external endpoint to call and the payload to send"
              },
              "outcome": {
                "type": "string",
                "description": "Node id to advance to after the response is merged into providedData (never branches)"
              }
            },
            "required": [
              "id",
              "type",
              "request",
              "outcome"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique node identifier"
              },
              "type": {
                "type": "string",
                "const": "field_condition"
              },
              "rules": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "left": {
                      "type": "object",
                      "properties": {
                        "source": {
                          "type": "string",
                          "enum": [
                            "extractedData",
                            "providedData"
                          ],
                          "description": "Where the value is read from: 'extractedData' (a field from extractionSchema, extracted on demand from the transcript) or 'providedData' (a key set at creation or written by a prior external_call)"
                        },
                        "field": {
                          "type": "string",
                          "description": "The field/key name within the source"
                        }
                      },
                      "required": [
                        "source",
                        "field"
                      ],
                      "additionalProperties": false,
                      "description": "Reference to the session value to test"
                    },
                    "operator": {
                      "type": "string",
                      "enum": [
                        "equals",
                        "notEquals",
                        "gt",
                        "lt",
                        "gte",
                        "lte",
                        "exists",
                        "notExists"
                      ],
                      "description": "Comparison operator (omit 'right' for 'exists'/'notExists')"
                    },
                    "right": {
                      "anyOf": [
                        {
                          "$ref": "#/properties/flow/items/anyOf/2/properties/awaitExternal/properties/request/properties/vars/items/properties/value/anyOf/0"
                        },
                        {
                          "$ref": "#/properties/flow/items/anyOf/2/properties/awaitExternal/properties/request/properties/vars/items/properties/value/anyOf/1"
                        }
                      ],
                      "description": "Literal or reference to compare against; omit for 'exists'/'notExists'"
                    },
                    "outcome": {
                      "type": "string",
                      "description": "Node id to route to when this rule matches"
                    }
                  },
                  "required": [
                    "left",
                    "operator",
                    "outcome"
                  ],
                  "additionalProperties": false
                },
                "minItems": 1,
                "description": "Rules evaluated top-to-bottom; first match wins"
              },
              "default": {
                "type": "string",
                "description": "Node id to route to when no rule matches"
              }
            },
            "required": [
              "id",
              "type",
              "rules",
              "default"
            ],
            "additionalProperties": false
          }
        ]
      },
      "description": "Array of nodes forming the session's directed graph"
    },
    "flowVariants": {
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": {
          "$ref": "#/properties/flow/items"
        }
      },
      "propertyNames": {
        "minLength": 1,
        "maxLength": 64,
        "pattern": "^[A-Za-z0-9_-]+$"
      },
      "description": "Optional additional flows declared at export time. The landing page selects one by calling window.__startSession({ flowId: 'variant-id' }); the browser never sends a graph."
    },
    "avatarId": {
      "type": "string",
      "description": "Avatar ID from the facesign://catalog resource."
    },
    "langs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional whitelist of BCP-47 language codes (from facesign://catalog) the exported session may use. DEFAULT BEHAVIOUR (recommended): OMIT this parameter entirely — the app then supports every language in the FaceSign catalog, and `uiStrings` must cover every catalog language. ONLY set `langs` when the user EXPLICITLY restricts the language set (e.g. 'Spanish-only demo', 'support English and Russian'). Do NOT narrow to `['en']` just because the user described the demo in English or did not mention languages. Example (explicit restriction): [\"en\", \"es\", \"ru\"]. The set of target languages for `uiStrings` is derived from this list (or the full catalog if omitted)."
    },
    "defaultLang": {
      "type": "string",
      "description": "Optional fallback BCP-47 language code used when the end-user's browser language is not in `langs`. DEFAULT BEHAVIOUR: OMIT this parameter. When set, must be one of the codes in `langs` (if `langs` is also set)."
    },
    "zone": {
      "type": "string",
      "enum": [
        "us",
        "eu"
      ],
      "description": "Data processing zone"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Arbitrary metadata to attach"
    },
    "clientReferenceId": {
      "type": "string",
      "description": "Your own reference ID for this session"
    },
    "providedData": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "phone": {
          "type": "string"
        }
      },
      "additionalProperties": true,
      "description": "Pre-known user data"
    },
    "videoAIAnalysisEnabled": {
      "type": "boolean",
      "description": "Enable video AI fraud analysis"
    },
    "extractionSchema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fieldName": {
            "type": "string",
            "description": "Key under which the extracted value appears in session.report.extractedData."
          },
          "type": {
            "type": "string",
            "enum": [
              "string",
              "number",
              "boolean",
              "date"
            ],
            "description": "Expected value type. `date` is returned as an ISO 8601 string."
          },
          "description": {
            "type": "string",
            "description": "Natural-language hint for the LLM describing what to look for in the transcript. This is the primary extraction signal — be specific."
          },
          "enum": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional allowed string values. When set, the LLM normalizes free-form answers into one of the listed values."
          }
        },
        "required": [
          "fieldName",
          "type",
          "description"
        ],
        "additionalProperties": false
      },
      "description": "Optional schema describing fields the FaceSign backend should extract from the session transcript using an LLM. Results are populated post-session at `session.report.extractedData` as `{ [fieldName]: string | number | boolean | null }` (null when the transcript did not contain the data). Render results in your recapHtml when present."
    },
    "customization": {
      "type": "object",
      "properties": {
        "permissionsPage": {
          "type": "object",
          "properties": {
            "buttonText": {
              "type": "string"
            },
            "mainHeading": {
              "type": "string"
            },
            "subheading": {
              "type": "string"
            },
            "backgroundType": {
              "type": "string",
              "enum": [
                "AVATAR",
                "COLOR"
              ]
            },
            "backgroundColor": {
              "type": "string"
            }
          },
          "additionalProperties": false
        },
        "controls": {
          "type": "object",
          "properties": {
            "showUxControls": {
              "type": "boolean",
              "description": "Master switch for the in-session control panel. When false the panel is not rendered and every other controls.* setting has no effect"
            },
            "captionsOpenedByDefault": {
              "type": "boolean",
              "description": "Start the session with the closed-captions (transcript) panel open. Omitted or false keeps it closed. The user can toggle it with the CC button either way. Set it for accessibility, or when viewers may be reading along in a second language. Ignored when showUxControls is false"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false,
      "description": "UI customization"
    },
    "landingHtml": {
      "type": "string",
      "description": "REQUIRED. Raw HTML/JS for the pre-session landing page. NO CDATA, NO markdown fences. Every visible string MUST come from `uiStrings` — reference them via {{KEY}} placeholders (interpolated at inject time) or via window.t('KEY') (dynamic at runtime). Contract: reads window.__FACESIGN_FLOW__ (the default flow, for display only). MUST call window.__startSession(input?) to launch the session. input may contain only a declared flowId and/or providedData collected by the form; never pass a flow graph from the browser.\n\nSTYLE GUIDE (Pre-Session Page):\nMatch this visual style for consistency with the FaceSign UI.\n\nBackground: Light gray #f5f7fa. Full-viewport centered layout (flexbox, min-height: 100vh; min-height: 100dvh — always use dvh with vh fallback for iOS compatibility).\n\nCard: White, border-radius 16px, box-shadow 0 4px 24px rgba(0,0,0,.08), padding 2.5-3rem, max-width 480-600px, centered.\n\nHeadings: Bold, 1.4-1.8rem, color #1a1a2e, centered in card.\n\nInputs: Full-width, padding 14px 16px, border 2px solid #d1d5db, border-radius 12px, font-size 1rem. Focus: border-color #5b7bab. Placeholder color #9ca3af.\n\nPrimary buttons: Background #7b8fb5 (steel-blue), color white, font-weight 600, font-size 1.05rem, border-radius 50px (pill shape), padding 14px, full-width in card. Hover: background #6a7fa5. Disabled: background #c5cdd8, cursor not-allowed.\n\nLinks: Color #4573b8, no underline, underline on hover. Back navigation: \"← Back\" at top-left of card, color #4573b8, font-size 0.95rem.\n\nProfile images: Circular (border-radius 50%), 120-150px diameter, centered, subtle box-shadow.\n\nSpacing: 2.5-3rem card padding, 1.5rem between form groups, 1rem between label and input, 2rem above primary button.\n\nFont: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif.\n\n\nCOMMON MISTAKES TO AVOID (UI/CSS):\n\n1. Never set padding or margin on body\nThe custom HTML is injected into a host page that controls its own layout. Setting padding, margin, or min-height on body will conflict with the host page styles and create unwanted spacing.\n\nWrong:\nbody { padding: 2rem; min-height: 100vh; }\n(Also wrong — using only 100vh without dvh fallback. Always add min-height: 100dvh after 100vh for iOS Safari.)\n\nRight — use a wrapper element instead:\nbody { margin: 0; padding: 0; }\n.wrap { max-width: 860px; margin: 0 auto; padding: 2rem; }\n\nThe same applies to background on body — avoid it unless you are certain the host page does not set its own background.\n\n2. Use HTML entities for emoji, not JS unicode escapes\nWhen building HTML strings in JavaScript (via innerHTML, string concatenation, etc.), JS unicode escapes like \\ud83c\\udfa5 will NOT render as emoji. They only work inside JS string literals that are directly displayed via textContent or similar APIs.\n\nWrong — renders as garbled text:\nh += '<div class=\"title\">\\ud83c\\udfa5 Video AI Analysis</div>';\n\nRight — use HTML numeric entities:\nh += '<div class=\"title\">&#127909; Video AI Analysis</div>';\n\nAlso right — use emoji directly in static HTML (outside of JS):\n<div class=\"title\">🎥 Video AI Analysis</div>\n\nCommon emoji HTML entities reference:\n&#128100; 👤 User/person\n&#127874; 🎂 Birthday cake\n&#128205; 📍 Pin/location\n&#128187; 💻 Computer\n&#10024;  ✨ Sparkles\n&#128269; 🔍 Search\n&#127909; 🎥 Camera\n&#127916; 🎬 Clapper board\n&#128203; 📋 Clipboard\n&#9895;   ⚧ Gender symbol\n&#10003;  ✓ Checkmark\n\n3. CSS class name collision between landingHtml and recapHtml\nCRITICAL: landingHtml and recapHtml are injected into the SAME host document. If both fragments use the same class names (e.g., .card, .container, .header), styles from one will leak into the other, causing layout breakage.\n\nALWAYS use unique prefixed class names:\n- landingHtml (pre-session/landing page): prefix all classes with .lp- (e.g., .lp-card, .lp-header, .lp-btn)\n- recapHtml (results page): prefix all classes with .r- (e.g., .r-card, .r-header, .r-wrap)\n\nWrong — causes collisions:\n/* in landingHtml */  .card { max-width: 460px; }\n/* in recapHtml */    .card { max-width: 900px; }\n\nRight — namespaced:\n/* in landingHtml */  .lp-card { max-width: 460px; }\n/* in recapHtml */    .r-card { max-width: 900px; }\n\n\nCOMMON MISTAKES TO AVOID (Code/API):\n\n4. window.__startSession race condition\nNEVER call window.__startSession() synchronously in a click handler. The host page may not have injected the function yet. ALWAYS use polling:\n\nfunction waitAndStart(input) {\n  var n = 0;\n  var iv = setInterval(function() {\n    n++;\n    if (typeof window.__startSession === 'function') {\n      clearInterval(iv);\n      window.__startSession(input);\n    } else if (n > 100) {\n      clearInterval(iv);\n      document.body.innerHTML = '<p style=\"text-align:center;padding:2rem;color:red;\">Failed to initialize session. Please refresh.</p>';\n    }\n  }, 100);\n}\n\nWrong:\nstartBtn.addEventListener('click', function() { window.__startSession(); });\n\nRight:\nstartBtn.addEventListener('click', function() { waitAndStart(); });\n\nFor exported apps, NEVER send window.__FACESIGN_FLOW__ or another graph back to\nthe server. To select a flow declared in export_app, pass its ID:\nwaitAndStart({ flowId: 'enhanced', providedData: { name: nameInput.value } });\n\n5. Permissions are automatic — do NOT add a permissions node by default\nFaceSign automatically requests camera and microphone permissions at session start. Most flows do NOT need a PERMISSIONS node. Only add one in these specific cases:\n(a) The user wants to request microphone and camera permissions separately at different times during the flow (instead of both at once at session start).\n(b) The user wants to move the permission request to the initial page (landingHtml), outside the FaceSign flow itself.\n\n6. nodeReport.type values are lowercase snake_case\nThe API returns nodeReport.type in lowercase snake_case: \"face_compare\", \"document_scan\", \"conversation\", \"permissions\", \"liveness_detection\", etc. — NOT uppercase like \"FACE_COMPARE\".\n\nALWAYS use case-insensitive comparison when looking up node reports:\n\nfunction getNode(r, type) {\n  var rr = (r && r.nodeReports) || [];\n  var tl = type.toLowerCase();\n  for (var i = 0; i < rr.length; i++) {\n    if (rr[i].type && rr[i].type.toLowerCase() === tl) return rr[i];\n  }\n  return null;\n}\n\n// Usage: getNode(report, 'face_compare'), getNode(report, 'document_scan')\n\n7. Microblink document report — nested field structure\nDOCUMENT_SCAN nodeReport.report fields are NOT plain strings. They use Microblink's nested structure:\n  firstName: { latin: { value: \"JANICE\" } }\n  dateOfBirth: { originalString: { latin: { value: \"04/30/1970\" } } }\n  — OR —\n  dateOfBirth: { day: 30, month: 4, year: 1970 }\n\nNEVER read fields directly as strings (e.g., dr.firstName will be an object, not \"JANICE\").\n\nALWAYS use this safe-value extractor:\n\nfunction sv(v) {\n  if (v == null) return '';\n  if (typeof v === 'string') return v;\n  if (v.latin && v.latin.value != null) return String(v.latin.value);\n  if (v.originalString) return sv(v.originalString);\n  if (v.day != null && v.month != null && v.year != null)\n    return v.month + '/' + v.day + '/' + v.year;\n  return '';\n}\n\n// Usage: sv(dr.firstName) → \"JANICE\", sv(dr.dateOfBirth) → \"04/30/1970\"\n\n8. videoAIAnalysis criterion is camelCase — format for display\nThe criterion field (e.g., \"facialExpressionAndMovement\", \"useOfExternalDevices\") comes in camelCase. Convert to human-readable format:\n\nfunction toStartCase(s) {\n  if (!s) return '';\n  return s.replace(/([A-Z]+)/g, function(m) { return ' ' + m.toLowerCase(); })\n    .trim().replace(/^./, function(c) { return c.toUpperCase(); });\n}\n// \"facialExpressionAndMovement\" → \"Facial expression and movement\"\n\n9. Conversation node: condition vs prompt\nIn CONVERSATION nodes:\n- \"condition\" (in outcomes) = ONLY describes the trigger event for transitioning to the next node (e.g., \"User explicitly agrees to proceed\")\n- \"prompt\" = ALL instructions for the avatar's behavior, including how to greet, how to respond to questions, how to handle objections, and how to persuade\n- User questions or objections during the conversation are handled within the SAME node (continued dialog), NOT via separate outcomes\n- Conversation nodes can have any number of outcomes depending on the use case:\n  * Branching nodes (e.g., \"what color?\") → one outcome per branch + a fallback\n  * Consent/agreement nodes → typically 2: agreement + fallback after N attempts\n- ALWAYS include a fallback outcome for when the conversation stalls (e.g., \"conversation exceeded N exchanges with no condition met\" or \"user does not want to reply\")\n\nWrong — putting behavior instructions in condition:\n\"condition\": \"User agrees. If they ask questions, answer warmly and ask again\"\n\nRight — behavior in prompt, condition is just the trigger:\n\"prompt\": \"Explain the process. If the user has questions, answer them warmly. Once they're ready, confirm.\"\n\"condition\": \"User explicitly agrees or says they are ready\""
    },
    "recapHtml": {
      "type": "string",
      "description": "REQUIRED. Raw HTML/JS for the results/recap page. NO CDATA, NO markdown fences. Every visible string MUST come from `uiStrings` (via {{KEY}} or window.t('KEY')). Contract: reads window.__FACESIGN_SESSION__, window.__FACESIGN_SESSION_ID__, window.__refetchSession() (returns Promise with updated session data). The COMMON MISTAKES sections from the `landingHtml` field description apply here too — read them once and follow for both fields. For the complete session data shape (Session, SessionReport, NodeReport types, delayed vs immediate fields), read the `facesign://session-data-types` MCP resource.\n\nSTYLE GUIDE (Results/Recap Page):\nMatch this visual style for consistency with the FaceSign UI.\n\nBackground: Light gray #f5f7fa with subtle gradient to light blue at top.\n\nLayout: Single-column, max-width 900px, centered (margin 0 auto), padding 2rem.\n\nPage header: \"Session summary\" bold 1.6rem. Subtitle with date/time and duration in muted color #888, font-size 0.9rem.\n\nUser info card: White card with rounded photo (80-100px), grid of icon+text pairs for age, gender, location, device. Icons in muted blue #6b7faa.\n\nSection cards: White background, border-radius 12px, box-shadow 0 2px 12px rgba(0,0,0,.05), padding 1.5rem, margin-bottom 1.5rem.\n\nSection headings: Bold 1.15rem, color #1a1a2e, with small emoji/icon prefix (e.g. ✨ AI Analysis, 🔍 Detected Signals, 📋 Transcript). Margin-bottom 1rem.\n\nStatus banners (full-width within card, border-radius 12px, padding 1rem 1.5rem, white text, bold):\n- Verified/success: background #4a9d6e, shield ✓ icon\n- High-risk/warning: background #d97b30, ⚠ warning icon\n\nSignal items: Left border 4px solid, padding-left 1rem, margin-bottom 1rem, background white or tinted.\n- Normal: border-color #059669, light green tint background #f0fdf4\n- Suspicious: border-color #f59e0b, light yellow tint background #fefce8\n- High-risk: border-color #ef4444, light red tint background #fef2f2\n\nStatus badges (inline, pill): border-radius 6px, padding 2px 10px, font-weight 700, font-size 0.8rem, uppercase.\n- RECOGNIZED/NORMAL: background #d1fae5, color #065f46\n- SUSPICIOUS: background #fef3c7, color #92400e\n\nConfidence scores: Right-aligned, font-size 0.85rem, color #aaa.\n\nKey-value grid: Two-column layout. Label: small text, color #888, font-size 0.8rem, uppercase. Value: font-size 0.95rem, color #1a1a2e, below label.\n\nTranscript: Dark background #1e2a3a, border-radius 10px, padding 1.5rem, monospace font. \"CONVERSATION LOG\" header uppercase, small, muted. Each line: timestamp (gray #777), speaker label (FACESIGN: in teal #4db8a4, USER: in green #6bc96f), message text white. Line-height 1.8.\n\nVideo: Centered, border-radius 8px, max-width 100%, dark container background.\n\nFont: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif.\n\n\nBEST PRACTICES FOR STABLE RENDERING (recapHtml):\n\nSession data arrives in two stages: some fields are available immediately when the session ends (user info, AI analysis, transcript), while others require polling. Video AI analysis may take up to 60 seconds; media usually arrives sooner. Naive implementations cause layout jumping (DOM rebuild on each poll) and duplicate network requests.\n\nARCHITECTURE: Split Static vs Dynamic Rendering.\n\nrenderStatic(data) — called ONCE:\nRenders all sections that won't change: user info (age, sex, location, device), aiAnalysis.overallSummary, aiAnalysis.analysis list, transcript, documentImages.\n\nupdateDynamic(data) — called on each poll:\nUpdates ONLY sections whose data arrives asynchronously: nodeReports, videoAIAnalysis, deepfakeDetection, and media (avatarVideo, screenshots).\nIMPORTANT: nodeReports is DELAYED — do NOT render node report data (face compare results, document scan results, etc.) in renderStatic().\nEach dynamic section has its own wrapper element (e.g. <div id=\"video-ai-content\">, <div id=\"node-reports-content\">) so updates replace only that element's innerHTML, leaving the rest untouched.\nTrack completion with boolean flags (videoAIDone, recordingDone, nodeReportsDone). Once a section is populated, skip further updates.\nSet videoAIDone when videoAIAnalysisStatus is either `succeeded` or `failed`. A failed analysis is terminal: replace the spinner with an unavailable message and do not interpret the missing result as clean evidence. If the status is absent, analysis was not requested, so omit the section.\n\nHTML STRUCTURE:\n<!-- Static sections: rendered once -->\n<div id=\"userinfo-card\"></div>\n<div id=\"summary-card\"></div>\n<div id=\"analysis-card\"></div>\n\n<!-- Dynamic sections: inner content updated by polling -->\n<div id=\"video-ai-card\">\n  <div class=\"card\">\n    <div class=\"card-title\">Video AI Analysis</div>\n    <div id=\"video-ai-content\"><!-- spinner initially, replaced when data arrives --></div>\n  </div>\n</div>\n\n<div id=\"recording-card\">\n  <div class=\"card\">\n    <div class=\"card-title\">Session Recording</div>\n    <div id=\"recording-content\"><!-- spinner initially, replaced when data arrives --></div>\n  </div>\n</div>\n\n<!-- Static section: rendered once -->\n<div id=\"transcript-card\"></div>\n\nPOLLING: Single Entry Point with Guard (IIFE pattern):\nIMPORTANT: Polling MUST be limited — max 30 attempts, max 2 minutes total. Stop polling when limits are reached even if some data hasn't arrived.\n(function() {\n  var polling = false;\n  var pollCount = 0;\n  var MAX_POLLS = 30;\n  var startTime = Date.now();\n  var MAX_DURATION = 2 * 60 * 1000; // 2 minutes\n  var videoAIDone = false;\n  var recordingDone = false;\n  var nodeReportsDone = false;\n\n  function shouldStop() {\n    return pollCount >= MAX_POLLS || (Date.now() - startTime) >= MAX_DURATION;\n  }\n\n  function poll() {\n    if (polling) return;\n    if (shouldStop()) return;\n    polling = true;\n    pollCount++;\n    if (typeof window.__refetchSession !== 'function') {\n      polling = false;\n      setTimeout(poll, 2000);\n      return;\n    }\n    window.__refetchSession()\n      .then(function(data) {\n        polling = false;\n        updateDynamic(data);\n        if ((!videoAIDone || !recordingDone || !nodeReportsDone) && !shouldStop()) setTimeout(poll, 4000);\n      })\n      .catch(function() {\n        polling = false;\n        if (!shouldStop()) setTimeout(poll, 4000);\n      });\n  }\n\n  function init() {\n    var data = window.__FACESIGN_SESSION__;\n    if (!data) return;\n    renderStatic(data);\n    var needMore = updateDynamic(data);\n    if (needMore) setTimeout(poll, 4000);\n  }\n\n  if (window.__FACESIGN_SESSION__) {\n    init();\n  } else {\n    var chk = setInterval(function() {\n      if (window.__FACESIGN_SESSION__) { clearInterval(chk); init(); }\n    }, 500);\n  }\n})();\n\nKEY RULES:\n- Call renderStatic() exactly once — avoids DOM rebuild and layout jumps\n- updateDynamic() only touches dedicated container elements — no reflow outside the updated section\n- Use a polling boolean guard — prevents concurrent __refetchSession() calls\n- ALWAYS limit polling — max 30 attempts AND max 2 minutes total. Never poll indefinitely.\n- Use videoAIDone / recordingDone / nodeReportsDone flags — stops updating a section once its data has been rendered\n- For video AI, derive videoAIDone from videoAIAnalysisStatus, not from the presence of videoAIAnalysis alone\n- nodeReports is DELAYED — always render node report data (face compare, document scan, etc.) in updateDynamic(), never in renderStatic()\n- Single init() entry point via IIFE — eliminates duplicate initialization paths\n- Check typeof __refetchSession === 'function' before calling — handles the case where the API isn't injected yet\n- Use setTimeout not setInterval for polling — ensures the next poll starts only after the previous one completes\n- nodeReport.type is lowercase snake_case (\"face_compare\", \"document_scan\") — use case-insensitive comparison\n- Document scan report fields are Microblink nested objects — use a safe-value extractor function (see COMMON MISTAKES)\n- videoAIAnalysis criterion is camelCase — convert to human-readable with toStartCase() (see COMMON MISTAKES)\n\nSUMMARY: Render once, patch selectively, poll safely with limits. Static content is written to the DOM a single time. Dynamic content (nodeReports, videoAIAnalysis, media) targets specific container elements. Polling is serialized with a guard flag and stops as soon as all async data has arrived or limits are reached (max 30 attempts / 2 minutes)."
    },
    "uiStrings": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        }
      },
      "description": "REQUIRED. Per-language UI string dictionary: { langId: { key: translatedString } }. You invent the keys to match {{KEY}} / window.t('KEY') in landingHtml and recapHtml. Must contain `en` plus every language in `langs` (or every catalog language if `langs` is omitted). All per-language dicts must share the IDENTICAL key set."
    },
    "appName": {
      "type": "string",
      "description": "Name for the generated app (used in package.json, defaults to 'facesign-app')"
    }
  },
  "required": [
    "flow",
    "landingHtml",
    "recapHtml",
    "uiStrings"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Install

Tools (5)

set_api_keyget_sessionlist_sessionslaunch_session_uiexport_app

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.facesign.ai/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "facesign-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.facesign.ai/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

set_api_key

get_session

list_sessions

launch_session_ui

export_app

Install

Remote endpoint

Related servers