refactor(core): type-safety hardening — double casts, magic numbers, globals

- Extract magic numbers: UHD_SQUARE_MIN/UHD_RECT_MIN in htmlParser,
  PROFILER_TIMEOUT_MS/FC_MATCH_TIMEOUT_MS in systemFontLocator,
  MAX_COPY_INDEX in files route
- Replace 4 as-unknown-as-HTMLElement double casts with isHTMLElement
  type predicate (reusing existing structural guard in sourceMutation)
- Create runtime/globals.ts with getDebugSurface typed accessor,
  eliminating double cast in diagnostics.ts
- Extract applyMediaAttrs and lastKeyframeOpacity to reduce function
  complexity in htmlParser and files route
- Remove dead SwallowedEvent interface from diagnostics

Author: miguel-heygen

packages/core/src/fonts/systemFontLocator.ts

@@ -4,6 +4,8 @@ import { homedir, platform } from "node:os";
 import { join, resolve } from "node:path";
 
 export const SYSTEM_FONT_SIZE_LIMIT = 5 * 1024 * 1024;
+const PROFILER_TIMEOUT_MS = 5000;
+const FC_MATCH_TIMEOUT_MS = 3000;
 
 export type FontFileFormat = "ttf" | "otf" | "woff2" | "woff" | "ttc";
 
