@markgrafhq/starlight-markgraf 0.0.42

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Eibes
+
+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,72 @@
+# @markgrafhq/starlight-markgraf
+
+Astro/Starlight integration for embedding [markgraf](https://github.com/markgrafhq) animations.
+
+## Install
+
+```bash
+npm install @markgrafhq/starlight-markgraf @markgrafhq/markgraf-react @astrojs/react react react-dom
+```
+
+## Configure
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import react from "@astrojs/react";
+import starlight from "@astrojs/starlight";
+import markgraf from "@markgrafhq/starlight-markgraf";
+
+export default defineConfig({
+  integrations: [react(), starlight({ title: "Docs" }), markgraf()],
+});
+```
+
+Import the player CSS in a global stylesheet:
+
+```css
+@import "@markgrafhq/starlight-markgraf/css";
+```
+
+## Use
+
+Fenced code blocks with the `markgraf` language render as live players:
+
+````markdown
+```markgraf
+seed 1
+scene v1 {
+  + client: Client
+  + api: API
+  + client -> api
+  client ~> api: GET /user/42
+}
+```
+````
+
+Or use the component directly in MDX/Astro:
+
+```astro
+---
+import Markgraf from "@markgrafhq/starlight-markgraf/Markgraf.astro";
+---
+
+<Markgraf src={`seed 1\nscene v1 { + a: A }`} />
+```
+
+Players include the floating play, scrub, time, and speed controls by default.
+The Astro component accepts `controls={false}` when a page should hide them.
+
+Custom controls belong in a React island so the control function stays in the
+browser rather than crossing Astro's serialization boundary:
+
+```tsx
+import { StarlightMarkgrafPlayer } from "@markgrafhq/starlight-markgraf";
+
+export const Diagram = ({ src }: { src: string }) => (
+  <StarlightMarkgrafPlayer
+    src={src}
+    controls={(api) => <MyDiagramControls api={api} />}
+  />
+);
+```

package/dist/MarkgrafPlayer.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from "react";
+import { type MarkgrafApi } from "@markgrafhq/markgraf-react";
+type Renderer = "canvas" | "svg";
+export type MarkgrafControls = boolean | ((api: MarkgrafApi<Element>) => ReactNode);
+export interface MarkgrafPlayerProps {
+    src: string;
+    renderer?: Renderer;
+    className?: string;
+    /**
+     * Shows the transport bar by default. Pass `false` to hide it, or a render
+     * function to replace it with controls driven by the same player API.
+     */
+    controls?: MarkgrafControls;
+}
+export declare const StarlightMarkgrafPlayer: ({ src, renderer, className, controls, }: MarkgrafPlayerProps) => import("react").JSX.Element;
+export {};

package/dist/MarkgrafPlayer.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { useMarkgraf } from "@markgrafhq/markgraf-react";
+const playIcon = (_jsx("svg", { viewBox: "0 0 15 15", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M3.24 2.05a.5.5 0 0 1 .52.02l8.5 5a.5.5 0 0 1 0 .86l-8.5 5A.5.5 0 0 1 3 12.5v-10a.5.5 0 0 1 .24-.45Z" }) }));
+const pauseIcon = (_jsx("svg", { viewBox: "0 0 15 15", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M3.5 2.5a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 .5.5v10a.5.5 0 0 1-.5.5H4a.5.5 0 0 1-.5-.5v-10Zm5 0A.5.5 0 0 1 9 2h2a.5.5 0 0 1 .5.5v10a.5.5 0 0 1-.5.5H9a.5.5 0 0 1-.5-.5v-10Z" }) }));
+const speedIcon = (_jsx("svg", { className: "markgraf-doc-speed-icon", viewBox: "0 0 15 15", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M3.14 5.64a.5.5 0 0 1 .71 0L7.5 9.29l3.65-3.65a.5.5 0 0 1 .7.71l-4 4a.5.5 0 0 1-.7 0l-4-4a.5.5 0 0 1 0-.71Z" }) }));
+const useDocumentTheme = () => {
+    const [theme, setTheme] = useState("light");
+    useEffect(() => {
+        const root = document.documentElement;
+        const update = () => setTheme(root.dataset.theme === "dark" ? "dark" : "light");
+        update();
+        const observer = new MutationObserver(update);
+        observer.observe(root, {
+            attributes: true,
+            attributeFilter: ["data-theme"],
+        });
+        return () => observer.disconnect();
+    }, []);
+    return theme;
+};
+const formatTime = (seconds) => {
+    const safe = Number.isFinite(seconds) ? Math.max(0, seconds) : 0;
+    const minutes = Math.floor(safe / 60);
+    const remainder = safe - minutes * 60;
+    return `${minutes}:${remainder.toFixed(1).padStart(4, "0")}`;
+};
+const DefaultControls = ({ api, speed, setSpeed, }) => {
+    const duration = Number.isFinite(api.duration)
+        ? Math.max(0, api.duration)
+        : 0;
+    const time = Number.isFinite(api.time)
+        ? Math.max(0, Math.min(api.time, duration))
+        : 0;
+    return (_jsxs("div", { className: "markgraf-doc-controls", "aria-label": "Diagram playback controls", children: [_jsx("button", { className: "markgraf-doc-play", type: "button", "aria-label": api.playing ? "Pause diagram" : "Play diagram", "aria-pressed": api.playing, disabled: !api.ready, onClick: api.toggle, children: api.playing ? pauseIcon : playIcon }), _jsx("input", { className: "markgraf-doc-scrub", type: "range", "aria-label": "Diagram time", min: "0", max: Math.max(duration, 0.001), step: "0.01", value: time, disabled: !api.ready, onChange: (event) => api.seek(event.currentTarget.valueAsNumber) }), _jsxs("output", { className: "markgraf-doc-time", "aria-live": "off", children: [formatTime(time), " / ", formatTime(duration)] }), _jsxs("div", { className: "markgraf-doc-speed-control", children: [_jsxs("select", { className: "markgraf-doc-speed", "aria-label": "Playback speed", value: speed, disabled: !api.ready, onChange: (event) => setSpeed(Number(event.currentTarget.value)), children: [_jsx("option", { value: "0.5", children: "0.5\u00D7" }), _jsx("option", { value: "1", children: "1\u00D7" }), _jsx("option", { value: "1.5", children: "1.5\u00D7" }), _jsx("option", { value: "2", children: "2\u00D7" })] }), speedIcon] })] }));
+};
+const Controls = ({ api, controls, }) => {
+    const [speed, setSpeed] = useState(1);
+    useEffect(() => {
+        if (controls === true && api.ready)
+            api.setSpeed(speed);
+    }, [api.ready, controls, speed]);
+    if (typeof controls === "function")
+        return controls(api);
+    if (!controls)
+        return null;
+    return _jsx(DefaultControls, { api: api, speed: speed, setSpeed: setSpeed });
+};
+const CanvasPlayer = ({ src, theme, className, controls, }) => {
+    const api = useMarkgraf(src, { renderer: "canvas", theme });
+    return (_jsxs("div", { className: `not-content markgraf-doc-player ${className ?? ""}`, "data-markgraf-theme": theme, children: [_jsx("canvas", { className: "markgraf-player markgraf-doc-stage", ref: api.elementRef, onClick: api.toggle, "aria-label": "Animated Markgraf diagram" }), _jsx(Controls, { api: api, controls: controls })] }));
+};
+const SvgPlayer = ({ src, theme, className, controls, }) => {
+    const api = useMarkgraf(src, { renderer: "svg", theme });
+    return (_jsxs("div", { className: `not-content markgraf-doc-player ${className ?? ""}`, "data-markgraf-theme": theme, children: [_jsx("svg", { className: "markgraf-player markgraf-doc-stage", ref: api.elementRef, onClick: api.toggle, "aria-label": "Animated Markgraf diagram" }), _jsx(Controls, { api: api, controls: controls })] }));
+};
+export const StarlightMarkgrafPlayer = ({ src, renderer = "canvas", className, controls = true, }) => {
+    const theme = useDocumentTheme();
+    const props = { src, renderer, className, controls, theme };
+    return renderer === "svg" ? (_jsx(SvgPlayer, { ...props })) : (_jsx(CanvasPlayer, { ...props }));
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { AstroIntegration } from "astro";
+import remarkMarkgraf from "./remark-markgraf.mjs";
+export { remarkMarkgraf };
+export { StarlightMarkgrafPlayer, type MarkgrafControls, type MarkgrafPlayerProps, } from "./MarkgrafPlayer.js";
+export default function markgrafIntegration(): AstroIntegration;

package/dist/index.js

@@ -0,0 +1,17 @@
+import remarkMarkgraf from "./remark-markgraf.mjs";
+export { remarkMarkgraf };
+export { StarlightMarkgrafPlayer, } from "./MarkgrafPlayer.js";
+export default function markgrafIntegration() {
+    return {
+        name: "markgraf-starlight",
+        hooks: {
+            "astro:config:setup": ({ updateConfig }) => {
+                updateConfig({
+                    markdown: {
+                        remarkPlugins: [remarkMarkgraf],
+                    },
+                });
+            },
+        },
+    };
+}

package/dist/markgraf-react.css

@@ -0,0 +1,154 @@
+@import "@markgrafhq/markgraf-react/css";
+
+.markgraf-doc-player {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  min-width: 0;
+  min-height: 11.25rem;
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  border: 1px solid color-mix(in srgb, currentColor 14%, transparent);
+  border-radius: 0.875rem;
+  background: #ffffff;
+  box-shadow: 0 1rem 3rem rgb(0 0 0 / 10%);
+}
+
+.markgraf-doc-player[data-markgraf-theme="dark"] {
+  background: #101827;
+}
+
+.markgraf-doc-stage {
+  display: block;
+  width: 100%;
+  height: 100%;
+  min-height: 11.25rem;
+  cursor: pointer;
+}
+
+.markgraf-doc-controls {
+  position: absolute;
+  z-index: 2;
+  right: 50%;
+  bottom: 0.75rem;
+  display: grid;
+  grid-template-columns: 1.75rem minmax(7rem, 1fr) auto auto;
+  align-items: center;
+  gap: 0.5rem;
+  width: min(35rem, calc(100% - 2rem));
+  padding: 0.375rem 0.5rem;
+  border: 1px solid rgb(255 255 255 / 14%);
+  border-radius: 999px;
+  color: #ffffff;
+  background: rgb(8 13 22 / 58%);
+  box-shadow: 0 0.875rem 2.75rem rgb(0 0 0 / 28%);
+  opacity: 0.78;
+  transform: translateX(50%);
+  transition:
+    opacity 140ms ease,
+    background 140ms ease;
+  backdrop-filter: blur(18px);
+}
+
+.markgraf-doc-player:hover .markgraf-doc-controls,
+.markgraf-doc-controls:focus-within {
+  background: rgb(8 13 22 / 78%);
+  opacity: 0.98;
+}
+
+.markgraf-doc-play {
+  display: grid;
+  width: 1.75rem;
+  height: 1.75rem;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  place-items: center;
+  color: inherit;
+  background: rgb(255 255 255 / 10%);
+  cursor: pointer;
+}
+
+.markgraf-doc-play:hover,
+.markgraf-doc-play:focus-visible {
+  background: rgb(255 255 255 / 20%);
+}
+
+.markgraf-doc-play svg {
+  width: 0.875rem;
+  height: 0.875rem;
+}
+
+.markgraf-doc-scrub {
+  min-width: 0;
+  height: 0.875rem;
+  margin: 0;
+  accent-color: #ffffff;
+  cursor: pointer;
+}
+
+.markgraf-doc-time {
+  color: rgb(255 255 255 / 76%);
+  font-family: var(
+    --sl-font-mono,
+    var(--ifm-font-family-monospace, ui-monospace, monospace)
+  );
+  font-size: 0.625rem;
+  line-height: 1;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+.markgraf-doc-speed-control {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+.markgraf-doc-speed {
+  appearance: none;
+  width: 100%;
+  padding: 0.1875rem 1.375rem 0.1875rem 0.5rem;
+  border: 0;
+  border-radius: 999px;
+  color: #ffffff;
+  background: rgb(255 255 255 / 10%);
+  font-size: 0.625rem;
+  cursor: pointer;
+}
+
+.markgraf-doc-speed-icon {
+  position: absolute;
+  right: 0.4375rem;
+  width: 0.75rem;
+  height: 0.75rem;
+  color: rgb(255 255 255 / 72%);
+  pointer-events: none;
+}
+
+.markgraf-doc-speed option {
+  color: #111827;
+  background: #ffffff;
+}
+
+.markgraf-doc-controls :disabled {
+  cursor: wait;
+  opacity: 0.5;
+}
+
+@media (max-width: 32rem) {
+  .markgraf-doc-controls {
+    grid-template-columns: 1.75rem minmax(5rem, 1fr) auto;
+  }
+
+  .markgraf-doc-time {
+    display: none;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .markgraf-doc-controls {
+    transition: none;
+  }
+}

package/dist/remark-markgraf.js

@@ -0,0 +1,51 @@
+import { visit } from "unist-util-visit";
+
+const importNode = {
+  type: "mdxjsEsm",
+  value: 'import Markgraf from "@markgrafhq/starlight-markgraf/Markgraf.astro";',
+  data: {
+    estree: {
+      type: "Program",
+      sourceType: "module",
+      body: [
+        {
+          type: "ImportDeclaration",
+          specifiers: [
+            {
+              type: "ImportDefaultSpecifier",
+              local: { type: "Identifier", name: "Markgraf" },
+            },
+          ],
+          source: {
+            type: "Literal",
+            value: "@markgrafhq/starlight-markgraf/Markgraf.astro",
+            raw: '"@markgrafhq/starlight-markgraf/Markgraf.astro"',
+          },
+        },
+      ],
+    },
+  },
+};
+
+export default function remarkMarkgraf() {
+  return (tree) => {
+    let needsImport = false;
+
+    visit(tree, "code", (node, index, parent) => {
+      if (node.lang !== "markgraf" || !parent || index == null) return;
+
+      needsImport = true;
+
+      parent.children[index] = {
+        type: "mdxJsxFlowElement",
+        name: "Markgraf",
+        attributes: [
+          { type: "mdxJsxAttribute", name: "src", value: node.value },
+        ],
+        children: [],
+      };
+    });
+
+    if (needsImport) tree.children.unshift(importNode);
+  };
+}

package/dist/remark-markgraf.mjs

@@ -0,0 +1,51 @@
+import { visit } from "unist-util-visit";
+
+const importNode = {
+  type: "mdxjsEsm",
+  value: 'import Markgraf from "@markgrafhq/starlight-markgraf/Markgraf.astro";',
+  data: {
+    estree: {
+      type: "Program",
+      sourceType: "module",
+      body: [
+        {
+          type: "ImportDeclaration",
+          specifiers: [
+            {
+              type: "ImportDefaultSpecifier",
+              local: { type: "Identifier", name: "Markgraf" },
+            },
+          ],
+          source: {
+            type: "Literal",
+            value: "@markgrafhq/starlight-markgraf/Markgraf.astro",
+            raw: '"@markgrafhq/starlight-markgraf/Markgraf.astro"',
+          },
+        },
+      ],
+    },
+  },
+};
+
+export default function remarkMarkgraf() {
+  return (tree) => {
+    let needsImport = false;
+
+    visit(tree, "code", (node, index, parent) => {
+      if (node.lang !== "markgraf" || !parent || index == null) return;
+
+      needsImport = true;
+
+      parent.children[index] = {
+        type: "mdxJsxFlowElement",
+        name: "Markgraf",
+        attributes: [
+          { type: "mdxJsxAttribute", name: "src", value: node.value },
+        ],
+        children: [],
+      };
+    });
+
+    if (needsImport) tree.children.unshift(importNode);
+  };
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@markgrafhq/starlight-markgraf",
+  "version": "0.0.42",
+  "description": "Starlight/Astro integration for embedding markgraf animations. Transforms ```markgraf fenced code blocks into a live player and exposes a <Markgraf src=\"…\" /> component.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./Markgraf.astro": "./src/Markgraf.astro",
+    "./remark": {
+      "default": "./dist/remark-markgraf.js"
+    },
+    "./css": "./dist/markgraf-react.css"
+  },
+  "files": [
+    "dist",
+    "src/Markgraf.astro",
+    "src/MarkgrafPlayer.tsx",
+    "src/player.css",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "./dist/markgraf-react.css"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && cp src/remark-markgraf.mjs dist/remark-markgraf.mjs && cp src/remark-markgraf.mjs dist/remark-markgraf.js && cp src/player.css dist/markgraf-react.css"
+  },
+  "peerDependencies": {
+    "astro": ">=4",
+    "@astrojs/react": ">=3",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "@markgrafhq/markgraf-react": "0.0.42",
+    "unist-util-visit": "^5"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "typescript": "^5"
+  },
+  "keywords": [
+    "markgraf",
+    "starlight",
+    "astro",
+    "astro-integration",
+    "remark",
+    "animation",
+    "diagram"
+  ],
+  "license": "MIT",
+  "author": "Mark Eibes <mark.eibes@gmail.com>",
+  "homepage": "https://github.com/markgrafhq/starlight-markgraf#readme",
+  "bugs": "https://github.com/markgrafhq/starlight-markgraf/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markgrafhq/starlight-markgraf.git"
+  }
+}

