From 5d21cf64bb2b8e2ca36e6b2dca10a8bc076a97cb Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Wed, 15 Jul 2026 13:00:46 -0700 Subject: [PATCH] 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. --- packages/lint/src/rules/composition.test.ts | 107 +++++++++++++++ packages/lint/src/rules/composition.ts | 138 ++++++++++++++++++++ 2 files changed, 245 insertions(+) diff --git a/packages/lint/src/rules/composition.test.ts b/packages/lint/src/rules/composition.test.ts index 2a44596ec2..7af5e73a09 100644 --- a/packages/lint/src/rules/composition.test.ts +++ b/packages/lint/src/rules/composition.test.ts @@ -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 = ` +
+
+
+ + `; + 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 = ` +
+
+
+ + `; + 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 = ` +
+
+
+ + `; + 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 = ` +
+
Generated
+
+ + `; + 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 = ` +
+
+
+ + `; + 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 = ` +
+
+
+ + `; + const result = await lintHyperframeHtml(html); + expect(find(result.findings)).toBeUndefined(); + }); + + it("does not warn when there are no scripts at all", async () => { + const html = ` +
+
+
+ `; + const result = await lintHyperframeHtml(html); + expect(find(result.findings)).toBeUndefined(); + }); + }); }); diff --git a/packages/lint/src/rules/composition.ts b/packages/lint/src/rules/composition.ts index a2ffa4f69b..dfbde7f117 100644 --- a/packages/lint/src/rules/composition.ts +++ b/packages/lint/src/rules/composition.ts @@ -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 { + const ids = new Set(); + 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 { + const idsByVariable = new Map(); + 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(); + 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
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(); + + 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; + }, ];