![\"${USERNAME}\"](\"https://github.com/${USERNAME}.png\" "\\"${USERNAME}\\"")
"
+ done
+ echo "$GALLERY_HTML" > gallery_fragment.txt
+
+ - name: Update README.md
+ run: |
+ set -euo pipefail
+ # Safety check for markers
+ start_count=$(grep -c '' README.md || true)
+ end_count=$(grep -c '' README.md || true)
+ if [ "$start_count" -ne 1 ] || [ "$end_count" -ne 1 ]; then
+ echo "Error: README.md must contain exactly one pair of markers."
+ exit 1
+ fi
+
+ start_line=$(grep -n '' README.md | cut -d: -f1)
+ end_line=$(grep -n '' README.md | cut -d: -f1)
+ if [ "$start_line" -ge "$end_line" ]; then
+ echo "Error: CONTRIBUTORS_START must appear before CONTRIBUTORS_END."
+ exit 1
+ fi
+
+ sed -i '//,// {
+ //! { //! d; }
+ }' README.md
+ sed -i '//r gallery_fragment.txt' README.md
+
+ - name: Commit and Push
+ run: |
+ git config --global user.name "github-actions[bot]"
+ git config --global user.email "github-actions[bot]@users.noreply.github.com"
+ git add README.md
+ if git diff --staged --quiet; then
+ echo "No changes to README."
+ else
+ git commit -m "docs: update contributor gallery"
+ git push
+ fi
diff --git a/.github/workflows/gssoc-labeler.yml b/.github/workflows/gssoc-labeler.yml
new file mode 100644
index 0000000..cdc3eab
--- /dev/null
+++ b/.github/workflows/gssoc-labeler.yml
@@ -0,0 +1,45 @@
+name: GSSoC Labeler
+
+on:
+ issues:
+ types: [opened, edited]
+ pull_request_target:
+ types: [opened, edited]
+
+jobs:
+ label_gssoc:
+ runs-on: ubuntu-latest
+
+ permissions:
+ issues: write
+ pull-requests: write
+
+ steps:
+ - name: Check and add GSSoC label
+ uses: actions/github-script@v7
+ with:
+ script: |
+ let bodyText = "";
+ let issueNum = null;
+
+ if (context.payload.issue?.body) {
+ bodyText = context.payload.issue.body;
+ issueNum = context.payload.issue.number;
+ }
+ else if (context.payload.pull_request?.body) {
+ bodyText = context.payload.pull_request.body;
+ issueNum = context.payload.pull_request.number;
+ }
+
+ const isGSSoC =
+ bodyText.includes("[x] I am participating in GSSoC 2026") ||
+ bodyText.includes("[X] I am participating in GSSoC 2026");
+
+ if (isGSSoC && issueNum) {
+ await github.rest.issues.addLabels({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: issueNum,
+ labels: ["gssoc:accepted"],
+ });
+ }
diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml
new file mode 100644
index 0000000..2756720
--- /dev/null
+++ b/.github/workflows/labeler.yml
@@ -0,0 +1,69 @@
+name: Auto Label Issues and PRs
+
+on:
+ pull_request:
+ types: [opened, synchronize, reopened]
+ issues:
+ types: [opened, reopened]
+
+permissions:
+ contents: read
+ issues: write
+ pull-requests: write
+
+jobs:
+ label-pr:
+ name: Label Pull Requests
+ runs-on: ubuntu-latest
+ if: github.event_name == 'pull_request'
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Apply labels based on changed files
+ uses: actions/labeler@v5
+ with:
+ repo-token: "${{ secrets.GITHUB_TOKEN }}"
+ configuration-path: .github/labeler.yml
+
+ label-issue:
+ name: Label Issues
+ runs-on: ubuntu-latest
+ if: github.event_name == 'issues'
+ steps:
+ - name: Label new issues with gssoc26
+ uses: actions/github-script@v7
+ with:
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+ script: |
+ const issue = context.payload.issue;
+ const body = (issue.body || '').toLowerCase();
+ const title = (issue.title || '').toLowerCase();
+
+ const labelsToAdd = ['gssoc26'];
+
+ if (title.includes('bug') || body.includes('bug')) {
+ labelsToAdd.push('bug');
+ }
+ if (title.includes('feature') || body.includes('enhancement')) {
+ labelsToAdd.push('enhancement');
+ }
+ if (title.includes('docs') || body.includes('documentation')) {
+ labelsToAdd.push('documentation');
+ }
+ if (title.includes('level 1') || body.includes('level 1')) {
+ labelsToAdd.push('level1');
+ }
+ if (title.includes('level 2') || body.includes('level 2')) {
+ labelsToAdd.push('level2');
+ }
+ if (title.includes('level 3') || body.includes('level 3')) {
+ labelsToAdd.push('level3');
+ }
+
+ await github.rest.issues.addLabels({
+ owner: context.repo.owner,
+ repo: context.repo.repo,
+ issue_number: issue.number,
+ labels: labelsToAdd
+ });
diff --git a/.github/workflows/pr-merged-thanks.yml b/.github/workflows/pr-merged-thanks.yml
index 957008f..abd145f 100644
--- a/.github/workflows/pr-merged-thanks.yml
+++ b/.github/workflows/pr-merged-thanks.yml
@@ -8,7 +8,9 @@ jobs:
thank-contributor:
if: github.event.pull_request.merged == true
runs-on: ubuntu-latest
+
permissions:
+ pull-requests: write
issues: write
steps:
@@ -16,18 +18,17 @@ jobs:
uses: actions/github-script@v7
with:
script: |
- github.rest.issues.createComment({
+ await github.rest.issues.createComment({
issue_number: context.payload.pull_request.number,
owner: context.repo.owner,
repo: context.repo.repo,
- body: |
- š **Thank you for your contribution!**
+ body: `š **Thank you for your contribution!**
- Your Pull Request has been merged successfully.
+ Your Pull Request has been merged successfully.
- We appreciate the time and effort you put into improving this project. Contributions like yours help the repository grow and stay useful for everyone.
+ We appreciate the time and effort you put into improving this project. Contributions like yours help the repository grow and stay useful for everyone.
- If you'd like to contribute again, please check the open issues and make sure you are assigned before opening another Pull Request.
+ If you'd like to contribute again, please check the open issues and make sure you are assigned before opening another Pull Request.
- Thanks again for your support! š
- })
+ Thanks again for your support! š`
+ });
diff --git a/.gitignore b/.gitignore
index b7faf40..41e7fdf 100644
Binary files a/.gitignore and b/.gitignore differ
diff --git a/.local/secondary_skills/LICENSE.txt b/.local/secondary_skills/LICENSE.txt
new file mode 100644
index 0000000..2c6c47b
--- /dev/null
+++ b/.local/secondary_skills/LICENSE.txt
@@ -0,0 +1,21 @@
+Copyright (c) 2026 Replit, Inc. All rights reserved.
+
+The contents of this directory are proprietary to Replit, Inc. and are
+licensed for use solely within the Replit platform under the applicable
+Replit user terms. Use of the contents of this directory within the
+Replit platform, including by Replit users for commercial purposes, is
+unlimited and expressly permitted.
+
+Outside of the Replit platform, the contents of this directory are
+licensed under the Creative Commons Attribution-NonCommercial 4.0
+International License (CC BY-NC 4.0). You may obtain a copy of that
+license at:
+https://creativecommons.org/licenses/by-nc/4.0/
+
+Under CC BY-NC 4.0, you may share and adapt the contents of this
+directory for non-commercial purposes, provided you appropriately credit
+Replit, Inc. and indicate if changes were made. Commercial use of the
+contents of this directory outside of the Replit platform is strictly
+prohibited without a separate license from Replit, Inc.
+
+For commercial licensing inquiries, contact: support@replit.com
diff --git a/.local/secondary_skills/ad-creative/.fingerprint b/.local/secondary_skills/ad-creative/.fingerprint
new file mode 100644
index 0000000..8dc23b8
--- /dev/null
+++ b/.local/secondary_skills/ad-creative/.fingerprint
@@ -0,0 +1 @@
+9ddf6593609d4d0fcb1ab58f575522cd
\ No newline at end of file
diff --git a/.local/secondary_skills/ad-creative/SKILL.md b/.local/secondary_skills/ad-creative/SKILL.md
new file mode 100644
index 0000000..b9dded7
--- /dev/null
+++ b/.local/secondary_skills/ad-creative/SKILL.md
@@ -0,0 +1,872 @@
+---
+name: ad-creative
+description: Design static ad creatives for social media and display advertising campaigns.
+---
+
+# Ad Creative Maker
+
+Design static ad creatives for social media ads, display banners, and digital advertising campaigns. Build production-ready ads via the design subagent and present them as iframes on the canvas.
+
+## When to Use
+
+- User needs ad creatives for Facebook, Instagram, LinkedIn, Google Display, or TikTok
+- User wants banner ads or display advertising assets
+
+- User needs multiple ad variants for A/B testing
+- User wants ad copy and visual design together
+
+- User wants to iterate on ad creative based on performance data
+- User asks for carousel ads (Instagram, Facebook, X/Twitter)
+
+- User wants retargeting/remarketing ad creatives
+- User provides their own product photos or brand images and wants ads built around them
+
+- User needs ads in multiple sizes/formats (square + portrait + landscape)
+- User wants a product launch or teaser campaign
+
+- User wants seasonal or holiday-themed ads
+- User needs app install ad creatives
+
+- User wants to refresh or update existing ads without performance data
+- User asks to make ads that match their website's look and feel
+
+## When NOT to Use
+
+- Organic social media content (use content-machine skill)
+- Video ads or animated content (use storyboard skill for planning)
+
+- Full landing pages (use the artifacts skill)
+
+## Golden Rules (check before every ad)
+
+1. **<20 words total on the image** ā everything else goes in primary text / description fields
+2. **Only 4 elements per ad**: Logo, Hero, Benefit line, CTA button
+
+3. **Flat solid background colors only** ā no gradients, no patterns, no textures (exception: awareness/launch ads may use a hero image as the background)
+4. **Real brand logo, always** ā never substitute plain text for a logo (see Logo Extraction below)
+
+5. **Left-align content** ā logo top-left, text left-aligned, CTA left-aligned. Centered layouts look generic.
+
+## Methodology
+
+### Step 1: Creative Brief
+
+Gather: Platform and Format, Objective, Target audience, Key message, CTA, Brand assets, Performance data (if iterating).
+
+**Brand research (mandatory before building):** Always use web search to look up the brand's actual visual identity before designing. Search for `[brand] brand font typeface typography`and`[brand] brand colors hex`. Use the brand's real fonts, colors, and visual language ā never guess or substitute generic alternatives. If the official fonts are commercial/licensed, find the closest Google Fonts alternatives used in the brand's own guidelines. Common pairings: a sans-serif for headlines (e.g., Poppins) and a serif for body text (e.g., Lora). Include these in the subagent task instructions so every angle uses the correct brand identity.
+
+**Font loading (mandatory in every ad HTML):** After identifying the brand's fonts (or closest Google Fonts alternatives), include them in the head of every ad HTML file:
+
+```html
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+Always specify the exact weights needed (400, 700, 900). Never rely on browser defaults or system fonts ā every ad must load its fonts explicitly.
+
+**Extract real brand colors from the site (mandatory).** Do not trust web search results for colors ā they are frequently wrong. Instead, fetch the actual CSS from the brand's website:
+
+```bash
+
+curl -s -L "https://brand.com" | grep -iE '(theme-color|TileColor|mask-icon.*color)' | head -5
+
+curl -s -L "https://brand.com" | tr -d '\n' | grep -oP 'href="[^"]*\\css[^"]*"' | head -3
+
+curl -s "https://brand.com/path/to/style.css" | grep -oP '#[0-9a-fA-F]{3,8}' | sort -u
+
+```
+
+### Step 2: Platform Specifications (2025-2026)
+
+#### Meta (Facebook/Instagram) ā Visual
+
+| Placement | Dimensions | Safe zone |
+
+|---|---|---|
+
+| Feed (square) | 1080x1080 | ~100px margin all edges |
+
+| Feed (portrait) ā **preferred** | 1080x1350 (4:5) | 4:5 outperforms 1:1 on CTR |
+
+| Stories | 1080x1920 | Top 14% + bottom 20% = dead zones |
+
+| Reels | 1080x1920 | Top 14% + bottom 35% = dead zones |
+
+| **Universal safe core**|**1010x1280 centered** | Works across all placements |
+
+Upload at 2x pixel density for Retina sharpness. JPG/PNG, 30MB max.
+
+#### Meta ā Text
+
+| Element | Limit | Notes |
+
+|---|---|---|
+
+| Primary text | ~72 chars visible in Reels / 125 in Feed | Write for 72 |
+
+| Headline | 40 chars rec | Below image |
+
+| Description | 30 chars rec | Often hidden on mobile |
+
+#### Google Ads
+
+**RSA:** Headlines 30 chars (each must work standalone ā Google mixes randomly), Descriptions 90 chars, up to 15 headlines / 4 descriptions. Pin sparingly ā pinning drops Ad Strength.
+
+**RDA:** Landscape 1200x628 (1.91:1), Square 1200x1200 (required), Portrait 1200x1500 (4:5, optional). Short headline 30 chars, Long headline 90 chars, Description 90 chars. All images 5MB or less, keep under 150KB for fast load.
+
+**Highest-inventory static sizes** (if uploading fixed banners): 300x250, 728x90, 320x50, 300x600, 336x280.
+
+**Performance Max:** Same asset pool serves across Search/Display/YouTube/Gmail/Maps/Discover. Upload all 3 image ratios + a YouTube video ā don't let Google auto-generate one.
+
+#### LinkedIn Ads
+
+Intro text 150 chars rec (600 max), Headline 70 chars rec (200 max), Image 1200x627 or 1200x1200.
+
+#### TikTok Ads
+
+1080x1920 (9:16), Ad text 100 chars max (~80 visible). Spark Ads (boosting organic creator posts) outperform In-Feed Ads on engagement.
+
+#### X / Twitter Ads
+
+| Placement | Dimensions |
+
+|---|---|
+
+| Single image | 1200x675 (1.91:1) or 1080x1080 (1:1) |
+
+| Carousel cards | 1080x1080 (1:1), 2-6 cards |
+
+| Portrait | 1080x1350 (4:5) |
+
+Tweet text 280 chars (~100 visible with media). Card headline 70 chars.
+
+### Step 3: Determine Campaign Mode
+
+Before defining angles, determine whether this is **direct-response**or**awareness/launch**.
+
+#### Direct-Response (default)
+
+Use for conversion, lead generation, app installs, purchases. This is the default ā most ad requests are direct-response.
+
+#### Awareness / Launch Campaigns
+
+Use for product launches, brand announcements, event teasers, top-of-funnel awareness. Prioritize mood and brand impression over clicks.
+
+##### Key differences from direct-response
+
+- **No CTA button on the image.** The CTA lives in the post text or link, not the visual.
+- **Even less text: ~10-15 words max** ā typically brand name, one positioning line, and a date/tagline.
+
+- **Visual metaphor over product shots.** Use evocative imagery that communicates feeling or aspiration.
+- **Multiple visual worlds per campaign.** For carousels or multi-asset campaigns, create 3-5 distinct aesthetic treatments ā different palettes, subjects, moods ā while keeping typography and logo placement consistent.
+
+- **Layout pattern:** Logo (top corner) then Hero visual (fills most of the frame) then Brand name/headline (bottom, large, bold) then Subtitle + date (smaller, below headline).
+- **Hero images allowed.** Unlike direct-response, awareness ads may use a full-bleed generated image as the background (see Image Guidance below).
+
+**When to use awareness mode:** Pre-launch teasers, brand-building campaigns, event promotion, or when the user says "announce," "tease," "launch," or asks for something "premium" without conversion goals.
+
+### Step 3b: Define Angles
+
+Before writing individual copy, establish 3-5 distinct angles ā different reasons someone would click:
+
+| Category | Example |
+
+|----------|---------|
+
+| Pain point | "Stop wasting time on X" |
+
+| Outcome | "Achieve Y in Z days" |
+
+| Social proof | "Join 10,000+ teams who..." |
+
+| Curiosity | "The X secret top companies use" |
+
+| Identity | "Built for [specific role/type]" |
+
+| Urgency | "Limited time: get X free" |
+
+| Contrarian | "Why [common practice] doesn't work" |
+
+**For retargeting ads**, adjust angles for warm audiences who already know the brand:
+
+- Reminder: "Still thinking about X?"
+- Incentive: "Come back for 15% off"
+
+- Social proof: "See why 10,000 others chose us"
+- Scarcity: "Only 3 left in your size"
+
+- Objection handling: "Free returns, no risk"
+
+### Step 4: Design Principles
+
+- **Under 20 words total on the image** ā this is the most important rule. Icons, stats rows, feature grids, and badges all violate this. If it doesn't fit in Logo + Hero + Benefit + CTA, it belongs in the primary text.
+- Visual hierarchy: Logo (top-left) then Hero element then Benefit then CTA
+
+- WCAG 4.5:1 contrast minimum
+- CTA: contrasting color, rounded corners, verb-first, left-aligned
+
+- **No gradients** ā flat solid colors only. Use different solid colors across ads for variety. Exception: awareness/launch ads may use a bottom readability gradient over a hero image.
+
+### Steps 5-6: Generate and Validate Copy
+
+Vary word choice, specificity, tone, and structure across angles. Always validate character counts before delivering. Include counts in your output.
+
+```text
+
+## Angle: [Pain Point ā Manual Reporting]
+
+### Headlines (30 char max)
+
+1. "Stop Building Reports by Hand" (29)
+2. "Automate Your Weekly Reports" (28)
+
+3. "Reports in 5 Min, Not 5 Hrs" (27)
+
+### Descriptions (90 char max)
+
+1. "Marketing teams save 10+ hours/week with automated reporting. Start free." (73)
+2. "Connect your data sources once. Get automated reports forever. No code required." (80)
+
+```
+
+### Step 7: Build Ad Creatives
+
+#### File Setup
+
+Place all ad HTML files in `artifacts/mockup-sandbox/public/ads/`ā served by the mockup-sandbox Vite dev server at`/__mockup/ads/filename.html`.
+
+After copying image assets from `attached_assets/`, always fix permissions:
+
+```bash
+
+chmod 644 artifacts/mockup-sandbox/public/ads/*.png artifacts/mockup-sandbox/public/ads/*.jpg
+
+```
+
+Files copied from `attached_assets/`default to`rw-------` (unreadable by the server).
+
+#### Cache Busting
+
+Canvas iframes cache aggressively. After editing any ad file, increment `?v=N` on the iframe URL:
+
+```text
+
+https://your-domain.dev/__mockup/ads/angle1.html?v=2
+
+```
+
+#### Parallel Subagents ā Full Task Template
+
+Launch one design subagent per angle simultaneously. Each subagent gets a complete, self-contained task with all brand details, the HTML structure, and styling rules baked in. **Do not assume the subagent knows any of the golden rules ā repeat them explicitly.**
+
+```javascript
+
+await startAsyncSubagent({
+
+task: `Create a production-ready ad creative as a standalone HTML file.
+
+**Brand:**
+
+- Name: [Brand Name]
+- Primary color: [hex] | Secondary: [hex] | Accent: [hex]
+
+- Headline font: [Font Name] (Google Fonts ā load via link tag in head)
+- Body font: [Font Name] (Google Fonts ā load via link tag in head)
+
+- Logo: [inline SVG code or path to logo file]
+
+**Ad Details:**
+
+- Platform: [Meta Feed / Google Display / LinkedIn / TikTok / X]
+- Angle: [Pain Point / Outcome / Social Proof / etc.]
+
+- Headline: "[exact headline text]"
+- Benefit: "[one short benefit line]"
+
+- CTA: "[verb-first CTA text]"
+- Background color: [hex ā flat solid, NO gradients]
+
+**File:** Write to artifacts/mockup-sandbox/public/ads/[filename].html
+
+**MANDATORY HTML STRUCTURE ā follow exactly:**
+
+The ad must use this structure:
+
+- html/body: width 100vw, height 100vh, overflow hidden, margin 0, padding 0
+- .ad container: width 100vw, height 100vh, solid background color (NO gradients), flex column, justify-content space-between, padding 6vh 7vw
+
+- .logo: top-left, inline SVG at height 5vh
+- .middle: flex column, gap 3vh, containing headline, benefit, and CTA
+
+- .headline: brand headline font, font-size 8vw, font-weight 900, line-height 1.1
+- .benefit: brand body font, font-size 3vw, slightly transparent white
+
+- .cta: inline-block, padding 2vh 5vw, accent color background, border-radius 1vw, font-weight 700, align-self flex-start (LEFT-ALIGNED)
+- .footer: font-size 1.8vw, subtle color, brand URL
+
+**RULES ā do not violate:**
+
+- Only 4 elements: Logo, Headline, Benefit, CTA. No icons, stats, badges, feature grids, or dividers.
+- Under 20 words total visible on the ad.
+
+- Flat solid background color ā NO gradients, NO patterns.
+- All sizing in vw/vh ā NO fixed pixel dimensions.
+
+- Left-align everything ā logo top-left, text left-aligned, CTA left-aligned. Do NOT center.
+- Load fonts from Google Fonts in the head. Do NOT use system fonts or Inter.
+
+- The CTA button must use a contrasting accent color and be verb-first.`,
+
+specialization: "DESIGN",
+
+relevantFiles: ["artifacts/mockup-sandbox/public/ads/[filename].html"]
+
+});
+
+// Repeat for each angle ā all launch simultaneously
+
+```
+
+After launching, call the `wait_for_background_tasks` tool to wait for every ad-design subagent. Then embed each ad as an iframe on the canvas using `apply_canvas_actions`, and call `presentArtifact({ artifactId, shapeIds: [...] })` with the IDs of the new iframe shapes.
+
+#### Viewport-Relative Sizing (mandatory)
+
+```css
+
+html, body {
+
+margin: 0; padding: 0;
+
+width: 100vw; height: 100vh;
+
+overflow: hidden;
+
+}
+
+```
+
+All internal sizing must use vw/vh. No fixed pixel dimensions on containers.
+
+#### Ad HTML Structure (mandatory pattern)
+
+Every ad must follow this exact structure ā 4 elements, no more:
+
+```html
+
+Hello world.
" + +book.add_item(ch1) + +book.toc = [epub.Link("ch1.xhtml", "Chapter 1", "ch1")] + +book.add_item(epub.EpubNcx()) + +book.add_item(epub.EpubNav()) + +book.spine = ["nav", ch1] + +epub.write_epub("out.epub", book) + +``` + +**EPUB gotchas:** + +- `pandoc` is the simplest for format-to-format EPUB conversion +- Always add `--metadata title="..."` when creating EPUB ā readers require a title + +- EPUB is essentially a ZIP of HTML files ā `ebooklib` gives you fine-grained control +- For EPUB ā PDF, pandoc needs a LaTeX engine (`texlive-xetex`) + +- Cover images: use `--epub-cover-image=cover.jpg` with pandoc + +## HTML to PDF + +```python + +# --- weasyprint (best CSS support, no browser needed) --- + +from weasyprint import HTML + +# Simple file conversion + +HTML("in.html").write_pdf("out.pdf") + +# From URL + +HTML("https://example.com").write_pdf("page.pdf") + +# From HTML string + +HTML(string="World
").write_pdf("out.pdf") + +# With custom CSS + +HTML("in.html").write_pdf("out.pdf", stylesheets=["custom.css"]) + +# With page size and margins + +from weasyprint import CSS + +HTML("in.html").write_pdf("out.pdf", stylesheets=[ + +CSS(string="@page { size: A4; margin: 2cm; }") + +]) + +# Landscape orientation + +HTML("in.html").write_pdf("out.pdf", stylesheets=[ + +CSS(string="@page { size: A4 landscape; margin: 1.5cm; }") + +]) + +``` + +```bash + +# --- CLI alternatives --- + +# pandoc (simpler, less CSS fidelity) + +pandoc in.html -o out.pdf --pdf-engine=xelatex + +# weasyprint CLI + +weasyprint in.html out.pdf + +weasyprint https://example.com page.pdf + +``` + +**HTML to PDF gotchas:** + +- `weasyprint` supports CSS3 including flexbox, grid, and `@page` rules ā best for styled documents +- `weasyprint` does NOT run JavaScript ā for JS-heavy pages, use `playwright` or `pyppeteer` instead + +- For JS-rendered pages: `playwright` ā `page.pdf()` is the most reliable option +- pandoc HTML ā PDF goes through LaTeX, so complex CSS layouts may not render correctly + +- Large HTML files with many images: use `HTML(filename="in.html", base_url=".")` so relative image paths resolve + +## GIF Creation + +```python + +from PIL import Image + +import imageio.v3 as iio + +from pathlib import Path + +# --- Images ā animated GIF (Pillow) --- + +frames = [Image.open(f"frame_{i}.png") for i in range(10)] + +frames[0].save("out.gif", save_all=True, append_images=frames[1:], + +duration=100, loop=0) \# duration in ms, loop=0 means infinite + +# --- Images ā GIF with optimization --- + +frames = [Image.open(f"frame_{i}.png").convert("RGBA") for i in range(10)] + +frames[0].save("out.gif", save_all=True, append_images=frames[1:], + +duration=100, loop=0, optimize=True) + +# --- Directory of images ā GIF --- + +frame_paths = sorted(Path("frames").glob("*.png")) + +frames = [Image.open(p) for p in frame_paths] + +frames[0].save("out.gif", save_all=True, append_images=frames[1:], + +duration=100, loop=0) + +# --- GIF ā individual frames --- + +gif = Image.open("in.gif") + +for i in range(gif.n_frames): + +gif.seek(i) + +gif.save(f"frame_{i}.png") + +# --- Resize GIF --- + +gif = Image.open("in.gif") + +resized_frames = [] + +for i in range(gif.n_frames): + +gif.seek(i) + +resized_frames.append(gif.copy().resize((320, 240), Image.LANCZOS)) + +resized_frames[0].save("small.gif", save_all=True, append_images=resized_frames[1:], + +duration=gif.info.get("duration", 100), loop=0) + +# --- Video ā GIF (imageio + ffmpeg) --- + +import imageio.v3 as iio + +frames = iio.imread("in.mp4", plugin="pyav") + +iio.imwrite("out.gif", frames, plugin="pillow", duration=40, loop=0) + +# --- GIF ā MP4 (ffmpeg CLI, much smaller file) --- + +# ffmpeg -i in.gif -pix_fmt yuv420p -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" out.mp4 + +``` + +**GIF gotchas:** + +- GIF is limited to 256 colors per frame ā complex images lose quality +- Use `optimize=True` to reduce file size, but large GIFs are still huge compared to MP4 + +- `duration` is per-frame in milliseconds (100ms = 10 FPS, 40ms = 25 FPS) +- `loop=0` means infinite loop; `loop=1` plays once then stops + +- For video ā GIF, consider downscaling first ā full-resolution GIFs are enormous +- Pillow GIF output doesn't support transparency well ā use `imageio` for better results + +- For best quality: create GIF from video with ffmpeg: `ffmpeg -i in.mp4 -vf "fps=15,scale=480:-1" out.gif` + +## PDF to SVG + +```python + +# --- PyMuPDF (fitz) ā best quality, vector-preserving --- + +import fitz \# pip install pymupdf + +# Single page + +doc = fitz.open("in.pdf") + +page = doc[0] + +svg_text = page.get_svg_image() + +with open("page_1.svg", "w") as f: + +f.write(svg_text) + +# All pages + +doc = fitz.open("in.pdf") + +for i, page in enumerate(doc): + +svg_text = page.get_svg_image() + +with open(f"page_{i+1}.svg", "w") as f: + +f.write(svg_text) + +doc.close() + +# With custom resolution (matrix scales the output) + +doc = fitz.open("in.pdf") + +page = doc[0] + +mat = fitz.Matrix(2, 2) \# 2x scale for higher detail + +svg_text = page.get_svg_image(matrix=mat) + +with open("page_hires.svg", "w") as f: + +f.write(svg_text) + +``` + +```bash + +# --- CLI alternatives --- + +# pdf2svg (if installed) + +pdf2svg in.pdf out.svg 1 \# page number + +# Inkscape CLI + +inkscape in.pdf --export-type=svg --export-filename=out.svg + +# pdftocairo (from poppler-utils) + +pdftocairo -svg in.pdf out.svg + +``` + +**PDF to SVG gotchas:** + +- `pymupdf` (imported as `fitz`) produces true vector SVGs ā text stays as text, paths stay as paths +- Scanned PDFs produce SVGs with embedded raster images (no vector data to extract) + +- Large PDFs with complex graphics produce very large SVG files +- `pdf2svg` CLI tool is simple but must be installed separately (`apt install pdf2svg`) + +- For rasterized SVG (simpler but not truly vector): render PDF to PNG first, then embed in SVG + +## Validation + +Always verify output: + +```python + +# Row count parity + +assert len(pd.read_csv("out.csv")) == len(pd.read_json("in.json")) + +# JSON well-formed + +json.load(open("out.json")) + +# Image opens + +Image.open("out.jpg").verify() + +``` diff --git a/.local/secondary_skills/flashcard-generator/.fingerprint b/.local/secondary_skills/flashcard-generator/.fingerprint new file mode 100644 index 0000000..25fc69e --- /dev/null +++ b/.local/secondary_skills/flashcard-generator/.fingerprint @@ -0,0 +1 @@ +446c4f0b199781c8ce744d0532529de8 \ No newline at end of file diff --git a/.local/secondary_skills/flashcard-generator/SKILL.md b/.local/secondary_skills/flashcard-generator/SKILL.md new file mode 100644 index 0000000..4164d54 --- /dev/null +++ b/.local/secondary_skills/flashcard-generator/SKILL.md @@ -0,0 +1,233 @@ +--- +name: flashcard-generator +description: Generate flashcards, quizzes, and study guides from notes or topics. +--- + +# Flashcard & Quiz Generator + +Generate study materials grounded in memory science. Follow Wozniak's formulation rules, schedule with SM-2, export to Anki via `genanki`. + +## When to Use + +- User pastes notes/textbook content to convert to cards, needs exam prep, or wants an Anki deck + +## When NOT to Use + +- In-depth research (deep-research), data analysis (data-analysis) + +## Why Spaced Repetition Works + +Ebbinghaus (1885) showed memory decays as `R = e^(-t/S)`where`S`is memory stability ā without review, ~50-70% of new information is gone within 24 hours. The curve was replicated in 2015 (Murre & Dros, PLOS ONE). Each successful recall increases`S`, flattening the curve. **The core insight: reviewing just before you'd forget is the most efficient moment to review.** Active recall (retrieving the answer) builds stability far more than passive re-reading ā this is why cards beat highlighting. + +## Card Formulation: Wozniak's 20 Rules + +Piotr Wozniak (SuperMemo creator; Anki forked his SM-2 algorithm) published the canonical rules in 1999 at supermemo.com. The ones that matter most for card generation: + +**Rule 1-2: Understand before you memorize.** Don't make cards for material the user hasn't grasped yet. Cards reinforce; they don't teach. + +**Rule 4: Minimum Information Principle ā the single most important rule.** One atomic fact per card. Complex cards get forgotten as a unit ā if any part fails, the whole card resets. Split aggressively. + +- Bad: `Q: What are the three branches of US government and what does each do?` (6 facts, fails together) +- Good: Six cards. `Q: Which branch of US government writes laws? A: Legislative` Ć each branch Ć each function. + +**Rule 5: Cloze deletion is the fastest path from prose to cards.** Take a sentence, blank one term. Beginners who struggle with minimum-information should default to cloze. + +- Source: `TCP guarantees ordered delivery; UDP does not.` +- Cards: `{{c1::TCP}} guarantees ordered delivery; {{c2::UDP}} does not.` ā 2 cards from one sentence + +**Rule 9-10: Avoid sets and enumerations.**"List all 7 OSI layers" is a nightmare card ā high failure rate, painful reviews. Instead, use**overlapping cloze**: one sentence with the full list, generate N cards each blanking one item. The redundancy is intentional ā it's extra *cards*, not extra info per card. + +**Rule 11: Combat interference.** Similar cards confuse each other (`affect`vs`effect`, port 80 vs 443). Add disambiguating context:`Q: [web, unencrypted] Default HTTP port? A: 80`. + +**Rule 14: Personalize.** `Q: What's O(n log n)? A: Merge sort ā like the algorithm you botched in the Stripe interview` sticks better than the abstract definition. + +**The diagnostic:** If a card's ease factor drops below 1.3 in review, the card is malformed, not hard. Rewrite it, don't grind it. + +## Card Types + +| Type | Use for | Example | + +|---|---|---| + +| **Basic QāA** | Single facts | `Q: Capital of Mongolia? A: Ulaanbaatar` | + +| **Cloze** | Converting prose fast; lists | `The {{c1::mitochondria}} produces {{c2::ATP}} via {{c3::oxidative phosphorylation}}` ā 3 cards | + +| **Reversed** | Bidirectional recall (vocab) | Generates both `frāen`and`enāfr` | + +| **Application** | Understanding, not recall | `Q: Revenue +20%, profit ā5%. Why? A: Costs grew faster than revenue` | + +| **Image occlusion** | Anatomy, diagrams, maps | Blank one label on a diagram per card (Wozniak rule 8) | + +Mix Bloom's levels: ~40% remember (basic/cloze), ~30% understand, ~30% apply/analyze. Pure recall decks feel productive but fail on exams that test transfer. + +## SM-2 Scheduling (What Anki Runs) + +Wozniak's 1987 algorithm. Each card tracks three values: repetition count `n`, ease factor`EF`(starts at 2.5), interval`I` in days. After each review, grade 0-5: + +```text + +if grade >= 3: \# correct + +if n == 0: I = 1 + +elif n == 1: I = 6 + +else: I = round(I * EF) \# exponential growth + +n += 1 + +else: \# forgot + +n = 0; I = 1 \# reset interval, keep EF + +EF += 0.1 - (5-grade) * (0.08 + (5-grade)*0.02) + +EF = max(EF, 1.3) \# floor ā below this, card is malformed + +``` + +Grade 5 ā EF +0.10. Grade 4 ā no change. Grade 3 ā EF ā0.14. A card you always rate "good" (4) with EF 2.5 goes: 1 ā 6 ā 15 ā 38 ā 94 days. **FSRS** (Anki 23.10+) is the ML successor ā fits a personal forgetting curve, ~20-30% fewer reviews for same retention. Mention it; default to SM-2 for simplicity. + +## Export to Anki: `genanki` + +`pip install genanki`(github.com/kerrickstaley/genanki). Generates`.apkg` files that import directly via File ā Import. + +```python + +import genanki, random + +# Generate these ONCE, then hardcode ā stable IDs let users re-import updates + +MODEL_ID = random.randrange(1 << 30, 1 << 31) \# e.g. 1607392319 + +DECK_ID = random.randrange(1 << 30, 1 << 31) + +basic = genanki.Model(MODEL_ID, 'Basic', + +fields=[{'name': 'Q'}, {'name': 'A'}], + +templates=[{'name': 'Card 1', 'qfmt': '{{Q}}', + +'afmt': '{{FrontSide}}
`(paths break). Stable GUIDs let re-imports update cards in place ā subclass`Note`and override`guid` to hash only the question field.
+
+**Quizlet/CSV fallback:** Tab-separated, one card per line: `question\tanswer\n`. Quizlet imports directly. Also works for Anki's File ā Import ā Text.
+
+## Output: Always Build a Web App
+
+**Every flashcard generation MUST produce an interactive web app as the primary output.**Do not output cards as plain text or markdown ā always build a React + Vite single-page app with**two modes** the user can switch between:
+
+### Mode 1: Flashcard Review
+
+1. **Card display** ā show front of card, flip to back on click or spacebar
+2. **SM-2 grading**ā four buttons: Again (1), Hard (3), Good (4), Easy (5), wired to the SM-2 algorithm above.**Grading and accuracy:** grades 3-5 (Hard, Good, Easy) count as "correct"; grade 1 (Again) counts as "incorrect". Accuracy is calculated per session as `(correct / reviewed) * 100`. This resets on page reload; review progress (intervals, due dates) persists in localStorage.
+
+3. **Spaced repetition queue** ā `localStorage`persistence for`{cardId: {n, EF, I, due}}`. **Card ordering:**previously reviewed cards that are due appear first, sorted by due date (most overdue first). New (unseen) cards are**shuffled randomly each session**using**Fisher-Yates shuffle** (the only unbiased O(n) shuffle algorithm ā naive`array.sort(() => Math.random() - 0.5)` produces biased distributions). Never present new cards in a fixed order ā it creates a false sense of learning tied to sequence rather than recall.
+4. **Session stats** ā cards reviewed, accuracy %, cards due tomorrow, total remaining
+
+5. **Card type support** ā render Basic QāA, Cloze (hide blanked terms), and Reversed cards correctly
+6. **Flip animation** ā CSS 3D transform, keyboard shortcuts (Space to flip, 1/2/3/4 for grading)
+
+7. **Card difficulty indicators** ā show a visual indicator (colored dot or badge) on each card based on its current ease factor. Green for EF ā„ 2.5 (easy), yellow for 1.8 ā¤ EF < 2.5 (moderate), red for EF < 1.8 (hard). Helps users see at a glance which cards they're mastering vs. struggling with.
+8. **Leech detection** ā track how many times a card has been graded Again (1). If a card is reset more than 4 times, flag it as a "leech" with a visual warning (e.g., a ā ļø icon). Leeches are almost always malformed cards that should be rewritten, not drilled harder. Optionally offer a "Rewrite this card" prompt.
+
+9. **Daily new card limit** ā enforce a configurable daily limit for new (unseen) cards, defaulting to 20. Store the count in localStorage with today's date. Once the limit is reached, only show review cards. This prevents users from overwhelming themselves ā the review debt from too many new cards becomes unsustainable by week 3.
+10. **Study streak** ā track consecutive days of study in localStorage. Display a streak counter (e.g., "š„ 5-day streak") in the session stats area. A day counts if the user reviews at least 1 card. Streaks reset if a day is missed. Streaks are a proven motivator for building daily review habits.
+
+### Mode 2: AI Quiz
+
+An AI-powered quiz mode that generates and grades questions:
+
+1. **Quiz setup** ā user picks a topic (or all topics) and number of questions (5, 10, 20, custom)
+2. **Question generation**ā use AI integrations to generate N questions from the card material. Mix question types: multiple choice, short answer, and true/false. Questions should test understanding and application, not just recall.**Difficulty progression:** start with easier recall-level questions and ramp up to application/analysis questions as the quiz progresses. This builds confidence and mirrors real exam structure.
+
+3. **Answer & grade** ā user answers each question, then AI grades the response with a score and explanation of what was right/wrong
+4. **Quiz results** ā summary screen with overall score, per-question breakdown, and which topics need more work
+
+5. **Weak spot feedback**ā highlight topics where the user scored lowest and suggest reviewing those flashcards.**Link back to flashcard mode:** include a "Review these cards" button next to weak topics that switches to flashcard mode pre-filtered to that topic. This closes the learn-test-review loop.
+
+### Mode 3 (Optional): Card Import from Notes
+
+If the user wants to create their own cards, offer a text import mode:
+
+1. **Paste area** ā user pastes notes, bullet points, or prose into a text area
+2. **AI card generation** ā use AI integrations to parse the text and generate flashcards following Wozniak's minimum information principle. Output Basic QāA and Cloze cards.
+
+3. **Review before adding** ā show the generated cards in an editable list. Let the user approve, edit, or delete each card before adding to the deck.
+4. **Merge into deck** ā approved cards get added to the main deck with fresh SM-2 state (n=0, EF=2.5, I=0).
+
+### UI/UX Requirements
+
+- **Tab or toggle** to switch between Flashcard and Quiz modes
+- **Clean, focused design** ā one card or question centered on screen, no clutter
+
+- **Mobile-friendly** ā responsive layout, touch targets
+- **Topic/deck selector** ā filter by topic in both modes
+
+- **Progress indicator** ā card counter in flashcard mode, question progress bar in quiz mode
+- **Progress history** ā store daily review counts and accuracy in localStorage. Optionally display a simple chart or heatmap showing review activity over the past 30 days. This gives users a sense of long-term progress beyond the current session.
+
+## Best Practices
+
+1. **Minimum information principle trumps everything** ā when in doubt, split the card
+2. **Cloze is the default for prose** ā fastest path from notes to reviewable cards
+
+3. **Never make set-enumeration cards** ā "list all X" ā overlapping cloze instead
+4. **30 great cards > 100 mediocre ones** ā review burden compounds; every bad card costs minutes over months
+
+5. **Cap new cards at ~20/day** ā the review debt from 100 new cards/day becomes unsustainable by week 3
+6. **Interleave topics in the card data array** ā when hardcoding cards, mix topics throughout the array rather than grouping all cards of one topic together. Even with shuffle logic, interleaving ensures better variety if the shuffle ever fails or is bypassed
+
+## Technical Notes
+
+- **Fisher-Yates shuffle implementation:** When shuffling new cards, always use the Fisher-Yates (Knuth) algorithm. The naive `array.sort(() => Math.random() - 0.5)` approach produces biased distributions where some orderings are significantly more likely than others. Correct implementation:
+
+```typescript
+
+function fisherYatesShuffle