svg-scroll-draw 2.13.0 → 2.14.0

package/README.md

@@ -363,7 +363,7 @@ import { ScrollDraw } from 'svg-scroll-draw/vue';
 ## AOS drop-in — switch from AOS in one line
 
 Already using [AOS](https://github.com/michalsnik/aos)? `svg-scroll-draw/aos` speaks its API and
-reads its markup, so the move is an import change. Keep every `data-aos`, `data-aos-offset`,
+reads its markup, so the move is an import change — or one command: `npx svg-scroll-draw migrate`. Keep every `data-aos`, `data-aos-offset`,
 `data-aos-delay`, `data-aos-anchor-placement` and custom animation; delete `aos.css` — the styles ship
 inside the module. 3.0 KB gzipped with the styles, against 6.7 KB for AOS 2.3.4 with its stylesheet.
 
@@ -403,7 +403,8 @@ Differences, on purpose:
 
 On [ScrollReveal](https://scrollrevealjs.org)? It is GPL-3.0 (with a paid licence for commercial work)
 and has not shipped since 4.0.9. `svg-scroll-draw/scrollreveal` is an independent, MIT-licensed
-implementation of the same API, so the move is an import change. 4.5 KB gzipped, against 5.6 KB.
+implementation of the same API, so the move is an import change — or one command: `npx svg-scroll-draw migrate`.
+4.5 KB gzipped, against 5.6 KB.
 
 ```diff
 - import ScrollReveal from 'scrollreveal';
@@ -434,8 +435,8 @@ Differences, on purpose:
 ## vivus drop-in — keep your `new Vivus()` code
 
 On [vivus](https://github.com/maxwellito/vivus)? It has not shipped since 0.4.6 (April 2021).
-`svg-scroll-draw/vivus` runs the same API, so the move is an import change. 3.9 KB gzipped, against
-4.1 KB.
+`svg-scroll-draw/vivus` runs the same API, so the move is an import change — or one command:
+`npx svg-scroll-draw migrate`. 3.9 KB gzipped, against 4.1 KB.
 
 ```diff
 - import Vivus from 'vivus';
@@ -604,6 +605,19 @@ npx svg-scroll-draw init
 
 Scaffolds a ready-to-use starter file for React, Vue, Svelte, Solid, or Vanilla JS.
 
+### Switching from AOS, ScrollReveal or vivus
+
+```bash
+npx svg-scroll-draw migrate --dry-run   # see what would change
+npx svg-scroll-draw migrate             # apply it
+```
+
+Points every `import` / `require` of `aos`, `scrollreveal` and `vivus` at the matching drop-in, swaps CDN
+`<script>` tags for the script-tag builds (dropping any stale `integrity` hash), removes AOS's `aos.css`
+imports, `<link>`s and `@import`s, and swaps the dependency in `package.json`. It rewrites module names,
+URLs and dependency entries only — never the code that uses them — skips `node_modules` and build output,
+and will not write over uncommitted git changes unless you pass `--force`.
+
 ---
 
 ## Browser support

package/dist/aos/index.d.mts

@@ -0,0 +1,53 @@
+type AOSAnchorPlacement = 'top-bottom' | 'top-center' | 'top-top' | 'center-bottom' | 'center-center' | 'center-top' | 'bottom-bottom' | 'bottom-center' | 'bottom-top';
+interface AOSOptions {
+    /** Px from the trigger point before the animation starts. Default 120. */
+    offset?: number;
+    /** Ms to wait before animating in. Default 0. */
+    delay?: number;
+    /** Animation length in ms. Default 400. */
+    duration?: number;
+    /** An AOS easing name (`'ease-out-back'`…) or any CSS timing function. Default `'ease'`. */
+    easing?: string;
+    /** Animate only the first time the element scrolls in. Default false. */
+    once?: boolean;
+    /** Animate out again when the element scrolls past the top. Default false. */
+    mirror?: boolean;
+    /** Which edge of the element meets which edge of the window. Default `'top-bottom'`. */
+    anchorPlacement?: AOSAnchorPlacement;
+    /** Skip animations entirely: a boolean, a predicate, or a viewport class. */
+    disable?: boolean | 'phone' | 'tablet' | 'mobile' | (() => boolean);
+    /** Document event that starts AOS. Default `'DOMContentLoaded'`. */
+    startEvent?: string;
+    /** Do not watch the DOM for new `[data-aos]` elements. Default false. */
+    disableMutationObserver?: boolean;
+    /** Class added at init. Default `'aos-init'`. */
+    initClassName?: string;
+    /** Class added while animated in. Default `'aos-animate'`. */
+    animatedClassName?: string;
+    /** Also add the `data-aos` value as classes (for animate.css-style sets). Default false. */
+    useClassNames?: boolean;
+    /** Accepted for compatibility; scroll handling is batched per frame instead. */
+    throttleDelay?: number;
+    /** Accepted for compatibility; resize handling is debounced internally. */
+    debounceDelay?: number;
+}
+/** Start animating every `[data-aos]` element. Same options as AOS. */
+declare function init(options?: AOSOptions): HTMLElement[];
+/** Recalculate every trigger position (after a layout change). */
+declare function refresh(): void;
+/** Find `[data-aos]` elements again (after adding or removing some), then refresh. */
+declare function refreshHard(): void;
+/**
+ * Stop listening and remove the injected stylesheet. Not in AOS — added for
+ * single-page apps that unmount the page AOS was started on. Elements keep
+ * whatever classes they have.
+ */
+declare function destroy(): void;
+declare const AOS: {
+    init: typeof init;
+    refresh: typeof refresh;
+    refreshHard: typeof refreshHard;
+    destroy: typeof destroy;
+};
+
+export { type AOSAnchorPlacement, type AOSOptions, AOS as default, destroy, init, refresh, refreshHard };

package/dist/aos/index.d.ts

@@ -0,0 +1,53 @@
+type AOSAnchorPlacement = 'top-bottom' | 'top-center' | 'top-top' | 'center-bottom' | 'center-center' | 'center-top' | 'bottom-bottom' | 'bottom-center' | 'bottom-top';
+interface AOSOptions {
+    /** Px from the trigger point before the animation starts. Default 120. */
+    offset?: number;
+    /** Ms to wait before animating in. Default 0. */
+    delay?: number;
+    /** Animation length in ms. Default 400. */
+    duration?: number;
+    /** An AOS easing name (`'ease-out-back'`…) or any CSS timing function. Default `'ease'`. */
+    easing?: string;
+    /** Animate only the first time the element scrolls in. Default false. */
+    once?: boolean;
+    /** Animate out again when the element scrolls past the top. Default false. */
+    mirror?: boolean;
+    /** Which edge of the element meets which edge of the window. Default `'top-bottom'`. */
+    anchorPlacement?: AOSAnchorPlacement;
+    /** Skip animations entirely: a boolean, a predicate, or a viewport class. */
+    disable?: boolean | 'phone' | 'tablet' | 'mobile' | (() => boolean);
+    /** Document event that starts AOS. Default `'DOMContentLoaded'`. */
+    startEvent?: string;
+    /** Do not watch the DOM for new `[data-aos]` elements. Default false. */
+    disableMutationObserver?: boolean;
+    /** Class added at init. Default `'aos-init'`. */
+    initClassName?: string;
+    /** Class added while animated in. Default `'aos-animate'`. */
+    animatedClassName?: string;
+    /** Also add the `data-aos` value as classes (for animate.css-style sets). Default false. */
+    useClassNames?: boolean;
+    /** Accepted for compatibility; scroll handling is batched per frame instead. */
+    throttleDelay?: number;
+    /** Accepted for compatibility; resize handling is debounced internally. */
+    debounceDelay?: number;
+}
+/** Start animating every `[data-aos]` element. Same options as AOS. */
+declare function init(options?: AOSOptions): HTMLElement[];
+/** Recalculate every trigger position (after a layout change). */
+declare function refresh(): void;
+/** Find `[data-aos]` elements again (after adding or removing some), then refresh. */
+declare function refreshHard(): void;
+/**
+ * Stop listening and remove the injected stylesheet. Not in AOS — added for
+ * single-page apps that unmount the page AOS was started on. Elements keep
+ * whatever classes they have.
+ */
+declare function destroy(): void;
+declare const AOS: {
+    init: typeof init;
+    refresh: typeof refresh;
+    refreshHard: typeof refreshHard;
+    destroy: typeof destroy;
+};
+
+export { type AOSAnchorPlacement, type AOSOptions, AOS as default, destroy, init, refresh, refreshHard };

package/dist/cinematic/index.d.mts

@@ -0,0 +1,72 @@
+type StoryEasing = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring' | 'bounce' | 'elastic';
+/** A traced path that strokes itself on across a scroll range. */
+interface DrawAnimation {
+    type: 'draw';
+    /** DOM id the runtime binds to (with leading '#'), e.g. "#path-3". */
+    target: string;
+    /** SVG path data, in canvas coordinates. */
+    d: string;
+    /** Pre-measured total path length (px). */
+    length: number;
+    /** Scroll progress where the draw begins, e.g. "20%". */
+    start: string;
+    /** Scroll progress where the draw completes, e.g. "50%". */
+    end: string;
+    stroke: string;
+    strokeWidth: number;
+    easing: StoryEasing;
+}
+/** Any layer fading opacity across a scroll range. */
+interface FadeAnimation {
+    type: 'fade';
+    target: string;
+    start: string;
+    end: string;
+    from: number;
+    to: number;
+}
+type StoryAnimation = DrawAnimation | FadeAnimation;
+interface StoryScene {
+    id: string;
+    /** Optional background layer (a product photo) as a data URL or remote URL. */
+    background?: string;
+    animations: StoryAnimation[];
+}
+interface Story {
+    version: 1;
+    /** Total scroll height of the experience, e.g. "400vh". */
+    totalHeight: string;
+    /** The authoring viewBox the coordinates are expressed in. */
+    canvas: {
+        width: number;
+        height: number;
+    };
+    scenes: StoryScene[];
+}
+
+interface CinematicOptions {
+    /** Mount point — a selector or element. Becomes the scroll wrapper. */
+    wrapper: string | HTMLElement;
+}
+interface CinematicInstance {
+    /** Stop the scroll loop and detach observers (built DOM is left in place). */
+    destroy: () => void;
+    /** Current global scroll progress through the story (0–1). */
+    getProgress: () => number;
+}
+/**
+ * The viral loader. Reads a Cinematic Story (authored in the Studio) and wires
+ * a scroll-scrubbed timeline: paths stroke themselves on and layers fade in as
+ * the user scrolls, all driven off the wrapper's scroll progress.
+ *
+ *   import { Cinematic } from "svg-scroll-draw";
+ *   import story from "./story.json";
+ *   new Cinematic({ wrapper: "#app" }).loadStory(story);
+ */
+declare class Cinematic {
+    private mount;
+    constructor(options: CinematicOptions);
+    loadStory(story: Story): CinematicInstance;
+}
+
+export { Cinematic, type CinematicInstance, type CinematicOptions, type DrawAnimation, type FadeAnimation, type Story, type StoryAnimation, type StoryEasing, type StoryScene };

package/dist/cinematic/index.d.ts

@@ -0,0 +1,72 @@
+type StoryEasing = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring' | 'bounce' | 'elastic';
+/** A traced path that strokes itself on across a scroll range. */
+interface DrawAnimation {
+    type: 'draw';
+    /** DOM id the runtime binds to (with leading '#'), e.g. "#path-3". */
+    target: string;
+    /** SVG path data, in canvas coordinates. */
+    d: string;
+    /** Pre-measured total path length (px). */
+    length: number;
+    /** Scroll progress where the draw begins, e.g. "20%". */
+    start: string;
+    /** Scroll progress where the draw completes, e.g. "50%". */
+    end: string;
+    stroke: string;
+    strokeWidth: number;
+    easing: StoryEasing;
+}
+/** Any layer fading opacity across a scroll range. */
+interface FadeAnimation {
+    type: 'fade';
+    target: string;
+    start: string;
+    end: string;
+    from: number;
+    to: number;
+}
+type StoryAnimation = DrawAnimation | FadeAnimation;
+interface StoryScene {
+    id: string;
+    /** Optional background layer (a product photo) as a data URL or remote URL. */
+    background?: string;
+    animations: StoryAnimation[];
+}
+interface Story {
+    version: 1;
+    /** Total scroll height of the experience, e.g. "400vh". */
+    totalHeight: string;
+    /** The authoring viewBox the coordinates are expressed in. */
+    canvas: {
+        width: number;
+        height: number;
+    };
+    scenes: StoryScene[];
+}
+
+interface CinematicOptions {
+    /** Mount point — a selector or element. Becomes the scroll wrapper. */
+    wrapper: string | HTMLElement;
+}
+interface CinematicInstance {
+    /** Stop the scroll loop and detach observers (built DOM is left in place). */
+    destroy: () => void;
+    /** Current global scroll progress through the story (0–1). */
+    getProgress: () => number;
+}
+/**
+ * The viral loader. Reads a Cinematic Story (authored in the Studio) and wires
+ * a scroll-scrubbed timeline: paths stroke themselves on and layers fade in as
+ * the user scrolls, all driven off the wrapper's scroll progress.
+ *
+ *   import { Cinematic } from "svg-scroll-draw";
+ *   import story from "./story.json";
+ *   new Cinematic({ wrapper: "#app" }).loadStory(story);
+ */
+declare class Cinematic {
+    private mount;
+    constructor(options: CinematicOptions);
+    loadStory(story: Story): CinematicInstance;
+}
+
+export { Cinematic, type CinematicInstance, type CinematicOptions, type DrawAnimation, type FadeAnimation, type Story, type StoryAnimation, type StoryEasing, type StoryScene };

package/dist/cli/init.js

@@ -25,8 +25,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // src/cli/init.ts
 var readline = __toESM(require("readline"));
-var fs = __toESM(require("fs"));
-var path = __toESM(require("path"));
+var fs2 = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
 
 // src/cli/generators.ts
 var SAMPLE_SVG_JSX = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 100">
@@ -138,6 +138,254 @@ function needsSelector(framework) {
   return framework === "vanilla";
 }
 
+// src/cli/migrate.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var import_node_child_process = require("child_process");
+var LIBS = ["aos", "scrollreveal", "vivus"];
+var LABEL = { aos: "AOS", scrollreveal: "ScrollReveal", vivus: "vivus" };
+var esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function rewriteSpecifiers(src, changes) {
+  let out = src;
+  for (const lib of LIBS) {
+    const spec = lib === "aos" ? `aos(?:\\/dist\\/aos(?:\\.js)?)?` : esc(lib);
+    const target = `svg-scroll-draw/${lib}`;
+    const fromRe = new RegExp(`(\\bfrom\\s*)(['"])${spec}\\2`, "g");
+    const dynRe = new RegExp(`(\\bimport\\s*\\(\\s*)(['"])${spec}\\2(\\s*\\))`, "g");
+    const reqRe = new RegExp(`(\\brequire\\s*\\(\\s*)(['"])${spec}\\2(\\s*\\))`, "g");
+    let n = 0;
+    out = out.replace(fromRe, (_m, pre, q) => {
+      n++;
+      return `${pre}${q}${target}${q}`;
+    });
+    out = out.replace(dynRe, (_m, pre, q, post) => {
+      n++;
+      return `${pre}${q}${target}${q}${post}`;
+    });
+    out = out.replace(reqRe, (_m, pre, q, post) => {
+      n++;
+      return lib === "aos" ? `${pre}${q}${target}${q}${post}` : `${pre}${q}${target}${q}${post}.default`;
+    });
+    if (n) changes.push(`${LABEL[lib]}: ${n} import${n === 1 ? "" : "s"} \u2192 ${target}`);
+  }
+  return out;
+}
+function dropAosCssImports(src, changes) {
+  let n = 0;
+  const out = src.replace(/^[ \t]*import\s+(['"])aos\/dist\/aos(?:\.min)?\.css\1;?[ \t]*\r?\n?/gm, () => {
+    n++;
+    return "";
+  }).replace(/^[ \t]*require\s*\(\s*(['"])aos\/dist\/aos(?:\.min)?\.css\1\s*\);?[ \t]*\r?\n?/gm, () => {
+    n++;
+    return "";
+  });
+  if (n) changes.push(`AOS: removed ${n} aos.css import${n === 1 ? "" : "s"} (the drop-in ships its styles)`);
+  return out;
+}
+var SCRIPT_URL = {
+  aos: /^(?:https?:)?\/\/(?:unpkg\.com\/aos(?:@[^/]+)?(?:\/dist\/aos(?:\.min)?\.js)?|cdn\.jsdelivr\.net\/npm\/aos(?:@[^/]+)?(?:\/dist\/aos(?:\.min)?\.js)?|cdnjs\.cloudflare\.com\/ajax\/libs\/aos\/[^/]+\/aos(?:\.min)?\.js)$|(?:^|\/)node_modules\/aos\/dist\/aos(?:\.min)?\.js$/,
+  scrollreveal: /^(?:https?:)?\/\/(?:unpkg\.com\/scrollreveal(?:@[^/]+)?(?:\/dist\/scrollreveal(?:\.min)?\.js)?|cdn\.jsdelivr\.net\/npm\/scrollreveal(?:@[^/]+)?(?:\/dist\/scrollreveal(?:\.min)?\.js)?|cdnjs\.cloudflare\.com\/ajax\/libs\/scrollReveal\.js\/[^/]+\/scrollreveal(?:\.min)?\.js)$|(?:^|\/)node_modules\/scrollreveal\/dist\/scrollreveal(?:\.min)?\.js$/i,
+  vivus: /^(?:https?:)?\/\/(?:unpkg\.com\/vivus(?:@[^/]+)?(?:\/dist\/vivus(?:\.min)?\.js)?|cdn\.jsdelivr\.net\/npm\/vivus(?:@[^/]+)?(?:\/dist\/vivus(?:\.min)?\.js)?|cdnjs\.cloudflare\.com\/ajax\/libs\/vivus\/[^/]+\/vivus(?:\.min)?\.js)$|(?:^|\/)node_modules\/vivus\/dist\/vivus(?:\.min)?\.js$/
+};
+var AOS_CSS_URL = /^(?:https?:)?\/\/(?:unpkg\.com\/aos(?:@[^/]+)?\/dist\/aos\.css|cdn\.jsdelivr\.net\/npm\/aos(?:@[^/]+)?\/dist\/aos\.css|cdnjs\.cloudflare\.com\/ajax\/libs\/aos\/[^/]+\/aos(?:\.min)?\.css)$|(?:^|\/)node_modules\/aos\/dist\/aos\.css$/;
+function rewriteScriptTags(src, version, changes) {
+  return src.replace(/<script\b([^>]*)>/gi, (tag, attrs) => {
+    const m = /\bsrc\s*=\s*(["'])([^"']+)\1/i.exec(attrs);
+    if (!m) return tag;
+    const lib = LIBS.find((l) => SCRIPT_URL[l].test(m[2]));
+    if (!lib) return tag;
+    const url = `https://unpkg.com/svg-scroll-draw@${version}/dist/cdn/${lib}.global.js`;
+    const hadIntegrity = /\bintegrity\s*=/i.test(attrs);
+    const next = attrs.replace(m[0], `src=${m[1]}${url}${m[1]}`).replace(/\s+integrity\s*=\s*(["'])[^"']*\1/gi, "");
+    changes.push(`${LABEL[lib]}: <script> \u2192 ${url}${hadIntegrity ? " (old integrity hash removed)" : ""}`);
+    return `<script${next}>`;
+  });
+}
+function dropAosCssLinks(src, changes) {
+  let n = 0;
+  const out = src.replace(/^[ \t]*<link\b[^>]*>[ \t]*\r?\n?/gim, (line) => {
+    const m = /\bhref\s*=\s*(["'])([^"']+)\1/i.exec(line);
+    if (m && AOS_CSS_URL.test(m[2])) {
+      n++;
+      return "";
+    }
+    return line;
+  });
+  if (n) changes.push(`AOS: removed ${n} aos.css <link> (the drop-in ships its styles)`);
+  return out;
+}
+function dropAosCssAtImports(src, changes) {
+  let n = 0;
+  const out = src.replace(
+    /^[ \t]*@import\s+(?:url\(\s*)?(['"]?)~?aos\/dist\/aos(?:\.min)?\.css\1\s*\)?\s*;?[ \t]*\r?\n?/gm,
+    () => {
+      n++;
+      return "";
+    }
+  );
+  if (n) changes.push(`AOS: removed ${n} @import of aos.css (the drop-in ships its styles)`);
+  return out;
+}
+var SCRIPT_EXT = /\.(?:[cm]?[jt]sx?|vue|svelte|astro)$/i;
+var HTML_EXT = /\.(?:html?|vue|svelte|astro|php|ejs|hbs|njk|liquid|erb)$/i;
+var CSS_EXT = /\.(?:css|scss|sass|less)$/i;
+function migrateSource(src, filename, version) {
+  const changes = [];
+  let code = src;
+  if (SCRIPT_EXT.test(filename)) {
+    code = dropAosCssImports(code, changes);
+    code = rewriteSpecifiers(code, changes);
+  }
+  if (HTML_EXT.test(filename)) {
+    code = rewriteScriptTags(code, version, changes);
+    code = dropAosCssLinks(code, changes);
+  }
+  if (CSS_EXT.test(filename) || /\.(?:vue|svelte|astro)$/i.test(filename)) {
+    code = dropAosCssAtImports(code, changes);
+  }
+  return { code, changes };
+}
+function migratePackageJson(text, version) {
+  const changes = [];
+  let pkg;
+  try {
+    pkg = JSON.parse(text);
+  } catch {
+    return { code: text, changes };
+  }
+  const remove = [...LIBS, "@types/aos"];
+  let home = null;
+  for (const field of ["dependencies", "devDependencies"]) {
+    const deps = pkg[field];
+    if (!deps) continue;
+    for (const name of remove) {
+      if (name in deps) {
+        delete deps[name];
+        changes.push(`package.json: removed ${name} from ${field}`);
+        if (!home && name !== "@types/aos") home = field;
+      }
+    }
+  }
+  if (!home) return { code: text, changes };
+  const already = ["dependencies", "devDependencies"].some(
+    (f) => pkg[f]?.["svg-scroll-draw"]
+  );
+  if (!already) {
+    const deps = pkg[home] ?? (pkg[home] = {});
+    deps["svg-scroll-draw"] = `^${version}`;
+    pkg[home] = Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a.localeCompare(b)));
+    changes.push(`package.json: added svg-scroll-draw ^${version} to ${home}`);
+  }
+  const indent = /^\{\r?\n(\t| +)/.exec(text)?.[1] ?? "  ";
+  return { code: JSON.stringify(pkg, null, indent) + (text.endsWith("\n") ? "\n" : ""), changes };
+}
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  ".next",
+  ".nuxt",
+  ".output",
+  ".svelte-kit",
+  ".vercel",
+  ".netlify",
+  ".turbo",
+  ".cache",
+  "coverage",
+  ".parcel-cache",
+  "vendor"
+]);
+var MAX_BYTES = 2 * 1024 * 1024;
+function* walk(dir) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) yield* walk(path.join(dir, entry.name));
+    } else if (entry.isFile()) {
+      yield path.join(dir, entry.name);
+    }
+  }
+}
+function installCommand(dir) {
+  if (fs.existsSync(path.join(dir, "pnpm-lock.yaml"))) return "pnpm install";
+  if (fs.existsSync(path.join(dir, "yarn.lock"))) return "yarn install";
+  if (fs.existsSync(path.join(dir, "bun.lockb")) || fs.existsSync(path.join(dir, "bun.lock"))) return "bun install";
+  return "npm install";
+}
+function gitDirty(dir) {
+  try {
+    return (0, import_node_child_process.execSync)("git status --porcelain", { cwd: dir, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() !== "";
+  } catch {
+    return false;
+  }
+}
+var HELP = `
+  svg-scroll-draw migrate [dir] [--dry-run] [--force]
+
+  Moves a project off AOS, ScrollReveal and vivus onto svg-scroll-draw's drop-ins:
+    \u2022 imports / requires of 'aos', 'scrollreveal', 'vivus' \u2192 svg-scroll-draw/<lib>
+    \u2022 CDN <script> tags \u2192 svg-scroll-draw's script-tag builds
+    \u2022 AOS's aos.css imports, <link>s and @imports removed (the drop-in ships its styles)
+    \u2022 package.json: the old packages swapped for svg-scroll-draw
+
+  --dry-run   show what would change, write nothing
+  --force     write even if the git working tree has uncommitted changes
+`;
+function runMigrate(args, version, log = console.log) {
+  if (args.includes("--help") || args.includes("-h")) {
+    log(HELP);
+    return 0;
+  }
+  const dryRun = args.includes("--dry-run");
+  const force = args.includes("--force");
+  const dir = path.resolve(args.find((a) => !a.startsWith("-")) ?? ".");
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    log(`  \u2717 Not a directory: ${dir}`);
+    return 1;
+  }
+  const edits = [];
+  for (const file of walk(dir)) {
+    const base = path.basename(file);
+    const isPkg = base === "package.json";
+    if (!isPkg && !SCRIPT_EXT.test(base) && !HTML_EXT.test(base) && !CSS_EXT.test(base)) continue;
+    if (fs.statSync(file).size > MAX_BYTES) continue;
+    const text = fs.readFileSync(file, "utf8");
+    if (!isPkg && !/aos|scrollreveal|vivus/i.test(text)) continue;
+    const result = isPkg ? migratePackageJson(text, version) : migrateSource(text, base, version);
+    if (result.changes.length && result.code !== text) edits.push({ file, code: result.code, changes: result.changes });
+  }
+  log(`
+  svg-scroll-draw migrate${dryRun ? " (dry run)" : ""} \u2014 ${dir}
+`);
+  if (!edits.length) {
+    log("  No AOS, ScrollReveal or vivus usage found. Nothing to do.\n");
+    return 0;
+  }
+  for (const { file, changes } of edits) {
+    log(`  ${path.relative(dir, file) || path.basename(file)}`);
+    for (const c of changes) log(`    \u2022 ${c}`);
+  }
+  if (dryRun) {
+    log(`
+  ${edits.length} file${edits.length === 1 ? "" : "s"} would change. Run again without --dry-run to apply.
+`);
+    return 0;
+  }
+  if (!force && gitDirty(dir)) {
+    log("\n  \u2717 The git working tree has uncommitted changes. Commit or stash them first so the");
+    log("    migration is a clean diff you can review, or pass --force to write anyway.\n");
+    return 1;
+  }
+  for (const { file, code } of edits) fs.writeFileSync(file, code);
+  const touchedPkg = edits.some((e) => path.basename(e.file) === "package.json");
+  log(`
+  \u2713 Updated ${edits.length} file${edits.length === 1 ? "" : "s"}.`);
+  log(`  Next: ${touchedPkg ? `run \`${installCommand(dir)}\`, then ` : ""}review the diff (git diff) and try the page.
+`);
+  return 0;
+}
+
 // src/cli/init.ts
 var RESET = "\x1B[0m";
 var BOLD = "\x1B[1m";
@@ -147,19 +395,19 @@ var GREEN = "\x1B[32m";
 var CYAN = "\x1B[36m";
 function ask(rl, question, fallback) {
   return new Promise(
-    (resolve) => rl.question(`  ${CYAN}?${RESET} ${question} ${DIM}(${fallback})${RESET} `, (ans) => {
-      resolve(ans.trim() || fallback);
+    (resolve2) => rl.question(`  ${CYAN}?${RESET} ${question} ${DIM}(${fallback})${RESET} `, (ans) => {
+      resolve2(ans.trim() || fallback);
     })
   );
 }
 function pick(rl, question, options, fallback) {
   const opts = options.map((o, i) => `${DIM}${i + 1})${RESET} ${o}`).join("  ");
   return new Promise(
-    (resolve) => rl.question(`  ${CYAN}?${RESET} ${question}
+    (resolve2) => rl.question(`  ${CYAN}?${RESET} ${question}
      ${opts}
      ${DIM}(${fallback})${RESET} `, (ans) => {
       const idx = parseInt(ans) - 1;
-      resolve(idx >= 0 && idx < options.length ? options[idx] : fallback);
+      resolve2(idx >= 0 && idx < options.length ? options[idx] : fallback);
     })
   );
 }
@@ -179,8 +427,8 @@ async function main() {
     }
     const selector = needsSelector(framework) ? await ask(rl, "CSS selector for your SVG container?", "#my-svg") : "#my-svg";
     const outFile = FILE_NAMES[framework] ?? "scroll-draw.js";
-    const outPath = path.join(process.cwd(), outFile);
-    if (fs.existsSync(outPath)) {
+    const outPath = path2.join(process.cwd(), outFile);
+    if (fs2.existsSync(outPath)) {
       const overwrite = await ask(rl, `${outFile} already exists. Overwrite?`, "y");
       if (overwrite.toLowerCase() !== "y") {
         console.log(`
@@ -190,7 +438,7 @@ async function main() {
       }
     }
     const code = GENERATORS[framework]?.({ selector, easing, preset }) ?? "";
-    fs.writeFileSync(outPath, code, "utf8");
+    fs2.writeFileSync(outPath, code, "utf8");
     console.log(`
  ${GREEN}\u2713${RESET} ${BOLD}${outFile}${RESET} created.
 `);
@@ -208,7 +456,30 @@ async function main() {
     rl.close();
   }
 }
-main().catch((e) => {
-  console.error(e);
-  process.exit(1);
-});
+function ownVersion() {
+  try {
+    return JSON.parse(fs2.readFileSync(path2.join(__dirname, "..", "..", "package.json"), "utf8")).version;
+  } catch {
+    return "latest";
+  }
+}
+var USAGE = `
+  npx svg-scroll-draw init       scaffold a starter file
+  npx svg-scroll-draw migrate    switch a project from AOS, ScrollReveal or vivus (--dry-run to preview)
+`;
+var [command, ...rest] = process.argv.slice(2);
+if (command === "help" || command === "--help" || command === "-h") {
+  console.log(USAGE);
+} else if (command === "migrate") {
+  process.exitCode = runMigrate(rest, ownVersion());
+} else if (command === void 0 || command === "init") {
+  main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+} else {
+  console.error(`
+  Unknown command "${command}".
+${USAGE}`);
+  process.exitCode = 1;
+}

package/dist/devtools/index.d.mts

@@ -0,0 +1,12 @@
+declare function enable(): void;
+declare function disable(): void;
+declare function toggle(): void;
+declare function highlight(target: string | Element): void;
+declare const devtools: {
+    enable: typeof enable;
+    disable: typeof disable;
+    toggle: typeof toggle;
+    highlight: typeof highlight;
+};
+
+export { devtools };

package/dist/devtools/index.d.ts

@@ -0,0 +1,12 @@
+declare function enable(): void;
+declare function disable(): void;
+declare function toggle(): void;
+declare function highlight(target: string | Element): void;
+declare const devtools: {
+    enable: typeof enable;
+    disable: typeof disable;
+    toggle: typeof toggle;
+    highlight: typeof highlight;
+};
+
+export { devtools };

package/dist/text/index.d.mts

@@ -0,0 +1,52 @@
+type EasingName = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring' | 'bounce' | 'elastic';
+interface TriggerConfig {
+    start?: string;
+    end?: string;
+}
+interface ScrollDrawInstance {
+    destroy: () => void;
+    /** Reset and replay the animation from the beginning. */
+    replay: () => void;
+    /** Pause the animation at the current progress. */
+    pause: () => void;
+    /** Resume a paused animation. */
+    resume: () => void;
+    /** Jump to a specific progress value (0–1) and pause. */
+    seek: (progress: number) => void;
+    /** Returns current draw progress (0–1). */
+    getProgress: () => number;
+    /**
+     * Re-measure after a layout change: path lengths, and the scroll trigger window.
+     *
+     * The engine already re-measures on `resize`, on `orientationchange`, and via a
+     * `ResizeObserver` on the document element — but none of those fire for a layout
+     * change that leaves the document height alone, such as a tab switching, a
+     * sibling collapsing, or a font swapping inside a fixed-height box. Call this
+     * after one of those.
+     *
+     * Optional on this shared type because several instances here are fan-outs over
+     * other instances or SSR no-op stubs. `scrollDraw`, `scrollPin`,
+     * `scrollHorizontal`, `scrollDrawTimeline` and the group APIs all provide it;
+     * use `instance.refresh?.()` if you hold an instance of unknown origin.
+     */
+    refresh?: () => void;
+}
+
+interface ScrollTextOptions {
+    split?: 'chars' | 'words' | 'lines';
+    stagger?: number;
+    easing?: EasingName | ((t: number) => number);
+    from?: {
+        opacity?: number;
+        y?: number;
+        x?: number;
+        rotate?: number;
+        scale?: number;
+    };
+    trigger?: TriggerConfig;
+    once?: boolean;
+    onComplete?: () => void;
+}
+declare function scrollText(target: string | Element, options?: ScrollTextOptions): ScrollDrawInstance;
+
+export { type ScrollTextOptions, scrollText };

package/dist/text/index.d.ts

@@ -0,0 +1,52 @@
+type EasingName = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring' | 'bounce' | 'elastic';
+interface TriggerConfig {
+    start?: string;
+    end?: string;
+}
+interface ScrollDrawInstance {
+    destroy: () => void;
+    /** Reset and replay the animation from the beginning. */
+    replay: () => void;
+    /** Pause the animation at the current progress. */
+    pause: () => void;
+    /** Resume a paused animation. */
+    resume: () => void;
+    /** Jump to a specific progress value (0–1) and pause. */
+    seek: (progress: number) => void;
+    /** Returns current draw progress (0–1). */
+    getProgress: () => number;
+    /**
+     * Re-measure after a layout change: path lengths, and the scroll trigger window.
+     *
+     * The engine already re-measures on `resize`, on `orientationchange`, and via a
+     * `ResizeObserver` on the document element — but none of those fire for a layout
+     * change that leaves the document height alone, such as a tab switching, a
+     * sibling collapsing, or a font swapping inside a fixed-height box. Call this
+     * after one of those.
+     *
+     * Optional on this shared type because several instances here are fan-outs over
+     * other instances or SSR no-op stubs. `scrollDraw`, `scrollPin`,
+     * `scrollHorizontal`, `scrollDrawTimeline` and the group APIs all provide it;
+     * use `instance.refresh?.()` if you hold an instance of unknown origin.
+     */
+    refresh?: () => void;
+}
+
+interface ScrollTextOptions {
+    split?: 'chars' | 'words' | 'lines';
+    stagger?: number;
+    easing?: EasingName | ((t: number) => number);
+    from?: {
+        opacity?: number;
+        y?: number;
+        x?: number;
+        rotate?: number;
+        scale?: number;
+    };
+    trigger?: TriggerConfig;
+    once?: boolean;
+    onComplete?: () => void;
+}
+declare function scrollText(target: string | Element, options?: ScrollTextOptions): ScrollDrawInstance;
+
+export { type ScrollTextOptions, scrollText };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svg-scroll-draw",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Scroll-driven animation for the web — draw SVG paths, reveal elements, pin sections, scrub video. Zero dependencies, native CSS fast path, works with React, Vue, Svelte, Solid, Angular, Astro and vanilla JS",
   "keywords": [
     "svg",