package/src/Markgraf.astro

@@ -0,0 +1,21 @@
+---
+import { StarlightMarkgrafPlayer } from "./MarkgrafPlayer";
+import "./player.css";
+
+interface Props {
+  src: string;
+  renderer?: "canvas" | "svg";
+  class?: string;
+  controls?: boolean;
+}
+
+const { src, renderer = "canvas", class: className, controls = true } = Astro.props;
+---
+
+<StarlightMarkgrafPlayer
+  client:visible
+  src={src}
+  renderer={renderer}
+  className={className}
+  controls={controls}
+/>

package/src/MarkgrafPlayer.tsx

@@ -0,0 +1,217 @@
+import { type ReactNode, useEffect, useState } from "react";
+import { useMarkgraf, type MarkgrafApi } from "@markgrafhq/markgraf-react";
+
+type Renderer = "canvas" | "svg";
+type Theme = "light" | "dark";
+
+export type MarkgrafControls =
+  | boolean
+  | ((api: MarkgrafApi<Element>) => ReactNode);
+const playIcon = (
+  <svg viewBox="0 0 15 15" aria-hidden="true" focusable="false">
+    <path d="M3.24 2.05a.5.5 0 0 1 .52.02l8.5 5a.5.5 0 0 1 0 .86l-8.5 5A.5.5 0 0 1 3 12.5v-10a.5.5 0 0 1 .24-.45Z" />
+  </svg>
+);
+
+const pauseIcon = (
+  <svg viewBox="0 0 15 15" aria-hidden="true" focusable="false">
+    <path d="M3.5 2.5a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 .5.5v10a.5.5 0 0 1-.5.5H4a.5.5 0 0 1-.5-.5v-10Zm5 0A.5.5 0 0 1 9 2h2a.5.5 0 0 1 .5.5v10a.5.5 0 0 1-.5.5H9a.5.5 0 0 1-.5-.5v-10Z" />
+  </svg>
+);
+
+const speedIcon = (
+  <svg
+    className="markgraf-doc-speed-icon"
+    viewBox="0 0 15 15"
+    aria-hidden="true"
+    focusable="false"
+  >
+    <path d="M3.14 5.64a.5.5 0 0 1 .71 0L7.5 9.29l3.65-3.65a.5.5 0 0 1 .7.71l-4 4a.5.5 0 0 1-.7 0l-4-4a.5.5 0 0 1 0-.71Z" />
+  </svg>
+);
+
+export interface MarkgrafPlayerProps {
+  src: string;
+  renderer?: Renderer;
+  className?: string;
+  /**
+   * Shows the transport bar by default. Pass `false` to hide it, or a render
+   * function to replace it with controls driven by the same player API.
+   */
+  controls?: MarkgrafControls;
+}
+
+const useDocumentTheme = (): Theme => {
+  const [theme, setTheme] = useState<Theme>("light");
+
+  useEffect(() => {
+    const root = document.documentElement;
+    const update = () =>
+      setTheme(root.dataset.theme === "dark" ? "dark" : "light");
+    update();
+
+    const observer = new MutationObserver(update);
+    observer.observe(root, {
+      attributes: true,
+      attributeFilter: ["data-theme"],
+    });
+    return () => observer.disconnect();
+  }, []);
+
+  return theme;
+};
+
+const formatTime = (seconds: number): string => {
+  const safe = Number.isFinite(seconds) ? Math.max(0, seconds) : 0;
+  const minutes = Math.floor(safe / 60);
+  const remainder = safe - minutes * 60;
+  return `${minutes}:${remainder.toFixed(1).padStart(4, "0")}`;
+};
+
+const DefaultControls = ({
+  api,
+  speed,
+  setSpeed,
+}: {
+  api: MarkgrafApi<Element>;
+  speed: number;
+  setSpeed: (speed: number) => void;
+}) => {
+  const duration = Number.isFinite(api.duration)
+    ? Math.max(0, api.duration)
+    : 0;
+  const time = Number.isFinite(api.time)
+    ? Math.max(0, Math.min(api.time, duration))
+    : 0;
+
+  return (
+    <div
+      className="markgraf-doc-controls"
+      aria-label="Diagram playback controls"
+    >
+      <button
+        className="markgraf-doc-play"
+        type="button"
+        aria-label={api.playing ? "Pause diagram" : "Play diagram"}
+        aria-pressed={api.playing}
+        disabled={!api.ready}
+        onClick={api.toggle}
+      >
+        {api.playing ? pauseIcon : playIcon}
+      </button>
+
+      <input
+        className="markgraf-doc-scrub"
+        type="range"
+        aria-label="Diagram time"
+        min="0"
+        max={Math.max(duration, 0.001)}
+        step="0.01"
+        value={time}
+        disabled={!api.ready}
+        onChange={(event) => api.seek(event.currentTarget.valueAsNumber)}
+      />
+
+      <output className="markgraf-doc-time" aria-live="off">
+        {formatTime(time)} / {formatTime(duration)}
+      </output>
+
+      <div className="markgraf-doc-speed-control">
+        <select
+          className="markgraf-doc-speed"
+          aria-label="Playback speed"
+          value={speed}
+          disabled={!api.ready}
+          onChange={(event) => setSpeed(Number(event.currentTarget.value))}
+        >
+          <option value="0.5">0.5×</option>
+          <option value="1">1×</option>
+          <option value="1.5">1.5×</option>
+          <option value="2">2×</option>
+        </select>
+        {speedIcon}
+      </div>
+    </div>
+  );
+};
+
+const Controls = ({
+  api,
+  controls,
+}: {
+  api: MarkgrafApi<Element>;
+  controls: MarkgrafControls;
+}) => {
+  const [speed, setSpeed] = useState(1);
+
+  useEffect(() => {
+    if (controls === true && api.ready) api.setSpeed(speed);
+  }, [api.ready, controls, speed]);
+
+  if (typeof controls === "function") return controls(api);
+  if (!controls) return null;
+  return <DefaultControls api={api} speed={speed} setSpeed={setSpeed} />;
+};
+
+const CanvasPlayer = ({
+  src,
+  theme,
+  className,
+  controls,
+}: MarkgrafPlayerProps & { theme: Theme; controls: MarkgrafControls }) => {
+  const api = useMarkgraf(src, { renderer: "canvas", theme });
+
+  return (
+    <div
+      className={`not-content markgraf-doc-player ${className ?? ""}`}
+      data-markgraf-theme={theme}
+    >
+      <canvas
+        className="markgraf-player markgraf-doc-stage"
+        ref={api.elementRef}
+        onClick={api.toggle}
+        aria-label="Animated Markgraf diagram"
+      />
+      <Controls api={api} controls={controls} />
+    </div>
+  );
+};
+
+const SvgPlayer = ({
+  src,
+  theme,
+  className,
+  controls,
+}: MarkgrafPlayerProps & { theme: Theme; controls: MarkgrafControls }) => {
+  const api = useMarkgraf(src, { renderer: "svg", theme });
+
+  return (
+    <div
+      className={`not-content markgraf-doc-player ${className ?? ""}`}
+      data-markgraf-theme={theme}
+    >
+      <svg
+        className="markgraf-player markgraf-doc-stage"
+        ref={api.elementRef}
+        onClick={api.toggle}
+        aria-label="Animated Markgraf diagram"
+      />
+      <Controls api={api} controls={controls} />
+    </div>
+  );
+};
+
+export const StarlightMarkgrafPlayer = ({
+  src,
+  renderer = "canvas",
+  className,
+  controls = true,
+}: MarkgrafPlayerProps) => {
+  const theme = useDocumentTheme();
+  const props = { src, renderer, className, controls, theme };
+  return renderer === "svg" ? (
+    <SvgPlayer {...props} />
+  ) : (
+    <CanvasPlayer {...props} />
+  );
+};

