goosetools-worker 0.1.1 → 0.2.1

package/README.md

@@ -1,12 +1,12 @@
 # carousel-maker
 
-Brand-aware Instagram carousel generator. Photos + words in → ready-to-post 1080×1350 PNGs out.
+Brand-aware Instagram carousel generator. Photos, clips and words in → ready-to-post 1080×1350 slides out (PNG, or MP4 for slides built on a video).
 
 ## How it works
 
 1. **`brand.yml`** — your colors, fonts, handle. Set once; every slide inherits it.
 2. **A style** — `styles/<name>/` holds a template set + `style.yml` (font/color overrides) + the reference images that inspired it. Like Recraft: drop inspo screenshots in `styles/<name>/refs/`, have the agent distill them into templates, reuse forever. `brand.yml → defaultStyle` picks the default; a carousel can override with `style: <name>` in its slides.yml.
-3. **A carousel folder** — `carousels/<name>/` with a `slides.yml` (and photos alongside it).
+3. **A carousel folder** — `carousels/<name>/` with a `slides.yml` (and `photos/` + `videos/` alongside it).
 4. **Render** — HTML templates filled with your brand tokens, screenshotted headless at 2x.
 
 ## Usage
@@ -16,6 +16,9 @@ npm install && npx playwright install chromium   # first time only
 
 node src/render.js carousels/my-post
 # → carousels/my-post/output/slide-01.png, slide-02.png, ...
+
+# optional, last: only if you want video slides (see below)
+brew install ffmpeg
 ```
 
 ## slides.yml
@@ -29,6 +32,9 @@ slides:
   - template: photo        # your photo, text over a dark gradient
     photo: photos/desk.jpg
     text: caption over the photo
+  - template: photo        # same template, but the background MOVES
+    video: videos/build.mp4
+    text: caption over the clip
   - template: text         # dark slide, *asterisks* render in accent color
     text: |-
       body copy with
@@ -51,21 +57,149 @@ Every slide gets a progress bar + page counter baked in, and a swipe chevron on
 
 Add a template by dropping a new `templates/<name>.html` — it gets the full brand.yml context plus `{{text}}`, `{{photoSrc}}`, `{{handle}}`, `{{ui}}` (the progress bar + chevron; include it in every template). If the new template has a light background, add its name to `LIGHT_TEMPLATES` in `src/render.js` so the chrome adapts.
 
+## Video slides
+
+Any slide that takes a `photo:` takes a `video:` instead — same template, same
+`focus:` / `zoom:` framing controls, but the clip plays full-bleed behind the
+slide's text. Instagram carousels accept video items, so a deck can mix stills
+and motion freely.
+
+```yaml
+  - template: photo
+    video: videos/build.mp4
+    focus: "60% 45%"   # centre of the subject, as on a photo
+    zoom: 1.8
+    text: watch it *come together*
+```
+
+How it renders: the slide is screenshotted twice — once normally over a frame
+pulled out of the clip (`slide-03.png` — what the framing self-check reads),
+and once with every
+background stripped so only the artwork remains. ffmpeg then crops the clip to
+the slide shape and burns that artwork over it (`slide-03.mp4`, H.264 /
+yuv420p, 1080 wide, audio kept, first 60s).
+
+This means **no template needs to know about video** — every style's `photo`
+template gained video support for free.
+
+### ffmpeg (optional, but required for video)
+
+Video slides need `ffmpeg` and `ffprobe` on your PATH. They do **not** come
+with Node, npm, or Playwright — Playwright bundles an ffmpeg, but it's built
+`--disable-everything` for WebM screen recording: no H.264, no AAC, no
+ffprobe. So it's a real install:
+
+```bash
+brew install ffmpeg              # macOS
+winget install Gyan.FFmpeg       # Windows
+sudo apt install ffmpeg          # Linux
+```
+
+It's genuinely optional: a deck with no `video:` slides never even checks for
+it. But a deck **with** clips fails loudly rather than quietly rendering them
+as stills — a carousel that looks finished and silently isn't the one you
+asked for is the worse outcome. `goosetools-worker status` shows whether this
+computer can do video.
+
 ## Goose Tools worker
 
 This repo doubles as the **worker** behind goosetools.com's Carousel Maker.
 The web app queues jobs; a worker on your own computer claims them, drafts
 the slide copy with your local Claude Code login (your subscription), renders
-with the engine above, and uploads the finished PNGs.
+with the engine above, and uploads the finished slides.
 
 ```bash
 # one-time: install Claude Code + sign in, then
