Integrate ReadingVox

<!-- Put a placeholder wherever you want a "Listen to this page" button -->
<article>
  <h1>Lesson 4: Flight</h1>
  <div data-readingvox-button data-toolbar="true"></div>
  …
</article>

<footer>
  <!-- Opens the toolbar instead of playing straight away -->
  <div data-readingvox-button data-size="small" data-label="Listen" data-action="toolbar"></div>
</footer>

<!-- Only the placed buttons, no floating corner button: -->
<script src="https://readingvox.com/widget.js" data-key="YOUR_API_KEY" data-show-toggle="false" async></script>

<article lang="en">
  <h1>Field trip to the science museum</h1>

  <!-- Skipped: anything with class="no-read" -->
  <div class="share-buttons no-read">Share · Print · Email</div>

  <!-- Say it differently: the page shows "NASA", the voice says the words -->
  <p>
    We'll visit the <span data-rv-say="National Aeronautics and Space Administration">NASA</span> exhibit.
  </p>

  <!-- Read in Spanish with a Spanish voice -->
  <p lang="es">Los estudiantes deben traer almuerzo.</p>
</article>

<!-- A quiz, wizard, tabs or slide deck: one step showing, the rest hidden -->
<main>
  <section class="step">Question 1: How do you like to solve problems?</section>
  <section class="step" hidden>Question 2: …</section>          <!-- skipped -->
  <section class="step" style="display:none">Question 3: …</section> <!-- skipped -->
  <section class="step" aria-hidden="true">Question 4: …</section>   <!-- skipped -->
</main>
<!-- Show the next step (or render it in place, as React does) and Play reads that step -->

<!-- https://www.example.com/lesson: the page visitors open -->
<script src="https://readingvox.com/widget.js" data-key="YOUR_API_KEY" async></script>

<main>
  <h1>Lesson 4: Flight</h1>
  <!-- Same origin: read automatically, nothing to add inside -->
  <iframe src="/quizzes/flight-check"></iframe>
  <!-- Another subdomain: add the script inside that page too (below) -->
  <iframe src="https://media.example.com/notes/42"></iframe>
</main>

<!-- https://media.example.com/notes/42: the framed page -->
<!-- Same snippet. Framed by a page that runs ReadingVox, it shows no button and
     reads through that page; opened on its own, it works as a normal page. -->
<script src="https://readingvox.com/widget.js" data-key="YOUR_API_KEY" async></script>

<!-- Framed by a different domain you trust? List that origin on both pages: -->
<script src="https://readingvox.com/widget.js" data-key="YOUR_API_KEY"
  data-frame-origins="https://partner.example.org" async></script>

<!-- Define the init function first, then load the widget async; it calls initReadingVox when ready -->
<script>
  function initReadingVox() {
    // async scripts can arrive before the page has finished loading
    if (document.readyState === "loading") {
      return document.addEventListener("DOMContentLoaded", initReadingVox);
    }
    var rv = new ReadingVox({
      apiKey: "YOUR_API_KEY",
      voice: "heart",
      mode: "page",
      selectors: ["article"],
      onReady: function () { console.log("ReadingVox ready"); },
      onError: function (err) { console.warn("ReadingVox:", err.message); },
    });
    rv.initialize();

    // Optional: your own button
    document.querySelector("#listen").addEventListener("click", function () {
      rv.isPlaying() ? rv.pause() : rv.play();
    });
  }
</script>
<script src="https://readingvox.com/widget.js" data-auto-init="false" async onload="initReadingVox()"></script>

// readingvox.ts — load the widget script once, then create instances yourself

export type ReadingVoxVoice = "heart" | "michael" | "lily" | "leo" | "mia" | "theo"

export interface ReadingVoxOptions {
  apiKey: string
  voice?: ReadingVoxVoice
  speed?: number                      // 0.5 – 2
  mode?: "highlight" | "page" | "block"
  selectors?: string[]                // what to read (default: article, main, [role=main], .content)
  ignoreSelectors?: string[]          // what to skip inside it
  observeContent?: boolean            // pick up content that renders after load
  readFrames?: boolean                // read iframes in place (default true)
  frameOrigins?: string[]             // extra origins allowed for frame mode
  contentLanguage?: string            // "auto" (default) or e.g. "es"
  uiLanguage?: string                 // toolbar language, e.g. "es"
  enabledTools?: string[]             // same ids as data-tools
  theme?: "auto" | "light" | "dark" | { mode?: "auto" | "light" | "dark"; primaryColor?: string }
  toolbarPosition?: "top" | "bottom"
  togglePosition?: "bottom-right" | "bottom-left" | "top-right" | "top-left"
  showToggle?: boolean
  documentLinks?: boolean             // Listen buttons on PDF links
  onReady?: () => void
  onPlay?: () => void
  onPause?: () => void
  onEnd?: () => void
  onError?: (error: Error) => void
}

export interface ReadingVoxInstance {
  initialize(): Promise<void>
  play(): Promise<void>
  pause(): void
  stop(): void
  isPlaying(): boolean
  playText(text: string): Promise<void>
  setSpeed(speed: number): void
  setVoice(voice: ReadingVoxVoice): void
  destroy(): void
}

declare global {
  interface Window {
    ReadingVox?: new (options: ReadingVoxOptions) => ReadingVoxInstance
  }
}

const SRC = "https://readingvox.com/widget.js"
let loading: Promise<void> | null = null

