How onlytk/stickerpicker works
Project Type and Purpose
• This is an open‑source Matrix “sticker picker” widget with two halves:
a) A Python‑based CLI/library for creating and converting sticker packs (build‑time).
b) A static, client‑side web widget (runtime) that can be embedded in any Matrix client (e.g., Element).
• The CLI ingests JSON definitions in packs/, fetches or converts emote images, and writes out the processed pack metadata and assets. The web folder hosts the widget’s HTML, JS, CSS, and the generated pack metadata for static deployment.
Main Components of the System
A. Build‑Time (Developer Machine)
• Sticker CLI (Python package in sticker/):
– stickerimport.py reads packs/*.json, downloads or references image assets.
– scalar_convert.py optionally produces Scalar‐compatible pack JSON (packs/scalar-*.json).
– Utility modules under sticker/lib handle HTTP, Matrix API calls, JSON I/O.
• Output artifacts:
– emotes/ (images + index.json, pack.json)
– web/packs/ (emotes.json, index.json)
B. Static Hosting (e.g., GitHub Pages)
• Serves:
– Emote images & JSON from emotes/
– Web widget under web/ (HTML, JS bundles, CSS, web/packs/)
C. Runtime (End‑User Matrix Client)
• Matrix client (Element Web/iOS/Android) loads the widget via an iframe pointing to index.html.
• Widget modules (web/src/*.js + web/lib/htm/preact.js):
– Reads web/packs/index.json to list sticker packs.
– On pack selection, loads that pack’s emotes.json.
– On sticker click, uses widget-api.js to postMessage a Matrix sticker event back to the host.
• Client widget API interacts over postMessage and the Matrix Widget protocol.
• Frequently‑used stickers are stored in browser localStorage.
Relationships and Interactions
• Developer invokes the Sticker CLI → processes packs/ → emits assets and JSON into emotes/ and web/packs/.
• CI/deployment pushes these static folders plus the web/ source to a static file server.
• End user’s Matrix client embeds the widget iframe → widget loads static assets (HTML/JS/CSS/JSON/images).
• Widget ↔ Matrix client communicate via the Widget postMessage API:
• Widget sends “sticker selected” events up.
• Client may send down “update frequently‑used” or theming info.
Architectural Patterns and Design Principles
• Clear separation of concerns:
• Build‑time toolchain (Python CLI) vs. run‑time widget (JS/CSS/HTML).
• No dynamic back‑end server—entirely static hosting.
• Modular front‑end: small UI components (search, spinner, list).
• Use of standard browser APIs (fetch, postMessage) and a lightweight view library (Preact + htm).
• Configurable pack definitions in JSON—easy to extend or import from other services (e.g., Telegram, Scalar).
Key Technologies and Frameworks
• Python 3 (+ requirements in requirements.txt), setup.py for packaging the CLI.
• sticker/lib: custom matrix/HTTP utils.
• Front‑end:
• JavaScript modules under web/src/
• Preact + htm (web/lib/htm/preact.js)
• ESInstall loader (web/esinstall.js)
• CSS/SASS for styling (web/style/)
• Static hosting via GitHub Pages or any web server.