-node worker/index.js --url https://goosetools.com --token gt_...   # token from the website
+npx --yes goosetools-worker install --url https://goosetools.com --token gt_...   # token from the website
 ```
 
+`install` saves the token to `~/.goosetools/env` and registers a login
+service (launchd on macOS, a Scheduled Task on Windows) so the worker runs
+in the background whenever the computer is on — even after a restart.
+`npx --yes goosetools-worker uninstall` removes it. To run in the foreground
+instead: `npx --yes goosetools-worker run --url … --token …`.
+
 Optional env: `VOICE_DIR` points at a writing-voice folder the drafts should
-follow (see `worker/index.js`). Erin's Mac runs it permanently via launchd —
-`scripts/com.ern.carousel-maker.worker.plist` (config in `worker/.env`).
+follow (see `worker/index.js`).
+
+### Worker commands
+
+| Command | What it does |
+| --- | --- |
+| `install --token gt_…` | First-time setup: save the token, install the background copy, register the service. |
+| `update` | Pull the newest code into the background copy and restart it. Reuses the saved token. |
+| `status` | What's installed, whether it's running, and recent log lines. Start here when something's wrong. |
+| `uninstall` | Remove the service and the saved token. |
+| `run` | Run the loop in this window instead of in the background. |
+
+All of them work via `npx --yes goosetools-worker@latest <command>`.
+
+## Worker FAQ
+
+**The website says my computer isn't connected.**
+Run `npx --yes goosetools-worker@latest status`. It tells you whether the
+worker is installed, whether the process is actually running, and whether a
+token is saved. Each line is one of the things that has to be true for the
+website to show "Connected".
+
+**How do I get a new version onto my computer?**
+`npx --yes goosetools-worker@latest update`.
+
+This matters more than it looks. The background service does **not** run from
+wherever you ran `npx`, or from a git checkout — it runs a copy installed
+under `~/.goosetools/app`. New code only reaches that copy when you reinstall
+it, and the running process only picks the new code up when it restarts (Node
+reads every file once, at startup). `update` does both, and reuses your saved
+token so you don't have to find it again.
+
+**I updated but nothing changed.**
+Check `status` — the "Installed" line is the version the daemon will run, and
+"Running" shows the live process. If Installed is the new version but the
+behavior is old, the process didn't restart; run `update` again.
+
+**`status` shows errors — is my worker broken?**
+Look at the "last written" time next to the error block. The service restarts
+itself and keeps its old log, so errors from days ago sit there long after
+they stopped mattering. If "Activity" was written recently and "Errors" wasn't,
+the worker is fine — it's polling normally.
+
+**"Poll failed (will retry)"** is the worker not reaching the server: laptop
+asleep, wifi dropped, or the site briefly down. It retries every 30s on its
+own; no action needed unless it's still happening now.
+
+**"This computer's worker is outdated for this job"** means the website sent
+a kind of job this worker version doesn't know how to do. Run `update`.
+
+**"Style X isn't installed on this computer yet"** — styles live on the
+machine that renders them (`styles/<slug>/`). A style generated on a different
+computer won't exist on this one; regenerate it here.
+
+**Jobs sit in "queued" forever.**
+Queued means the website has the job but no worker has claimed it. Confirm the
+worker is running with `status`, and confirm it's pointed at the same server
+(the "Server" line) as the site you queued from.
+
+**Where are the logs?**
+`~/.goosetools/worker.log` (activity) and `~/.goosetools/worker.err.log`
+(errors). `status` tails both.
+
+**Do I need to keep a terminal open?** No — that's what `install` sets up.
+`run` is the foreground alternative if you'd rather watch it work.
+
+### Publishing a new worker version
+
+Users get updates from npm, so pushing to git is not enough — `update` and
+`npx goosetools-worker@latest` both resolve to the **published** version:
+
+```bash
+npm version patch   # or minor/major
+npm publish
+git push --follow-tags
+```
+
+Until you publish, `npm view goosetools-worker version` will lag the repo and
+everyone else stays on the older code. `status` flags the mismatch on your own
+machine ("you're ahead — local dev build").
 
 ## Roadmap
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goosetools-worker",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "The Goose Tools carousel worker — your computer drafts and renders carousel slides for goosetools.com using your own Claude account.",
   "repository": {
     "type": "git",
@@ -9,7 +9,8 @@
   "files": [
     "worker",
     "src",
-    "styles",
+    "styles/graph-paper",
+    "styles/polka-dot",
     "carousels/demo/slides.yml",
     "brand.yml",
     "README.md"

package/src/fonts.js

@@ -0,0 +1,102 @@
+// Shared font registry — the only fonts the renderer will load. Used by
+// render.js (Google Fonts URL) and the worker (validating/prompting the
+// top-level `fonts:` override in slides.yml).
+
+// per-family axis specs — some families don't ship every weight
+export const FONT_SPECS = {
+  "Instrument Serif": "ital@0;1",
+  "Fraunces": "ital,wght@0,400;0,500;0,600;1,400;1,500",
+  "Silkscreen": "wght@400;700",
+  "Pixelify Sans": "wght@400;500;700",
+  "Doto": "wght@400;700;900",
+  "VT323": "wght@400",
+  "Space Mono": "wght@400;700",
+  "Geist Mono": "wght@400;500",
+  // brand-settings shortlist (goosetools.com)
+  "Space Grotesk": "wght@400;500;700",
+  "Inter": "wght@400;500;700",
+  "DM Sans": "opsz,wght@9..40,400;9..40,500;9..40,700",
+  "DM Serif Display": "ital@0;1",
+  "Archivo": "wght@400;600;700",
+  "Bricolage Grotesque": "opsz,wght@12..96,400;12..96,700",
+  "Work Sans": "wght@400;500;700",
+  "IBM Plex Sans": "wght@400;500;700",
+};
+
+export const FONT_OVERRIDE_KEYS = ["heading", "body", "mono"];
+
+// ── Uploaded fonts ───────────────────────────────────────────────────────────
+// A font the user uploaded on goosetools.com. It arrives with the brand as
+// {family, url} and is NOT in the registry above — Google has never heard of
+// it, so it has to be fetched and declared as an @font-face instead.
+
+/**
+ * Font container signatures — the same check the overlay worker does.
+ *
+ * The content type a browser reports for a .woff2 is routinely
+ * application/octet-stream, so the bytes are the only real signal. Anything
+ * that isn't a font (a renamed zip, an image) is dropped rather than handed to
+ * Chromium's font parser.
+ */
+function sniff(buf) {
+  const tag = buf.subarray(0, 4).toString("latin1");
+  if (tag === "wOF2") return "woff2";
+  if (tag === "wOFF") return "woff";
+  if (tag === "OTTO") return "otf";
+  if (tag === "true" || tag === "ttcf") return "ttf";
+  if (buf.readUInt32BE(0) === 0x00010000) return "ttf";
+  return null;
+}
+
+/**
+ * @font-face rules for the uploaded fonts, with the file inlined.
+ *
+ * Inlined as a data URI rather than linked because the page is rendered from
+ * setContent with no origin to resolve a relative path against, and a font
+ * that 404s mid-render is a silent fallback rather than an error.
+ *
+ * One bad or unreachable font is skipped with a warning — it must not take
+ * down a render the rest of which is fine.
+ */
+export async function customFontFaces(fonts) {
+  const out = [];
+  for (const f of fonts ?? []) {
+    if (!f?.family || !/^https:\/\//.test(String(f.url ?? ""))) continue;
+    try {
+      const res = await fetch(f.url);
+      if (!res.ok) throw new Error(`download failed: ${res.status}`);
+      const buf = Buffer.from(await res.arrayBuffer());
+      const format = sniff(buf);
+      if (!format) {
+        console.warn(`  ! "${f.family}" isn't a font file — skipped`);
+        continue;
+      }
+      out.push(
+        `@font-face{font-family:"${f.family}";` +
+          `src:url("data:font/${format};base64,${buf.toString("base64")}") format("${format}");` +
+          `font-display:block;}`,
+      );
+    } catch (e) {
+      console.warn(`  ! "${f.family}" skipped (${e?.message ?? e})`);
+    }
+  }
+  return out.join("\n");
+}
+
+// Per-carousel font overrides (slides.yml top-level `fonts:`) may only name
+// families from the registry; unknown keys/families are dropped, never fatal.
+export function sanitizeFonts(fonts, ownFamilies = []) {
+  if (!fonts || typeof fonts !== "object" || Array.isArray(fonts)) return null;
+  // A family the user uploaded is as legitimate as a registry one — it is
+  // declared as an @font-face instead of fetched from Google, and dropping it
+  // here is what made "use my brand font" silently fall back to the style's.
+  const own = new Set(ownFamilies);
+  const out = {};
+  for (const [k, v] of Object.entries(fonts)) {
+    if (FONT_OVERRIDE_KEYS.includes(k) && (FONT_SPECS[String(v)] || own.has(String(v)))) {
+      out[k] = String(v);
+    }
+    if (k === "headingWeight" && Number.isFinite(Number(v))) out.headingWeight = Number(v);
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}

package/src/normalize-photos.js

@@ -0,0 +1,53 @@
+// Normalize photo orientation: iPhone JPEGs store sideways pixels + an EXIF
+// "rotate me" flag. Browsers honor the flag; raw-pixel readers don't — so
+// focus/zoom coordinates estimated from the raw file disagree with the
+// rendered crop. Re-encoding through Chromium's decoder bakes the rotation
+// into the pixels (and strips the flag), making both views agree.
+//
+// usage: node src/normalize-photos.js <photos-dir>
+
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { chromium } from "playwright";
+
+const dir = resolve(process.argv[2] ?? "");
+if (!dir) {
+  console.error("usage: node src/normalize-photos.js <photos-dir>");
+  process.exit(1);
+}
+
+const MIME = { ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp" };
+const files = readdirSync(dir).filter((f) => MIME[extname(f).toLowerCase()]);
+if (files.length === 0) process.exit(0);
+
+const browser = await chromium.launch({ args: ["--mute-audio", "--use-mock-keychain"] });
+const page = await browser.newPage();
+
+for (const f of files) {
+  const p = join(dir, f);
+  const mime = MIME[extname(f).toLowerCase()];
+  const dataUri = `data:${mime};base64,${readFileSync(p).toString("base64")}`;
+  const out = await page.evaluate(
+    async ({ src, mime }) => {
+      const img = new Image();
+      await new Promise((ok, err) => {
+        img.onload = ok;
+        img.onerror = err;
+        img.src = src;
+      });
+      // naturalWidth/Height are post-EXIF-rotation in Chromium; drawing to a
+      // canvas bakes the upright orientation into the pixels.
+      const canvas = document.createElement("canvas");
+      canvas.width = img.naturalWidth;
+      canvas.height = img.naturalHeight;
+      canvas.getContext("2d").drawImage(img, 0, 0);
+      return canvas.toDataURL(mime, 0.92);
+    },
+    { src: dataUri, mime },
+  );
+  // Same filename, same format — nothing downstream has to know.
+  writeFileSync(p, Buffer.from(out.split(",")[1], "base64"));
+  console.log(`normalized ${f}`);
+}
+
+await browser.close();