svg-terminal 1.0.0 → 1.1.1

package/README.md

@@ -18,7 +18,7 @@ Generate animated SVG terminals from a declarative YAML config. The output is a
 ```bash
 npx svg-terminal init                       # writes terminal.yml
 npx svg-terminal generate                   # writes terminal.svg
-npx svg-terminal blocks                     # lists all 47 blocks
+npx svg-terminal blocks                     # lists all 48 blocks
 ```
 
 Or as a GitHub Action — refresh your profile README on a schedule:
@@ -31,14 +31,14 @@ Or as a GitHub Action — refresh your profile README on a schedule:
     commit: true
 ```
 
-See the full [GitHub Action](#github-action) section below, the [block catalog](./examples/blocks/) (47 blocks, one preview each), and the [12-theme gallery](#themes).
+See the full [GitHub Action](#github-action) section below, the [block catalog](./examples/blocks/) (48 blocks, one preview each), and the [12-theme gallery](#themes).
 
 ### What's in the box
 
 - **Declarative YAML config** — write blocks, pick a theme, run the CLI
-- **47 built-in blocks** — across identity, retro / fake-system, status, ASCII art, single-line animation, and humor categories. Browse the [block catalog](./examples/blocks/) for previews of each
+- **48 built-in blocks** — across identity, retro / fake-system, status, ASCII art, single- and multi-line animation, and humor categories. Browse the [block catalog](./examples/blocks/) for previews of each
 - **12 built-in themes** — dracula, nord, monokai, amber, green-phosphor, cyberpunk, solarized-dark, win95, catppuccin, tokyo-night, gruvbox, high-contrast (with chrome to match)
-- **Single-line frame animation** — `BlockResult.animation = { frames, fps, loop }` powers the 9 animated blocks (spinners, clock, dice, progress bar, etc.). Multi-line is a known restriction
+- **Frame animation** — `BlockResult.animation = { frames, fps, loop }` powers the 10 animated blocks (spinners, clock, dice, progress bar, etc.). Frames may be single- **or multi-line** as of #69 (`jumping-jack` is the reference multi-line block)
 - **Dynamic-block cache** — the 5 cacheable blocks (weather, github-stats, github-languages, quote, fun-fact) write to `.svg-terminal-cache.json`. Pair with `--frozen-cache` for offline CI builds
 - **Reduced-motion respected** — `@media (prefers-reduced-motion)` clamps the CSS fade-ins AND (since v0.17) the frame cycle. SMIL-driven typing reveal, cursor walk, and scroll-on-overflow remain animated; pair with `--static` for full stillness
 - **Schema-validated, XSS-safe** — strict zod schema on every config field; user-controllable values are escaped at SVG emit sites. See [SECURITY.md](./SECURITY.md)
@@ -125,7 +125,7 @@ Each is the same 2-block config (motd + neofetch) rendered against the named the
 
 ## Blocks
 
-Run `svg-terminal blocks` to list all 47 (cacheable ones marked `*`), or `svg-terminal blocks <name>` to print one block's config schema directly without grepping the source.
+Run `svg-terminal blocks` to list all 48 (cacheable ones marked `*`), or `svg-terminal blocks <name>` to print one block's config schema directly without grepping the source.
 
 | Block | Description |
 |-------|-------------|
@@ -172,6 +172,7 @@ Run `svg-terminal blocks` to list all 47 (cacheable ones marked `*`), or `svg-te
 | `progress-bar` | Fake build progress bar that fills 0% → 100% |
 | `bouncing-dot` | Single glyph bouncing left ↔ right |
 | `dice-roll` | N d6 dice that tumble and land on a result |
+| `jumping-jack` | Multi-line stick figure doing jumping jacks (reference multi-line animation) |
 | `palette-swatch` | One-line render of all 16 theme palette colors |
 | `semver-bump` | Current semver + bump preview (major/minor/patch) |
 | `ascii-calendar` | Current-month calendar grid with today highlighted |
