@markdy/astro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hoang Yell (https://hoangyell.com)
+
+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/README.md

@@ -0,0 +1,77 @@
+# @markdy/astro
+
+[Astro](https://astro.build/) island component for [MarkdyScript](../../docs/SYNTAX.md) animated scenes.
+
+## Features
+
+- **SSR placeholder** — correctly-sized `<div>` prevents layout shift before hydration
+- **Viewport-triggered hydration** — `IntersectionObserver` with 100px root margin
+- **View Transition compatible** — re-observes elements on `astro:page-load`
+- **Zero config** — pass your MarkdyScript code as a prop
+
+## Installation
+
+```sh
+pnpm add @markdy/astro
+```
+
+## Usage
+
+```astro
+---
+import { Markdy } from "@markdy/astro";
+
+const code = `
+  scene width=800 height=400 bg=#fff5f9
+  actor hero = figure(#c68642, m, 😎) at (400, 200)
+  @0.0: hero.enter(from=left, dur=0.8)
+  @1.5: hero.say("Hello!", dur=1.2)
+`;
+---
+
+<Markdy code={code} width={800} height={400} bg="#fff5f9" autoplay />
+```
+
+### In MDX
+
+```mdx
+import { Markdy } from "@markdy/astro";
+
+export const code = `
+  scene width=600 height=300 bg=white
+  actor label = text("Hello") at (200, 130) size 40 opacity 0
+  @0.3: label.fade_in(dur=0.6)
+`;
+
+<Markdy code={code} width={600} height={300} autoplay />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `code` | `string` | *(required)* | MarkdyScript source code |
+| `width` | `number` | `800` | Placeholder width in pixels |
+| `height` | `number` | `400` | Placeholder height in pixels |
+| `bg` | `string` | `"white"` | Placeholder background colour |
+| `assets` | `Record<string, string>` | `{}` | Asset URL overrides |
+| `autoplay` | `boolean` | `true` | Start playing on hydration |
+| `class` | `string` | — | CSS class for the outer wrapper |
+
+> **Tip:** Match `width`, `height`, and `bg` props to your `scene` declaration values to avoid a visual flash on hydration.
+
+## How It Works
+
+1. **Server:** renders a sized placeholder `<div>` with a `▶ markdy` label
+2. **Client:** an `IntersectionObserver` watches all `.markdy-root` elements
+3. **On viewport entry:** the observer fires, clears the placeholder, and calls `createPlayer()` from `@markdy/renderer-dom`
+4. **View Transitions:** listens for `astro:page-load` to re-observe newly added elements
+
+## Documentation
+
+- **[Tutorial](../../docs/TUTORIAL.md)** — step-by-step guide from zero to animated scenes
+- **[Syntax Reference](../../docs/SYNTAX.md)** — complete DSL language spec
+
+## License
+
+[MIT](../../LICENSE)

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@markdy/astro",
+  "version": "0.1.0",
+  "description": "Astro island component for MarkdyScript animations.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "keywords": [
+    "markdy",
+    "astro",
+    "animation",
+    "island",
+    "component"
+  ],
+  "author": "Hoang Yell <hoangyell@gmail.com> (https://hoangyell.com)",
+  "homepage": "https://markdy.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HoangYell/markdy-com.git",
+    "directory": "packages/astro"
+  },
+  "bugs": {
+    "url": "https://github.com/HoangYell/markdy-com/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@markdy/renderer-dom": "0.1.0"
+  },
+  "peerDependencies": {
+    "astro": ">=4.0.0"
+  },
+  "devDependencies": {
+    "astro": "^5.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/Markdy.astro

@@ -0,0 +1,134 @@
+---
+/**
+ * @markdy/astro — <Markdy /> island component
+ *
+ * SSR: renders a correctly-sized placeholder div so layout is stable.
+ * Client: hydrates via IntersectionObserver when the element enters the
+ *         viewport (equivalent to client:visible behaviour).
+ */
+
+export interface Props {
+  /** MarkdyScript source code. */
+  code: string;
+  /**
+   * Placeholder width in pixels (should match the `width` in the scene
+   * declaration). Used only for the SSR placeholder — the renderer reads
+   * the actual value from the parsed AST.
+   */
+  width?: number;
+  /** Placeholder height in pixels. */
+  height?: number;
+  /**
+   * Placeholder background colour. Pass the same value as `bg` in the
+   * scene declaration so there is no flash on hydration.
+   */
+  bg?: string;
+  /**
+   * Asset URL overrides.  Keys are the asset names used in the DSL.
+   * Values are the URLs the renderer should use instead of the parsed path.
+   * Useful for CDN assets or data URIs in demos.
+   */
+  assets?: Record<string, string>;
+  /** Start playing as soon as the scene is hydrated. Defaults to true. */
+  autoplay?: boolean;
+  class?: string;
+}
+
+const {
+  code,
+  width = 800,
+  height = 400,
+  bg = "white",
+  assets = {},
+  autoplay = true,
+  class: className,
+} = Astro.props;
+---
+
+<div
+  class:list={["markdy-root", className]}
+  data-markdy-code={code}
+  data-markdy-assets={JSON.stringify(assets)}
+  data-markdy-autoplay={String(autoplay)}
+  style={`width:${width}px;height:${height}px;overflow:hidden`}
+>
+  <!--
+    SSR placeholder: keeps layout stable before the island hydrates.
+    Background matches the scene bg prop to avoid a visible flash.
+  -->
+  <div
+    class="markdy-placeholder"
+    aria-label="Markdy animation loading"
+    style={`width:${width}px;height:${height}px;background:${bg};display:flex;align-items:center;justify-content:center`}
+  >
+    <span
+      style="font-family:sans-serif;font-size:12px;color:#bbb;letter-spacing:0.05em"
+      aria-hidden="true"
+    >
+      ▶ markdy
+    </span>
+  </div>
+</div>
+
+<script>
+  import { createPlayer } from "@markdy/renderer-dom";
+
+  function hydrate(el: HTMLElement): void {
+    const code = el.dataset.markdyCode;
+    if (!code) return;
+
+    let assets: Record<string, string> = {};
+    try {
+      assets = JSON.parse(el.dataset.markdyAssets ?? "{}") as Record<
+        string,
+        string
+      >;
+    } catch {
+      // Leave assets empty on parse failure — renderer falls back to DSL paths.
+    }
+
+    const autoplay = el.dataset.markdyAutoplay !== "false";
+
+    // Clear the SSR placeholder before mounting the canvas.
+    el.innerHTML = "";
+    el.style.overflow = "visible";
+
+    createPlayer({ container: el, code, assets, autoplay });
+  }
+
+  // Observe every unhydrated .markdy-root element and hydrate it when it
+  // enters the viewport (100 px root margin so the scene is ready before
+  // the user actually sees it).
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          const el = entry.target as HTMLElement;
+          observer.unobserve(el);
+          hydrate(el);
+        }
+      }
+    },
+    { rootMargin: "100px" },
+  );
+
+  function initAll(): void {
+    document
+      .querySelectorAll<HTMLElement>(".markdy-root:not([data-markdy-init])")
+      .forEach((el) => {
+        // Flag the element to prevent double-registration across re-runs.
+        el.dataset.markdyInit = "pending";
+        observer.observe(el);
+      });
+  }
+
+  // Initial page load.
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initAll);
+  } else {
+    initAll();
+  }
+
+  // Re-run after Astro View Transitions / client-side navigation.
+  document.addEventListener("astro:page-load", initAll);
+</script>

package/src/index.ts

@@ -0,0 +1 @@
+export { default as Markdy } from "./Markdy.astro";