@potoru/react

Potoru stories in React: <PotoPlayer>, <PotoSnapshot>, <PotoEditor> and compile(). Thin wrappers of the Potoru elements (<potoru-player>, <potoru-snapshot> and <potoru-editor> from @potoru/web, a dependency), with the same names as every other Potoru host.

npm install @potoru/react react

import { useRef } from "react";
import { PotoPlayer, PotoSnapshot } from "@potoru/react";

export function Story() {
  const player = useRef(null);
  return (
    <>
      <PotoPlayer
        ref={player}
        src="https://example.com/stories/sunrise.poto"
        autoplay
        muted
        loop
        controls
        style={{ width: "100%" }}
        onReady={(detail) => console.log("ready", detail.mode, detail.duration)}
        onReport={(detail) => console.log("the story reported", detail.event, detail.payload)}
        onError={(detail) => console.warn(detail.code, detail.message)}
      />
      <button onClick={() => player.current?.restart()}>Restart</button>
      <button onClick={() => player.current?.fire("story-door", "open")}>Open the door</button>
      <PotoSnapshot src="https://example.com/stories/sunrise.poto" time={1.5} style={{ width: 240 }} />
    </>
  );
}

import { PotoEditor, compile } from "@potoru/react";

// A format v4 source folder as path → text.
const result = await compile({ yaml: files });          // { ok, poto, diagnostics, sizes }
<PotoEditor yaml={files} mode="yaml" style={{ height: 560 }} onCompiled={(r) => save(r.poto)} />

Components

| Component | Props | Ref (handle) | |---|---|---| | PotoPlayer | src (URL or bytes), libraries, mode, camera, autoplay, muted, loop, controls, captions, still + time, fit, renderer, id, className, style; onReady, onPlay, onPause, onEnded, onReport, onError, onSlide, onScene, onCaption, onCamera | play(), pause(), seek(s), restart(), next(), prev(), goto(i), set(target, data, value), fire(target, event, payload?), setCamera(id), load(src), currentTime(), duration(), element | | PotoSnapshot | src, time, libraries, camera, fit, id, className, style; onReady, onError | seek(s), load(src), currentTime(), duration(), element | | PotoEditor | yaml, mode ("yaml" or "script"), script, id, className, style; onCompiled, onError | getFiles(), setFiles(), getScript(), setScript(), setMode(), compile(), download(), lastResult, element |

compile(input): { yaml } (YAML mode, a source folder) or { script, yaml? } (Script mode, authoring-API JavaScript in a sandbox; browsers only, JavaScript only in 1.0). Never rejects for bad source: problems come back as diagnostics with file and line. The full interface, shared by every host: docs/COMPONENTS.md in the repository.

Notes

• PotoPlayer and PotoSnapshot use @potoru/web/player; PotoEditor and compile() import the full @potoru/web lazily when the editor mounts or compile() runs, and the compiler itself loads on the first compile: an app that imports only PotoPlayer / PotoSnapshot bundles no compiler or editor code.
• The module starts with "use client" (Next.js App Router); the elements register in the browser only. On the server the components render the bare tags.
• With an app bundler, copy node_modules/@potoru/web/dist/fonts/ to fonts/ next to your page for stories that use the built-in fonts (see the @potoru/web README).
• A package that needs a newer player fails with onError code needs-newer-player.
• react 18 or 19 is a peer dependency. Versions move in lockstep with @potoru/web.

Licence

Apache-2.0 (LICENSE, NOTICE). "Potoru" is a trademark of The Potoru Authors.