@deneb-ui/cli 2.0.23 → 2.0.25

package/bin/index.js

@@ -692,6 +692,7 @@ function initProject(targetInput, options = {}) {
     'validate-and-zip': 'deneb validate-and-zip .',
     'package:template': 'deneb package .',
     'update:deneb': 'deneb update',
+    'fonts:install': 'deneb fonts install .',
   };
   let addedCount = 0;
   for (const [key, val] of Object.entries(scriptsToAdd)) {
@@ -763,6 +764,16 @@ function initProject(targetInput, options = {}) {
     }
   }
 
+  if (!skipInstall) {
+    try {
+      const { runFontsInstall } = require('../src/tools/deneb-fonts.cjs');
+      console.log(`\n\x1b[36mAa Downloading and configuring DENEB Google Fonts...\x1b[0m`);
+      runFontsInstall(targetDir, []);
+    } catch (err) {
+      console.log(`\n\x1b[33m! Fonts were not installed automatically: ${err.message}. Run \x1b[1mdeneb fonts install .\x1b[0m\x1b[0m`);
+    }
+  }
+
   console.log(`\n\x1b[32m✔ Project initialization complete!\x1b[0m`);
   console.log(`\nYou can now run:`);
   console.log(`  \x1b[36mnpm run lab\x1b[0m               \x1b[90m# Launch Local Visual Editing Lab\x1b[0m`);
