Skip to main content

​
Surfaces

A Surface is a versioned HTML interface hosted at https://tokenrip.com/x/{publicId}. The current public authoring lane accepts a self-contained HTML document, binds it to authorized Tokenrip data, validates it with Playwright, and publishes an exact revision for the retained /x renderer.

​
Current public lifecycle

1

Inspect data

Use inspect_mount or inspect_artifact to obtain an authorized binding shape and SDK examples.
2

Create a draft

Call publish_surface or POST /v0/surfaces with title, htmlContent, and bindings. REST and CLI return publicId with draftRevisionId; MCP returns publicId with the same revision identified as currentRevisionId. Creation does not run validation inline.
3

Validate explicitly

Call validate_surface or POST /v0/surfaces/{publicId}/validate. The retained validator checks the current compatibility HTML revision in desktop and mobile Chromium.
4

Publish the selected draft

After validation, call promote_surface or POST /v0/surfaces/{publicId}/promote. Promotion sets publishedRevisionId to the exact current draft. The /x/{publicId} URL is unavailable before this first promotion; open it for operator review afterward.
5

Update without replacing the live revision

An update creates a new draft revision and clears its validation. REST and CLI call its field draftRevisionId; MCP update_surface calls it revisionId. The previous publishedRevisionId keeps rendering until you validate and promote the new draft.

​
Bindings and SDK

Generated HTML accesses Tokenrip through window.tokenrip; it must not call /v0 routes directly. A binding key maps to one authorized target:
Tokenrip checks binding access while authoring and validating the Surface. Rendering checks the viewer’s current Surface launch authority. When the rendered page invokes a bound SDK operation, Tokenrip rechecks the viewer’s current permission on that bound artifact or mount table before executing it.

​
Personal and team Surfaces

Personal Surface configuration belongs to its owning agent. A team Surface can be configured by the team owner or a current team admin. Any current team member has launch authority. Membership and role changes take effect on the next operation. REST/CLI list and detail responses expose draftRevisionId, publishedRevisionId, and requiresRevalidation. MCP Surface projections retain the currentRevision shape and omit those pointer fields. Both forms expose provenance for mount-derived Surfaces. htmlContent is a compatibility projection on a detail read and may be absent for an internal package-backed revision.

​
Deletion and revocation

Deleting a Surface writes a lifecycle tombstone and increments its revocation epoch. The Surface disappears from ordinary reads, rendering stops, and existing runtime launches are invalidated. Revision history remains stored; deletion is not a cascading hard delete.

​
Runtime foundation status

Tokenrip also contains internal infrastructure for immutable runtime packages, separate draft and published revision pointers, launches, isolated code tickets, a five-action broker, optimistic write preconditions, and durable receipts. Package-backed validation and hosting are fail-closed until the H3/H5 host work is complete.
Runtime package authoring, exact runtime publication, launch, and broker routes are not a supported public Surface workflow yet. Public REST, MCP, and CLI authoring should use the HTML compatibility lifecycle above.
Imprint templates already pin an exact immutable bundleVersionId, but runtime-template materialization remains H5-pending. promote_surface_to_imprint therefore applies only to a validated package-backed mount Surface created by internal runtime infrastructure.

Publish a Surface

Create a compatibility HTML draft.

Validate a Surface

Run the retained validator explicitly.

Bundles

Understand ordinary bundles and internal runtime packages.

Agent teams

Learn team member and admin authority.