Interactive Page Repost Publisher
Use this skill when the source page is not a normal Markdown/article import:
- custom elements, canvas/SVG demos, sliders, inline scripts
- page-local JS bundle is required to understand the content
- the user wants both article searchability and preserved interaction
- the interactive page itself must support Chinese/English switching
Companion Skills
- Required:
../staticflow-cli-publisher/SKILL.md
- Required for article translation and summary quality:
../article-bilingual-translation-publisher/SKILL.md
- Optional for mixed-source normalization:
../external-blog-repost-publisher/SKILL.md
Non-Negotiable Rules
Rule 1: Interactive view is a standalone local page
- Do not forward the user to the origin URL.
- Do not rely on remote JS/CSS/image assets at runtime.
- Serve the mirror from StaticFlow backend route:
/interactive-pages/<page_id>?lang=zh
/interactive-pages/<page_id>?lang=en
Rule 2: Do not inject the interactive page into normal article HTML
- The article page is for search, SEO, summary, and the “open interactive” CTA.
- The interactive experience lives in its own HTML page.
- Avoid trying to run source page scripts inside the normal SPA article body.
Rule 3: All mirror assets go into LanceDB
- Mirror assets belong in:
interactive_pages
interactive_assets
interactive_page_locales
- Do not keep the production mirror only on disk.
Rule 4: Publish in two tracks
- Track A:
articles
- Chinese translated body in
content
- normalized English source body in
content_en
- bilingual
detailed_summary.zh/en
- Track B: interactive mirror
- base locale from the captured source page
- localized locale variants via
interactive add-locale
Rule 5: Localized interaction is part of the deliverable
- It is not enough to translate only the article body.
- The interactive UI itself must have localized assets if the user asks for Chinese/English switching.
- After adding a non-source locale,
interactive_pages.translation_scope should become article_and_interactive.
Rule 6: Localized interactive pages must preserve source fidelity
- Localized pages should remain as close to the source DOM structure as practical.
- Do not flatten or regenerate source code blocks if that would drop syntax-highlighting classes or visual styling hooks.
- Preserve original visual behavior, code highlighting, component structure, and interaction wiring unless a change is required for localization.
- Translation quality target is a faithful full-text translation, not a shortened rewrite.
Rule 7: Raw localized entries must remain single-locale
/interactive-pages/<page_id>/entry?lang=zh must read as a Chinese-first page and must not embed a full English article body.
/interactive-pages/<page_id>/entry?lang=en must read as an English-first page and must not embed a full Chinese article body.
- Do not stack two full-language article bodies inside one raw entry.
- Do not treat “English source page + appended Chinese translation block” as acceptable localization.
Rule 8: Bilingual comparison belongs to the article track
- Bilingual comparison is allowed in
articles.content / articles.content_en or article detail UI.
- Raw interactive entries must not implement bilingual comparison by appending a second full-language article below the first.
/interactive-pages/<page_id>/entry?lang=<locale> is a localized mirror, not a side-by-side bilingual view.
Rule 9: Translation source must be clean
- If the currently published LanceDB article body is malformed, do not reuse it as translation source material.
- Rebuild bilingual article artifacts from source HTML, clean source Markdown, or another verified clean extraction.
- Existing broken reposts require a rebuild from clean source, not patch stacking on top of corrupted Markdown.
Rule 10: Provide direct access to the raw localized entry page
- The standalone wrapper is useful, but it is not the only entry.
- The user should be able to open the current-language raw render directly:
/interactive-pages/<page_id>/entry?lang=zh
/interactive-pages/<page_id>/entry?lang=en
- If a wrapper shell exists, include a visible CTA that opens the current-language raw render.
Rule 11: Verify routes, DB rows, and real interaction after write
- Query the DB rows after publish.
- Open the local mirror route and confirm it renders.
- Verify core interaction still works after localization.
- Verify localized copy on real rendered frames, not only the landing screen.
Rule 12: Article date should default to the import date
- Unless the user explicitly asks to preserve the source publication date in
articles.date, use the actual import date.
- If the source article has its own original publication date, mention it in the article body or attribution instead of reusing it as the StaticFlow article date by default.
Rule 13: Do not capture the executed DOM as the entry HTML
- For JS-heavy pages, the entry HTML should come from the original fetched response HTML whenever practical.
- Do not serialize
document.documentElement.outerHTML after the page has already executed and mutated the DOM unless the task specifically requires a post-init snapshot.
- Otherwise replay can duplicate runtime-generated nodes, causing overlapping titles, SVGs, or other animated content on reload.
Default DB
- Unless the user says otherwise, use:
/mnt/wsl/data4tb/static-flow-data/lancedb
Naming and Storage Conventions
articles.id: stable article id, e.g. bloom-filters
interactive_pages.id: ipg-<article_id>, e.g. ipg-bloom-filters
- localized interactive assets should usually live under:
localized/zh/...
localized/en/...
Workflow
Step 1: Confirm this page needs the interactive pipeline
Use this skill instead of normal repost when:
- the page depends on page-specific JS to make sense
- the page uses custom elements or heavy DOM initialization
- screenshots or plain Markdown would lose the core teaching value
Step 2: Prepare bilingual article artifacts
Create under /tmp/interactive_repost/<article_id>/:
content_zh.md
content_en.md
summary_zh.md
summary_en.md
Requirements:
content_en must be a normalized English source article, not a recap
content must be a polished Chinese translation
- both should include attribution and source URL
Step 3: Capture and ingest the base interactive mirror
Use sf-cli interactive ingest-page.
Canonical command:
cargo run -q -p sf-cli -- interactive \
--db-path /mnt/wsl/data4tb/static-flow-data/lancedb \
ingest-page \
--url "<source_url>" \
--article-id "<article_id>" \
--file /tmp/interactive_repost/<article_id>/content_zh.md \
--summary "<short_summary>" \
--tags "tag-a,tag-b" \
--category "<category>" \
--category-description "<category_description>" \
--content-en-file /tmp/interactive_repost/<article_id>/content_en.md \
--summary-zh-file /tmp/interactive_repost/<article_id>/summary_zh.md \
--summary-en-file /tmp/interactive_repost/<article_id>/summary_en.md \
--author ackingliu \
--allow-host "<expected_host>"
Notes:
--capture-script defaults to scripts/capture_interactive_page.mjs
--capture-manifest can be used to skip a fresh Playwright capture
- Prefer passing
--date <import-date> explicitly so the stored article date matches the ingest date.
- base ingest creates:
articles.article_kind = interactive_repost
articles.source_url
articles.interactive_page_id = ipg-<article_id>
interactive_pages
interactive_assets
Capture guidance:
- Rewrite asset URLs against the source response HTML, then store that rewritten source HTML as the entry page.
- Remove or neutralize source
<base> tags when mirroring so local asset routing stays stable.
- If runtime URL patching is used, make it skip already-local
/api/interactive-pages/... asset paths to avoid double rewrite and 404s.
Step 4: Build localized interactive assets
If the user needs Chinese/English switching inside the interactive page:
- create localized HTML/JS/CSS assets
- generate a capture-manifest style JSON for that locale
- add the locale with
sf-cli interactive add-locale
Canonical command:
cargo run -q -p sf-cli -- interactive \
--db-path /mnt/wsl/data4tb/static-flow-data/lancedb \
add-locale \
--page-id "ipg-<article_id>" \
--locale zh \
--title "<localized_title>" \
--manifest /tmp/interactive_repost/<article_id>/locale-zh-manifest.json
Expectations:
- localized assets are written into
interactive_assets
- locale metadata is written into
interactive_page_locales
- old assets under
localized/<locale>/ are replaced
- localized HTML should preserve original classes/markup needed for syntax highlighting and page styling
- translated interactive content should cover the source text as completely as practical
Locale QA requirements before add-locale:
- Audit the localized HTML/JS assets for leftover user-visible English sentences, especially frame scripts that update subtitles over time.
- Do not stop at the first frame; inspect later frames such as election, replication, partition recovery, conclusion, and any direct-entry hash routes.
- If you manually patch localized asset files after generating the locale manifest, refresh the manifest
sha256 values before publishing.
- Confirm the localized raw entry is single-locale, not a bilingual stacked page.
- Confirm there is no malformed Jekyll macro residue, broken table markdown, or raw template marker carried over from a previous repost.
- If the existing LanceDB article content is malformed, regenerate bilingual article artifacts from clean source before publishing the locale.
Step 5: Frontend entry policy
- Article detail should open the local mirror directly.
- Preferred user-facing entry:
/interactive-pages/ipg-<article_id>?lang=zh
- Old SPA helper routes may exist, but the final experience should land on the standalone mirror page.
- If a shell/wrapper page is used, it should also expose a direct CTA to:
/interactive-pages/ipg-<article_id>/entry?lang=<locale>
Step 6: Verify after write
DB verification:
cargo run -q -p sf-cli -- db --db-path /mnt/wsl/data4tb/static-flow-data/lancedb \
query-rows articles --where "id = '<article_id>'" --limit 1
cargo run -q -p sf-cli -- db --db-path /mnt/wsl/data4tb/static-flow-data/lancedb \
query-rows interactive_pages --where "id = 'ipg-<article_id>'" --limit 1
cargo run -q -p sf-cli -- db --db-path /mnt/wsl/data4tb/static-flow-data/lancedb \
query-rows interactive_page_locales --where "page_id = 'ipg-<article_id>'" --limit 10
Route verification:
curl -I "http://127.0.0.1:39123/interactive-pages/ipg-<article_id>?lang=zh"
curl -I "http://127.0.0.1:39123/interactive-pages/ipg-<article_id>/entry?lang=zh"
Behavior verification:
- open the mirror page in a browser
- switch
中文 / English
- open the current-language raw entry page directly
- confirm the key buttons/sliders/graphs still work
- click through multiple steps in later frames, not just the first
Continue
- confirm syntax highlighting and original visual styling still render correctly
- confirm there are no duplicated runtime-generated elements after reload such as overlapping titles, subtitles, or SVG scenes
- confirm requests are served from
/api/interactive-pages/<page_id>/assets/...
- confirm there are no obvious leftover English sentences in the localized locale except intentional protocol names / proper nouns
- confirm
/entry?lang=<locale> does not embed a full second-language article body below the localized one
Deliverable Checklist
articles row exists and is queryable from frontend
interactive_pages.status = ready
interactive_pages.translation_scope
article_only for source-only mirror
article_and_interactive after localized interactive locale is added
- localized interactive route opens and is readable
- current-language raw entry route opens directly and remains readable
- article detail contains a strong CTA to open the interactive page
- wrapper shell contains a visible CTA to open the raw current-language render
- no runtime dependence on the original host for mirrored assets
Failure Handling
- If the source host is not on the allowed list, stop before mirroring or use an explicit override.
- If the page only renders a shell, retry with Playwright capture before giving up.
- If localized assets break interaction, keep the original locale intact and fix the locale manifest/assets before re-running
add-locale.
- If localization looks partly translated, inspect the localized frame scripts and other runtime text sources before blaming routing.
- If the article is already published, preserve unrelated fields unless the user explicitly asks for overwrite.
Working Example
https://samwho.dev/bloom-filters/
- article id:
bloom-filters
- page id:
ipg-bloom-filters
- expected frontend entry:
/interactive-pages/ipg-bloom-filters?lang=zh
1---2name: interactive-page-repost-publisher3description: >-4 Ingest JS-heavy external pages into StaticFlow as standalone local5 interactive mirrors backed by LanceDB assets, with bilingual article6 write-back and localized interactive locales.7metadata:8 source: https://skillmd.com/skills/zero-yx/interactive-page-repost-publisher9---1011# Interactive Page Repost Publisher1213Use this skill when the source page is not a normal Markdown/article import:14- custom elements, canvas/SVG demos, sliders, inline scripts15- page-local JS bundle is required to understand the content16- the user wants both article searchability and preserved interaction17- the interactive page itself must support Chinese/English switching1819## Companion Skills20- Required: `../staticflow-cli-publisher/SKILL.md`21- Required for article translation and summary quality: `../article-bilingual-translation-publisher/SKILL.md`22- Optional for mixed-source normalization: `../external-blog-repost-publisher/SKILL.md`2324## Non-Negotiable Rules2526### Rule 1: Interactive view is a standalone local page27- Do not forward the user to the origin URL.28- Do not rely on remote JS/CSS/image assets at runtime.29- Serve the mirror from StaticFlow backend route:30 - `/interactive-pages/<page_id>?lang=zh`31 - `/interactive-pages/<page_id>?lang=en`3233### Rule 2: Do not inject the interactive page into normal article HTML34- The article page is for search, SEO, summary, and the “open interactive” CTA.35- The interactive experience lives in its own HTML page.36- Avoid trying to run source page scripts inside the normal SPA article body.3738### Rule 3: All mirror assets go into LanceDB39- Mirror assets belong in:40 - `interactive_pages`41 - `interactive_assets`42 - `interactive_page_locales`43- Do not keep the production mirror only on disk.4445### Rule 4: Publish in two tracks46- Track A: `articles`47 - Chinese translated body in `content`48 - normalized English source body in `content_en`49 - bilingual `detailed_summary.zh/en`50- Track B: interactive mirror51 - base locale from the captured source page52 - localized locale variants via `interactive add-locale`5354### Rule 5: Localized interaction is part of the deliverable55- It is not enough to translate only the article body.56- The interactive UI itself must have localized assets if the user asks for Chinese/English switching.57- After adding a non-source locale, `interactive_pages.translation_scope` should become `article_and_interactive`.5859### Rule 6: Localized interactive pages must preserve source fidelity60- Localized pages should remain as close to the source DOM structure as practical.61- Do not flatten or regenerate source code blocks if that would drop syntax-highlighting classes or visual styling hooks.62- Preserve original visual behavior, code highlighting, component structure, and interaction wiring unless a change is required for localization.63- Translation quality target is a faithful full-text translation, not a shortened rewrite.6465### Rule 7: Raw localized entries must remain single-locale66- `/interactive-pages/<page_id>/entry?lang=zh` must read as a Chinese-first page and must not embed a full English article body.67- `/interactive-pages/<page_id>/entry?lang=en` must read as an English-first page and must not embed a full Chinese article body.68- Do not stack two full-language article bodies inside one raw entry.69- Do not treat “English source page + appended Chinese translation block” as acceptable localization.7071### Rule 8: Bilingual comparison belongs to the article track72- Bilingual comparison is allowed in `articles.content` / `articles.content_en` or article detail UI.73- Raw interactive entries must not implement bilingual comparison by appending a second full-language article below the first.74- `/interactive-pages/<page_id>/entry?lang=<locale>` is a localized mirror, not a side-by-side bilingual view.7576### Rule 9: Translation source must be clean77- If the currently published LanceDB article body is malformed, do not reuse it as translation source material.78- Rebuild bilingual article artifacts from source HTML, clean source Markdown, or another verified clean extraction.79- Existing broken reposts require a rebuild from clean source, not patch stacking on top of corrupted Markdown.8081### Rule 10: Provide direct access to the raw localized entry page82- The standalone wrapper is useful, but it is not the only entry.83- The user should be able to open the current-language raw render directly:84 - `/interactive-pages/<page_id>/entry?lang=zh`85 - `/interactive-pages/<page_id>/entry?lang=en`86- If a wrapper shell exists, include a visible CTA that opens the current-language raw render.8788### Rule 11: Verify routes, DB rows, and real interaction after write89- Query the DB rows after publish.90- Open the local mirror route and confirm it renders.91- Verify core interaction still works after localization.92- Verify localized copy on real rendered frames, not only the landing screen.9394### Rule 12: Article date should default to the import date95- Unless the user explicitly asks to preserve the source publication date in `articles.date`, use the actual import date.96- If the source article has its own original publication date, mention it in the article body or attribution instead of reusing it as the StaticFlow article date by default.9798### Rule 13: Do not capture the executed DOM as the entry HTML99- For JS-heavy pages, the entry HTML should come from the original fetched response HTML whenever practical.100- Do not serialize `document.documentElement.outerHTML` after the page has already executed and mutated the DOM unless the task specifically requires a post-init snapshot.101- Otherwise replay can duplicate runtime-generated nodes, causing overlapping titles, SVGs, or other animated content on reload.102103## Default DB104- Unless the user says otherwise, use:105 - `/mnt/wsl/data4tb/static-flow-data/lancedb`106107## Naming and Storage Conventions108- `articles.id`: stable article id, e.g. `bloom-filters`109- `interactive_pages.id`: `ipg-<article_id>`, e.g. `ipg-bloom-filters`110- localized interactive assets should usually live under:111 - `localized/zh/...`112 - `localized/en/...`113114## Workflow115116### Step 1: Confirm this page needs the interactive pipeline117Use this skill instead of normal repost when:118- the page depends on page-specific JS to make sense119- the page uses custom elements or heavy DOM initialization120- screenshots or plain Markdown would lose the core teaching value121122### Step 2: Prepare bilingual article artifacts123Create under `/tmp/interactive_repost/<article_id>/`:124- `content_zh.md`125- `content_en.md`126- `summary_zh.md`127- `summary_en.md`128129Requirements:130- `content_en` must be a normalized English source article, not a recap131- `content` must be a polished Chinese translation132- both should include attribution and source URL133134### Step 3: Capture and ingest the base interactive mirror135Use `sf-cli interactive ingest-page`.136137Canonical command:138139```bash140cargo run -q -p sf-cli -- interactive \141 --db-path /mnt/wsl/data4tb/static-flow-data/lancedb \142 ingest-page \143 --url "<source_url>" \144 --article-id "<article_id>" \145 --file /tmp/interactive_repost/<article_id>/content_zh.md \146 --summary "<short_summary>" \147 --tags "tag-a,tag-b" \148 --category "<category>" \149 --category-description "<category_description>" \150 --content-en-file /tmp/interactive_repost/<article_id>/content_en.md \151 --summary-zh-file /tmp/interactive_repost/<article_id>/summary_zh.md \152 --summary-en-file /tmp/interactive_repost/<article_id>/summary_en.md \153 --author ackingliu \154 --allow-host "<expected_host>"155```156157Notes:158- `--capture-script` defaults to `scripts/capture_interactive_page.mjs`159- `--capture-manifest` can be used to skip a fresh Playwright capture160- Prefer passing `--date <import-date>` explicitly so the stored article date matches the ingest date.161- base ingest creates:162 - `articles.article_kind = interactive_repost`163 - `articles.source_url`164 - `articles.interactive_page_id = ipg-<article_id>`165 - `interactive_pages`166 - `interactive_assets`167168Capture guidance:169- Rewrite asset URLs against the source response HTML, then store that rewritten source HTML as the entry page.170- Remove or neutralize source `<base>` tags when mirroring so local asset routing stays stable.171- If runtime URL patching is used, make it skip already-local `/api/interactive-pages/...` asset paths to avoid double rewrite and 404s.172173### Step 4: Build localized interactive assets174If the user needs Chinese/English switching inside the interactive page:1751. create localized HTML/JS/CSS assets1762. generate a capture-manifest style JSON for that locale1773. add the locale with `sf-cli interactive add-locale`178179Canonical command:180181```bash182cargo run -q -p sf-cli -- interactive \183 --db-path /mnt/wsl/data4tb/static-flow-data/lancedb \184 add-locale \185 --page-id "ipg-<article_id>" \186 --locale zh \187 --title "<localized_title>" \188 --manifest /tmp/interactive_repost/<article_id>/locale-zh-manifest.json189```190191Expectations:192- localized assets are written into `interactive_assets`193- locale metadata is written into `interactive_page_locales`194- old assets under `localized/<locale>/` are replaced195- localized HTML should preserve original classes/markup needed for syntax highlighting and page styling196- translated interactive content should cover the source text as completely as practical197198Locale QA requirements before `add-locale`:199- Audit the localized HTML/JS assets for leftover user-visible English sentences, especially frame scripts that update subtitles over time.200- Do not stop at the first frame; inspect later frames such as election, replication, partition recovery, conclusion, and any direct-entry hash routes.201- If you manually patch localized asset files after generating the locale manifest, refresh the manifest `sha256` values before publishing.202- Confirm the localized raw entry is single-locale, not a bilingual stacked page.203- Confirm there is no malformed Jekyll macro residue, broken table markdown, or raw template marker carried over from a previous repost.204- If the existing LanceDB article content is malformed, regenerate bilingual article artifacts from clean source before publishing the locale.205206### Step 5: Frontend entry policy207- Article detail should open the local mirror directly.208- Preferred user-facing entry:209 - `/interactive-pages/ipg-<article_id>?lang=zh`210- Old SPA helper routes may exist, but the final experience should land on the standalone mirror page.211- If a shell/wrapper page is used, it should also expose a direct CTA to:212 - `/interactive-pages/ipg-<article_id>/entry?lang=<locale>`213214### Step 6: Verify after write215DB verification:216217```bash218cargo run -q -p sf-cli -- db --db-path /mnt/wsl/data4tb/static-flow-data/lancedb \219 query-rows articles --where "id = '<article_id>'" --limit 1220221cargo run -q -p sf-cli -- db --db-path /mnt/wsl/data4tb/static-flow-data/lancedb \222 query-rows interactive_pages --where "id = 'ipg-<article_id>'" --limit 1223224cargo run -q -p sf-cli -- db --db-path /mnt/wsl/data4tb/static-flow-data/lancedb \225 query-rows interactive_page_locales --where "page_id = 'ipg-<article_id>'" --limit 10226```227228Route verification:229230```bash231curl -I "http://127.0.0.1:39123/interactive-pages/ipg-<article_id>?lang=zh"232curl -I "http://127.0.0.1:39123/interactive-pages/ipg-<article_id>/entry?lang=zh"233```234235Behavior verification:236- open the mirror page in a browser237- switch `中文 / English`238- open the current-language raw entry page directly239- confirm the key buttons/sliders/graphs still work240- click through multiple steps in later frames, not just the first `Continue`241- confirm syntax highlighting and original visual styling still render correctly242- confirm there are no duplicated runtime-generated elements after reload such as overlapping titles, subtitles, or SVG scenes243- confirm requests are served from `/api/interactive-pages/<page_id>/assets/...`244- confirm there are no obvious leftover English sentences in the localized locale except intentional protocol names / proper nouns245- confirm `/entry?lang=<locale>` does not embed a full second-language article body below the localized one246247## Deliverable Checklist248- `articles` row exists and is queryable from frontend249- `interactive_pages.status = ready`250- `interactive_pages.translation_scope`251 - `article_only` for source-only mirror252 - `article_and_interactive` after localized interactive locale is added253- localized interactive route opens and is readable254- current-language raw entry route opens directly and remains readable255- article detail contains a strong CTA to open the interactive page256- wrapper shell contains a visible CTA to open the raw current-language render257- no runtime dependence on the original host for mirrored assets258259## Failure Handling260- If the source host is not on the allowed list, stop before mirroring or use an explicit override.261- If the page only renders a shell, retry with Playwright capture before giving up.262- If localized assets break interaction, keep the original locale intact and fix the locale manifest/assets before re-running `add-locale`.263- If localization looks partly translated, inspect the localized frame scripts and other runtime text sources before blaming routing.264- If the article is already published, preserve unrelated fields unless the user explicitly asks for overwrite.265266## Working Example267- `https://samwho.dev/bloom-filters/`268- article id: `bloom-filters`269- page id: `ipg-bloom-filters`270- expected frontend entry:271 - `/interactive-pages/ipg-bloom-filters?lang=zh`