This is the data-forma-* HTML runtime entry point. Call mountMarkup explicitly with reviewed markup, a tier and deliberate grants. It is distinct from mounting a TypeScript component or activating compiler-declared islands.
Read the usage guide or all entry points.
18 exports · published 3.0.0 declarations
import { applyContainmentHints } from '@getforma/core/runtime';Values and functions
applyContainmentHints#
declare function applyContainmentHints(root?: ParentNode, options?: ContainmentHintsOptions): number;Apply CSS containment hints to opt-in containers for lower layout/paint cost.
Related declarations: ContainmentHintsOptions
clearDiagnostics#
declare function clearDiagnostics(): void;Clear runtime diagnostics collected so far.
getDiagnostics#
declare function getDiagnostics(): RuntimeDiagnostic[];Runtime diagnostics captured while parsing/binding templates.
Related declarations: RuntimeDiagnostic
getScopes#
declare function getScopes(): ScopeDescriptor[];DevTools: enumerate all active scopes and their current signal values. Only called when the State Inspector panel is open — zero overhead otherwise.
Related declarations: ScopeDescriptor
mountMarkup#
declare function mountMarkup(root: Element, markup: TrustedHtml, options: MountOptions): MountHandle;Mount markup under root in a tier, with grants (FORMA-128; decision
brief DR-14, DR-15, L-36, L-47). The runtime binds only under the root it is
handed, never by watching body, and the mount takes its configuration
only from this call.
- Tier.
compiled,reviewedorunreviewed(DR-14). Anunreviewedmount takes no grants and refuses to mount on any origin but an opaque one: content nobody reviewed renders only in the preview frame. - Grants (DR-15):
fetch(methods, path prefixes, cookies or not, a timeout up to 30 s),dom(the page beyond the root) andnavigate(click()). A grant the object leaves out is not given; leaving out the whole object also gives none. Every denial is a codedformajs:diagnostic(kind: 'grant-denied'). $el,$event,$refsreach only the root's descendants: a hop to any other element, or a selector asking about one, needsdom(L-36).data-fetchanswered with a status outside 200-299 writes an error to itserror:target, never data.- Development builds keep a report of the grants the mount used
(
grantsUsed()), so a reviewer writes grants from observed use.
The shared responsibility (v2 10.1): the application chooses the tier and passes grants only for content whose hash matches what its reviewer approved (L-47); Forma enforces what the mount grants. DOM binding begins only at this call and subsequent handle.update calls; handle.unmount ends it. An initial binding failure disposes partial and completed scopes before it rethrows. Already written DOM may remain inert; the root can be mounted again.
Verified by: src/tests/runtime-tiered-mount.test.ts > "binds only under the root it is handed: markup injected outside it stays unbound" Verified by: src/tests/runtime-tiered-mount.test.ts > "an unreviewed mount refuses any origin but an opaque one, and any grant" Verified by: src/tests/runtime-tiered-mount.test.ts > "the development report lists exactly the grants a fixture widget used"
Related declarations: MountHandle, MountOptions, TrustedHtml
resetScope#
declare function resetScope(element: Element): void;DevTools: reset all values on a scope to their initial JSON state.
setScopeValue#
declare function setScopeValue(element: Element, key: string, value: unknown): void;DevTools: set a state value on a specific scope element. Triggers normal reactive effects (data-show, data-text, etc.).
trustedHtml#
declare function trustedHtml(markup: string): TrustedHtml;Vouch for markup as HTML a raw sink may write unescaped: the one raw
constructor in TypeScript (DR-19), so a search for its name finds every raw
entry. Nothing is sanitised: pass only markup you control, never a value an
end user supplied.
h('div', { dangerouslySetInnerHTML: { __html: trustedHtml(renderedMarkdown) } });Verified by: src/dom/tests/trusted-html.test.ts > "every raw sink writes a trustedHtml() value without a warning, and the DOM holds its markup" Verified by: src/dom/tests/trusted-html.test.ts > "trustedHtml() returns a TrustedHTML from the forma policy where the browser has Trusted Types"
Related declarations: TrustedHtml
yieldToMain#
declare function yieldToMain(): Promise<void>;Yield control to keep the main thread responsive during large batches.
Exported types
FetchGrant#
interface FetchGrant {
readonly methods?: readonly FetchMethod[];
readonly paths: readonly string[];
readonly cookies?: boolean;
readonly timeoutMs?: number;
}What a mount's data-fetch may send.
Related declarations: FetchMethod
Member notes
methods
Methods it may send. Default: ['GET'].
paths
Where it may send them: path prefixes on the page's own origin
('/api/widgets/'), or absolute http(s): prefixes on another
('https://api.example.com/v1/'). A prefix without a trailing slash
matches that path and the paths below it, never a sibling that merely
starts with the same characters.
cookies
Whether the user's cookies go with a same-origin request. Default: false.
timeoutMs
Abort a request after this many milliseconds: at most, and by default, 30,000.
FetchMethod#
type FetchMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';The methods data-fetch sends.
GrantReport#
interface GrantReport {
fetch?: {
methods: FetchMethod[];
paths: string[];
cookies: boolean;
};
dom?: true;
navigate?: true;
}The grants a mount has used, written as grants, so a reviewer can approve
one as the widget's grant set (DR-15, L-36). Only the grants used appear; a
fetch lists the methods and exact paths it sent and whether the user's
cookies went with a request.
Related declarations: FetchMethod
MountConfig#
interface MountConfig {
readonly name?: string;
readonly exprBudget?: number;
readonly diagnostics?: boolean;
readonly autoContainment?: boolean;
}A mount's configuration. It comes only from its call: no script tag or global reaches it.
Member notes
name
How diagnostics and the grant report name the mount. Default: #<root id>, else mount-<n>.
exprBudget
The interpreter's step budget per task for this mount. Default: 100,000.
diagnostics
Expression diagnostics; a denied grant is reported regardless. Default: true.
autoContainment
CSS containment hints on [data-forma-contain] elements under the root. Default: false.
MountGrants#
interface MountGrants {
readonly fetch?: FetchGrant;
readonly dom?: boolean;
readonly navigate?: boolean;
}A mount's grants (DR-15). A grant absent from the object is not given; an absent object also grants nothing (FORMA-108).
Related declarations: FetchGrant
Member notes
fetch
data-fetch.
dom
The page beyond the mount root: elements outside it, and selectors that ask about them.
navigate
click(), which can follow a link or submit a form in the user's session.
MountHandle#
interface MountHandle {
readonly root: Element;
readonly tier: MountTier;
readonly name: string;
update(markup: TrustedHtml): void;
unmount(): void;
grantsUsed(): GrantReport | null;
}What mountMarkup() returns.
Related declarations: GrantReport, MountTier, TrustedHtml
Member notes
update
Render new markup into the root: reconciled, so scopes whose shape is unchanged keep their state.
unmount
Dispose every binding of the mount and empty its root.
grantsUsed
Development builds: the grants used so far. Production builds: null.
MountOptions#
interface MountOptions {
readonly tier: MountTier;
readonly grants?: MountGrants;
readonly config?: MountConfig;
}The third argument of mountMarkup().
Related declarations: MountConfig, MountGrants, MountTier
MountTier#
type MountTier = 'compiled' | 'reviewed' | 'unreviewed';DR-14's three tiers. compiled: markup the application's own build made.
reviewed: a directive widget the application reviewed and admitted, on its
origin, with the grants its reviewer wrote. unreviewed: content nobody
reviewed, which mounts only in an opaque-origin document (the preview frame)
and with no grants. Which tier a mount uses is the application's decision.
TrustedHtml#
interface TrustedHtml {
readonly __formaTrustedHtml: true;
}Markup vouched for by trustedHtml: a browser TrustedHTML where the
browser has Trusted Types, else Forma's frozen stand-in. Every raw sink takes
only this value. A TrustedHTML from an
application's own policy is accepted at run time too; TypeScript sees it as
this type only through a cast (value as unknown as TrustedHtml).
Member notes
__formaTrustedHtml
Type-level brand only: no value carries this property. It keeps a plain string, or any other object, from passing for trusted markup.
Referenced declaration types
These types appear in the published signatures but are not separate named exports from this entry point. They are shown to explain the contract, not as additional import paths.
ContainmentHintsOptions#
interface ContainmentHintsOptions {
selector?: string;
contain?: string;
contentVisibility?: string;
containIntrinsicSize?: string;
skipIfAlreadySet?: boolean;
}ExprGrant#
type ExprGrant = 'dom' | 'navigate';A grant an expression can need; the runtime checks fetch itself.
RuntimeDiagnostic#
interface RuntimeDiagnostic {
kind: 'handler-unsupported' | 'expression-unsupported' | 'grant-denied' | 'markup-refused';
expr: string;
reason: string;
code: string;
count: number;
firstSeenAt: number;
lastSeenAt: number;
mount?: string;
tier?: MountTier;
grant?: 'fetch' | ExprGrant;
}Related declarations: ExprGrant, MountTier
Member notes
code
Stable machine-readable cause, e.g. FORMA_E_METHOD_DENIED.
mount
Under a tiered mount (FORMA-128): the mount's name and tier.
grant
For grant-denied: the grant the mount did not give.
ScopeDescriptor#
interface ScopeDescriptor {
element: Element;
id: string;
values: Record<string, {
value: unknown;
type: string;
}>;
initialJSON: string;
}Other entry points
@getforma/core · @getforma/core/runtime-hardened · @getforma/core/runtime-csp · @getforma/core/tc39 · @getforma/core/http · @getforma/core/storage · JSX namespace