# Pages

Pages are public forms, portals and HTML pages that live inside a Space and are
shared through links. A page has a draft and immutable published versions.
Flow: pages.create (draft) -> pages.update_draft (definition, name, settings;
published links keep their frozen version) -> pages.publish (new version,
the response lists the inputs and outputs) -> pages.links_create (share link
with optional password, email gate, expiry, visit limit) -> hand the link to
the user. pages.get shows draft, current version and counters;
pages.html_get returns the HTML artifact of an HTML page.

Blocks pages show data with two block types: records (key, record_type_id,
field_ids, optional view_key, base_filter, sort, page_size, allow_export) and
chart (key, record_chart_id of a saved chart, optional days and height sm|md).
Both are checked against the space on every save; pages.publish freezes the
schema version and, for charts, the effective spec, so later chart edits never
change what a published link shows.

HTML pages (kind 'html') are a self-contained document (max 5 MiB) rendered
in a sandboxed frame: no network, no external scripts, styles or fonts, only
inline code and data: URLs. The document talks to the page through
window.adlass, every call returns a Promise: getContext() -> {title, locale,
preview, viewer, fields, submission_mode, can_download, data: [{key, type}]};
records(key, {cursor, limit, q}) -> {fields, items, next_cursor}; chart(key,
{days}) -> {columns, rows, truncated, warnings, window, display}; submit(values);
upload(file, key); download(assetKey); track(event). records and chart only
accept keys declared in definition.data (same block shapes as above); submit
validates against definition.fields. Chart rows carry numbers as strings and
dates as ISO days, columns carry role x|series|measure and labels; display is
the chart's title, type and format, enough to draw it (see the records_charts
guide). settings.chrome 'none' hides the header bar so the document owns the
whole viewport. The author of an HTML page is trusted like a space manager: the
bridge limits what the document can read, not what a link inside it does with
it; publishing stays a human decision.

Drafts may be incomplete (empty keys, labels or title); completeness is checked
by pages.publish, which returns field paths. Download blocks name a slot via
asset_key and may stay unbound: visitors then see the download as not yet
available. pages.assets_set (or the assets field of pages.update_draft) binds a
document of the Space to a slot; after binding run pages.publish and
pages.links_retarget, because existing links stay pinned to their version.

Links: pages.links_list, pages.links_get (url, managers only),
pages.links_update (label, expiry, gates, status ACTIVE or DISABLED),
pages.links_rotate (new token, old URL stops working), pages.links_retarget
(another published version), pages.links_revoke (irreversible).

Results: pages.submissions_list and pages.submissions_get return visitor
answers following the version's output schema; pages.submissions_set_status
marks them processed. pages.visits_list and pages.stats report traffic.
pages.archive disables all links (pages.publish restores); pages.delete is
irreversible.