X-Puzzle-Kit

Creative Puzzle & Stitching Toolkit for X (Twitter)

English | 简体中文

✨ Highlights

Chrome Extension (PC)	Android (PWA)	iOS (Shortcut)
✨ Timeline Injection Right-click to split	🚀 System Share Target Add to Home Screen	📲 Shortcut Integration One-click from App

Seamless experience from Desktop Extension to Mobile PWA

🖼️ Stitch & Collect (Stitcher)

• Creative Assembly: Love the clever 4-panel splits or manga spreads designed by your favorite artists? One-click to grab these brilliant ideas and assemble them into a high-res masterpiece for your personal collection.
• Smart Prediction: Auto-detects the best layout (T-shape, Grid) based on image count.
• Native Integration (Ext only): Injects a "🧩 Stitch" button directly into the timeline. From "Admiring" to "Cherishing" in one click.

✂️ Smart Splitter

• Multi-Mode Splitting: Offers versatile layouts including 2x2 Grid, T-Shape (1 big, 2 small), and Custom Rows/Cols (Nx1, 1xN), perfectly tailored for Twitter's 4-image grid or vertical strip comics.
• Precision Editing: Features Unified and Individual drag modes. You can scale and move the image globally or adjust each cell independently, including replacing images for specific cells.
• Twitter Optimization: Built-in one-click "Twitter Aspect Ratio" optimization ensures your images are cropped perfectly for the timeline view.
• Customizable Export: Adjust gap sizes, fill exposed backgrounds with colors, and choose to export as a ZIP archive or individual images.

📱 Platform

• PWA & Mobile: Full PWA support with a premium touch UI for iOS/Android.
• Silent Updates: Frontend logic updates instantly (especially when launched via iOS Shortcuts), bypassing extension store review delays.
• Mobile Integration: Import tweets directly via the system "Share" menu from the Mobile App or Mobile Web. Supported via Web Share Target (Android) and Shortcuts (iOS).

🔒 Core

• Privacy Policy:
  • Extension: 100% Local processing, zero communication with external servers.
  • Web/PWA: Uses a secure proxy (Cloudflare Worker) for tweet URL parsing (no data stored). Final image processing always stays local in your browser.

📦 Installation

Method 1: Web App / PWA (Easiest)

No installation required! Simply visit the web version and add it to your Home Screen for a native-like experience.

• URL: https://x-puzzle-kit.pages.dev
• Features: Supports sharing directly from the Mobile App or Web version (via System Share menu).

Method 2: Chrome Extension (Best for Desktop)

The most efficient way for desktop users.

1. Web Store (Recommended): Chrome Web Store ↗ Click "Add to Chrome".
2. Manual Install (Alternative):
   • Download the latest .zip from the Releases Page and unzip it.
   • Go to chrome://extensions/ in Chrome and enable "Developer mode".
   • Click "Load unpacked" and select the unzipped folder.

Method 3: Build from Source

For developers who want to contribute or build from source:

git clone https://github.com/Shirolin/X-Puzzle-Kit.git
cd X-Puzzle-Kit
npm install
npm run build      # Build Chrome Extension (dist)
npm run build:web  # Build Web/PWA Version (dist-web)
# For extension, load the 'dist' directory in Chrome

🛠️ Tech Stack

Built with modern web technologies for performance and experience:

• Framework: React + Preact (Lite weight)
• Language: TypeScript
• Build Tool: Vite
• Components: Lucide, Sonner, SortableJS
• Styling: Vanilla CSS (Apple Design Style) / Scss-like Utilities

🔖 Release & Build

This project uses an automated release workflow.

Automated Release

Simply push a version tag, and GitHub Actions will automatically package and release it:

npm version patch  # or minor / major
git push --follow-tags

Manual Packaging

To build .zip and .crx files locally:

npm run package

Artifacts will be generated in the release/ directory.

🤝 Contribution & Support

Issues and Pull Requests are welcome!

If you find this project helpful, please give it a Star ⭐️ or buy me a coffee:

• Afdian
• Ko-fi

📄 License

GPL-3.0 License © 2026 shirolin