feat(cli): check warns when text leaves the 9:16 social safe areas (#7680)

* feat(cli): check warns when text leaves the 9:16 social safe areas

* feat(core): safe areas owned by core; check adds --safe-zone standard

* style(cli): format

* refactor(core): name the safe-area band fields

* fix(cli): defects outrank safe-zone warnings at the issue cap

* style(cli): format

* test: read the safe-box constants from core
This commit is contained in:
Miguel Ángel
2026-11-14 02:00:15 +00:00
committed by GitHub
parent f7b49f1207
commit 45882027bd
16 changed files with 466 additions and 54 deletions
+11
View File
@@ -1288,6 +1288,7 @@ cover every finding from the full check.
| `--no-craft` | Skip the craft pass (dead stretches, unread lines, silent film), the longest part of a full check. The report marks it skipped. Use it for a render preflight; keep it on for the full check before a release. |
| `--strict` | Exit non-zero on warnings too (default: errors only) |
| `--caption-zone "<x0=..;y0=..;x1=..;y1=..>"` | Opt-in band gate. Flags a text element's DOM box that overlaps the fractional band. Optional `severity` and `seek`. |
| `--safe-zone <tiktok\|reels\|shorts\|standard\|off>` | Warn when text, captions included, leaves a safe area: a platform's on 9:16 compositions (default: all three), or `standard` title-safe margins (10% from each edge) on any frame. Never fails `--strict` |
| `--frame-check` | Opt-in out-of-frame detection for `img`, `svg`, `video`, and `canvas` |
| `--layout` | Layout knobs, currently `proseCoverageFloor=0.05` (0–1, default 0.15) |
| `--browser-gpu` / `--no-browser-gpu` | Hardware GPU capture, or deterministic SwiftShader (default: auto-detect) |
@@ -1424,6 +1425,16 @@ For deliberate lower-third copy under `--caption-zone`, use
nothing else — overflow, overlap, occlusion, and contrast still apply. Put it on
the narrowest wrapper that owns the band copy.
On a 9:16 composition, check samples every text block and caption line against the
areas TikTok, Instagram Reels and YouTube Shorts leave clear of their buttons and
captions. Each block that leaves one is an `outside_safe_zone` warning naming the
platforms and the edges it crosses, at the first time it is seen. The areas are
reference guides from each platform's vertical ad specs: TikTok 720x1280 with a
stepped right edge, Reels with the bottom 35%, top 14% and 6% sides excluded, Shorts
1080x1920 excluding 48px left, 192px right, 288px top and 672px bottom. `--safe-zone standard` checks the title-safe margins instead, 10% in from each
edge, on any aspect ratio. Mark text that may sit outside them with
`data-layout-allow-safe-zone`.
#### Verify motion, not just layout
Layout sampling cannot catch a render-≠-preview bug: an entrance the seek lands
+151 -5
View File
@@ -22,7 +22,7 @@ vi.mock("../telemetry/events.js", () => ({
}));
import { contrastRatio, parseColorRGBA } from "./contrast-bg.js";
import { createCheckCommand, parseCheckRange } from "./check.js";
import { createCheckCommand, parseCheckRange, parseSafeZone } from "./check.js";
import { assertKnownFlags } from "../utils/reject-unknown-flags.js";
import { readConfig } from "../telemetry/config.js";
import {
@@ -234,7 +234,7 @@ function fakeDriver(overrides: Partial<CheckAuditDriver> = {}): CheckAuditDriver
}
interface GeometryFixture {
kind: "text" | "media";
kind: "text" | "media" | "block";
tag: string;
text: string;
selector: string;
@@ -1035,6 +1035,7 @@ it("flags text whose DOM box overlaps the caption band at the default end seek",
expect(collectGeometryCandidates).toHaveBeenCalledWith(10, {
text: true,
media: false,
blocks: false,
tolerance: 2,
});
expect(report.layout.samples).toEqual([5, 10]);
@@ -1210,6 +1211,7 @@ it("checks media overflow at the default midpoint and applies warning severity",
expect(collectGeometryCandidates).toHaveBeenCalledWith(5, {
text: false,
media: true,
blocks: false,
tolerance: 2,
});
expect(report.layout.findings[0]).toMatchObject({
@@ -1245,9 +1247,9 @@ it("converts progress seeks to time, gates each collector, and keeps distinct ca
expect(report.layout.samples).toEqual([2, 4, 6]);
expect(collectGeometryCandidates.mock.calls).toEqual([
[2, { text: true, media: false, tolerance: 2 }],
[4, { text: false, media: true, tolerance: 2 }],
[6, { text: true, media: false, tolerance: 2 }],
[2, { text: true, media: false, blocks: false, tolerance: 2 }],
[4, { text: false, media: true, blocks: false, tolerance: 2 }],
[6, { text: true, media: false, blocks: false, tolerance: 2 }],
]);
expect(report.layout.findings).toEqual([
expect.objectContaining({
@@ -1289,6 +1291,150 @@ it("does not collect or emit opt-in geometry findings when both flags are off",
expect(JSON.stringify(report)).not.toContain("frame_out_of_frame");
});
describe("social safe zones", () => {
const portrait = { width: 1080, height: 1920 };
const block = (selector: string, text: string, rect: LayoutRect, time: number) =>
geometryCandidate({ kind: "block", tag: "p", text, selector, rect, time });
// A caption in the bottom 30% and a title centred in the upper half.
const captionAndTitle = (time: number) => [
block("#caption", "Follow for part two", fixtureRect(140, 1400, 800, 120), time),
block("#title", "Centred title", fixtureRect(216, 600, 648, 120), time),
];
async function safeZoneScenario(
candidates: (time: number) => ReturnType<typeof geometryCandidate>[],
options: Partial<CheckOptions> = {},
canvas = portrait,
) {
const collectGeometryCandidates = vi.fn(async (time: number) => candidates(time));
const { report } = await runScenario(
fakeDriver({
getDuration: vi.fn(async () => 4),
getCanvas: vi.fn(async () => canvas),
collectGeometryCandidates,
}),
{ samples: 2, contrast: false, safeZones: ["tiktok", "reels", "shorts"], ...options },
);
return { report, collectGeometryCandidates };
}
it("warns once, at the first time, for a caption below every platform's safe area", async () => {
const { report, collectGeometryCandidates } = await safeZoneScenario(captionAndTitle, {
strict: true,
});
expect(collectGeometryCandidates).toHaveBeenCalledWith(
expect.any(Number),
expect.objectContaining({ blocks: true }),
);
expect(report.layout.findings).toEqual([
expect.objectContaining({
code: "outside_safe_zone",
severity: "warning",
selector: "#caption",
time: report.layout.samples[0],
message:
'<p> "Follow for part two" is outside the safe area: TikTok (bottom edge), Instagram Reels (bottom edge), YouTube Shorts (bottom edge).',
}),
]);
expect(report.ok).toBe(true);
});
it("follows TikTok's stepped right edge", async () => {
const { report } = await safeZoneScenario((time) => [
block("#under-step", "Under the buttons", fixtureRect(756, 960, 108, 96), time),
block("#above-step", "Above the buttons", fixtureRect(756, 384, 108, 96), time),
]);
expect(report.layout.findings).toEqual([
expect.objectContaining({
selector: "#under-step",
message: '<p> "Under the buttons" is outside the safe area: TikTok (right edge).',
}),
]);
});
it("narrows to one platform", async () => {
const { report } = await safeZoneScenario(captionAndTitle, { safeZones: ["shorts"] });
expect(report.layout.findings.map((finding) => finding.message)).toEqual([
'<p> "Follow for part two" is outside the safe area: YouTube Shorts (bottom edge).',
]);
});
it("skips text marked data-layout-allow-safe-zone", async () => {
const { report } = await safeZoneScenario((time) => [
geometryCandidate({
kind: "block",
tag: "p",
text: "Sticker",
selector: "#sticker",
rect: fixtureRect(140, 1400, 800, 120),
time,
dataAttributes: { "data-layout-allow-safe-zone": "" },
}),
]);
expect(report.layout.findings).toEqual([]);
});
it("reports nothing when off or when the frame is not 9:16", async () => {
const off = await safeZoneScenario(captionAndTitle, { safeZones: [] });
const landscape = await safeZoneScenario(captionAndTitle, {}, { width: 1920, height: 1080 });
expect(off.collectGeometryCandidates).not.toHaveBeenCalled();
expect(landscape.collectGeometryCandidates).not.toHaveBeenCalled();
expect(off.report.layout.findings).toEqual([]);
expect(landscape.report.layout.findings).toEqual([]);
});
it("never lets a safe-zone warning push a defect warning past --max-issues", async () => {
const { report } = await safeZoneScenario(
(time) => [
...captionAndTitle(time),
geometryCandidate({
kind: "text",
tag: "p",
text: "Lower third",
selector: "#lower-third",
rect: fixtureRect(140, 1700, 800, 80),
time,
}),
],
{ maxIssues: 1, strict: true, captionZone: { x0: 0, y0: 0.85, x1: 1, y1: 1 } },
);
expect(report.layout.findings).toEqual([
expect.objectContaining({ code: "caption_zone_collision", selector: "#lower-third" }),
]);
expect(report.ok).toBe(false);
});
it("checks title-safe margins on any frame when asked for standard", async () => {
const landscape = { width: 1920, height: 1080 };
const { report } = await safeZoneScenario(
(time) => [
block("#edge-title", "Near the edge", fixtureRect(96, 400, 600, 100), time),
block("#centred", "Centred", fixtureRect(660, 490, 600, 100), time),
],
{ safeZones: ["standard"] },
landscape,
);
expect(report.layout.findings.map((finding) => finding.message)).toEqual([
'<p> "Near the edge" is outside the safe area: title-safe margins (left edge).',
]);
});
it("parses --safe-zone", () => {
expect(parseSafeZone(undefined)).toEqual(["tiktok", "reels", "shorts"]);
expect(parseSafeZone("reels")).toEqual(["reels"]);
expect(parseSafeZone("standard")).toEqual(["standard"]);
expect(parseSafeZone("off")).toEqual([]);
expect(() => parseSafeZone("instagram")).toThrow(CliUsageError);
});
});
it("computes caption bands from a portrait composition viewport", async () => {
const viewport = resolveCompositionViewportFromHtml(
'<div data-composition-id="portrait" data-width="1080" data-height="1920"></div>',
+17
View File
@@ -39,6 +39,8 @@ import {
} from "../utils/checkPipeline.js";
import type { CaptionZoneOptions, FrameCheckOptions, LayoutOptions } from "../utils/checkTypes.js";
import { resolveLocalBrowserGpuMode } from "../browser/gpuPolicy.js";
import { SOCIAL_SAFE_AREA_NAMES } from "@hyperframes/core/safe-areas";
import type { SafeZone } from "../utils/safeZones.js";
import { preResolveHostileMediaProxies, type PreparedMediaFile } from "../utils/checkBrowser.js";
import { parseTimeoutMs } from "../utils/timeoutArg.js";
import { failureMessage, jsonFailure } from "../utils/jsonError.js";
@@ -297,6 +299,11 @@ const CHECK_COMMAND_ARGS = {
description:
'Caption band "x0=0;y0=.82;x1=1;y1=1[;severity=warning|error][;seek=.5,1]" (fractions 0-1; defaults: warning, seek=1)',
},
"safe-zone": {
type: "string",
description:
"Warn when text leaves a safe area: tiktok, reels or shorts on 9:16 (default: all three), standard (title-safe margins, any frame), or off",
},
"frame-check": {
type: "string",
description:
@@ -499,6 +506,7 @@ function parseCheckOptions(args: Record<string, unknown>): CheckOptions {
...(checkReview()?.findingFrames ? { findingFrames: true } : {}),
...(checkReview()?.inspect ? { inspect: true } : {}),
captionZone: parseCaptionZone(args["caption-zone"]),
safeZones: parseSafeZone(args["safe-zone"]),
frameCheck: parseFrameCheck(args["frame-check"]),
layout: parseLayout(args.layout),
autoProxy: args.proxy as boolean | undefined,
@@ -623,6 +631,15 @@ function parseNumberStrict(raw: string): number | null {
return Number.isFinite(value) ? value : null;
}
export function parseSafeZone(value: unknown): SafeZone[] {
if (value === undefined) return [...SOCIAL_SAFE_AREA_NAMES];
if (value === "off") return [];
const zone = [...SOCIAL_SAFE_AREA_NAMES, "standard" as const].find((name) => name === value);
if (!zone)
throw new CliUsageError("Invalid --safe-zone; use tiktok, reels, shorts, standard or off.");
return [zone];
}
function parseCaptionZone(value: unknown): CaptionZoneOptions | undefined {
if (value === undefined || value === null) return undefined;
const fields = parseCaptionFields(captionZoneString(value));
@@ -126,6 +126,10 @@
return !!authoredElement(element).closest("[data-layout-allow-caption-zone]");
}
function hasAllowSafeZoneFlag(element) {
return !!authoredElement(element).closest("[data-layout-allow-safe-zone]");
}
function hasTextClipOptOut(element) {
return (
hasAllowOverflowFlag(element) || authoredElement(element).hasAttribute("data-layout-bleed")
@@ -2813,10 +2817,34 @@
};
}
const CAPTION_STAGES = '[data-composition-id="captions"], .caption-layer, #caption-stage';
// One box per reading block (a caption stage counts as one), so a line split into word spans is one finding.
function addTextToBlock(blocks, block, element) {
const rect = textRectFor(element, true);
if (!rect) return;
const entry = blocks.get(block) ?? { rects: [], texts: [] };
entry.rects.push(rect);
entry.texts.push(textContentFor(element, true));
blocks.set(block, entry);
}
function blockCandidates(blocks) {
return Array.from(blocks, ([block, entry]) => ({
kind: "block",
tag: block.tagName.toLowerCase(),
text: entry.texts.join(" "),
rect: unionRects(entry.rects),
elementRect: toRect(block.getBoundingClientRect()),
...candidateAnchor(block),
}));
}
window.__hyperframesGeometryCandidates = function collectGeometryCandidates(options) {
const includeText = options?.text === true;
const includeMedia = options?.media === true;
if (!includeText && !includeMedia) return [];
const includeBlocks = options?.blocks === true;
if (!includeText && !includeMedia && !includeBlocks) return [];
const tolerance = typeof options?.tolerance === "number" ? options.tolerance : 2;
const root =
document.querySelector("[data-composition-id][data-width][data-height]") ||
@@ -2824,11 +2852,15 @@
document.body;
const rootRect = rootRectFor(root);
const candidates = [];
const blocks = new Map();
for (const element of Array.from(document.querySelectorAll("body *"))) {
if (element.closest('[data-composition-id="captions"], .caption-layer, #caption-stage')) {
continue;
}
const captionStage = element.closest(CAPTION_STAGES);
if (captionStage && !includeBlocks) continue;
if (!isVisibleElement(element, 0.05, false)) continue;
if (includeBlocks && hasOwnTextCandidate(element, true) && !hasAllowSafeZoneFlag(element)) {
addTextToBlock(blocks, captionStage || readingBlock(element, root), element);
}
if (captionStage) continue;
const elementRect = toRect(element.getBoundingClientRect());
if (includeText && hasOwnTextCandidate(element, true) && !hasAllowCaptionZoneFlag(element)) {
const rect = textRectFor(element, true);
@@ -2844,7 +2876,7 @@
);
}
}
return candidates;
return candidates.concat(blockCandidates(blocks));
};
window.__hyperframesLayoutAudit = function auditLayout(options) {
@@ -731,6 +731,36 @@ it("excludes text marked data-layout-allow-caption-zone from geometry candidates
expect(candidates.map((candidate) => candidate.selector)).toEqual(["#copy"]);
});
it("groups text into reading blocks, caption layers included, for the safe-zone check", () => {
document.body.innerHTML = `
<div id="root" data-composition-id="main" data-width="1080" data-height="1920">
<h1 id="title">Big <span id="word">title</span></h1>
<p id="sticker" data-layout-allow-safe-zone>Follow</p>
<div id="captions" class="caption-layer"><span id="w1">Hello</span><span id="w2">world</span></div>
</div>
`;
installGeometry(
{
root: rect({ left: 0, top: 0, width: 1080, height: 1920 }),
text: rect({ left: 100, top: 1500, width: 300, height: 80 }),
},
{ word: { display: "inline" } },
);
installAuditScript();
const candidates = runGeometryCandidates({
text: false,
media: false,
blocks: true,
tolerance: 2,
});
expect(candidates.map(({ kind, selector, text }) => ({ kind, selector, text }))).toEqual([
{ kind: "block", selector: "#title", text: "Big title" },
{ kind: "block", selector: "#captions", text: "Hello world" },
]);
});
it("scans body-level composition siblings and includes a media boundary root", () => {
document.body.innerHTML = `
<canvas id="boundary" data-composition-id="background" data-width="640" data-height="360"></canvas>
@@ -4160,6 +4190,7 @@ declare global {
__hyperframesGeometryCandidates?: (options: {
text: boolean;
media: boolean;
blocks?: boolean;
tolerance: number;
}) => GeometryCandidateResult[];
}
@@ -4168,6 +4199,7 @@ declare global {
function runGeometryCandidates(options: {
text: boolean;
media: boolean;
blocks?: boolean;
tolerance: number;
}): GeometryCandidateResult[] {
const collector = window.__hyperframesGeometryCandidates;
+3 -1
View File
@@ -2121,7 +2121,8 @@ function parseGeometryIdentity(
value: Record<string, unknown>,
): Pick<CheckGeometryCandidate, "kind" | "tag" | "text"> | null {
const kindValue = Reflect.get(value, "kind");
const kind = kindValue === "text" || kindValue === "media" ? kindValue : null;
const kind =
kindValue === "text" || kindValue === "media" || kindValue === "block" ? kindValue : null;
if (!kind) return null;
const tag = stringValue(value, "tag");
if (!tag) return null;
@@ -2291,6 +2292,7 @@ const LAYOUT_ISSUE_CODES: readonly LayoutIssueCode[] = [
"video_alpha_unread",
"text_not_painted",
"caption_zone_collision",
"outside_safe_zone",
"frame_out_of_frame",
"escaped_container",
"panel_out_of_canvas",
+71 -24
View File
@@ -16,6 +16,7 @@ import {
finishCheckSnapshots,
} from "./checkSnapshotDirectory.js";
import { findingAtRoot, findingElementKey, groupSampledFindings } from "./checkFindings.js";
import { safeZoneEdgesCrossed, safeZoneLabel, safeZonesFor, type SafeZone } from "./safeZones.js";
import {
MAX_FINDING_FRAME_TIMES,
selectFindingFrames,
@@ -40,6 +41,7 @@ import {
CONTENT_OVERLAP_HELD_ERROR_MS,
longestContiguousRunMs,
dedupeLayoutIssues,
isGuidanceIssue,
limitLayoutIssues,
mergeSampleTimes,
type LayoutIssue,
@@ -317,13 +319,15 @@ function geometryRequest(
time: number,
grid: SampleGrid,
options: CheckOptions,
sets: SampleSets,
): GeometryCandidateRequest | null {
const text = grid.captionSamples.includes(time);
const media = grid.frameSamples.includes(time);
if (!text && !media) return null;
const blocks = sets.safeZones.length > 0 && sets.layout.has(time);
if (!text && !media && !blocks) return null;
const configuredTolerance = options.frameCheck?.tol;
const tolerance = typeof configuredTolerance === "number" ? configuredTolerance : 2;
return { text, media, tolerance };
return { text, media, blocks, tolerance };
}
function candidateIsSized(candidate: CheckGeometryCandidate, canvas: Canvas): boolean {
@@ -385,6 +389,35 @@ function captionFinding(
};
}
function safeZoneFinding(
candidate: CheckGeometryCandidate,
zones: SafeZone[],
canvas: Canvas,
time: number,
): AnchoredLayoutIssue | null {
if (candidate.kind !== "block" || candidate.rect.width < 4 || candidate.rect.height < 4) {
return null;
}
// Backstop for mocks/non-browser sources; the browser already drops opted-out text.
if ("data-layout-allow-safe-zone" in candidate.dataAttributes) return null;
const crossed = zones.flatMap((zone) => {
const edges = safeZoneEdgesCrossed(candidate.rect, canvas, zone);
if (edges.length === 0) return [];
return [`${safeZoneLabel(zone)} (${edges.join(" and ")} edge${edges.length > 1 ? "s" : ""})`];
});
if (crossed.length === 0) return null;
const text = candidate.text.slice(0, 48);
return {
...geometryIssueAnchor(candidate, time),
code: "outside_safe_zone",
severity: "warning",
text,
message: `<${candidate.tag}> "${text}" is outside the safe area: ${crossed.join(", ")}.`,
fixHint:
"Move the text inside the safe area, or mark text meant to sit there with data-layout-allow-safe-zone.",
};
}
function maxOverflow(candidate: CheckGeometryCandidate): number {
if (!candidate.overflow) return 0;
return Math.max(
@@ -435,24 +468,20 @@ async function collectGeometryAt(
driver: CheckAuditDriver,
options: CheckOptions,
grid: SampleGrid,
sets: SampleSets,
canvas: Canvas,
time: number,
): Promise<AnchoredLayoutIssue[]> {
const request = geometryRequest(time, grid, options);
const request = geometryRequest(time, grid, options, sets);
if (!request) return [];
const candidates = await driver.collectGeometryCandidates(time, request);
const issues: AnchoredLayoutIssue[] = [];
for (const candidate of candidates) {
if (request.text) {
const finding = captionFinding(candidate, options, canvas, time);
if (finding) issues.push(finding);
}
if (request.media) {
const finding = frameFinding(candidate, options, canvas, time);
if (finding) issues.push(finding);
}
}
return issues;
return candidates
.flatMap((candidate) => [
request.blocks ? safeZoneFinding(candidate, sets.safeZones, canvas, time) : null,
request.text ? captionFinding(candidate, options, canvas, time) : null,
request.media ? frameFinding(candidate, options, canvas, time) : null,
])
.filter((finding): finding is AnchoredLayoutIssue => finding !== null);
}
function emptyGridSamples(): GridSamples {
@@ -490,6 +519,8 @@ interface SampleSets {
motion: Set<number>;
contrast: Set<number>;
canvas: Canvas | null;
/** Platforms to judge text against; empty unless the frame is 9:16. */
safeZones: SafeZone[];
}
async function collectSampleAt(
@@ -519,7 +550,7 @@ async function collectSampleAt(
collected.indicatorFrames.push(await driver.collectOffPivotRotationSample(time));
}
if (sets.canvas) {
const geometryIssues = await collectGeometryAt(driver, options, grid, sets.canvas, time);
const geometryIssues = await collectGeometryAt(driver, options, grid, sets, sets.canvas, time);
collected.layoutIssues.push(...geometryIssues);
issuesAtTime.push(...geometryIssues);
}
@@ -533,6 +564,25 @@ async function collectSampleAt(
return collected;
}
async function buildSampleSets(
driver: CheckAuditDriver,
options: CheckOptions,
grid: SampleGrid,
motion: MotionPlan,
): Promise<SampleSets> {
const safeZones = options.safeZones ?? [];
const geometryEnabled =
grid.captionSamples.length > 0 || grid.frameSamples.length > 0 || safeZones.length > 0;
const canvas = geometryEnabled ? await driver.getCanvas() : null;
return {
layout: new Set(grid.layoutSamples),
motion: new Set(motion.times),
contrast: new Set(grid.contrastSamples),
canvas,
safeZones: canvas ? safeZonesFor(safeZones, canvas) : [],
};
}
// Frames are a function of time, so a helper page that is ready takes the next unclaimed sample
// and the merge keeps the serial order. A helper only adds speed: one that fails hands its samples back.
async function collectGridSamples(
@@ -545,13 +595,7 @@ async function collectGridSamples(
report: CheckProgress,
keep: (read: () => Partial<CheckBrowserResult>) => void,
): Promise<GridSamples> {
const geometryEnabled = grid.captionSamples.length > 0 || grid.frameSamples.length > 0;
const sets: SampleSets = {
layout: new Set(grid.layoutSamples),
motion: new Set(motion.times),
contrast: new Set(grid.contrastSamples),
canvas: geometryEnabled ? await driver.getCanvas() : null,
};
const sets = await buildSampleSets(driver, options, grid, motion);
const gridStart = performance.now();
const times = mergeSampleTimes(grid.layoutSamples, motion.times);
const pending = times.map((_, index) => index);
@@ -2073,7 +2117,10 @@ function buildReport(
contrastSection.errorCount +
craftSection.errorCount;
// Craft findings are judgment calls a film may break on purpose, so --strict gates defects only.
const strictWarningCount = warningCount - craftSection.warningCount;
const guidanceWarnings = layout.findings.filter(
(finding) => finding.severity === "warning" && isGuidanceIssue(finding),
).length;
const strictWarningCount = warningCount - craftSection.warningCount - guidanceWarnings;
const report: CheckReport = {
ok: errorCount === 0 && (!options.strict || strictWarningCount === 0),
strict: options.strict,
+4 -1
View File
@@ -11,6 +11,7 @@ import type { HdrAutoPromotion } from "@hyperframes/engine";
import type { ComponentReport } from "@hyperframes/inspector/live";
import type { PrelaunchedBrowser } from "../capture/captureCompositionFrame.js";
import type { CheckPhase } from "./checkDeadline.js";
import type { SafeZone } from "./safeZones.js";
export interface CheckOptions {
samples: number;
@@ -31,6 +32,7 @@ export interface CheckOptions {
findingFrames?: boolean;
inspect?: boolean;
captionZone?: CaptionZoneOptions;
safeZones?: SafeZone[];
frameCheck?: FrameCheckOptions;
/** Opt-in layout-audit knobs (`--layout "proseCoverageFloor=0.05"`). Defaults stay in the browser audit. */
layout?: LayoutOptions;
@@ -135,6 +137,7 @@ export interface ContrastCapture {
export interface GeometryCandidateRequest {
text: boolean;
media: boolean;
blocks: boolean;
tolerance: number;
}
@@ -172,7 +175,7 @@ export interface CheckFindingInspection {
}
export interface CheckGeometryCandidate extends CheckAnchor {
kind: "text" | "media";
kind: "text" | "media" | "block";
tag: string;
text: string;
rect: LayoutRect;
+17 -6
View File
@@ -22,6 +22,7 @@ export type LayoutIssueCode =
| "video_alpha_unread"
| "text_not_painted"
| "caption_zone_collision"
| "outside_safe_zone"
| "frame_out_of_frame"
// Coordinate-frame findings — geometry computed in one frame, rendered in another.
| "escaped_container"
@@ -344,8 +345,7 @@ function applyPersistenceTier(
multiSampleRun: boolean,
sampleTimes?: readonly number[],
): LayoutIssue {
if (!multiSampleRun) return issue;
if (!PERSISTENCE_TIERED_CODES.has(issue.code)) return issue;
if (!multiSampleRun || !PERSISTENCE_TIERED_CODES.has(issue.code)) return issue;
const occurrences = issue.occurrences ?? 1;
// A single collapsed occurrence is held 0ms by construction (firstSeen ===
@@ -354,13 +354,18 @@ function applyPersistenceTier(
if (occurrences <= 1) {
return caughtForWholeLifetime(issue, sampleTimes) ? issue : { ...issue, severity: "info" };
}
const promoted = heldPromotion(issue, occurrences);
return promoted ? { ...issue, severity: promoted } : issue;
}
function heldPromotion(issue: LayoutIssue, occurrences: number): LayoutIssueSeverity | null {
if (issue.code === "content_overlap" && isContentOverlapHeldLongEnough(issue, occurrences)) {
return { ...issue, severity: "error" };
return "error";
}
if (issue.code === "canvas_overflow" && isCanvasBreachHeldLarge(issue, occurrences)) {
return { ...issue, severity: "warning" };
return "warning";
}
return issue;
return null;
}
// A held, canvas-scale, PARTIALLY visible breach is drift; a fully off-canvas rect is a parked entrance.
@@ -394,6 +399,11 @@ function isContentOverlapHeldLongEnough(issue: LayoutIssue, occurrences: number)
return heldMs >= CONTENT_OVERLAP_HELD_ERROR_MS;
}
// Platform guidance, not a defect: it never fails --strict and is the first to go past --max-issues.
export function isGuidanceIssue(issue: Pick<LayoutIssue, "code">): boolean {
return issue.code === "outside_safe_zone";
}
export function limitLayoutIssues(
issues: LayoutIssue[],
maxIssues: number,
@@ -402,7 +412,8 @@ export function limitLayoutIssues(
const sortedIssues = [...issues].sort((a, b) => {
const severityDelta = severityRank(a.severity) - severityRank(b.severity);
if (severityDelta !== 0) return severityDelta;
return a.time - b.time;
const guidanceDelta = Number(isGuidanceIssue(a)) - Number(isGuidanceIssue(b));
return guidanceDelta !== 0 ? guidanceDelta : a.time - b.time;
});
return {
issues: sortedIssues.slice(0, limit),
+53
View File
@@ -0,0 +1,53 @@
import {
SOCIAL_SAFE_AREAS,
TITLE_SAFE_PERCENT,
safeBoxInsetPercent,
type SafeArea,
type SocialSafeArea,
} from "@hyperframes/core/safe-areas";
import type { LayoutRect } from "./layoutAudit.js";
export type SafeZone = SocialSafeArea | "standard";
export type SafeZoneEdge = "left" | "top" | "right" | "bottom";
const TITLE_INSET = safeBoxInsetPercent(TITLE_SAFE_PERCENT);
const SAFE_AREAS: Record<SafeZone, SafeArea> = {
...SOCIAL_SAFE_AREAS,
standard: {
label: "title-safe margins",
width: 100,
height: 100,
clearBandsTopToBottom: [[TITLE_INSET, 100 - TITLE_INSET, TITLE_INSET, 100 - TITLE_INSET]],
},
};
export function safeZoneLabel(zone: SafeZone): string {
return SAFE_AREAS[zone].label;
}
/** The social areas only describe 9:16 frames; title-safe margins fit any frame. */
export function safeZonesFor(zones: SafeZone[], canvas: { width: number; height: number }) {
const nineBySixteen = canvas.height > 0 && Math.abs(canvas.width / canvas.height - 9 / 16) < 0.01;
return zones.filter((zone) => zone === "standard" || nineBySixteen);
}
export function safeZoneEdgesCrossed(
box: LayoutRect,
canvas: { width: number; height: number },
zone: SafeZone,
): SafeZoneEdge[] {
const area = SAFE_AREAS[zone];
const x = (value: number) => (value / area.width) * canvas.width;
const y = (value: number) => (value / area.height) * canvas.height;
const edges = new Set<SafeZoneEdge>();
const first = area.clearBandsTopToBottom[0];
const last = area.clearBandsTopToBottom.at(-1);
if (first && box.top < y(first[0])) edges.add("top");
if (last && box.bottom > y(last[1])) edges.add("bottom");
for (const [top, bottom, left, right] of area.clearBandsTopToBottom) {
if (box.bottom <= y(top) || box.top >= y(bottom)) continue;
if (box.left < x(left)) edges.add("left");
if (box.right > x(right)) edges.add("right");
}
return (["left", "top", "right", "bottom"] as const).filter((edge) => edges.has(edge));
}
+6
View File
@@ -56,6 +56,12 @@
"types": "./dist/safePath.d.ts",
"environments": ["bun", "node"]
},
"./safe-areas": {
"source": "./src/safeAreas.ts",
"runtime": "./dist/safeAreas.js",
"types": "./dist/safeAreas.d.ts",
"environments": ["browser", "bun", "node"]
},
"./browser-marker": {
"source": "./src/browserMarker.ts",
"runtime": "./dist/browserMarker.js",
+10
View File
@@ -68,6 +68,12 @@
"import": "./src/safePath.ts",
"types": "./src/safePath.ts"
},
"./safe-areas": {
"bun": "./src/safeAreas.ts",
"node": "./dist/safeAreas.js",
"import": "./src/safeAreas.ts",
"types": "./src/safeAreas.ts"
},
"./browser-marker": {
"bun": "./src/browserMarker.ts",
"node": "./dist/browserMarker.js",
@@ -678,6 +684,10 @@
"import": "./dist/safePath.js",
"types": "./dist/safePath.d.ts"
},
"./safe-areas": {
"import": "./dist/safeAreas.js",
"types": "./dist/safeAreas.d.ts"
},
"./browser-marker": {
"import": "./dist/browserMarker.js",
"types": "./dist/browserMarker.d.ts"
+1 -1
View File
@@ -22,7 +22,7 @@ function loadedModules(entry: string): string[] {
}
describe("entries a host imports for one helper", () => {
it.each(["./safe-path", "./asset-paths", "./preview-quality"])(
it.each(["./safe-path", "./safe-areas", "./asset-paths", "./preview-quality"])(
"%s loads none of the parsers",
(entry) => {
expect(loadedModules(entry).filter((path) => HEAVY.test(path))).toEqual([]);
+46
View File
@@ -0,0 +1,46 @@
export interface SafeArea {
label: string;
width: number;
height: number;
clearBandsTopToBottom: [top: number, bottom: number, left: number, right: number][];
}
// Vertical-ad guides checked 2026-10-13: TikTok in-feed ads template (720x1280, stepped right edge
// for the action buttons), Meta's Reels ads guide (bottom 35%; top 14% and sides 6% are a conservative
// pick), Google's YouTube Shorts video ad specs (1080x1920). Platform UI varies by caption and device.
export const SOCIAL_SAFE_AREAS = {
tiktok: {
label: "TikTok",
width: 720,
height: 1280,
clearBandsTopToBottom: [
[160, 560, 80, 640],
[560, 840, 80, 520],
],
},
reels: {
label: "Instagram Reels",
width: 100,
height: 100,
clearBandsTopToBottom: [[14, 65, 6, 94]],
},
shorts: {
label: "YouTube Shorts",
width: 1080,
height: 1920,
clearBandsTopToBottom: [[288, 1248, 48, 888]],
},
} satisfies Record<string, SafeArea>;
export type SocialSafeArea = keyof typeof SOCIAL_SAFE_AREAS;
export const SOCIAL_SAFE_AREA_NAMES: SocialSafeArea[] = ["tiktok", "reels", "shorts"];
// Adobe Premiere default: action-safe and title-safe margins are 10% and 20% total (5% and 10% per edge).
export const ACTION_SAFE_PERCENT = 90;
export const TITLE_SAFE_PERCENT = 80;
export const SAFE_BOX_PERCENTS = [ACTION_SAFE_PERCENT, TITLE_SAFE_PERCENT] as const;
export function safeBoxInsetPercent(boxPercent: number): number {
return (100 - boxPercent) / 2;
}
@@ -1,10 +1,6 @@
// Adobe Premiere default: action-safe and title-safe margins are 10% and 20% total (5% and 10% per edge).
export const ACTION_SAFE_PERCENT = 90;
export const TITLE_SAFE_PERCENT = 80;
export const SAFE_BOX_PERCENTS = [ACTION_SAFE_PERCENT, TITLE_SAFE_PERCENT] as const;
/** Inset from each frame edge, as a percent of the frame. */
export function safeBoxInsetPercent(boxPercent: number): number {
return (100 - boxPercent) / 2;
}
export {
ACTION_SAFE_PERCENT,
SAFE_BOX_PERCENTS,
TITLE_SAFE_PERCENT,
safeBoxInsetPercent,
} from "@hyperframes/core/safe-areas";
+1 -1
View File
@@ -60,7 +60,7 @@ test("the Remotion translation docs do not claim volume ramps are unsupported",
});
test("the entry skill's safe boxes equal the preview's", async () => {
const src = await read("packages/studio/src/utils/previewSafeMargins.ts");
const src = await read("packages/core/src/safeAreas.ts");
const action = src.match(/ACTION_SAFE_PERCENT = (\d+)/)?.[1];
const title = src.match(/TITLE_SAFE_PERCENT = (\d+)/)?.[1];
const skill = await read(ENTRY_SKILL);