From 7c7ff6d89e99e81002dc919ae6d7b34193d6d202 Mon Sep 17 00:00:00 2001 From: James Russo Date: Sun, 15 Nov 2026 02:12:42 +0000 Subject: [PATCH] fix(docs): check catalog link values and keep them out of copied commands (#7783) * fix(docs): check catalog link values by type and isolate the preview A catalog page restores its variable values from the query string, so a shared link decides what the preview composition is given. Values from a link are now kept only when they fit the variable they name: a finite number, a boolean, one of an enum's options, a colour, an image address, or text with no angle brackets. Anything else opens at its default. The preview player now runs the composition with an opaque origin (sandbox-origin="opaque"), so a composition cannot reach the docs page. The bootstrap already drives the player only through its API and postMessage, and every docs asset is served with CORS, so playback, seek-on-remount and edits behave as before. chatgpt-exchange sets its editable text with textContent instead of building innerHTML from it. A new check, check:registry-innerhtml, fails any registry file that reads variables and adds markup writes; the files that do so today are listed with their current counts and may only go down. Co-Authored-By: Claude Opus 5.5 * fix(docs): keep a link's text out of copied commands until the reader sets it (#7785) A catalog page restores tuned values from its link, and the install command, the render command and the agent request carried those values as if the reader had typed them. The commands quote only for bash and zsh, and the agent request is pasted as the reader's own words. The page now tracks which variables the reader set on it. A value that only came with the link goes into a command when it is a number, a boolean, or short text of letters, digits, spaces and plain punctuation, and into the agent request only when it is a number, a boolean or one of the item's own options. A page opened with values from its link says so and offers "Reset to defaults", and the install command wraps instead of scrolling so the whole line is visible. Co-authored-by: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- docs/custom.css | 5 + docs/snippets/catalog-detail.jsx | 161 +++++++++-- docs/snippets/install-command.jsx | 23 +- package.json | 3 +- .../chatgpt-exchange/chatgpt-exchange.html | 42 +-- scripts/catalog-detail.test.ts | 253 +++++++++++++++++- scripts/check-registry-innerhtml.mjs | 102 +++++++ scripts/check-registry-innerhtml.test.mjs | 57 ++++ 8 files changed, 593 insertions(+), 53 deletions(-) create mode 100644 scripts/check-registry-innerhtml.mjs create mode 100644 scripts/check-registry-innerhtml.test.mjs diff --git a/docs/custom.css b/docs/custom.css index 270906d8b2..3e9ef395ed 100644 --- a/docs/custom.css +++ b/docs/custom.css @@ -347,6 +347,11 @@ samp { border-radius: 0; border-color: var(--hf-ui-border) !important; color: var(--hf-heading) !important; + /* The whole command stays on screen. A page's link can add values to it, and + a reader should see everything they are about to paste, not the start of a + line that scrolls. */ + white-space: pre-wrap; + overflow-wrap: anywhere; } /* diff --git a/docs/snippets/catalog-detail.jsx b/docs/snippets/catalog-detail.jsx index 87869d8f5f..a6fe69ecea 100644 --- a/docs/snippets/catalog-detail.jsx +++ b/docs/snippets/catalog-detail.jsx @@ -240,6 +240,21 @@ export const CatalogDetail = ({ font-variant-numeric: tabular-nums; color: var(--ve-muted); } +.hf-ve-link-notice { + display: flex; + flex-wrap: wrap; + align-items: center; + justify-content: space-between; + gap: 8px 16px; + margin: 0 0 12px; + padding: 10px 14px; + border: 1px solid var(--ve-line); + border-radius: 14px; + background: var(--ve-surface); + font-size: 13px; + line-height: 1.45; + color: var(--ve-fg); +} .hf-ve-desc { margin: 6px 0 0; font-size: 12px; @@ -1718,19 +1733,77 @@ export const CatalogDetail = ({ }); } - /** The entries of a parsed query object that name a declared id and hold a primitive value. */ - function declaredValues(parsed, ids) { + /** + * Whether a value from a link fits the variable it names. + * + * A link is written by whoever shares it, and the value goes into a + * composition that may put it straight into markup. So each value has to look + * like what its control could have produced: a number for a slider, one of the + * listed options for a choice, a colour for a swatch, an address for an image, + * and text with no markup for a string. The declared default always passes. + */ + function fitsVariable(variable, value) { + if (JSON.stringify(value) === JSON.stringify(variable.default)) return true; + switch (variable.type) { + case "number": + return typeof value === "number" && Number.isFinite(value); + case "boolean": + return typeof value === "boolean"; + case "enum": + return (variable.options ?? []).some((option) => option.value === value); + case "color": + return ( + typeof value === "string" && + /^(?:#[0-9a-f]{3,8}|[a-z]{3,24}|(?:rgb|hsl)a?\([\d\s.,%/+-]{1,48}\))$/i.test(value) + ); + case "image": + return ( + typeof value === "string" && + value.length <= 2048 && + /^(?:https?:\/\/|[\w./-])[^\s<>"'`()\\]*$/i.test(value) + ); + default: + return typeof value === "string" && value.length <= 10000 && !/[<>]/.test(value); + } + } + + /** The entries of a parsed query object that name a declared variable and fit its type. */ + function declaredValues(parsed, variables) { if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {}; + const byId = new Map(variables.map((variable) => [variable.id, variable])); return Object.fromEntries( - Object.entries(parsed).filter(([id, value]) => { - if (!ids.has(id)) return false; - if (typeof value === "number") return Number.isFinite(value); - return typeof value === "string" || typeof value === "boolean"; - }), + Object.entries(parsed).filter(([id, value]) => byId.has(id) && fitsVariable(byId.get(id), value)), ); } // <<< preview values + // >>> copied values + /** + * Whether a value a link arrived with can go into a copied command as it is. + * + * The command is pasted into whatever shell the reader has: bash, zsh, fish, + * PowerShell or cmd.exe. They agree on almost nothing about quoting, so + * rather than escape for each, a link's text is carried only when it is + * short and made of letters, digits, spaces and punctuation that none of them + * reads as syntax inside the argument. Numbers and booleans always qualify. + */ + function plainLinkValue(value) { + if (typeof value === "number") return Number.isFinite(value); + if (typeof value === "boolean") return true; + return typeof value === "string" && value.length <= 200 && /^[A-Za-z0-9 .,:_#+\-/@()?]*$/.test(value); + } + + /** + * The changed values copied text may carry: every value the reader set on + * this page, and a value a link arrived with only when `keepFromLink` allows. + */ + function copiedValues(changed, edited, keepFromLink) { + return Object.fromEntries( + Object.entries(changed).filter(([id, value]) => edited.includes(id) || keepFromLink(id, value)), + ); + } + // <<< copied values + const readFromUrl = () => { if (typeof window === "undefined") return {}; try { @@ -1739,8 +1812,9 @@ export const CatalogDetail = ({ // `URLSearchParams` has already decoded this once. Decoding again turned // a path full of percent-escapes into something that no longer parsed, // and doubled the length of every link. - // Only ids this item declares; a stale link must not inject stray keys. - return declaredValues(JSON.parse(raw), new Set(variables.map((v) => v.id))); + // Only ids this item declares, each holding what its control could have + // set; a stale or hand-made link must not inject stray keys or markup. + return declaredValues(JSON.parse(raw), variables); } catch { return {}; } @@ -1748,6 +1822,18 @@ export const CatalogDetail = ({ const [values, setValues] = useState(() => ({ ...defaults, ...readFromUrl() })); + /** + * Ids the reader set on this page, and ids the link opened the page with. + * + * A link is written by whoever shared it. Its values still drive the + * preview, but the copy buttons only treat a value as the reader's own once + * they have set it here: until then a link's free text stays out of the + * agent request and the commands. The install command is a separate + * component, so the list is also published on `window` for it. + */ + const [edited, setEdited] = useState([]); + const [fromLink, setFromLink] = useState([]); + /** * Read the URL again once the component is actually in a browser. * @@ -1763,11 +1849,15 @@ export const CatalogDetail = ({ useEffect(() => { const fromUrl = readFromUrl(); if (Object.keys(fromUrl).length > 0) setValues((current) => ({ ...current, ...fromUrl })); + setFromLink( + Object.keys(fromUrl).filter((id) => JSON.stringify(fromUrl[id]) !== JSON.stringify(defaults[id])), + ); // eslint-disable-next-line react-hooks/exhaustive-deps }, []); // `replaceState` rather than `pushState`: dragging a slider should not stack // up history entries the back button has to walk through. + const publishedEdited = useRef(""); useEffect(() => { if (typeof window === "undefined") return; const changed = Object.fromEntries( @@ -1781,13 +1871,16 @@ export const CatalogDetail = ({ // Comparing first keeps it to an actual change rather than touching the // history API on each one. const next = url.toString(); - if (next !== window.location.href) { - window.history.replaceState(null, "", next); + const editedNow = JSON.stringify(edited); + if (next !== window.location.href || editedNow !== publishedEdited.current) { + if (next !== window.location.href) window.history.replaceState(null, "", next); + publishedEdited.current = editedNow; + window.__hfEditedVars = { ...window.__hfEditedVars, [compositionId]: edited }; // `replaceState` fires no event, and the install command on the same page // needs to follow these values. window.dispatchEvent(new CustomEvent("hf-vars-changed")); } - }, [values, defaults, urlKey]); + }, [values, defaults, urlKey, edited, compositionId]); // What the SVG import last had to say, per variable. Held here because // `control` is a function rather than a component and cannot hold it itself. const [notes, setNotes] = useState({}); @@ -1880,6 +1973,10 @@ export const CatalogDetail = ({ " arm(resumeAt || 0);", " }", " player = document.createElement('hyperframes-player');", + // The composition runs with values a shared link chose, so it gets an + // origin of its own rather than this page's: whatever it does stays inside + // the preview. This script only ever talks to it through the player's API. + " player.setAttribute('sandbox-origin', 'opaque');", " player.setAttribute('controls', ''); player.setAttribute('muted', '');", " document.body.appendChild(player);", " player.addEventListener('ended', function () { player.seek(0); player.play(); });", @@ -1939,6 +2036,16 @@ export const CatalogDetail = ({ snippetLines.push([[SHIKI.punct, ">"]]); const dirty = variables.some((v) => values[v.id] !== defaults[v.id]); + const resetValues = () => { + setValues(defaults); + setNotes({}); + setEdited([]); + setFromLink([]); + }; + // Values the link set that the reader has not touched since. + const heldFromLink = fromLink.filter( + (id) => !edited.includes(id) && JSON.stringify(values[id]) !== JSON.stringify(defaults[id]), + ); const hasTune = variables.length > 0; const [tab, setTab] = useState("preview"); @@ -1958,12 +2065,16 @@ export const CatalogDetail = ({ return changed; }; const renderCommand = (() => { - const changed = changedValues(); + const changed = copiedValues(changedValues(), edited, (id, value) => plainLinkValue(value)); const vars = Object.keys(changed).length ? ` --variables '${JSON.stringify(changed).replace(/'/g, "'\\''")}'` : ""; return `# Run from the installed project's root.\nnpx hyperframes render --composition '${compositionSrc}'${vars}`; })(); const agentRequest = (() => { - const changed = changedValues(); + // The reader pastes this to an agent as their own words, so a link's text + // never goes in: only numbers, switches and the author's own options do. + const changed = copiedValues(changedValues(), edited, (id, value) => + typeof value !== "string" || variables.some((v) => v.id === id && v.type === "enum"), + ); const base = `Install the HyperFrames catalog item "${compositionId}" (${title || compositionId}) into my project with \`npx hyperframes add ${compositionId}\`, mount it at the point of my composition where it should play, and verify with \`npx hyperframes check\`.`; const set = Object.entries(changed).map(([id, value]) => `${id} = ${JSON.stringify(value)}`); return set.length ? `${base} Set ${set.join(", ")}; keep the other variables at their defaults.` : `${base} Keep the default variables unless I say otherwise.`; @@ -2109,6 +2220,18 @@ export const CatalogDetail = ({
+ {heldFromLink.length > 0 && ( +
+ + This page opened with settings from its link: {heldFromLink.join(", ")}. Text from a link + stays out of copied commands and the agent request until you set it here. + + +
+ )} +
{seconds && ( @@ -2162,7 +2285,10 @@ export const CatalogDetail = ({ {control( v, values[v.id], - (next) => setValues((prev) => ({ ...prev, [v.id]: next })), + (next) => { + setEdited((prev) => (prev.includes(v.id) ? prev : [...prev, v.id])); + setValues((prev) => ({ ...prev, [v.id]: next })); + }, notes[v.id], (note) => setNotes((prev) => ({ ...prev, [v.id]: note })), setTyping, @@ -2174,10 +2300,7 @@ export const CatalogDetail = ({