Faces

Get the authenticated user's live editor state across all their open browser tabs. Returns an array of active tabs, each with the project slug they're viewing, the currently selected slide (faceId), and whether agent mode is enabled. Tabs with no activity in the last ~60 seconds are not included. Useful for understanding which project the user is currently working on before suggesting actions or calling other tools that need a projectSlug.

List the face plugins available to attach to a slide (id and one-line description). Plugins add runtime behaviors a slide's React code can't express on its own — e.g. collecting form submissions, or embedding a live AI video presenter. Call this to discover what's available, then get_plugin_docs for the full config schema and code examples before setup_plugin.

List the authenticated user's projects. Returns project IDs, names, and metadata. Use cursor for pagination.

List all slides in a project. Returns slide IDs and names. Use the slide ID with get_slide and update_slide.

List the teams the authenticated user belongs to. Returns team IDs, slugs, names, and the user's role in each. The personal team is flagged with isPersonal: true and is the default when creating a project without teamId.

Publish a project's latest version, making it publicly accessible at its live URL. Returns the publishedUrl. Call this after the user is happy with the slides. Re-publishing an already-published project pushes the current latest version live.

Rename a project. Changes only the display name — the projectSlug and URLs stay the same.

Reorder ALL slides in a project to the order you specify. Pass the complete list of existing slideIds in the order you want them to appear. Missing or extra IDs return 400. The order is applied atomically; both the persisted project state and the live editor view end up in the same order. Use this to restructure an existing deck (e.g. move the intro to the end, swap sections). For creating new slides in a specific order, use create_slides instead — do NOT delete and recreate just to reorder.

Configure a plugin instance on a specific slide. Validates config against the plugin's schema and writes it to the slide's face.plugins.json. Other plugin instances already on the slide are preserved — only the instance with this localName is added or changed. By default this REFUSES to overwrite an existing instance with the same localName (returns 409). To tweak an existing instance's config, pass overwrite: true. Use a fresh localName to add a second instance alongside existing ones. After setup, the slide's face.tsx can call the plugin via its hook (e.g. useFormPlugin(localName) / usePresenterPlugin(localName)) — see get_plugin_docs for the exact API. Read the current face.plugins.json from get_slide first if you need to see what's already configured.

Enable 'agent mode' on a specific project in the user's browser. This hides the right sidebar (chat, content, controls) and shows a black floating bar at the bottom indicating that an agent is driving the session. The user can still deactivate it manually. Pair with get_user_state to discover which projectSlug the user currently has open. Set enabled=false to remotely deactivate agent mode. The signal is broadcast to all of the user's browser tabs that have the project open.

Signal that you are about to edit a slide. This shows a loading gradient in the editor so viewers know the slide is being modified. Call this BEFORE making changes with update_slide. Always call finish_slide_editing when done, even if the edit fails.

Unpublish a project, taking it offline so its live URL no longer serves the project. The project and its slides are not deleted — it can be re-published later with publish_project.

Update project.config.json. Only keys present in `config` are changed; other keys are preserved. Use this to define or update the project-wide design system under `tokens` before styling slides. Example tokens block: { "tokens": { "palette": [ { "name": "--background", "value": "#0D0D0D" }, { "name": "--foreground", "value": "#F7F2EA" }, { "name": "--brand", "value": "#FF5A36" } ], "fonts": [ { "name": "--font-display", "family": "Space Grotesk" }, { "name": "--font-body", "family": "Inter" } ] } } Color names must start with `--`; font names with `--font-`. See get_slide_guide for the full design token reference.

Update a slide's source files. File contents go INSIDE the `files` object, not at the top level. Only keys present in `files` are changed — omit keys for files you don't want to modify. The code is compiled and validated before saving — returns 400 with detailed errors if it doesn't compile. If face.tsx imports a sibling file (e.g. `import "./face.css"`), create that file FIRST in a separate update_slide call before adding the import to face.tsx. Missing sibling files cause the artifact to fail compilation in the browser. IMPORTANT: You must call get_slide_guide and read the authoring reference before writing any slide code. See the instructions for the full file format reference, workflows, and examples.

Take a screenshot of a slide as it currently renders, and return it as an image so you can see the slide visually. Use this to verify layout, spacing, colors, typography, image placement, or whether a recent edit produced the intended result. The screenshot is captured headlessly in the cloud against the latest saved version of the project. Call this AFTER finishing any edits so the rendering reflects current state. Pass isMobile=true to capture the mobile layout.