PlaySpace
Quickstart

Level 3: single surfaces

Frame one PlaySpace thing at a time, in your own layout, with your own navigation around it. A storybook reader beside a chart. A form to fill in during a session. A sandtray in a panel your clinicians already know.

Level 1 frames the product and lets it navigate. Level 3 frames one artifact, hands the result back through an event, and leaves the rest of the page to you. Choose it when you have an interface you want to keep, and a specific place in it where a PlaySpace surface belongs.

The mechanics are the same as Level 1: a token minted on your server, a component given a callback. What changes is that you pick the mode, you pass the identifier the mode needs, and you act on the event it emits.

The surfaces

Each surface has a reference page of its own — what it renders, the identifier it needs, what each capability adds, the server and browser snippets, every event it emits, and the things that will bite you. This table is the index.

Mode What it renders Capabilities the token needs Events it emits needs patientId Reference
create the storybook authoring flow storybook:create, storybook:read storybook.created, storybook.ready no Storybooks
reader one storybook, read-only storybook:read storybook.shared with storybook:share no Storybooks
storybook-workspace the clinician's whole storybook library, with its own navigation storybook:read, plus whichever of storybook:create (New storybook, and the editor's Regenerate image and Add page: each a real generation), storybook:write (Add to my rooms, Rooms, and the editor's text, illustration and page-order edits), storybook:delete (Delete in the editor) the seat should hold storybook.created, storybook.saved, storybook.deleted, storybook.shared no Storybooks
list the clinician's published forms, to pick from form:read form.opened no Forms
fill one form, answerable form:read, form:submit form.opened, form.submitted required Forms
form-create the form builder form:create form.created no Forms
form-shelf which of the clinician's rooms one form appears in form:compose form.shelf_changed no Forms
form-workspace the clinician's whole forms library, with its own navigation form:read, plus at least one of form:create, form:write, form:delete, form:compose; client:read optional, and what offers Fill out and Send to client form.created, form.saved, form.deleted, form.shelf_changed, form.fill_requested, form.send_requested no Forms
worksheet one worksheet, read-only worksheet:read worksheet.ready no Worksheets
worksheet-upload a PDF becomes a worksheet in the library worksheet:create, worksheet:read worksheet.created no Worksheets
worksheet-edit one worksheet in the drawing editor: pages, drawing tools, add / reorder / delete a page worksheet:write, worksheet:read, plus worksheet:delete to offer Delete and worksheet:generate to offer AI images worksheet.saved, worksheet.deleted no Worksheets
worksheet-workspace the clinician's whole worksheet library, with its own navigation worksheet:read, plus whichever of worksheet:create (upload, blank create, Duplicate), worksheet:write (the editor, Add to my rooms, Rooms), worksheet:delete, worksheet:generate the seat should hold worksheet.created, worksheet.saved, worksheet.deleted, worksheet.shared no Worksheets
game a live sandtray or dollhouse session, two seats games:play game.session_started, game.save_created, game.saved, game.save_loaded named when the session is started Games

reader, fill and form-shelf take the identifier of the thing they show; worksheet and worksheet-edit take a worksheet identifier. A game seat is different in kind: its token comes from POST /v1/partner/game-sessions rather than from the embed-token mint, and one call returns both seats.

The whole PlaySpace workspace is framed the same way, by a shell mode that owns its own navigation. It is Level 1, and its reference page is the whole workspace.

Surfaces that exist only inside the framed workspace

There is no standalone document for these, so do not go looking for a mode:

  • Clinical Notes, the list and the reader.
  • Clients, the roster and one client's usage summary.
  • Calendar, the clinician's own calendar, and the Video Session list.
  • Home, the day's summary.
  • Rooms — the playroom list, one room's shelf, and creating or editing a room.
  • The Rooms picker for a storybook. The form picker has a standalone mode of its own, form-shelf; the worksheet picker has no mode of its own but is reachable from the worksheet reader inside worksheet-workspace.

Their data is still reachable from your own server through the Partner API, which is Level 4. What has no Level 3 form is the screen.

If you want these inside your product as screens, the answer is Level 1, not a mode.

token or fetchToken

This is the one mechanic every surface above shares, so it is written down once here rather than on each reference page. Both properties are accepted, and at least one is required. The difference is what happens when the token expires.

fetchToken is the default choice. The SDK calls it to mount, and again shortly before each expiry, then pushes the fresh token into the running frame as a message. The document is not reloaded and nothing on screen is lost. Use it wherever the surface can outlive fifteen minutes, which is nearly everywhere.

token pins one credential to one frame. Because the token is part of the frame's source, changing the property remounts the frame. That is what you want when the token's subject changes, as it does for a patient-bound fill: a new patient is a new frame. It is what you do not want mid-session.

Raise ttlSeconds only where a remount would cost real work. The drawing editor is the case that earns it: a clinician draws for as long as a session lasts, saves happen automatically about a second after the drawing stops, and a remount would interrupt that. The default is fifteen minutes, the minimum a minute, the maximum an hour.

Where to go next

A surface you are about to build has its own reference page: storybooks, forms, worksheets, games, and the whole workspace.

Two of them are worked through end to end as guides. Embed a sandtray is the game surface, and the interesting part is getting the client's seat to the client's browser without putting a credential in a link. Generate a storybook is the create surface, with the server-side generation path beside it for comparison.

Data without a screen is Level 4.

Every mode, capability, event and error code is in the @playspace-health/embed reference. A host that cannot install the package frames the same surfaces by URL — Using the API from other languages gives the URL for each one.