@@ -230,7 +231,7 @@ accessibility:
   describe: false   # default true — emit <desc> with full content
 ```
 
-**Reduced-motion caveat.** The SVG emits an inline `@media (prefers-reduced-motion: reduce)` rule, but it only applies to CSS animations. The typing reveal, cursor walk, scroll, and frame-cycle animations are SMIL (`<animate>` elements) and SMIL doesn't read the same CSS media query. Users who set the OS-level reduced-motion preference will still see full-speed animation. If that's a problem for your audience, generate with `--static` — same content, no motion at all.
+**Reduced-motion caveat.** The SVG emits an inline `@media (prefers-reduced-motion: reduce)` rule, which applies to CSS animations — the fade-ins and the frame cycle (single- and multi-line) honor it (migrated SMIL → CSS in v0.17). The remaining SMIL holdouts — typing reveal, cursor walk, and scroll-on-overflow — don't read the same CSS media query, so users who set the OS-level reduced-motion preference still see those animate. If that's a problem for your audience, generate with `--static` — same content, no motion at all.
 
 ### Caching API responses
 

package/dist/{chunk-IVINEQLU.js → chunk-24NH6UUG.js}

@@ -1,5 +1,5 @@
 // src/index.ts
-import { z as z50 } from "zod";
+import { z as z51 } from "zod";
 
 // src/core/config.ts
 import { readFileSync } from "fs";
@@ -1284,22 +1284,39 @@ function buildRevealClip(clipId, startX, charWidth, charCount, fontSize, startTi
   const finalWidth = roundCoord(charCount * charWidth);
   return `<defs><clipPath id="${clipId}"><rect x="${startX}" y="${-fontSize}" width="${finalWidth}" height="${fontSize * 2}">${setHold("width", 0, startTime)}<animate attributeName="width" values="${values.join(";")}" keyTimes="${keyTimes.join(";")}" calcMode="discrete" begin="${startTime}ms" dur="${typingDuration}ms" fill="freeze"/></rect></clipPath></defs>`;
 }
-function generateAnimatedOutputLine(y, frames, color, startTime, colorMap, chrome, fps, loop) {
+function generateAnimatedOutputLine(y, frames, color, startTime, colorMap, chrome, fps, loop, lineHeight) {
   const n = frames.length;
   const frameDurMs = 1e3 / fps;
   const cycleMs = Math.round(n * frameDurMs);
   const iter = loop ? "infinite" : "1";
-  const textElements = frames.map((frame, i) => {
-    const styled = hasMarkup(frame);
-    const textContent = styled ? generateStyledText(parseMarkup(frame, colorMap, color), color, chrome.dimOpacity) : escapeXml(frame);
-    const textFill = styled ? "" : ` fill="${escapeXml(color)}"`;
-    const delayMs = Math.round(i * frameDurMs);
-    const anim = `animation: frame-cycle-${n} ${cycleMs}ms linear ${delayMs}ms ${iter}`;
-    return `<text class="tt frame-cycle-${n}"${textFill} opacity="${i === 0 ? "1" : "0"}" style="${anim}">${textContent}</text>`;
-  }).join("");
+  const height = Math.max(1, ...frames.map((f) => f.length));
+  const animFor = (i) => `animation: frame-cycle-${n} ${cycleMs}ms linear ${Math.round(i * frameDurMs)}ms ${iter}`;
+  const renderRow = (row) => {
+    const styled = hasMarkup(row);
+    return {
+      fill: styled ? "" : ` fill="${escapeXml(color)}"`,
+      content: styled ? generateStyledText(parseMarkup(row, colorMap, color), color, chrome.dimOpacity) : escapeXml(row)
+    };
+  };
+  let body;
+  if (height === 1) {
+    body = frames.map((frame, i) => {
+      const { fill, content } = renderRow(frame[0] ?? "");
+      return `<text class="tt frame-cycle-${n}"${fill} opacity="${i === 0 ? "1" : "0"}" style="${animFor(i)}">${content}</text>`;
+    }).join("");
+  } else {
+    body = frames.map((frame, i) => {
+      const rows = [];
+      for (let r = 0; r < height; r++) {
+        const { fill, content } = renderRow(frame[r] ?? "");
+        rows.push(`<text y="${roundCoord(r * lineHeight)}"${fill}>${content}</text>`);
+      }
+      return `<g class="tt frame-cycle-${n}" opacity="${i === 0 ? "1" : "0"}" style="${animFor(i)}">${rows.join("")}</g>`;
+    }).join("");
+  }
   return `
     <g transform="translate(0, ${y})"${fadeInStyle(startTime)}>