export function loadReadingVox(): Promise<void> {
  if (typeof window === "undefined") return Promise.resolve() // server render
  if (window.ReadingVox) return Promise.resolve()
  if (!loading) {
    loading = new Promise<void>((resolve, reject) => {
      const script = document.createElement("script")
      script.src = SRC
      script.async = true
      script.dataset.autoInit = "false" // we create the instance ourselves
      script.onload = () => resolve()
      script.onerror = () => {
        loading = null
        reject(new Error("ReadingVox failed to load"))
      }
      document.head.appendChild(script)
    })
  }
  return loading
}

// useReadingVox.ts
import { useEffect } from "react"
import { loadReadingVox, type ReadingVoxInstance, type ReadingVoxOptions } from "./readingvox"

/**
 * Creates the widget after your content renders and removes it on unmount.
 * Pass the current route as resetKey so each page gets a fresh instance.
 */
export function useReadingVox(options: ReadingVoxOptions, resetKey?: unknown) {
  useEffect(() => {
    let instance: ReadingVoxInstance | null = null
    let cancelled = false

    loadReadingVox()
      .then(() => {
        if (cancelled || !window.ReadingVox) return
        instance = new window.ReadingVox(options)
        instance.initialize().catch(() => {}) // e.g. a page with nothing to read
      })
      .catch((err) => console.warn(err))

    return () => {
      cancelled = true
      instance?.destroy()
    }
    // Options are read once per page; change resetKey to re-create
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [resetKey])
}

// App.tsx (Vite + React Router)
import { Outlet, useLocation } from "react-router-dom"
import { useReadingVox } from "./useReadingVox"

export default function App() {
  const { pathname } = useLocation()

  useReadingVox(
    {
      apiKey: import.meta.env.VITE_READINGVOX_KEY,
      voice: "heart",
      selectors: ["main article"],
      observeContent: true, // articles that load from an API after the route renders
    },
    pathname,
  )

  return (
    <main>
      <Outlet />
    </main>
  )
}

# .env (Vite exposes VITE_* variables to the browser)
VITE_READINGVOX_KEY=rv_live_...

// app/readingvox.tsx
"use client"

import { usePathname } from "next/navigation"
import { useReadingVox } from "@/lib/useReadingVox" // the hook from the React example

export function ReadingVox() {
  const pathname = usePathname()

  useReadingVox(
    {
      apiKey: process.env.NEXT_PUBLIC_READINGVOX_KEY!,
      voice: "heart",
      selectors: ["article"],
      observeContent: true,
    },
    pathname, // client-side navigation re-creates the widget for the new page
  )

  return null
}

// app/layout.tsx
import { ReadingVox } from "./readingvox"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <ReadingVox />
      </body>
    </html>
  )
}

# .env.local
NEXT_PUBLIC_READINGVOX_KEY=rv_live_...

// composables/useReadingVox.ts
import { onBeforeUnmount, onMounted, watch } from "vue"
import { useRoute } from "vue-router"
import { loadReadingVox, type ReadingVoxInstance, type ReadingVoxOptions } from "../readingvox"

export function useReadingVox(options: ReadingVoxOptions) {
  const route = useRoute()
  let instance: ReadingVoxInstance | null = null
  let generation = 0

  async function start() {
    const mine = ++generation
    instance?.destroy()
    instance = null
    await loadReadingVox()
    if (mine !== generation || !window.ReadingVox) return // a newer route won
    instance = new window.ReadingVox(options)
    instance.initialize().catch(() => {})
  }

  onMounted(start)
  // flush: "post" waits until the new page's DOM is rendered
  watch(() => route.path, start, { flush: "post" })
  onBeforeUnmount(() => {
    generation++
    instance?.destroy()
    instance = null
  })
}

<!-- App.vue -->
<script setup lang="ts">
import { useReadingVox } from "./composables/useReadingVox"

useReadingVox({
  apiKey: import.meta.env.VITE_READINGVOX_KEY,
  voice: "heart",
  selectors: ["main article"],
  observeContent: true,
})
</script>

<template>
  <main><RouterView /></main>
</template>

// server.js — Express + EJS, with a Content Security Policy that allows ReadingVox
import express from "express"
import helmet from "helmet"

const app = express()
app.set("view engine", "ejs")

app.use(
  helmet({
    contentSecurityPolicy: {
      directives: {
        "script-src": ["'self'", "https://readingvox.com"],
        "connect-src": ["'self'", "https://readingvox.com"],
        "media-src": ["'self'", "https://readingvox.com", "blob:"],
        "font-src": ["'self'", "https://readingvox.com"],
        "style-src": ["'self'", "'unsafe-inline'"],
      },
    },
  }),
)

// The key is public (it ends up in your HTML) and locked to your domains,
// but keeping it in config makes per-environment keys easy.
app.use((req, res, next) => {
  res.locals.readingvoxKey = process.env.READINGVOX_KEY
  next()
})

app.get("/articles/:slug", async (req, res) => {
  const article = await loadArticle(req.params.slug)
  res.render("article", { article, readAloud: true })
})

app.listen(3000)

<!-- views/article.ejs -->
<article>
  <h1><%= article.title %></h1>
  <%- article.html %>
</article>

<% if (readAloud && readingvoxKey) { %>
  <script
    src="https://readingvox.com/widget.js"
    data-key="<%= readingvoxKey %>"
    data-voice="heart"
    data-selectors="article"
    async
  ></script>
<% } %>

// Read any string aloud (e.g. a quiz question rendered in canvas or an image)
await rv.playText("Which planet is closest to the Sun?")

// Read from a specific element to the end of the content
await rv.readFrom(document.querySelector("#chapter-3"))

rv.setSpeed(1.25)
rv.setVoice("michael")
rv.stop()