purgetss 7.7.1 → 7.11.1

package/src/core/images/index.js

@@ -17,6 +17,7 @@
 
 import fs from 'fs'
 import path from 'path'
+import sharp from 'sharp'
 import { logger } from '../branding/branding-logger.js'
 import { logger as mainLogger } from '../../shared/logger.js'
 import { confirmWithAlways } from '../../shared/prompt.js'
@@ -35,20 +36,49 @@ export async function runImages(opts) {
     iphoneOnly = false,
     format = null,
     quality = 85,
+    baseWidth = null,
+    opacity = null,     // 0-100 or null
+    padding = null,     // 0-40 (per side, %) or null
+    outputRelpath = null, // basename + subfolder relative to images root, no extension
     dryRun = false,
     yes = false,
-    confirmOverwrites = true
+    confirmOverwrites = true,
+    filesOverrides = []  // [{ filename: 'images/<relpath>', width, height? }, …]
   } = opts
 
   if (!fs.existsSync(source)) {
     throw new Error(`Source not found: ${source}`)
   }
 
+  if (outputRelpath != null && fs.statSync(source).isDirectory()) {
+    throw new Error('--output is incompatible with directory sources (one basename cannot apply to multiple files). Pass a single file as the source, or drop --output.')
+  }
+
   const projectType = detectProjectType(projectRoot)
   const { androidBaseDir, iphoneBaseDir } = resolveOutputDirs(projectRoot, projectType)
 
   const files = collectImageFiles(source)
 
+  // Build a lookup keyed by `images/<subpath>` so per-file `width`/`height`
+  // declared in `config.cjs > images.files` can override the directory scan's
+  // default sizing. CLI `--width` still wins over both.
+  const overrides = buildOverridesMap(filesOverrides)
+  const imagesFolderForKey = projectRoot === process.cwd()
+    ? projectsPurge_TSS_Images_Folder
+    : path.join(projectRoot, 'purgetss', 'images')
+
+  if (baseWidth == null) {
+    const uncoveredSvgs = files.filter(f => {
+      if (path.extname(f).toLowerCase() !== '.svg') return false
+      const key = overrideKeyFor(f, imagesFolderForKey)
+      return !overrides.has(key)
+    })
+    if (uncoveredSvgs.length > 0) {
+      logger.warning('⚠  SVG source detected without --width and no entry in config.cjs > images.files. Output sizes will be derived from each SVG\'s viewBox (treated as a 4× master).')
+      logger.warning('   For SVGs from vector editors with disproportionate viewBoxes, pass --width <n> (e.g. --width 256) or add an entry to images.files to pin the @1x/mdpi width.')
+    }
+  }
+
   console.log()
   mainLogger.info('Generating multi-density image variants...')
   console.log()