@@ -238,7 +240,7 @@ function getSystemProfilerIndex(): Map<string, SystemProfilerEntry[]> {
     const raw = execFileSync("system_profiler", ["SPFontsDataType", "-json"], {
       encoding: "utf8",
       maxBuffer: 12 * 1024 * 1024,
-      timeout: 5000,
+      timeout: PROFILER_TIMEOUT_MS,
     });
     const parsed = JSON.parse(raw);
     if (!parsed?.SPFontsDataType || !Array.isArray(parsed.SPFontsDataType)) return profilerCache;
@@ -289,7 +291,7 @@ function locateViaFcMatch(targetFamily: string): LocatedFont | null {
   try {
     const result = execFileSync("fc-match", [targetFamily, "--format=%{file}"], {
       encoding: "utf8",
-      timeout: 3000,
+      timeout: FC_MATCH_TIMEOUT_MS,
     }).trim();
     if (!result || !isRegularFile(result) || !isPathBounded(result)) return null;
     const fileName = result.split("/").pop() ?? "";

packages/core/src/parsers/htmlParser.ts

@@ -139,19 +139,16 @@ function parseResolutionFromHtml(doc: Document): CanvasResolution | null {
   return null;
 }
 
+const UHD_SQUARE_MIN = 2160;
+const UHD_RECT_MIN = 3840;
+
 function resolveResolutionFromDimensions(width: number, height: number): CanvasResolution {
   const longSide = Math.max(width, height);
-  // UHD cutoff is the long side of the 4K presets (3840 for `landscape-4k` /
-  // `portrait-4k`, 2160 for `square-4k`). A looser threshold (e.g. >= 2560)
-  // would silently misclassify QHD/1440p (2560x1440) as 4K, which is the
-  // wrong default for a common authoring resolution closer to 1080p than to
-  // UHD. Authors who genuinely want the 4K preset can still set
-  // `data-resolution="..."` explicitly.
   if (width === height) {
-    return longSide >= 2160 ? "square-4k" : "square";
+    return longSide >= UHD_SQUARE_MIN ? "square-4k" : "square";
   }
   const isLandscape = width > height;
-  const isUhd = longSide >= 3840;
+  const isUhd = longSide >= UHD_RECT_MIN;
   if (isLandscape) return isUhd ? "landscape-4k" : "landscape";
   return isUhd ? "portrait-4k" : "portrait";
 }
@@ -612,16 +609,20 @@ export function addElementToHtml(
 
   let newEl: Element;
 
+  function applyMediaAttrs(el: Element, mediaEl: TimelineMediaElement): void {
+    if (mediaEl.src) el.setAttribute("src", mediaEl.src);
+    if (mediaEl.volume !== undefined && mediaEl.volume !== 1) {
+      el.setAttribute("data-volume", String(mediaEl.volume));
+    }
+  }
+
   switch (element.type) {
     case "video": {
       const mediaEl = element as TimelineMediaElement;
       newEl = doc.createElement("video");
       newEl.setAttribute("muted", "");
       newEl.setAttribute("playsinline", "");
-      if (mediaEl.src) newEl.setAttribute("src", mediaEl.src);
-      if (mediaEl.volume !== undefined && mediaEl.volume !== 1) {
-        newEl.setAttribute("data-volume", String(mediaEl.volume));
-      }
+      applyMediaAttrs(newEl, mediaEl);
       if (mediaEl.hasAudio) {
         newEl.setAttribute("data-has-audio", "true");
       }
@@ -637,10 +638,7 @@ export function addElementToHtml(
     case "audio": {
       const mediaEl = element as TimelineMediaElement;
       newEl = doc.createElement("audio");
-      if (mediaEl.src) newEl.setAttribute("src", mediaEl.src);
-      if (mediaEl.volume !== undefined && mediaEl.volume !== 1) {
-        newEl.setAttribute("data-volume", String(mediaEl.volume));
-      }
+      applyMediaAttrs(newEl, mediaEl);
       break;
     }
     case "text":

packages/core/src/runtime/diagnostics.ts

@@ -27,24 +27,11 @@
  * helper call is a real statement, so no `no-empty` warnings ship in the
  * inlined IIFE.
  */
-export interface SwallowedEvent {
-  /** Short, descriptive label naming the operation that failed. */
-  label: string;
-  /** The thrown value (often an Error, but JS allows anything). */
-  error: unknown;
-}
-
-interface HFDebugSurface {
-  __hfDebug?: boolean;
-  __HYPERFRAMES_DEBUG?: boolean;
-  __hf?: {
-    onSwallowed?: (event: SwallowedEvent) => void;
-  };
-}
+import { getDebugSurface } from "./globals.js";
 
 export function swallow(label: string, error?: unknown): void {
   if (typeof window === "undefined") return;
-  const w = window as unknown as HFDebugSurface;
+  const w = getDebugSurface();
 
   const handler = w.__hf?.onSwallowed;
   if (handler) {

packages/core/src/runtime/globals.ts

@@ -0,0 +1,11 @@
+export interface HFDebugSurface {
+  __hfDebug?: boolean;
+  __HYPERFRAMES_DEBUG?: boolean;
+  __hf?: {
+    onSwallowed?: (event: { label: string; error: unknown }) => void;
+  };
+}
+
+export function getDebugSurface(): HFDebugSurface {
+  return globalThis as HFDebugSurface;
+}

packages/core/src/studio-api/helpers/sourceMutation.ts

@@ -122,7 +122,7 @@ export function removeElementFromHtml(source: string, target: SourceMutationTarg
   return wrappedFragment ? document.body.innerHTML || "" : document.toString();
 }
 
-function isHTMLElement(el: Element): boolean {
+export function isHTMLElement(el: Element): el is HTMLElement {
   const HTMLEl = el.ownerDocument.defaultView?.HTMLElement;
   return HTMLEl ? el instanceof HTMLEl : "style" in el;
 }
@@ -283,7 +283,7 @@ export function patchElementInHtml(
   const { document, wrappedFragment } = parseSourceDocument(source);
   const el = findTargetElement(document, target);
   if (!el || !isHTMLElement(el)) return { html: source, matched: false };
-  const htmlEl = el as unknown as HTMLElement;
+  const htmlEl = el;
 
   for (const op of operations) {
     switch (op.type) {
@@ -320,7 +320,7 @@ export function patchElementInHtml(
       case "text-content":
         if (op.value != null) {
           const inner = htmlEl.children.length === 1 ? htmlEl.firstElementChild : null;
-          const textTarget = inner ? (inner as unknown as HTMLElement) : htmlEl;
+          const textTarget = inner && isHTMLElement(inner) ? inner : htmlEl;
           textTarget.textContent = op.value;
         }
         break;

packages/core/src/studio-api/routes/files.ts

@@ -29,6 +29,7 @@ import {
   patchElementInHtml,
   probeElementInSource,
   splitElementInHtml,
+  isHTMLElement,
   type PatchOperation,
 } from "../helpers/sourceMutation.js";
 import { parseHTML } from "linkedom";
@@ -265,7 +266,8 @@ function stripStudioEditsFromTarget(document: Document, selector: string): numbe
   try {
     for (const el of document.querySelectorAll(selector)) {
       if (!el.getAttribute("data-hf-studio-path-offset")) continue;
-      const htmlEl = el as unknown as HTMLElement;
+      if (!isHTMLElement(el)) continue;
+      const htmlEl = el;
       const originalTranslate = el.getAttribute("data-hf-studio-original-inline-translate");
       htmlEl.style.removeProperty("--hf-studio-offset-x");
       htmlEl.style.removeProperty("--hf-studio-offset-y");
@@ -285,33 +287,29 @@ function stripStudioEditsFromTarget(document: Document, selector: string): numbe
   return stripped;
 }
 
-function bakeVisibilityOnDelete(document: Document, anim: GsapAnimation): void {
-  let finalOpacity: number | string | undefined;
-  if (anim.method === "from") {
-    return;
-  }
-  if (anim.keyframes) {
-    const kfs = anim.keyframes.keyframes;
-    for (let i = kfs.length - 1; i >= 0; i--) {
-      if ("opacity" in kfs[i]!.properties) {
-        finalOpacity = kfs[i]!.properties.opacity;
-        break;
-      }
-    }
-  } else if ("opacity" in anim.properties) {
-    finalOpacity = anim.properties.opacity;
-  }
-  if (finalOpacity == null) {
-    return;
-  }
-  if (typeof finalOpacity === "string" && /^[+\-*]=/.test(finalOpacity)) {
-    return;
+function lastKeyframeOpacity(kfs: GsapAnimation["keyframes"]): number | string | undefined {
+  if (!kfs) return undefined;
+  for (let i = kfs.keyframes.length - 1; i >= 0; i--) {
+    if ("opacity" in kfs.keyframes[i]!.properties) return kfs.keyframes[i]!.properties.opacity;
   }
-  const numOpacity = Number(finalOpacity);
-  if (!Number.isFinite(numOpacity) || numOpacity === 0) return;
+  return undefined;
+}
+
+function resolveFinalOpacity(anim: GsapAnimation): number | null {
+  if (anim.method === "from") return null;
+  const raw = anim.keyframes ? lastKeyframeOpacity(anim.keyframes) : anim.properties.opacity;
+  if (raw == null) return null;
+  if (typeof raw === "string" && /^[+\-*]=/.test(raw)) return null;
+  const num = Number(raw);
+  return Number.isFinite(num) && num !== 0 ? num : null;
+}
+
+function bakeVisibilityOnDelete(document: Document, anim: GsapAnimation): void {
+  const opacity = resolveFinalOpacity(anim);
+  if (opacity === null) return;
   try {
     for (const el of document.querySelectorAll(anim.targetSelector)) {
-      (el as unknown as HTMLElement).style.setProperty("opacity", String(numOpacity));
+      if (isHTMLElement(el)) el.style.setProperty("opacity", String(opacity));
     }
   } catch {
     // Invalid selector — skip silently.
@@ -780,8 +778,9 @@ async function processUploadedFiles(
       const ext = dotIdx > 0 ? name.slice(dotIdx) : "";
       const base = dotIdx > 0 ? name.slice(0, dotIdx) : name;
       let n = 2;
-      while (n < 10000 && existsSync(resolve(targetDir, `${base} (${n})${ext}`))) n++;
-      if (n >= 10000) {
+      const MAX_COPY_INDEX = 10000;
+      while (n < MAX_COPY_INDEX && existsSync(resolve(targetDir, `${base} (${n})${ext}`))) n++;
+      if (n >= MAX_COPY_INDEX) {
         skipped.push(name);
         continue;
       }