메뉴
Use when modifying the iframe DOM mirror (server `sanitize.ts`) or the in-iframe overlay script (`frontend/src/lib/overlay.ts`). Covers the sanitization pipeline rules, the overlay script contract, the postMessage protocol, and the cross-package sync requirement.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Use when opening a pull request for this repository. Enforces atomic commits, the required PR body shape (quick explainer of what we're doing + why), and the mandatory assignee.
Use when adding or modifying a Fastify route in `server/src/routes/`. Covers the buildApp DI pattern, request validation with Fastify schemas, error mapping per `09-api-contracts.md`, and the matching test template.
Use when adding or modifying a Stimulus controller in `frontend/src/controllers/`. Covers naming, registration, targets/values/actions conventions, custom events, and the matching test template.
Use when writing or running tests in either package (frontend Stimulus/lib or server Fastify/sanitizer/Playwright). Provides Vitest setup, mounting helpers, route inject patterns, and Playwright stubbing templates.
| name | dom-mirror-overlay |
| description | Use when modifying the iframe DOM mirror (server `sanitize.ts`) or the in-iframe overlay script (`frontend/src/lib/overlay.ts`). Covers the sanitization pipeline rules, the overlay script contract, the postMessage protocol, and the cross-package sync requirement. |
This pair of components is the trickiest part of the system. Read
docs/07-dom-mirror.md and docs/09-api-contracts.md before changing
anything here.
Order of operations in server/src/sanitize.ts (DO NOT reorder without
updating tests):
script, noscript, iframe, object,
embed, link[rel="manifest"], link[rel*="prefetch"], SW regs.on*).javascript: URLs from href/src/action.baseUrl.
Targets: href, src, srcset, poster, action, data,
style url(...).<base target="_top"> in <head>.deps.fetcher. On any
failure, leave the <link> untouched.<script> tag at the end of
<body>. The script carries no marker attribute; the overlay IIFE
guards itself against double-install by setting
window[OVERLAY_INSTALLED_FLAG] on first run and short-circuiting
on subsequent runs. The sanitizer therefore appends
unconditionally — any pre-existing overlay <script> from a prior
sanitize pass was already removed in step 1.Each rule has a dedicated test. When adding a rule, add the test first.
frontend/src/lib/overlay.ts exports a single overlayScript: string.
This string must be:
window[OVERLAY_INSTALLED_FLAG] = true on first run and bails on
every subsequent run. Do not reintroduce a parallel marker (e.g. a
data-* attribute on the injected <script>); a single source of
truth keeps the two packages from drifting.document.body and window listeners it
installs.What it does:
DOMContentLoaded, post { source, type: "overlay_ready" }.dragover: compute elementFromPoint, walk up to the nearest
non-html/non-body element, apply outline + a small floating label
(positioned absolute, pointer-events: none).dragleave / drag end: clear the outline.drop: compute the selector via the shared selector.ts
algorithm (inlined into the bundle that produces the script string),
then post { source, type: "tag_dropped", selector }.click on links/forms inside the document and calls
preventDefault() so the user never accidentally navigates the
srcdoc.Constants:
const SOURCE = "iframe-scrapper-overlay";
Parent ↔ overlay messages always carry source: "iframe-scrapper-overlay".
Anything else is ignored on both ends.
| Direction | type | payload |
|---|---|---|
| overlay → parent | overlay_ready | — |
| overlay → parent | tag_dropped | { selector: string } |
Future (not v1): place_marker, clear_marker going parent → overlay.
The overlay script lives in frontend/src/lib/overlay.ts but is served
by the sidecar inside the sanitized HTML. Two acceptable approaches:
Approach A (preferred): build-time copy.
A tiny server/scripts/sync-overlay.ts reads
frontend/src/lib/overlay.ts, extracts the overlayScript constant
content, and writes server/src/overlay.generated.ts. Run as a
prebuild/predev step in the server package. A unit test asserts
the two strings match (regenerates and diffs in the test).
Approach B: source-of-truth in shared text file.
Put the overlay JS in shared/overlay.js and have both packages import
its contents via Vite's ?raw and Node's fs.readFileSync. Adds a
shared dir but avoids generation.
Pick A for v1. Document the script in the file header.
docs/11-testing.md § sanitizer rules.iframe.srcdoc = "<html><body>" + sample + "<script>" + overlayScript + "</script></body></html>",
then drive dragover/drop events and listen for messages on
window.expect(serverOverlayCopy).toBe(frontendOverlayCopy).document.documentElement from the overlay. Stick to
document.body.source discriminator.overlay.ts — the file's content
becomes a string shipped to the browser; keep it tiny.