goosetools-worker 0.2.4 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goosetools-worker",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "The Goose Tools carousel worker — your computer drafts and renders carousel slides for goosetools.com using your own Claude account.",
   "repository": {
     "type": "git",
@@ -13,7 +13,8 @@
     "styles/polka-dot",
     "carousels/demo/slides.yml",
     "brand.yml",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "type": "module",
   "bin": {

package/skills/reference-analysis.md

@@ -0,0 +1,149 @@
+# Reference Analysis Methodology
+
+How to study a set of reference images, map them onto something new, and check
+the finished render against them. Shared by the Carousel Maker (slides) and the
+Overlay Factory (overlays on reels) — the reference images are the source of
+truth for EVERY behavior described here; there are no hardcoded rules. Worker
+prompts splice individual sections by the SECTION markers below.
+
+SHARED FILE: the source of truth is workers/shared/reference-analysis.md in the
+goosetools repo, copied into each worker's skills/ by `npm run workers:sync`.
+
+<!-- SECTION: principles -->
+## Principles — both tools
+
+- **Purpose first, paint second.** Work out what each reference is FOR — the
+  recurring format a follower would recognize — before its colours and fonts.
+  A copy that nails the palette but misses the format is wrong.
+- **Variance vs constants.** Across the set, note what varies and what never
+  changes. Freedom lives exactly where the references vary; fidelity is owed
+  everywhere they don't.
+- **Same-account test.** The finished thing should read as the same account's
+  work if posted next to the references — same format, same typographic
+  voice, same palette logic. Pixel-matching any one reference is NOT the goal.
+- **Look, don't assume.** Read every image before deciding anything, and judge
+  your own output by looking at the render, not by re-reading your markup.
+
+<!-- SECTION: analyze -->
+## Phase A — understand what each reference is DOING
+
+Read every reference image first. For each one, work out:
+
+- **Role**: is this the cover (the hook slide), a middle content slide, or
+  the closer/CTA? The first reference is usually the cover; use layout and
+  copy cues (page counters, "swipe", "follow") to confirm.
+- **Content job**: what is the slide FOR? Presenting a color palette with
+  labeled swatches? Comparing a before vs an after? Listing tips? Showcasing
+  a product photo? The recurring format a follower would recognize is the
+  thing to reproduce — purpose first, paint second.
+- **Photo and subject**: where does the photo's main subject sit in the
+  frame? How tight is the crop?
+- **Overlays**: where do overlays (swatch stacks, badges, labels, text
+  blocks) sit relative to the subject? Record which behavior this set uses:
+  some styles keep overlays OFF the subject (overlays live in the empty
+  side of the frame); others deliberately lay elements OVER the photo as
+  part of the look. Both are legitimate — copy whichever these references do.
+- **Variance vs constants**: across the whole set, what varies (number of
+  swatches, which side the overlay sits on, crop tightness) and what never
+  changes (the format, the typography, the palette treatment, the border
+  style)? Freedom lives exactly where the references vary; fidelity is owed
+  everywhere they don't.
+
+<!-- SECTION: map -->
+## Phase B — map references onto the new carousel, role to role
+
+Match by ROLE and FORMAT, never image-to-image: your cover should do what
+the reference cover does, your closer what their closer does, and every
+middle slide should follow the references' middle-slide format. Your slide 3
+does not need to mirror reference slide 3.
+
+- **Colors**: if the user's photos share a coherent palette (e.g. they are
+  all sunsets, all one product line), sample the carousel's colors from THE
+  USER'S PHOTOS so the deck feels made from their images. If the photos are
+  visually unrelated, keep the references' original colors. Never mix in
+  colors from anywhere else.
+- **Variance**: whatever varied across the references may vary across your
+  slides the same way — swatch counts, overlay side, crop tightness. Do not
+  make every slide identical when the references weren't.
+- **Overlay placement**: follow the coverage behavior recorded in Phase A.
+  If the references keep overlays clear of the subject, look at each of the
+  user's photos (and what the user's prompt says the photo is about) and
+  place overlays on the empty side — use `variant: flip` on a slide to
+  mirror a template's overlay to the other side. If the references overlay
+  the photo deliberately, do the same.
+- **Photo count adaptation** — the references decide the slide mix:
+  - More photos than slides: choose the photos that best serve each slide's
+    message, but if the user's prompt asks to show something specific, the
+    photo showing it MUST be used.
+  - Fewer photos than the format wants: if the references put a photo on
+    every slide, reuse a photo with a DIFFERENT focus/zoom crop so it reads
+    as a new frame; if the references include photo-free formats (statement
+    slides, text slides), use those instead. Never pad with invented filler
+    content.
+
+<!-- SECTION: compare -->
+## Phase C — compare each rendered slide against the references
+
+For each rendered slide, find the reference(s) with the same ROLE (slide 1 =
+cover, last slide = CTA/closer, everything else = middle) and ask:
+
+- **Same-account test**: if this slide were posted next to the references,
+  would it read as the same account's work — same format, same typographic
+  voice, same palette logic? Exact alignment with any single reference is
+  NOT required; matching the format is.
+- **Overlay-behavior test**: does the slide follow the references' coverage
+  behavior? If they keep overlays off the subject, is this slide's subject
+  (or a face) hidden under a swatch stack, badge, or caption? If so it
+  fails — fix with `variant: flip` (mirror the overlay side) or a focus/zoom
+  change that moves the subject clear.
+- **Framing test**: is the thing the slide is about actually prominent and
+  centered by the crop, exactly as the reference format frames its subjects?
+
+Fix vocabulary (per slide): `focus` ("X% Y%" on the original photo),
+`zoom` (1–3), `variant: flip` (mirror the overlay side), `swatches`
+(recount/recolor a swatch list — only on slides that already have one).
+Never rewrite a slide's text or switch its template during comparison.
+
+<!-- SECTION: overlay-analyze -->
+## Overlay Phase A — understand what the references are DOING
+
+These are frames from reels (or screenshots of them) with text or graphics laid
+over footage. For the set, work out:
+
+- **Format**: what one episode of this is — a question, a hot take, a stat, a
+  quote, a before/after label? That is what the fields should capture.
+- **Hierarchy**: what the eye reads first, second, third, and how that is
+  achieved (size, weight, colour, a box, a bar, a label above the main line).
+- **Type**: weight, case, letter-spacing, serif vs sans vs mono, line length,
+  how many lines the main text runs to.
+- **Containers**: solid box, translucent scrim, outline, shadow only, or text
+  straight on footage — and corner radius, border, padding.
+- **Placement**: where on the 9:16 frame each element sits, and how much of
+  the frame the overlay takes. Note anything placed where Instagram's UI would
+  cover it — keep the format but move it into the safe band.
+- **Colour logic**: which colours are fixed accents and which come from the
+  footage; how contrast is kept over busy or bright video.
+- **Variance vs constants** across the set (see Principles).
+
+<!-- SECTION: overlay-compare -->
+## Overlay Phase C — compare the rendered frame against the references
+
+Look at the rendered frame (sample text in every field, over grey) next to the
+references and ask:
+
+- **Same-account test**: would this sit next to the references as the same
+  series? Same format, hierarchy, type treatment, container style, colour
+  logic.
+- **Hierarchy test**: does the eye land where it lands in the references, in
+  the same order?
+- **Proportion test**: is the overlay roughly the size the references use — not
+  a tiny label where they fill the band, not a slab where they are a caption?
+- **Legibility test**: would it read over ANY footage, on a phone at arm's
+  length? Thin text straight on video fails.
+- **Safe-area test**: is anything in Instagram's top bar, right action rail or
+  bottom caption zone?
+
+Fix by editing the templates (sizes, weights, spacing, colours, containers,
+widthPct, anchor). Never change field keys, the content brief, or wording that
+the user typed or asked for.
+