@@ -60,6 +90,10 @@ export async function runImages(opts) {
   if (!androidOnly) platforms.push('iPhone (@1x, @2x, @3x)')
   logger.property('Platforms:  ', platforms.join(' + '))
   if (format) logger.property('Format:     ', `convert all to ${format}`)
+  if (baseWidth != null) logger.property('Width:      ', `${baseWidth} px @1x/mdpi`)
+  if (opacity != null) logger.property('Opacity:    ', `${opacity}%`)
+  if (padding != null) logger.property('Padding:    ', `${padding}% per side`)
+  if (outputRelpath != null) logger.property('Output:     ', `images/${outputRelpath}.<ext>`)
   if (dryRun) logger.warning('DRY RUN — no files will be written')
 
   if (files.length === 0) {
@@ -67,9 +101,9 @@ export async function runImages(opts) {
     return { written: [] }
   }
 
-  if (!dryRun && confirmOverwrites) {
+  if (!dryRun && confirmOverwrites && !yes) {
     logger.warning(`⚠  Scaled images will OVERWRITE existing variants under ${androidBaseDir} and ${iphoneBaseDir}.`)
-    logger.warning(`   Commit first if you want a rollback.`)
+    logger.warning('   Commit first if you want a rollback.')
     const choice = await confirmWithAlways('Continue? [y/N/a]', { yes })
     if (choice === 'no') {
       logger.info('Aborted.')
@@ -87,8 +121,8 @@ export async function runImages(opts) {
   }
 
   if (projectType === 'unknown') {
-    logger.warning(`Could not detect project layout. Expected 'app/' (Alloy) or 'Resources/' (Classic).`)
-    logger.warning(`Assets will still be written to the detected default paths — verify the output.`)
+    logger.warning('Could not detect project layout. Expected \'app/\' (Alloy) or \'Resources/\' (Classic).')
+    logger.warning('Assets will still be written to the detected default paths — verify the output.')
   }
 
   // Relative paths preserve the user's subdirectory structure inside purgetss/images/.
@@ -109,17 +143,70 @@ export async function runImages(opts) {
 
   logger.section('Scaling')
   for (const file of files) {
-    const relPath = path.relative(sourceRoot, file)
-    logger.bullet(relPath)
+    // When --output is set, override the computed relPath with the user's
+    // basename + subfolder. Append the source extension so downstream
+    // path.parse / renameWithFormat behave the same as for natural sources.
+    const relPath = outputRelpath != null
+      ? outputRelpath + path.extname(file)
+      : path.relative(sourceRoot, file)
+
+    // Per-file resolution: CLI --width wins; if absent, fall back to the
+    // entry in `images.files` (if any); else null (gen-scales reads viewBox).
+    const override = overrides.get(overrideKeyFor(file, imagesFolderForKey))
+    const effectiveBaseWidth = baseWidth ?? override?.width ?? null
+    const effectiveBaseHeight = baseWidth != null ? null : (override?.height ?? null)
+
+    // SVGs listed in `images.files` are almost always referenced from views/
+    // controllers as `image="/.../foo.svg"`, and Titanium's runtime only falls
+    // back from a `.svg` reference to `.png` (verified empirically — not to
+    // .webp, .jpeg, etc.). Forcing PNG here prevents the standalone command
+    // from quietly emitting a format Titanium can't load via that fallback.
+    // Raster files in `files` and SVGs NOT in `files` still honor `format`.
+    const ext = path.extname(file).toLowerCase()
+    const isSvg = ext === '.svg'
+    const isSvgInFiles = override != null && isSvg
+    const effectiveFormat = isSvgInFiles ? null : format
+
+    // Build an informative bullet so the user can see which decisions applied
+    // per file: source of width, where it came from, and the actual output
+    // format (especially when PNG is forced for SVGs in `files`).
+    const widthSource = baseWidth != null
+      ? `${baseWidth}dp (CLI --width)`
+      : override
+        ? `${override.width}dp (files)`
+        : isSvg ? 'viewBox' : 'source 4×'
+    const outFormat = effectiveFormat ?? (isSvg ? 'png' : ext.slice(1))
+    const formatTag = isSvgInFiles && format && format !== 'png'
+      ? `${outFormat} (forced; ignores format: ${format})`
+      : outFormat
+    logger.bullet(`${relPath} → ${widthSource} · ${formatTag}`)
 
     if (dryRun) continue
 
+    // Quality warning: if the user pinned a width (via CLI or `files`), the
+    // source must carry at least `width × 4` pixels — that's what xxxhdpi/@4x
+    // needs. Anything smaller forces Sharp to upscale, producing blurry output.
+    // SVG sources are vector and exempt from this check.
+    if (effectiveBaseWidth != null && !isSvg) {
+      const meta = await sharp(file).metadata()
+      const requiredXxxhdpi = effectiveBaseWidth * 4
+      if (Number.isFinite(meta.width) && meta.width < requiredXxxhdpi) {
+        logger.warning(
+          `⚠  ${relPath}: source is ${meta.width}px wide but xxxhdpi needs ${requiredXxxhdpi}px (4× of declared ${effectiveBaseWidth}dp @1x). Output will be upscaled and may look blurry — provide a source ≥ ${requiredXxxhdpi}px.`
+        )
+      }
+    }
+
     if (!iphoneOnly) {
-      const androidFiles = await genAndroidScales(file, relPath, androidBaseDir, { format, quality })
+      const androidFiles = await genAndroidScales(file, relPath, androidBaseDir, {
+        format: effectiveFormat, quality, baseWidth: effectiveBaseWidth, baseHeight: effectiveBaseHeight, opacity, padding
+      })
       written.push(...androidFiles)
     }
     if (!androidOnly) {
-      const iphoneFiles = await genIphoneScales(file, relPath, iphoneBaseDir, { format, quality })
+      const iphoneFiles = await genIphoneScales(file, relPath, iphoneBaseDir, {
+        format: effectiveFormat, quality, baseWidth: effectiveBaseWidth, baseHeight: effectiveBaseHeight, opacity, padding
+      })
       written.push(...iphoneFiles)
     }
   }
@@ -148,6 +235,31 @@ function resolveOutputDirs(projectRoot, projectType) {
   }
 }
 
+// Normalize a config `images.files` entry list into a Map keyed by filename.
+// Invalid entries (missing filename, non-numeric width) are silently skipped
+// so a typo in config doesn't crash the whole pipeline.
+function buildOverridesMap(entries) {
+  const map = new Map()
+  if (!Array.isArray(entries)) return map
+  for (const entry of entries) {
+    if (!entry || typeof entry.filename !== 'string') continue
+    if (typeof entry.width !== 'number' || !Number.isFinite(entry.width)) continue
+    const key = entry.filename.replace(/^\/+/, '')
+    map.set(key, {
+      width: entry.width,
+      height: typeof entry.height === 'number' && Number.isFinite(entry.height) ? entry.height : null
+    })
+  }
+  return map
+}
+
+// Match the key shape stored in `config.cjs > images.files`:
+// `images/<subpath>/<name>.<ext>` relative to `purgetss/images/`.
+function overrideKeyFor(file, imagesFolder) {
+  const rel = path.relative(imagesFolder, file).split(path.sep).join('/')
+  return rel.startsWith('..') ? null : `images/${rel}`
+}
+
 function collectImageFiles(source) {
   const stat = fs.statSync(source)
   if (stat.isFile()) {

package/src/core/purger/icon-purger.js

@@ -49,7 +49,7 @@ export function purgeFontAwesome(uniqueClasses, cleanUniqueClasses, debug = fals
     if (fs.existsSync(projectsFA_TSS_File)) {
       sourceFolder = projectsFA_TSS_File
       purgedClasses = '\n// Pro/Beta Font Awesome\n'
-      purgingMessage = `Purging ${chalk.yellow('Pro/Beta Font Awesome')} styles...')`
+      purgingMessage = `Purging ${chalk.yellow('Pro/Beta Font Awesome')} styles...`
     } else {
       sourceFolder = srcFontAwesomeTSSFile
       purgedClasses = '\n// Default Font Awesome\n'
@@ -128,9 +128,13 @@ export function purgeFontIcons(sourceFolder, uniqueClasses, message, cleanUnique
 
   let purgedClasses = ''
   const sourceTSS = fs.readFileSync(sourceFolder, 'utf8')
+  const hasMatches = cleanUniqueClasses.some(element => sourceTSS.includes(`'.${element}'`))
 
-  if (cleanUniqueClasses.some(element => sourceTSS.includes(`'.${element}'`))) {
-    logger.info(message)
+  if (hasMatches) {
+    // In debug mode the label is emitted by localFinish inline with the timing.
+    // In non-debug mode this is the progress indicator (only shown when there's
+    // actual work for this font, matching pre-existing behavior).
+    if (!debug) logger.info(message)
     const sourceTSSFile = sourceTSS.split(/\r?\n/)
     uniqueClasses.forEach(className => {
       const cleanClassName = cleanClassNameFn(className)

package/src/core/purger/tailwind-purger.js

@@ -14,6 +14,7 @@ import _ from 'lodash'
 import chalk from 'chalk'
 import * as helpers from '../../shared/helpers.js'
 import { logger } from '../../shared/logger.js'
+import { deriveAlphaKey } from '../../shared/semantic-helpers.js'
 import {
   // eslint-disable-next-line camelcase
   projectsTailwind_TSS,
@@ -47,7 +48,9 @@ function cleanClassNameFn(className) {
 export function purgeTailwind(uniqueClasses, debug = false) {
   if (debug) localStart()
 
-  logger.info('Purging', chalk.yellow('utilities.tss'), 'styles...')
+  // In debug mode, the section label is emitted by localFinish together with
+  // the timing (inline). In non-debug mode this line is the progress indicator.
+  if (!debug) logger.info('Purging', chalk.yellow('utilities.tss'), 'styles...')
 
   let purgedClasses = ''
   let tailwindClasses = fs.readFileSync(projectsTailwind_TSS, 'utf8').split(/\r?\n/)
@@ -191,10 +194,20 @@ export function purgeTailwind(uniqueClasses, debug = false) {
       const opacityIndex = _.findIndex(tailwindClasses, line => line.startsWith(`'.${opacityValue.className}'`))
 
       const classProperties = tailwindClasses[opacityIndex]
-      if (opacityIndex > -1 && classProperties.includes('#')) {
-        // ! TODO: Check if color value is a hex value!! (if not, they are using rbg, rgba or semantic colors)
-        // ! In other words, we need to validate the color value, before we can alter its opacity.
-        const defaultHexValue = (classProperties.includes('from')) ? classProperties.match(/#[0-9a-f]{6}/g)[1] : classProperties.match(/#[0-9a-f]{6}/i)[0]
+      if (opacityIndex > -1 && classProperties && !classProperties.includes('#')) {
+        const derivedLine = tryDeriveSemanticOpacityLine(classProperties, opacityValue)
+        if (derivedLine) {
+          purgedClasses += switchPlatform(helpers.checkPlatformAndDevice(derivedLine, opacityValue.classNameWithTransparency))
+        } else {
+          console.warn('')
+          console.warn(chalk.yellow(`   Skipping ".${opacityValue.className}/${opacityValue.decimalValue}" — semantic color, no hex to blend.`))
+          console.warn(chalk.yellow(`   Use a PurgeTSS built-in color, bg-(#AARRGGBB), or "purgetss semantic --single ... --alpha ${opacityValue.decimalValue}".`))
+          console.warn('')
+        }
+      }
+      if (opacityIndex > -1 && classProperties && classProperties.includes('#')) {
+        const hexMatches = classProperties.match(/#[0-9a-f]{6}/gi)
+        const defaultHexValue = (classProperties.includes('from')) ? hexMatches[1] : hexMatches[0]
         let classWithoutDecimalOpacity = `${classProperties.replace(new RegExp(defaultHexValue.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), `#${opacityValue.transparency}${defaultHexValue.substring(1)}`)}`
         // Special case: #000000
         if (classProperties.includes('from') && defaultHexValue === '#000000') classWithoutDecimalOpacity = classWithoutDecimalOpacity.replace('00000000', '000000')
@@ -216,6 +229,31 @@ export function purgeTailwind(uniqueClasses, debug = false) {
   return purgedClasses
 }
 
+// Auto-derive a semantic key with applied alpha and emit a TSS line for the
+// `class/N` form. Returns the rewritten line (with selector renamed to include
+// `/N` and the semantic value swapped for the derived key), or `null` when no
+// candidate matches an entry in semantic.colors.json. Conflict errors from
+// `deriveAlphaKey` propagate naturally.
+function tryDeriveSemanticOpacityLine(classProperties, opacityValue) {
+  const bodyMatch = classProperties.match(/\{([^}]*)\}/)
+  if (!bodyMatch) return null
+  const candidates = (bodyMatch[1].match(/'([^']+)'/g) || [])
+    .map(m => m.slice(1, -1))
+    .filter(v => !v.startsWith('#'))
+  for (const candidate of candidates) {
+    const derivedKey = deriveAlphaKey(candidate, opacityValue.decimalValue)
+    if (derivedKey) {
+      let line = classProperties.replace(new RegExp(`'${candidate}'`, 'g'), `'${derivedKey}'`)
+      line = line.replace(
+        `'.${opacityValue.className}'`,
+        `'.${opacityValue.className}/${opacityValue.decimalValue}'`
+      )
+      return line
+    }
+  }
+  return null
+}
+
 /**
  * Switch platform specific styles - COPIED exactly from original switchPlatform() function
  * NO CHANGES to logic, preserving 100% of original functionality

package/src/core/svg/cache.js

@@ -0,0 +1,96 @@
+/**
+ * PurgeTSS - SVG pipeline cache
+ *
+ * Tracks the last successful generation of each SVG so subsequent runs can
+ * skip work when nothing changed. Cached file: `purgetss/.cache/svg-images.json`.
+ *
+ * An entry is invalidated (regen) when any of these change:
+ *   - The SVG file content (sha1 hash).
+ *   - The resolved widthDp / heightDp.
+ *   - The list of target PNG paths.
+ *   - Any of the target PNGs is missing on disk.
+ *
+ * Stale entries for SVGs no longer referenced are left untouched here — the
+ * planned `purgetss clean` command is responsible for purging orphans.
+ *
+ * @fileoverview Idempotency cache for the SVG pipeline
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import crypto from 'crypto'
+import { projectsPurgeTSSFolder } from '../../shared/constants.js'
+
+const CACHE_DIR = path.join(projectsPurgeTSSFolder, '.cache')
+const CACHE_FILE = path.join(CACHE_DIR, 'svg-images.json')
+
+/**
+ * Load the on-disk cache as a plain object. Returns `{}` if the file is
+ * missing or unreadable — corrupted caches simply force a regen rather than
+ * halting the build.
+ */
+export function loadCache() {
+  try {
+    if (!fs.existsSync(CACHE_FILE)) return {}
+    const raw = fs.readFileSync(CACHE_FILE, 'utf8')
+    const parsed = JSON.parse(raw)
+    return (parsed && typeof parsed === 'object') ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Persist the cache to disk, creating `.cache/` if needed.
+ */
+export function saveCache(cache) {
+  fs.mkdirSync(CACHE_DIR, { recursive: true })
+  fs.writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2) + '\n', 'utf8')
+}
+
+/**
+ * Compute the sha1 hash of an SVG file. Reads the bytes verbatim so
+ * whitespace-only edits also bust the cache (desired — they may change rendering).
+ */
+export function hashFile(absPath) {
+  const buf = fs.readFileSync(absPath)
+  return crypto.createHash('sha1').update(buf).digest('hex')
+}
+
+/**
+ * Decide whether the cached entry is still valid for the given resolved inputs.
+ *
+ * @param {Object} cached - Previous cache entry (or undefined).
+ * @param {string} svgHash - sha1 of the current SVG.
+ * @param {number} widthDp - Currently resolved widthDp.
+ * @param {number} heightDp - Currently resolved heightDp.
+ * @param {string[]} targets - Absolute paths the pipeline would emit this run.
+ * @returns {boolean} True if every target PNG is present and inputs match.
+ */
+export function isCacheHit(cached, svgHash, widthDp, heightDp, targets) {
+  if (!cached) return false
+  if (cached.svgHash !== svgHash) return false
+  if (cached.widthDp !== widthDp) return false
+  if (cached.heightDp !== heightDp) return false
+  if (!Array.isArray(cached.targets) || cached.targets.length !== targets.length) return false
+
+  const cachedPaths = new Set(cached.targets.map(t => (typeof t === 'string' ? t : t.path)))
+  for (const t of targets) {
+    if (!cachedPaths.has(t)) return false
+    if (!fs.existsSync(t)) return false
+  }
+  return true
+}
+
+/**
+ * Build the cache entry shape we persist after a successful generation.
+ */
+export function makeCacheEntry(svgHash, widthDp, heightDp, targets) {
+  return {
+    svgHash,
+    widthDp,
+    heightDp,
+    targets: [...targets]
+  }
+}

package/src/core/svg/derive-dimensions.js

@@ -0,0 +1,120 @@
+/**
+ * PurgeTSS - SVG dimension deriver
+ *
+ * Reduces all the references to a single SVG into one final `{ widthDp, heightDp }`
+ * pair that the image generator can consume as the `1×` baseline. Strategy:
+ *
+ *   1. For each reference, resolve the cascade against the purged app.tss
+ *      class→props map.
+ *   2. Collect every numeric width across references; the SVG's width is the
+ *      max (a single view rendered at 800dp can't share PNGs with a view at
+ *      128dp without visible blur).
+ *   3. Resolve height: explicit numeric width wins; otherwise fall back to a
+ *      proportional value derived from the SVG's viewBox aspect ratio.
+ *
+ * Edge cases handled:
+ *   - Every reference resolves to a non-numeric width (`Ti.UI.SIZE`, percentage,
+ *     unknown class, etc.) → SVG is skipped with a warning.
+ *   - SVG file missing in `purgetss/images/` → skipped with a warning.
+ *   - SVG has an invalid/missing viewBox → skipped with an error.
+ *
+ * @fileoverview Per-SVG dimension reducer that feeds the image generator
+ * @author César Estrada
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { resolveDimensions } from './resolve-classes.js'
+import { readSvgSafely } from '../../shared/svg-utils.js'
+
+// Hard cap on the largest target PNG we are willing to emit, applied at the
+// `xxxhdpi` / `@3x` step downstream. Keeps Sharp from producing absurdly large
+// PNGs when the user accidentally pins a 4K width to a class.
+export const MAX_DIMENSION_PX = 4096
+
+/**
+ * Reduce raw SVG references into per-SVG resolved dimensions.
+ *
+ * @param {Object} args
+ * @param {Map<string, Array<{ classes: string[] }>>} args.refsBySvg - Map keyed by SVG relpath
+ *   (relative to imagesFolder, normalized to forward slashes), values are the list of
+ *   references seen for that SVG.
+ * @param {Map} args.tssMap - Output of parseTssMap().
+ * @param {string} args.imagesFolder - Absolute path to `purgetss/images/`.
+ * @param {Object} args.logger - Logger with `.warning(msg)` and `.info(msg)`.
+ * @returns {Promise<Map<string, { widthDp: number, heightDp: number }>>}
+ *   Resolved entries only; skipped SVGs are omitted (warnings logged inline).
+ */
+export async function deriveDimensions({ refsBySvg, tssMap, imagesFolder, logger }) {
+  const resolved = new Map()
+
+  for (const [relPath, refs] of refsBySvg) {
+    const absPath = path.join(imagesFolder, relPath)
+    if (!fs.existsSync(absPath)) {
+      logger.warning(`⚠  SVG not found: purgetss/images/${relPath} — skipping`)
+      continue
+    }
+
+    const numericWidths = []
+    const numericHeights = []
+    for (const ref of refs) {
+      const { width, height } = resolveDimensions(ref.classes, tssMap)
+      if (typeof width === 'number' && Number.isFinite(width) && width > 0) {
+        numericWidths.push(width)
+      }
+      if (typeof height === 'number' && Number.isFinite(height) && height > 0) {
+        numericHeights.push(height)
+      }
+    }
+
+    if (numericWidths.length === 0 && numericHeights.length === 0) {
+      logger.warning(
+        `⚠  ${relPath}: no class resolved width or height to a number — skipping. ` +
+        'Add a w-* or h-* utility on the view, or pin the size manually in purgetss/config.cjs > images.files.'
+      )
+      continue
+    }
+
+    try {
+      await readViewBox(absPath)
+    } catch (err) {
+      logger.warning(`⚠  ${relPath}: ${err.message} — skipping`)
+      continue
+    }
+
+    // Symmetric materialization: only the dimensions the developer pinned
+    // explicitly land in config.cjs. The other side is derived from the SVG
+    // aspect by gen-scales on every run, so it stays in sync with viewBox
+    // edits and class changes without stale "stuck" values getting cemented
+    // into config the way auto-derived heights used to.
+    const widthDp = numericWidths.length > 0 ? Math.max(...numericWidths) : null
+    const heightDp = numericHeights.length > 0 ? Math.max(...numericHeights) : null
+
+    resolved.set(relPath, { widthDp, heightDp })
+  }
+
+  return resolved
+}
+
+async function readViewBox(absPath) {
+  // Plan: error when the SVG declares neither viewBox nor width+height
+  // attributes. Sharp can infer a bounding box from the rendered content,
+  // but treating that as "valid" hides authoring mistakes (e.g. an export
+  // that lost its viewBox), so we enforce the explicit declaration first.
+  const head = fs.readFileSync(absPath, 'utf8').slice(0, 4096)
+  const svgTag = head.match(/<svg\b[^>]*>/i)?.[0] ?? ''
+  const hasViewBox = /\bviewBox\s*=\s*['"][^'"]+['"]/.test(svgTag)
+  const hasWidth = /\bwidth\s*=\s*['"][^'"]+['"]/.test(svgTag)
+  const hasHeight = /\bheight\s*=\s*['"][^'"]+['"]/.test(svgTag)
+  if (!hasViewBox && !(hasWidth && hasHeight)) {
+    throw new Error('SVG has no viewBox or explicit width/height attribute')
+  }
+
+  const { meta } = await readSvgSafely(absPath, {})
+  const vbW = meta.width
+  const vbH = meta.height
+  if (!Number.isFinite(vbW) || !Number.isFinite(vbH) || vbW <= 0 || vbH <= 0) {
+    throw new Error('SVG has no usable viewBox / width / height')
+  }
+  return { vbW, vbH }
+}