What you can build

Three integration patterns. They are not alternatives — most partners ship the third first because it takes an afternoon, then move to the first over the following quarter as usage justifies it.

---

Pattern 1 — Embedded

PlaySpace surfaces render inside your application. Your navigation, your domain, your session. A clinician clicks "Open sandtray" in your appointment view and a sandtray appears in the panel beside your notes. They never see our brand, our login, or our chrome unless you choose to show it.

This is the deepest integration and the one that makes PlaySpace feel like a feature of your product rather than a link out of it.

import { PlaySpaceProvider, Sandtray } from '@playspace/react'

export function SessionWorkspace({ token }) {
  return (
    <div className="grid grid-cols-2">
      <YourClinicalNotes />
      <PlaySpaceProvider token={token}>
        <Sandtray />
      </PlaySpaceProvider>
    </div>
  )
}

What it costs you: a token endpoint on your backend, one provider component, and a decision about where the surface lives in your layout.

What you get: every surface in the catalog, addressable individually, role-aware, with lifecycle events you can act on. A generated storybook can appear in your own document list the moment it is ready, because you were told it was ready.

---

Pattern 2 — Programmatic

You drive PlaySpace from your backend, and render nothing. Generate a storybook for a client overnight and attach the resulting document to their chart in your system. Pull the form responses a clinician collected in a session and write them into your own assessment history. Export a client's complete PlaySpace record when they request their data.

No user interface, no iframe, no browser. Just your server talking to ours.

const job = await playspace.storybooks.generate({
  clinician: { externalId: 'staff_8842' },
  subject:   { externalId: 'client_55130' },
  prompt: 'A story about starting at a new school, for a seven-year-old who is nervous about it.',
  pages: 8,
})

const storybook = await job.wait()
const pdf = await playspace.storybooks.download(storybook.id, { format: 'pdf' })

What it costs you: server credentials and the calls you choose to make.

What you get: every artifact PlaySpace produces, as structured data and as a rendered document, attributable to a person in your system and exportable on demand.

---

Pattern 3 — Linked

You send people to a hosted PlaySpace session and get the results back. One call returns two links — one for the clinician, one for the client. Put them in your appointment view and your reminder emails. The session runs on our domain, in our interface, and hands you back what happened when it ends.

const session = await playspace.sessions.create({
  appointment: { externalId: 'appt_11923' },
  clinician:   { externalId: 'staff_8842' },
  participants: [{ externalId: 'client_55130' }],
  playroom: 'child-default',
})

session.links.clinician // → https://play.playspace.health/s/...
session.links.patient   // → https://play.playspace.health/s/...

What it costs you: one endpoint call and two links in your interface.

What you get: the complete PlaySpace session experience with no user interface work at all, including surfaces not yet available as embedded components.

---

What each pattern gives you, by surface

A surface marked "saves and snapshots only" under Programmatic means the interaction itself needs a person and a screen; what your backend can reach is the state it produced.

---

Who each pattern serves

Your clinicians get therapeutic play without a second tab, a second login, or a second invoice. The single most common reason a clinician abandons a specialist tool is that it lives outside the system they already have open.

Your clients — most of them children — get a play surface that opens from the same link their appointment already uses. No account, no password, no application to install.

Your product gets a category of capability that is genuinely hard to build. The sandtray alone is a synchronised three-dimensional multiplayer surface with a figure library, a save model and a two-cursor presence layer. It exists, it is in clinical use, and it can be in your product behind one component.

---

What we do not ask of you

We do not ask you to move your data. No patient import, no schedule synchronisation, no reconciliation job, no nightly file. You keep your records. We hold a pointer to them.

We do not compete with your core. We do not schedule, we do not bill, we do not do claims, and we do not write into your clinical notes. Where our surfaces produce something documentation-shaped, you read it and decide what to do with it.

We do not require your clinicians to hold a PlaySpace account. A clinician your platform vouches for is a clinician we accept. Identity flows one way, from you to us.

---

What we ask of you

A token endpoint. One route on your backend that authenticates your own user and returns a PlaySpace token scoped to them. Twenty lines. It exists so that your credentials never reach a browser.

Origin registration. The domains your application is served from, registered ahead of time. We validate them when a token is minted rather than when a frame fails to load, so a misconfiguration is an error message you can read instead of a blank rectangle you have to guess at.

A decision about clinical documentation. Notes are opt-in per organisation and off by default. If your platform ships its own documentation product, leave it off.