@fictjs/runtime

Fict reactive runtime

Usage

npm install @fictjs/runtime
# or
yarn add @fictjs/runtime

You can visit Fict for more documentation.

Package Surfaces

• @fictjs/runtime: low-level public runtime API. It does not export compiler macros.
• @fictjs/runtime/advanced: advanced reactive primitives and escape hatches.
• @fictjs/runtime/loader: SSR/resume loader entrypoint.
• @fictjs/runtime/internal: compiler ABI for generated code only; do not import by hand.

Reactive Getter Contract

Runtime value paths do not infer reactivity from function arity. A plain zero-argument function is treated as a function value/callback. Use reactive(fn) from @fictjs/runtime/advanced when manually authoring a low-level reactive getter; compiler-generated getters are marked automatically.

Dev/Prod Mode Contract (__DEV__)

Runtime dev-only branches use this precedence:

1. __DEV__ (recommended, compile-time constant)
2. Fallback: process.env.NODE_ENV !== 'production' when process exists

For browser builds, define __DEV__ explicitly in your bundler for predictable DX and dead-code elimination:

• development: __DEV__ = true
• production: __DEV__ = false

Multi-Document Contract (iframe / foreign Document)

@fictjs/runtime supports rendering into containers owned by non-global documents (for example, elements from an iframe document). Runtime-created nodes, markers, and fragments are created from the active ownerDocument.

Supported contract:

• render() into a container from another Document
• list/conditional/suspense marker creation in that container's ownerDocument
• node insertion paths that rely on runtime-created nodes

Important caveat:

• If user code manually returns nodes created from a different document and inserts them into another document tree, runtime may fall back to adoptNode() or importNode() during insertion/reordering. importNode() clones DOM nodes and does not preserve JS-side expando state or imperative listeners attached outside of Fict's binding flow.

Recommendation:

• Create DOM nodes using the target container's ownerDocument (or let Fict create nodes) when working across iframe/foreign-document boundaries.

Runtime Stability Stress

Run stress scenarios for runtime correctness and reliability:

pnpm --dir packages/runtime test:stress

Long profile:

pnpm --dir packages/runtime test:stress:long

Root aliases are also available:

pnpm stress:runtime
pnpm stress:runtime:long

Environment knobs:

• FICT_RUNTIME_SOAK_ITERS
• FICT_RUNTIME_CHURN_CYCLES
• FICT_RUNTIME_CHURN_LIST_SIZE
• FICT_RUNTIME_LEAK_ROUNDS
• FICT_RUNTIME_LEAK_EFFECTS_PER_ROUND
• FICT_RUNTIME_MAX_HEAP_GROWTH_BYTES
• FICT_RUNTIME_BACKPRESSURE_UPDATES
• FICT_RUNTIME_BACKPRESSURE_TIMEOUT_MS
• FICT_RUNTIME_MAX_DRAIN_LATENCY_MS