syntaxshot-cli 1.0.0

package/.syntaxshot-usage.json

@@ -0,0 +1,3 @@
+{
+  "count": 1
+}

package/.syntaxshotrc.json

@@ -0,0 +1,11 @@
+{
+  "theme": "solar",
+  "format": "png",
+  "output": "syntaxshots",
+  "fontSize": 16,
+  "lineNumbers": true,
+  "quality": 0.95,
+  "excludeDirs": [],
+  "excludeFiles": [],
+  "plan": "pro"
+}

package/README.md

@@ -0,0 +1,102 @@
+# syntaxshot-cli
+
+Generate real syntax-highlighted code screenshots from the terminal — no browser involved, using `shiki` (highlighting) + `@napi-rs/canvas` (rendering).
+
+## Installation
+
+```bash
+cd syntaxshot
+npm install
+npm link        # this enables the global `syntaxshot` command
+```
+
+That's it. `@napi-rs/canvas` ships prebuilt binaries for Windows, macOS, and Linux, so **you don't need to install Cairo, GTK, Visual Studio Build Tools, or any native dependency** (unlike the classic `canvas` package, which is a lot of pain on Windows).
+
+## Basic usage (Free plan)
+
+```bash
+syntaxshot init                          # creates .syntaxshotrc.json with your defaults
+syntaxshot path/to/file.js               # generates syntaxshots/file.png
+syntaxshot a.js b.ts c.css --theme nord  # multiple files, one theme
+syntaxshot a.py --format jpg -o outputs  # jpg, custom folder
+```
+
+The Free plan **always requires you to name each file**. The Pro plan can do all of the above, plus:
+
+```bash
+syntaxshot ./src                       # [Pro plan] scans the whole folder
+```
+
+When you pass it a folder, syntaxshot:
+1. Walks it recursively.
+2. Filters "capturable" files (recognized code extension) and automatically ignores what doesn't make sense to show: `node_modules`, `.git`, `dist`/`build`, lockfiles (`package-lock.json`, `yarn.lock`...), `package.json`, `tsconfig.json`, any `.env*`, and dotfiles in general.
+3. Tells you how many files it found and how many images it's about to generate, then **asks for confirmation** before generating anything.
+4. Once confirmed, generates everything automatically, keeping the subfolder structure inside the output folder (so files with the same name in different folders don't overwrite each other).
+
+Pass `-y` / `--yes` to skip the confirmation prompt (handy for scripts/CI).
+
+If you're on the Free plan and try to pass a folder, the CLI blocks it with a clear message asking you to list files one by one — it doesn't disable normal usage, it just redirects you to the manual flow.
+
+You can customize what the scan ignores in `.syntaxshotrc.json`:
+```json
+{
+  "excludeDirs": ["scripts", "tmp"],
+  "excludeFiles": ["seed-data.json"]
+}
+```
+
+The Free plan allows **10 images**; the counter lives in `.syntaxshot-usage.json` in the folder where you run the command.
+
+## Activating a Pro license
+
+Once you've paid (see the `syntaxshot-api` project), you'll get a license key by email. Activate it once per machine:
+
+```bash
+syntaxshot login SYNX-XXXX-XXXX-XXXX
+```
+
+This validates the key against the license API and caches the result in `~/.syntaxshot/license.json` (re-checked automatically every 24h; if the API is briefly unreachable, a previously-valid license keeps working for up to 7 days so you're never blocked by a network hiccup).
+
+```bash
+syntaxshot logout   # removes the license from this machine
+```
+
+By default the CLI validates against `https://api.syntaxshot.dev` — point it at your own deployment (or `http://localhost:3000` while developing) with:
+```bash
+export SYNTAXSHOT_API_URL=https://your-deployment.vercel.app
+```
+
+## Configuration (`.syntaxshotrc.json`)
+
+```json
+{
+  "theme": "midnight",
+  "format": "png",
+  "output": "syntaxshots",
+  "fontSize": 16,
+  "lineNumbers": true,
+  "quality": 0.95,
+  "plan": "free"
+}
+```
+
+Set `"plan": "pro"` here only as a **local dev override** (e.g. while working on the CLI itself) — it skips license validation entirely. For real usage, activate a license with `syntaxshot login <key>` instead; see below.
+
+## Available themes
+
+- `midnight` — Dracula-style palette, dark violet window (the one in the reference image)
+- `nord` — Nord palette, blue-gray window
+- `solar` — Solarized Light, light window
+
+Quick list: `syntaxshot themes`
+
+## Key files if you want to extend this
+
+- `src/themes.js` — add new themes here (syntax palette + window colors)
+- `src/highlighter.js` — extension → language map for shiki
+- `src/scanner.js` — folder-scan logic and exclusion rules (Pro)
+- `src/renderer.js` — all the canvas drawing (background, window, text)
+- `src/license.js` — license activation/validation + local caching
+- `bin/syntaxshot.js` — CLI, plan limits, `--auto`, confirmation prompt, `login`/`logout`
+
+The license backend itself (Stripe webhook, `/api/v1/validate`, license key generation) lives in the separate `syntaxshot-api` project.

package/bin/syntaxshot.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { execSync } from "node:child_process";
+
+import { loadConfig, writeDefaultConfig } from "../src/config.js";
+import { resolveTheme, THEMES } from "../src/themes.js";
+import { detectLang, tokenizeCode } from "../src/highlighter.js";
+import { renderSnippet } from "../src/renderer.js";
+import { renderSnippetSVG } from "../src/svgRenderer.js";
+import { checkAndConsume, FREE_LIMIT } from "../src/usage.js";
+import { findEligibleFiles } from "../src/scanner.js";
+import { activateLicense, logoutLicense, resolvePlan } from "../src/license.js";
+
+const program = new Command();
+
+program
+  .name("syntaxshot")
+  .description(
+    "Generate syntax-highlighted code screenshots from your terminal.",
+  )
+  .version("1.0.0");
+
+program
+  .command("login <licenseKey>")
+  .description("Activate your Pro license on this machine")
+  .action(async (licenseKey) => {
+    const result = await activateLicense(licenseKey.trim());
+    if (!result.ok) {
+      console.error(`❌ ${result.error}`);
+      process.exit(1);
+    }
+    console.log(`✅ License activated. Plan: ${result.plan}.`);
+  });
+
+program
+  .command("logout")
+  .description("Remove the locally stored license")
+  .action(() => {
+    logoutLicense();
+    console.log("✅ License removed from this machine.");
+  });
+
+program
+  .command("init")
+  .description(
+    "Create a .syntaxshotrc.json file with the default configuration",
+  )
+  .action(() => writeDefaultConfig());
+
+program
+  .command("themes")
+  .description("List the available themes")
+  .action(() => {
+    console.log("Available themes:");
+    Object.entries(THEMES).forEach(([key, t]) =>
+      console.log(`  - ${key} (${t.label})`),
+    );
+  });
+
+program
+  .argument(
+    "[paths...]",
+    "File(s) to capture (Free and Pro), or a folder to auto-scan (Pro only)",
+  )
+  .option("-t, --theme <name>", "Visual theme (overrides config)")
+  .option("-f, --format <ext>", "png | jpg (overrides config)")
+  .option("-o, --output <dir>", "Output folder (overrides config)")
+  .option("--no-line-numbers", "Hide line numbers")
+  .option("-y, --yes", "Skip the confirmation prompt when scanning a folder")
+  .option("--auto", "[Pro plan] auto-detect files changed via git")
+  .action(async (inputPaths, cmdOpts) => {
+    const cwd = process.cwd();
+    const config = loadConfig(cwd);
+    const theme = resolveTheme(cmdOpts.theme || config.theme);
+    const format = (cmdOpts.format || config.format || "png").toLowerCase();
+    const outputDir = cmdOpts.output || config.output || "syntaxshots";
+    const lineNumbers = cmdOpts.lineNumbers ?? config.lineNumbers;
+    const plan = await resolvePlan(config.plan);
+
+    const allowedFormats =
+      plan === "pro" ? ["png", "jpg", "jpeg", "svg"] : ["png", "jpg", "jpeg"];
+    if (!allowedFormats.includes(format)) {
+      console.error(
+        `❌ The "${format}" format is a Pro plan feature. The Free plan supports png or jpg.\n` +
+          `   Use --format png or --format jpg, or upgrade to Pro for svg.`,
+      );
+      process.exit(1);
+    }
+
+    let targets = [];
+
+    if (cmdOpts.auto) {
+      if (plan !== "pro") {
+        console.error(
+          "❌ --auto is a Pro plan feature. On the Free plan, list file(s) manually:\n   syntaxshot path/to/file.js",
+        );
+        process.exit(1);
+      }
+      const changed = getChangedFilesFromGit();
+      if (changed.length === 0) {
+        console.log("No modified files detected via git. Nothing to capture.");
+        return;
+      }
+      console.log(
+        `🔎 Auto-detected ${changed.length} file(s) changed via git.`,
+      );
+      targets = changed.map((f) => ({ file: path.resolve(f), scanRoot: null }));
+    } else {
+      const explicitFiles = [];
+      const directories = [];
+
+      for (const p of inputPaths) {
+        if (!fs.existsSync(p)) {
+          explicitFiles.push(p);
+          continue;
+        }
+        if (fs.statSync(p).isDirectory()) {
+          directories.push(path.resolve(p));
+        } else {
+          explicitFiles.push(p);
+        }
+      }
+
+      if (directories.length > 0 && plan !== "pro") {
+        console.error(
+          "❌ Scanning a whole folder is a Pro plan feature.\n" +
+            "   On the Free plan, list files one by one:\n" +
+            "   syntaxshot file1.js file2.css file3.ts",
+        );
+        process.exit(1);
+      }
+
+      targets = explicitFiles.map((f) => ({
+        file: path.resolve(f),
+        scanRoot: null,
+      }));
+
+      for (const dir of directories) {
+        const found = findEligibleFiles(dir, {
+          excludeDirs: config.excludeDirs,
+          excludeFiles: config.excludeFiles,
+        });
+        targets.push(...found.map((f) => ({ file: f, scanRoot: dir })));
+      }
+
+      if (directories.length > 0) {
+        const scannedCount = targets.filter((t) => t.scanRoot).length;
+
+        if (scannedCount === 0) {
+          console.log(
+            `📁 Scanned: ${directories.map((d) => path.relative(cwd, d) || ".").join(", ")}\n` +
+              "No eligible files found (everything was excluded or unsupported).",
+          );
+          return;
+        }
+
+        console.log(
+          `📁 Folder(s) scanned: ${directories.map((d) => path.relative(cwd, d) || ".").join(", ")}`,
+        );
+        console.log(
+          `📄 Found ${scannedCount} eligible file(s). This will generate ${scannedCount} image(s):`,
+        );
+        targets
+          .filter((t) => t.scanRoot)
+          .slice(0, 25)
+          .forEach((t) => console.log(`   - ${path.relative(cwd, t.file)}`));
+        if (scannedCount > 25)
+          console.log(`   ...and ${scannedCount - 25} more`);
+        console.log("");
+
+        if (!cmdOpts.yes) {
+          const proceed = await askConfirmation(
+            `Continue and generate ${scannedCount} image(s)? (y/N) `,
+          );
+          if (!proceed) {
+            console.log("Cancelled. No images were generated.");
+            return;
+          }
+        }
+      }
+    }
+
+    if (targets.length === 0) {
+      console.error(
+        "❌ You must provide at least one file or one folder.\n" +
+          "   Usage: syntaxshot path/to/file.js [another/file.ts ...]\n" +
+          "   Pro plan: syntaxshot path/to/folder   (scans and generates everything automatically)",
+      );
+      process.exit(1);
+    }
+
+    const check = checkAndConsume(plan, targets.length, cwd);
+    if (!check.allowed) {
+      console.error(
+        `❌ Free plan limit reached (${FREE_LIMIT} images). You have ${Math.max(
+          check.remaining,
+          0,
+        )} left. Upgrade to Pro for unlimited generation.`,
+      );
+      process.exit(1);
+    }
+
+    const resolvedOutputDir = path.resolve(cwd, outputDir);
+    fs.mkdirSync(resolvedOutputDir, { recursive: true });
+
+    for (const target of targets) {
+      await processFile(target.file, {
+        theme,
+        format,
+        outputDir: resolvedOutputDir,
+        lineNumbers,
+        fontSize: config.fontSize,
+        quality: config.quality,
+        scanRoot: target.scanRoot,
+      });
+    }
+
+    if (plan === "free") {
+      console.log(
+        `ℹ️  Free plan: ${check.remaining} capture(s) left this month.`,
+      );
+    }
+  });
+
+async function askConfirmation(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const answer = await rl.question(question);
+  rl.close();
+  return /^y(es)?$/i.test(answer.trim());
+}
+
+async function processFile(absPath, opts) {
+  if (!fs.existsSync(absPath)) {
+    console.error(`⚠️  Not found, skipping: ${absPath}`);
+    return;
+  }
+
+  const code = fs.readFileSync(absPath, "utf-8");
+  const lang = detectLang(absPath);
+  const lines = await tokenizeCode(code, lang, opts.theme.shikiTheme);
+
+  let buffer;
+  if (opts.format === "svg") {
+    const svg = renderSnippetSVG(lines, opts.theme, {
+      fileName: path.basename(absPath),
+      fontSize: opts.fontSize,
+      lineNumbers: opts.lineNumbers,
+    });
+    buffer = Buffer.from(svg, "utf-8");
+  } else {
+    const canvas = renderSnippet(lines, opts.theme, {
+      fileName: path.basename(absPath),
+      fontSize: opts.fontSize,
+      lineNumbers: opts.lineNumbers,
+    });
+    buffer =
+      opts.format === "jpg" || opts.format === "jpeg"
+        ? canvas.toBuffer("image/jpeg", opts.quality ?? 0.95)
+        : canvas.toBuffer("image/png");
+  }
+
+  let outPath;
+  if (opts.scanRoot) {
+    const relDir = path.dirname(path.relative(opts.scanRoot, absPath));
+    const baseName = path.basename(absPath, path.extname(absPath));
+    const targetDir = path.join(opts.outputDir, relDir === "." ? "" : relDir);
+    fs.mkdirSync(targetDir, { recursive: true });
+    outPath = path.join(targetDir, `${baseName}.${opts.format}`);
+  } else {
+    const baseName = path.basename(absPath, path.extname(absPath));
+    outPath = path.join(opts.outputDir, `${baseName}.${opts.format}`);
+  }
+
+  fs.writeFileSync(outPath, buffer);
+  console.log(
+    `✅ ${path.relative(process.cwd(), absPath)} → ${path.relative(process.cwd(), outPath)}`,
+  );
+}
+
+function getChangedFilesFromGit() {
+  try {
+    const output = execSync("git diff --name-only HEAD", { encoding: "utf-8" });
+    return output
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .filter((f) => fs.existsSync(f));
+  } catch {
+    return [];
+  }
+}
+
+program.parse();

package/examples/StorageModule.js

@@ -0,0 +1,23 @@
+export class StorageModule {
+  constructor(storage = window.localStorage) { this.storage = storage; }
+  save(key, data) { this.storage.setItem(key, JSON.stringify(data)); }
+  load(key, fallback = null) {
+    const raw = this.storage.getItem(key);
+    if (!raw) return fallback;
+    try { return JSON.parse(raw); } catch { return fallback; }
+  }
+  delete(key) { this.storage.removeItem(key); }
+  list(prefix) {
+    const values = [];
+    for (let i = 0; i < this.storage.length; i += 1) {
+      const key = this.storage.key(i);
+      if (key?.startsWith(prefix)) values.push(...this.load(key, []));
+    }
+    return values;
+  }
+  clearPomodoroData() {
+    Object.keys(this.storage)
+      .filter((key) => key.startsWith('pomodoro:'))
+      .forEach((key) => this.storage.removeItem(key));
+  }
+}

package/examples/api.ts

@@ -0,0 +1,11 @@
+interface User {
+  id: string;
+  name: string;
+  role: "admin" | "user";
+}
+
+export async function fetchUser(id: string): Promise<User> {
+  const res = await fetch(`/api/users/${id}`);
+  if (!res.ok) throw new Error("User not found");
+  return res.json();
+}

package/examples/style.css

@@ -0,0 +1,14 @@
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  padding: 24px;
+  border-radius: 12px;
+  background: linear-gradient(135deg, #1e1b3a, #0f0c29);
+  box-shadow: 0 20px 40px rgba(0,0,0,0.4);
+}
+
+.card:hover {
+  transform: translateY(-4px);
+  transition: transform 0.2s ease-in-out;
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "syntaxshot-cli",
+  "version": "1.0.0",
+  "description": "Genera capturas de codigo con resaltado de sintaxis desde la terminal",
+  "type": "module",
+  "bin": {
+    "syntaxshot": "./bin/syntaxshot.js"
+  },
+  "main": "bin/syntaxshot.js",
+  "scripts": {
+    "test": "node bin/syntaxshot.js"
+  },
+  "dependencies": {
+    "@napi-rs/canvas": "^0.1.53",
+    "commander": "^12.0.0",
+    "shiki": "^4.3.1"
+  }
+}

package/src/config.js

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const CONFIG_FILENAME = ".syntaxshotrc.json";
+
+const DEFAULTS = {
+  theme: "midnight",
+  format: "png",          // "png" | "jpg"
+  output: "syntaxshots",  // output folder
+  fontSize: 16,
+  lineNumbers: true,
+  quality: 0.95,          // only applies to jpg
+  excludeDirs: [],        // extra folders to ignore during folder scan (Pro)
+  excludeFiles: [],       // extra filenames to ignore during folder scan (Pro)
+};
+
+export function loadConfig(cwd = process.cwd()) {
+  const configPath = path.join(cwd, CONFIG_FILENAME);
+  if (!fs.existsSync(configPath)) return { ...DEFAULTS };
+  try {
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    return { ...DEFAULTS, ...raw };
+  } catch {
+    console.warn(`⚠️  Could not read ${CONFIG_FILENAME}, using default values.`);
+    return { ...DEFAULTS };
+  }
+}
+
+export function writeDefaultConfig(cwd = process.cwd()) {
+  const configPath = path.join(cwd, CONFIG_FILENAME);
+  if (fs.existsSync(configPath)) {
+    console.log(`${CONFIG_FILENAME} already exists, it was not overwritten.`);
+    return;
+  }
+  fs.writeFileSync(configPath, JSON.stringify(DEFAULTS, null, 2));
+  console.log(`✅ Created ${CONFIG_FILENAME} with the default configuration.`);
+}
+
+export { DEFAULTS };

package/src/highlighter.js

@@ -0,0 +1,52 @@
+import { codeToTokens } from "shiki";
+import path from "node:path";
+
+export const EXT_TO_LANG = {
+  ".js": "javascript",
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".jsx": "jsx",
+  ".ts": "typescript",
+  ".tsx": "tsx",
+  ".css": "css",
+  ".scss": "scss",
+  ".html": "html",
+  ".json": "json",
+  ".py": "python",
+  ".rb": "ruby",
+  ".go": "go",
+  ".rs": "rust",
+  ".java": "java",
+  ".php": "php",
+  ".sh": "shell",
+  ".yml": "yaml",
+  ".yaml": "yaml",
+  ".md": "markdown",
+  ".sql": "sql",
+  ".c": "c",
+  ".cpp": "cpp",
+  ".cs": "csharp",
+  ".vue": "vue",
+  ".swift": "swift",
+  ".kt": "kotlin",
+};
+
+export function detectLang(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return EXT_TO_LANG[ext] || "plaintext";
+}
+
+/**
+ * Tokenizes the code and returns an array of lines, each line is an
+ * array of tokens { content, color }.
+ */
+export async function tokenizeCode(code, lang, shikiTheme) {
+  const { tokens } = await codeToTokens(code, {
+    lang,
+    theme: shikiTheme,
+  });
+
+  return tokens.map((line) =>
+    line.map((tok) => ({ content: tok.content, color: tok.color || "#e6e6e6" }))
+  );
+}

package/src/license.js

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const LICENSE_DIR = path.join(os.homedir(), ".syntaxshot");
+const LICENSE_FILE = path.join(LICENSE_DIR, "license.json");
+
+// How long a validated license stays trusted before re-checking with the API.
+const REVALIDATE_AFTER_MS = 24 * 60 * 60 * 1000; // 24h
+// If the API is unreachable (offline), keep trusting a previously-valid
+// license for this long before falling back to Free.
+const OFFLINE_GRACE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+const API_URL = process.env.SYNTAXSHOT_API_URL || "https://api.syntaxshot.dev";
+
+function readLicenseFile() {
+  if (!fs.existsSync(LICENSE_FILE)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(LICENSE_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeLicenseFile(data) {
+  fs.mkdirSync(LICENSE_DIR, { recursive: true });
+  fs.writeFileSync(LICENSE_FILE, JSON.stringify(data, null, 2));
+}
+
+async function validateWithApi(licenseKey) {
+  const res = await fetch(`${API_URL}/api/v1/validate`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ licenseKey }),
+    signal: AbortSignal.timeout(8000),
+  });
+  return res.json();
+}
+
+/** Called by `syntaxshot login <key>`. Validates once and stores it. */
+export async function activateLicense(licenseKey) {
+  const result = await validateWithApi(licenseKey);
+  if (!result.valid) {
+    return { ok: false, error: result.error || "This license key is not active." };
+  }
+
+  writeLicenseFile({
+    licenseKey,
+    plan: result.plan,
+    lastCheckedAt: new Date().toISOString(),
+    lastKnownValid: true,
+  });
+
+  return { ok: true, plan: result.plan };
+}
+
+export function logoutLicense() {
+  if (fs.existsSync(LICENSE_FILE)) fs.unlinkSync(LICENSE_FILE);
+}
+
+/**
+ * Resolves the effective plan for this run.
+ * Order of precedence:
+ *   1. config.plan === "pro" in the local .syntaxshotrc.json — a manual dev
+ *      override, documented as such (not meant for end users).
+ *   2. A cached, still-fresh license from `syntaxshot login`.
+ *   3. Re-validate a stale cached license against the API.
+ *   4. Fall back to Free.
+ */
+export async function resolvePlan(localConfigPlan) {
+  if (localConfigPlan === "pro") return "pro"; // local/dev override, see README
+
+  const cached = readLicenseFile();
+  if (!cached) return "free";
+
+  const age = Date.now() - new Date(cached.lastCheckedAt).getTime();
+  if (age < REVALIDATE_AFTER_MS) {
+    return cached.lastKnownValid ? "pro" : "free";
+  }
+
+  try {
+    const result = await validateWithApi(cached.licenseKey);
+    writeLicenseFile({
+      ...cached,
+      plan: result.plan,
+      lastCheckedAt: new Date().toISOString(),
+      lastKnownValid: !!result.valid,
+    });
+    return result.valid ? "pro" : "free";
+  } catch {
+    // Offline or API down: trust the last known state for a grace period.
+    if (cached.lastKnownValid && age < OFFLINE_GRACE_MS) return "pro";
+    return "free";
+  }
+}

package/src/renderer.js

@@ -0,0 +1,152 @@
+import { createCanvas, GlobalFonts } from "@napi-rs/canvas";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FONTS_DIR = path.join(__dirname, "..", "fonts");
+
+let fontsRegistered = false;
+function ensureFonts() {
+  if (fontsRegistered) return;
+  GlobalFonts.registerFromPath(
+    path.join(FONTS_DIR, "JetBrainsMono-Regular.ttf"),
+    "JetBrains Mono"
+  );
+  GlobalFonts.registerFromPath(
+    path.join(FONTS_DIR, "JetBrainsMono-Bold.ttf"),
+    "JetBrains Mono Bold"
+  );
+  GlobalFonts.registerFromPath(
+    path.join(FONTS_DIR, "JetBrainsMono-Italic.ttf"),
+    "JetBrains Mono Italic"
+  );
+  fontsRegistered = true;
+}
+
+function roundRect(ctx, x, y, w, h, r) {
+  ctx.beginPath();
+  ctx.moveTo(x + r, y);
+  ctx.arcTo(x + w, y, x + w, y + h, r);
+  ctx.arcTo(x + w, y + h, x, y + h, r);
+  ctx.arcTo(x, y + h, x, y, r);
+  ctx.arcTo(x, y, x + w, y, r);
+  ctx.closePath();
+}
+
+/**
+ * @param {Array<Array<{content:string,color:string}>>} lines
+ * @param {object} theme  ver src/themes.js
+ * @param {object} opts   { fileName, fontSize, lineNumbers, padding }
+ */
+export function renderSnippet(lines, theme, opts = {}) {
+  ensureFonts();
+
+  const fontSize = opts.fontSize || 16;
+  const lineHeight = Math.round(fontSize * 1.6);
+  const padding = opts.padding ?? 40;
+  const outerPadding = 64; // margen alrededor de la ventana (fondo con gradiente)
+  const showLineNumbers = opts.lineNumbers ?? true;
+  const fileName = opts.fileName || "snippet";
+  const tabHeight = 56;
+  const charWidth = fontSize * 0.6; // monospace approximation
+
+  const longestLine = Math.max(
+    1,
+    ...lines.map((l) => l.reduce((sum, t) => sum + t.content.length, 0))
+  );
+  const gutterWidth = showLineNumbers
+    ? Math.max(3, String(lines.length).length) * charWidth + 24
+    : 0;
+
+  const codeWidth = longestLine * charWidth;
+  const windowWidth = Math.ceil(gutterWidth + codeWidth + padding * 2);
+  const windowHeight = Math.ceil(tabHeight + lines.length * lineHeight + padding * 1.4);
+
+  const canvasWidth = windowWidth + outerPadding * 2;
+  const canvasHeight = windowHeight + outerPadding * 2;
+
+  const canvas = createCanvas(canvasWidth, canvasHeight);
+  const ctx = canvas.getContext("2d");
+
+  // Fondo con gradiente
+  const grad = ctx.createLinearGradient(0, 0, canvasWidth, canvasHeight);
+  grad.addColorStop(0, theme.pageGradient[0]);
+  grad.addColorStop(1, theme.pageGradient[1]);
+  ctx.fillStyle = grad;
+  ctx.fillRect(0, 0, canvasWidth, canvasHeight);
+
+  // Subtle glow behind the window
+  ctx.save();
+  ctx.filter = "blur(60px)";
+  ctx.fillStyle = theme.glow;
+  roundRect(ctx, outerPadding + 20, outerPadding + 30, windowWidth - 40, windowHeight - 40, 40);
+  ctx.fill();
+  ctx.restore();
+
+  // Sombra de la ventana
+  ctx.save();
+  ctx.shadowColor = "rgba(0,0,0,0.45)";
+  ctx.shadowBlur = 40;
+  ctx.shadowOffsetY = 18;
+  ctx.fillStyle = theme.windowBg;
+  roundRect(ctx, outerPadding, outerPadding, windowWidth, windowHeight, 18);
+  ctx.fill();
+  ctx.restore();
+
+  // Borde
+  ctx.strokeStyle = theme.windowBorder;
+  ctx.lineWidth = 1;
+  roundRect(ctx, outerPadding, outerPadding, windowWidth, windowHeight, 18);
+  ctx.stroke();
+
+  // Tab superior
+  ctx.save();
+  roundRect(ctx, outerPadding, outerPadding, windowWidth, tabHeight, 18);
+  ctx.clip();
+  ctx.fillStyle = theme.tabBg;
+  ctx.fillRect(outerPadding, outerPadding, windowWidth, tabHeight);
+  ctx.restore();
+
+  // Dots estilo macOS
+  const dotY = outerPadding + tabHeight / 2;
+  theme.dots.forEach((color, i) => {
+    ctx.beginPath();
+    ctx.fillStyle = color;
+    ctx.arc(outerPadding + 26 + i * 24, dotY, 7, 0, Math.PI * 2);
+    ctx.fill();
+  });
+
+  // Nombre del archivo
+  ctx.fillStyle = theme.tabText;
+  ctx.font = "600 15px 'JetBrains Mono'";
+  ctx.textBaseline = "middle";
+  ctx.textAlign = "center";
+  ctx.fillText(fileName, outerPadding + windowWidth / 2, dotY);
+  ctx.textAlign = "left";
+
+  // Code
+  const codeStartY = outerPadding + tabHeight + padding * 0.6;
+  const codeStartX = outerPadding + padding;
+  ctx.font = `${fontSize}px 'JetBrains Mono'`;
+  ctx.textBaseline = "top";
+
+  lines.forEach((tokens, i) => {
+    const y = codeStartY + i * lineHeight;
+
+    if (showLineNumbers) {
+      ctx.fillStyle = theme.lineNumberColor;
+      ctx.textAlign = "right";
+      ctx.fillText(String(i + 1), codeStartX + gutterWidth - 20, y + 2);
+      ctx.textAlign = "left";
+    }
+
+    let x = codeStartX + gutterWidth;
+    tokens.forEach((tok) => {
+      ctx.fillStyle = tok.color;
+      ctx.fillText(tok.content, x, y);
+      x += tok.content.length * charWidth;
+    });
+  });
+
+  return canvas;
+}

package/src/scanner.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+import { EXT_TO_LANG } from "./highlighter.js";
+
+// Folders that never make sense to walk into.
+const DEFAULT_EXCLUDED_DIRS = new Set([
+  "node_modules", ".git", ".hg", ".svn",
+  "dist", "build", "out", "coverage", ".next", ".nuxt", ".cache",
+  ".vscode", ".idea", "vendor", "__pycache__", ".venv", "venv",
+]);
+
+// Specific files that exist in almost any project but that
+// nobody wants to show off in a screenshot (config, secrets, lockfiles...).
+const DEFAULT_EXCLUDED_FILENAMES = new Set([
+  "package.json", "package-lock.json", "npm-shrinkwrap.json",
+  "yarn.lock", "pnpm-lock.yaml", "composer.lock", "Gemfile.lock", "Cargo.lock",
+  "tsconfig.json", "tsconfig.node.json", "jsconfig.json",
+  ".gitignore", ".npmrc", ".nvmrc", ".editorconfig",
+  ".eslintrc.json", ".eslintrc", ".prettierrc", ".prettierrc.json",
+]);
+
+function isExcludedFile(fileName, excludedFilenames) {
+  if (fileName.startsWith(".env")) return true;   // .env, .env.local, .env.production...
+  if (fileName.startsWith(".") ) return true;      // dotfiles in general
+  if (fileName.endsWith(".lock")) return true;
+  if (excludedFilenames.has(fileName)) return true;
+  return false;
+}
+
+/**
+ * Recursively walks `rootDir` and returns the absolute paths of
+ * "capturable" files: they have a recognized language extension and are not
+ * in the exclusion list (config, secrets, dependencies, etc).
+ */
+export function findEligibleFiles(rootDir, opts = {}) {
+  const excludedDirs = new Set([...DEFAULT_EXCLUDED_DIRS, ...(opts.excludeDirs || [])]);
+  const excludedFilenames = new Set([...DEFAULT_EXCLUDED_FILENAMES, ...(opts.excludeFiles || [])]);
+
+  const results = [];
+
+  function walk(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (excludedDirs.has(entry.name)) continue;
+        walk(path.join(dir, entry.name));
+        continue;
+      }
+      if (!entry.isFile()) continue;
+
+      const fileName = entry.name;
+      if (isExcludedFile(fileName, excludedFilenames)) continue;
+
+      const ext = path.extname(fileName).toLowerCase();
+      if (!EXT_TO_LANG[ext]) continue; // only recognized code extensions
+
+      results.push(path.join(dir, fileName));
+    }
+  }
+
+  walk(rootDir);
+  return results;
+}

