astro-magic-move 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Cable
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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/index.ts

@@ -0,0 +1,2 @@
+export { default as MagicMove } from "./src/MagicMove.astro";
+export type { MagicMoveProps } from "./src/types";

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "astro-magic-move",
+  "version": "0.1.0",
+  "description": "Animated code morphing for Astro, powered by Shiki Magic Move. Build-time tokenization, zero-framework client JS, CSS-variable theming.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jacob Cable",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cabljac/astro-magic-move"
+  },
+  "homepage": "https://astro-magic-move.dev",
+  "exports": {
+    ".": "./index.ts",
+    "./styles": "./styles/magic-move.css"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "styles/",
+    "LICENSE"
+  ],
+  "keywords": [
+    "astro-component",
+    "withastro",
+    "shiki",
+    "code-animation",
+    "magic-move"
+  ],
+  "peerDependencies": {
+    "astro": "^5.0.0 || ^6.0.0"
+  },
+  "dependencies": {
+    "shiki": "^3.0.0",
+    "shiki-magic-move": "^1.3.0"
+  }
+}

package/src/MagicMove.astro

@@ -0,0 +1,184 @@
+---
+import type { MagicMoveProps } from "./types";
+import { cssVarTheme } from "./theme";
+import { createHighlighter, type HighlighterGeneric } from "shiki";
+import { codeToKeyedTokens, createMagicMoveMachine } from "shiki-magic-move/core";
+
+interface Props extends MagicMoveProps {}
+
+const {
+	before,
+	after,
+	steps: stepsProp,
+	lang = "typescript",
+	trigger = "scroll",
+	duration = 800,
+	stagger = 0.3,
+	threshold = 0.4,
+	lineNumbers = false,
+	class: className,
+} = Astro.props;
+
+// Resolve steps from props
+let steps: string[];
+if (stepsProp) {
+	if (stepsProp.length < 2) {
+		throw new Error("[astro-magic-move] `steps` must contain at least 2 items.");
+	}
+	steps = stepsProp;
+} else if (before != null && after != null) {
+	steps = [before, after];
+} else {
+	throw new Error(
+		"[astro-magic-move] Provide either `before` + `after` or `steps` (min 2 items).",
+	);
+}
+
+// Module-level highlighter cache (survives HMR via globalThis)
+const CACHE_KEY = "__astro_magic_move_hl";
+type HLCache = Map<string, HighlighterGeneric<string, string>>;
+const hlCache: HLCache = ((globalThis as Record<string, unknown>)[CACHE_KEY] ??= new Map()) as HLCache;
+
+let highlighter = hlCache.get(lang);
+if (!highlighter) {
+	highlighter = await createHighlighter({
+		themes: [cssVarTheme],
+		langs: [lang],
+	});
+	hlCache.set(lang, highlighter);
+}
+
+// Build the magic move machine and compile all steps at build time
+const machine = createMagicMoveMachine(
+	(code) =>
+		codeToKeyedTokens(highlighter, code, { lang, theme: "css-variables" }, lineNumbers),
+	{},
+);
+
+const compiledSteps = steps.map((code) => machine.commit(code).current);
+
+const stepsJson = JSON.stringify(compiledSteps);
+---
+
+<magic-move
+	class:list={["magic-move", className]}
+	data-trigger={trigger}
+	data-duration={duration}
+	data-stagger={stagger}
+	data-threshold={threshold}
+	data-lang={lang}
+	{...(lineNumbers ? { "data-line-numbers": "" } : {})}
+>
+	<pre class="shiki-magic-move-container"><code>{steps[0]}</code></pre>
+	<script is:inline type="application/json" set:html={stepsJson} />
+</magic-move>
+
+<script>
+	import { MagicMoveRenderer } from "shiki-magic-move/renderer";
+
+	class MagicMoveElement extends HTMLElement {
+		private renderer: MagicMoveRenderer | null = null;
+		private steps: any[] = [];
+		private currentStep = 0;
+		private observer: IntersectionObserver | null = null;
+
+		connectedCallback() {
+			const dataScript = this.querySelector('script[type="application/json"]');
+			if (!dataScript?.textContent) return;
+			this.steps = JSON.parse(dataScript.textContent);
+			dataScript.remove();
+
+			const container = this.querySelector("pre");
+			if (!container) return;
+			container.innerHTML = "";
+
+			const duration = Number(this.dataset.duration ?? 800);
+			const stagger = Number(this.dataset.stagger ?? 0.3);
+			const threshold = Number(this.dataset.threshold ?? 0.4);
+			const trigger = this.dataset.trigger ?? "scroll";
+			const lineNumbers = this.hasAttribute("data-line-numbers");
+
+			this.renderer = new MagicMoveRenderer(container, {
+				duration,
+				stagger,
+				lineNumbers,
+				animateContainer: true,
+			});
+
+			// replace() for instant initial display (no animation, no empty frame)
+			this.renderer.replace(this.steps[0]);
+			this.currentStep = 0;
+			this.setupTrigger(trigger, threshold);
+		}
+
+		disconnectedCallback() {
+			this.observer?.disconnect();
+		}
+
+		private setupTrigger(trigger: string, threshold: number) {
+			switch (trigger) {
+				case "scroll":
+					this.setupScrollTrigger(threshold);
+					break;
+				case "click":
+					this.style.cursor = "pointer";
+					this.addEventListener("click", () => {
+						const next = (this.currentStep + 1) % this.steps.length;
+						this.animateToStep(next);
+					});
+					break;
+				case "auto":
+					requestAnimationFrame(() => {
+						this.animateToStep(1);
+					});
+					break;
+			}
+		}
+
+		private setupScrollTrigger(threshold: number) {
+			this.observer = new IntersectionObserver(
+				([entry]) => {
+					if (entry.isIntersecting) {
+						this.animateToStep(1);
+						this.observer?.disconnect();
+					}
+				},
+				{ threshold },
+			);
+			this.observer.observe(this);
+		}
+
+		private async animateToStep(stepIndex: number) {
+			if (!this.renderer || stepIndex === this.currentStep) return;
+			if (stepIndex < 0 || stepIndex >= this.steps.length) return;
+
+			await this.renderer.render(this.steps[stepIndex]);
+			this.currentStep = stepIndex;
+
+			this.dispatchEvent(
+				new CustomEvent("magic-move:step", {
+					detail: { step: stepIndex, total: this.steps.length },
+					bubbles: true,
+				}),
+			);
+		}
+	}
+
+	if (!customElements.get("magic-move")) {
+		customElements.define("magic-move", MagicMoveElement);
+	}
+</script>
+
+<style is:global>
+	magic-move {
+		display: block;
+		position: relative;
+	}
+
+	magic-move .shiki-magic-move-container {
+		margin: 0;
+		overflow-x: auto;
+		overflow-y: hidden;
+		scrollbar-width: thin;
+	}
+</style>

