@explorer02/cfm-survey-sdk 0.3.9 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorer02/cfm-survey-sdk",
-  "version": "0.3.9",
+  "version": "0.4.1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/templates/docs/templates/CsatMatrixScale.tsx

@@ -16,14 +16,64 @@ import {
   mcqSelectedAccentVar,
   mcqSelectedBgVar,
 } from '@/lib/surveyUi/selectionStyles';
-import { csatColumnLabelStyle, ratingColumnLabelStyle } from '@/lib/surveyUi/labelStyles';
+import { csatColumnLabelStyle, ratingColumnLabelStyle, stackAnchorLabelLines, ratingAnchorLabelPillStyle } from '@/lib/surveyUi/labelStyles';
 
 const MATRIX_ROW_LABEL_WIDTH = 'var(--cfm-matrix-row-width, 180px)';
 
 type CsatMatrixQuestion = CsatQuestion | RatingMatrixQuestion;
 
 function anchorLabelStyle(question: CsatMatrixQuestion) {
-  return question.type === 'RATING_MATRIX' ? ratingColumnLabelStyle() : csatColumnLabelStyle();
+  return question.type === 'RATING_MATRIX' ? ratingAnchorLabelPillStyle() : csatColumnLabelStyle();
+}
+
+function anchorLabelPositionPercent(
+  index: number,
+  labelCount: number,
+  columnCount: number,
+  isGraphics: boolean,
+  question: CsatMatrixQuestion,
+): number {
+  if (labelCount === 1) return 50;
+  const useFullSpan = isGraphics || question.type === 'RATING_MATRIX';
+  const startPercent = useFullSpan ? 0 : 0.5 / columnCount;
+  const rangePercent = useFullSpan ? 1 : (columnCount - 1) / columnCount;
+  return (startPercent + (index / (labelCount - 1)) * rangePercent) * 100;
+}
+
+function anchorLabelRowMinHeight(question: CsatMatrixQuestion, hasLabels: boolean): string {
+  if (question.type === 'RATING_MATRIX' && hasLabels) return '44px';
+  return '24px';
+}
+
+function renderAnchorLabelContent(label: string, question: CsatMatrixQuestion): React.ReactNode {
+  if (question.type !== 'RATING_MATRIX') return label;
+  const lines = stackAnchorLabelLines(label);
+  if (lines.length === 1) return label;
+  return lines.map((line, idx) => (
+    <span key={idx} style={{ display: 'block' }}>
+      {line}
+    </span>
+  ));
+}
+
+function anchorLabelBoxStyle(question: CsatMatrixQuestion, isGraphics: boolean): React.CSSProperties {
+  if (question.type === 'RATING_MATRIX') {
+    return {
+      textAlign: 'center',
+      fontSize: '12px',
+      fontWeight: 600,
+      ...ratingAnchorLabelPillStyle(),
+    };
+  }
+  return {
+    textAlign: 'center',
+    fontSize: isGraphics ? '12px' : '13px',
+    fontWeight: 600,
+    lineHeight: 1.3,
+    whiteSpace: isGraphics ? 'normal' : 'nowrap',
+    maxWidth: isGraphics ? '72px' : undefined,
+    ...anchorLabelStyle(question),
+  };
 }
 
 function columnHeaderLabelStyle(question: CsatMatrixQuestion) {
@@ -36,6 +86,15 @@ function graphicsColumnLabelStyle(question: CsatMatrixQuestion) {
   return { fontSize: '12px', fontWeight: 500, lineHeight: 1.2, wordBreak: 'break-word' as const, ...pillStyle };
 }
 
+/** Graphics uses anchor labels (bold top row) — per-column tick badges duplicate them for CSAT + RATING. */
+function hasGraphicsAnchorLabels(labels: string[] | undefined): boolean {
+  return Boolean(labels?.some((label) => label.trim().length > 0));
+}
+
+function shouldShowGraphicsColumnLabelRow(isGraphics: boolean, labels: string[] | undefined): boolean {
+  return isGraphics && !hasGraphicsAnchorLabels(labels);
+}
+
 function GraphicsColumnLabelsRow({
   scaleColumns,
   question,
@@ -47,8 +106,8 @@ function GraphicsColumnLabelsRow({
   const labelStyle = graphicsColumnLabelStyle(question);
 
   return (
-    <div style={{ flex: 1, padding: '0 24px' }}>
-      <div style={{ position: 'relative', margin: '0 16px', height: '16px' }}>
+    <div style={{ flex: 1, minWidth: 0, padding: '0 8px' }}>
+      <div style={{ position: 'relative', margin: '0 8px', height: '16px' }}>
         {scaleColumns.map((col, i) => {
           const percent = scaleColumns.length === 1 ? 0 : (i / (scaleColumns.length - 1)) * 100;
           return (
@@ -60,7 +119,7 @@ function GraphicsColumnLabelsRow({
                 transform: 'translateX(-50%)',
                 bottom: 0,
                 textAlign: 'center',
-                width: '64px',
+                maxWidth: '72px',
               }}
             >
               <span style={labelStyle} dangerouslySetInnerHTML={{ __html: col.label }} />
@@ -212,28 +271,31 @@ function CsatMatrixGrid({
   const n = labels?.length || 0;
 
   return (
-    <div style={{ width: '100%' }}>
+    <div style={{ width: '100%', maxWidth: '100%', minWidth: 0, overflowX: 'auto', boxSizing: 'border-box' }}>
       {/* Labels row */}
       {showLabels && m > 0 && (
-        <div style={{ display: 'flex', alignItems: 'flex-end', marginBottom: '12px' }}>
-          <div style={{ width: MATRIX_ROW_LABEL_WIDTH, flexShrink: 0 }} />
-          <div style={{ flex: 1, display: 'flex' }}>
-            <div style={{ flex: 1, position: 'relative', height: '24px', ...(isGraphics ? { margin: '0 40px' } : {}) }}>
+        <div style={{ display: 'flex', alignItems: 'flex-end', marginBottom: '12px', minWidth: 0 }}>
+          <div style={{ width: MATRIX_ROW_LABEL_WIDTH, flexShrink: 0, minWidth: 0 }} />
+          <div style={{ flex: 1, display: 'flex', minWidth: 0 }}>
+            <div style={{
+              flex: 1,
+              position: 'relative',
+              minHeight: anchorLabelRowMinHeight(question, Boolean(showLabels)),
+              minWidth: 0,
+              ...(isGraphics || question.type === 'RATING_MATRIX' ? { margin: '0 8px' } : {}),
+            }}>
               {labels!.map((label, i) => {
-                const startPercent = isGraphics ? 0 : 0.5 / m;
-                const rangePercent = isGraphics ? 1 : (m - 1) / m;
-                const percent = n === 1 ? 50 : (startPercent + (i / (n - 1)) * rangePercent) * 100;
+                const percent = anchorLabelPositionPercent(i, n, m, isGraphics, question);
 
                 return (
                   <div key={i} style={{
                     position: 'absolute',
                     left: `${percent}%`,
+                    bottom: 0,
                     transform: 'translateX(-50%)',
-                    textAlign: 'center', fontSize: '13px', fontWeight: 600,
-                    lineHeight: 1.3, whiteSpace: 'nowrap',
-                    ...anchorLabelStyle(question),
+                    ...anchorLabelBoxStyle(question, isGraphics),
                   }}>
-                    {label}
+                    {renderAnchorLabelContent(label, question)}
                   </div>
                 );
               })}
@@ -243,9 +305,9 @@ function CsatMatrixGrid({
         </div>
       )}
 
-      {/* Column tick labels for graphics sliders (shown with or without anchor labels) */}
-      {isGraphics && m > 0 && (
-        <div style={{ display: 'flex', alignItems: 'flex-end', marginBottom: showLabels ? '8px' : '16px', minHeight: '24px' }}>
+      {/* Column tick labels for graphics — only when no anchor label row above */}
+      {shouldShowGraphicsColumnLabelRow(isGraphics, labels) && m > 0 && (
+        <div style={{ display: 'flex', alignItems: 'flex-end', marginBottom: '16px', minHeight: '24px' }}>
           <div style={{ width: MATRIX_ROW_LABEL_WIDTH, flexShrink: 0 }} />
           <div style={{ flex: 1, display: 'flex' }}>
             <GraphicsColumnLabelsRow scaleColumns={scaleColumns} question={question} />
@@ -285,15 +347,15 @@ function CsatMatrixGrid({
         {statementRows.map((row, rowIdx) => (
           <div key={row.id} style={{
             display: 'flex', alignItems: 'center', borderRadius: '8px',
-            padding: '12px 0', ...matrixRowBackgroundStyle(rowIdx),
+            padding: '12px 0', minWidth: 0, ...matrixRowBackgroundStyle(rowIdx),
           }}>
-            <div style={{ width: MATRIX_ROW_LABEL_WIDTH, flexShrink: 0, padding: '0 16px' }}>
+            <div style={{ width: MATRIX_ROW_LABEL_WIDTH, flexShrink: 0, minWidth: 0, padding: '0 12px' }}>
               <span style={{ fontSize: '14px', fontWeight: 500, color: '#111827', lineHeight: 1.4 }}
                 dangerouslySetInnerHTML={{ __html: row.statementText }} />
             </div>
 
             {isGraphics ? (
-              <div style={{ flex: 1, padding: '0 24px', position: 'relative', display: 'flex', flexDirection: 'column', justifyContent: 'center' }}>
+              <div style={{ flex: 1, minWidth: 0, padding: '0 8px', position: 'relative', display: 'flex', flexDirection: 'column', justifyContent: 'center' }}>
                 <CustomSliderTrack
                   min={0}
                   max={scaleColumns.length - 1}
@@ -450,40 +512,47 @@ function CsatMatrixCarousel({
   const showLabels = labels && labels.length > 0;
 
   return (
-    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', backgroundColor: '#fff', borderRadius: '12px', border: '1px solid #e5e5e5', padding: '32px', boxShadow: '0 4px 6px -1px rgba(0,0,0,0.05)', width: '100%', boxSizing: 'border-box' }}>
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', backgroundColor: '#fff', borderRadius: '12px', border: '1px solid #e5e5e5', padding: '24px 16px', boxShadow: '0 4px 6px -1px rgba(0,0,0,0.05)', width: '100%', maxWidth: '100%', minWidth: 0, overflowX: 'auto', boxSizing: 'border-box' }}>
       <h3 style={{ fontSize: '18px', fontWeight: 500, color: '#111827', marginBottom: '32px', textAlign: 'center' }} dangerouslySetInnerHTML={{ __html: row.statementText }} />
       
       {showLabels && scaleColumns.length > 0 && (
-        <div style={{ width: '100%', maxWidth: '800px', display: 'flex', position: 'relative', height: '24px', marginBottom: '16px' }}>
+        <div style={{
+          width: '100%',
+          maxWidth: '100%',
+          minWidth: 0,
+          position: 'relative',
+          minHeight: anchorLabelRowMinHeight(question, Boolean(showLabels)),
+          marginBottom: '16px',
+          ...(isGraphics || question.type === 'RATING_MATRIX' ? { padding: '0 8px' } : {}),
+        }}>
           {labels!.map((label, i) => {
             const m = scaleColumns.length;
             const n = labels!.length;
-            const startPercent = isGraphics ? 0 : 0.5 / m;
-            const rangePercent = isGraphics ? 1 : (m - 1) / m;
-            const percent = n === 1 ? 50 : (startPercent + (i / (n - 1)) * rangePercent) * 100;
+            const percent = anchorLabelPositionPercent(i, n, m, isGraphics, question);
 
             return (
               <div key={i} style={{
-                position: 'absolute', left: `${percent}%`, transform: 'translateX(-50%)',
-                textAlign: 'center', fontSize: '13px', fontWeight: 600,
-                lineHeight: 1.3, whiteSpace: 'nowrap',
-                ...anchorLabelStyle(question),
+                position: 'absolute',
+                left: `${percent}%`,
+                bottom: 0,
+                transform: 'translateX(-50%)',
+                ...anchorLabelBoxStyle(question, isGraphics),
               }}>
-                {label}
+                {renderAnchorLabelContent(label, question)}
               </div>
             );
           })}
         </div>
       )}
 
-      {isGraphics && scaleColumns.length > 0 && (
-        <div style={{ width: '100%', maxWidth: '800px', marginBottom: showLabels ? '8px' : '16px' }}>
+      {shouldShowGraphicsColumnLabelRow(isGraphics, labels) && scaleColumns.length > 0 && (
+        <div style={{ width: '100%', maxWidth: '100%', marginBottom: '16px' }}>
           <GraphicsColumnLabelsRow scaleColumns={scaleColumns} question={question} />
         </div>
       )}
 
       {isGraphics ? (
-        <div style={{ width: '100%', maxWidth: '800px', marginBottom: '40px', padding: '0 24px' }}>
+        <div style={{ width: '100%', maxWidth: '100%', minWidth: 0, marginBottom: '40px', padding: '0 8px' }}>
            <CustomSliderTrack
             min={0} max={scaleColumns.length - 1} htmlStep={1}
             value={

package/templates/docs/templates/CustomSliderTrack.tsx

@@ -56,7 +56,7 @@ export function CustomSliderTrack({
 
   return (
     <div
-      style={{ position: 'relative', height: '32px', display: 'flex', alignItems: 'center', margin: '0 16px', opacity: disabled ? 0.5 : 1 }}
+      style={{ position: 'relative', height: '32px', display: 'flex', alignItems: 'center', margin: '0 8px', opacity: disabled ? 0.5 : 1 }}
       onMouseEnter={() => !disabled && setIsHovered(true)}
       onMouseLeave={() => { setIsHovered(false); setIsDragging(false); }}
     >
@@ -94,7 +94,7 @@ export function CustomSliderTrack({
         onTouchStart={() => !disabled && setIsDragging(true)}
         onTouchEnd={() => setIsDragging(false)}
         style={{
-          position: 'absolute', top: '50%', left: '-16px', right: '-16px', width: 'calc(100% + 32px)', height: '100%',
+          position: 'absolute', top: '50%', left: '-8px', right: '-8px', width: 'calc(100% + 16px)', height: '100%',
           transform: 'translateY(-50%)', opacity: 0, cursor: disabled ? 'not-allowed' : 'pointer', zIndex: 10, margin: 0,
         }}
       />

package/templates/docs/templates/Footer.tsx

@@ -39,10 +39,11 @@ export default function Footer() {
               data-cfm-logo
               src={seedLogoSrc!}
               alt=""
-              className="object-contain"
+              className="object-contain object-left"
               style={{
-                width: 'var(--cfm-footer-logo-width, 120px)',
                 height: 'var(--cfm-footer-logo-height, 32px)',
+                maxWidth: 'var(--cfm-footer-logo-width, 120px)',
+                width: 'auto',
               }}
             />
           </div>

package/templates/docs/templates/Header.tsx

@@ -76,20 +76,20 @@ export default function Header({ embedded = false }: HeaderProps) {
             {seedCompany}
           </span>
 
-          {seedCompany ? (
-            <span
-              data-cfm-company
-              className="font-semibold"
-              style={{
-                display: hasLogoFile && seedShowCompany ? undefined : 'none',
-                color: 'var(--cfm-header-company-color, var(--cfm-text))',
-                fontSize: 'var(--cfm-header-company-size, 18px)',
-                fontWeight: 'var(--cfm-header-company-weight, 600)',
-              }}
-            >
-              {seedCompany}
-            </span>
-          ) : null}
+          {/* Always in DOM for wizard bridge — visibility toggled via layoutFlags.showCompanyName */}
+          <span
+            data-cfm-company
+            className="font-semibold"
+            style={{
+              display:
+                seedCompany && hasLogoFile && seedShowCompany ? undefined : 'none',
+              color: 'var(--cfm-header-company-color, var(--cfm-text))',
+              fontSize: 'var(--cfm-header-company-size, 18px)',
+              fontWeight: 'var(--cfm-header-company-weight, 600)',
+            }}
+          >
+            {seedCompany}
+          </span>
         </div>
       </div>
     </header>

package/templates/docs/templates/LikertMatrixScale.tsx

@@ -248,7 +248,7 @@ function LikertMatrixGridLayout({
   };
 
   return (
-    <div style={{ width: '100%' }}>
+    <div style={{ width: '100%', maxWidth: '100%', minWidth: 0, overflowX: 'auto', boxSizing: 'border-box' }}>
       {!repeatColumnHeaders && renderHeader()}
 
       <div style={{ display: 'flex', flexDirection: 'column', gap: repeatColumnHeaders ? '24px' : '0' }}>
@@ -326,7 +326,7 @@ function LikertMatrixGridLayout({
                 </div>
 
                 {isBipolar && (
-                  <div style={{ flex: '0 0 25%', padding: '0 16px', textAlign: 'right', boxSizing: 'border-box' }}>
+                  <div style={{ flex: `0 0 ${BIPOLAR_COL_WIDTH}`, padding: '0 16px', textAlign: 'right', boxSizing: 'border-box' }}>
                     <span style={{ fontSize: '14px', fontWeight: 500, color: '#111827', lineHeight: 1.4, wordWrap: 'break-word', display: 'block' }}
                       dangerouslySetInnerHTML={{ __html: transposeTable ? '' : ('oppositeStatementText' in rowItem ? rowItem.oppositeStatementText ?? '' : '') }} />
                   </div>

package/templates/docs/templates/Question.tsx

@@ -19,7 +19,7 @@ import { FileUploadScale } from './FileUploadScale';
 import { HeatmapScale } from './HeatmapScale';
 import { RankOrderScale } from './RankOrderScale';
 import RatingScale from './RatingScale';
-import { getLayoutFlags } from '@/lib/uiConfig';
+import { showQuestionNumbersInChrome, showRequiredAsteriskInChrome, resolveNpsButtonStyle, resolveNpsHintMinLabel, resolveNpsHintMaxLabel } from '@/lib/uiConfig';
 import { hintLabelStyle } from '@/lib/surveyUi/labelStyles';
 import {
   mcqCheckboxControlStyle,
@@ -48,7 +48,8 @@ export default function Question({
   customFieldValues = {},
   onSelect,
 }: QuestionProps) {
-  const { showQuestionNumbers, showRequiredAsterisk } = getLayoutFlags();
+  const showNumbers = showQuestionNumbersInChrome();
+  const showAsterisk = showRequiredAsteriskInChrome();
 
   const questionsById = useMemo(
     () => new Map(allQuestions.map(q => [q.id, q])),
@@ -125,31 +126,35 @@ export default function Question({
         borderRadius: 'var(--cfm-border-radius, 12px)',
         fontFamily: 'var(--cfm-font-family)',
         marginBottom: 'var(--cfm-card-gap, 32px)',
+        maxWidth: '100%',
+        overflowX: 'auto',
+        boxSizing: 'border-box',
       }}
     >
       <h2
         className="text-lg font-medium leading-relaxed"
         style={{ color: 'var(--cfm-text, #111827)' }}
       >
-        {question.questionNumber != null && (
-          <span
-            data-cfm-question-number
-            className="mr-1 font-semibold"
-            style={{ display: showQuestionNumbers ? undefined : 'none' }}
-          >
-            {question.questionNumber}.
-          </span>
-        )}
+        <span
+          data-cfm-question-number
+          className="mr-1 font-semibold"
+          style={{
+            display:
+              question.questionNumber != null && showNumbers ? undefined : 'none',
+          }}
+        >
+          {question.questionNumber != null ? `${question.questionNumber}.` : ''}
+        </span>
         <span dangerouslySetInnerHTML={{ __html: displayQuestionText }} />
-        {question.required && (
-          <span
-            data-cfm-required
-            className="ml-1 text-red-500"
-            style={{ display: showRequiredAsterisk ? undefined : 'none' }}
-          >
-            *
-          </span>
-        )}
+        <span
+          data-cfm-required
+          className="ml-1 text-red-500"
+          style={{
+            display: question.required && showAsterisk ? undefined : 'none',
+          }}
+        >
+          *
+        </span>
       </h2>
       {displayQuestionDescription && (
         <div
@@ -165,7 +170,8 @@ export default function Question({
               <span
                 className="absolute left-0 top-0 max-w-[30%] text-left leading-tight"
                 style={{ ...hintLabelStyle(), padding: '2px 6px', borderRadius: '4px' }}
-                dangerouslySetInnerHTML={{ __html: question.minLabel ?? '' }}
+                data-cfm-hint-min
+                dangerouslySetInnerHTML={{ __html: resolveNpsHintMinLabel(question.minLabel ?? '') }}
               />
               {question.midLabel && (
                 <span
@@ -184,7 +190,8 @@ export default function Question({
               <span
                 className="absolute right-0 top-0 max-w-[30%] text-right leading-tight"
                 style={{ ...hintLabelStyle(), padding: '2px 6px', borderRadius: '4px' }}
-                dangerouslySetInnerHTML={{ __html: question.maxLabel ?? '' }}
+                data-cfm-hint-max
+                dangerouslySetInnerHTML={{ __html: resolveNpsHintMaxLabel(question.maxLabel ?? '') }}
               />
             </div>
           )}
@@ -194,7 +201,7 @@ export default function Question({
             selectedValue={selectedValue}
             onSelect={onSelect}
             variant="nps"
-            buttonStyle={question.buttonStyle}
+            buttonStyle={resolveNpsButtonStyle(question.buttonStyle)}
           />
         </div>
       )}

package/templates/docs/templates/RankOrderScale.tsx

@@ -182,8 +182,16 @@ function DropdownRankLayout({
                 aria-label={`Rank for ${option.optionLabel || option.id}`}
                 value={currentRank ?? ''}
                 onChange={event => handleRankChange(option.id, event.target.value)}
-                className="h-10 w-16 shrink-0 rounded border bg-white px-2 text-sm outline-none"
-                style={{ borderColor: 'var(--cfm-rank-select-border, #d1d5db)' }}
+                className="h-10 w-16 shrink-0 rounded border px-2 text-sm font-semibold outline-none"
+                style={{
+                  borderColor: 'var(--cfm-rank-select-border, #d1d5db)',
+                  backgroundColor: currentRank
+                    ? 'var(--cfm-rank-badge-bg, var(--cfm-mcq-selected-bg, #fdf2f8))'
+                    : '#ffffff',
+                  color: currentRank
+                    ? 'var(--cfm-rank-badge-text, var(--cfm-mcq-selected-accent, var(--cfm-primary, #e20074)))'
+                    : '#374151',
+                }}
                 onFocus={e => {
                   e.currentTarget.style.borderColor = focusRingVar;
                   e.currentTarget.style.boxShadow = `0 0 0 1px ${focusRingVar}`;

package/templates/docs/templates/SliderMatrixScale.tsx

@@ -168,7 +168,7 @@ export function SliderMatrixScale({ question, selectedValue = {}, onSelect }: Sl
   };
 
   return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px', width: '100%', maxWidth: '100%', minWidth: 0, overflowX: 'auto', boxSizing: 'border-box' }}>
       {renderHeaderRow()}
 
       {statementRows.map(row => {

package/templates/docs/templates/labelStyles.ts

@@ -64,3 +64,30 @@ export function ratingColumnLabelStyle(): CSSProperties {
 export function sliderTickLabelStyle(): CSSProperties {
   return columnLabelPillStyle('sliderTick');
 }
+
+/** Split multi-word anchor labels into stacked lines for equal-width matrix headers. */
+export function stackAnchorLabelLines(label: string): string[] {
+  const trimmed = label.trim();
+  if (!trimmed) return [''];
+  const words = trimmed.split(/\s+/);
+  if (words.length <= 1) return [trimmed];
+  const mid = Math.ceil(words.length / 2);
+  return [words.slice(0, mid).join(' '), words.slice(mid).join(' ')].filter(Boolean);
+}
+
+/** Rating matrix anchor pills — stacked text, fixed width, same look on every format. */
+export function ratingAnchorLabelPillStyle(): CSSProperties {
+  return {
+    ...columnLabelPillStyle('rating'),
+    display: 'inline-flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    justifyContent: 'center',
+    whiteSpace: 'normal',
+    maxWidth: '72px',
+    minWidth: '52px',
+    padding: '3px 6px',
+    wordBreak: 'break-word',
+    lineHeight: 1.15,
+  };
+}

package/templates/docs/templates/uiConfig.ts

@@ -82,6 +82,29 @@ export function getLayoutFlags() {
   };
 }
 
+function readLiveChromeFlag(cssVar: string, configFallback: boolean): boolean {
+  if (typeof window === 'undefined') return configFallback;
+  const root = document.documentElement;
+  const live =
+    root.style.getPropertyValue(cssVar).trim() ||
+    getComputedStyle(root).getPropertyValue(cssVar).trim();
+  if (live === '0') return false;
+  if (live === '1') return true;
+  return configFallback;
+}
+
+/** Wizard live preview reads --cfm-show-question-numbers; production uses survey-ui-config.json. */
+export function showQuestionNumbersInChrome(): boolean {
+  const flags = getLayoutFlags();
+  return readLiveChromeFlag('--cfm-show-question-numbers', flags.showQuestionNumbers);
+}
+
+/** Wizard live preview reads --cfm-show-required-asterisk; production uses survey-ui-config.json. */
+export function showRequiredAsteriskInChrome(): boolean {
+  const flags = getLayoutFlags();
+  return readLiveChromeFlag('--cfm-show-required-asterisk', flags.showRequiredAsterisk);
+}
+
 export function getPlaceholders(): Record<string, string> {
   return { ...(surveyUiConfig.placeholders ?? {}) };
 }
@@ -89,3 +112,80 @@ export function getPlaceholders(): Record<string, string> {
 export function isDebugEnabled(): boolean {
   return surveyUiConfig.debug?.enabled === true;
 }
+
+export type NpsButtonStyle = 'standard' | 'numbered' | 'emoji' | 'pill';
+
+function readLiveNpsButtonStyle(): NpsButtonStyle | null {
+  if (typeof window === 'undefined') return null;
+  const root = document.documentElement;
+  const attr = root.getAttribute('data-cfm-nps-button-style');
+  if (attr === 'standard' || attr === 'numbered' || attr === 'emoji' || attr === 'pill') {
+    return attr;
+  }
+  const live =
+    root.style.getPropertyValue('--cfm-nps-button-style').trim() ||
+    getComputedStyle(root).getPropertyValue('--cfm-nps-button-style').trim();
+  if (live === 'standard' || live === 'numbered' || live === 'emoji' || live === 'pill') {
+    return live;
+  }
+  return null;
+}
+
+/** Wizard bridge + survey-ui-config.json override API `buttonStyle` for NPS cells. */
+export function resolveNpsButtonStyle(questionStyle?: string): NpsButtonStyle {
+  const live = readLiveNpsButtonStyle();
+  if (live) return live;
+
+  if (
+    questionStyle === 'standard' ||
+    questionStyle === 'numbered' ||
+    questionStyle === 'emoji' ||
+    questionStyle === 'pill'
+  ) {
+    return questionStyle;
+  }
+
+  const fromJson = (
+    surveyUiConfig.questionTypes as { NPS_SCALE?: { buttonStyle?: string } } | undefined
+  )?.NPS_SCALE?.buttonStyle;
+  if (
+    fromJson === 'standard' ||
+    fromJson === 'numbered' ||
+    fromJson === 'emoji' ||
+    fromJson === 'pill'
+  ) {
+    return fromJson;
+  }
+  return 'numbered';
+}
+
+function readLiveNpsHintText(kind: 'min' | 'max'): string | null {
+  if (typeof window === 'undefined') return null;
+  const root = document.documentElement;
+  const cssVar = kind === 'min' ? '--cfm-hint-min-text' : '--cfm-hint-max-text';
+  const fromCss =
+    root.style.getPropertyValue(cssVar).trim() ||
+    getComputedStyle(root).getPropertyValue(cssVar).trim();
+  return fromCss || null;
+}
+
+function resolveNpsHintText(kind: 'min' | 'max', questionFallback: string): string {
+  const fromCss = readLiveNpsHintText(kind);
+  if (fromCss) return fromCss;
+  if (questionFallback.trim()) return questionFallback;
+
+  const nps = (
+    surveyUiConfig.questionTypes as { NPS_SCALE?: { hintMinText?: string; hintMaxText?: string } } | undefined
+  )?.NPS_SCALE;
+  const fromJson = kind === 'min' ? nps?.hintMinText : nps?.hintMaxText;
+  const trimmed = fromJson?.trim();
+  return trimmed || questionFallback;
+}
+
+export function resolveNpsHintMinLabel(questionFallback = ''): string {
+  return resolveNpsHintText('min', questionFallback);
+}
+
+export function resolveNpsHintMaxLabel(questionFallback = ''): string {
+  return resolveNpsHintText('max', questionFallback);
+}