@@ -1074,6 +1085,9 @@ if (command === 'init') {
   runValidateAndZip(commandArgs[0] || '.', commandArgs.slice(1));
 } else if (command === 'update' || command === 'upgrade') {
   updateDependencies(commandArgs);
+} else if (command === 'fonts') {
+  const { runFontsCommand } = require('../src/tools/deneb-fonts.cjs');
+  process.exit(runFontsCommand(commandArgs));
 } else if (command === 'save-recipe' || command === 'learn') {
   const targetDir = path.resolve(commandArgs[0] || '.');
   const recipeName = commandArgs[1] || path.basename(targetDir);
@@ -1098,6 +1112,7 @@ Core Commands:
   doctor            Run comprehensive environment, manifest, visual editing AST & asset diagnostic checks (flags: --fix, --json)
   save-recipe       Learn and save calibrated fixes & schemas into reusable recipe bank (e.g. deneb save-recipe . shoes-store)
   learn             Alias for save-recipe
+  fonts             Google Fonts catalog — list presets or install self-hosted @fontsource packages
   update            Update DENEB packages (@deneb-ui/ui, @deneb-ui/cli) and UI components
   validate          Validate website configuration and visual editing contracts with Fivora platform
   zip               Zip the project without unnecessary folders or files (node_modules, .next, .git, .env)
@@ -1121,6 +1136,9 @@ Examples:
   deneb init --recipe electronics
   deneb init --recipe cosmetics
   deneb init --legacy
+  deneb fonts list
+  deneb fonts install .
+  deneb fonts install . --font inter --font playfair-display
   deneb update
   deneb validate .
   deneb validate --zip

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deneb-ui/cli",
-  "version": "2.0.23",
+  "version": "2.0.25",
   "description": "Official DENEB CLI — scaffold, convert, validate, and package Fivora-ready storefront templates.",
   "bin": {
     "deneb": "bin/index.js",
@@ -48,7 +48,12 @@
   "license": "MIT",
   "dependencies": {
     "@babel/parser": "^7.28.0",
+    "@deneb-ui/core": "^2.0.25",
     "adm-zip": "^0.6.0",
     "recast": "^0.23.11"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2",
+    "typescript": "^5.9.3"
   }
 }

package/src/arc/__tests__/arc.test.cjs

@@ -13,6 +13,13 @@ const { applyFilePlan } = require('../transformer.cjs');
 const { buildFieldPath, inferFieldName } = require('../field-paths.cjs');
 const { runDenebArc } = require('../index.cjs');
 const { parseSource } = require('../ast.cjs');
+const { loadFingerprintBoost } = require('../learning.cjs');
+
+test('unseen fingerprints do not change planner confidence', () => {
+  const hint = loadFingerprintBoost(null);
+  assert.equal(hint.boost, 0);
+  assert.equal(hint.skip, false);
+});
 const contract = require('../fivora-contract.cjs');
 const { ensureStaticExportConfig } = require('../next-config.cjs');
 
@@ -101,12 +108,38 @@ test('AST transformer preserves className and uses nullish fallbacks', () => {
   assert.match(result.code, /className="hero"/);
   assert.match(result.code, /data-preview-field-path=/);
   assert.match(result.code, /\?\?/);
-  assert.match(result.code, /<span data-preview-field-path="/);
+  assert.match(result.code, /<span[\s\S]*data-preview-field-path="/);
   assert.doesNotMatch(result.code, /'use client'/);
   assert.match(result.code, /site-data\.json|@\/data\/site-data\.json/);
+  assert.match(result.code, /data-preview-style-target=/);
+  assert.match(result.code, /data-preview-style-type="text"/);
   parseSource(result.code, relativeFile);
 });
 
+test('planner emits style-bind next to content transforms', () => {
+  const relativeFile = 'src/components/Hero.tsx';
+  const code = fs.readFileSync(path.join(FIXTURE, relativeFile), 'utf8');
+  const analysis = analyzeFile({
+    code,
+    relativeFile,
+    profile: scanProject(FIXTURE),
+    graph: { sharedFiles: [] },
+    ownerScope: 'home',
+    componentMeta: { name: 'Hero', role: 'hero' },
+  });
+  analysis.relativeFile = relativeFile;
+  analysis.code = code;
+  const plan = planTransformations({
+    profile: scanProject(FIXTURE),
+    analyses: [analysis],
+    recipe: { actionRules: { splitActionAndLabel: true } },
+  });
+  const binds = plan.files[0].transformations.filter((t) => t.operation === 'style-bind');
+  assert.ok(binds.length >= 1, 'expected style-bind operations');
+  assert.ok(binds.every((t) => t.stylePath && t.styleKind));
+  assert.ok(plan.stats.styleBinds >= 1);
+});
+
 test('dry-run does not modify source files', () => {
   const dir = copyFixture();
   const before = fs.readFileSync(path.join(dir, 'src', 'components', 'Hero.tsx'), 'utf8');
@@ -142,6 +175,11 @@ test('ARC converts a Next.js fixture into Fivora contracts without redesigning',
   assert.doesNotMatch(promo, /use client';;/);
   assert.doesNotMatch(JSON.stringify(siteData.content), /VANTA/);
   assert.ok(siteData.content.home.hero.title);
+  assert.ok(siteData.theme?.headingFont);
+  assert.ok(siteData.theme?.bodyFont);
+  assert.equal(typeof siteData.styles, 'object');
+  assert.ok(Object.keys(siteData.styles).length >= 1, 'style-bind seeds site-data.styles');
+  assert.match(hero, /data-preview-style-type=/);
   assert.ok(manifest.editorSchema.sections.length >= 1);
   assert.ok(manifest.editorSchema.sections.length < 12);
   assert.equal(manifest.arcVersion, result.arcVersion);
@@ -150,8 +188,8 @@ test('ARC converts a Next.js fixture into Fivora contracts without redesigning',
   const second = silence(() => runDenebArc(dir, 'arc-fixture', { telemetry: 'off' }));
   assert.equal(second.outcome, 'success');
   const hero2 = fs.readFileSync(path.join(dir, 'src', 'components', 'Hero.tsx'), 'utf8');
-  const spanCount1 = (hero.match(/<span data-preview-field-path=/g) || []).length;
-  const spanCount2 = (hero2.match(/<span data-preview-field-path=/g) || []).length;
+  const spanCount1 = (hero.match(/<span[\s\S]*?data-preview-field-path=/g) || []).length;
+  const spanCount2 = (hero2.match(/<span[\s\S]*?data-preview-field-path=/g) || []).length;
   assert.equal(spanCount2, spanCount1);
 });
 
@@ -301,6 +339,8 @@ test('static-array collections become list contracts without changing render log
   const grid = fs.readFileSync(path.join(dir, 'src', 'components', 'ProductGrid.tsx'), 'utf8');
 
   assert.match(grid, /data-preview-list-path="home\.products"/);
+  assert.match(grid, /data-preview-style-type="grid"/);
+  assert.match(grid, /data-preview-style-type="card"/);
   assert.match(grid, /data-preview-item-path=\{`home\.products\[\$\{index\}\]`\}/);
   assert.match(grid, /data-preview-field-path=\{`home\.products\[\$\{index\}\]\.title`\}/);
   // The array is site-data backed with the developer's literal as fallback.
@@ -332,7 +372,7 @@ test('literal text inside a broad container is wrapped instead of marked illegal
   const about = fs.readFileSync(path.join(dir, 'src', 'app', 'about', 'page.tsx'), 'utf8');
 
   // Fivora rejects data-preview-field-path on <div>, so the text gets a span.
-  assert.match(about, /<div className="mt-10 text-sm text-slate-500">\s*<span data-preview-field-path=/);
+  assert.match(about, /<div[\s\S]*className="mt-10 text-sm text-slate-500"[\s\S]*<span[\s\S]*data-preview-field-path=/);
   assert.ok(!/<div[^>]*data-preview-field-path/.test(about));
 });
 
@@ -343,7 +383,7 @@ test('shadcn Button asChild keeps the action on the link and the label in a span
 
   assert.match(hero, /<Button asChild>/);
   assert.match(hero, /href=\{siteData\?\.content\?\.home\?\.hero\?\.shopCollectionUrl \?\? "\/products"\}/);
-  assert.match(hero, /<span data-preview-field-path="home\.hero\.shopCollectionLabel">/);
+  assert.match(hero, /<span[\s\S]*data-preview-field-path="home\.hero\.shopCollectionLabel"/);
   // The decorative icon stays static.
   assert.match(hero, /<ArrowRight className="ml-2 size-4" aria-hidden="true" \/>/);
 });
@@ -385,7 +425,7 @@ test('Pages Router projects convert and satisfy the strict contract', () => {
   assert.match(index, /from "\.\.\/data\/site-data\.json"/);
   // tel: actions are split into url + label.
   assert.match(index, /href=\{siteData\?\.content\?\.home\?\.contact\?\.phoneUrl \?\? "tel:\+94771234567"\}/);
-  assert.match(index, /<span data-preview-field-path="home\.contact\.phoneLabel">/);
+  assert.match(index, /<span[\s\S]*data-preview-field-path="home\.contact\.phoneLabel"/);
   // Original class names are untouched.
   assert.match(index, /className="wrapper"/);
   assert.match(contact, /className="photo"/);

package/src/arc/ast.cjs

@@ -229,7 +229,7 @@ function wrapTextInEditableSpan(fieldPath, fallback, fieldType) {
   return b.jsxElement(
     b.jsxOpeningElement(
       b.jsxIdentifier('span'),
-      [jsxPreviewAttr(fieldPath)],
+      [jsxPreviewAttr(fieldPath), ...jsxStyleAttrs(fieldPath, 'text')],
       false
     ),
     b.jsxClosingElement(b.jsxIdentifier('span')),
@@ -238,6 +238,20 @@ function wrapTextInEditableSpan(fieldPath, fallback, fieldType) {
   );
 }
 
+function jsxStyleAttrs(stylePath, kind) {
+  if (!stylePath || !kind) return [];
+  return [
+    b.jsxAttribute(b.jsxIdentifier('data-preview-style-target'), b.stringLiteral(stylePath)),
+    b.jsxAttribute(b.jsxIdentifier('data-preview-style-type'), b.stringLiteral(kind)),
+  ];
+}
+
+function ensureStyleAttrs(node, stylePath, kind) {
+  if (!node || !node.openingElement || !stylePath || !kind) return;
+  if (hasJsxAttribute(node, 'data-preview-style-target')) return;
+  node.openingElement.attributes.push(...jsxStyleAttrs(stylePath, kind));
+}
+
 function hasDirective(ast, value) {
   const program = ast.program || ast;
   const first = program.body && program.body[0];
@@ -310,6 +324,8 @@ module.exports = {
   siteDataBinding,
   siteDataListBinding,
   jsxPreviewAttr,
+  jsxStyleAttrs,
+  ensureStyleAttrs,
   jsxStaticAttr,
   jsxTemplatePathAttr,
   wrapTextInEditableSpan,

package/src/arc/font-plan.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+function tryCoreFonts() {
+  try {
+    return require('@deneb-ui/core');
+  } catch {
+    try {
+      return require('../../../../packages/deneb-core/dist/index.js');
+    } catch {
+      return null;
+    }
+  }
+}
+
+const core = tryCoreFonts();
+
+function collectFontIdsFromSiteData(siteData) {
+  if (core && typeof core.collectFontIdsFromSiteData === 'function') {
+    const ids = core.collectFontIdsFromSiteData(siteData);
+    if (ids && ids.length) return ids;
+  }
+  const defaults = (core && core.DEFAULT_PROJECT_FONT_IDS) || ['inter', 'plus-jakarta-sans', 'playfair-display'];
+  return [...defaults];
+}
+
+function applyFontTheme(siteData, fontIds) {
+  const next = siteData && typeof siteData === 'object' ? siteData : {};
+  const theme = { ...(next.theme || {}) };
+  const structureTheme = next.template?.structure?.theme;
+  if (isPlain(structureTheme)) {
+    Object.assign(theme, structureTheme);
+  }
+  if (!theme.headingFont) {
+    theme.headingFont = prettyFont(fontIds[1] || fontIds[0] || 'inter');
+  }
+  if (!theme.bodyFont) {
+    theme.bodyFont = prettyFont(fontIds[0] || 'inter');
+  }
+  next.theme = theme;
+  if (next.template && next.template.structure) {
+    next.template.structure.theme = {
+      ...(next.template.structure.theme || {}),
+      headingFont: theme.headingFont,
+      bodyFont: theme.bodyFont,
+    };
+  }
+  return next;
+}
+
+function prettyFont(id) {
+  if (core && typeof core.lookupFontDefinition === 'function') {
+    const def = core.lookupFontDefinition(id);
+    if (def?.label) return def.label;
+  }
+  return String(id || 'Inter');
+}
+
+function isPlain(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+module.exports = {
+  collectFontIdsFromSiteData,
+  applyFontTheme,
+};

package/src/arc/index.cjs

@@ -477,11 +477,7 @@ function runDenebArc(projectDir, projectName, options = {}) {
   } else {
     console.log('  \x1b[32m✓\x1b[0m Fivora strict contract');
   }
-  if (fivoraAudit.uncoveredVisibleText.length) {
-    console.log(
-      `  \x1b[33m⚠\x1b[0m ${fivoraAudit.uncoveredVisibleText.length} visible text node(s) still uncovered — run \x1b[1mdeneb validate .\x1b[0m before packaging`
-    );
-  }
+  printer.printUncoveredText(fivoraAudit.uncoveredVisibleText);
   coverage.actionLinkContracts = contracts.fieldPaths.filter((p) => /Url$/.test(p)).length;
   coverage.contractCollisions = contracts.actionCollisions;
   console.log(`  Action/link contracts validated: ${coverage.actionLinkContracts}`);
@@ -560,7 +556,10 @@ function runDenebArc(projectDir, projectName, options = {}) {
   writeJson(path.join(journalDir, 'validation.json'), validation);
   writeJson(path.join(projectDir, '.deneb', 'report.json'), report);
 
-  if (outcome === 'success') printer.printSuccess();
+  if (outcome === 'success') {
+    printer.printSuccess();
+    printer.printDeveloperNextSteps();
+  }
   return result;
 }
 

package/src/arc/learning.cjs

@@ -85,6 +85,29 @@ function recordExperience({ projectDir, profile, plan, validation, outcome, tele
   return records;
 }
 
+function loadFingerprintBoost(fingerprint) {
+  if (!fingerprint) {
+    return { boost: 0, skip: false, state: null };
+  }
+  try {
+    const store = readJsonSafe(fingerprintStorePath(), { fingerprints: {} }) || { fingerprints: {} };
+    const entry = store.fingerprints?.[fingerprint];
+    if (!entry) return { boost: 0, skip: false, state: null };
+    if (entry.state === 'deprecated') {
+      return { boost: 0, skip: true, state: 'deprecated' };
+    }
+    if (entry.state === 'verified') {
+      return { boost: 0.08, skip: false, state: 'verified' };
+    }
+    if (entry.state === 'candidate') {
+      return { boost: 0.03, skip: false, state: 'candidate' };
+    }
+    return { boost: 0, skip: false, state: entry.state || 'observed' };
+  } catch {
+    return { boost: 0, skip: false, state: null };
+  }
+}
+
 function mapOperation(operation) {
   switch (operation) {
     case 'extract-text':
@@ -96,6 +119,8 @@ function mapOperation(operation) {
       return 'url-extraction';
     case 'split-action-contract':
       return 'contract-split';
+    case 'style-bind':
+      return 'style-bind';
     case 'collection-conversion':
       return 'collection-conversion';
     default:
@@ -176,6 +201,7 @@ function redactSecrets(value) {
 
 module.exports = {
   recordExperience,
+  loadFingerprintBoost,
   registryArchitecture,
   redactSecrets,
   promoteState,

package/src/arc/manifest.cjs

@@ -3,6 +3,7 @@
 const path = require('path');
 const { readJsonSafe, writeJson, deepMerge, isPlainObject } = require('./fs-utils.cjs');
 const { ARC_VERSION, SCHEMA_VERSION } = require('./version.cjs');
+const { collectFontIdsFromSiteData, applyFontTheme } = require('./font-plan.cjs');
 const { humanLabel, classifyFieldType } = require('./field-paths.cjs');
 const {
   enumerateContentPaths,
@@ -154,6 +155,18 @@ function collectFieldsFromPlan(plan) {
   return fields;
 }
 
+function collectStylesFromPlan(plan, existingStyles) {
+  const styles = isPlainObject(existingStyles) ? { ...existingStyles } : {};
+  for (const file of plan.files || []) {
+    for (const t of file.transformations || []) {
+      if (t.operation !== 'style-bind' || !t.stylePath) continue;
+      if (t.stylePath.includes('[*]')) continue;
+      if (!styles[t.stylePath]) styles[t.stylePath] = {};
+    }
+  }
+  return styles;
+}
+
 function baseContent(projectName, routes) {
   const navLabels = {};
   for (const page of routes) navLabels[page.id] = page.label || page.id;
@@ -339,8 +352,12 @@ function buildSiteDataAndManifest({
       requiredFeatures: [],
     },
     content,
+    styles: collectStylesFromPlan(plan, existingSiteData?.styles),
+    ...(isPlainObject(existingSiteData?.theme) ? { theme: { ...existingSiteData.theme } } : {}),
   };
 
+  applyFontTheme(siteData, collectFontIdsFromSiteData(siteData));
+
   if (!siteData.template.structure) siteData.template.structure = {};
   siteData.template.structure.pages = routes.map((p) => p.id);
 

package/src/arc/planner.cjs

@@ -3,6 +3,8 @@
 const { CONFIDENCE } = require('./version.cjs');
 const { inferSection, inferFieldName, buildFieldPath, classifyFieldType, uniquePath } = require('./field-paths.cjs');
 const { classifyHref } = require('./adapters.cjs');
+const { loadFingerprintBoost } = require('./learning.cjs');
+const { appendStyleBindTransforms } = require('./style-candidates.cjs');
 
 function recipeBoost(candidate, recipe) {
   if (!recipe) return 0;
@@ -30,7 +32,21 @@ function planTransformations({ profile, analyses, recipe }) {
   for (const analysis of analyses) {
     const transformations = [];
     for (const candidate of analysis.candidates || []) {
-      const confidence = Math.min(0.99, (candidate.confidence || 0) + recipeBoost(candidate, recipe));
+      const fingerprintHint = loadFingerprintBoost(candidate.fingerprint);
+      if (fingerprintHint.skip) {
+        skipped.push({
+          file: candidate.file,
+          loc: candidate.loc,
+          reason: 'fingerprint-deprecated',
+          confidence: candidate.confidence || 0,
+          kind: candidate.kind,
+        });
+        continue;
+      }
+      const confidence = Math.min(
+        0.99,
+        (candidate.confidence || 0) + recipeBoost(candidate, recipe) + (fingerprintHint.boost || 0),
+      );
       const decision = decideThreshold(confidence, candidate);
       const section = inferSection({
         componentName: candidate.componentName,
@@ -75,6 +91,8 @@ function planTransformations({ profile, analyses, recipe }) {
           why: candidate.reason,
           recipe: recipe?.name || null,
           confidence,
+          fingerprintBoost: fingerprintHint.boost || 0,
+          fingerprintState: fingerprintHint.state || null,
         },
       };
 
@@ -188,6 +206,8 @@ function planTransformations({ profile, analyses, recipe }) {
     });
   }
 
+  appendStyleBindTransforms(filePlans);
+
   return {
     files: filePlans,
     skipped,
@@ -212,12 +232,17 @@ function summarizePlan(filePlans, skipped) {
   const auto = filePlans.reduce((n, f) => n + f.transformations.filter((t) => t.decision === 'auto').length, 0);
   const validate = filePlans.reduce((n, f) => n + f.transformations.filter((t) => t.decision === 'validate').length, 0);
   const filesAffected = filePlans.filter((f) => f.transformations.length > 0).length;
+  const styleBinds = filePlans.reduce(
+    (n, f) => n + f.transformations.filter((t) => t.operation === 'style-bind').length,
+    0,
+  );
   return {
     planned,
     auto,
     validate,
     skipped: skipped.length,
     filesAffected,
+    styleBinds,
   };
 }
 

package/src/arc/printer.cjs

@@ -67,6 +67,7 @@ function printPlan(plan) {
   if (plan.stats.validate) info(`${plan.stats.validate} transformations queued with extra validation`);
   const skippedDynamic = plan.skipped.filter((s) => /dynamic|api/.test(s.reason || '')).length;
   const skippedLow = plan.skipped.filter((s) => (s.confidence || 1) < 0.6).length;
+  if (plan.stats.styleBinds) ok(`${plan.stats.styleBinds} Fivora style-bind contracts`);
   if (skippedDynamic) ok(`${skippedDynamic} existing dynamic values preserved`);
   if (skippedLow) warn(`${skippedLow} low-confidence candidates skipped`);
 }
@@ -96,8 +97,12 @@ function printExplain(plan) {
     if (!file.transformations.length) continue;
     console.log(`  ${C.bold}${file.file}${C.reset}`);
     for (const t of file.transformations) {
-      console.log(`    - ${t.operation} ${t.field || t.urlField || ''}`);
-      console.log(`      ${C.dim}why: ${t.reason}  confidence: ${t.confidence}  recipe: ${t.recipeId || 'none'}${C.reset}`);
+      const target = t.stylePath || t.field || t.urlField || t.listField || '';
+      console.log(`    - ${t.operation} ${target}`);
+      const boost = t.explain?.fingerprintBoost
+        ? `  fingerprint: ${t.explain.fingerprintState}+${t.explain.fingerprintBoost}`
+        : '';
+      console.log(`      ${C.dim}why: ${t.reason}  confidence: ${t.confidence}  recipe: ${t.recipeId || 'none'}${boost}${C.reset}`);
     }
   }
 }
@@ -130,6 +135,29 @@ function printSuccess() {
   console.log(`\n${C.green}${C.bold}Deneb ARC completed successfully.${C.reset}\n`);
 }
 
+function printUncoveredText(findings = []) {
+  if (!findings.length) return;
+  warn(`${findings.length} visible text node(s) still uncovered — run deneb validate . before packaging`);
+  for (const item of findings.slice(0, 12)) {
+    const loc = item.filePath ? `${item.filePath}${item.line ? `:${item.line}` : ''}` : '';
+    const snippet = String(item.text || '').slice(0, 80);
+    console.log(`    ${C.dim}${loc}  <${item.tag}> ${snippet}${C.reset}`);
+  }
+  if (findings.length > 12) {
+    console.log(`    ${C.dim}... ${findings.length - 12} more in .deneb/report.json${C.reset}`);
+  }
+}
+
+function printDeveloperNextSteps() {
+  heading('Next steps for Fivora');
+  console.log(`  ${C.cyan}1.${C.reset} npm run lab              ${C.dim}preview visual editing locally${C.reset}`);
+  console.log(`  ${C.cyan}2.${C.reset} deneb fonts install .    ${C.dim}self-host Google Fonts used by this site${C.reset}`);
+  console.log(`  ${C.cyan}3.${C.reset} npm run validate         ${C.dim}same contract Fivora ingest uses${C.reset}`);
+  console.log(`  ${C.cyan}4.${C.reset} npm run validate-and-zip ${C.dim}upload-ready ZIP${C.reset}`);
+  console.log(`  ${C.dim}Style edits: Fivora sends FIVORA_PREVIEW_STYLE_PATCH to data-preview-style-target nodes.${C.reset}`);
+  console.log(`  ${C.dim}Re-run with --explain to see why each field/style was bound.${C.reset}\n`);
+}
+
 function printRollback(reason) {
   console.log(`\n${C.yellow}Deneb ARC rolled back the conversion.${C.reset}`);
   console.log(`${C.dim}${reason}${C.reset}\n`);
@@ -146,6 +174,8 @@ module.exports = {
   printDryRun,
   printError,
   printSuccess,
+  printUncoveredText,
+  printDeveloperNextSteps,
   printRollback,
   ok,
   warn,

package/src/arc/style-candidates.cjs

@@ -0,0 +1,72 @@
+'use strict';
+
+const TEXT_OPS = new Set(['extract-text', 'wrap-text-span']);
+const BUTTON_TAGS = new Set(['button', 'Button', 'CTAButton']);
+
+function inferStyleKind(transform) {
+  if (transform.operation === 'collection-conversion') return 'grid';
+  if (transform.operation === 'split-action-contract') return 'text';
+  if (BUTTON_TAGS.has(transform.tag) && transform.operation === 'extract-text') return 'button';
+  if (TEXT_OPS.has(transform.operation)) return 'text';
+  return null;
+}
+
+function stylePathFor(transform, kind) {
+  if (kind === 'grid' && transform.listField) return `${transform.listField}.grid`;
+  if (kind === 'card' && transform.listField) return `${transform.listField}[*].card`;
+  if (transform.operation === 'split-action-contract') return transform.labelField;
+  return transform.field || transform.labelField || null;
+}
+
+/**
+ * Adds explainable style-bind operations next to content transforms so
+ * developers see why Fivora can restyle a node without CSS rewrites.
+ */
+function appendStyleBindTransforms(filePlans) {
+  for (const file of filePlans || []) {
+    const extra = [];
+    for (const transform of file.transformations || []) {
+      if (transform.operation === 'style-bind') continue;
+      if (transform.operation === 'wrap-text-span') continue;
+      if (transform.operation === 'collection-conversion' && transform.listField) {
+        extra.push(makeStyleBind(transform, `${transform.listField}.grid`, 'grid'));
+        extra.push(makeStyleBind(transform, `${transform.listField}[*].card`, 'card'));
+        continue;
+      }
+      const kind = inferStyleKind(transform);
+      const stylePath = stylePathFor(transform, kind);
+      if (!kind || !stylePath) continue;
+      extra.push(makeStyleBind(transform, stylePath, kind));
+    }
+    file.transformations = [...(file.transformations || []), ...extra];
+  }
+}
+
+function makeStyleBind(transform, stylePath, kind) {
+  return {
+    loc: transform.loc,
+    operation: 'style-bind',
+    tag: transform.tag,
+    file: transform.file,
+    confidence: Math.min(0.99, (transform.confidence || 0.9) - 0.02),
+    decision: transform.decision === 'skip' ? 'skip' : 'auto',
+    reason: `Bind Fivora style contract (${kind}) without rewriting CSS`,
+    field: transform.field,
+    stylePath,
+    styleKind: kind,
+    fingerprint: transform.fingerprint,
+    recipeId: transform.recipeId || null,
+    explain: {
+      detected: `${transform.tag} style-${kind}`,
+      why: 'Fivora visual editor patches --deneb-* CSS variables via FIVORA_PREVIEW_STYLE_PATCH',
+      recipe: transform.recipeId || null,
+      confidence: transform.confidence,
+    },
+  };
+}
+
+module.exports = {
+  appendStyleBindTransforms,
+  inferStyleKind,
+  stylePathFor,
+};