-      ${textElements}
+      ${body}
     </g>`;
 }
 function generateOutputLine(y, content, color, startTime, colorMap, chrome, pinWidth, fontSize) {
@@ -1351,7 +1368,8 @@ function generateAllLines(frames, terminal, lineHeight, colors, chrome, animatio
             colorMap,
             chromeConfig,
             frame.framesFps ?? 4,
-            frame.framesLoop ?? true
+            frame.framesLoop ?? true,
+            lineHeight
           )
         );
       } else {
@@ -1374,12 +1392,26 @@ function generateAllLines(frames, terminal, lineHeight, colors, chrome, animatio
   return Array.from(processedLines.entries()).sort((a, b) => a[0] - b[0]).map(([, content]) => content).join("\n");
 }
 
+// src/core/strict-mode.ts
+var STRICT = false;
+function setStrict(enabled) {
+  STRICT = enabled;
+}
+function isStrict() {
+  return STRICT;
+}
+
 // src/core/svg-generator.ts
+function animationHeight(frames) {
+  return Math.max(1, ...frames.map((f) => f.length));
+}
 function countTotalLines(sequences) {
   let total = 0;
   for (const seq of sequences) {
     if (seq.type === "command") {
       total += 1;
+    } else if (seq.frames && seq.frames.length > 0) {
+      total += animationHeight(seq.frames);
     } else {
       total += seq.content.split("\n").length;
     }
@@ -1625,12 +1657,19 @@ function createAnimationFrames(sequences, terminal, maxVisibleLines, scrollDurat
         continue;
       }
       if (seq.frames && seq.frames.length > 0) {
-        buffer.push({ type: "output" });
+        const height = animationHeight(seq.frames);
+        if (height > maxVisibleLines) {
+          const msg = `[svg-terminal] An animated block is ${height} rows tall but only ${maxVisibleLines} row(s) fit the terminal \u2014 the overflow is clipped. Use window.autoHeight (default) or a taller window.height / maxHeight. (#124)`;
+          if (isStrict()) throw new Error(msg);
+          console.warn(msg);
+        }
+        for (let r = 0; r < height; r++) buffer.push({ type: "output" });
         frames.push({
           time: currentTime,
           type: "add-output",
-          lineIndex: buffer.length - 1,
-          content: seq.frames[0],
+          lineIndex: buffer.length - height,
+          // top row of the reserved band
+          content: seq.frames[0].join("\n"),
           // frame 0 acts as the static fallback
           color: seq.color,
           frames: seq.frames,
@@ -2170,7 +2209,63 @@ import { z as z7 } from "zod";
 import { z as z6 } from "zod";
 
 // src/core/http.ts
+import { isIP } from "net";
 var DEFAULT_FETCH_TIMEOUT = 1e4;
+var MAX_REDIRECTS = 5;
+function ipv4Blocked(ip) {
+  const parts = ip.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255)) {
+    return false;
+  }
+  const [a, b] = parts;
+  if (a === 0) return true;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a === 255 && b === 255 && parts[2] === 255 && parts[3] === 255) return true;
+  return false;
+}
+function ipv6Blocked(ip) {
+  const v = ip.toLowerCase();
+  if (v === "::1" || v === "::") return true;
+  if (/^fe[89ab]/.test(v)) return true;
+  if (/^f[cd]/.test(v)) return true;
+  const dotted = v.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (dotted) return ipv4Blocked(dotted[1]);
+  const hex = v.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (hex) {
+    const hi = parseInt(hex[1], 16);
+    const lo = parseInt(hex[2], 16);
+    return ipv4Blocked(`${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`);
+  }
+  return false;
+}
+function isBlockedHost(hostname) {
+  const host = hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+  if (host === "localhost" || host.endsWith(".localhost")) return true;
+  const kind = isIP(host);
+  if (kind === 4) return ipv4Blocked(host);
+  if (kind === 6) return ipv6Blocked(host);
+  return false;
+}
+function fetchBlockReason(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return "unparseable URL";
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return `unsupported scheme "${parsed.protocol}"`;
+  }
+  if (isBlockedHost(parsed.hostname)) {
+    return "private / loopback / link-local address";
+  }
+  return null;
+}
 function safeUrlForLog(url) {
   try {
     const u = new URL(url);
@@ -2207,20 +2302,47 @@ async function readCappedText(response, url) {
   }
   return new TextDecoder().decode(Buffer.concat(chunks));
 }
-var USER_AGENT = `svg-terminal/${true ? "1.0.0" : "0.0.0-dev"}`;
+var USER_AGENT = `svg-terminal/${true ? "1.1.1" : "0.0.0-dev"}`;
 async function fetchWithTimeout(url, timeoutMs = DEFAULT_FETCH_TIMEOUT) {
+  const blocked = fetchBlockReason(url);
+  if (blocked) {
+    console.warn(`[svg-terminal] Refused to fetch ${safeUrlForLog(url)}: ${blocked}`);
+    return null;
+  }
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const response = await fetch(url, {
-      signal: controller.signal,
-      headers: { "User-Agent": USER_AGENT }
-    });
-    if (!response.ok) {
-      console.warn(`[svg-terminal] HTTP ${response.status} from ${safeUrlForLog(url)}`);
-      return null;
+    let currentUrl = url;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+      const response = await fetch(currentUrl, {
+        signal: controller.signal,
+        headers: { "User-Agent": USER_AGENT },
+        redirect: "manual"
+      });
+      if (response.status >= 300 && response.status < 400 && response.headers.has("location")) {
+        let next;
+        try {
+          next = new URL(response.headers.get("location"), currentUrl).toString();
+        } catch {
+          console.warn(`[svg-terminal] Bad redirect Location from ${safeUrlForLog(currentUrl)}`);
+          return null;
+        }
+        const blockedHop = fetchBlockReason(next);
+        if (blockedHop) {
+          console.warn(`[svg-terminal] Refused redirect to ${safeUrlForLog(next)}: ${blockedHop}`);
+          return null;
+        }
+        currentUrl = next;
+        continue;
+      }
+      if (!response.ok) {
+        console.warn(`[svg-terminal] HTTP ${response.status} from ${safeUrlForLog(currentUrl)}`);
+        return null;
+      }
+      return response;
     }
-    return response;
+    console.warn(`[svg-terminal] Too many redirects (>${MAX_REDIRECTS}) fetching ${safeUrlForLog(url)}`);
+    return null;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     if (message.includes("abort")) {
@@ -4339,6 +4461,34 @@ var tocBlock = {
   }
 };
 
+// src/blocks/jumping-jack.ts
+import { z as z50 } from "zod";
+var POSE_OPEN = ["\\o/", " | ", "/ \\"];
+var POSE_SHUT = [" o ", "/|\\", " | "];
+var jumpingJackSchema = z50.object({
+  fps: z50.number().int().min(1).max(30).optional(),
+  command: z50.string().optional(),
+  color: z50.string().optional()
+}).strict();
+var jumpingJackBlock = {
+  name: "jumping-jack",
+  description: "A multi-line stick figure doing jumping jacks",
+  configSchema: jumpingJackSchema,
+  render(_context, config) {
+    const fps = config["fps"] ?? 2;
+    const command = config["command"] ?? "exercise";
+    const color = config["color"] ?? "yellow";
+    const paint = (rows) => rows.map((r) => `[[fg:${color}]]${r}[[/fg]]`);
+    const frames = [paint(POSE_OPEN), paint(POSE_SHUT)];
+    return {
+      command,
+      lines: frames[0],
+      // static fallback (first pose, all 3 rows)
+      animation: { frames, fps }
+    };
+  }
+};
+
 // src/blocks/index.ts
 function registerBuiltinBlocks() {
   registerBlocks([
@@ -4388,15 +4538,15 @@ function registerBuiltinBlocks() {
     paletteSwatchBlock,
     semverBumpBlock,
     asciiCalendarBlock,
-    tocBlock
+    tocBlock,
+    jumpingJackBlock
   ]);
 }
 
 // src/index.ts
 registerBuiltinBlocks();
-var STRICT_BLOCK_CONFIG = false;
 function setStrictBlockConfig(enabled) {
-  STRICT_BLOCK_CONFIG = enabled;
+  setStrict(enabled);
 }
 function validateBlockEntry(block, entry, index) {
   const cfg = entry.config ?? {};
@@ -4404,7 +4554,7 @@ function validateBlockEntry(block, entry, index) {
     try {
       block.configSchema.parse(cfg);
     } catch (err) {
-      if (err instanceof z50.ZodError) {
+      if (err instanceof z51.ZodError) {
         const issues = err.issues.map((i) => {
           const path = i.path.length ? i.path.join(".") : "<root>";
           return `  ${path}: ${i.message}`;
@@ -4435,7 +4585,7 @@ ${issues}`
     const known = block.allowedKeys.join(", ");
     const msg = `Unknown config key(s) [${list}] for block "${block.name}" at blocks[${index}]
   Known keys: ${known}`;
-    if (STRICT_BLOCK_CONFIG) {
+    if (isStrict()) {
       throw new BlockConfigError(block.name, index, msg);
     }
     console.warn(`[svg-terminal] warning: ${msg}`);
@@ -4470,7 +4620,9 @@ async function generate(userConfig, options = {}) {
       pause: resolvePause(entry.pause ?? result.pause),
       pinWidth: result.pinWidth,
       ...result.animation ? {
-        frames: result.animation.frames.map((f) => f.join("\n")),
+        // Carry frames as string[][] (rows preserved) straight through the
+        // timeline — no lossy join/split round-trip (#69, nexus B-PIPELINE).
+        frames: result.animation.frames,
         framesFps: Math.min(30, Math.max(1, result.animation.fps ?? 4)),
         framesLoop: result.animation.loop ?? true
       } : {}
@@ -4600,4 +4752,4 @@ export {
   inspectCache,
   generateStatic
 };
-//# sourceMappingURL=chunk-IVINEQLU.js.map
+//# sourceMappingURL=chunk-24NH6UUG.js.map

package/dist/cli.js

@@ -11,7 +11,7 @@ import {
   mergeConfig,
   setStrictBlockConfig,
   themes
-} from "./chunk-IVINEQLU.js";
+} from "./chunk-24NH6UUG.js";
 
 // src/cli.ts
 import { writeFileSync, watch as fsWatch } from "fs";
@@ -127,7 +127,7 @@ function isZodOptional(t) {
 }
 
 // src/cli.ts
-var VERSION = true ? "1.0.0" : "0.0.0-dev";
+var VERSION = true ? "1.1.1" : "0.0.0-dev";
 var args = process.argv.slice(2);
 var command = args[0];
 function getFlag(name) {

package/dist/index.d.ts

@@ -211,8 +211,11 @@ interface Sequence {
     pause?: number;
     /** Delay before this sequence starts in ms */
     delay?: number;
-    /** Optional multi-frame payload — output sequences only. Each entry is one frame's content (newline-separated lines). Triggers frame-cycle rendering. */
-    frames?: string[];
+    /** Optional multi-frame payload — output sequences only. Each entry is one
+     *  frame; each frame is an array of rows. Multi-line frames are supported
+     *  (#69) — single-row frames (the common case) are `[oneLine]`. Triggers
+     *  frame-cycle rendering. */
+    frames?: string[][];
     /** Frames per second when `frames` is set (default 4, capped at 30). */
     framesFps?: number;
     /** Loop frames forever when set (default true). */
@@ -233,8 +236,9 @@ interface AnimationFrame {
     typingDuration?: number;
     scrollLines?: number;
     bufferStart?: number;
-    /** Multi-frame payload — present only on add-output frames spawned from animated blocks. */
-    frames?: string[];
+    /** Multi-frame payload — present only on add-output frames spawned from
+     *  animated blocks. Each frame is an array of rows (#69 multi-line). */
+    frames?: string[][];
     framesFps?: number;
     framesLoop?: boolean;
     /** Width-pinning opt-in from BlockResult.pinWidth. */
@@ -712,7 +716,13 @@ interface GenerateOptions {
      */
     onCacheEvent?: (event: CacheEventType, key: string) => void;
 }
-/** Enable strict mode globally — unknown block-config keys throw instead of warning. */
+/**
+ * Enable strict mode globally — soft warnings (unknown block-config keys for
+ * schemaless blocks; an over-tall animated band, #124) become hard errors.
+ * The flag lives in `./core/strict-mode.js` so `svg-generator.ts` can read it
+ * without importing this module (which would be circular). Re-exported here as
+ * `setStrictBlockConfig` for back-compat with the CLI + library consumers.
+ */
 declare function setStrictBlockConfig(enabled: boolean): void;
 /**
  * Generate an animated SVG terminal from a declarative config.

package/dist/index.js

@@ -47,7 +47,7 @@ import {
   themes,
   tokyoNight,
   win95
-} from "./chunk-IVINEQLU.js";
+} from "./chunk-24NH6UUG.js";
 export {
   BlockConfigError,
   ConfigError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svg-terminal",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Generate animated SVG terminals for GitHub READMEs from a declarative YAML config. 47 built-in blocks, 12 themes, zero runtime deps in the output.",
   "type": "module",
   "main": "dist/index.js",
@@ -59,13 +59,14 @@
     "node": ">=22.0.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.19.19",
     "@vitest/coverage-v8": "^4.1.7",
-    "eslint": "^9.39.4",
+    "eslint": "^10.4.1",
     "tsup": "^8.0.0",
     "tsx": "^4.22.3",
-    "typescript": "^5.7.0",
+    "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.0",
     "vitest": "^4.1.7"
   },