feat(lint): warn when a script builds an element's text with no static fallback

Studio's manual-edit save patches text fields back into the static HTML
source by locating existing content. When an element's visible text is
built entirely at runtime (getElementById/querySelector + appendChild/
innerHTML/textContent), there's nothing in the source to patch, and a
manual edit in Studio silently fails with "Couldn't find this element in
the source file." Hit this exact failure authoring a Studio QA fixture
whose caption-word spans were only ever created by a load-time script.

Adds manual_edit_unsupported_runtime_text (warning) to catch it, exempting
caption-cue elements since transcript-driven word spans are an intentional
instance of the same shape.
This commit is contained in:
Vance Ingalls
2026-07-15 13:00:46 -07:00
parent 968c90397b
commit 5d21cf64bb
2 changed files with 245 additions and 0 deletions
+107
View File
@@ -1688,4 +1688,111 @@ describe("composition rules", () => {
expect(find(result.findings)).toBeUndefined();
});
});
describe("manual_edit_unsupported_runtime_text", () => {
const CODE = "manual_edit_unsupported_runtime_text";
const find = (findings: { code: string }[]) => findings.find((f) => f.code === CODE);
it("warns when a script builds an empty element's content via getElementById + appendChild", async () => {
const html = `<html><body>
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
<div id="qa-caption-host"></div>
</div>
<script>
const host = document.getElementById("qa-caption-host");
for (const word of ["Generated", "caption", "words", "here"]) {
const span = document.createElement("span");
span.textContent = word;
host.appendChild(span);
}
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = find(result.findings);
expect(finding).toBeDefined();
expect(finding?.severity).toBe("warning");
expect(finding?.elementId).toBe("qa-caption-host");
});
it("warns for a direct getElementById(...).innerHTML assignment with no static content", async () => {
const html = `<html><body>
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
<div id="stat-value"></div>
</div>
<script>
document.getElementById("stat-value").innerHTML = "<b>42</b>";
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = find(result.findings);
expect(finding).toBeDefined();
expect(finding?.elementId).toBe("stat-value");
});
it("warns when the element is targeted via a bare #id querySelector", async () => {
const html = `<html><body>
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
<div id="qa-list"></div>
</div>
<script>
const host = document.querySelector("#qa-list");
host.textContent = "built at runtime";
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(find(result.findings)).toBeDefined();
});
it("does not warn when the element already has static fallback content", async () => {
const html = `<html><body>
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
<div id="qa-caption-host"><span>Generated</span></div>
</div>
<script>
const host = document.getElementById("qa-caption-host");
host.appendChild(document.createElement("span"));
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(find(result.findings)).toBeUndefined();
});
it("does not warn for a caption-cue id even with no static content", async () => {
const html = `<html><body>
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
<div id="caption-word"></div>
</div>
<script>
const host = document.getElementById("caption-word");
host.appendChild(document.createElement("span"));
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(find(result.findings)).toBeUndefined();
});
it("does not warn when the script only reads the element, never injects content", async () => {
const html = `<html><body>
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
<div id="qa-readonly"></div>
</div>
<script>
const el = document.getElementById("qa-readonly");
console.log(el.getBoundingClientRect());
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(find(result.findings)).toBeUndefined();
});
it("does not warn when there are no scripts at all", async () => {
const html = `<html><body>
<div data-composition-id="main" data-start="0" data-duration="6" data-width="1920" data-height="1080">
<div id="qa-empty"></div>
</div>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(find(result.findings)).toBeUndefined();
});
});
});
+138
View File
@@ -10,6 +10,10 @@ import {
} from "../utils";
import { COMPOSITION_VARIABLE_TYPES } from "@hyperframes/parsers/composition";
function escapeRegExp(value: string): string {
return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}
// Agent guidance thresholds: warning-only nudges for files/tracks that become hard
// to inspect and revise reliably in a single composition.
const MAX_COMPOSITION_LINES = 300;
@@ -178,6 +182,98 @@ function isInsideInertTemplate(tag: OpenTag, tags: readonly OpenTag[]): boolean
);
}
// A DOM call that injects content into an element: appendChild/append/
// insertAdjacentHTML/insertAdjacentElement, or an innerHTML/textContent/
// innerText assignment (the negative lookahead keeps `===` from matching).
const RUNTIME_INJECTION_CALL_PATTERN =
"(?:\\.(?:appendChild|append|insertAdjacentHTML|insertAdjacentElement)\\s*\\(|\\.(?:innerHTML|textContent|innerText)\\s*=(?!=))";
// Element ids referenced via `document.getElementById("x")` or a bare `#x`
// querySelector, immediately chained into an injection call — e.g.
// `document.getElementById("x").appendChild(...)`. A multi-part selector
// isn't resolved to a single id, so it's left alone rather than guessed at.
function findDirectlyInjectedIds(scriptContent: string): Set<string> {
const ids = new Set<string>();
const patterns = [
new RegExp(
`(?:document|window\\.document)\\.getElementById\\(\\s*["']([^"']+)["']\\s*\\)\\s*${RUNTIME_INJECTION_CALL_PATTERN}`,
"g",
),
new RegExp(
`(?:document|window\\.document)\\.querySelector\\(\\s*["']#([\\w-]+)["']\\s*\\)\\s*${RUNTIME_INJECTION_CALL_PATTERN}`,
"g",
),
];
for (const pattern of patterns) {
let match: RegExpExecArray | null;
while ((match = pattern.exec(scriptContent)) !== null) {
if (match[1]) ids.add(match[1]);
}
}
return ids;
}
// Element ids captured into a variable (`const host = document.getElementById(...)`
// or the `#x` querySelector form) that the variable is later used to inject
// content into, anywhere else in the same script.
function findIndirectlyInjectedIds(scriptContent: string): Set<string> {
const idsByVariable = new Map<string, string>();
const assignmentPatterns = [
/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:document|window\.document)\.getElementById\(\s*["']([^"']+)["']\s*\)/g,
/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:document|window\.document)\.querySelector\(\s*["']#([\w-]+)["']\s*\)/g,
];
for (const pattern of assignmentPatterns) {
let match: RegExpExecArray | null;
while ((match = pattern.exec(scriptContent)) !== null) {
const [, variableName, targetId] = match;
if (variableName && targetId) idsByVariable.set(variableName, targetId);
}
}
const ids = new Set<string>();
for (const [variableName, targetId] of idsByVariable) {
const usagePattern = new RegExp(
`\\b${escapeRegExp(variableName)}\\s*${RUNTIME_INJECTION_CALL_PATTERN}`,
);
if (usagePattern.test(scriptContent)) ids.add(targetId);
}
return ids;
}
// Whether `targetId` is a legitimate finding: it resolves to a real element
// with no static text/markup already in source, and isn't a caption-cue
// element (transcript-driven word spans are an intentional instance of this
// same shape, not a bug — see isCaptionCue).
function buildRuntimeTextFinding(
targetId: string,
tags: readonly OpenTag[],
source: string,
): HyperframeLintFinding | null {
const targetTag = tags.find((tag) => readAttr(tag.raw, "id") === targetId);
if (!targetTag || targetTag.closeIndex == null) return null;
if (isCaptionCue(targetTag)) return null;
const innerContent = source.slice(targetTag.index + targetTag.raw.length, targetTag.closeIndex);
if (innerContent.trim().length > 0) return null; // already has static fallback content
return {
code: "manual_edit_unsupported_runtime_text",
severity: "warning",
elementId: targetId,
message:
`#${targetId} has no static text/markup in source — its visible content is built entirely ` +
"at runtime by a script. HyperFrames Studio's manual-edit save locates text fields by " +
"matching existing source content, so a manual edit to this element in Studio will fail to " +
'save with "Couldn\'t find this element in the source file".',
fixHint:
"Author the element's expected content as static markup (even placeholder text) so Studio's " +
"manual-edit save has something to patch, and have the script update/replace it rather than " +
"build it from nothing. If this element is intentionally not meant to be manually edited " +
"(e.g. transcript-driven captions), this warning can be ignored.",
snippet: truncateSnippet(targetTag.raw),
};
}
export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
// duplicate_composition_id catches meta-tag/root collisions that create duplicate composition entries.
({ tags }) => {
@@ -1079,4 +1175,46 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
// in runtime/init.ts). Not an error; data-duration is optional here.
return [];
},
// manual_edit_unsupported_runtime_text
//
// Studio's manual-edit save path patches text fields back into the static
// HTML source by locating the element's existing text content. When an
// element's visible text is built entirely at runtime — a script grabbing
// it via getElementById/querySelector and then appendChild/innerHTML/
// textContent — there is no static counterpart in the source for the save
// path to locate, and a manual text edit made to that element in Studio
// silently fails to save ("Couldn't find this element in the source
// file"). This is a real failure mode hit while authoring a Studio QA
// fixture: a <div> whose word-spans were only ever created by a load-time
// script had nothing for the save path to patch.
//
// Caption/subtitle word-by-word spans generated from a transcript are a
// deliberate, expected instance of this same shape — per-word manual
// editing isn't the intended workflow there — so elements matching the
// existing caption-cue id/class convention (see isCaptionCue above) are
// exempted. This is advisory (warning): the pattern is often intentional;
// the point is to surface the save-time limitation, not to forbid it.
({ tags, scripts, source }) => {
const findings: HyperframeLintFinding[] = [];
const flaggedIds = new Set<string>();
for (const script of scripts) {
const content = stripJsComments(script.content);
const candidateIds = new Set([
...findDirectlyInjectedIds(content),
...findIndirectlyInjectedIds(content),
]);
for (const targetId of candidateIds) {
if (flaggedIds.has(targetId)) continue;
const finding = buildRuntimeTextFinding(targetId, tags, source);
if (!finding) continue;
flaggedIds.add(targetId);
findings.push(finding);
}
}
return findings;
},
];