fix(core): resolve sub-composition sibling asset paths in render and asset discovery - #2994

Verdict: APPROVE at 48a04f1b87.

Two-defect fix, consolidation win, thorough tests. Clean follow-up to #2983 — same discriminator (assetExists probe) now shared by every asset-resolution site (preview + render + inliner + bundler + HEVC lint + project lint + publish-proxy-bake + media-treatment). No blockers.

Defect 1 — Sibling resolution now covers render + discovery (extended from #2983's thumbnail path)

rewriteAssetPath(compSrcPath, relativePath, assetExists?) in parsers/rewriteSubCompPaths.ts:79-98 adds the probe. Semantics:

1. Non-relative URL (absolute / data: / protocol) → unchanged.
2. compDir === "." || !compDir (composition at project root) → unchanged.
3. ../ or .. → route through existing join + resolve (parent-relative, unchanged).
4. Plain relative WITHOUT probe → return unchanged (backward-compat: no caller breakage).
5. Plain relative WITH probe: split path/suffix via splitPathSuffix, compute sibling = resolve("/", join(compDir, filePart)).slice(1), check assetExists(sibling). If true → return sibling + suffix (query/hash preserved). Else → return unchanged.

The disk-check-as-discriminator moves from studio-server-local (#2983) into shared parsers. Every caller now uses the SAME resolver, so preview + render + discovery agree on which convention (sibling vs project-root) a given ref means — closing the studio-server-vs-producer divergence risk I raised in the #2983 review.

Test coverage at rewriteSubCompPaths.test.ts:57-101:

• Sibling resolves against comp dir ✓
• Query/hash preserved (frame.png?v=2 → design/styleframes/frame.png?v=2) ✓
• Project-root-relative left alone when no sibling (assets/logo.png from blocks/hero.html) ✓
• ../ still routes through the existing needsRewrite path without consulting the probe ✓
• No-op without probe (backward compat) ✓

Defect 2 — Hoisted <link href> / external <script src> were bypassing the rewriter ENTIRELY

inlineSubCompositions.ts:302-320 — head-hoisted <script src> and <link href> extraction previously used (s.getAttribute("src") || "").trim() with NO rewrite. Even the documented ../ form was being pushed as-authored → escaped the project → 404 at render time. Fix: resolveSubAssetPath = raw => rewriteAssetPath(src, raw, assetExists) wraps the extraction so every hoisted attribute goes through the same resolver as the body-attribute pass.

The content-region <script> extraction at :335 got the same fix.

Test coverage at inlineSubCompositions.test.ts:576-618 pins all three cases (hoisted links, hoisted scripts, markup + hoisted CSS + inline styles) — and specifically asserts ../shared/theme.css becomes design/shared/theme.css (the previously-escaping case), not just the sibling case.

Consolidation

studio-server/subComposition.ts loses 60 lines: removes the local resolvePreviewAssetPath and rewriteCssUrls helpers, delegates to shared rewriteAssetPaths / rewriteInlineStyleAssetUrls / rewriteCssAssetUrls from @hyperframes/core. One resolver, uniform behavior across preview / render / discovery — this is the "same root cause, the rest of the surface" outcome from the PR body.

HEVC lint sibling-vs-same-named-root — the strongest test

hevcPreviewLint.test.ts:33-45:

const dir = makeProject(["clip.mp4", "design/styleframes/clip.mp4"]);
collectLocalVideoCandidates(dir, [{ html: `<video src="clip.mp4"></video>`, compSrcPath: "design/styleframes/frame-01.html" }]);
expect([...candidates.keys()]).toEqual([join(dir, "design/styleframes/clip.mp4")]);

Both a sibling AND a same-named project-root file exist. Pre-fix behavior would probe the wrong file (project root). Post-fix correctly prefers the sibling. This is the "wrong-file" case the PR body calls out, and the test pins the fix.

Every caller consistently wires the probe

Verified existsSync(join(projectDir, path)) (or equivalent resolve) at each site:

• producer/htmlCompiler.ts:971 — existsSync(resolve(projectDir, path))
• studio-server/subComposition.ts:38 — existsSync(join(projectDir, path))
• core/htmlBundler.ts:902-905 — resolveEntryPath(path) !== null && existsSync(resolved) (bundler-side path resolution)
• cli/publishProxyBake.ts:149-150 — existsSync(resolve(absProjectDir, path))
• cli/media-treatment.ts:502 — existsSync(join(projectDir, path))
• lint/hevcPreviewLint.ts:95 — existsSync(join(projectDir, path))
• lint/project.ts:133/287/335 — three sites, all consistent

Callers that CANNOT see the filesystem (browser-facing) simply omit the probe → backward-compat behavior.

Non-blockers

1. existsSync per attribute per composition. For N sub-comps × M asset refs, this is N×M sync stat calls. For preview/thumbnail path this is fine (already tolerated in #2983). For render + discovery paths that touch large projects, marginal per-render cost — probably in the low-ms range and not a hot loop. Same non-blocker I raised on #2983.

2. Windows path separator handling. The shared implementation uses node:path's native join / dirname / resolve (not path/posix). On Windows, join produces \\-separated strings. existsSync accepts either separator on Windows so the probe still returns true; the concern is only if the rewritten path (sibling + suffix) with backslashes gets written into HTML — some browsers/renderers might not handle backslashes cleanly. Pacific's dev/prod matrix (Mac dev + Linux prod) avoids this in practice. Non-blocker; noting for anyone touching this on Windows.

3. splitPathSuffix matches the first ? OR #. If foo.png#frag?v=2 (fragment before query — non-standard but possible), suffix would be #frag?v=2. Correctly preserved as one blob. Not a concern; noting for completeness.

4. "Not covered" section acknowledges lintProject's missing-asset scan doesn't reach sub-composition markup. Separate pre-existing gap; probe is wired regardless so it's correct if/when that scan reaches those sources. Author's own callout — not this PR's regression.

Test-plan checkboxes match my read

Author's test plan: 5 parser tests, 3 inliner tests, 3 HEVC lint tests. Suites green (parsers 908, core 1434, studio-server 402, lint 514, producer unit 556). The 2 pre-existing transcribe failures in CLI are unrelated. CI: 41 passing, 11 running, 0 failing at time of review.

— Review by Via