Skip to content

Commit 201c829

Browse files
feat(lint): flag a canvas-level CSS zoom that rescales a fixed frame (#4412)
* feat(lint): flag a canvas-level CSS zoom that rescales a fixed frame The capture frame is sized from the root's data-width/data-height, which are layout pixels. CSS `zoom` on the canvas itself -- the composition root, or html/body above it -- rescales the painted content inside that frame without changing the frame, so the two disagree. Measured at 0.8.71 on an 800x400 composition holding two 100x100 boxes at left:100 and left:600, rendered to a PNG sequence with the boxes located by colour: root zoom:0.5 canvas stays 800x400; boxes paint at (50,25) and (300,25) at 50x50 -- the composition occupies the top-left quarter and the rest of every frame is dead space. root zoom:2 canvas stays 800x400; the left:100 box paints at (200,100) at 200x200, and the left:600 box renders ZERO PIXELS. It is inside the declared composition and absent from the output, and nothing in lint, check or the render log says so. A `zoom` on a DESCENDANT is deliberately not flagged. Measured in the same run: a child at left:100 with zoom:2 paints at (200,100) at 200x200, which is exactly what CSS `zoom` specifies. It is honoured, not ignored, so flagging every `zoom` would be flagging correct authoring. The `(?<![\w-])` lookbehind on the declaration pattern is load-bearing: `--zoom: 2` and `--panel-zoom: 0.5` are author variables, and a plain \b boundary flags both. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * style(lint): format to the repo's 100-column width `oxfmt --check` is a CI gate and these lines exceeded the repo's 100-column printWidth. Formatting only: verified whitespace- and trailing-comma-identical to the previous revision, with the comparison shown to detect a real change. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * fix(lint): satisfy noUncheckedIndexedAccess in the zoom rule Two strictness failures under the package's `noUncheckedIndexedAccess` + `strict`, both mine, both breaking `@hyperframes/core`'s build (and every job downstream of it): - `hits[0]` is `T | undefined`, and a preceding `hits.length === 0` check does not narrow it. Guard on the element instead of the length. - The local `hits` type declared `snippet: string`, stricter than `truncateSnippet`, which returns `string | undefined` — it returns undefined for an empty normalised input, and `Finding.snippet` is optional for exactly that reason. Mirrored that contract rather than coercing with `?? ""`, so an absent snippet stays absent instead of becoming "". Reproduced both in isolation against the real signatures before fixing, and confirmed each mutation reproduces the original error verbatim. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * refactor(lint): split canvas-zoom collection by source The `Fallow audit` gate flagged the rule's callback as critical: `fallow/high-crap-score`, CRAP 116.3 against a threshold of 30, cyclomatic 21. That is a fair reading — the callback collected hits from two unrelated sources and then built the finding, all inline. Split the collection into named functions by SOURCE (`inlineCanvasZoomHits`, `stylesheetCanvasZoomHits`, composed by `canvasZoomHits`), leaving the callback to resolve the first hit and word the finding. Decision points in the callback go 21 -> 7. Behaviour-preserving, and measured rather than asserted: both revisions were executed against 16 inputs covering inline/<html>/<body>, stylesheet selectors, comma lists, at-rules, comments, `!important`, class-matched roots, multiple style blocks, and the inline-before-stylesheet precedence. Output is identical on all 16, and the comparison was shown to detect a difference by swapping the concatenation order, which diverges on exactly the precedence case. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> * refactor(lint): split the stylesheet zoom walk into selector, rule, walk The first split took `Fallow audit` from critical (CRAP 116.3, cyclomatic 21) to minor (37.1, cyclomatic 11) — right direction, still over the threshold of 30. CRAP weights complexity against COVERAGE, and I cannot measure coverage on this machine, so rather than tune to the margin this splits the stylesheet walk into the three things it was doing: find the first canvas-targeting selector in a comma list (`firstCanvasSelector`), turn one CSS rule into at most one hit (`canvasZoomInRule`), and walk the rules. No function in the rule now exceeds 6 decision points, which clears the threshold at any plausible coverage rather than at the measured one. `firstCanvasSelector` returning the first match preserves the previous `break` exactly: one hit per rule, not one per selector. Behaviour re-verified against the ORIGINAL revision of this branch — identical on all 16 inputs, with the comparison shown to detect a real difference by dropping the `targetsCanvasRoot` guard, which diverges on two cases. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
1 parent 9d48369 commit 201c829

2 files changed

Lines changed: 324 additions & 0 deletions

File tree

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

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2180,4 +2180,121 @@ describe("composition rules", () => {
21802180
expect(finding?.message).toMatch(/25 elements/);
21812181
});
21822182
});
2183+
2184+
// root_zoom_rescales_a_fixed_canvas — measured at 0.8.71 on an 800x400
2185+
// composition: root zoom:2 renders a left:600 box at ZERO pixels (scaled to
2186+
// x=1200, outside a frame still 800 wide); root zoom:0.5 paints the whole
2187+
// composition into the top-left quarter. A zoom on a DESCENDANT is honoured
2188+
// exactly as CSS specifies and must stay silent.
2189+
describe("root_zoom_rescales_a_fixed_canvas", () => {
2190+
const codes = (r: { findings: Array<{ code: string }> }) => r.findings.map((f) => f.code);
2191+
2192+
it("flags a rescaling zoom on the composition root", async () => {
2193+
const result = await lintHyperframeHtml(`<!doctype html><html><head><style>
2194+
#root { width: 800px; height: 400px; zoom: 2; }
2195+
</style></head><body>
2196+
<div id="root" data-composition-id="main" data-width="800" data-height="400" data-duration="5"></div>
2197+
</body></html>`);
2198+
2199+
expect(codes(result)).toContain("root_zoom_rescales_a_fixed_canvas");
2200+
const finding = result.findings.find((f) => f.code === "root_zoom_rescales_a_fixed_canvas");
2201+
expect(finding?.severity).toBe("error");
2202+
expect(finding?.message).toContain("zero pixels");
2203+
});
2204+
2205+
it("describes the shrinking case as dead space, not clipping", async () => {
2206+
const result = await lintHyperframeHtml(`<!doctype html><html><head><style>
2207+
#root { zoom: 0.5; }
2208+
</style></head><body>
2209+
<div id="root" data-composition-id="main" data-width="800" data-height="400" data-duration="5"></div>
2210+
</body></html>`);
2211+
2212+
const finding = result.findings.find((f) => f.code === "root_zoom_rescales_a_fixed_canvas");
2213+
expect(finding?.message).toContain("dead space");
2214+
expect(finding?.message).not.toContain("zero pixels");
2215+
});
2216+
2217+
it("flags zoom on html and on body, which scale the canvas from above", async () => {
2218+
for (const selector of ["html", "body"]) {
2219+
const result = await lintHyperframeHtml(`<!doctype html><html><head><style>
2220+
${selector} { zoom: 1.5; }
2221+
</style></head><body>
2222+
<div id="root" data-composition-id="main" data-width="800" data-height="400" data-duration="5"></div>
2223+
</body></html>`);
2224+
expect(codes(result)).toContain("root_zoom_rescales_a_fixed_canvas");
2225+
}
2226+
});
2227+
2228+
it("flags an inline zoom on the root", async () => {
2229+
const result = await lintHyperframeHtml(`<!doctype html><html><body>
2230+
<div id="root" style="zoom: 2" data-composition-id="main" data-width="800" data-height="400" data-duration="5"></div>
2231+
</body></html>`);
2232+
2233+
expect(codes(result)).toContain("root_zoom_rescales_a_fixed_canvas");
2234+
});
2235+
2236+
it("stays silent on a zoom applied to a descendant", async () => {
2237+
const result = await lintHyperframeHtml(`<!doctype html><html><head><style>
2238+
.badge { zoom: 2; }
2239+
</style></head><body>
2240+
<div id="root" data-composition-id="main" data-width="800" data-height="400" data-duration="5">
2241+
<div class="badge"></div>
2242+
</div>
2243+
</body></html>`);
2244+
2245+
expect(codes(result)).not.toContain("root_zoom_rescales_a_fixed_canvas");
2246+
});
2247+
2248+
it("stays silent on identity zoom values", async () => {
2249+
for (const value of ["1", "1.0", "100%", "normal", "unset", "initial"]) {
2250+
const result = await lintHyperframeHtml(`<!doctype html><html><head><style>
2251+
#root { zoom: ${value}; }
2252+
</style></head><body>
2253+
<div id="root" data-composition-id="main" data-width="800" data-height="400" data-duration="5"></div>
2254+
</body></html>`);
2255+
expect(codes(result)).not.toContain("root_zoom_rescales_a_fixed_canvas");
2256+
}
2257+
});
2258+
2259+
// A custom property is not the CSS `zoom` property. A plain \b boundary
2260+
// flags both, which is the same trap the negative-z-index rule hit.
2261+
it("stays silent on custom properties whose name ends in zoom", async () => {
2262+
const result = await lintHyperframeHtml(`<!doctype html><html><head><style>
2263+
#root { --zoom: 2; --panel-zoom: 0.5; }
2264+
</style></head><body>
2265+
<div id="root" data-composition-id="main" data-width="800" data-height="400" data-duration="5"></div>
2266+
</body></html>`);
2267+
2268+
expect(codes(result)).not.toContain("root_zoom_rescales_a_fixed_canvas");
2269+
});
2270+
2271+
it("reads through !important", async () => {
2272+
const identity = await lintHyperframeHtml(`<!doctype html><html><head><style>
2273+
#root { zoom: 1 !important; }
2274+
</style></head><body>
2275+
<div id="root" data-composition-id="main" data-width="800" data-height="400" data-duration="5"></div>
2276+
</body></html>`);
2277+
expect(codes(identity)).not.toContain("root_zoom_rescales_a_fixed_canvas");
2278+
2279+
const rescaling = await lintHyperframeHtml(`<!doctype html><html><head><style>
2280+
#root { zoom: 2 !important; }
2281+
</style></head><body>
2282+
<div id="root" data-composition-id="main" data-width="800" data-height="400" data-duration="5"></div>
2283+
</body></html>`);
2284+
const finding = rescaling.findings.find(
2285+
(f) => f.code === "root_zoom_rescales_a_fixed_canvas",
2286+
);
2287+
expect(finding?.message).toContain("zoom: 2`");
2288+
});
2289+
2290+
it("ignores a zoom inside a CSS comment", async () => {
2291+
const result = await lintHyperframeHtml(`<!doctype html><html><head><style>
2292+
#root { /* zoom: 2; */ width: 800px; }
2293+
</style></head><body>
2294+
<div id="root" data-composition-id="main" data-width="800" data-height="400" data-duration="5"></div>
2295+
</body></html>`);
2296+
2297+
expect(codes(result)).not.toContain("root_zoom_rescales_a_fixed_canvas");
2298+
});
2299+
});
21832300
});

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

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,155 @@ function rootClassStyledSelectors(styles: ExtractedBlock[], rootClasses: string[
205205
return offenders;
206206
}
207207

208+
// A `zoom` declaration and its value. The lookbehind keeps custom properties
209+
// out: `--panel-zoom: 2` and `--zoom: 0.5` are author variables, not the CSS
210+
// `zoom` property, and a plain \b would flag both.
211+
const ZOOM_DECLARATION = /(?<![\w-])zoom\s*:\s*([^;}]+)/gi;
212+
213+
/** zoom values that leave the canvas alone; anything else rescales it. */
214+
function isIdentityZoom(rawValue: string): boolean {
215+
const value = rawValue
216+
.trim()
217+
.replace(/!\s*important\s*$/i, "")
218+
.trim()
219+
.toLowerCase();
220+
return (
221+
value === "" ||
222+
value === "normal" ||
223+
value === "unset" ||
224+
value === "initial" ||
225+
value === "revert" ||
226+
value === "1" ||
227+
value === "1.0" ||
228+
value === "100%"
229+
);
230+
}
231+
232+
/** First rescaling `zoom` value in a declaration block, or null. */
233+
function firstRescalingZoom(css: string): string | null {
234+
ZOOM_DECLARATION.lastIndex = 0;
235+
let match: RegExpExecArray | null;
236+
while ((match = ZOOM_DECLARATION.exec(css)) !== null) {
237+
const value = (match[1] ?? "").trim();
238+
if (!isIdentityZoom(value)) return value.replace(/!\s*important\s*$/i, "").trim();
239+
}
240+
return null;
241+
}
242+
243+
/**
244+
* Does this selector's leftmost compound target the canvas itself — the
245+
* composition root, or an ancestor of it? A zoom on a DESCENDANT is ordinary
246+
* authoring and renders exactly as authored; only the canvas-level one
247+
* desynchronises painted content from the declared frame.
248+
*/
249+
function targetsCanvasRoot(
250+
selector: string,
251+
rootId: string | null,
252+
rootClasses: string[],
253+
): boolean {
254+
const leftmost = selector.trim().split(/[\s>+~]+/)[0] ?? "";
255+
const bare = leftmost.toLowerCase();
256+
if (bare === "html" || bare === "body" || bare === ":root" || bare === "*") return true;
257+
if (rootId && leftmostCompoundId(selector) === rootId) return true;
258+
return leftmostCompoundClasses(selector).some((cls) => rootClasses.includes(cls));
259+
}
260+
261+
/**
262+
* A rescaling canvas-level `zoom`, with where it was declared. Collected in
263+
* priority order — inline on the root, then <html>, then <body>, then
264+
* stylesheet rules — because the rule reports the FIRST one it finds.
265+
*
266+
* `truncateSnippet` returns undefined for an empty normalised input, and
267+
* `Finding.snippet` is optional for exactly that reason: an absent snippet is
268+
* absent, not "". This mirrors that contract rather than coercing it away.
269+
*/
270+
type CanvasZoomHit = { where: string; value: string; snippet: string | undefined };
271+
272+
function inlineCanvasZoomHits(rootTag: OpenTag, tags: OpenTag[]): CanvasZoomHit[] {
273+
const hits: CanvasZoomHit[] = [];
274+
const htmlTag = findHtmlTag(tags);
275+
const bodyTag = tags.find((tag) => tag.name.toLowerCase() === "body");
276+
for (const [label, tag] of [
277+
["the root element's inline style", rootTag],
278+
["<html>'s inline style", htmlTag],
279+
["<body>'s inline style", bodyTag],
280+
] as const) {
281+
if (!tag) continue;
282+
const inline = readAttr(tag.raw, "style");
283+
const value = inline ? firstRescalingZoom(inline) : null;
284+
if (value) hits.push({ where: label, value, snippet: truncateSnippet(tag.raw) });
285+
}
286+
return hits;
287+
}
288+
289+
/**
290+
* The first selector in a comma list that targets the canvas, or null. Only the
291+
* first matters: the rest of the list describes the same declaration block, so
292+
* one hit per RULE is what the caller wants.
293+
*/
294+
function firstCanvasSelector(
295+
header: string,
296+
rootId: string | null,
297+
rootClasses: string[],
298+
): string | null {
299+
for (const selector of header.split(",")) {
300+
const trimmed = selector.trim();
301+
if (trimmed && targetsCanvasRoot(trimmed, rootId, rootClasses)) return trimmed;
302+
}
303+
return null;
304+
}
305+
306+
/** A canvas-level rescaling `zoom` declared by one CSS rule, or null. */
307+
function canvasZoomInRule(
308+
header: string,
309+
body: string,
310+
rootId: string | null,
311+
rootClasses: string[],
312+
): CanvasZoomHit | null {
313+
const trimmedHeader = header.trim();
314+
// An at-rule's "header" is `@media ...`, not a selector list.
315+
if (!trimmedHeader || trimmedHeader.startsWith("@")) return null;
316+
const value = firstRescalingZoom(body);
317+
if (!value) return null;
318+
const selector = firstCanvasSelector(trimmedHeader, rootId, rootClasses);
319+
if (!selector) return null;
320+
return {
321+
where: `\`${selector}\``,
322+
value,
323+
snippet: truncateSnippet(`${selector} { zoom: ${value} }`),
324+
};
325+
}
326+
327+
function stylesheetCanvasZoomHits(
328+
styles: ExtractedBlock[],
329+
rootId: string | null,
330+
rootClasses: string[],
331+
): CanvasZoomHit[] {
332+
const hits: CanvasZoomHit[] = [];
333+
for (const style of styles) {
334+
const ruleWithBody = /([^{}]+)\{([^{}]*)\}/g;
335+
let match: RegExpExecArray | null;
336+
while ((match = ruleWithBody.exec(stripCssComments(style.content))) !== null) {
337+
const hit = canvasZoomInRule(match[1] ?? "", match[2] ?? "", rootId, rootClasses);
338+
if (hit) hits.push(hit);
339+
}
340+
}
341+
return hits;
342+
}
343+
344+
function canvasZoomHits(
345+
rootTag: OpenTag,
346+
tags: OpenTag[],
347+
styles: ExtractedBlock[],
348+
rootId: string | null,
349+
rootClasses: string[],
350+
): CanvasZoomHit[] {
351+
return [
352+
...inlineCanvasZoomHits(rootTag, tags),
353+
...stylesheetCanvasZoomHits(styles, rootId, rootClasses),
354+
];
355+
}
356+
208357
/** Declared variable ids from an <html> tag's raw text; null when the JSON is unparseable. */
209358
function collectDeclaredVariableIds(htmlTagRaw: string): Set<string> | null {
210359
const declared = new Set<string>();
@@ -1229,6 +1378,64 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
12291378
},
12301379
];
12311380
},
1381+
1382+
// root_zoom_rescales_a_fixed_canvas
1383+
//
1384+
// The capture frame is sized from the root's data-width/data-height, which are
1385+
// LAYOUT pixels. CSS `zoom` on the canvas itself (the root, or html/body above
1386+
// it) rescales the painted content inside that frame without changing the frame,
1387+
// so the two disagree and the author gets neither of the two things they might
1388+
// have meant.
1389+
//
1390+
// Measured at 0.8.71 on an 800x400 composition holding two 100x100 boxes at
1391+
// left:100 and left:600, rendered to a PNG sequence and the boxes located by
1392+
// colour:
1393+
//
1394+
// root zoom:0.5 canvas stays 800x400; boxes paint at (50,25) and (300,25),
1395+
// each 50x50 -- the composition occupies the top-left quarter
1396+
// and the rest of every frame is dead space.
1397+
// root zoom:2 canvas stays 800x400; the left:100 box paints at (200,100)
1398+
// at 200x200, and the left:600 box renders ZERO PIXELS --
1399+
// scaled to x=1200, outside a frame that is still 800 wide.
1400+
//
1401+
// The second case is the one worth an error: content that is inside the declared
1402+
// composition silently does not exist in the output, with nothing else in lint,
1403+
// check or the render log naming it.
1404+
//
1405+
// Deliberately NOT flagged: `zoom` on a descendant. Measured in the same run --
1406+
// a child at left:100 with zoom:2 paints at (200,100) at 200x200, which is
1407+
// exactly what CSS `zoom` specifies. It is honoured, not ignored, so a rule that
1408+
// fired on every `zoom` would be flagging correct authoring.
1409+
({ rootTag, tags, styles }) => {
1410+
if (!rootTag) return [];
1411+
const rootId = readAttr(rootTag.raw, "id");
1412+
const rootClasses = (readAttr(rootTag.raw, "class") || "").split(/\s+/).filter(Boolean);
1413+
const hits = canvasZoomHits(rootTag, tags, styles, rootId, rootClasses);
1414+
1415+
// `noUncheckedIndexedAccess` makes hits[0] `T | undefined`, and a length
1416+
// check does not narrow it — guard on the element itself.
1417+
const hit = hits[0];
1418+
if (!hit) return [];
1419+
const enlarging =
1420+
!hit.value.startsWith("-") && parseFloat(hit.value) > (hit.value.includes("%") ? 100 : 1);
1421+
return [
1422+
{
1423+
code: "root_zoom_rescales_a_fixed_canvas",
1424+
severity: "error",
1425+
message:
1426+
`\`zoom: ${hit.value}\` on ${hit.where} rescales the painted composition inside a frame that does not rescale with it. ` +
1427+
`The capture frame is sized from the root's data-width/data-height in LAYOUT pixels, and \`zoom\` changes only what is painted inside it, so ` +
1428+
(enlarging
1429+
? `content past the frame's edge renders zero pixels — it is inside the declared composition and absent from the output, with nothing else reporting it.`
1430+
: `the composition paints into part of the frame and the remainder of every output frame is dead space.`),
1431+
fixHint:
1432+
`Author the composition at its real size — set data-width/data-height (and the root's width/height) to the dimensions you want — and drop the canvas-level \`zoom\`. ` +
1433+
`To scale the OUTPUT without changing layout, pass \`--output-resolution\` to render, which supersamples. ` +
1434+
`\`zoom\` on descendants is fine and is not flagged: it is honoured exactly as specified.`,
1435+
snippet: hit.snippet,
1436+
},
1437+
];
1438+
},
12321439
];
12331440

12341441
const CLIP_MEDIA_TAGS = new Set<string>(["img", "video", "audio"]);

0 commit comments

Comments
 (0)