@elastic/distillate 0.1.0 → 0.2.0

package/docs/reference/api/testing.md

@@ -4,7 +4,7 @@
 
 ### VarInvariantViolation [#varinvariantviolation]
 
-Defined in: [var\_invariant.ts:14](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/var_invariant.ts#L14)
+Defined in: [var\_invariant.ts:14](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/var_invariant.ts#L14)
 
 A `var(...)` whose custom property is never declared in the same CSS text.
 
@@ -12,8 +12,8 @@ A `var(...)` whose custom property is never declared in the same CSS text.
 
 | Property | Modifier | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ | ------ |
-| $$$context$$$ `context` | `readonly` | `string` | Surrounding CSS text for error reporting. | [var\_invariant.ts:18](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/var_invariant.ts#L18) |
-| $$$reference$$$ `reference` | `readonly` | `string` | The undeclared custom property name (e.g. `--aui-color-bg`). | [var\_invariant.ts:16](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/var_invariant.ts#L16) |
+| $$$context$$$ `context` | `readonly` | `string` | Surrounding CSS text for error reporting. | [var\_invariant.ts:18](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/var_invariant.ts#L18) |
+| $$$reference$$$ `reference` | `readonly` | `string` | The undeclared custom property name (e.g. `--aui-color-bg`). | [var\_invariant.ts:16](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/var_invariant.ts#L16) |
 
 ## Functions
 
@@ -23,7 +23,7 @@ A `var(...)` whose custom property is never declared in the same CSS text.
 function assertVarRefsHaveDeclarations(css): void;
 ```
 
-Defined in: [var\_invariant.ts:135](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/var_invariant.ts#L135)
+Defined in: [var\_invariant.ts:135](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/var_invariant.ts#L135)
 
 Throws if any `var(...)` in `css` has no matching custom-property declaration.
 
@@ -49,7 +49,7 @@ If any reference has no declaration in the same text.
 function findVarRefViolations(css): readonly VarInvariantViolation[];
 ```
 
-Defined in: [var\_invariant.ts:109](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/var_invariant.ts#L109)
+Defined in: [var\_invariant.ts:109](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/var_invariant.ts#L109)
 
 Returns all `var(...)` references whose custom property is never declared in `css`.
 
@@ -75,7 +75,7 @@ function tokenTreeDts(
 ): string;
 ```
 
-Defined in: [testing.ts:23](https://github.com/elastic/distillate/blob/f131912edadeb90a659ad22ee215412bedb1394d/src/testing.ts#L23)
+Defined in: [testing.ts:23](https://github.com/elastic/distillate/blob/d1dccb0eb5372d5984331c21603220340752a304/src/testing.ts#L23)
 
 Emits a TypeScript `interface` for a derived token tree, for Monaco extraLib text.
 

package/docs/reference/entry-points.md

@@ -31,13 +31,16 @@ import {
 | `css` / `decls` | runtime | Handle and declaration templates. Also on the `createStyleModule` factory argument. |
 | `rule` / `media` / `container` / `variants` / `mapDomain` | runtime | Root-entry authoring helpers. `mapDomain` has no collector side effect. |
 | `combineClassNames` | runtime | `context.resolveClassName(...handles)`. |
-| `StylesCollector` | runtime | Class; `artifactCollector` / `stylesheetCollector` return instances. |
+| `StylesCollector` | runtime | Class; `artifactCollector` / `stylesheetCollector` / `liveCollection` return or wrap instances. `subscribe` reports growth. |
+| `createDomSink` | runtime | One `<style>` element in `document.head` or a given `parent` (e.g. a `ShadowRoot`), flushed per turn. Also exported from `./emotion`. |
 | `renderStyles` | runtime | Unbound renderer; prefer `distillery.renderStyles`. |
 | `createStyleNameResolver` | runtime | Standalone compact/readable name map. |
 | `StyleRegistry` | runtime | Module registry class. |
 | `Distillery` / `DistilleryOptions` / `DistilleryEnvironment` / `ThemeVarDefinition` | type | Bindings. |
 | `TokensOf` / `ValuesOf` / `PathsOf` / `ThemeTree` / `SchemePair` / `ThemeVariation` / `ResolvedThemeVariation` / `ThemeAlternate` / `RenderStylesOptions` | type | Theme derivation and render selection. |
 | `StyleHandle` / `StylesModule` / `StyleNameResolver` / `StyleNameMode` / `StyleTarget` | type | Handles, modules, naming. |
+| `LiveCollection` / `LiveCollectionOptions` | type | `distillery.liveCollection` result and options. |
+| `StyleSink` / `CreateDomSinkOptions` / `DocumentLike` / `StyleElementLike` / `StyleParentLike` | type | Sink surface. |
 
 ### Key signatures
 
@@ -57,6 +60,11 @@ distillery.stylesheetCollector(
   names?: 'compact' | 'readable',
   options?: { warn?: (message: string) => void }
 ): StylesCollector;
+distillery.liveCollection(options?: {
+  sink?: StyleSink;
+  render?: RenderStylesOptions;
+  warn?: (message: string) => void;
+}): LiveCollection; // { collector, resolveClassName(...handles), css() }
 distillery.renderStyles(
   collector: StylesCollector,
   resolver?: StyleNameResolver,
@@ -66,6 +74,12 @@ distillery.renderStyles(
 collector.use(module | entry | entries): void;
 collector.useHandles(handles: readonly StyleHandle[]): readonly StyleHandle[];
 collector.createResolver(): StyleNameResolver;
+collector.subscribe(listener: () => void): () => void; // once per outermost call that grows
+createDomSink(options: {
+  document: DocumentLike;
+  parent?: StyleParentLike;
+  schedule?: (flush: () => void) => void;
+}): StyleSink;
 ```
 
 Field-level environment types: [Environment](environment.md).
@@ -88,13 +102,13 @@ const { css, cx, injectGlobal, stylesheet, globalModules } = createEmotion(
 | Export | Kind | Role |
 | ------ | ---- | ---- |
 | `createEmotion` | runtime | `css` / `cx` / `injectGlobal` over the distillery registry. |
-| `createDomSink` | runtime | One `<style>` element, flushed per turn. |
+| `createDomSink` | runtime | One `<style>` element, flushed per turn. Re-exported from the root entry. |
 | `Emotion` / `EmotionCss` / `CreateEmotionOptions` / `StyleSink` | type | Return and option types. |
-| `CreateDomSinkOptions` / `DocumentLike` / `StyleElementLike` | type | DOM sink surface. |
+| `CreateDomSinkOptions` / `DocumentLike` / `StyleElementLike` / `StyleParentLike` | type | DOM sink surface. Same as the root entry. |
 
 ```ts
 createEmotion(distillery, options?: { sink?: StyleSink }): Emotion;
-createDomSink(options: { document: DocumentLike; schedule?: (flush: () => void) => void }): StyleSink;
+createDomSink(options: { document: DocumentLike; parent?: StyleParentLike; schedule?: (flush: () => void) => void }): StyleSink;
 ```
 
 The string form of a `css` template is readable and does not collect. The wrapper is still a `StyleHandle` for `useHandles` / `resolveClassName`.

package/docs/reference/okf-map.md

@@ -8,7 +8,7 @@ description: Generated map of the Distillate OKF concept graph.
 Generated from `.okf/distillate` by `pnpm okf:map`. Do not edit by hand.
 
 - Concepts: 19
-- Links: 29
+- Links: 30
 - Isolated concepts: 0
 
 ## Graph
@@ -44,6 +44,7 @@ flowchart LR
     concepts_ordering --> concepts_naming
     concepts_tokens --> concepts_distillery
     concepts_tokens --> reference_public_contract
+    entry_points_emotion --> entry_points_root
     entry_points_emotion --> playbooks_migrate_from_emotion
     entry_points_root --> entry_points_emotion
     entry_points_root --> entry_points_testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elastic/distillate",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Theme-agnostic CSS style engine: typed authoring with dependency capture, render-driven reachability collection, and dual readable/compact output targets. One runtime dependency: stylis.",
   "license": "Elastic-2.0",
   "author": "Elastic",

package/src/collector.ts

@@ -113,6 +113,9 @@ export class StylesCollector {
   private readonly handles = new Map<string, StyleHandle>();
   private readonly themeDeps = new Set<string>();
   private readonly varDeps = new Set<ContextualVarPath>();
+  private readonly listeners = new Set<() => void>();
+  private depth = 0;
+  private dirty = false;
 
   constructor({
     target,
@@ -138,6 +141,12 @@ export class StylesCollector {
    * @param value Module (all non-variant entries), a single entry, or an array of entries.
    */
   use(value: StylesModule | StyleEntry | readonly StyleEntry[]): void {
+    this.batch(() => this.useValue(value));
+  }
+
+  private useValue(
+    value: StylesModule | StyleEntry | readonly StyleEntry[]
+  ): void {
     if (isReadonlyArray(value)) {
       value.forEach((entry) => this.use(entry));
       return;
@@ -155,7 +164,7 @@ export class StylesCollector {
         if (entry.kind === 'handle' && !this.retainHandle(entry)) {
           continue;
         }
-        this.entries.set(entryKey(entry), entry);
+        this.setEntry(entry);
         if (entry.kind === 'handle' || entry.kind === 'rule') {
           this.addDeclarationDeps(entry.declarations);
         } else {
@@ -171,7 +180,7 @@ export class StylesCollector {
         if (!this.retainHandle(handle)) {
           continue;
         }
-        this.handles.set(handle.key, handle);
+        this.setHandle(handle);
       }
       return;
     }
@@ -185,69 +194,89 @@ export class StylesCollector {
    * @param module Module whose entries should all be collected.
    */
   useAllEntries(module: StylesModule): void {
-    for (const entry of module.entries) {
-      if (entry.kind === 'handle' && !this.retainHandle(entry)) {
-        continue;
+    this.batch(() => {
+      for (const entry of module.entries) {
+        if (entry.kind === 'handle' && !this.retainHandle(entry)) {
+          continue;
+        }
+        this.setEntry(entry);
       }
-      this.entries.set(entryKey(entry), entry);
-    }
-    for (const handle of module.handleList) {
-      if (!this.retainHandle(handle)) {
-        continue;
+      for (const handle of module.handleList) {
+        if (!this.retainHandle(handle)) {
+          continue;
+        }
+        this.setHandle(handle);
       }
-      this.handles.set(handle.key, handle);
-    }
-    module.themeDeps.forEach((path) => this.themeDeps.add(path));
-    module.varDeps.forEach((path) => this.varDeps.add(path));
+      this.addDeps(module.themeDeps, module.varDeps);
+    });
   }
 
   /**
    * Collects handles and auto-includes rules whose selector deps are all present.
    *
-   * Media blocks include only inner rules whose deps are met.
+   * Media blocks gain inner rules whose deps are met and keep rules already collected.
    *
    * @param handles Handles resolved during this render pass (e.g. from `resolveClassName`).
    * @returns Handles that were retained. Empty untargeted handles are omitted in compact mode.
    */
   useHandles(handles: readonly StyleHandle[]): readonly StyleHandle[] {
-    const retained: StyleHandle[] = [];
-    for (const handle of handles) {
-      if (!this.retainHandle(handle)) {
-        continue;
-      }
-      retained.push(handle);
-      if (this.handles.has(handle.key)) {
-        continue;
-      }
-      this.entries.set(entryKey(handle), handle);
-      this.handles.set(handle.key, handle);
-      this.addDeclarationDeps(handle.declarations);
-    }
-    for (const handle of retained) {
-      const module = this.registry.module(handle.moduleName);
-      if (!module) {
-        continue;
+    return this.batch(() => {
+      const retained: StyleHandle[] = [];
+      for (const handle of handles) {
+        if (!this.retainHandle(handle)) {
+          continue;
+        }
+        retained.push(handle);
+        if (this.handles.has(handle.key)) {
+          continue;
+        }
+        this.setEntry(handle);
+        this.setHandle(handle);
+        this.addDeclarationDeps(handle.declarations);
       }
-      for (const dependent of dependentEntries(module, handle.key)) {
-        this.tryActivateDependent(dependent);
+      for (const handle of retained) {
+        const module = this.registry.module(handle.moduleName);
+        if (!module) {
+          continue;
+        }
+        for (const dependent of dependentEntries(module, handle.key)) {
+          this.tryActivateDependent(dependent);
+        }
       }
-    }
-    return retained;
+      return retained;
+    });
   }
 
   /** Collects `auto` rules on `module` whose every selector dependency is already collected. */
   useRulesWhenDepsMet(module: StylesModule): void {
-    for (const entry of module.entries) {
-      if (entry.kind !== 'rule') {
-        continue;
-      }
-      if (this.entries.has(entryKey(entry))) {
-        continue;
-      }
-      if (this.allDepsMet(entry.dependsOn)) {
-        this.addEntry(entry);
+    this.batch(() => {
+      for (const entry of module.entries) {
+        if (entry.kind !== 'rule') {
+          continue;
+        }
+        if (this.entries.has(entryKey(entry))) {
+          continue;
+        }
+        if (this.allDepsMet(entry.dependsOn)) {
+          this.addEntry(entry);
+        }
       }
-    }
+    });
+  }
+
+  /**
+   * Calls `listener` after a public mutation adds an entry, handle, theme var, or contextual var.
+   *
+   * Fires at most once per outermost call; nested calls such as `use([a, b])` batch into it.
+   *
+   * @param listener Called with no arguments after the collection grows.
+   * @returns Unsubscribes `listener`.
+   */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
   }
 
   private tryActivateDependent(entry: StyleEntry): void {
@@ -265,18 +294,22 @@ export class StylesCollector {
       return;
     }
     if (entry.kind === 'media') {
-      const liveRules = entry.rules.filter(
-        (rule) => rule.auto && this.allDepsMet(rule.dependsOn)
+      // Add newly live rules; keep rules already collected (e.g. by `use`).
+      const existing = this.entries.get(entryKey(entry));
+      const collected = new Set<StyleRule>(
+        existing?.kind === 'media' ? existing.rules : []
+      );
+      const rules = entry.rules.filter(
+        (rule) =>
+          collected.has(rule) || (rule.auto && this.allDepsMet(rule.dependsOn))
       );
-      if (liveRules.length === 0) {
+      if (rules.length === collected.size) {
         return;
       }
       const filtered: StyleMedia =
-        liveRules.length === entry.rules.length
-          ? entry
-          : { ...entry, rules: liveRules };
-      this.entries.set(entryKey(filtered), filtered);
-      for (const rule of liveRules) {
+        rules.length === entry.rules.length ? entry : { ...entry, rules };
+      this.setEntry(filtered);
+      for (const rule of rules) {
         this.addDeclarationDeps(rule.declarations);
       }
     }
@@ -293,7 +326,7 @@ export class StylesCollector {
 
   /** Marks a theme token path as reachable so it appears in the emitted theme block, even if no collected declaration reads it. */
   useThemeVar(path: string): void {
-    this.themeDeps.add(path);
+    this.batch(() => this.addDeps([path], []));
   }
 
   /** Creates a {@link StyleNameResolver} scoped to this collector's current dep set. */
@@ -439,9 +472,9 @@ export class StylesCollector {
     if (entry.kind === 'handle' && !this.retainHandle(entry)) {
       return;
     }
-    this.entries.set(entryKey(entry), entry);
+    this.setEntry(entry);
     if (entry.kind === 'handle') {
-      this.handles.set(entry.key, entry);
+      this.setHandle(entry);
       this.addDeclarationDeps(entry.declarations);
       return;
     }
@@ -455,8 +488,61 @@ export class StylesCollector {
   }
 
   private addDeclarationDeps(declarations: Declarations): void {
-    declarations.deps.theme.forEach((path) => this.themeDeps.add(path));
-    declarations.deps.vars.forEach((path) => this.varDeps.add(path));
+    this.addDeps(declarations.deps.theme, declarations.deps.vars);
+  }
+
+  private addDeps(
+    theme: Iterable<string>,
+    vars: Iterable<ContextualVarPath>
+  ): void {
+    const before = this.themeDeps.size + this.varDeps.size;
+    for (const path of theme) {
+      this.themeDeps.add(path);
+    }
+    for (const path of vars) {
+      this.varDeps.add(path);
+    }
+    if (this.themeDeps.size + this.varDeps.size !== before) {
+      this.dirty = true;
+    }
+  }
+
+  // A media entry changes when it gains inner rules.
+  private setEntry(entry: StyleEntry): void {
+    const key = entryKey(entry);
+    const existing = this.entries.get(key);
+    this.entries.set(key, entry);
+    if (
+      !existing ||
+      (existing.kind === 'media' &&
+        entry.kind === 'media' &&
+        existing.rules.length !== entry.rules.length)
+    ) {
+      this.dirty = true;
+    }
+  }
+
+  private setHandle(handle: StyleHandle): void {
+    if (!this.handles.has(handle.key)) {
+      this.dirty = true;
+    }
+    this.handles.set(handle.key, handle);
+  }
+
+  // Listeners run once the outermost public mutation returns.
+  private batch<T>(mutate: () => T): T {
+    this.depth += 1;
+    try {
+      return mutate();
+    } finally {
+      this.depth -= 1;
+      if (this.depth === 0 && this.dirty) {
+        this.dirty = false;
+        for (const listener of [...this.listeners]) {
+          listener();
+        }
+      }
+    }
   }
 }
 

package/src/dom_sink.ts

@@ -5,26 +5,24 @@
  * 2.0.
  */
 
-import type { StyleSink } from './emotion';
+import type { StyleElementLike, StyleParentLike, StyleSink } from './sink';
 
-/** Minimal interface for a DOM `<style>` element. */
-export interface StyleElementLike {
-  /** Current stylesheet text, or `null` before the first flush. */
-  textContent: string | null;
-}
+export type { StyleElementLike, StyleParentLike } from './sink';
 
 /** Minimal interface for a DOM `Document` able to create and append style tags. */
 export interface DocumentLike {
   /** Creates a `<style>` element. */
   createElement(tagName: 'style'): StyleElementLike;
-  /** Node that receives the created style element. */
-  readonly head: { appendChild(node: StyleElementLike): void };
+  /** Default parent for the created style element. */
+  readonly head: StyleParentLike;
 }
 
 /** Host document and optional flush scheduler for a `<style>` sink. */
 export interface CreateDomSinkOptions {
-  /** The host document where the style element will be appended. */
+  /** Document that creates the style element. */
   document: DocumentLike;
+  /** Node that receives the style element, e.g. a `ShadowRoot`. Defaults to `document.head`. */
+  parent?: StyleParentLike;
   /** Defers the flush. Defaults to `queueMicrotask`. */
   schedule?: (flush: () => void) => void;
 }
@@ -34,6 +32,7 @@ export interface CreateDomSinkOptions {
  */
 export const createDomSink = ({
   document,
+  parent,
   schedule = queueMicrotask,
 }: CreateDomSinkOptions): StyleSink => {
   let element: StyleElementLike | null = null;
@@ -47,7 +46,7 @@ export const createDomSink = ({
     }
     if (!element) {
       element = document.createElement('style');
-      document.head.appendChild(element);
+      (parent ?? document.head).appendChild(element);
     }
     element.textContent = latestRender();
   };

package/src/emotion.ts

@@ -8,6 +8,7 @@
 import type { Distillery } from './engine';
 import { contentHash64 } from './hash';
 import { flattenTemplate, isHandleLike, type TemplateSlice } from './nesting';
+import type { StyleSink } from './sink';
 import {
   globalStylesFromFlattened,
   pendingHandleFromFlattened,
@@ -21,13 +22,9 @@ export {
   type CreateDomSinkOptions,
   type DocumentLike,
   type StyleElementLike,
+  type StyleParentLike,
 } from './dom_sink';
-
-/** Receives stylesheet invalidation from Emotion compat modules. */
-export interface StyleSink {
-  /** Marks the sink dirty. `render` produces the current stylesheet when it flushes. */
-  invalidate(render: () => string): void;
-}
+export type { StyleSink } from './sink';
 
 /** Shared sink for Emotion compat modules on one registry. */
 export interface CreateEmotionOptions {

package/src/engine.ts

@@ -19,12 +19,14 @@ import {
   type StyleNameResolverOptions,
 } from './names';
 import { renderStyles, type RenderStylesOptions } from './runtime';
+import type { StyleSink } from './sink';
 import {
   createStyleModuleWithEnvironment,
   type PrimitiveStyleAuthoringApi,
   readableVarOwnersFromEnvironment,
   type ResolvedStyles,
   type StyleAuthoringApi,
+  type StyleHandle,
   StyleRegistry,
   type StylesModule,
   type StylesObject,
@@ -39,6 +41,30 @@ import {
   type ValuesOf,
 } from './theme';
 
+/** Sink, render options, and warning sink for {@link Distillery.liveCollection}. */
+export interface LiveCollectionOptions {
+  /** Invalidated whenever the collection grows. Nothing is written before the first handle. */
+  sink?: StyleSink;
+  /** Options forwarded to `renderStyles` by `css()`. */
+  render?: RenderStylesOptions;
+  /** Warning sink for no-op handles. Used only when the distillery has `dev: true`. */
+  warn?: (message: string) => void;
+}
+
+/**
+ * Readable collection filled by one live render.
+ *
+ * Readable only: compact names depend on the complete collected set and need two passes.
+ */
+export interface LiveCollection {
+  /** Underlying readable artifact collector. Mutations here (e.g. `use(globalModule)`, `useThemeVar`) also invalidate the sink. */
+  readonly collector: StylesCollector;
+  /** Collects `handles` and returns their readable class names, space-separated. */
+  readonly resolveClassName: (...handles: StyleHandle[]) => string;
+  /** Renders the CSS collected so far. */
+  readonly css: () => string;
+}
+
 /** One component library's binding: environment, registry, and pre-bound operations. Destructure-safe (no `this`). */
 export interface Distillery<
   TTokens = unknown,
@@ -79,6 +105,8 @@ export interface Distillery<
     names?: StyleNameMode,
     options?: Pick<StylesCollectorOptions, 'warn'>
   ) => StylesCollector;
+  /** Readable collection for one live render; keeps `sink` current as handles resolve. */
+  readonly liveCollection: (options?: LiveCollectionOptions) => LiveCollection;
   /** Emits collected CSS for this environment. */
   readonly renderStyles: (
     collector: StylesCollector,
@@ -135,6 +163,19 @@ export const createDistillery = <const TTheme extends ThemeTree>(
     sharedVars ?? new Set()
   );
 
+  const artifactCollector = (
+    names: StyleNameMode,
+    collectorOptions?: Pick<StylesCollectorOptions, 'warn'>
+  ): StylesCollector =>
+    new StylesCollector({
+      target: 'artifact',
+      names,
+      registry,
+      prefix,
+      dev,
+      ...(collectorOptions?.warn ? { warn: collectorOptions.warn } : {}),
+    });
+
   return {
     environment,
     tokens,
@@ -160,15 +201,7 @@ export const createDistillery = <const TTheme extends ThemeTree>(
         ({ css: style, tokens: moduleTokens }) =>
           factory({ style, tokens: moduleTokens })
       ),
-    artifactCollector: (names, options) =>
-      new StylesCollector({
-        target: 'artifact',
-        names,
-        registry,
-        prefix,
-        dev,
-        ...(options?.warn ? { warn: options.warn } : {}),
-      }),
+    artifactCollector,
     stylesheetCollector: (names = 'readable', options) => {
       const collector = new StylesCollector({
         target: 'stylesheet',
@@ -183,6 +216,23 @@ export const createDistillery = <const TTheme extends ThemeTree>(
       }
       return collector;
     },
+    liveCollection: ({ sink, render, warn } = {}) => {
+      const collector = artifactCollector('readable', warn ? { warn } : {});
+      const css = (): string =>
+        renderStyles(environment, collector, undefined, render);
+      if (sink) {
+        collector.subscribe(() => sink.invalidate(css));
+      }
+      return {
+        collector,
+        resolveClassName: (...handles) =>
+          collector
+            .useHandles(handles)
+            .map((handle) => handle.readableName)
+            .join(' '),
+        css,
+      };
+    },
     renderStyles: (collector, resolver, renderOptions) =>
       renderStyles(environment, collector, resolver, renderOptions),
     createNameResolver: (resolverOptions) =>

package/src/index.ts

@@ -5,7 +5,20 @@
  * 2.0.
  */
 
-export { createDistillery, type Distillery } from './engine';
+export {
+  createDistillery,
+  type Distillery,
+  type LiveCollection,
+  type LiveCollectionOptions,
+} from './engine';
+export {
+  createDomSink,
+  type CreateDomSinkOptions,
+  type DocumentLike,
+  type StyleElementLike,
+  type StyleParentLike,
+} from './dom_sink';
+export type { StyleSink } from './sink';
 export {
   type DistilleryEnvironment,
   type DistilleryOptions,

package/src/sink.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+/** Receives stylesheet invalidation from a live collection or Emotion compat modules. */
+export interface StyleSink {
+  /** Marks the sink dirty. `render` produces the current stylesheet when it flushes. */
+  invalidate(render: () => string): void;
+}
+
+/** Minimal interface for a DOM `<style>` element. */
+export interface StyleElementLike {
+  /** Current stylesheet text, or `null` before the first flush. */
+  textContent: string | null;
+}
+
+/** Node that receives a managed `<style>` element, e.g. `document.head` or a `ShadowRoot`. */
+export interface StyleParentLike {
+  // Method syntax (bivariant) so DOM `Node.appendChild<T extends Node>` assigns.
+  /** Appends the managed style element. */
+  appendChild(node: StyleElementLike): void;
+}