package/src/player.css

@@ -0,0 +1,154 @@
+@import "@markgrafhq/markgraf-react/css";
+
+.markgraf-doc-player {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  min-width: 0;
+  min-height: 11.25rem;
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  border: 1px solid color-mix(in srgb, currentColor 14%, transparent);
+  border-radius: 0.875rem;
+  background: #ffffff;
+  box-shadow: 0 1rem 3rem rgb(0 0 0 / 10%);
+}
+
+.markgraf-doc-player[data-markgraf-theme="dark"] {
+  background: #101827;
+}
+
+.markgraf-doc-stage {
+  display: block;
+  width: 100%;
+  height: 100%;
+  min-height: 11.25rem;
+  cursor: pointer;
+}
+
+.markgraf-doc-controls {
+  position: absolute;
+  z-index: 2;
+  right: 50%;
+  bottom: 0.75rem;
+  display: grid;
+  grid-template-columns: 1.75rem minmax(7rem, 1fr) auto auto;
+  align-items: center;
+  gap: 0.5rem;
+  width: min(35rem, calc(100% - 2rem));
+  padding: 0.375rem 0.5rem;
+  border: 1px solid rgb(255 255 255 / 14%);
+  border-radius: 999px;
+  color: #ffffff;
+  background: rgb(8 13 22 / 58%);
+  box-shadow: 0 0.875rem 2.75rem rgb(0 0 0 / 28%);
+  opacity: 0.78;
+  transform: translateX(50%);
+  transition:
+    opacity 140ms ease,
+    background 140ms ease;
+  backdrop-filter: blur(18px);
+}
+
+.markgraf-doc-player:hover .markgraf-doc-controls,
+.markgraf-doc-controls:focus-within {
+  background: rgb(8 13 22 / 78%);
+  opacity: 0.98;
+}
+
+.markgraf-doc-play {
+  display: grid;
+  width: 1.75rem;
+  height: 1.75rem;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  place-items: center;
+  color: inherit;
+  background: rgb(255 255 255 / 10%);
+  cursor: pointer;
+}
+
+.markgraf-doc-play:hover,
+.markgraf-doc-play:focus-visible {
+  background: rgb(255 255 255 / 20%);
+}
+
+.markgraf-doc-play svg {
+  width: 0.875rem;
+  height: 0.875rem;
+}
+
+.markgraf-doc-scrub {
+  min-width: 0;
+  height: 0.875rem;
+  margin: 0;
+  accent-color: #ffffff;
+  cursor: pointer;
+}
+
+.markgraf-doc-time {
+  color: rgb(255 255 255 / 76%);
+  font-family: var(
+    --sl-font-mono,
+    var(--ifm-font-family-monospace, ui-monospace, monospace)
+  );
+  font-size: 0.625rem;
+  line-height: 1;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+.markgraf-doc-speed-control {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+.markgraf-doc-speed {
+  appearance: none;
+  width: 100%;
+  padding: 0.1875rem 1.375rem 0.1875rem 0.5rem;
+  border: 0;
+  border-radius: 999px;
+  color: #ffffff;
+  background: rgb(255 255 255 / 10%);
+  font-size: 0.625rem;
+  cursor: pointer;
+}
+
+.markgraf-doc-speed-icon {
+  position: absolute;
+  right: 0.4375rem;
+  width: 0.75rem;
+  height: 0.75rem;
+  color: rgb(255 255 255 / 72%);
+  pointer-events: none;
+}
+
+.markgraf-doc-speed option {
+  color: #111827;
+  background: #ffffff;
+}
+
+.markgraf-doc-controls :disabled {
+  cursor: wait;
+  opacity: 0.5;
+}
+
+@media (max-width: 32rem) {
+  .markgraf-doc-controls {
+    grid-template-columns: 1.75rem minmax(5rem, 1fr) auto;
+  }
+
+  .markgraf-doc-time {
+    display: none;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .markgraf-doc-controls {
+    transition: none;
+  }
+}