package/src/svgRenderer.js

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FONTS_DIR = path.join(__dirname, "..", "fonts");
+
+let cachedFontBase64 = null;
+function getEmbeddedFontBase64() {
+  if (!cachedFontBase64) {
+    const bytes = fs.readFileSync(path.join(FONTS_DIR, "JetBrainsMono-Regular.ttf"));
+    cachedFontBase64 = bytes.toString("base64");
+  }
+  return cachedFontBase64;
+}
+
+function escapeXml(str) {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/ /g, "\u00A0"); // non-breaking space: survives renderers that
+    // don't honor xml:space="preserve" (many SVG viewers/editors collapse
+    // regular spaces regardless of that attribute)
+}
+
+/**
+ * Same visual layout as renderer.js, but emitted as an SVG string instead of
+ * a rasterized canvas. The font is embedded as base64 so the file looks
+ * right even on a machine that doesn't have JetBrains Mono installed.
+ *
+ * @param {Array<Array<{content:string,color:string}>>} lines
+ * @param {object} theme  see src/themes.js
+ * @param {object} opts   { fileName, fontSize, lineNumbers, padding }
+ */
+export function renderSnippetSVG(lines, theme, opts = {}) {
+  const fontSize = opts.fontSize || 16;
+  const lineHeight = Math.round(fontSize * 1.6);
+  const padding = opts.padding ?? 40;
+  const outerPadding = 64;
+  const showLineNumbers = opts.lineNumbers ?? true;
+  const fileName = opts.fileName || "snippet";
+  const tabHeight = 56;
+  const charWidth = fontSize * 0.6;
+
+  const longestLine = Math.max(
+    1,
+    ...lines.map((l) => l.reduce((sum, t) => sum + t.content.length, 0))
+  );
+  const gutterWidth = showLineNumbers
+    ? Math.max(3, String(lines.length).length) * charWidth + 24
+    : 0;
+
+  const codeWidth = longestLine * charWidth;
+  const windowWidth = Math.ceil(gutterWidth + codeWidth + padding * 2);
+  const windowHeight = Math.ceil(tabHeight + lines.length * lineHeight + padding * 1.4);
+
+  const canvasWidth = windowWidth + outerPadding * 2;
+  const canvasHeight = windowHeight + outerPadding * 2;
+
+  const codeStartY = outerPadding + tabHeight + padding * 0.6;
+  const codeStartX = outerPadding + padding + gutterWidth;
+  const fontFamily = "'JetBrains Mono', monospace";
+
+  const dotsMarkup = theme.dots
+    .map(
+      (color, i) =>
+        `<circle cx="${outerPadding + 26 + i * 24}" cy="${outerPadding + tabHeight / 2}" r="7" fill="${color}"/>`
+    )
+    .join("");
+
+  const linesMarkup = lines
+    .map((tokens, i) => {
+      const y = codeStartY + i * lineHeight + fontSize; // SVG text y = baseline
+      const lineNumberMarkup = showLineNumbers
+        ? `<text x="${codeStartX - 20}" y="${y}" text-anchor="end" font-family="${fontFamily}" font-size="${fontSize}" fill="${theme.lineNumberColor}">${i + 1}</text>`
+        : "";
+
+      const tokensMarkup = tokens
+        .map((tok) => `<tspan fill="${tok.color}">${escapeXml(tok.content)}</tspan>`)
+        .join("");
+
+      return (
+        lineNumberMarkup +
+        `<text x="${codeStartX}" y="${y}" xml:space="preserve" font-family="${fontFamily}" font-size="${fontSize}">${tokensMarkup}</text>`
+      );
+    })
+    .join("\n");
+
+  return `<svg width="${canvasWidth}" height="${canvasHeight}" viewBox="0 0 ${canvasWidth} ${canvasHeight}" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <style>
+      @font-face {
+        font-family: 'JetBrains Mono';
+        src: url(data:font/ttf;base64,${getEmbeddedFontBase64()}) format('truetype');
+      }
+      text { font-family: ${fontFamily}; }
+    </style>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="${theme.pageGradient[0]}"/>
+      <stop offset="1" stop-color="${theme.pageGradient[1]}"/>
+    </linearGradient>
+    <filter id="shadow" x="-50%" y="-50%" width="200%" height="200%">
+      <feDropShadow dx="0" dy="18" stdDeviation="20" flood-color="#000" flood-opacity="0.45"/>
+    </filter>
+  </defs>
+
+  <rect width="${canvasWidth}" height="${canvasHeight}" fill="url(#bg)"/>
+
+  <rect x="${outerPadding}" y="${outerPadding}" width="${windowWidth}" height="${windowHeight}"
+        rx="18" fill="${theme.windowBg}" stroke="${theme.windowBorder}" filter="url(#shadow)"/>
+
+  <clipPath id="tabClip">
+    <rect x="${outerPadding}" y="${outerPadding}" width="${windowWidth}" height="${tabHeight}" rx="18"/>
+  </clipPath>
+  <rect x="${outerPadding}" y="${outerPadding}" width="${windowWidth}" height="${tabHeight}"
+        fill="${theme.tabBg}" clip-path="url(#tabClip)"/>
+
+  ${dotsMarkup}
+
+  <text x="${outerPadding + windowWidth / 2}" y="${outerPadding + tabHeight / 2 + 5}"
+        text-anchor="middle" font-family="${fontFamily}" font-size="15" font-weight="600" fill="${theme.tabText}">${escapeXml(fileName)}</text>
+
+  ${linesMarkup}
+</svg>`;
+}

