@effing/create 0.1.0

package/LICENSE

@@ -0,0 +1,11 @@
+O'Saasy License
+
+Copyright © 2026, Trackuity BV.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+2. No licensee or downstream recipient may use the Software (including any modified or derivative versions) to directly compete with the original Licensor by offering it to third parties as a hosted, managed, or Software-as-a-Service (SaaS) product or cloud service where the primary value of the service is the functionality of the Software itself.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @effing/create
+
+**Scaffold a new Effing project with the starter template.**
+
+> Part of the [**Effing**](../../README.md) family — programmatic video creation with TypeScript.
+
+## Usage
+
+```bash
+# Using npm
+npm create @effing my-app
+
+# Using pnpm
+pnpm create @effing my-app
+
+# Using yarn
+yarn create @effing my-app
+
+# Using npx directly
+npx @effing/create my-app
+```
+
+Then:
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+Open [http://localhost:3839](http://localhost:3839) to see your project.
+
+## What's included
+
+The starter template includes:
+
+- **React Router** for routing and nifty preview pages
+- **Annies** — Frame-based animations streamed as TAR archives
+- **Effies** — Video compositions combining animations, images, and audio
+- **FFS integration** — A “Render it FFS” button that can POST your Effie JSON to an `@effing/ffs` server (which you can run locally or remotely)
+- Example annies and effies to get you started
+
+## Development
+
+This package is part of the Effing monorepo.
+
+### Testing locally
+
+```bash
+# From the monorepo root
+cd packages/create
+pnpm install
+pnpm build
+
+# Test the CLI (creates a project outside the monorepo)
+node dist/index.js /tmp/test-effing-app
+```
+
+### Updating the template
+
+1. Make changes in `demos/starter`
+2. Run `pnpm build` in this package
+3. The `prebuild` script automatically copies `demos/starter` → `template/`, renaming dotfiles and replacing `workspace:*` versions

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import fs from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+async function copyDir(src, dest) {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destName = entry.name.startsWith("_") ? "." + entry.name.slice(1) : entry.name;
+    const destPath = path.join(dest, destName);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}
+function printUsage() {
+  console.log(`
+Usage: npm create @effing <project-name>
+
+Creates a new Effing project with the starter template.
+
+Examples:
+  npm create @effing my-app
+  pnpm create @effing my-app
+  yarn create @effing my-app
+`);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    printUsage();
+    process.exit(0);
+  }
+  const projectName = args[0];
+  if (!projectName) {
+    console.error("Error: Please specify a project name.\n");
+    printUsage();
+    process.exit(1);
+  }
+  const root = path.resolve(projectName);
+  const templateDir = path.resolve(__dirname, "../template");
+  try {
+    await fs.access(root);
+    console.error(`Error: Directory "${projectName}" already exists.`);
+    process.exit(1);
+  } catch {
+  }
+  console.log(`
+Creating a new Effing project in ${root}...
+`);
+  await copyDir(templateDir, root);
+  const pkgPath = path.join(root, "package.json");
+  const pkg = JSON.parse(await fs.readFile(pkgPath, "utf-8"));
+  pkg.name = path.basename(root);
+  await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  console.log("Done! To get started:\n");
+  console.log(`  cd ${projectName}`);
+  console.log("  npm install");
+  console.log("  npm run dev\n");
+  console.log("Then open http://localhost:3839 to see your project.\n");
+}
+main().catch((err) => {
+  console.error("Error:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@effing/create",
+  "version": "0.1.0",
+  "description": "Create a new Effing project",
+  "type": "module",
+  "bin": "./dist/index.js",
+  "files": [
+    "dist",
+    "template"
+  ],
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "effing",
+    "create",
+    "scaffold",
+    "cli"
+  ],
+  "license": "O'Saasy",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "node scripts/copy-template.js",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/template/README.md

@@ -0,0 +1,245 @@
+# Effing Starter Demo
+
+A complete example application demonstrating how to build Annies (animations) and Effies (video compositions) using the `@effing/*` packages.
+
+## Getting Started
+
+```bash
+cd demos/starter
+pnpm install
+pnpm dev
+```
+
+Open [http://localhost:3839](http://localhost:3839) to see the demo.
+
+## Project Structure
+
+```
+demos/starter/
+├── app/
+│   ├── annies/              # Annie animation definitions
+│   │   ├── index.ts         # Annie registry and types
+│   │   └── *.annie.tsx      # Annies
+│   ├── effies/              # Effie composition definitions
+│   │   ├── index.ts         # Effie registry and types
+│   │   └── *.effie.tsx      # Effies
+│   ├── routes/
+│   │   ├── _index.tsx       # Homepage listing all annies/effies
+│   │   ├── an.$segment.tsx  # Annie TAR streaming endpoint
+│   │   ├── ff.$segment.tsx  # Effie JSON endpoint
+│   │   ├── pan.$annieId.tsx # Annie preview page
+│   │   └── pff.$effieId.tsx # Effie preview page
+│   ├── fonts.server.ts      # Font definitions and loading utils
+│   └── urls.server.ts       # URL generation helpers
+└── vite.config.ts
+```
+
+## Creating Annies
+
+Annies are frame-based animations. Create a file at `app/annies/*.annie.tsx`:
+
+```typescript
+// app/annies/my-animation.annie.tsx
+import { z } from "zod";
+import { pngFromSatori } from "@effing/satori";
+import { tween, easeOutQuad } from "@effing/tween";
+import type { AnnieRendererArgs } from ".";
+
+// 1. Define props schema
+export const propsSchema = z.object({
+  text: z.string(),
+  frameCount: z.number().int().min(1).optional(),
+});
+
+type MyAnimationProps = z.infer<typeof propsSchema>;
+
+// 2. Define preview props (used by preview page)
+export const previewProps: MyAnimationProps = {
+  text: "Hello!",
+  frameCount: 60,
+};
+
+// 3. Export async generator that yields PNG frames
+export async function* renderer({
+  props: { text, frameCount = 60 },
+  width,
+  height,
+}: AnnieRendererArgs<MyAnimationProps>): AsyncGenerator<Buffer> {
+  const fonts = await loadFonts([myFont]);
+
+  yield* tween(frameCount, async ({ lower: progress }) => {
+    const scale = 1 + 0.3 * easeOutQuad(progress);
+
+    return pngFromSatori(
+      <div style={{
+        width, height,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        fontSize: 72,
+        transform: `scale(${scale})`,
+      }}>
+        {text}
+      </div>,
+      { width, height, fonts }
+    );
+  });
+}
+```
+
+The Annie will automatically appear on the homepage and be accessible at:
+
+- **Preview:** `/pan/my-animation`
+- **TAR stream:** `/an/{signed-segment}?w=1080&h=1080`
+
+## Creating Effies
+
+Effies are video compositions that combine Annies, images, audio, and effects. Create a file at `app/effies/*.effie.tsx`:
+
+```typescript
+// app/effies/my-video.effie.tsx
+import { z } from "zod";
+import { effieData, effieSegment } from "@effing/effie";
+import { annieUrl } from "~/urls.server";
+import type { EffieRendererArgs } from ".";
+
+// 1. Define props schema
+export const propsSchema = z.object({
+  title: z.string(),
+  imageUrl: z.string().url(),
+});
+
+type MyVideoProps = z.infer<typeof propsSchema>;
+
+// 2. Define preview props
+export const previewProps: MyVideoProps = {
+  title: "My Video",
+  imageUrl: "https://picsum.photos/1080/1920",
+};
+
+// 3. Export async function that returns EffieData
+export async function renderer({
+  props: { title, imageUrl },
+  width,
+  height,
+}: EffieRendererArgs<MyVideoProps>) {
+  return effieData({
+    width,
+    height,
+    fps: 30,
+    cover: imageUrl,
+    background: { type: "color", color: "black" },
+    segments: [
+      effieSegment({
+        duration: 5,
+        layers: [
+          {
+            type: "animation",
+            source: await annieUrl({
+              annieId: "text-typewriter",
+              props: { text: title, fontSize: 72 },
+              width,
+              height,
+            }),
+          },
+        ],
+      }),
+    ],
+  });
+}
+```
+
+The Effie will automatically appear on the homepage and be accessible at:
+
+- **Preview:** `/pff/my-video`
+- **JSON:** `/ff/{signed-segment}?ratio=1:1`
+
+## Routes
+
+### Homepage (`/`)
+
+Lists all available Annies and Effies with links to their preview pages.
+
+### Annie Preview (`/pan/:annieId`)
+
+Displays an interactive preview of an Annie using `@effing/annie-player`. Shows:
+
+- Playable animation with load/play/pause controls
+- Direct URL to the TAR stream
+
+### Effie Preview (`/pff/:effieId`)
+
+Comprehensive preview of an Effie composition using `@effing/effie-preview`. Shows:
+
+- Cover image (or rendered video after clicking "Render it FFS")
+- Background preview
+- All segments with their layers
+- Render button to generate video via FFS
+
+### Annie Stream (`/an/:segment`)
+
+Serves Annie TAR archives. The segment is a signed payload containing:
+
+- `annieId` — Which Annie to render
+- Props — Animation parameters
+
+### Effie JSON (`/ff/:segment`)
+
+Serves Effie JSON. The segment is a signed payload containing:
+
+- `effieId` — Which Effie to render
+- Props — Composition parameters
+
+## CDN Caching
+
+Both the `/an/:segment` and `/ff/:segment` routes can easily be placed behind a CDN in production. Since the segment contains signed, deterministic parameters, the same URL always produces the same output, making them ideal cache keys.
+
+Note also that CDN timeouts are not a concern for the annies, even though they might take a while to generate in practice, because they are streamed frame by frame. The CDN receives data continuously and won't time out waiting for the first byte.
+
+## Environment Variables
+
+```bash
+# Required: Base URL for the application
+BASE_URL=http://localhost:3839
+# Required: Secret for signing URL segments
+SECRET_KEY=your-secret-key
+
+# Optional: FFS rendering service
+FFS_BASE_URL=http://localhost:2000
+FFS_API_KEY=your-ffs-api-key
+```
+
+## URL Generation
+
+The `urls.server.ts` module provides helpers for generating URLs to be used in effies:
+
+```typescript
+import { annieUrl, pngUrlFromSatori } from "~/urls.server";
+
+// Generate signed Annie URL
+const url = await annieUrl({
+  annieId: "text-typewriter",
+  props: { text: "Hello", fontSize: 72 },
+  width: 1080,
+  height: 1920,
+});
+
+// Generate data URL from JSX
+const coverUrl = await pngUrlFromSatori(
+  <div>Cover Image</div>,
+  { width: 1080, height: 1920, fonts }
+);
+```
+
+## Rendering Videos
+
+The preview page can render videos if FFS is configured:
+
+1. Set `FFS_BASE_URL` and `FFS_API_KEY` environment variables
+2. Open an Effie preview page (`/pff/:effieId`)
+3. Click "Render it FFS" to send the composition to the rendering service
+4. The rendered video appears in place of the cover image
+
+You can also render at different scales (33%, 67%, 100%, 200%) for faster previews or higher quality output.
+
+In production, you'd use an FFS server directly to render effies. Point FFS at your `/ff/:segment` endpoint and it will fetch the effie JSON, resolve all annie URLs, and produce the final video.

package/template/_env.example

@@ -0,0 +1,5 @@
+BASE_URL=http://localhost:3839
+SECRET_KEY=s3cr3t-k3y-goes-here
+
+FFS_BASE_URL=http://localhost:2000
+FFS_API_KEY=ffs-4p1-k3y-goes-here

package/template/app/annies/index.ts

@@ -0,0 +1,45 @@
+import invariant from "tiny-invariant";
+import type { z } from "zod";
+
+/**
+ * Arguments passed to annie renderer functions
+ */
+export type AnnieRendererArgs<PropsType> = {
+  props: PropsType;
+  width: number;
+  height: number;
+};
+
+type AnnieModule = {
+  propsSchema: z.ZodSchema<unknown>;
+  previewProps: object;
+  renderer: (args: AnnieRendererArgs<unknown>) => AsyncGenerator<Buffer>;
+};
+
+// Dynamically load all annie modules
+const modules = Object.fromEntries(
+  Object.entries(import.meta.glob("./*.annie.tsx")).map(([key, value]) => {
+    const id = key.split("/").slice(-1)[0].replace(".annie.tsx", "");
+    return [id, value];
+  }),
+);
+
+export type AnnieId = string;
+
+export function isAnnieId(annieId: string): annieId is AnnieId {
+  return annieId in modules;
+}
+
+export function getAnnieIds(): string[] {
+  return Object.keys(modules);
+}
+
+export async function getAnnie(annieId: string): Promise<AnnieModule> {
+  invariant(isAnnieId(annieId), `no annie found for annieId '${annieId}'`);
+  const module = (await modules[annieId]()) as AnnieModule;
+  return {
+    renderer: module.renderer,
+    previewProps: module.previewProps,
+    propsSchema: module.propsSchema,
+  };
+}

package/template/app/annies/photo-zoom.annie.tsx

@@ -0,0 +1,56 @@
+import sharp from "sharp";
+import { z } from "zod";
+import { tween, easeOutQuad } from "@effing/tween";
+import type { AnnieRendererArgs } from ".";
+
+export const propsSchema = z.object({
+  imageUrl: z.string().url(),
+  frameCount: z.number().int().min(1).optional(),
+  zoomLevel: z.number().optional(),
+});
+
+export type PhotoZoomProps = z.infer<typeof propsSchema>;
+
+export const previewProps: PhotoZoomProps = {
+  imageUrl: "https://picsum.photos/1200/1200",
+  frameCount: 120,
+  zoomLevel: 0.2,
+};
+
+export async function* renderer({
+  props: { imageUrl, frameCount = 90, zoomLevel = 0.2 },
+  width,
+  height,
+}: AnnieRendererArgs<PhotoZoomProps>): AsyncGenerator<Buffer> {
+  // Fetch and decode the source image
+  const image = await fetch(imageUrl);
+  const imageBuffer = await image.arrayBuffer();
+  const { data: originalImageData, info: originalImageInfo } = await sharp(
+    Buffer.from(imageBuffer),
+  )
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+
+  const imageSharp = sharp(originalImageData, {
+    raw: {
+      width: originalImageInfo.width,
+      height: originalImageInfo.height,
+      channels: originalImageInfo.channels,
+    },
+  });
+
+  // Generate frames with zoom effect
+  yield* tween(frameCount, async ({ lower: p }) => {
+    const zoomValue = 1 + zoomLevel * easeOutQuad(p);
+    const ow = Math.round(width * zoomValue);
+    const oh = Math.round(height * zoomValue);
+    const left = Math.floor((ow - width) / 2);
+    const top = Math.floor((oh - height) / 2);
+    return imageSharp
+      .clone()
+      .resize(ow, oh, { fit: "cover" })
+      .extract({ left, top, width, height })
+      .jpeg()
+      .toBuffer();
+  });
+}

package/template/app/annies/text-typewriter.annie.tsx

@@ -0,0 +1,151 @@
+import { z } from "zod";
+import { interBold, loadFonts } from "~/fonts.server";
+import { pngFromSatori } from "@effing/satori";
+import { tween } from "@effing/tween";
+import type { AnnieRendererArgs } from ".";
+
+export const propsSchema = z.object({
+  text: z.string(),
+  fontSize: z.number().int().min(1),
+  fontFamily: z.enum(["Inter", "Roboto", "Open Sans"]).optional(),
+  fontColor: z.string().optional(),
+  typingFrameCount: z.number().int().min(10).optional(),
+  blinkingFrameCount: z.number().int().min(0).optional(),
+  horizontalAlignment: z.enum(["left", "center", "right"]).optional(),
+  verticalAlignment: z.enum(["top", "center", "bottom"]).optional(),
+});
+
+export type TextTypewriterProps = z.infer<typeof propsSchema>;
+
+export const previewProps: TextTypewriterProps = {
+  text: "Hello World!",
+  fontSize: 72,
+  fontFamily: "Inter",
+  fontColor: "#ffffff",
+  horizontalAlignment: "center",
+  verticalAlignment: "center",
+};
+
+export async function* renderer({
+  props: {
+    text,
+    fontSize,
+    fontFamily = "Inter",
+    fontColor = "#ffffff",
+    typingFrameCount,
+    blinkingFrameCount = 60,
+    horizontalAlignment = "center",
+    verticalAlignment = "center",
+  },
+  width,
+  height,
+}: AnnieRendererArgs<TextTypewriterProps>): AsyncGenerator<Buffer> {
+  const fonts = await loadFonts([interBold]);
+
+  if (!typingFrameCount) {
+    typingFrameCount = text.length * 3;
+  }
+
+  // Typing phase
+  yield* tween(typingFrameCount, async ({ lower: p }) => {
+    const charsShown = Math.floor(p * text.length);
+    const textToShow = text.slice(0, charsShown);
+    return pngFromSatori(
+      <TextTypewriterOverlay
+        text={textToShow}
+        fontSize={fontSize}
+        fontFamily={fontFamily}
+        fontColor={fontColor}
+        horizontalAlignment={horizontalAlignment}
+        verticalAlignment={verticalAlignment}
+        cursorShown={true}
+      />,
+      { width, height, fonts },
+    );
+  });
+
+  // Blinking cursor phase
+  yield* tween(blinkingFrameCount, async ({ lower: p }) => {
+    const cursorShown = Math.floor(p * 5) % 2 === 1;
+    return pngFromSatori(
+      <TextTypewriterOverlay
+        text={text}
+        fontSize={fontSize}
+        fontFamily={fontFamily}
+        fontColor={fontColor}
+        horizontalAlignment={horizontalAlignment}
+        verticalAlignment={verticalAlignment}
+        cursorShown={cursorShown}
+      />,
+      { width, height, fonts },
+    );
+  });
+}
+
+export function TextTypewriterOverlay({
+  text,
+  fontFamily = "Inter",
+  fontSize,
+  fontColor = "#ffffff",
+  horizontalAlignment = "center",
+  verticalAlignment = "center",
+  cursorShown,
+}: {
+  text: string;
+  fontFamily?: string;
+  fontSize: number;
+  fontColor?: string;
+  horizontalAlignment?: "left" | "center" | "right";
+  verticalAlignment?: "top" | "center" | "bottom";
+  cursorShown: boolean;
+}) {
+  return (
+    <div
+      style={{
+        display: "flex",
+        position: "absolute",
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        alignItems: { top: "flex-start", center: "center", bottom: "flex-end" }[
+          verticalAlignment
+        ],
+        justifyContent: {
+          left: "flex-start",
+          center: "center",
+          right: "flex-end",
+        }[horizontalAlignment],
+        padding: 40,
+      }}
+    >
+      <div
+        style={{
+          fontFamily,
+          fontSize: fontSize,
+          fontWeight: "bold",
+          color: fontColor,
+          display: "flex",
+          flexDirection: "row",
+          alignItems: "center",
+          justifyContent: "center",
+          textAlign: horizontalAlignment,
+          whiteSpace: "nowrap",
+        }}
+      >
+        {text}
+        <span
+          style={{
+            height: fontSize,
+            width: 3,
+            display: "block",
+            backgroundColor: fontColor,
+            marginLeft: 4,
+            verticalAlign: "middle",
+            opacity: Number(cursorShown),
+          }}
+        />
+      </div>
+    </div>
+  );
+}