lint: validate composition variables declared on supported root elements #4383

Invalid data-composition-variables JSON is diagnosed on <html> but passes lint on a composition-root div or template root. Runtime supports those declaring elements, so a typo there silently drops declared defaults without the existing helpful diagnostic.

Reproduction

From the repository root:

cat > /tmp/hf-d4.ts <<'TS'
const { lintHyperframeHtml } = await import(`${process.cwd()}/packages/lint/src/hyperframeLinter.ts`);
const root = `<div id="main" data-composition-id="main" data-no-timeline data-width="1920" data-height="1080" data-duration="10" DECLARATION></div>`;
for (const [name, html, options] of [
  ["html", `<html data-composition-variables='broken'><body>${root.replace("DECLARATION", "")}</body></html>`, {}],
  ["root", `<html><body>${root.replace("DECLARATION", "data-composition-variables='broken'")}</body></html>`, {}],
  ["template", `<template>${root.replace("DECLARATION", "data-composition-variables='broken'")}</template>`, { isSubComposition: true }],
] as const) {
  console.log(name, (await lintHyperframeHtml(html, options)).findings.map((f: {code: string}) => f.code));
}
TS
bun /tmp/hf-d4.ts

Observed:

html [ "invalid_composition_variables_declaration" ]
root []
template []

Expected: all three malformed declarations receive invalid_composition_variables_declaration.

Scope and suggested approach

The existing declaration rule restricts validation to findHtmlTag(tags). getVariables collects declaring elements beyond <html>, and the existing binding diagnostic supports composition roots. Apply the existing declaration/schema validation to the supported declaring elements. Keep current schema and runtime behavior.

Add cases to composition.test.ts.

Acceptance criteria

• Malformed JSON and invalid declaration shapes are diagnosed on full-document roots and template/fragment composition roots.
• Valid supported declarations remain clean.
• Each invalid declaration is reported once with its actual source location/element where available.
• Multiple declaring elements are checked independently; validation does not change their runtime precedence.
• Existing composition-rule tests pass.

Estimated difficulty: easy. Reviewer/mentor: pending.

Related work

No active matching implementation was found in the checked inventory. Existing root-binding and source-location support should be reused; do not change variable precedence, schema, or the runtime's fallback behavior.

Validation

From a dependency-installed repository checkout, run the reproduction above with Bun. It imports source directly and does not need real media files, Chrome, or FFmpeg. Add regression cases in the linked existing suite, then run:

bun run --cwd packages/lint test src/rules/composition.test.ts
bunx oxlint packages/lint/src/rules/composition.ts packages/lint/src/rules/composition.test.ts
bunx oxfmt --check packages/lint/src/rules/composition.ts packages/lint/src/rules/composition.test.ts

Discovery ran the minimal source-level reproduction, not the full test suite or a video render. Reproduced on fa4261beea63bb4f36ff6a2f20fb4646fae3f2c6 (0.8.68); relevant source is unchanged on origin/main at 86fa10ced4297bfd9f4fe67b6767afae7a07fd3c (0.8.69).

Overlap refresh: checked open issue/PR titles and bodies from the fresh publication inventory on 2026-09-23; no matching active implementation found. Before starting, check the discussion and linked PRs, then comment with your intended approach so ownership can be coordinated.