fix(core,producer,cli): pre-flight validation for empty/malformed sub-compositions (#1831)

* fix(core,producer,cli): pre-flight validation for empty/malformed sub-compositions

The #1 render failure bucket in production telemetry (PostHog project 356858,
dashboard 1783183 "HyperFrames — Bottom-Line & Activation"; ~65-69K
occurrences / ~27-28K affected users over 30 days, ~80% via AI-agent
authoring flows) is a `data-composition-src` reference pointing at a scene
file that is empty, malformed, or missing.

Root cause, traced end-to-end:
- The literal error "Composition HTML is empty or could not be parsed: <path>"
  is real (not a PostHog paraphrase) — thrown by a since-reverted guard in
  packages/core/src/compiler/inlineSubCompositions.ts (#1364), then changed to
  a silent skip in #1678 to avoid aborting renders on partial content during
  authoring. #1629 added per-assembler guards for 3 skill workflows
  (product-launch-video, faceless-explainer, pr-to-video), but general-video
  and hand-authored flows — where the dominant filename `scene-title.html`
  (40K+/68K of the bucket) originates — have no assembler and thus no guard.
  #1678 assumed the assembler guards from #1629 covered this pre-render; they
  only covered 3 of the many authoring flows.
- On current `main`, an empty/malformed data-composition-src file no longer
  crashes or throws during render — it's silently dropped by the tolerant
  inliner. Reproduced locally: `hyperframes render` on a project with an
  empty scene-title.html "succeeds" after ~93s (two 45s
  pollSubCompositionTimelines timeouts) with the scene silently missing from
  the output video. `hyperframes validate` also reports "No console errors"
  for the same broken project.
- The raw `Cannot destructure property 'firstElementChild' of
  'documentElement' as it is null` crash reproduces directly against
  linkedom (the DOMParser polyfill packages/cli/src/utils/dom.ts installs in
  the real CLI runtime) for empty and non-HTML input — confirmed with a
  standalone repro script, not just inferred. jsdom/happy-dom (used in this
  repo's own test environment) are spec-compliant and never produce a null
  documentElement, which is why this needed a linkedom-specific test file.

Fix:
- New shared helper `checkSubCompositionUsability`
  (packages/core/src/compiler/subCompositionValidity.ts) is the single
  source of truth for "is this data-composition-src file usable" — mirrors
  the inliner's own parse/template/body logic so all callers agree.
- `inlineSubCompositions.ts` (preview/studio bundling) now uses the shared
  helper internally but keeps its #1678 tolerant skip-and-continue behavior
  unchanged — mid-authoring iteration on a partial project must keep
  working. `onMissingComposition` now also receives a human-readable reason.
- New render-only pre-flight (`assertSubCompositionsUsable` in
  packages/producer/src/services/htmlCompiler.ts) walks every
  data-composition-src reference (including nested ones, root-relative,
  matching parseSubCompositions' own resolution) before any compilation
  work starts, and throws naming every offending file at once. This is
  unconditional — not gated behind --strict — because a render that
  silently drops a scene is strictly worse than one that refuses to start.
  Confirmed locally: render now fails in ~0.4s with an actionable message
  instead of "succeeding" after 93s with a missing scene.
- New `hyperframes lint` rule `missing_or_empty_sub_composition`
  (packages/cli/src/utils/lintProject.ts) surfaces the same check as a
  file-scoped, actionable lint error (already unconditional — lint exits 1
  on any error).
- `hyperframes validate` now also runs this check before launching a
  browser, so it no longer reports "No console errors" for a project with a
  broken sub-composition.
- `packages/core/src/parsers/htmlParser.ts`: guarded every
  `documentElement`-may-be-null access (parseHtml, updateElementInHtml,
  addElementToHtml, removeElementFromHtml, extractCompositionMetadata,
  validateCompositionHtml) with a new typed `CompositionHtmlParseError` (or,
  for validateCompositionHtml's collect-and-report contract, a typed
  validation failure) instead of a raw crash.

Tests: empty file, whitespace-only, malformed/non-HTML, missing file, nested
sub-compositions (both happy path and broken-grandchild), and the happy path
— at the shared-helper, lint, and render pre-flight layers.

Not changed: the AI-agent authoring skills (skills/*). general-video and
hand-authored flows have no assemble-index.mjs equivalent to guard, so the
fix is at the CLI/render layer instead — flow-agnostic, covers every
authoring path, and the skills' existing "run lint/validate and stop on
failure" guidance now actually catches this class of mistake once run.

Not run in this environment: the producer package's full regression-harness
test suite (`bun test` in packages/producer) — it performs heavy real
rendering (S3 asset downloads, Google Fonts fetches, full video encodes) and
did not complete in a reasonable time in this sandbox. Verified instead via
the targeted test file for all touched code (76/76 passing), whole-repo
typecheck/build/oxlint, `fallow audit` (complexity/duplication/dead-code
gate, clean), and manual end-to-end CLI runs (render/lint/validate) against
reproduction projects, including a nested sub-composition scenario. CI
should run the full producer suite before merge.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* refactor(parsers,lint): port empty-composition pre-flight to extracted packages

Rebased onto main, which extracted @hyperframes/lint from core (lint depends
only on parsers, not core). Relocate checkSubCompositionUsability from core to
@hyperframes/parsers so both core (inliner) and lint can consume it without a
core<->lint cycle; core keeps a @deprecated re-export shim.

Correctness fixes from code review:
- checkSubCompositionUsability now returns "no-composition-root" when the
  <template>/<body> content has no [data-composition-id] element (previously
  a marker-free placeholder body passed both guards).
- lint's missing/empty sub-composition rule now only checks files reachable
  via data-composition-src from the root (matching render pre-flight), instead
  of a raw filesystem walk that false-positived on orphaned files.
- drop `as string` cast in inlineSubCompositions in favor of an explicit
  null guard (per CLAUDE.md).

Review-comment items:
- move EmptyCompositionError JSDoc above the class (was above the adapter fn).
- correct stale circular-ref comment to match actual silent-skip behavior.
- rewrite self-contradicting lint message ("silently drop") to describe the
  new loud render-pre-flight abort.
- add the __PLACEHOLDER__ (/^__[A-Z_]+__$/) skip to the render pre-flight so
  it agrees with lint.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

packages/parsers/src/htmlParser.ts

@@ -19,6 +19,22 @@ import { removeAnimationFromScript } from "./gsapWriterAcorn.js";
 
 const MEDIA_TYPES = new Set<string>(["video", "image", "audio"]);
 
+/**
+ * Thrown by htmlParser functions when the input HTML is empty or does not
+ * parse to a document with a `documentElement` — the condition that,
+ * unguarded, previously surfaced as a raw
+ * `Cannot read properties of null (reading '...')` /
+ * `Cannot destructure property 'firstElementChild' of 'documentElement' as
+ * it is null` crash deep inside the DOM implementation instead of a clear,
+ * catchable error naming which function received bad input.
+ */
+export class CompositionHtmlParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CompositionHtmlParseError";
+  }
+}
+
 export interface ParsedHtml {
   elements: TimelineElement[];
   gsapScript: string | null;
@@ -117,6 +133,7 @@ function parseResolutionFromCss(doc: Document, cssText: string | null): CanvasRe
 
 function parseResolutionFromHtml(doc: Document): CanvasResolution | null {
   const htmlEl = doc.documentElement;
+  if (!htmlEl) return null;
   const resolutionAttr = htmlEl.getAttribute("data-resolution");
   if (
     resolutionAttr === "landscape" ||
@@ -166,6 +183,9 @@ export function parseHtml(html: string): ParsedHtml {
   let idCounter = 0;
 
   const htmlEl = doc.documentElement;
+  if (!htmlEl) {
+    throw new CompositionHtmlParseError("parseHtml: input HTML is empty or could not be parsed");
+  }
   const customStylesAttr = htmlEl.getAttribute("data-custom-styles");
   let customStyles: string | null = null;
   if (customStylesAttr) {
@@ -591,6 +611,11 @@ export function updateElementInHtml(
     }
   }
 
+  if (!doc.documentElement) {
+    throw new CompositionHtmlParseError(
+      "updateElementInHtml: input HTML is empty or could not be parsed",
+    );
+  }
   return "<!DOCTYPE html>\n" + doc.documentElement.outerHTML;
 }
 
@@ -601,6 +626,12 @@ export function addElementToHtml(
   const parser = new DOMParser();
   const doc = parser.parseFromString(html, "text/html");
 
+  if (!doc.documentElement) {
+    throw new CompositionHtmlParseError(
+      "addElementToHtml: input HTML is empty or could not be parsed",
+    );
+  }
+
   // Prefer zoom container, fall back to stage, then container, then body
   const container =
     doc.querySelector("#stage-zoom-container") ||
@@ -608,6 +639,10 @@ export function addElementToHtml(
     doc.querySelector("#stage") ||
     doc.body;
 
+  if (!container) {
+    throw new CompositionHtmlParseError("addElementToHtml: input HTML has no <body>");
+  }
+
   const id = element.id || `element-${Date.now()}`;
 
   let newEl: Element;
@@ -716,6 +751,11 @@ function cascadeRemoveGsapById(doc: Document, elementId: string): void {
 export function removeElementFromHtml(html: string, elementId: string): string {
   const parser = new DOMParser();
   const doc = parser.parseFromString(html, "text/html");
+  if (!doc.documentElement) {
+    throw new CompositionHtmlParseError(
+      "removeElementFromHtml: input HTML is empty or could not be parsed",
+    );
+  }
   doc.getElementById(elementId)?.remove();
   cascadeRemoveGsapById(doc, elementId);
   return "<!DOCTYPE html>\n" + doc.documentElement.outerHTML;
@@ -731,6 +771,11 @@ export function extractCompositionMetadata(html: string): CompositionMetadata {
   const parser = new DOMParser();
   const doc = parser.parseFromString(html, "text/html");
   const htmlEl = doc.documentElement;
+  if (!htmlEl) {
+    throw new CompositionHtmlParseError(
+      "extractCompositionMetadata: input HTML is empty or could not be parsed",
+    );
+  }
 
   const compositionId = htmlEl.getAttribute("data-composition-id");
   const durationStr = htmlEl.getAttribute("data-composition-duration");
@@ -798,6 +843,14 @@ export function validateCompositionHtml(html: string): ValidationResult {
   const doc = parser.parseFromString(html, "text/html");
   const htmlEl = doc.documentElement;
 
+  if (!htmlEl) {
+    return {
+      valid: false,
+      errors: ["Composition HTML is empty or could not be parsed"],
+      warnings: [],
+    };
+  }
+
   const compositionId = htmlEl.getAttribute("data-composition-id");
   if (!compositionId) {
     errors.push("Missing data-composition-id attribute on <html> element");