package/src/theme.ts

@@ -0,0 +1,25 @@
+import { createCssVariablesTheme } from "shiki/core";
+
+/**
+ * A shared CSS-variables theme. Colors are driven by `--shiki-*` custom
+ * properties. Sensible defaults are provided so the component looks good
+ * out of the box — consumers override as many or as few as they want.
+ */
+export const cssVarTheme = createCssVariablesTheme({
+	name: "css-variables",
+	variablePrefix: "--shiki-",
+	variableDefaults: {
+		foreground: "#d4d4d4",
+		background: "#1e1e1e",
+		"token-keyword": "#c586c0",
+		"token-string": "#ce9178",
+		"token-function": "#dcdcaa",
+		"token-comment": "#6a9955",
+		"token-constant": "#4fc1ff",
+		"token-parameter": "#9cdcfe",
+		"token-punctuation": "#d4d4d4",
+		"token-string-expression": "#ce9178",
+		"token-link": "#4fc1ff",
+	},
+	fontStyle: true,
+});

package/src/types.ts

@@ -0,0 +1,46 @@
+export interface MagicMoveProps {
+	/** Code for the initial state. Shorthand for two-step usage. */
+	before?: string;
+
+	/** Code for the final state. Shorthand for two-step usage. */
+	after?: string;
+
+	/**
+	 * Array of code strings for multi-step morphing.
+	 * Takes precedence over before/after if provided.
+	 * Must contain at least 2 items.
+	 */
+	steps?: string[];
+
+	/** Language for syntax highlighting. Default: `'typescript'` */
+	lang?: string;
+
+	/**
+	 * How the animation is triggered:
+	 * - `'scroll'`: animate when element enters viewport (default)
+	 * - `'click'`: toggle forward on click, wraps around
+	 * - `'auto'`: animate immediately when the element mounts
+	 */
+	trigger?: "scroll" | "click" | "auto";
+
+	/** Animation duration in ms. Default: `800` */
+	duration?: number;
+
+	/** Stagger delay for token entrance. Default: `0.3` */
+	stagger?: number;
+
+	/**
+	 * IntersectionObserver threshold (0–1). Only used when trigger='scroll'.
+	 * Default: `0.4`
+	 */
+	threshold?: number;
+
+	/** Whether to animate line numbers. Default: `false` */
+	lineNumbers?: boolean;
+
+	/**
+	 * CSS class(es) applied to the outer `<magic-move>` element.
+	 * Use this for all visual styling (bg, border, rounded, shadow, padding, width, etc).
+	 */
+	class?: string;
+}

package/styles/magic-move.css

@@ -0,0 +1,23 @@
+/* Core transition CSS from shiki-magic-move */
+@import "shiki-magic-move/style.css";
+
+/* Structural defaults — consumers can override via class prop */
+magic-move {
+	display: block;
+	position: relative;
+}
+
+.shiki-magic-move-container {
+	margin: 0;
+	overflow-x: auto;
+	overflow-y: hidden;
+	padding: 1rem 1.25rem;
+	font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+		"Liberation Mono", "Courier New", monospace;
+	font-size: 0.875rem;
+	line-height: 1.7;
+	text-align: left;
+	background: var(--shiki-background, #1e1e1e);
+	color: var(--shiki-foreground, #d4d4d4);
+	scrollbar-width: thin;
+}