Skip to content

Commit 2229d0d

Browse files
fix(lint): root_dimensions_mismatch sub-composition false positive + regex SSOT consolidation (#4012)
* fix(lint): guard root_dimensions_mismatch against sub-compositions Sub-compositions mounted via data-composition-src are fetched with DOMParser and only their matched <template>/<body> subtree is imported into the live document. A sub-composition authored as a full standalone HTML document still carries its own <html>/<head>/<meta viewport>, but none of that ever reaches the rendering document, so a mismatch there was always a false positive. Guard the rule with options.isSubComposition, matching the sibling missing_timeline_registry rule's existing pattern. Split the warning wording: html/body CSS actually sizes the element that clips the root, but the CDP viewport is set from the root's own data-width/data-height (frameCapture.ts), never from <meta viewport>. A viewport-only mismatch is real drift but not a clipping risk. Co-Authored-By: Miguel Ángel <[email protected]> * fix(cli,parsers): consolidate scaffold resolution regexes into one definition applyResolutionPreset kept its own prefix-capturing regex literals for the html/body CSS size and meta viewport content, duplicating the same three patterns already defined in @hyperframes/parsers for lint's read-only root_dimensions_mismatch comparison. Merge to one definition per pattern that captures both the prefix (for in-place replace) and the digits (for comparison), so the two callers can no longer drift on where a scaffold's resolution lives. Existing applyResolutionPreset tests stay green. Co-Authored-By: Miguel Ángel <[email protected]> --------- Co-authored-by: Miguel Ángel <[email protected]>
1 parent d6fe667 commit 2229d0d

5 files changed

Lines changed: 187 additions & 47 deletions

File tree

‎packages/cli/src/commands/init.ts‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,11 @@ import {
5353
normalizeResolutionFlag,
5454
type CanvasResolution,
5555
} from "@hyperframes/core";
56+
import {
57+
HTML_BODY_CSS_HEIGHT_FIRST_RE,
58+
HTML_BODY_CSS_WIDTH_FIRST_RE,
59+
VIEWPORT_META_SIZE_RE,
60+
} from "@hyperframes/parsers";
5661

5762
function resolveScaffoldTemplateId(exampleFlag: string | undefined, hasMediaFile: boolean): string {
5863
const example = exampleFlag === "agent" ? "blank" : exampleFlag;
@@ -527,20 +532,18 @@ export function applyResolutionPreset(destDir: string, resolution: CanvasResolut
527532

528533
// Inline `html, body { ... }` CSS: handle width-before-height and
529534
// height-before-width orderings. Hand-authored templates can use either.
530-
const bodyCssRe = /(html\s*,\s*body\s*\{[^}]*?width:\s*)\d+px([^}]*?height:\s*)\d+px/i;
531-
if (bodyCssRe.test(html)) {
532-
html = html.replace(bodyCssRe, `$1${width}px$2${height}px`);
535+
// Groups 1 and 3 are the text before each dimension, 2 and 4 the digits.
536+
if (HTML_BODY_CSS_WIDTH_FIRST_RE.test(html)) {
537+
html = html.replace(HTML_BODY_CSS_WIDTH_FIRST_RE, `$1${width}px$3${height}px`);
533538
changed = true;
534539
}
535-
const bodyCssReverseRe = /(html\s*,\s*body\s*\{[^}]*?height:\s*)\d+px([^}]*?width:\s*)\d+px/i;
536-
if (bodyCssReverseRe.test(html)) {
537-
html = html.replace(bodyCssReverseRe, `$1${height}px$2${width}px`);
540+
if (HTML_BODY_CSS_HEIGHT_FIRST_RE.test(html)) {
541+
html = html.replace(HTML_BODY_CSS_HEIGHT_FIRST_RE, `$1${height}px$3${width}px`);
538542
changed = true;
539543
}
540544

541-
const viewportRe = /(<meta[^>]*name=["']viewport["'][^>]*content=["'])width=\d+,\s*height=\d+/i;
542-
if (viewportRe.test(html)) {
543-
html = html.replace(viewportRe, `$1width=${width}, height=${height}`);
545+
if (VIEWPORT_META_SIZE_RE.test(html)) {
546+
html = html.replace(VIEWPORT_META_SIZE_RE, `$1${width}$3${height}`);
544547
changed = true;
545548
}
546549

‎packages/lint/src/rules/core.test.ts‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,71 @@ describe("core rules", () => {
176176
expect(result.findings.find((f) => f.code === "root_dimensions_mismatch")).toBeUndefined();
177177
});
178178

179+
it("does not report root_dimensions_mismatch for a full sub-composition document whose own viewport meta disagrees with its root", async () => {
180+
// Matches the hf2550 flowchart-vertical fixture's shape: a full standalone
181+
// document mounted as a sub-composition. See the rule's comment in core.ts
182+
// for why its own <meta viewport> never reaches the rendering document.
183+
const html = `
184+
<!doctype html>
185+
<html>
186+
<head>
187+
<meta name="viewport" content="width=1440, height=2560" />
188+
</head>
189+
<body>
190+
<div id="root" data-composition-id="c1" data-width="1080" data-height="1920"></div>
191+
<script>window.__timelines = {};</script>
192+
</body>
193+
</html>`;
194+
const result = await lintHyperframeHtml(html, { isSubComposition: true });
195+
expect(result.findings.find((f) => f.code === "root_dimensions_mismatch")).toBeUndefined();
196+
});
197+
198+
it("still reports root_dimensions_mismatch for the same shape linted as a top-level composition, with no-clipping-risk wording since there is no html/body CSS block at all", async () => {
199+
const html = `
200+
<!doctype html>
201+
<html>
202+
<head>
203+
<meta name="viewport" content="width=1440, height=2560" />
204+
</head>
205+
<body>
206+
<div id="root" data-composition-id="c1" data-width="1080" data-height="1920"></div>
207+
<script>window.__timelines = {};</script>
208+
</body>
209+
</html>`;
210+
const result = await lintHyperframeHtml(html);
211+
const finding = result.findings.find((f) => f.code === "root_dimensions_mismatch");
212+
expect(finding).toBeDefined();
213+
// No html/body CSS block is present here at all (the real hf2550 fixture
214+
// shape) -- distinct from the "present and matching" case covered below --
215+
// so the "absent" and "matches" cases of describeSizeMismatch must both
216+
// route to the same no-clipping-risk wording, not just the "matches" one.
217+
expect(finding?.message).not.toContain("clips");
218+
expect(finding?.message.toLowerCase()).toContain("no effect on capture");
219+
});
220+
221+
it("uses no-clipping-risk wording when only the viewport meta disagrees and html/body CSS matches the root", async () => {
222+
const html = portraitCompositionWithScaffold(
223+
"width: 1080px; height: 1920px;",
224+
"width=1440, height=2560",
225+
);
226+
const result = await lintHyperframeHtml(html);
227+
const finding = result.findings.find((f) => f.code === "root_dimensions_mismatch");
228+
expect(finding).toBeDefined();
229+
expect(finding?.message).toContain("the viewport meta is 1440x2560");
230+
expect(finding?.message).not.toContain("clips");
231+
expect(finding?.message.toLowerCase()).toContain("no effect on capture");
232+
});
233+
234+
it("keeps the body-clipping wording when html/body CSS itself disagrees with the root", async () => {
235+
const html = portraitCompositionWithScaffold(
236+
"width: 1920px; height: 1080px;",
237+
"width=1080, height=1920",
238+
);
239+
const result = await lintHyperframeHtml(html);
240+
const finding = result.findings.find((f) => f.code === "root_dimensions_mismatch");
241+
expect(finding?.message).toContain("clips");
242+
});
243+
179244
it("accepts body as the composition root", async () => {
180245
const html = `
181246
<html><body data-composition-id="c1" data-width="1920" data-height="1080">

‎packages/lint/src/rules/core.ts‎

Lines changed: 49 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -239,15 +239,17 @@ function findVisibleMarkupCommentLeak(source: string): string | null {
239239

240240
type ScaffoldSize = { width: string; height: string };
241241

242+
// Groups 1 and 3 are prefix text for applyResolutionPreset's in-place
243+
// replace; lint only reads the digit groups (2 and 4).
242244
function readHtmlBodyCssSize(source: string): ScaffoldSize | null {
243245
const widthFirst = source.match(HTML_BODY_CSS_WIDTH_FIRST_RE);
244246
if (widthFirst) {
245-
const [, width = "", height = ""] = widthFirst;
247+
const [, , width = "", , height = ""] = widthFirst;
246248
return { width, height };
247249
}
248250
const heightFirst = source.match(HTML_BODY_CSS_HEIGHT_FIRST_RE);
249251
if (heightFirst) {
250-
const [, height = "", width = ""] = heightFirst;
252+
const [, , height = "", , width = ""] = heightFirst;
251253
return { width, height };
252254
}
253255
return null;
@@ -256,7 +258,7 @@ function readHtmlBodyCssSize(source: string): ScaffoldSize | null {
256258
function readViewportMetaSize(source: string): ScaffoldSize | null {
257259
const match = source.match(VIEWPORT_META_SIZE_RE);
258260
if (!match) return null;
259-
const [, width = "", height = ""] = match;
261+
const [, , width = "", , height = ""] = match;
260262
return { width, height };
261263
}
262264

@@ -270,15 +272,43 @@ function describeSizeMismatch(
270272
return `${label} is ${size.width}x${size.height}`;
271273
}
272274

273-
function findScaffoldSizeMismatches(
275+
// Only html/body CSS actually clips the root; the CDP viewport comes from
276+
// data-width/data-height, not `<meta viewport>` — so a viewport-only drift gets distinct wording.
277+
function describeRootDimensionsDrift(
274278
source: string,
275279
dataWidth: string,
276280
dataHeight: string,
277-
): string[] {
278-
return [
279-
describeSizeMismatch("html/body CSS", readHtmlBodyCssSize(source), dataWidth, dataHeight),
280-
describeSizeMismatch("the viewport meta", readViewportMetaSize(source), dataWidth, dataHeight),
281-
].filter((mismatch): mismatch is string => mismatch !== null);
281+
): { message: string; fixHint: string } | null {
282+
const bodyCssMismatch = describeSizeMismatch(
283+
"html/body CSS",
284+
readHtmlBodyCssSize(source),
285+
dataWidth,
286+
dataHeight,
287+
);
288+
const viewportMismatch = describeSizeMismatch(
289+
"the viewport meta",
290+
readViewportMetaSize(source),
291+
dataWidth,
292+
dataHeight,
293+
);
294+
if (!bodyCssMismatch && !viewportMismatch) return null;
295+
296+
const declared = `Root composition declares data-width="${dataWidth}" data-height="${dataHeight}"`;
297+
if (!bodyCssMismatch) {
298+
return {
299+
message: `${declared}, but ${viewportMismatch}. The viewport meta has no effect on capture — the renderer sizes the viewport from the root's own data-width/data-height — so this is stale metadata, not a clipping risk.`,
300+
fixHint:
301+
"update the meta viewport to match, or scaffold with `hyperframes init --resolution portrait`",
302+
};
303+
}
304+
const mismatches = viewportMismatch
305+
? `${bodyCssMismatch} and ${viewportMismatch}`
306+
: bodyCssMismatch;
307+
return {
308+
message: `${declared}, but ${mismatches}. The scaffolded body clips the composition at its old size.`,
309+
fixHint:
310+
"update html/body CSS and the meta viewport to match, or scaffold with `hyperframes init --resolution portrait`",
311+
};
282312
}
283313

284314
export const coreRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
@@ -339,28 +369,26 @@ export const coreRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
339369
// root. `hyperframes check`'s layout audits can't see it: they measure
340370
// against the root's own (already-correct) rect, not the body's.
341371
//
342-
// A sub-composition fragment has no html/body or viewport to compare
343-
// against, which makes this top-level-only without a separate guard.
344-
({ rootTag, source }) => {
345-
if (!rootTag) return [];
372+
// Sub-compositions are exempt: loadExternalCompositions (packages/core/src/
373+
// runtime/compositionLoader.ts) mounts only the matched <template>/<body>
374+
// subtree, so a sub-comp's own <html>/<head>/<meta viewport> never reach
375+
// the rendering document, even when it's a full standalone document.
376+
({ rootTag, source, options }) => {
377+
if (!rootTag || options.isSubComposition) return [];
346378
const dataWidth = readAttr(rootTag.raw, "data-width");
347379
const dataHeight = readAttr(rootTag.raw, "data-height");
348380
if (!dataWidth || !dataHeight) return [];
349381

350-
const mismatches = findScaffoldSizeMismatches(source, dataWidth, dataHeight);
351-
if (mismatches.length === 0) return [];
382+
const drift = describeRootDimensionsDrift(source, dataWidth, dataHeight);
383+
if (!drift) return [];
352384

353385
return [
354386
{
355387
code: "root_dimensions_mismatch",
356388
severity: "warning",
357-
message:
358-
`Root composition declares data-width="${dataWidth}" data-height="${dataHeight}", ` +
359-
`but ${mismatches.join(" and ")}. The scaffolded body clips the composition at its ` +
360-
`old size.`,
389+
message: drift.message,
361390
elementId: readAttr(rootTag.raw, "id") || undefined,
362-
fixHint:
363-
"update html/body CSS and the meta viewport to match, or scaffold with `hyperframes init --resolution portrait`",
391+
fixHint: drift.fixHint,
364392
snippet: truncateSnippet(rootTag.raw),
365393
},
366394
];
Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
import { describe, expect, it } from "vitest";
2+
import {
3+
HTML_BODY_CSS_HEIGHT_FIRST_RE,
4+
HTML_BODY_CSS_WIDTH_FIRST_RE,
5+
VIEWPORT_META_SIZE_RE,
6+
} from "./canvasScaffoldPatterns.js";
7+
8+
// Both callers key off group numbers: @hyperframes/lint's
9+
// root_dimensions_mismatch reads the digits, @hyperframes/cli's
10+
// applyResolutionPreset substitutes `$1<new>$3<new>` to keep the text around
11+
// them. Pin the layout here so neither can renumber against the other.
12+
const CASES = [
13+
{
14+
name: "HTML_BODY_CSS_WIDTH_FIRST_RE",
15+
re: HTML_BODY_CSS_WIDTH_FIRST_RE,
16+
source: "html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; }",
17+
digits: ["1920", "1080"],
18+
replacement: "$13840px$32160px",
19+
replaced: "html, body { margin: 0; width: 3840px; height: 2160px; overflow: hidden; }",
20+
},
21+
{
22+
name: "HTML_BODY_CSS_HEIGHT_FIRST_RE",
23+
re: HTML_BODY_CSS_HEIGHT_FIRST_RE,
24+
source: "html, body { margin: 0; height: 1080px; width: 1920px; overflow: hidden; }",
25+
digits: ["1080", "1920"],
26+
replacement: "$12160px$33840px",
27+
replaced: "html, body { margin: 0; height: 2160px; width: 3840px; overflow: hidden; }",
28+
},
29+
{
30+
name: "VIEWPORT_META_SIZE_RE",
31+
re: VIEWPORT_META_SIZE_RE,
32+
source: '<meta name="viewport" content="width=1920, height=1080" />',
33+
digits: ["1920", "1080"],
34+
replacement: "$13840$32160",
35+
replaced: '<meta name="viewport" content="width=3840, height=2160" />',
36+
},
37+
];
38+
39+
describe("canvas scaffold patterns", () => {
40+
it.each(CASES)("$name exposes the two dimensions as groups 2 and 4", ({ re, source, digits }) => {
41+
const match = source.match(re);
42+
expect(match).not.toBeNull();
43+
expect(match?.slice(1)).toHaveLength(4);
44+
expect([match?.[2], match?.[4]]).toEqual(digits);
45+
});
46+
47+
it.each(CASES)(
48+
"$name replaces both dimensions in place, leaving the rest untouched",
49+
({ re, source, replacement, replaced }) => {
50+
expect(source.replace(re, replacement)).toBe(replaced);
51+
},
52+
);
53+
});
Lines changed: 8 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,16 @@
11
/**
2-
* Where a scaffolded project's canvas resolution lives besides the composition
3-
* root's own `data-width`/`data-height`: the inline `html, body { width;
4-
* height }` CSS block and the `<meta name="viewport">` `content` attribute.
5-
* `@hyperframes/cli`'s `applyResolutionPreset` rewrites those same two places
6-
* when a project scaffolds with `--resolution`, but keeps its own
7-
* prefix-capturing regexes for that replace — these are a separate read-only
8-
* definition of the same locations, not the literal patterns it uses.
9-
*
10-
* Lives in `@hyperframes/parsers` rather than `@hyperframes/cli` because
11-
* `@hyperframes/lint` cannot depend on `cli` (`cli` depends on `lint`, not the
12-
* reverse), and `parsers` is a dependency both already share.
2+
* Where a scaffolded project's canvas resolution lives besides the root's own
3+
* data-width/data-height: the html/body CSS size and the meta viewport content.
134
*/
145

15-
/** Matches `html, body { ...width: <n>px... height: <n>px... }`. */
6+
/** html/body CSS, width first. Groups 1/3 are the surrounding text, 2/4 the digits. */
167
export const HTML_BODY_CSS_WIDTH_FIRST_RE =
17-
/html\s*,\s*body\s*\{[^}]*?width:\s*(\d+)px[^}]*?height:\s*(\d+)px/i;
8+
/(html\s*,\s*body\s*\{[^}]*?width:\s*)(\d+)px([^}]*?height:\s*)(\d+)px/i;
189

19-
/** Matches the same block with height authored before width. */
10+
/** Same block, height authored first. */
2011
export const HTML_BODY_CSS_HEIGHT_FIRST_RE =
21-
/html\s*,\s*body\s*\{[^}]*?height:\s*(\d+)px[^}]*?width:\s*(\d+)px/i;
12+
/(html\s*,\s*body\s*\{[^}]*?height:\s*)(\d+)px([^}]*?width:\s*)(\d+)px/i;
2213

23-
/** Matches `<meta ... name="viewport" ... content="width=<n>, height=<n>">`. */
14+
/** Viewport meta content. Shared by lint (reads groups 2/4) and cli (replaces via 1/3). */
2415
export const VIEWPORT_META_SIZE_RE =
25-
/<meta[^>]*name=["']viewport["'][^>]*content=["']width=(\d+),\s*height=(\d+)/i;
16+
/(<meta[^>]*name=["']viewport["'][^>]*content=["']width=)(\d+)(,\s*height=)(\d+)/i;

0 commit comments

Comments
 (0)