Custom Source visualization
A Source can render your HTML, JavaScript, CSS or statically exported React/Vite
application in its Visualize tab. Its .dreamrc selects the application:
The entry is a Source-root-relative HTML file under .dreamlake/visualization/.
The application is Source content: it has no Artifact catalog entry, independent
ACL, public URL or share settings. Existing dataset/annotation configurations
continue to use their existing renderers when no custom visualization is selected.
Build and publish
Use CLI 0.121.0 or later or Python SDK 0.48.1 or later for publication.
Build a static site with relative asset URLs; for Vite, use base: './'.
Bundle dependencies locally. Server-side rendering, arbitrary backend processes,
external scripts and persistent service workers are not supported.
The publisher uploads a content-addressed generation below
.dreamlake/visualization/<digest>/, then changes only visualize in the managed
root .dreamrc, using its exact file revision. Existing configuration keys are
preserved. A failed asset upload does not switch the pointer; a concurrent config
edit is refused rather than overwritten. Old generations are retained; remove
unused ones through ordinary Source file operations when no longer needed.
Code assets are managed Source files. Dataset reads can use either managed files
or the Source's external connector, with the normal resolved-path rules. If only
an external .dreamrc exists, first copy its resolved contents into the managed
layer using a create-only write; the publisher refuses to silently shadow it.
Keep the existing configuration if a read fails or its YAML is invalid.
Limits: 1,000 files, 32 MiB per code asset and 128 MiB per published build. Symlinks and special files are refused. Entry and asset paths must be canonical relative paths; query strings, fragments, encoded path separators and traversal are not accepted. Large dataset payloads belong outside the code bundle.
Read this Source
The host injects window.dreamlake.source before your scripts run:
Paths are relative to the Source root, not to the code directory. Pass
nextCursor as cursor to continue a listing. Each read is bounded to 32 MiB;
use inclusive, explicit bytes=start-end ranges for larger objects. A connector
must support Range and return HTTP 206 for a range request. text decodes UTF-8;
json parses that text. Rejected requests are surfaced as rejected promises.
The bridge is read-only and bound to the current Source. It has no namespace, Source-ID override, write operation or arbitrary-URL fetch. The trusted host fetches data through current Source authorization, then passes bytes or projected file metadata into the isolated application. Account tokens, storage credentials and signed read URLs are not exposed to application code. It may create local Blob URLs from returned bytes for images, downloaded files or bounded media.
Permissions and isolation
Source USE controls opening and reading; managed-file edit permission controls publishing. Existing Source share-link recipients must accept the share and sign in as required by Source access. This feature adds no anonymous access path.
Code runs on an isolated content origin with a sandbox and restrictive CSP, sharing the isolation policy used by hosted Artifacts. It cannot access the app's DOM, cookies or local storage. The trusted parent handles messages only from the active frame and its exact origin. Current authority is checked for asset requests and before releasing downloaded data. Source disablement, deletion, transfer and access revocation prevent subsequent authorized reads. Already downloaded bytes cannot be recalled. The five-minute code session is renewed by the host; sessions are not an independent access grant. Source data remains a direct storage download by the trusted browser host; only bounded code assets pass through the static host.
The publisher requires the visualization-session API and configured isolated
hosting. It checks server support before uploading code. If loading fails, the
Visualize view offers Back to Browse. Runtime application failures should be
handled by the application with a useful error state.
Python and TypeScript
The TypeScript SDK accepts explicit file bytes; directory traversal stays with the caller. Both SDK publishers use the same managed code directory and revision-guarded configuration publication. Python preserves YAML values and keys; comments may be reformatted. Neither publisher creates an Artifact or modifies Source sharing.
Session API
POST /namespaces/:namespace/sources/:sourceId/visualization-session accepts
{entry} under the authenticated caller's Source authority and returns
{origin, bootstrap, entry, ttlSeconds} with Cache-Control: no-store. Bootstrap
is a short-lived bearer URL for an HttpOnly, partitioned content session; never log
or persist it. The Web host owns renewal and the read bridge; opening bootstrap
alone does not provide dataset access. Ordinary Source APIs remain the authority
for browsing, read capabilities and uploads.