@mymagicpencil/react

React SDK for embedding My Magic Pencil visual lessons into your React application.

Installation

npm install @mymagicpencil/react

Quick Start

Wrap your app with the MagicPencilProvider:

import { MagicPencilProvider, MagicPencilEmbed } from '@mymagicpencil/react';

function App() {
  return (
    <MagicPencilProvider apiKey="your-publishable-key">
      <MagicPencilEmbed
        sessionId="session-id"
        width="100%"
        height="600px"
        onReady={() => console.log('Lesson ready!')}
        onComplete={() => console.log('Lesson complete!')}
      />
    </MagicPencilProvider>
  );
}

Components

<MagicPencilProvider>

Context provider that supplies your API key to all child components.

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiKey | string | Yes | Your publishable API key | | children | ReactNode | Yes | Child components |

<MagicPencilEmbed>

Renders an embedded visual lesson in an iframe.

| Prop | Type | Required | Description | |------|------|----------|-------------| | sessionId | string | No* | Session ID to display | | embedUrl | string | No* | Pre-resolved embed URL | | width | string \| number | No | Width (default: '100%') | | height | string \| number | No | Height (default: '100%') | | onReady | () => void | No | Called when lesson starts | | onComplete | () => void | No | Called when lesson finishes | | onError | (error: string) => void | No | Called on errors | | className | string | No | CSS class name |

*Provide either sessionId or embedUrl.

Ref Methods

const ref = useRef<MagicPencilRef>(null);
<MagicPencilEmbed ref={ref} sessionId="..." />

// Control playback
ref.current?.play();
ref.current?.pause();

Hooks

useSession()

Create sessions programmatically:

import { useSession } from '@mymagicpencil/react';

function LessonCreator() {
  const { createSession, isLoading, error } = useSession();

  const handleCreate = async () => {
    const session = await createSession({
      prompt: 'Explain photosynthesis',
      theme: 'dark',
      drawing_style: 'sketch',
    });
    console.log(session?.embed_url);
  };

  return <button onClick={handleCreate} disabled={isLoading}>Generate</button>;
}

Client

MagicPencilClient

For non-React or server-side usage:

import { MagicPencilClient } from '@mymagicpencil/react';

const client = new MagicPencilClient('your-secret-key');
const session = await client.createSession({ prompt: 'Explain gravity' });

License

MIT