@teacss/runtime

Shared stateful runtime for TeaCSS build integrations.

The runtime connects @teacss/config and @teacss/core: it loads an entry, tracks source modules, runs transformers, extracts tokens, and coordinates configuration reloads. Applications should use a concrete build adapter.

Use applyTransformerPipeline for the standard pre → default → post sequence. Use applyTransformers when an integration needs one phase. Stateful transformers may implement onModuleRemoved(id, ctx) to release module-owned registrations.

Each transformer reads its optional idFilter once per filtering decision and calls it with the transformer as this. Without an ID filter, the pipeline filter receives the current transformed code and module ID. Pipeline filtering removes the complete query or fragment suffix, including line terminators, without changing the path before the first ? or #. Transformer selection, reload snapshots, and removal cleanup ignore empty and inherited array slots, matching Core's configuration-list handling.

Reloads are transactional. A candidate configuration replays tracked sources and settles staged work before becoming live. Failure preserves the last valid runtime state while exposing current source dependencies for recovery.

Overlapping transforms reconcile to the newest source and context. Stateful transformers should key data by ctx or ctx.generator, and cleanup must be idempotent. onReload and onInvalidate return disposers. Observers are invoked synchronously in registration order. Returned promises are not awaited by reload or invalidation, but their rejections are reported as diagnostics without failing publication. Ordinary void callbacks allocate no promise. Nested cleanup retains access only to ancestor cleanups that are still active. Work outliving an ancestor must respect new locks for that ancestor's modules; inherited staged-module access and mutation notifications expire with their owner. Failures in the diagnostic sink cannot fail a committed reload or interrupt module removal cleanup after an observer fails. Reload staging and cleanup preserve large error lists, including their order and object identity, without expanding them into function arguments. Map views exposed to transformers route getOrInsert and getOrInsertComputed to their current storage, including staged and detached contexts, rather than writing into the view's unused native Map storage. Map and Set view forEach callbacks receive the requested thisArg and the view as their collection argument. Non-callable callbacks are rejected even for empty views, and a callable's own call property is not consulted. Transformer ID filters retain their transformer receiver and are read once per decision; invoking them does not consult the function's own call property. Virtual-module regexes match whole module IDs: layer suffixes cannot span path separators, and names inside queries or fragments are not filenames. The query-aware matcher includes multiline queries. Layer/query capture groups stay unchanged; the full match now includes any directory prefix.

getModuleOutput(ctx, id) reads the latest successful full-pipeline output, including output from a module currently excluded by global content filtering.

Source generation

Node integrations can share file reading and aggregation through the public subpath:

import {
  DEFAULT_SOURCE_IGNORE,
  generateSources,
  readSourceFile,
} from "@teacss/runtime/source-generation";

readSourceFile treats a missing file as empty and preserves other filesystem errors. generateSources applies configured extractors to file paths and generates directly from supplied source content. If the generator configuration is replaced, or its extractor list, extraction hooks, or environment mode changes during file extraction or generation, it re-extracts all supplied file sources before returning a result. This also covers in-place edits to prepared configurations, preventing mixed or obsolete tokens. Snapshots compare the same own extractor entries Core executes: filling an empty array slot invalidates the batch, while inherited slots remain ignored. Extraction snapshots track data-property hooks by function identity and accessor hooks by getter identity, including class-prototype getters. Snapshot checks do not invoke getters: returning a fresh bound function does not cause endless re-extraction, while replacing the getter still invalidates the batch. Changes to a hook's closed-over state require an explicit configuration update. Its Core input-validity check also stops obsolete unmatched and shortcut warnings before publication, leaving later genuine diagnostics eligible to warn. A caller-supplied isInputCurrent check is composed with the extraction snapshot; caller failures, false returns, and invalid return types are terminal even when the check also changes extraction. Only internal snapshot invalidation retries. Errors reading the caller's input-check option or validating its function type are terminal too; a valid option getter is captured once across retries. Running hooks and diagnostics already delivered before invalidation are not rolled back.

This package defines no utility vocabulary or application-facing class API.

Pre-1.0. Prefer a TeaCSS integration unless you are extending the build pipeline.