package/src/render.js

@@ -5,6 +5,7 @@ import yaml from "js-yaml";
 import { chromium } from "playwright";
 import { FONT_SPECS, customFontFaces, sanitizeFonts } from "./fonts.js";
 import { assertFfmpeg, composite, posterFrame } from "./video.js";
+import { styleDirFor } from "./state.js";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -39,7 +40,8 @@ const spec = yaml.load(readFileSync(join(dir, "slides.yml"), "utf8"));
 
 // resolve active style: slides.yml `style:` > brand.yml defaultStyle
 const styleName = spec.style ?? brandBase.defaultStyle;
-const styleDir = join(ROOT, "styles", styleName);
+// Built-ins ship in the package; everything else is per-machine (state.js).
+const styleDir = styleDirFor(styleName);
 if (!existsSync(styleDir)) {
   console.error(`Unknown style "${styleName}" — expected ${styleDir}`);
   process.exit(1);

package/src/state.js

@@ -0,0 +1,55 @@
+// Where the Carousel Maker's per-machine work lives.
+//
+// Generated styles and rendered decks used to be written inside the package
+// folder (styles/<slug>, carousels/web-*). Installed from npm, that folder is
+// ~/.goosetools/app/node_modules/goosetools-worker, which `update` deletes and
+// reinstalls — so every update silently deleted every style the user had
+// generated (it happened on 2026-09-26). They now live in ~/.goosetools/carousel,
+// which nothing reinstalls. The built-in styles and the demo deck still ship
+// in the package, because they ARE the package.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** Styles that ship in the package (see package.json `files`). */
+export const SHIPPED_STYLES = ["graph-paper", "polka-dot"];
+
+export const STATE_DIR = process.env.GOOSETOOLS_CAROUSEL_DIR ?? join(homedir(), ".goosetools", "carousel");
+export const STYLES_DIR = join(STATE_DIR, "styles");
+/** Per-job work folders: the deck, its photos, its rendered slides. */
+export const WORK_DIR = join(STATE_DIR, "carousels");
+
+/** Where a style's folder is: in the package if it ships, otherwise in state. */
+export function styleDirFor(slug) {
+  return SHIPPED_STYLES.includes(slug) ? join(ROOT, "styles", slug) : join(STYLES_DIR, slug);
+}
+
+/**
+ * Move any style that isn't a built-in out of the package folder.
+ *
+ * Only a checkout still has them there (an npm install lost them when it was
+ * replaced), but a checkout is exactly where a style made during development
+ * sits — so this runs on every start and is a no-op once done. A style
+ * already in state wins; the package copy is then just removed.
+ */
+export function migrateStylesOutOfPackage() {
+  const pkgStyles = join(ROOT, "styles");
+  if (!existsSync(pkgStyles)) return 0;
+  mkdirSync(STYLES_DIR, { recursive: true });
+  let moved = 0;
+  for (const d of readdirSync(pkgStyles, { withFileTypes: true })) {
+    if (!d.isDirectory() || SHIPPED_STYLES.includes(d.name)) continue;
+    const from = join(pkgStyles, d.name);
+    const to = join(STYLES_DIR, d.name);
+    if (!existsSync(to)) {
+      cpSync(from, to, { recursive: true });
+      moved++;
+    }
+    rmSync(from, { recursive: true, force: true });
+  }
+  return moved;
+}

package/worker/index.js

@@ -13,6 +13,7 @@ import { promisify } from "node:util";
 import yaml from "js-yaml";
 import { upload } from "./upload.js";
 import { skillSection } from "./skill.js";
+import { migrateStylesOutOfPackage, STYLES_DIR, styleDirFor, WORK_DIR } from "../src/state.js";
 import { extFromUrl } from "./style.js";
 import { FONT_SPECS, sanitizeFonts } from "../src/fonts.js";
 import { assertFfmpeg, isVideoPath, posterFrame } from "../src/video.js";
@@ -120,7 +121,7 @@ const MAX_PROMPT_REFS = 6;
 async function ensureStyleRefs(styleSlug, styleRefUrls) {
   const urls = (styleRefUrls ?? []).slice(0, 20);
   if (urls.length === 0) return [];
-  const refsDir = join(ROOT, "styles", styleSlug, "refs");
+  const refsDir = join(styleDirFor(styleSlug), "refs");
   const manifestPath = join(refsDir, "manifest.json");
 
   const cachedPaths = () => {
@@ -485,10 +486,10 @@ async function draftSlides(job, styleDir, media, refPaths, brand) {
 async function runJob(job) {
   console.log(`▶ job ${job.id}: "${(job.prompt ?? "").slice(0, 60)}" [${job.styleSlug}]`);
 
-  const styleDir = join(ROOT, "styles", job.styleSlug);
+  const styleDir = styleDirFor(job.styleSlug);
   if (!existsSync(styleDir)) throw new Error(`Style "${job.styleSlug}" isn't installed on this computer yet`);
 
-  const dir = join(ROOT, "carousels", `web-${job.id.slice(0, 8)}`);
+  const dir = join(WORK_DIR, `web-${job.id.slice(0, 8)}`);
   mkdirSync(join(dir, "photos"), { recursive: true });
   mkdirSync(join(dir, "videos"), { recursive: true });
   // Older servers don't send these — default to applying the brand, matching
@@ -699,6 +700,14 @@ Do not rewrite any slide's text and do not switch templates.`;
 
 // ── Main loop ────────────────────────────────────────────────────────────────
 console.log(`Goose Tools worker connected to ${BASE_URL} — waiting for jobs (Ctrl+C to stop)`);
+// Styles made from a checkout sat inside the package folder; move them to
+// ~/.goosetools/carousel so an update can't delete them (src/state.js).
+try {
+  const moved = migrateStylesOutOfPackage();
+  if (moved) console.log(`Moved ${moved} style(s) to ${STYLES_DIR}.`);
+} catch (e) {
+  console.error(`Couldn't move styles out of the package: ${e.message}`);
+}
 let firstPoll = true;
 
 while (true) {

package/worker/style.js

@@ -17,6 +17,7 @@ import { extname, join } from "node:path";
 import yaml from "js-yaml";
 import { upload } from "./upload.js";
 import { skillSection } from "./skill.js";
+import { styleDirFor, WORK_DIR } from "../src/state.js";
 
 const RESERVED_SLUGS = new Set(["graph-paper", "polka-dot"]);
 const REQUIRED_TEMPLATES = ["cover", "text", "photo", "cta"];
@@ -137,13 +138,13 @@ export async function runStyleJob(job, { api, execFileAsync, ROOT, TOKEN, BASE_U
   console.log(`▶ style ${job.id}: "${name}" (${refUrls.length} refs) [${slug}]`);
 
   if (RESERVED_SLUGS.has(slug)) throw new Error(`"${slug}" is a built-in style`);
-  const styleDir = join(ROOT, "styles", slug);
+  const styleDir = styleDirFor(slug);
   const marker = join(styleDir, ".generated");
   if (existsSync(styleDir) && !existsSync(marker)) {
-    throw new Error(`A hand-made style already exists at styles/${slug} on this computer`);
+    throw new Error(`A hand-made style already exists at ${styleDir} on this computer`);
   }
 
-  const workDir = join(ROOT, "carousels", `style-${job.id.slice(0, 8)}`);
+  const workDir = join(WORK_DIR, `style-${job.id.slice(0, 8)}`);
   const refsDir = join(workDir, "refs");
   mkdirSync(refsDir, { recursive: true });
 
@@ -157,7 +158,7 @@ export async function runStyleJob(job, { api, execFileAsync, ROOT, TOKEN, BASE_U
     refPaths.push(p);
   }
 
-  const exemplarDir = join(ROOT, "styles", "graph-paper");
+  const exemplarDir = styleDirFor("graph-paper");
   const exemplar = {
     styleYml: readFileSync(join(exemplarDir, "style.yml"), "utf8"),
     cover: readFileSync(join(exemplarDir, "templates", "cover.html"), "utf8"),
@@ -207,7 +208,7 @@ export async function runStyleJob(job, { api, execFileAsync, ROOT, TOKEN, BASE_U
     join(styleDir, "refs", "manifest.json"),
     JSON.stringify({ urls: refUrls.slice(0, 20) }, null, 2),
   );
-  console.log(`  styles/${slug}/ written (${Object.keys(files).length} files + ${refPaths.length} refs)`);
+  console.log(`  ${styleDir} written (${Object.keys(files).length} files + ${refPaths.length} refs)`);
 
   // Preview: render the new style's cover + text slide with the user's brand.
   const previewDir = join(workDir, "preview");