# @getforma/core/runtime-hardened

The hardened HTML runtime entry point and its published mount contract.

The published hardened runtime exposes the explicit tiered mount API. trustedHtml names trusted raw markup; it is not a sanitizer. Configure your response policy and grants deliberately.

Published declaration: [@getforma/core@3.0.0](https://unpkg.com/@getforma/core@3.0.0/dist/runtime-hardened.d.ts).

## Values and functions

### applyContainmentHints

Function export

```ts
declare function applyContainmentHints(root?: ParentNode, options?: ContainmentHintsOptions): number;
```

Apply CSS containment hints to opt-in containers for lower layout/paint cost.

Related declarations: [`ContainmentHintsOptions`](/docs/3.0/api-runtime-hardened/#type-ContainmentHintsOptions)

### clearDiagnostics

Function export

```ts
declare function clearDiagnostics(): void;
```

Clear runtime diagnostics collected so far.

### getDiagnostics

Function export

```ts
declare function getDiagnostics(): RuntimeDiagnostic[];
```

Runtime diagnostics captured while parsing/binding templates.

Related declarations: [`RuntimeDiagnostic`](/docs/3.0/api-runtime-hardened/#type-RuntimeDiagnostic)

### getScopes

Function export

```ts
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`](/docs/3.0/api-runtime-hardened/#type-ScopeDescriptor)

### mountMarkup

Function export

```ts
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`, `reviewed` or `unreviewed` (DR-14). An
  `unreviewed` mount 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) and `navigate`
  (`click()`). A grant the object leaves out is not given; leaving out the
  whole object also gives none. Every
  denial is a coded `formajs:diagnostic` (`kind: 'grant-denied'`).
- **`$el`, `$event`, `$refs`** reach only the root's descendants: a hop
  to any other element, or a selector asking about one, needs `dom` (L-36).
- **`data-fetch`** answered with a status outside 200-299 writes an error
  to its `error:` 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`](/docs/3.0/api-runtime-hardened/#symbol-MountHandle), [`MountOptions`](/docs/3.0/api-runtime-hardened/#symbol-MountOptions), [`TrustedHtml`](/docs/3.0/api-runtime-hardened/#symbol-TrustedHtml)

### resetScope

Function export

```ts
declare function resetScope(element: Element): void;
```

DevTools: reset all values on a scope to their initial JSON state.

### setScopeValue

Function export

```ts
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

Function export

```ts
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.

```ts
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`](/docs/3.0/api-runtime-hardened/#symbol-TrustedHtml)

### yieldToMain

Function export

```ts
declare function yieldToMain(): Promise<void>;
```

Yield control to keep the main thread responsive during large batches.

## Exported types

### FetchGrant

Interface export

```ts
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`](/docs/3.0/api-runtime-hardened/#symbol-FetchMethod)

**`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 alias export

```ts
type FetchMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
```

The methods `data-fetch` sends.

### GrantReport

Interface export

```ts
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`](/docs/3.0/api-runtime-hardened/#symbol-FetchMethod)

### MountConfig

Interface export

```ts
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.

**`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 export

```ts
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`](/docs/3.0/api-runtime-hardened/#symbol-FetchGrant)

**`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 export

```ts
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`](/docs/3.0/api-runtime-hardened/#symbol-GrantReport), [`MountTier`](/docs/3.0/api-runtime-hardened/#symbol-MountTier), [`TrustedHtml`](/docs/3.0/api-runtime-hardened/#symbol-TrustedHtml)

**`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 export

```ts
interface MountOptions {
    readonly tier: MountTier;
    readonly grants?: MountGrants;
    readonly config?: MountConfig;
}
```

The third argument of `mountMarkup()`.

Related declarations: [`MountConfig`](/docs/3.0/api-runtime-hardened/#symbol-MountConfig), [`MountGrants`](/docs/3.0/api-runtime-hardened/#symbol-MountGrants), [`MountTier`](/docs/3.0/api-runtime-hardened/#symbol-MountTier)

### MountTier

Type alias export

```ts
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 export

```ts
interface TrustedHtml {
    readonly __formaTrustedHtml: true;
}
```

Markup vouched for by [trustedHtml](/docs/3.0/api-runtime-hardened/#symbol-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`).

**`__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

### ContainmentHintsOptions

Referenced type; not separately importable from this entry point.

```ts
interface ContainmentHintsOptions {
    selector?: string;
    contain?: string;
    contentVisibility?: string;
    containIntrinsicSize?: string;
    skipIfAlreadySet?: boolean;
}
```



### ExprGrant

Referenced type; not separately importable from this entry point.

```ts
type ExprGrant = 'dom' | 'navigate';
```

A grant an expression can need; the runtime checks `fetch` itself.

### RuntimeDiagnostic

Referenced type; not separately importable from this entry point.

```ts
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`](/docs/3.0/api-runtime-hardened/#type-ExprGrant), [`MountTier`](/docs/3.0/api-runtime-hardened/#symbol-MountTier)

**`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

Referenced type; not separately importable from this entry point.

```ts
interface ScopeDescriptor {
    element: Element;
    id: string;
    values: Record<string, {
        value: unknown;
        type: string;
    }>;
    initialJSON: string;
}
```



## Other entry points

[@getforma/core](/docs/3.0/api-core/) · [@getforma/core/runtime](/docs/3.0/api-runtime/) · [@getforma/core/runtime-csp](/docs/3.0/api-runtime-csp/) · [@getforma/core/tc39](/docs/3.0/api-tc39/) · [@getforma/core/http](/docs/3.0/api-http/) · [@getforma/core/storage](/docs/3.0/api-storage/) · [JSX namespace](/docs/3.0/api-jsx/)