package/src/themes.js

@@ -0,0 +1,49 @@
+// Cada tema visual define: el "shikiTheme" (paleta de sintaxis) + los
+// colores del "chrome" (fondo, ventana, tab de archivo, glow) que dibuja el canvas.
+export const THEMES = {
+  midnight: {
+    label: "Midnight",
+    shikiTheme: "dracula",
+    pageGradient: ["#1e1b3a", "#0f0c29"],
+    windowBg: "#161327",
+    windowBorder: "rgba(255,255,255,0.06)",
+    tabBg: "#211d3c",
+    tabText: "#c9c3e6",
+    lineNumberColor: "rgba(255,255,255,0.25)",
+    dots: ["#ff5f56", "#ffbd2e", "#27c93f"],
+    glow: "rgba(120, 80, 255, 0.35)",
+  },
+  nord: {
+    label: "Nord",
+    shikiTheme: "nord",
+    pageGradient: ["#3b4252", "#2e3440"],
+    windowBg: "#2e3440",
+    windowBorder: "rgba(255,255,255,0.06)",
+    tabBg: "#3b4252",
+    tabText: "#d8dee9",
+    lineNumberColor: "rgba(255,255,255,0.25)",
+    dots: ["#bf616a", "#ebcb8b", "#a3be8c"],
+    glow: "rgba(94, 129, 172, 0.35)",
+  },
+  solar: {
+    label: "Solar Light",
+    shikiTheme: "solarized-light",
+    pageGradient: ["#fdf6e3", "#eee8d5"],
+    windowBg: "#fdf6e3",
+    windowBorder: "rgba(0,0,0,0.08)",
+    tabBg: "#eee8d5",
+    tabText: "#586e75",
+    lineNumberColor: "rgba(0,0,0,0.3)",
+    dots: ["#ff5f56", "#ffbd2e", "#27c93f"],
+    glow: "rgba(38, 139, 210, 0.15)",
+  },
+};
+
+export function resolveTheme(name) {
+  const t = THEMES[name];
+  if (!t) {
+    const names = Object.keys(THEMES).join(", ");
+    throw new Error(`Tema "${name}" no existe. Disponibles: ${names}`);
+  }
+  return t;
+}

package/src/usage.js

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const USAGE_FILENAME = ".syntaxshot-usage.json";
+const FREE_LIMIT = 10;
+
+function usagePath(cwd) {
+  return path.join(cwd, USAGE_FILENAME);
+}
+
+function readUsage(cwd) {
+  const p = usagePath(cwd);
+  if (!fs.existsSync(p)) return { count: 0 };
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch {
+    return { count: 0 };
+  }
+}
+
+function writeUsage(cwd, usage) {
+  fs.writeFileSync(usagePath(cwd), JSON.stringify(usage, null, 2));
+}
+
+/**
+ * plan: "free" | "pro" (will eventually come from config.licenseKey validated
+ * against your backend; here it's simulated with config.plan)
+ */
+export function checkAndConsume(plan, howMany, cwd = process.cwd()) {
+  if (plan === "pro") return { allowed: true, remaining: Infinity };
+
+  const usage = readUsage(cwd);
+  const remaining = FREE_LIMIT - usage.count;
+
+  if (howMany > remaining) {
+    return { allowed: false, remaining };
+  }
+
+  usage.count += howMany;
+  writeUsage(cwd, usage);
+  return { allowed: true, remaining: FREE_LIMIT - usage.count };
+}
+
+export { FREE_LIMIT };