Refactor Svelte live guidance into adapter reference

[abdulwahabone]

Summary

• Added docs/plans/live-svelte-guidance-refactor.md as the first commit on this branch.
• Split Svelte/SvelteKit live-mode instructions into skill/reference/live-svelte.md so skill/reference/live.md stays framework-neutral.
• Added guidanceRefs: ["reference/live-svelte.md"] to the Svelte adapter paths from live-inject, live-wrap, and live-insert; live.mjs preserves those refs in the boot payload.
• Updated the LLM live E2E agent to load live-svelte.md only for Svelte component-preview runs while still passing the per-run cssAuthoring contract.
• Hardened Svelte component preview binding: cycling now requires a visible mounted component, stable attrs like data-testid are preferred over generated svelte-* classes, and mounted state checkpoints after binding.
• Fixed mixed dynamic/static Svelte text variants, e.g. {expenses.length} offen, so generated variants preserve the static label while binding only the dynamic segment.
• Fixed nested split-state Svelte text bindings, e.g. <span>{expenses.length}</span><span>offen</span>, by capturing live prop values before DOM replacement and matching significant text nodes structurally instead of by raw global text-node index.
• Fixed Svelte Tune toggle binding so live preview uses boolean-compatible data-p-*="true", and Svelte accept cleanup keeps matching boolean/legacy truthy selector branches.
• Fixed Svelte shader capture for composited/translucent surfaces: direct selected-element capture is now reserved for opaque own surfaces/background images; translucent Svelte cards use ancestor crop while still cropping to the selected card rect.
• Fixed movie-card heading bleed for document-backed translucent cards: when the only painted ancestor is body/html, the shader now captures the selected card directly and composites it over the resolved page backdrop color instead of rendering/cropping the full document root.
• Fixed Svelte component-preview accept cleanup so accepted movie-card variants do not remain as a cloned preview beside HMR output, preserving the 3x3 movie grid immediately before refresh.
• Synced site/pages/shader-lab/index.astro with the alpha-aware shader proxy logic so the Svelte framework-proxy fixture remains a faithful repro harness.
• Fixed Svelte component prop extraction around control blocks so {#if}, {:else}, and {/if} are not emitted as props, duplicate prop names are avoided, and hidden branch text no longer shifts LLM prop substitution.
• Regenerated generated skill/provider outputs with bun run build.
• Visual Playwright test-file edits for the exhaustive DeepSeek sweep are intentionally not committed; the local copy lives under ignored tmp/framework-tests/.

Validation On Current Branch

• git diff --check
• bun run build
• node --test tests/live-svelte-component.test.mjs tests/live-browser-regression.test.mjs tests/live-e2e-agent-output.test.mjs
• node --test tests/live-browser-regression.test.mjs tests/live-e2e-agent-output.test.mjs tests/live-svelte-component.test.mjs
• bun test tests/live-reference.test.mjs
• node --test tests/framework-fixtures.test.mjs
• IMPECCABLE_E2E_ONLY=vite8-sveltekit bun run test:live-e2e
• IMPECCABLE_E2E_ONLY=vite8-sveltekit-stateful bun run test:live-e2e
• IMPECCABLE_E2E_ONLY=vite8-sveltekit IMPECCABLE_E2E_AGENT=llm IMPECCABLE_E2E_LLM_PROVIDER=deepseek DEEPSEEK_API_KEY=... bun run test:live-e2e
• IMPECCABLE_SVELTE_DEEPSEEK_ARTIFACT_DIR=/tmp/impeccable-svelte-open-count-fixed-final DEEPSEEK_API_KEY=... node --test --test-timeout=600000 --test-name-pattern "open-count text emphasis" tmp/framework-tests/live-svelte-adapter-deepseek.test.mjs
• IMPECCABLE_SVELTE_DEEPSEEK_ARTIFACT_DIR=/tmp/impeccable-svelte-split-count-fixed DEEPSEEK_API_KEY=... node --test --test-timeout=600000 --test-name-pattern "split open-count state" tmp/framework-tests/live-svelte-adapter-deepseek.test.mjs
• Red repro before movie-card shader crop fix: IMPECCABLE_SVELTE_DEEPSEEK_ARTIFACT_DIR=/tmp/impeccable-svelte-shader-crop-repro DEEPSEEK_API_KEY=... node --test --test-timeout=600000 --test-name-pattern "movie-card shader crop" tmp/framework-tests/live-svelte-adapter-deepseek.test.mjs
• Fixed movie-card shader crop sweep: IMPECCABLE_SVELTE_DEEPSEEK_ARTIFACT_DIR=/tmp/impeccable-svelte-shader-crop-fixed DEEPSEEK_API_KEY=... node --test --test-timeout=600000 --test-name-pattern "movie-card shader crop" tmp/framework-tests/live-svelte-adapter-deepseek.test.mjs
• Red repro before translucent shader-proxy fix: IMPECCABLE_SVELTE_DEEPSEEK_ARTIFACT_DIR=/tmp/impeccable-svelte-framework-proxy-repro DEEPSEEK_API_KEY=... node --test --test-timeout=600000 --test-name-pattern "framework proxy" tmp/framework-tests/live-svelte-adapter-deepseek.test.mjs
• Fixed shader-lab proxy sweep: IMPECCABLE_SVELTE_DEEPSEEK_ARTIFACT_DIR=/tmp/impeccable-svelte-framework-proxy-fixed DEEPSEEK_API_KEY=... node --test --test-timeout=600000 --test-name-pattern "framework proxy" tmp/framework-tests/live-svelte-adapter-deepseek.test.mjs
• Movie-card shader sweep after translucent proxy fix: IMPECCABLE_SVELTE_DEEPSEEK_ARTIFACT_DIR=/tmp/impeccable-svelte-movie-card-shader-after-proxy-fix DEEPSEEK_API_KEY=... node --test --test-timeout=600000 --test-name-pattern "movie-card" tmp/framework-tests/live-svelte-adapter-deepseek.test.mjs
• Red repro before movie-heading bleed fix: IMPECCABLE_SVELTE_DEEPSEEK_ARTIFACT_DIR=/tmp/impeccable-svelte-movie-heading-bleed-repro DEEPSEEK_API_KEY=... node --test --test-timeout=600000 --test-name-pattern "movie-card" tmp/framework-tests/live-svelte-adapter-deepseek.test.mjs
• Fixed movie-heading bleed sweep: IMPECCABLE_SVELTE_DEEPSEEK_ARTIFACT_DIR=/tmp/impeccable-svelte-movie-heading-bleed-fixed DEEPSEEK_API_KEY=... node --test --test-timeout=600000 --test-name-pattern "movie-card" tmp/framework-tests/live-svelte-adapter-deepseek.test.mjs
• Red repro before movie-card accept cleanup: IMPECCABLE_SVELTE_DEEPSEEK_ARTIFACT_DIR=/tmp/impeccable-svelte-movie-accept-duplicate-repro DEEPSEEK_API_KEY=... node --test --test-timeout=600000 --test-name-pattern "movie-card accept" tmp/framework-tests/live-svelte-adapter-deepseek.test.mjs
• Fixed movie-card accept cleanup sweep: IMPECCABLE_SVELTE_DEEPSEEK_ARTIFACT_DIR=/tmp/impeccable-svelte-movie-accept-duplicate-fixed DEEPSEEK_API_KEY=... node --test --test-timeout=600000 --test-name-pattern "movie-card accept" tmp/framework-tests/live-svelte-adapter-deepseek.test.mjs
• Shader-lab proxy sweep after heading fix: IMPECCABLE_SVELTE_DEEPSEEK_ARTIFACT_DIR=/tmp/impeccable-svelte-framework-proxy-after-heading-fix DEEPSEEK_API_KEY=... node --test --test-timeout=600000 --test-name-pattern "framework proxy" tmp/framework-tests/live-svelte-adapter-deepseek.test.mjs
• bun run test

DeepSeek / Visual Evidence

• Provider/model: DeepSeek, deepseek-v4-flash.
• Focused open-count artifact directory: /tmp/impeccable-svelte-open-count-fixed-final.
• Focused split-count artifact directory: /tmp/impeccable-svelte-split-count-fixed.
• Focused movie-card shader artifact directory: /tmp/impeccable-svelte-shader-crop-fixed.
• Focused shader-lab proxy artifact directory: /tmp/impeccable-svelte-framework-proxy-fixed.
• Focused movie-card post-proxy artifact directory: /tmp/impeccable-svelte-movie-card-shader-after-proxy-fix.
• Focused movie-card heading-bleed artifact directory: /tmp/impeccable-svelte-movie-heading-bleed-fixed.
• Focused movie-card accept-cleanup artifact directory: /tmp/impeccable-svelte-movie-accept-duplicate-fixed.
• Focused shader-lab proxy after heading fix artifact directory: /tmp/impeccable-svelte-framework-proxy-after-heading-fix.
• The shader-lab proxy run injects the Svelte framework-proxy card into a temp copy of /Users/abdulwahab/impeccable-live-svelte, captures original/proxy/shader/variant screenshots, and verifies debugState().shaderCapture.strategy === "ancestor-crop" with capture root .shader-proxy-shell, zero rect drift, and painted shader pixels.
• The movie-card shader run covers the real external Svelte app flow for .movie-grid > li:first-child .movie-card, captures original card, heading, selected chrome, generating shader, and both variants, asserts the shader rect matches the selected card within 2px, asserts the shader crop is visually closer to the card than to the Films (API practice) heading, and now verifies document-backed translucent cards use direct-composited-backdrop with capture root article.movie-card rather than body/html.
• The movie-card accept-cleanup run captures original grid, selected chrome, generating shader, both variants, immediate post-accept grid, and post-refresh grid; it asserts the grid remains exactly 9 list items/cards and Castle in the Sky appears once immediately after Accept.
• The split-count run covers the real 2 offen browser path, captures original and variant screenshots, asserts every mounted Svelte variant renders exact normalized text 2 offen, verifies the numeric text run has nonzero bounds/painted pixels, and discards cleanly.
• Earlier external Svelte smoke artifact directory: /tmp/impeccable-live-svelte-external-pr196-2026-06-02T23-28-51-245Z.
• The broader local exhaustive visual sweep remains ignored under tmp/framework-tests/ per request and is not part of this PR diff.

Svelte App Install Check

• Installed the rebuilt generated skill into /Users/abdulwahab/impeccable-live-svelte under .cursor/skills/impeccable and .agents/skills/impeccable.
• Verified both installed live-browser.js copies contain direct-composited-backdrop, captureElementDirectCompositedForShader, cssColorAlpha, and paintsOpaqueOwnShaderSurface.
• Verified both installed live-svelte-component.mjs copies contain the updated Svelte expression extraction path.
• Did not start or stop the app dev server or live helper server there.

Draft Status

This PR remains draft for reviewer/maintainer inspection.

---

Note

Medium Risk
Large changes to in-browser live mode (DOM binding, accept, shader capture) on a critical user path; scope is preview/UX tooling rather than auth or persistence, with mirrored skill copies increasing review surface.

Overview
This PR extracts Svelte/SvelteKit live-mode rules into reference/live-svelte.md, keeps live.md framework-neutral, and has wrap/insert/inject (and boot via live.mjs) emit guidanceRefs so agents load the adapter doc when previewMode is svelte-component.

Runtime and accept-path hardening in live-browser.js and live-svelte-component.mjs includes: requiring a visible mounted Svelte variant before cycling (with remount recovery), richer anchor resolution (stable attrs, ignoring svelte-* classes), structural mapping of live text to propContract, toggle params using data-p-*="true", Tune panel hit-testing via composedPath, and shader capture strategies (direct, composited backdrop, ancestor crop) with debug metadata for translucent Svelte surfaces.

Accept cleanup for Svelte component previews now tears down preview wrappers without leaving duplicate DOM beside HMR output; prop extraction skips control blocks and deduplicates prop names; accepted CSS sanitization aligns boolean param selectors with live preview.

^{Reviewed by Cursor Bugbot for commit ebafd00. Bugbot is set up for automated code reviews on this repo. Configure here.}

[abdulwahabone]

Found another bug. fixing