/**
 * Raw HTML's typed entry (DR-19, DR-20, L-37).
 *
 * Core writes markup unescaped in five places, the raw sinks:
 * `dangerouslySetInnerHTML`, `setHTMLUnsafe()`, `template()` and
 * `templateMany()`, `reconcile()` (the zero-build runtime's) and a `srcdoc`
 * binding. `trustedHtml(markup)` is the one way to tell them that a string is
 * markup someone vouches for. The name is the control: a reviewer, or a
 * consumer's CI (SR8's allowlist), finds every raw entry in an application by
 * searching for `trustedHtml`, and nothing else in core makes the value. (The
 * zero-build runtime's own `srcdoc` bindings, `data-bind:srcdoc` and a list
 * row's `srcdoc`, are raw entries too, which no `trustedHtml()` can reach: see
 * the runtime's coded refusal.)
 *
 * Where the browser has Trusted Types, `trustedHtml` returns a `TrustedHTML`
 * made by Forma's policy `forma`, so a page whose policy carries
 * `require-trusted-types-for 'script'; trusted-types forma forma-runtime`
 * accepts it at the sink. Elsewhere it returns a frozen stand-in that core's
 * sinks recognise and write as its markup. The policy passes markup through
 * unchanged: what `trustedHtml` is given is trusted, so the guarantee is the
 * name review and CI see, enforced at the sink by the browser.
 *
 * Every raw sink requires this value in development and production. Strings
 * and look-alikes are refused with a stable FORMA_E_* code before a DOM write.
 * This names reviewed raw content; it does not sanitize it or prevent other
 * page scripts from using the shared forma mint. The forma-runtime parser
 * accepts only browser TrustedHTML, never a string from that shared handle.
 */
/**
 * Markup vouched for by {@link 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`).
 */
interface TrustedHtml {
    /**
     * Type-level brand only: no value carries this property. It keeps a plain
     * string, or any other object, from passing for trusted markup.
     */
    readonly __formaTrustedHtml: true;
}
/**
 * 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"
 */
declare function trustedHtml(markup: string): TrustedHtml;

/** A grant an expression can need; the runtime checks `fetch` itself. */
type ExprGrant = 'dom' | 'navigate';

interface RuntimeDiagnostic {
    kind: 'handler-unsupported' | 'expression-unsupported' | 'grant-denied' | 'markup-refused';
    expr: string;
    reason: string;
    /** Stable machine-readable cause, e.g. `FORMA_E_METHOD_DENIED`. */
    code: string;
    count: number;
    firstSeenAt: number;
    lastSeenAt: number;
    /** Under a tiered mount (FORMA-128): the mount's name and tier. */
    mount?: string;
    tier?: MountTier;
    /** For `grant-denied`: the grant the mount did not give. */
    grant?: 'fetch' | ExprGrant;
}
/**
 * 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.
 */
type MountTier = 'compiled' | 'reviewed' | 'unreviewed';
/** The methods `data-fetch` sends. */
type FetchMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
/** What a mount's `data-fetch` may send. */
interface FetchGrant {
    /** Methods it may send. Default: `['GET']`. */
    readonly methods?: readonly FetchMethod[];
    /**
     * 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.
     */
    readonly paths: readonly string[];
    /** Whether the user's cookies go with a same-origin request. Default: false. */
    readonly cookies?: boolean;
    /** Abort a request after this many milliseconds: at most, and by default, 30,000. */
    readonly timeoutMs?: number;
}
/**
 * A mount's grants (DR-15). A grant absent from the object is not given;
 * an absent object also grants nothing (FORMA-108).
 */
interface MountGrants {
    /** `data-fetch`. */
    readonly fetch?: FetchGrant;
    /** The page beyond the mount root: elements outside it, and selectors that ask about them. */
    readonly dom?: boolean;
    /** `click()`, which can follow a link or submit a form in the user's session. */
    readonly navigate?: boolean;
}
/** A mount's configuration. It comes only from its call: no script tag or global reaches it. */
interface MountConfig {
    /** How diagnostics and the grant report name the mount. Default: `#<root id>`, else `mount-<n>`. */
    readonly name?: string;
    /** The interpreter's step budget per task for this mount. Default: 100,000. */
    readonly exprBudget?: number;
    /** Expression diagnostics; a denied grant is reported regardless. Default: true. */
    readonly diagnostics?: boolean;
    /** CSS containment hints on `[data-forma-contain]` elements under the root. Default: false. */
    readonly autoContainment?: boolean;
}
/** The third argument of `mountMarkup()`. */
interface MountOptions {
    readonly tier: MountTier;
    readonly grants?: MountGrants;
    readonly config?: MountConfig;
}
/**
 * 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.
 */
interface GrantReport {
    fetch?: {
        methods: FetchMethod[];
        paths: string[];
        cookies: boolean;
    };
    dom?: true;
    navigate?: true;
}
/** What `mountMarkup()` returns. */
interface MountHandle {
    readonly root: Element;
    readonly tier: MountTier;
    readonly name: string;
    /** Render new markup into the root: reconciled, so scopes whose shape is unchanged keep their state. */
    update(markup: TrustedHtml): void;
    /** Dispose every binding of the mount and empty its root. */
    unmount(): void;
    /** Development builds: the grants used so far. Production builds: `null`. */
    grantsUsed(): GrantReport | null;
}
/** Yield control to keep the main thread responsive during large batches. */
declare function yieldToMain(): Promise<void>;
interface ContainmentHintsOptions {
    selector?: string;
    contain?: string;
    contentVisibility?: string;
    containIntrinsicSize?: string;
    skipIfAlreadySet?: boolean;
}
/** Apply CSS containment hints to opt-in containers for lower layout/paint cost. */
declare function applyContainmentHints(root?: ParentNode, options?: ContainmentHintsOptions): number;
/** Runtime diagnostics captured while parsing/binding templates. */
declare function getDiagnostics(): RuntimeDiagnostic[];
/** Clear runtime diagnostics collected so far. */
declare function clearDiagnostics(): void;
interface ScopeDescriptor {
    element: Element;
    id: string;
    values: Record<string, {
        value: unknown;
        type: string;
    }>;
    initialJSON: string;
}
/**
 * DevTools: enumerate all active scopes and their current signal values.
 * Only called when the State Inspector panel is open — zero overhead otherwise.
 */
declare function getScopes(): ScopeDescriptor[];
/**
 * DevTools: set a state value on a specific scope element.
 * Triggers normal reactive effects (data-show, data-text, etc.).
 */
declare function setScopeValue(element: Element, key: string, value: unknown): void;
/**
 * DevTools: reset all values on a scope to their initial JSON state.
 */
declare function resetScope(element: Element): void;
/**
 * 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"
 */
declare function mountMarkup(root: Element, markup: TrustedHtml, options: MountOptions): MountHandle;

export { type FetchGrant, type FetchMethod, type GrantReport, type MountConfig, type MountGrants, type MountHandle, type MountOptions, type MountTier, type TrustedHtml, applyContainmentHints, clearDiagnostics, getDiagnostics, getScopes, mountMarkup, resetScope, setScopeValue, trustedHtml, yieldToMain };