@hyperframes/parsers 0.7.24 → 0.7.26

package/dist/index.d.ts

@@ -46,6 +46,66 @@ interface CompositionMetadata {
 declare function extractCompositionMetadata(html: string): CompositionMetadata;
 declare function validateCompositionHtml(html: string): ValidationResult;
 
+/**
+ * Shared "is this `outputResolution` preset compatible with the composition?"
+ * check.
+ *
+ * The `--resolution` render flag (a `CanvasResolution` preset) is chosen
+ * independently of the composition it renders, so a portrait composition
+ * (1080×1920) rendered with `--resolution landscape` (1920×1080) is a common
+ * mistake — especially from AI agents that pick a preset by habit rather than
+ * by inspecting the composition. Historically this surfaced as a cryptic
+ * `Error` thrown deep inside the render compiler (`resolveDeviceScaleFactor`
+ * in `@hyperframes/producer`), after the browser and ffmpeg had already spun
+ * up, with a message that named the mismatch but not the fix.
+ *
+ * This module gives every consumer (the render pre-flight in the CLI, the
+ * producer's `resolveDeviceScaleFactor`, and any future lint rule) a single,
+ * dependency-free definition of "is this preset usable for this composition"
+ * — including a suggested preset when there's an unambiguously-correct swap —
+ * so the same check can run *before* a render is attempted (loud, actionable,
+ * cheap) and again as defense-in-depth inside the pipeline.
+ *
+ * It lives in `@hyperframes/parsers` (rather than `@hyperframes/core`) because
+ * both `core`/`producer` and `lint` may need it, and `lint` cannot depend on
+ * `core`. The geometry it needs (`CANVAS_DIMENSIONS`) already lives here.
+ */
+
+type OutputResolutionIssueKind = "hdr-incompatible" | "alpha-incompatible" | "aspect-mismatch" | "downsampling" | "non-integer-scale";
+interface OutputResolutionCompatibility {
+    ok: boolean;
+    /** Present when `ok` is false. */
+    kind?: OutputResolutionIssueKind;
+    /** Human-readable, actionable message suitable for direct display. */
+    message?: string;
+    /**
+     * A preset whose orientation/aspect ratio matches the composition, when one
+     * exists and is an unambiguous swap for the user's intent. Present only for
+     * `aspect-mismatch`. Consumers may surface this as a suggestion ("did you
+     * mean `--resolution portrait`?"); it is intentionally *not* auto-applied —
+     * silently swapping a user-supplied flag changes their stated intent.
+     */
+    suggestedResolution?: CanvasResolution;
+}
+/**
+ * Check whether rendering a composition of the given dimensions with the given
+ * `outputResolution` preset (and alpha/HDR modes) is supported.
+ *
+ * Pure and dependency-free — the single source of truth for the constraints
+ * `resolveDeviceScaleFactor` enforces, so the CLI can run the exact same check
+ * as a pre-flight before any browser/ffmpeg work.
+ *
+ * @param outputResolution The chosen preset, or `undefined` when the render
+ *   uses the composition's native dimensions (always compatible).
+ */
+declare function checkOutputResolutionCompatibility(input: {
+    compositionWidth: number;
+    compositionHeight: number;
+    outputResolution: CanvasResolution | undefined;
+    alphaRequested?: boolean;
+    hdrRequested?: boolean;
+}): OutputResolutionCompatibility;
+
 /**
  * Rewrite `script` so top-level helper calls / loops that build the timeline
  * become explicit literal tweens. Returns the original script unchanged when
@@ -55,4 +115,4 @@ declare function unrollComputedTimeline(script: string): string;
 
 declare function queryByAttr(root: ParentNode, attr: string, value: string, tag?: string): Element | null;
 
-export { CanvasResolution, CompositionHtmlParseError, type CompositionMetadata, CompositionVariable, Keyframe, type ParsedHtml, StageZoomKeyframe, TimelineElement, ValidationResult, addElementToHtml, extractCompositionMetadata, parseHtml, queryByAttr, removeElementFromHtml, unrollComputedTimeline, updateElementInHtml, validateCompositionHtml };
+export { CanvasResolution, CompositionHtmlParseError, type CompositionMetadata, CompositionVariable, Keyframe, type OutputResolutionCompatibility, type OutputResolutionIssueKind, type ParsedHtml, StageZoomKeyframe, TimelineElement, ValidationResult, addElementToHtml, checkOutputResolutionCompatibility, extractCompositionMetadata, parseHtml, queryByAttr, removeElementFromHtml, unrollComputedTimeline, updateElementInHtml, validateCompositionHtml };

package/dist/index.js

@@ -850,6 +850,49 @@ var SCOPE_NODE_TYPES = /* @__PURE__ */ new Set([
   "FunctionExpression",
   "ArrowFunctionExpression"
 ]);
+var CONST_NODES = /* @__PURE__ */ Symbol("hf.constNodes");
+function constNodesOf(scope) {
+  return scope[CONST_NODES];
+}
+var MATH_FNS = /* @__PURE__ */ new Set(["min", "max", "round", "floor", "ceil", "abs", "sqrt", "sign", "trunc"]);
+var MATH_CONSTS = { PI: Math.PI, E: Math.E, SQRT2: Math.SQRT2 };
+function resolveMemberNode(node, scope) {
+  if (node.object?.type === "Identifier" && node.object.name === "Math") {
+    const key = node.property?.name;
+    return typeof key === "string" ? MATH_CONSTS[key] : void 0;
+  }
+  const objNode = resolveConstNode(node.object, scope);
+  if (!objNode) return void 0;
+  let valueNode;
+  if (node.computed) {
+    const idx = resolveNode(node.property, scope);
+    if (objNode.type === "ArrayExpression" && typeof idx === "number") {
+      valueNode = objNode.elements?.[idx];
+    } else if (objNode.type === "ObjectExpression" && (typeof idx === "string" || typeof idx === "number")) {
+      valueNode = findPropertyNode(objNode, String(idx));
+    }
+  } else if (objNode.type === "ObjectExpression") {
+    valueNode = findPropertyNode(objNode, node.property?.name ?? node.property?.value);
+  }
+  return valueNode ? resolveNode(valueNode, scope) : void 0;
+}
+function resolveConstMember(objNode, node, scope) {
+  if (!node.computed) {
+    return objNode.type === "ObjectExpression" ? findPropertyNode(objNode, node.property?.name ?? node.property?.value) : void 0;
+  }
+  const idx = resolveNode(node.property, scope);
+  if (objNode.type === "ArrayExpression" && typeof idx === "number") return objNode.elements?.[idx];
+  if (objNode.type === "ObjectExpression") return findPropertyNode(objNode, String(idx));
+  return void 0;
+}
+function resolveConstNode(node, scope) {
+  if (!node) return void 0;
+  if (node.type === "ArrayExpression" || node.type === "ObjectExpression") return node;
+  if (node.type === "Identifier") return constNodesOf(scope)?.get(node.name);
+  if (node.type !== "MemberExpression") return void 0;
+  const objNode = resolveConstNode(node.object, scope);
+  return objNode ? resolveConstMember(objNode, node, scope) : void 0;
+}
 function resolveNode(node, scope) {
   if (!node) return void 0;
   if (node.type === "NumericLiteral" || node.type === "Literal" && typeof node.value === "number")
@@ -886,6 +929,15 @@ function resolveNode(node, scope) {
   if (node.type === "TemplateLiteral" && node.expressions?.length === 0) {
     return node.quasis?.[0]?.value?.cooked ?? void 0;
   }
+  if (node.type === "MemberExpression") {
+    return resolveMemberNode(node, scope);
+  }
+  if (node.type === "CallExpression" && node.callee?.type === "MemberExpression" && node.callee.object?.type === "Identifier" && node.callee.object.name === "Math" && MATH_FNS.has(node.callee.property?.name)) {
+    const args = (node.arguments ?? []).map((a) => resolveNode(a, scope));
+    if (args.every((a) => typeof a === "number")) {
+      return Math[node.callee.property.name](...args);
+    }
+  }
   return void 0;
 }
 function extractLiteralValue(node, scope) {
@@ -943,14 +995,19 @@ function resolveCollectionSelector(node, ancestors, scope, bindings) {
 }
 function collectScopeBindings(ast) {
   const bindings = /* @__PURE__ */ new Map();
+  const constNodes = /* @__PURE__ */ new Map();
+  Object.defineProperty(bindings, CONST_NODES, { value: constNodes, enumerable: false });
   acornWalk.simple(ast, {
     VariableDeclarator(node) {
       const name = node.id?.name;
       const init = node.init;
-      if (name && init) {
-        const val = resolveNode(init, bindings);
-        if (val !== void 0) bindings.set(name, val);
+      if (!name || !init) return;
+      if (init.type === "ArrayExpression" || init.type === "ObjectExpression") {
+        constNodes.set(name, init);
+        return;
       }
+      const val = resolveNode(init, bindings);
+      if (val !== void 0) bindings.set(name, val);
     }
   });
   return bindings;
@@ -992,6 +1049,25 @@ function collectTargetBindings(ast, scope) {
       }
     }
   });
+  const COLLECTION_ALIAS_METHODS = /* @__PURE__ */ new Set(["slice", "filter", "concat", "reverse"]);
+  acornWalk.ancestor(ast, {
+    // fallow-ignore-next-line complexity
+    VariableDeclarator(node, _, ancestors) {
+      const name = node.id?.name;
+      const init = node.init;
+      if (!name || !init) return;
+      let sourceVar;
+      if (init.type === "MemberExpression" && init.object?.type === "Identifier") {
+        sourceVar = init.object.name;
+      } else if (init.type === "CallExpression" && init.callee?.type === "MemberExpression" && init.callee.object?.type === "Identifier" && init.callee.property?.type === "Identifier" && COLLECTION_ALIAS_METHODS.has(init.callee.property.name)) {
+        sourceVar = init.callee.object.name;
+      }
+      if (!sourceVar) return;
+      const selector = lookupBindingFromAncestors(sourceVar, ancestors, bindings);
+      if (selector)
+        addBinding(bindings, enclosingScopeNodeFromAncestors(ancestors), name, selector);
+    }
+  });
   return bindings;
 }
 function resolveTargetSelector(node, ancestors, scope, bindings) {
@@ -1014,6 +1090,32 @@ function resolveTargetSelector(node, ancestors, scope, bindings) {
   }
   return null;
 }
+function describeProxyTarget(targetNode, varsNode, scope) {
+  const objNode = targetNode?.type === "ObjectExpression" ? targetNode : targetNode?.type === "Identifier" ? resolveConstNode(targetNode, scope) : void 0;
+  if (objNode?.type !== "ObjectExpression") return null;
+  const onUpdate = findPropertyNode(varsNode, "onUpdate");
+  const driven = onUpdate ? drivenDomChannel(onUpdate) : void 0;
+  if (driven) return `proxy \u2192 ${driven}`;
+  return "dwell/hold";
+}
+function isStyleAssignmentTarget(left) {
+  return left?.type === "MemberExpression" && left.object?.type === "MemberExpression" && left.object.property?.name === "style" && !!left.property?.name;
+}
+function drivenDomChannel(fnNode) {
+  let found;
+  acornWalk.simple(fnNode, {
+    CallExpression(node) {
+      if (node.callee?.type === "MemberExpression" && node.callee.property?.name === "setAttribute" && typeof node.arguments?.[0]?.value === "string") {
+        found ??= node.arguments[0].value;
+      }
+    },
+    AssignmentExpression(node) {
+      const left = node.left;
+      if (isStyleAssignmentTarget(left)) found ??= `style.${left.property.name}`;
+    }
+  });
+  return found;
+}
 function isObjectProperty(prop) {
   return prop?.type === "ObjectProperty" || prop?.type === "Property";
 }
@@ -1482,8 +1584,13 @@ function tweenCallToAnimation(call, scope, source) {
   if (duration === void 0 && keyframesData) {
     duration = computeKeyframesTotalDuration(call.varsArg, scope, source);
   }
+  let selector = call.selector;
+  if (selector === "__unresolved__") {
+    const proxyLabel = describeProxyTarget(call.node.arguments?.[0], call.varsArg, scope);
+    if (proxyLabel) selector = proxyLabel;
+  }
   const anim = {
-    targetSelector: call.selector,
+    targetSelector: selector,
     method: call.method,
     position,
     properties,
@@ -1506,11 +1613,52 @@ function tweenCallToAnimation(call, scope, source) {
   if (keyframesData) anim.keyframes = keyframesData;
   if (motionPathResult) anim.arcPath = motionPathResult.arcPath;
   if (hasUnresolvedKeyframes) anim.hasUnresolvedKeyframes = true;
-  if (call.selector === "__unresolved__") anim.hasUnresolvedSelector = true;
+  if (selector === "__unresolved__") anim.hasUnresolvedSelector = true;
   const provenance = readProvenance(call.node);
   if (provenance) anim.provenance = provenance;
   return anim;
 }
+function staggerAmount(raw) {
+  if (typeof raw === "number") return raw;
+  if (typeof raw !== "string") return void 0;
+  const src = raw.startsWith("__raw:") ? raw.slice(6) : raw;
+  const m = /(?:each\s*:\s*)?(-?\d+(?:\.\d+)?)/.exec(src);
+  if (!m) return void 0;
+  const n = Number.parseFloat(m[1]);
+  return Number.isFinite(n) ? n : void 0;
+}
+function restValue(prop) {
+  return prop === "opacity" || prop.startsWith("scale") ? 1 : 0;
+}
+function staggeredKeyframes(anim, each) {
+  const vars = { ...anim.properties };
+  let from;
+  let to;
+  if (anim.method === "fromTo") {
+    from = { ...anim.fromProperties ?? {} };
+    to = vars;
+  } else if (anim.method === "from") {
+    from = vars;
+    to = {};
+    for (const k of Object.keys(vars)) to[k] = restValue(k);
+  } else {
+    from = { ...anim.fromProperties ?? {} };
+    for (const k of Object.keys(vars)) if (from[k] === void 0) from[k] = restValue(k);
+    to = vars;
+  }
+  return [
+    { percentage: 0, properties: { ...from, stagger: each } },
+    { percentage: 100, properties: { ...to, stagger: each } }
+  ];
+}
+function annotateStaggeredCollections(anims) {
+  for (const anim of anims) {
+    if (anim.keyframes || anim.arcPath) continue;
+    const each = staggerAmount(anim.extras?.stagger);
+    if (each === void 0) continue;
+    anim.keyframes = { format: "percentage", keyframes: staggeredKeyframes(anim, each) };
+  }
+}
 var GSAP_DEFAULT_DURATION = 0.5;
 function resolvePositionString(pos, cursor, prevStart) {
   const trimmed = pos.trim();
@@ -1536,6 +1684,55 @@ function resolvePositionString(pos, cursor, prevStart) {
   const n = Number.parseFloat(trimmed);
   return Number.isFinite(n) ? n : null;
 }
+function collectGsapSetStates(ast, scope, bindings, source) {
+  const states = /* @__PURE__ */ new Map();
+  acornWalk.ancestor(ast, {
+    // fallow-ignore-next-line complexity
+    CallExpression(node, _, ancestors) {
+      const callee = node.callee;
+      if (callee?.type !== "MemberExpression" || callee.object?.name !== "gsap" || callee.property?.name !== "set")
+        return;
+      const selector = resolveTargetSelector(node.arguments?.[0], ancestors, scope, bindings);
+      if (!selector) return;
+      const rec = objectExpressionToRecord(node.arguments?.[1], scope, source);
+      const props = states.get(selector) ?? {};
+      for (const [k, v] of Object.entries(rec)) {
+        if (typeof v === "number" || typeof v === "string") props[k] = v;
+      }
+      states.set(selector, props);
+    }
+  });
+  return states;
+}
+function mergeProps(target, props) {
+  for (const [k, v] of Object.entries(props)) target[k] = v;
+  return target;
+}
+function seedFromPreState(anim, cur) {
+  const from = { ...anim.fromProperties ?? {} };
+  let seeded = false;
+  for (const prop of Object.keys(anim.properties)) {
+    if (from[prop] === void 0 && cur[prop] !== void 0) {
+      from[prop] = cur[prop];
+      seeded = true;
+    }
+  }
+  if (seeded) anim.fromProperties = from;
+}
+function seedSetStates(anims, initial) {
+  const state = /* @__PURE__ */ new Map();
+  for (const [sel, props] of initial) state.set(sel, { ...props });
+  for (const anim of anims) {
+    const sel = anim.targetSelector;
+    if (anim.method === "set") {
+      state.set(sel, mergeProps(state.get(sel) ?? {}, anim.properties));
+      continue;
+    }
+    const cur = state.get(sel);
+    if (anim.method === "to" && cur) seedFromPreState(anim, cur);
+    state.set(sel, mergeProps(state.get(sel) ?? {}, anim.properties));
+  }
+}
 function applyTimelineDefaults(anims, defaults) {
   if (!defaults) return;
   for (const anim of anims) {
@@ -1548,31 +1745,89 @@ function applyTimelineDefaults(anims, defaults) {
     }
   }
 }
-function resolveTimelinePositions(anims) {
+function resolveLabelPosition(pos, labels, cursor) {
+  const m = /^([A-Za-z_$][\w$]*)\s*(?:([+-])=\s*([\d.]+))?$/.exec(pos.trim());
+  if (!m) return null;
+  const name = m[1];
+  let base = labels.get(name);
+  if (base === void 0) {
+    base = cursor;
+    labels.set(name, base);
+  }
+  if (m[2] && m[3]) {
+    const n = Number.parseFloat(m[3]);
+    if (Number.isFinite(n)) return m[2] === "+" ? base + n : base - n;
+  }
+  return base;
+}
+function resolveAnimStart(anim, cursor, prevStart, labels) {
+  if (anim.implicitPosition) return cursor;
+  if (typeof anim.position === "number") return anim.position;
+  if (typeof anim.position === "string") {
+    return resolveLabelPosition(anim.position, labels, cursor) ?? resolvePositionString(anim.position, cursor, prevStart);
+  }
+  return cursor;
+}
+function resolveTimelinePositions(anims, labelDefs = []) {
   let cursor = 0;
   let prevStart = 0;
-  for (const anim of anims) {
+  const labels = /* @__PURE__ */ new Map();
+  let labelIdx = 0;
+  const sortedLabels = [...labelDefs].sort((a, b) => a.order - b.order);
+  const defineLabel = (def) => {
+    let value;
+    if (typeof def.position === "number") value = def.position;
+    else if (typeof def.position === "string") {
+      value = resolveLabelPosition(def.position, labels, cursor) ?? cursor;
+    } else value = cursor;
+    labels.set(def.name, Math.max(0, value));
+  };
+  anims.forEach((anim, i) => {
+    while (labelIdx < sortedLabels.length && sortedLabels[labelIdx].order <= i) {
+      defineLabel(sortedLabels[labelIdx]);
+      labelIdx++;
+    }
     if (anim.method === "set" && anim.global) {
       anim.resolvedStart = 0;
-      continue;
+      return;
     }
     const duration = anim.method === "set" ? 0 : anim.duration ?? GSAP_DEFAULT_DURATION;
-    let start;
-    if (anim.implicitPosition) {
-      start = cursor;
-    } else if (typeof anim.position === "number") {
-      start = anim.position;
-    } else if (typeof anim.position === "string") {
-      start = resolvePositionString(anim.position, cursor, prevStart);
-    } else {
-      start = cursor;
-    }
+    const start = resolveAnimStart(anim, cursor, prevStart, labels);
     if (start != null) {
       anim.resolvedStart = Math.max(0, start);
       prevStart = anim.resolvedStart;
       cursor = Math.max(cursor, anim.resolvedStart + duration);
     }
-  }
+  });
+  while (labelIdx < sortedLabels.length) defineLabel(sortedLabels[labelIdx++]);
+}
+function collectAddLabelDefs(ast, ref, scope, sortedCalls) {
+  const callLocs = sortedCalls.map((c) => c.node.callee?.property?.loc?.start);
+  const defs = [];
+  acornWalk.simple(ast, {
+    // fallow-ignore-next-line complexity
+    CallExpression(node) {
+      const callee = node.callee;
+      const objMatches = ref.kind === "identifier" ? callee.object?.type === "Identifier" && callee.object.name === ref.name : sameMemberAccess(callee.object, ref.node);
+      if (callee?.type !== "MemberExpression" || !objMatches || callee.property?.name !== "addLabel")
+        return;
+      const nameNode = node.arguments?.[0];
+      const name = typeof nameNode?.value === "string" ? nameNode.value : void 0;
+      if (!name) return;
+      const posVal = resolveNode(node.arguments?.[1], scope);
+      const position = typeof posVal === "number" || typeof posVal === "string" ? posVal : void 0;
+      const labelLoc = callee.property?.loc?.start;
+      let order = sortedCalls.length;
+      if (labelLoc) {
+        order = callLocs.findIndex(
+          (l) => l && (l.line > labelLoc.line || l.line === labelLoc.line && l.column > labelLoc.column)
+        );
+        if (order === -1) order = sortedCalls.length;
+      }
+      defs.push({ name, position, order });
+    }
+  });
+  return defs;
 }
 function compareByLoc(a, b) {
   const aLoc = a.node.callee?.property?.loc?.start;
@@ -1653,7 +1908,10 @@ function parseGsapScriptAcorn(script) {
     sortBySourcePosition(calls);
     const rawAnims = calls.map((call) => tweenCallToAnimation(call, scope, script));
     applyTimelineDefaults(rawAnims, detection.defaults);
-    resolveTimelinePositions(rawAnims);
+    seedSetStates(rawAnims, collectGsapSetStates(ast, scope, targetBindings, script));
+    const labelDefs = collectAddLabelDefs(ast, ref, scope, calls);
+    resolveTimelinePositions(rawAnims, labelDefs);
+    annotateStaggeredCollections(rawAnims);
     const animations = assignStableIds(rawAnims);
     const declPattern = ref.kind === "identifier" ? `(?:const|let|var)\\s+${timelineVar}\\s*=\\s*gsap\\.timeline\\s*\\([^)]*\\)\\s*;?` : `${escapeRegExp(timelineVar)}\\s*=\\s*gsap\\.timeline\\s*\\([^)]*\\)\\s*;?`;
     const timelineMatch = script.match(new RegExp(`^[\\s\\S]*?${declPattern}`));
@@ -2491,6 +2749,76 @@ function checkSubCompositionUsability(html, parseHtml2) {
   return { ok: true };
 }
 
+// src/outputResolutionCompatibility.ts
+var OK = { ok: true };
+function suggestMatchingPreset(compositionWidth, compositionHeight, chosen) {
+  const aspectMatches = VALID_CANVAS_RESOLUTIONS.filter((preset) => {
+    const { width, height } = CANVAS_DIMENSIONS[preset];
+    return width * compositionHeight === height * compositionWidth;
+  });
+  if (aspectMatches.length === 0) return void 0;
+  const chosenIs4k = chosen.endsWith("-4k");
+  const sameTier = aspectMatches.find((preset) => preset.endsWith("-4k") === chosenIs4k);
+  return sameTier ?? aspectMatches[0];
+}
+function describeOrientation(width, height) {
+  if (width > height) return "landscape";
+  if (width < height) return "portrait";
+  return "square";
+}
+function buildAspectMismatch(compositionWidth, compositionHeight, outputResolution, target) {
+  const suggestedResolution = suggestMatchingPreset(
+    compositionWidth,
+    compositionHeight,
+    outputResolution
+  );
+  const suggestion = suggestedResolution ? ` The composition is ${describeOrientation(compositionWidth, compositionHeight)} \u2014 use --resolution ${suggestedResolution} instead.` : ` Pick a preset whose orientation matches, or omit --resolution to render at the composition's native dimensions.`;
+  return {
+    ok: false,
+    kind: "aspect-mismatch",
+    suggestedResolution,
+    message: `outputResolution ${outputResolution} (${target.width}\xD7${target.height}) does not match the aspect ratio of the composition (${compositionWidth}\xD7${compositionHeight}).` + suggestion
+  };
+}
+function checkOutputResolutionCompatibility(input) {
+  const { compositionWidth, compositionHeight, outputResolution } = input;
+  if (!outputResolution) return OK;
+  if (input.hdrRequested) {
+    return {
+      ok: false,
+      kind: "hdr-incompatible",
+      message: `outputResolution cannot be combined with hdrMode='force-hdr'. HDR rendering composites at composition dimensions and does not yet support supersampling. Pick one or render in two passes.`
+    };
+  }
+  if (input.alphaRequested) {
+    return {
+      ok: false,
+      kind: "alpha-incompatible",
+      message: `outputResolution cannot be combined with alpha output (--format webm|mov|png-sequence). The alpha screenshot path does not yet apply deviceScaleFactor and would silently produce composition-resolution frames. Render alpha at composition resolution and upscale separately, or use --format mp4.`
+    };
+  }
+  const target = CANVAS_DIMENSIONS[outputResolution];
+  if (target.width * compositionHeight !== target.height * compositionWidth) {
+    return buildAspectMismatch(compositionWidth, compositionHeight, outputResolution, target);
+  }
+  const widthRatio = target.width / compositionWidth;
+  if (widthRatio < 1) {
+    return {
+      ok: false,
+      kind: "downsampling",
+      message: `outputResolution ${outputResolution} (${target.width}\xD7${target.height}) is smaller than the composition (${compositionWidth}\xD7${compositionHeight}). Downsampling via --resolution is not supported.`
+    };
+  }
+  if (!Number.isInteger(widthRatio)) {
+    return {
+      ok: false,
+      kind: "non-integer-scale",
+      message: `outputResolution ${outputResolution} requires a non-integer device scale factor (${widthRatio}\xD7) to upsample from ${compositionWidth}\xD7${compositionHeight}. Pick a preset that's an integer multiple, or rescale the composition.`
+    };
+  }
+  return OK;
+}
+
 // src/gsapUnroll.ts
 import * as acorn2 from "acorn";
 import MagicString2 from "magic-string";
@@ -2718,6 +3046,7 @@ export {
   TIMELINE_COLORS,
   VALID_CANVAS_RESOLUTIONS,
   addElementToHtml,
+  checkOutputResolutionCompatibility,
   checkSubCompositionUsability,
   classifyPropertyGroup,
   classifyTweenPropertyGroup,