@pikacss/core 0.0.61 → 0.0.63

package/dist/index.d.mts

@@ -30,126 +30,119 @@ declare module '@pikacss/core' {
  *
  * @returns An `EnginePlugin` that intercepts `transformStyleDefinitions` to conditionally append `!important` to every property value.
  *
- * @remarks When `EngineConfig.important.default` is `true`, all property values receive `!important` unless the style definition explicitly sets `__important: false`. Individual style definitions can also opt-in with `__important: true` regardless of the default. An explicit `__important` flag is propagated into nested selector blocks (which may override it with their own explicit flag). The `__shortcut` reference is never modified.
+ * @remarks When `EngineConfig.important.default` is `true`, all property values receive `!important` unless the style definition explicitly sets `__important: false`. Individual style definitions can also opt-in with `__important: true` regardless of the default. An explicit `__important` flag is propagated into nested selector blocks (which may override it with their own explicit flag).
  *
  * @example
  * ```ts
  * createEngine({ plugins: [important()] })
  * ```
  */
-declare function important(): EnginePlugin;
+declare function important(): EnginePlugin<{
+  defaultValue: boolean;
+}>;
 //#endregion
 //#region src/plugins/keyframes.d.ts
-/**
- * Describes the progress stops of a CSS `@keyframes` animation.
- *
- * @remarks Accepts the named stops `from` and `to`, plus any percentage-based stop in the form `"N%"`. Each stop maps to a set of CSS properties applied at that point in the animation.
- *
- * @example
- * ```ts
- * const progress: KeyframesProgress = {
- *   from: { opacity: '0' },
- *   '50%': { opacity: '0.5' },
- *   to: { opacity: '1' },
- * }
- * ```
- */
+/** Describes the progress stops of a CSS `@keyframes` animation. */
 interface KeyframesProgress {
   /**
-   * CSS properties applied at the start of the animation.
-   *
-   * @default undefined
+   * Declarations at the beginning of the animation.
+   * @default `undefined`
    */
   from?: ResolvedCSSProperties;
   /**
-   * CSS properties applied at the end of the animation.
-   *
-   * @default undefined
+   * Declarations at the end of the animation.
+   * @default `undefined`
    */
   to?: ResolvedCSSProperties;
   [K: `${number}%`]: ResolvedCSSProperties;
 }
-/**
- * User-facing keyframes configuration. Accepts a name-only string, a tuple shorthand, or an object form.
- *
- * @remarks
- * - **String**: registers the name for autocomplete without defining animation frames.
- * - **Tuple `[name, frames?, autocomplete?, pruneUnused?]`**: concise shorthand.
- * - **Object `{ name, frames?, autocomplete?, pruneUnused? }`**: explicit form.
- *
- * @example
- * ```ts
- * const kf: Keyframes[] = [
- *   'spin',
- *   ['fade-in', { from: { opacity: '0' }, to: { opacity: '1' } }],
- * ]
- * ```
- */
-type Keyframes = string | [name: string, frames?: KeyframesProgress, autocomplete?: string[], pruneUnused?: boolean] | {
+/** Local keyframes emitted and optionally pruned by PikaCSS. */
+interface LocalKeyframesDefinition {
+  /** Name used for the local `@keyframes` rule. */
   name: string;
-  frames?: KeyframesProgress;
-  autocomplete?: string[];
+  /** CSS declarations grouped by animation progress stop. */
+  frames: KeyframesProgress;
+  /**
+   * Additional values accepted for the `animation` property autocomplete.
+   * @default `[]`
+   */
+  animationValues?: Arrayable<string>;
+  /**
+   * Documentation rendered for the generated Typegen keyframe member.
+   * @default `undefined`
+   */
+  description?: string;
+  /**
+   * Whether this local keyframe is removed when no generated style uses it.
+   * @default `KeyframesConfig.pruneUnused`
+   */
   pruneUnused?: boolean;
-};
-/**
- * Configuration object for the `keyframes` engine option.
- *
- * @remarks Passed via `EngineConfig.keyframes` to register `@keyframes` definitions at engine creation time.
- *
- * @example
- * ```ts
- * const config: KeyframesConfig = {
- *   definitions: [['spin', { from: { transform: 'rotate(0deg)' }, to: { transform: 'rotate(360deg)' } }]],
- *   pruneUnused: true,
- * }
- * ```
- */
-interface KeyframesConfig {
-  /** Array of keyframes definitions to register. */
-  definitions: Keyframes[];
   /**
-   * Default pruning policy for keyframes that are not referenced by any `animation` or `animation-name` atomic style.
-   *
-   * @default true
+   * Discriminator reserved for external keyframe definitions.
+   * @default `undefined`
    */
+  external?: never;
+}
+/** External keyframes known to authoring but never emitted/pruned by PikaCSS. */
+interface ExternalKeyframesDefinition {
+  /** Name of an externally defined `@keyframes` rule. */
+  external: string;
+  /**
+   * Additional values accepted for the `animation` property autocomplete.
+   * @default `[]`
+   */
+  animationValues?: Arrayable<string>;
+  /**
+   * Documentation rendered for the generated Typegen keyframe member.
+   * @default `undefined`
+   */
+  description?: string;
+  /**
+   * Discriminator excluding local keyframe definitions.
+   * @default `undefined`
+   */
+  name?: never;
+  /**
+   * Discriminator excluding local keyframe definitions.
+   * @default `undefined`
+   */
+  frames?: never;
+  /**
+   * External keyframes are never pruned by PikaCSS.
+   * @default `undefined`
+   */
+  pruneUnused?: never;
+}
+/** Canonical object-only keyframes definition. */
+type Keyframes = LocalKeyframesDefinition | ExternalKeyframesDefinition;
+/** Configuration for the built-in keyframes subsystem. */
+interface KeyframesConfig {
+  /** Local and external keyframe definitions available to the engine. */
+  definitions: Keyframes[];
+  /** Default pruning policy for local keyframes. @default true */
   pruneUnused?: boolean;
 }
 declare module '@pikacss/core' {
   interface EngineConfig {
-    /**
-     * Keyframes definitions configuration.
-     *
-     * @default undefined
-     */
+    /** Keyframe definitions consumed once during Engine initialization. */
     keyframes?: KeyframesConfig;
   }
-  interface Engine {
-    /** Runtime keyframes management: resolved keyframes store and `add` method for registering keyframes after engine creation. */
-    keyframes: {
-      store: Map<string, ResolvedKeyframesConfig>;
-      add: (...list: Keyframes[]) => void;
-    };
-  }
 }
-/**
- * Built-in engine plugin that provides CSS `@keyframes` registration, autocomplete integration, and smart pruning.
- *
- * @returns An `EnginePlugin` that registers keyframes definitions, wires up `animationName`/`animation` autocomplete entries, and emits a preflight containing only the `@keyframes` rules actually referenced by atomic styles.
- *
- * @remarks Reads `EngineConfig.keyframes` during `rawConfigConfigured` and attaches the `engine.keyframes` management interface during `configureEngine`. Unused keyframes are pruned from the output unless `pruneUnused: false` is set on the individual definition or globally.
- *
- * @example
- * ```ts
- * createEngine({ plugins: [keyframes()] })
- * ```
- */
-declare function keyframes(): EnginePlugin;
 interface ResolvedKeyframesConfig {
   name: string;
-  frames: KeyframesProgress | Nullish;
+  frames?: KeyframesProgress;
   pruneUnused: boolean;
-  autocomplete: string[];
+  animationValues: string[];
+  description?: string;
+  external: boolean;
 }
+interface KeyframesState {
+  definitions: Keyframes[];
+  defaultPruneUnused: boolean;
+  store: Map<string, ResolvedKeyframesConfig>;
+}
+/** Built-in keyframes subsystem with config-only semantic ingress. */
+declare function keyframes(): EnginePlugin<KeyframesState>;
 //#endregion
 //#region src/diagnostics.d.ts
 /** Severity of a PikaCSS diagnostic. */
@@ -176,6 +169,51 @@ interface Diagnostic {
 }
 /** Callback used by a host to receive structured diagnostics. */
 type DiagnosticHandler = (diagnostic: Diagnostic) => void;
+/**
+ * Host semantic metadata for one engine, supplied by the integration/bundler
+ * host and transported — never interpreted — by the platform-neutral core.
+ *
+ * @remarks
+ * The host (Vite adapter, Nuxt module, a programmatic caller) is the
+ * authority for these values. Plugins consume them through
+ * `context.host` so project-relative resources resolve against the same
+ * effective PikaCSS project root as config discovery, scans, and generated
+ * artifacts — never against `process.cwd()` once a host supplied a more
+ * specific root (#118). Core adds no filesystem, path, or bundler APIs here.
+ */
+interface EngineHostContext {
+  /**
+   * The effective PikaCSS project root for this engine (e.g. Vite's
+   * `config.root`, Nuxt's `rootDir`). Absent for standalone `createEngine()`
+   * callers that supply no host context.
+   */
+  readonly projectRoot?: string;
+  /**
+   * Opaque discriminator for PikaCSS-private generated CSS identities.
+   *
+   * @remarks Core transports this value without interpreting it. Subsystems
+   * and plugins that own private generated CSS names may consume it through
+   * `context.host`.
+   */
+  readonly privateCssDiscriminator?: string;
+}
+/** Context supplied when allocating a genuinely new atomic style ID. */
+interface AtomicStyleIdContext {
+  /** Zero-based engine-local allocation index. */
+  readonly index: number;
+  /** Resolved atomic style ID prefix. */
+  readonly prefix: string;
+}
+/** Strategy used by Core to allocate a genuinely new atomic style ID. */
+type AtomicStyleIdStrategy = (context: AtomicStyleIdContext) => string;
+/** Finalized external dependency descriptor for one Engine. */
+type EngineConfigDependency = Readonly<{
+  type: 'file';
+  path: string;
+}> | Readonly<{
+  type: 'directory-membership';
+  path: string;
+}>;
 /** Runtime-only options accepted by {@link createEngine}. */
 interface CreateEngineOptions {
   /**
@@ -183,12 +221,55 @@ interface CreateEngineOptions {
    *
    * @default A no-op handler.
    */
-  onDiagnostic?: DiagnosticHandler;
+  readonly onDiagnostic?: DiagnosticHandler;
+  /**
+   * Host semantic metadata for this engine (e.g. the effective project
+   * root). Exposed to plugins as `context.host`.
+   *
+   * @default An empty context.
+   */
+  readonly host?: EngineHostContext;
+  /**
+   * Overrides atomic-style ID allocation for host integrations.
+   *
+   * @internal
+   */
+  readonly atomicStyleIdStrategy?: AtomicStyleIdStrategy;
+  /**
+   * Receives each genuinely-new config dependency while the Engine is still
+   * initializing, including registrations made before a later initialization
+   * failure. Hosts use this only to preserve recovery metadata.
+   *
+   * @internal
+   */
+  readonly onConfigDependency?: (dependency: EngineConfigDependency) => void;
 }
-/** Context passed to plugin hooks by the engine. */
-interface EnginePluginContext {
+/**
+ * Context passed to plugin hooks by the engine.
+ *
+ * @remarks
+ * One context object exists per plugin definition **per engine** (#116): the
+ * same object is passed to every hook invocation of that plugin/engine pair,
+ * from `configureRawConfig` through committed notifications. Long-lived
+ * callbacks a plugin registers (shortcut resolvers, preflight functions,
+ * engine service methods) should close over this context — never over mutable
+ * plugin-factory closure variables, which are shared across every engine
+ * reusing the definition.
+ */
+interface EnginePluginContext<State = void> {
   /** Instance-scoped diagnostic handler. */
   onDiagnostic: DiagnosticHandler;
+  /**
+   * Engine-local plugin state, created once per plugin/engine pair by the
+   * plugin's `createState()` initializer. `undefined` (typed `void`) for
+   * stateless plugins that omit the initializer.
+   */
+  state: State;
+  /**
+   * Host semantic metadata for this engine (#118). Read-only from a
+   * plugin's perspective; empty when no host context was supplied.
+   */
+  readonly host: EngineHostContext;
 }
 //#endregion
 //#region src/resolver.d.ts
@@ -414,23 +495,7 @@ declare abstract class RecursiveResolver<T> extends AbstractResolver<T[]> {
    */
   resolve(string: string, _visited?: Set<string>): Promise<T[]>;
 }
-/**
- * Discriminated union describing a resolved rule configuration, either static or dynamic.
- * @internal
- *
- * @typeParam T - The element type of the rule's resolved value array.
- *
- * @remarks Produced by `resolveRuleConfig` from user-supplied shorthand configurations. The `autocomplete` array feeds the autocomplete type surface so IDE completions stay in sync with runtime rules.
- *
- * @example
- * ```ts
- * const config: ResolvedRuleConfig<string> = {
- *   type: 'static',
- *   rule: { key: 'hover', string: 'hover', resolved: ['$:hover'] },
- *   autocomplete: ['hover'],
- * }
- * ```
- */
+/** Discriminated normalized rule used by selector/shortcut private registries. */
 type ResolvedRuleConfig<T> = {
   type: 'static';
   rule: StaticRule<T[]>;
@@ -442,324 +507,243 @@ type ResolvedRuleConfig<T> = {
 };
 //#endregion
 //#region src/plugins/selectors.d.ts
-/**
- * User-facing selector rule configuration. Accepts string redirects, tuple shorthands, or object forms.
- *
- * @remarks
- * - **String**: a redirect to another named selector.
- * - **Tuple `[string, value]`**: a static rule mapping an exact selector name to one or more resolved CSS selectors.
- * - **Tuple `[RegExp, fn, autocomplete?]`**: a dynamic rule matching a pattern and lazily computing resolved CSS selectors.
- * - **Object `{ selector, value, autocomplete? }`**: an explicit form of either static or dynamic rule.
- *
- * A dynamic rule's value function may return `undefined`/`null` to signal a retryable-unresolved result: nothing is cached and the rule is re-invoked on a later resolve call (e.g. after a transient failure).
- *
- * @example
- * ```ts
- * const rules: Selector[] = [
- *   ['hover', '$:hover'],
- *   [/^media-(\d+)$/, m => `@media (min-width: ${m[1]}px)`, 'media-${breakpoint}'],
- * ]
- * ```
- */
-type Selector = string | [selector: RegExp, value: (matched: RegExpMatchArray) => Awaitable<Arrayable<UnionString | ResolvedSelector> | Nullish>, autocomplete?: Arrayable<string>] | [selector: string, value: Arrayable<UnionString | ResolvedSelector>] | {
-  selector: RegExp;
-  value: (matched: RegExpMatchArray) => Awaitable<Arrayable<UnionString | ResolvedSelector> | Nullish>;
-  autocomplete?: Arrayable<string>;
-} | {
-  selector: string;
+/** Static selector definition in the frozen object-only authoring grammar. */
+interface StaticSelector {
+  /** Name used to reference the selector in a style definition. */
+  name: string;
+  /** Selector or selectors emitted when the named selector is resolved. */
   value: Arrayable<UnionString | ResolvedSelector>;
-};
-/**
- * Configuration object for the `selectors` engine option.
- *
- * @remarks Passed via `EngineConfig.selectors` to register selector rules at engine creation time.
- *
- * @example
- * ```ts
- * const config: SelectorsConfig = {
- *   definitions: [['hover', '$:hover'], ['focus', '$:focus']],
- * }
- * ```
- */
+  /**
+   * Documentation rendered for the generated Typegen selector member.
+   * @default `undefined`
+   */
+  description?: string;
+}
+/** Dynamic selector definition with separate runtime and TypeScript input contracts. */
+interface DynamicSelector {
+  /** Pattern matched against a selector reference. */
+  pattern: RegExp;
+  /** TypeScript input expression for selector references handled by this rule. */
+  inputType: string;
+  /** Resolves a matched selector reference to one or more CSS selectors. */
+  resolve: (matched: RegExpMatchArray) => Awaitable<Arrayable<UnionString | ResolvedSelector> | Nullish>;
+  /**
+   * Concrete selector references offered in Typegen autocomplete.
+   * @default `[]`
+   */
+  autocomplete?: Arrayable<string>;
+  /**
+   * Documentation rendered for generated Typegen selector members.
+   * @default `undefined`
+   */
+  description?: string;
+}
+/** User-facing selector definition. Tuple/string shorthand forms are intentionally unsupported. */
+type Selector = StaticSelector | DynamicSelector;
+/** Configuration for the built-in selector subsystem. */
 interface SelectorsConfig {
-  /** Array of selector rule definitions to register. */
+  /** Static and dynamic selector definitions available to the engine. */
   definitions: Selector[];
 }
 declare module '@pikacss/core' {
   interface EngineConfig {
-    /**
-     * Selector rules configuration.
-     *
-     * @default undefined
-     */
+    /** Selector definitions consumed once during Engine initialization. */
     selectors?: SelectorsConfig;
   }
-  interface Engine {
-    /** Runtime selector management: resolver instance and `add` method for registering selectors after engine creation. */
-    selectors: {
-      resolver: SelectorResolver;
-      add: (...list: Selector[]) => void;
-    };
-  }
 }
-/**
- * Built-in engine plugin that provides the selector resolution system.
- *
- * @returns An `EnginePlugin` that registers the `selectors` resolver on the engine and hooks into `transformSelectors` to expand selector names into resolved CSS selectors.
- *
- * @remarks Reads `EngineConfig.selectors` during `rawConfigConfigured`, attaches a `RecursiveResolver` to `engine.selectors` during `configureEngine`, and resolves all selector strings in the `transformSelectors` hook.
- *
- * @example
- * ```ts
- * createEngine({ plugins: [selectors()] })
- * ```
- */
-declare function selectors$1(): EnginePlugin;
+interface SelectorsState {
+  definitions: Selector[];
+  resolver?: SelectorResolver;
+}
+/** Built-in selector subsystem. Effective raw config is its only semantic ingress. */
+declare function selectors$1(): EnginePlugin<SelectorsState>;
 declare class SelectorResolver extends RecursiveResolver<string> {}
-/**
- * Normalizes a `Selector` configuration into a `ResolvedRuleConfig`, a redirect string, or `undefined`.
- *
- * @param config - The selector rule configuration to resolve.
- * @returns A resolved static/dynamic rule config, a redirect string, or `undefined` if the shape is unrecognized.
- *
- * @remarks Delegates to the generic `resolveRuleConfig` with `'selector'` as the key name.
- *
- * @example
- * ```ts
- * const resolved = resolveSelectorConfig(['hover', '$:hover'])
- * ```
- */
-declare function resolveSelectorConfig(config: Selector): string | Nullish | ResolvedRuleConfig<string>;
+/** @internal */
+declare function resolveSelectorConfig(config: Selector): Nullish | ResolvedRuleConfig<string>;
 //#endregion
 //#region src/plugins/shortcuts.d.ts
-/**
- * User-facing shortcut rule configuration. Accepts string redirects, tuple shorthands, or object forms.
- *
- * @remarks Shortcuts expand a single name into one or more style items, allowing reusable composition of atomic styles. The configuration shapes mirror `Selector`: string redirect, `[string, value]` static, `[RegExp, fn, autocomplete?]` dynamic, or object equivalents. A dynamic rule's value function may return `undefined`/`null` to signal a retryable-unresolved result: nothing is cached and the rule is re-invoked on a later resolve call (e.g. after a transient failure).
- *
- * @example
- * ```ts
- * const rules: Shortcut[] = [
- *   ['btn', [{ padding: '0.5rem 1rem' }, { borderRadius: '0.25rem' }]],
- *   [/^btn-(.+)$/, m => ({ backgroundColor: m[1] }), 'btn-${color}'],
- * ]
- * ```
- */
-type Shortcut = string | [shortcut: RegExp, value: (matched: RegExpMatchArray) => Awaitable<Arrayable<ResolvedStyleItem> | Nullish>, autocomplete?: Arrayable<string>] | {
-  shortcut: RegExp;
-  value: (matched: RegExpMatchArray) => Awaitable<Arrayable<ResolvedStyleItem> | Nullish>;
-  autocomplete?: Arrayable<string>;
-} | [shortcut: string, value: Arrayable<ResolvedStyleItem>] | {
-  shortcut: string;
+/** Static shortcut definition in the frozen object-only authoring grammar. */
+interface StaticShortcut {
+  /** Name used to reference the shortcut in a `pika()` call. */
+  name: string;
+  /** Style items expanded when the named shortcut is resolved. */
   value: Arrayable<ResolvedStyleItem>;
-};
-/**
- * Configuration object for the `shortcuts` engine option.
- *
- * @remarks Passed via `EngineConfig.shortcuts` to register shortcut rules at engine creation time.
- *
- * @example
- * ```ts
- * const config: ShortcutsConfig = {
- *   definitions: [['btn', { padding: '0.5rem 1rem' }]],
- * }
- * ```
- */
+  /**
+   * Documentation rendered for the generated Typegen shortcut member.
+   * @default `undefined`
+   */
+  description?: string;
+}
+/** Path-free image metadata collected only while Core finalizes rich shortcut previews. */
+interface ShortcutPreviewImage {
+  /** Raw image bytes or text content supplied by the resolver. */
+  readonly content: string;
+  /** MIME type describing `content`. */
+  readonly mediaType: string;
+  /**
+   * Optional alternative text for the generated Markdown preview image.
+   * @default `undefined`
+   */
+  readonly alt?: string;
+}
+/** Documentation-only collector supplied to dynamic shortcut resolution during Typegen preview. */
+interface ShortcutPreviewCollector {
+  /** Registers one path-free image for the shortcut's generated preview. */
+  image: (image: ShortcutPreviewImage) => void;
+}
+/** Optional resolution context. Runtime resolution omits it; Typegen preview supplies it. */
+interface ShortcutResolutionContext {
+  /**
+   * Preview-only collector; absent during ordinary runtime resolution.
+   * @default `undefined`
+   */
+  readonly preview?: ShortcutPreviewCollector;
+}
+/** Dynamic shortcut definition with separate runtime and TypeScript input contracts. */
+interface DynamicShortcut {
+  /** Pattern matched against a shortcut reference. */
+  pattern: RegExp;
+  /** TypeScript input expression for shortcut references handled by this rule. */
+  inputType: string;
+  /** Resolves a matched shortcut reference to one or more style items. */
+  resolve: (matched: RegExpMatchArray, context?: ShortcutResolutionContext) => Awaitable<Arrayable<ResolvedStyleItem> | Nullish>;
+  /**
+   * Concrete shortcut references offered in Typegen autocomplete.
+   * @default `[]`
+   */
+  autocomplete?: Arrayable<string>;
+  /**
+   * Documentation rendered for generated Typegen shortcut members.
+   * @default `undefined`
+   */
+  description?: string;
+}
+/** User-facing shortcut definition. Tuple/string shorthand forms are intentionally unsupported. */
+type Shortcut = StaticShortcut | DynamicShortcut;
+/** Configuration for the built-in shortcut subsystem. */
 interface ShortcutsConfig {
-  /** Array of shortcut rule definitions to register. */
+  /** Static and dynamic shortcut definitions available to the engine. */
   definitions: Shortcut[];
 }
 declare module '@pikacss/core' {
   interface EngineConfig {
-    /**
-     * Shortcut rules configuration.
-     *
-     * @default undefined
-     */
+    /** Shortcut definitions consumed once during Engine initialization. */
     shortcuts?: ShortcutsConfig;
   }
-  interface Engine {
-    /** Runtime shortcut management: resolver instance and `add` method for registering shortcuts after engine creation. */
-    shortcuts: {
-      resolver: ShortcutResolver;
-      add: (...list: Shortcut[]) => void;
-    };
-  }
 }
-/**
- * Built-in engine plugin that provides the shortcut resolution system.
- *
- * @returns An `EnginePlugin` that registers the `shortcuts` resolver on the engine and hooks into `transformStyleItems` and `transformStyleDefinitions` to expand shortcut names into style items.
- *
- * @remarks Reads `EngineConfig.shortcuts` during `rawConfigConfigured`, attaches a `RecursiveResolver` to `engine.shortcuts` during `configureEngine`, and expands shortcut references in both `transformStyleItems` (string style items) and `transformStyleDefinitions` (the `__shortcut` pseudo-property).
- *
- * @example
- * ```ts
- * createEngine({ plugins: [shortcuts()] })
- * ```
- */
-declare function shortcuts(): EnginePlugin;
+interface ShortcutsState {
+  definitions: Shortcut[];
+  resolver?: ShortcutResolver;
+}
+/** Built-in shortcut subsystem. Effective raw config is its only semantic ingress. */
+declare function shortcuts(): EnginePlugin<ShortcutsState>;
 declare class ShortcutResolver extends RecursiveResolver<InternalStyleItem> {}
+/** @internal */
+declare function resolveShortcutConfig(config: Shortcut): Nullish | ResolvedRuleConfig<StyleItem>;
 //#endregion
 //#region src/plugins/variables.d.ts
-type ResolvedCSSProperty = keyof ResolvedCSSProperties;
-/**
- * Controls how a CSS variable participates in the autocomplete type surface.
- *
- * @remarks When `asValueOf` includes `'*'`, the variable appears as a value option for every CSS property. Use `'-'` to suppress value-of suggestions entirely.
- *
- * @example
- * ```ts
- * const auto: VariableAutocomplete = { asValueOf: ['color', 'background-color'], asProperty: true }
- * ```
- */
-interface VariableAutocomplete {
+type ResolvedCSSProperty = keyof ResolvedCSSProperties & string;
+/** Domain-local suggestion metadata for one CSS variable. */
+interface VariableSuggest {
+  /** Whether the custom property itself is emitted as an explicit Typegen property symbol. @default true */
+  asProperty?: boolean;
+  /** CSS properties for which `var(--name)` is suggested; `'*'` is an explicit wildcard. @default false */
+  asValueOf?: Arrayable<'*' | ResolvedCSSProperty> | false;
+}
+/** Local CSS variable leaf emitted and optionally pruned by PikaCSS. */
+interface LocalVariable {
+  /** Value emitted for the custom property. */
+  value: ResolvedCSSProperties[`--${string}`];
   /**
-   * CSS properties (or `'*'` for all, `'-'` for none) where this variable should appear as a `var()` value suggestion.
-   *
-   * @default undefined (`'*'` when unset)
+   * Controls Typegen suggestions for this variable.
+   * @default `{ asProperty: true, asValueOf: false }`
    */
-  asValueOf?: Arrayable<UnionString | '*' | '-' | ResolvedCSSProperty>;
+  suggest?: VariableSuggest;
   /**
-   * Whether this variable name should appear as an extra CSS property in the autocomplete surface.
-   *
-   * @default true
+   * Documentation rendered for the generated Typegen variable member.
+   * @default `undefined`
    */
-  asProperty?: boolean;
+  description?: string;
+  /**
+   * Whether this variable is removed when no generated style uses it.
+   * @default `VariablesConfig.pruneUnused`
+   */
+  pruneUnused?: boolean;
+  /**
+   * Discriminator reserved for external variable definitions.
+   * @default `undefined`
+   */
+  external?: never;
 }
-/**
- * Expanded object form of a CSS variable definition with optional metadata.
- *
- * @remarks Use this form when the variable needs custom autocomplete behaviour or opt-out of unused-pruning.
- *
- * @example
- * ```ts
- * const v: VariableObject = {
- *   value: '#3b82f6',
- *   autocomplete: { asValueOf: '*' },
- *   pruneUnused: false,
- * }
- * ```
- */
-interface VariableObject {
+/** External CSS variable leaf known to authoring but not emitted by PikaCSS. */
+interface ExternalVariable {
+  /** Marks a variable as defined outside the generated stylesheet. */
+  external: true;
   /**
-   * The CSS value assigned to this variable.
-   *
-   * @default undefined (variable is registered for autocomplete only, no value emitted)
+   * Controls Typegen suggestions for this externally defined variable.
+   * @default `{ asProperty: true, asValueOf: false }`
    */
-  value?: ResolvedCSSProperties[`--${string}`];
+  suggest?: VariableSuggest;
   /**
-   * Fine-grained control over this variable's autocomplete behaviour.
-   *
-   * @default undefined (`'*'` value suggestions when unset)
+   * Documentation rendered for the generated Typegen variable member.
+   * @default `undefined`
    */
-  autocomplete?: VariableAutocomplete;
+  description?: string;
   /**
-   * Whether this variable should be pruned from the output when it is not referenced by any atomic style or preflight.
-   *
-   * @default true (inherits from `VariablesConfig.pruneUnused`)
+   * Discriminator excluding local variable definitions.
+   * @default `undefined`
    */
-  pruneUnused?: boolean;
+  value?: never;
+  /**
+   * External variables are never pruned by PikaCSS.
+   * @default `undefined`
+   */
+  pruneUnused?: never;
 }
-/**
- * A CSS variable value, either a plain CSS value string/number or a `VariableObject` with metadata.
- *
- * @remarks Use the short form for simple values. Use `VariableObject` when autocomplete control or pruning opt-out is needed.
- *
- * @example
- * ```ts
- * const simple: Variable = '#fff'
- * const rich: Variable = { value: '#fff', autocomplete: { asValueOf: ['color'] } }
- * ```
- */
-type Variable = ResolvedCSSProperties[`--${string}`] | VariableObject;
-/**
- * A nested record mapping CSS variable names (`--*`) and optional selector scopes to variable definitions.
- *
- * @remarks Non-`--` keys are treated as selector scopes (e.g. `'.dark'`, `'@media ...'`) that nest the enclosed variables under that selector. Keys starting with `--` define actual CSS variables.
- *
- * @example
- * ```ts
- * const def: VariablesDefinition = {
- *   '--color-primary': '#3b82f6',
- *   '.dark': { '--color-primary': '#60a5fa' },
- * }
- * ```
- */
+/** Canonical object-only variable leaf. */
+type Variable = LocalVariable | ExternalVariable;
+/** CSS-like nested variable definition tree. Non-variable keys are selector scopes. */
 type VariablesDefinition = { [key in UnionString | ResolvedSelector]?: Variable | VariablesDefinition };
-/**
- * Configuration object for the `variables` engine option.
- *
- * @remarks Passed via `EngineConfig.variables` to define CSS custom properties, control pruning, and specify a safe list.
- *
- * @example
- * ```ts
- * const config: VariablesConfig = {
- *   definitions: {
- *     '--color-primary': '#3b82f6',
- *     '--shadow-elevated': '0 12px 40px rgb(0 0 0 / 0.12)',
- *   },
- *   pruneUnused: true,
- *   safeList: ['--color-primary'],
- * }
- * ```
- */
+/** Configuration for the built-in CSS variables subsystem. */
 interface VariablesConfig {
-  /** CSS variable definitions to register. Later entries override earlier ones when keys overlap. */
+  /** Variable definition trees. Later entries override earlier entries at the same selector/name path. */
   definitions?: Arrayable<VariablesDefinition>;
-  /**
-   * Default pruning policy for variables that are not referenced by any atomic style or preflight.
-   *
-   * @default true
-   */
+  /** Default pruning policy for local variables. @default true */
   pruneUnused?: boolean;
-  /**
-   * Variable names that should always be emitted regardless of usage.
-   *
-   * @default []
-   */
+  /** Variable names always emitted regardless of usage. */
   safeList?: (`--${string}` & {})[];
 }
 declare module '@pikacss/core' {
   interface EngineConfig {
-    /**
-     * CSS custom properties (variables) configuration.
-     *
-     * @default undefined
-     */
+    /** CSS variable definitions consumed once during Engine initialization. */
     variables?: VariablesConfig;
   }
   interface Engine {
-    /** Runtime variable management: resolved variable store and `add` method for registering variables after engine creation. */
-    variables: {
-      store: Map<string, ResolvedVariable[]>;
-      add: (variables: VariablesDefinition) => void;
-    };
+    /** Readonly semantic query of variable names referenced by current atomic styles, expanded transitively through configured variable values. */
+    getUsedVariableNames: () => ReadonlySet<string>;
   }
 }
-/**
- * Built-in engine plugin that provides CSS custom properties (variables) with smart pruning and autocomplete integration.
- *
- * @returns An `EnginePlugin` that registers variable definitions, manages a preflight for emitting `:root` / scoped variables, and prunes unused variables from the output.
- *
- * @remarks Reads `EngineConfig.variables` during `rawConfigConfigured` and attaches the `engine.variables` management interface during `configureEngine`. A preflight is registered that collects variable references from atomic styles and other preflights, transitively expands dependencies, and emits only used (or safe-listed) variables.
- *
- * @example
- * ```ts
- * createEngine({ plugins: [variables()] })
- * ```
- */
-declare function variables(): EnginePlugin;
 interface ResolvedVariable {
   name: string;
-  value: InternalPropertyValue;
+  value?: InternalPropertyValue;
   selector: string[];
   pruneUnused: boolean;
-  autocomplete: {
+  suggest: {
     asValueOf: string[];
     asProperty: boolean;
   };
+  description?: string;
+  external: boolean;
+}
+interface VariablesState {
+  definitions: VariablesDefinition[];
+  defaultPruneUnused: boolean;
+  safeSet: Set<string>;
+  resolved: ResolvedVariable[];
+  store: Map<string, ResolvedVariable[]>;
 }
+/** Built-in CSS variable subsystem with config-only semantic ingress. */
+declare function variables(): EnginePlugin<VariablesState>;
 /**
  * Extracts all CSS variable names referenced via `var(--*)` calls in a string.
  *
@@ -806,522 +790,212 @@ declare function normalizeVariableName(name: string): string;
  */
 declare function extractUsedVarNamesFromPreflightResult(result: string | PreflightDefinition): string[];
 //#endregion
-//#region src/types/utils.d.ts
-/**
- * Represents `null` or `undefined`, used throughout the engine to express optional absence.
- *
- * @remarks Prefer this alias over inlining `null | undefined` for consistency across the codebase.
- *
- * @example
- * ```ts
- * function process(value: string | Nullish) {
- *   if (value == null) return // handles both null and undefined
- * }
- * ```
- */
-type Nullish = null | undefined;
-/**
- * Branded string type that preserves literal union autocompletion while still accepting arbitrary strings.
- *
- * @remarks TypeScript narrows `string` to only known literals when a union is used. Intersecting with `{}` keeps the union suggestions in IDE autocomplete without rejecting unknown strings at the type level.
- *
- * @example
- * ```ts
- * type Color = 'red' | 'blue' | UnionString
- * const c: Color = 'red'    // autocomplete suggests 'red' | 'blue'
- * const d: Color = 'green'  // still valid
- * ```
- */
-type UnionString = string & {};
-/**
- * A value that can be either a single item or an array of items.
- *
- * @typeParam T - The element type.
- *
- * @remarks Used pervasively in configuration surfaces so consumers can pass a single value or an array without explicit wrapping.
- *
- * @example
- * ```ts
- * function normalize<T>(input: Arrayable<T>): T[] {
- *   return [input].flat() as T[]
- * }
- * normalize('a')     // ['a']
- * normalize(['a','b']) // ['a','b']
- * ```
- */
-type Arrayable<T> = T | T[];
-/**
- * A value that may be synchronous or wrapped in a `Promise`.
- *
- * @typeParam T - The resolved value type.
- *
- * @remarks Hook callbacks and plugin functions use this so authors can return either synchronously or asynchronously without the engine caring which.
- *
- * @example
- * ```ts
- * async function run(fn: () => Awaitable<string>) {
- *   const result = await fn() // works whether fn is sync or async
- * }
- * ```
- */
-type Awaitable<T> = T | Promise<T>;
-/**
- * Converts a union type into an intersection of all its members.
- *
- * @typeParam U - The union type to intersect.
- *
- * @remarks Leverages contra-variant inference on function parameter positions. Useful internally for merging augmented module declarations into a single combined type.
- *
- * @example
- * ```ts
- * type U = { a: 1 } | { b: 2 }
- * type I = UnionToIntersection<U> // { a: 1 } & { b: 2 }
- * ```
- */
-type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
-/**
- * Type-level strict equality check that resolves to `true` when `X` and `Y` are identical types.
- *
- * @typeParam X - First type to compare.
- * @typeParam Y - Second type to compare.
- *
- * @remarks Uses the double-conditional-inference trick to detect structural and modifier differences that `extends` alone would miss (e.g. `readonly` vs mutable).
- *
- * @example
- * ```ts
- * type A = IsEqual<string, string>  // true
- * type B = IsEqual<string, number>  // false
- * ```
- */
-type IsEqual<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
-/**
- * Evaluates to `true` when `T` is the `never` type, `false` otherwise.
- *
- * @typeParam T - The type to test.
- *
- * @remarks Wrapping `T` in a tuple prevents distributive conditional behavior that would otherwise collapse `never` before the check runs.
- *
- * @example
- * ```ts
- * type A = IsNever<never>  // true
- * type B = IsNever<string> // false
- * ```
- */
-type IsNever<T> = [T] extends [never] ? true : false;
-/**
- * Flattens an intersection type into a single object type for improved readability in IDE tooltips.
- *
- * @typeParam T - The intersection or object type to simplify.
- *
- * @remarks Mapped types re-enumerate all keys so the resulting hover preview shows a flat `{ ... }` shape instead of `A & B & C`.
- *
- * @example
- * ```ts
- * type Merged = Simplify<{ a: 1 } & { b: 2 }> // { a: 1; b: 2 }
- * ```
- */
-type Simplify<T> = { [K in keyof T]: T[K] } & {};
-/**
- * Converts a camelCase or PascalCase string literal type to kebab-case at the type level.
- *
- * @typeParam T - The string literal type to convert. CSS custom properties (`--*`) are returned as-is.
- *
- * @remarks Used to map JavaScript-style property names to their CSS kebab-case equivalents during style extraction and rendering.
- *
- * @example
- * ```ts
- * type A = ToKebab<'backgroundColor'> // 'background-color'
- * type B = ToKebab<'--my-var'>        // '--my-var'
- * ```
- */
-type ToKebab<T extends string> = T extends `--${string}` ? T : T extends `${infer A}${infer U}${infer Rest}` ? U extends Uppercase<U> ? U extends Lowercase<U> ? `${Lowercase<A>}${ToKebab<`${U}${Rest}`>}` : `${Lowercase<A>}-${ToKebab<`${Lowercase<U>}${Rest}`>}` : `${Lowercase<A>}${ToKebab<`${U}${Rest}`>}` : Lowercase<T>;
-/**
- * Converts a kebab-case string literal type to camelCase at the type level.
- *
- * @typeParam T - The string literal type to convert. CSS custom properties (`--*`) are returned as-is.
- *
- * @remarks The inverse of `ToKebab`. Used to reconcile CSS-native property names back to their JavaScript equivalents during autocomplete resolution.
- *
- * @example
- * ```ts
- * type A = FromKebab<'background-color'> // 'backgroundColor'
- * type B = FromKebab<'--my-var'>         // '--my-var'
- * ```
- */
-type FromKebab<T extends string> = T extends `--${string}` ? T : T extends `${infer Head}-${infer Tail}` ? `${Head}${FromKebab<Capitalize<Tail>>}` : T;
-/**
- * Safely extracts the value type at key `K` from object type `Obj`, returning `never` when `Obj` is `never` or `K` is not a key of `Obj`.
- *
- * @typeParam Obj - The source object type.
- * @typeParam K - The key to look up.
- *
- * @remarks Wrapping `Obj` in a tuple prevents distributive collapse when `Obj` is `never`.
- *
- * @example
- * ```ts
- * type V = GetValue<{ a: number }, 'a'> // number
- * type N = GetValue<{ a: number }, 'b'> // never
- * ```
- */
-type GetValue<Obj, K extends string> = [Obj] extends [never] ? never : K extends keyof Obj ? Obj[K] : never;
+//#region src/atomic-style.d.ts
 /**
- * Conditionally resolves `T[Key]` when the key exists and its value extends `I`; otherwise falls back to `Fallback`.
- *
- * @typeParam T - The source type to look up.
- * @typeParam Key - The key to look up in `T`.
- * @typeParam I - The constraint that `T[Key]` must satisfy.
- * @typeParam Fallback - The default type returned when `Key` is missing or `T[Key]` does not extend `I`.
+ * Mutable store holding all resolved atomic styles and their lookup indices for an engine instance.
+ * @internal
  *
- * @remarks Used extensively to resolve augmented types from `PikaAugment`, falling back to internal defaults when no augmentation is provided.
+ * @remarks The store is created once per engine and mutated as new styles are resolved via `engine.use()`. It maintains four related indices: content-hash to ID, ID to full atomic style, base-key to ID list (for order-sensitive reuse), and ID to insertion order.
  *
  * @example
  * ```ts
- * type R = ResolveFrom<{ Foo: string }, 'Foo', string, 'default'> // string
- * type D = ResolveFrom<{}, 'Foo', string, 'default'>              // 'default'
+ * const store = createEngineStore()
+ * // store.atomicStyleIds: Map<serializedKey, 'pk-a'>
  * ```
  */
-type ResolveFrom<T, Key extends string, I, Fallback extends I> = Key extends keyof T ? T[Key] extends I ? T[Key] : Fallback : Fallback;
+interface EngineStore {
+  /** Map from serialized content keys to their assigned atomic style IDs. */
+  atomicStyleIds: Map<string, string>;
+  /** Map from atomic style ID to the full `AtomicStyle` object. */
+  atomicStyles: Map<string, AtomicStyle>;
+  /** Map from base content key to the list of atomic style IDs that share it (for order-sensitive styles). */
+  atomicStyleIdsByBaseKey: Map<string, string[]>;
+  /** Map from atomic style ID to its insertion order index, used for deterministic output ordering. */
+  atomicStyleOrder: Map<string, number>;
+}
 //#endregion
-//#region src/types/autocomplete.d.ts
+//#region src/extractor.d.ts
 /**
- * Extracts the string keys of `T`, returning `never` when `T` itself is `never`.
+ * Function signature for the bound extraction function created by `createExtractFn`.
  * @internal
  *
- * @typeParam T - The type whose string keys to extract.
- *
- * @remarks Wraps `T` in a tuple to prevent distributive collapse on `never`, then narrows to `string` keys only. Used internally to derive autocomplete property names from augmented type maps.
- *
- * @example
- * ```ts
- * type Keys = AutocompleteKeys<{ foo: 1; bar: 2 }> // 'foo' | 'bar'
- * type Empty = AutocompleteKeys<never>              // never
- * ```
- */
-type AutocompleteKeys<T> = [T] extends [never] ? never : Extract<keyof T, string>;
-/**
- * Configuration for pattern-based autocomplete suggestions that are expanded at code generation time.
- *
- * @remarks Patterns define template strings or records that the code-generation layer uses to produce expanded autocomplete entries. Unlike direct entries, patterns describe *how* to generate completions rather than listing them explicitly.
+ * @remarks Accepts a single style definition and returns the extracted content list. The plugin transform hooks and default selector are captured in the closure.
  *
  * @example
  * ```ts
- * const patterns: AutocompletePatternsConfig = {
- *   selectors: ['hover', 'focus'],
- *   properties: { spacing: ['sm', 'md', 'lg'] },
- * }
+ * const extractFn: ExtractFn = createExtractFn({ ... })
+ * const contents = await extractFn({ color: 'red' })
  * ```
  */
-interface AutocompletePatternsConfig {
-  /**
-   * Selector pattern strings expanded into autocomplete selector suggestions.
-   *
-   * @default undefined
-   */
-  selectors?: Arrayable<string>;
-  /**
-   * Shortcut pattern strings expanded into autocomplete shortcut suggestions.
-   *
-   * @default undefined
-   */
-  shortcuts?: Arrayable<string>;
-  /**
-   * Property-to-values mapping whose keys are property names and values are the allowed value patterns.
-   *
-   * @default undefined
-   */
-  properties?: Record<string, Arrayable<string>>;
-  /**
-   * CSS property-to-values mapping whose keys are CSS property names and values are the allowed value patterns.
-   *
-   * @default undefined
-   */
-  cssProperties?: Record<string, Arrayable<string>>;
+type ExtractFn = (styleDefinition: InternalStyleDefinition) => Promise<ExtractedStyleContent[]>;
+//#endregion
+//#region src/pika.d.ts
+/** Read-side engine-scoped registry for first-level Pika static authoring extensions. */
+interface PikaManager {
+  /** Returns whether a finalized first-level static root is registered. */
+  hasStatic: (name: string) => boolean;
+  /** Returns the finalized implementation for a first-level static root. */
+  getStatic: (name: string) => unknown | undefined;
 }
-/**
- * A partial set of autocomplete entries contributed by a plugin or engine subsystem at runtime.
- *
- * @remarks Plugins call `engine.appendAutocomplete()` with an `AutocompleteContribution` to incrementally register new completions for selectors, shortcuts, properties, and CSS properties. Contributions are merged additively into the resolved autocomplete config.
- *
- * @example
- * ```ts
- * engine.appendAutocomplete({
- *   selectors: 'dark',
- *   cssProperties: { color: ['red', 'blue'] },
- * })
- * ```
- */
-interface AutocompleteContribution {
-  /**
-   * Selector name strings to add to the autocomplete suggestion pool.
-   *
-   * @default undefined
-   */
-  selectors?: Arrayable<string>;
-  /**
-   * Shortcut name strings to add to the autocomplete suggestion pool.
-   *
-   * @default undefined
-   */
-  shortcuts?: Arrayable<string>;
+/** Owner-bound initialization capability exposed only through one plugin context. */
+interface PikaRegistrationCapability {
+  /** Registers one first-level static authoring extension during this plugin's active configureEngine hook. */
+  extendStatic: (name: string, implementation: unknown) => void;
+}
+//#endregion
+//#region src/typegen/snapshot.d.ts
+/** Path-free preview asset produced by deterministic Typegen finalization. */
+interface TypegenPreviewAsset {
+  /** Opaque semantic asset identity used only to bind a later host href. */
+  readonly id: string;
+  /** Raw preview content. The host owns physical materialization/content addressing. */
+  readonly content: string;
+  /** Media type describing the raw content (for example `image/svg+xml`). */
+  readonly mediaType: string;
+}
+/** Path-free reference from member documentation to one preview asset artifact. */
+interface TypegenPreviewImage {
+  readonly assetId: string;
+  /** Optional Markdown image alt text. */
+  readonly alt?: string;
+}
+/** Intentional semantic JSDoc tag owned by Typegen rather than arbitrary prose. */
+interface TypegenJSDocTag {
+  /** Tag name without the leading `@` (for example `deprecated`). */
+  readonly name: string;
+  /** Optional lexical-safe tag text. */
+  readonly text?: string;
+}
+/** Path-free rich documentation vocabulary for generated Typegen members. */
+interface TypegenDocumentation {
+  /** User/domain description rendered before preview content. */
+  readonly description?: string;
+  /** Resolved CSS semantics shown in the established PikaCSS fenced preview. */
+  readonly previewCss?: string;
+  /** Preview image references whose hrefs are deliberately host-owned. */
+  readonly previewImages?: readonly TypegenPreviewImage[];
+  /** Intentional Typegen-owned semantic JSDoc tags. */
+  readonly tags?: readonly TypegenJSDocTag[];
+}
+/** Managed Typegen attachment points contributed by one plugin. */
+interface TypegenContribution {
+  /** Stable contribution identity. Must be non-empty and unique per Engine. */
+  readonly id: string;
+  /** Verbatim supporting TypeScript declarations. */
+  readonly declarations?: string;
+  /** First-level Pika static-extension type roots. */
+  readonly pika?: Readonly<Record<string, string>>;
   /**
-   * Extra non-CSS property names to register in the autocomplete type surface (e.g. `__shortcut`, `__layer`).
-   *
-   * @default undefined
+   * TypeScript type reference contributed to the nested selector surface.
+   * @default `undefined`
    */
-  extraProperties?: Arrayable<string>;
+  readonly selectors?: string;
   /**
-   * Extra CSS property names (including custom properties) to register in the autocomplete type surface.
-   *
-   * @default undefined
+   * TypeScript type reference contributed to the generated property surface.
+   * @default `undefined`
    */
-  extraCssProperties?: Arrayable<string>;
+  readonly properties?: string;
   /**
-   * Map of property names to their accepted TypeScript type strings or literal value suggestions.
-   *
-   * @default undefined
+   * TypeScript type reference contributed to CSS property names and values.
+   * @default `undefined`
    */
-  properties?: Record<string, Arrayable<string>>;
+  readonly cssProperties?: string;
   /**
-   * Map of CSS property names to their accepted value suggestions.
-   *
-   * @default undefined
+   * TypeScript type reference contributed to CSS property value autocomplete.
+   * @default `undefined`
    */
-  cssProperties?: Record<string, Arrayable<string>>;
+  readonly cssPropertyValues?: string;
   /**
-   * Pattern-based entries that define how to generate expanded autocomplete suggestions.
-   *
-   * @default undefined
+   * TypeScript type reference that narrows or constrains generated properties.
+   * @default `undefined`
    */
-  patterns?: AutocompletePatternsConfig;
+  readonly propertyConstraints?: string;
 }
-/**
- * User-facing autocomplete configuration supplied in `EngineConfig.autocomplete`.
- *
- * @remarks Accepts the same shape as `AutocompleteContribution` but additionally allows `properties` and `cssProperties` as tuple arrays for ordered definitions. Normalized into the resolved config during engine initialization.
- *
- * @example
- * ```ts
- * const config: AutocompleteConfig = {
- *   selectors: ['hover', 'focus'],
- *   properties: [['spacing', ['sm', 'md', 'lg']]],
- * }
- * ```
- */
-interface AutocompleteConfig {
+/** Immutable semantic contribution captured in a finalized Typegen snapshot. */
+interface TypegenSnapshotContribution {
+  /** Stable contribution identity copied from the registered contribution. */
+  readonly id: string;
   /**
-   * Selector name strings for autocomplete suggestions.
-   *
-   * @default undefined
+   * Supporting TypeScript declarations captured for the finalized snapshot.
+   * @default `undefined`
    */
-  selectors?: Arrayable<string>;
+  readonly declarations?: string;
   /**
-   * Shortcut name strings for autocomplete suggestions.
-   *
-   * @default undefined
+   * First-level Pika static-extension type roots captured for the snapshot.
+   * @default `undefined`
    */
-  shortcuts?: Arrayable<string>;
+  readonly pika?: Readonly<Record<string, string>>;
   /**
-   * Extra non-CSS property names to surface in autocomplete.
-   *
-   * @default undefined
+   * TypeScript type reference contributed to the nested selector surface.
+   * @default `undefined`
    */
-  extraProperties?: Arrayable<string>;
+  readonly selectors?: string;
   /**
-   * Extra CSS property names to surface in autocomplete.
-   *
-   * @default undefined
+   * TypeScript type reference contributed to the generated property surface.
+   * @default `undefined`
    */
-  extraCssProperties?: Arrayable<string>;
+  readonly properties?: string;
   /**
-   * Property-to-type mapping. Accepts either a record or an ordered array of `[property, type]` tuples.
-   *
-   * @default undefined
+   * TypeScript type reference contributed to CSS property names and values.
+   * @default `undefined`
    */
-  properties?: [property: string, tsType: Arrayable<string>][] | Record<string, Arrayable<string>>;
+  readonly cssProperties?: string;
   /**
-   * CSS property-to-value mapping. Accepts either a record or an ordered array of `[property, value]` tuples.
-   *
-   * @default undefined
+   * TypeScript type reference contributed to CSS property value autocomplete.
+   * @default `undefined`
    */
-  cssProperties?: [property: string, value: Arrayable<string>][] | Record<string, Arrayable<string>>;
+  readonly cssPropertyValues?: string;
   /**
-   * Pattern-based entries for generating expanded autocomplete suggestions.
-   *
-   * @default undefined
+   * TypeScript type reference that narrows or constrains generated properties.
+   * @default `undefined`
    */
-  patterns?: AutocompletePatternsConfig;
+  readonly propertyConstraints?: string;
 }
-/**
- * Fully resolved form of `AutocompletePatternsConfig` where all arrayable values have been normalized into `Set` and `Map` collections.
- * @internal
- *
- * @remarks Produced during engine config resolution. Using `Set` and `Map` avoids duplicate entries and enables efficient incremental appends by plugins.
- *
- * @example
- * ```ts
- * const patterns: ResolvedAutocompletePatternsConfig = {
- *   selectors: new Set(['hover']),
- *   shortcuts: new Set(),
- *   properties: new Map(),
- *   cssProperties: new Map(),
- * }
- * ```
- */
-interface ResolvedAutocompletePatternsConfig {
-  /** Set of resolved selector autocomplete patterns. */
-  selectors: Set<string>;
-  /** Set of resolved shortcut autocomplete patterns. */
-  shortcuts: Set<string>;
-  /** Map of property names to their expanded autocomplete value patterns. */
-  properties: Map<string, string[]>;
-  /** Map of CSS property names to their expanded autocomplete value patterns. */
-  cssProperties: Map<string, string[]>;
-}
-/**
- * Fully resolved autocomplete configuration used at runtime by the engine and integration layer.
- * @internal
- *
- * @remarks All user-facing arrayable and record values are normalized into `Set`/`Map` structures during engine config resolution. Plugins append entries via `engine.appendAutocomplete()` which mutates this structure in place.
- *
- * @example
- * ```ts
- * const ac: ResolvedAutocompleteConfig = {
- *   selectors: new Set(['hover']),
- *   shortcuts: new Set(),
- *   extraProperties: new Set(['__layer']),
- *   extraCssProperties: new Set(),
- *   properties: new Map(),
- *   cssProperties: new Map(),
- *   patterns: { selectors: new Set(), shortcuts: new Set(), properties: new Map(), cssProperties: new Map() },
- * }
- * ```
- */
-interface ResolvedAutocompleteConfig {
-  /** Known selector names available for autocomplete. */
-  selectors: Set<string>;
-  /** Known shortcut names available for autocomplete. */
-  shortcuts: Set<string>;
-  /** Non-CSS property names injected by plugins (e.g. `__shortcut`, `__layer`, `__important`). */
-  extraProperties: Set<string>;
-  /** Extra CSS property names (including custom properties) injected by plugins. */
-  extraCssProperties: Set<string>;
-  /** Property-to-type mappings for TypeScript type generation. */
-  properties: Map<string, string[]>;
-  /** CSS property-to-value mappings for value-level autocomplete. */
-  cssProperties: Map<string, string[]>;
-  /** Resolved pattern-based autocomplete entries. */
-  patterns: ResolvedAutocompletePatternsConfig;
+/** Path-independent Typegen semantic state produced by Engine finalization. */
+interface TypegenSnapshot {
+  /** Contributions captured and sorted when the Engine was finalized. */
+  readonly contributions: readonly TypegenSnapshotContribution[];
+  /** Path-free preview artifacts; host materialization binds these ids to hrefs later. */
+  readonly previewAssets: readonly TypegenPreviewAsset[];
 }
-/**
- * Shape contract for the autocomplete type map that plugins augment via module augmentation on `PikaAugment`.
- * @internal
- *
- * @remarks Each member corresponds to a dimension of the autocomplete surface. Plugin authors extend `PikaAugment` with a `DefineAutocomplete` entry whose members populate IDE completions.
- *
- * @example
- * ```ts
- * interface _Autocomplete {
- *   Selector: 'hover' | 'focus'
- *   Shortcut: 'btn' | 'card'
- *   Layer: 'base' | 'components'
- *   PropertyValue: { spacing: 'sm' | 'md' }
- *   CSSPropertyValue: { color: 'primary' | 'secondary' }
- * }
- * ```
- */
-interface _Autocomplete {
-  /** Union of known selector names for IDE autocomplete. */
-  Selector: UnionString;
-  /** Union of known shortcut names for IDE autocomplete. */
-  Shortcut: UnionString;
-  /** Union of known layer names for IDE autocomplete. */
-  Layer: UnionString;
-  /** Record mapping extra property names to their accepted value types for IDE autocomplete. */
-  PropertyValue: Record<string, unknown>;
-  /** Record mapping CSS property names to their accepted value unions for IDE autocomplete. */
-  CSSPropertyValue: Record<string, UnionString>;
+//#endregion
+//#region src/typegen/jsdoc.d.ts
+/** Host binding used only while rendering final TypeScript source. */
+interface TypegenJSDocRenderBindings {
+  /**
+   * Resolves one path-free semantic preview image to a Markdown href after the
+   * host has successfully materialized it. Returning nullish omits that image.
+   */
+  readonly resolvePreviewImageHref?: (assetId: string) => string | null | undefined;
 }
 /**
- * Identity helper that constrains the type parameter to the `_Autocomplete` shape, used inside `PikaAugment` to define the autocomplete map for a plugin.
+ * Renders one lexical-safe JSDoc block from path-free semantic documentation.
  *
- * @typeParam A - The autocomplete map satisfying the `_Autocomplete` contract.
+ * @remarks
+ * The renderer preserves the historical `### PikaCSS Preview` fenced-CSS
+ * convention and U+200E safety workaround. Arbitrary descriptions are prevented
+ * from becoming semantic JSDoc `@tags`. Preview-image hrefs are supplied only at
+ * final render time, so semantic snapshots never contain host paths or URIs.
  *
- * @remarks Provides compile-time validation that the augmented autocomplete map has all required members.
+ * @param documentation - Path-free description, preview, and semantic tags to render.
+ * @param bindings - Host callbacks used to resolve semantic preview asset IDs to hrefs.
+ * @param indent - Prefix applied to every line of the generated JSDoc block.
  *
- * @example
- * ```ts
- * declare module '@pikacss/core' {
- *   interface PikaAugment {
- *     Autocomplete: DefineAutocomplete<{
- *       Selector: 'hover' | 'focus'
- *       Shortcut: never
- *       Layer: 'base'
- *       PropertyValue: never
- *       CSSPropertyValue: never
- *     }>
- *   }
- * }
- * ```
- */
-type DefineAutocomplete<A extends _Autocomplete> = A;
-/**
- * Default autocomplete map used when no plugin provides an augmentation, with all dimensions set to `never`.
  * @internal
- *
- * @remarks Serves as the fallback in `ResolvedAutocomplete` so the engine always has a valid autocomplete shape even without any plugin augmentations.
- *
- * @example
- * ```ts
- * // When PikaAugment has no Autocomplete key:
- * type Resolved = ResolvedAutocomplete // EmptyAutocomplete
- * ```
  */
-type EmptyAutocomplete = DefineAutocomplete<{
-  Selector: never;
-  Shortcut: never;
-  Layer: never;
-  PropertyValue: never;
-  CSSPropertyValue: never;
-}>;
+declare function renderTypegenJSDoc(documentation: TypegenDocumentation, bindings?: TypegenJSDocRenderBindings, indent?: string): string[];
 //#endregion
-//#region src/atomic-style.d.ts
-/**
- * Mutable store holding all resolved atomic styles and their lookup indices for an engine instance.
- * @internal
- *
- * @remarks The store is created once per engine and mutated as new styles are resolved via `engine.use()`. It maintains four related indices: content-hash to ID, ID to full atomic style, base-key to ID list (for order-sensitive reuse), and ID to insertion order.
- *
- * @example
- * ```ts
- * const store = createEngineStore()
- * // store.atomicStyleIds: Map<serializedKey, 'pk-a'>
- * ```
- */
-interface EngineStore {
-  /** Map from serialized content keys to their assigned atomic style IDs. */
-  atomicStyleIds: Map<string, string>;
-  /** Map from atomic style ID to the full `AtomicStyle` object. */
-  atomicStyles: Map<string, AtomicStyle>;
-  /** Map from base content key to the list of atomic style IDs that share it (for order-sensitive styles). */
-  atomicStyleIdsByBaseKey: Map<string, string[]>;
-  /** Map from atomic style ID to its insertion order index, used for deterministic output ordering. */
-  atomicStyleOrder: Map<string, number>;
+//#region src/typegen/registry.d.ts
+/** Read-side engine-scoped Typegen manager. */
+interface TypegenManager {
+  /** Finalized immutable semantic snapshot. */
+  readonly snapshot: TypegenSnapshot;
+}
+/** Owner-bound initialization capability exposed only through one plugin context. */
+interface TypegenRegistrationCapability {
+  /** Registers one contribution during this plugin's active configureEngine hook. */
+  add: (contribution: TypegenContribution) => void;
 }
-//#endregion
-//#region src/extractor.d.ts
-/**
- * Function signature for the bound extraction function created by `createExtractFn`.
- * @internal
- *
- * @remarks Accepts a single style definition and returns the extracted content list. The plugin transform hooks and default selector are captured in the closure.
- *
- * @example
- * ```ts
- * const extractFn: ExtractFn = createExtractFn({ ... })
- * const contents = await extractFn({ color: 'red' })
- * ```
- */
-type ExtractFn = (styleDefinition: InternalStyleDefinition) => Promise<ExtractedStyleContent[]>;
 //#endregion
 //#region src/engine.d.ts
 /**
@@ -1333,6 +1007,8 @@ type ExtractFn = (styleDefinition: InternalStyleDefinition) => Promise<Extracted
  *
  * @remarks Core plugins (`important`, `variables`, `keyframes`, `selectors`, `shortcuts`) are prepended automatically. The function resolves plugins, runs all configuration hooks in sequence, and returns the ready-to-use engine.
  *
+ * The caller-owned `config` graph is treated as immutable input (#117): the engine clones it into an engine-local working copy before any plugin configuration hook runs, so plugin hooks that mutate their config (`config.layers ??= {}` and friends) never write back into caller-owned objects, and the same config object can be reused across sequential or concurrent `createEngine()` calls without accumulating setup mutations. Ordinary config data (plain objects/arrays, `Map`/`Set` contents, `Date`, `RegExp`) is recursively isolated — module-augmented plugin fields included; functions and other opaque class instances keep their identity and are treated as immutable values; the `plugins` array is copied while plugin definition objects keep their identity (#116).
+ *
  * @example
  * ```ts
  * const engine = await createEngine({ prefix: 'pk-', plugins: [myPlugin()] })
@@ -1342,7 +1018,7 @@ declare function createEngine(config?: EngineConfig, options?: CreateEngineOptio
 /**
  * The PikaCSS engine: manages atomic style resolution, rendering, preflights, and plugin hooks.
  *
- * @remarks Constructed via `createEngine()`. Holds the resolved configuration, the atomic style store, and exposes methods for processing style items (`use`), rendering CSS output (`renderPreflights`, `renderAtomicStyles`, `renderLayerOrderDeclaration`), and managing runtime extensions (`addPreflight`, `appendAutocomplete`, `appendCssImport`).
+ * @remarks Constructed via `createEngine()`. Holds the resolved configuration, the atomic style store, and exposes methods for processing style items (`use`), rendering CSS output (`renderPreflights`, `renderAtomicStyles`, `renderLayerOrderDeclaration`), and managing runtime extensions (`addPreflight`, `appendCssImport`).
  *
  * @example
  * ```ts
@@ -1352,22 +1028,23 @@ declare function createEngine(config?: EngineConfig, options?: CreateEngineOptio
  * ```
  */
 declare class Engine {
+  #private;
   /** The fully resolved engine configuration. */
   config: ResolvedEngineConfig;
   /** Instance-scoped diagnostic handler supplied by the host. */
   readonly onDiagnostic: DiagnosticHandler;
   /** Reference to the instance-scoped plugin hook dispatcher. */
   pluginHooks: ReturnType<typeof createEngineHooks>;
+  /** Finalized/read-side first-level Pika static authoring extension registry. */
+  readonly pika: PikaManager;
+  /** Finalized/read-side Typegen semantic registry. */
+  readonly typegen: TypegenManager;
   /** The extraction function that decomposes style definitions into atomic style contents. */
   extract: ExtractFn;
   /** The engine's runtime store holding registered atomic styles and their ID mappings. */
   store: EngineStore;
-  /**
-   * Absolute paths of external files this engine's config depends on (e.g. token files loaded by plugins).
-   *
-   * @remarks Plugins register paths via `addConfigDependency` during `configureEngine`. Integration layers (e.g. the unplugin) watch these files and re-create the engine when they change.
-   */
-  configDependencies: Set<string>;
+  /** Finalized external file and directory-membership dependencies for this engine. */
+  get configDependencies(): readonly EngineConfigDependency[];
   /**
    * Creates an engine instance from a resolved configuration.
    *
@@ -1380,7 +1057,7 @@ declare class Engine {
    * const engine = new Engine(resolvedConfig)
    * ```
    */
-  constructor(config: ResolvedEngineConfig, onDiagnostic?: DiagnosticHandler, pluginHooks?: ReturnType<typeof createEngineHooks>);
+  constructor(config: ResolvedEngineConfig, onDiagnostic?: DiagnosticHandler, pluginHooks?: ReturnType<typeof createEngineHooks>, atomicStyleIdStrategy?: AtomicStyleIdStrategy);
   /**
    * Reports a structured diagnostic to this engine instance's host handler.
    *
@@ -1404,18 +1081,19 @@ declare class Engine {
    */
   invokePreflight(fn: PreflightFn, isFormatted: boolean, ctx?: PreflightContext): Promise<string | PreflightDefinition>;
   /**
-   * Registers an external file path as a config dependency of this engine.
-   *
-   * @param path - The file path (ideally absolute) the current config was derived from.
+   * Registers a file dependency during Engine initialization.
    *
-   * @remarks Call from a plugin (typically in `configureEngine`) after loading data from disk. Integration layers watch registered paths and rebuild the engine when any of them changes.
-   *
-   * @example
-   * ```ts
-   * engine.addConfigDependency('/project/design.md')
-   * ```
+   * @param path - File path whose content/existence participates in Engine configuration semantics. Missing files are allowed.
+   * @throws If registration is attempted after Engine finalization.
    */
   addConfigDependency(path: string): void;
+  /**
+   * Registers a direct directory-membership dependency during Engine initialization.
+   *
+   * @param path - Directory path whose direct member create/delete/rename events invalidate Engine configuration semantics.
+   * @throws If registration is attempted after Engine finalization.
+   */
+  addConfigDirectoryMembershipDependency(path: string): void;
   /**
    * Fires the `preflightUpdated` hook to notify plugins that preflight content has changed.
    *
@@ -1433,7 +1111,7 @@ declare class Engine {
    *
    * @param atomicStyle - The atomic style that was just added to the store.
    *
-   * @remarks Called automatically by `use()` when a previously unseen atomic style is resolved.
+   * @remarks Called automatically by `commitUse()` when a previously unseen atomic style is registered. This is a committed notification: the style's ID, cache keys, and store indices are already established, so mutating the payload is unsupported — plugins that need to transform styles must use the provisional hooks (`transformStyleItems`, `transformStyleDefinitions`, `transformSelectors`, `transformStyleContents`) instead (#114).
    *
    * @example
    * ```ts
@@ -1442,63 +1120,80 @@ declare class Engine {
    */
   notifyAtomicStyleAdded(atomicStyle: AtomicStyle): void;
   /**
-   * Fires the `autocompleteConfigUpdated` hook to notify plugins that autocomplete entries changed.
+   * Appends a CSS `@import` statement to the preflight output.
    *
+   * @param cssImport - The raw `@import` string (a trailing semicolon is appended if missing).
    *
-   * @remarks Called automatically after `appendAutocomplete` when the contribution modifies the resolved autocomplete config.
+   * @remarks Deduplicates imports. Fires `preflightUpdated` when a new import is added.
    *
    * @example
    * ```ts
-   * engine.notifyAutocompleteConfigUpdated()
+   * engine.appendCssImport('@import url("https://fonts.googleapis.com/css2?family=Inter")')
    * ```
    */
-  notifyAutocompleteConfigUpdated(): void;
+  appendCssImport(cssImport: string): void;
   /**
-   * Merges an autocomplete contribution into the resolved autocomplete config.
+   * Registers a new preflight that will be rendered before atomic styles.
    *
-   * @param contribution - The autocomplete entries to append (selectors, properties, CSS properties, etc.).
+   * @param preflight - A preflight definition: a function, a static string/object, or a wrapper with `layer`/`id` metadata.
    *
-   * @remarks Delegates to the `appendAutocomplete` utility and fires `autocompleteConfigUpdated` if the config was actually modified.
+   * @remarks The preflight is resolved into a `ResolvedPreflight` (extracting optional `layer` and `id`) and appended to `config.preflights`. Fires `preflightUpdated` so plugins and the integration layer know to re-render.
    *
    * @example
    * ```ts
-   * engine.appendAutocomplete({ selectors: 'hover', cssProperties: { color: 'red' } })
+   * engine.addPreflight({ layer: 'base', preflight: '*, *::before { box-sizing: border-box; }' })
    * ```
    */
-  appendAutocomplete(contribution: AutocompleteContribution): void;
+  addPreflight(preflight: Preflight): void;
   /**
-   * Appends a CSS `@import` statement to the preflight output.
+   * Provisionally resolves style items into a commit-ready plan without touching committed engine state.
    *
-   * @param cssImport - The raw `@import` string (a trailing semicolon is appended if missing).
+   * @param itemList - Style items to process: string references (shortcuts) and/or style definition objects.
+   * @returns A promise of the {@link StyleUsePlan} to pass to `commitUse()`.
    *
-   * @remarks Deduplicates imports. Fires `preflightUpdated` when a new import is added.
+   * @remarks
+   * Runs the full provisional pipeline: `transformStyleItems`, extraction
+   * (`transformStyleDefinitions`/`transformSelectors`), normalization, and the
+   * normalized-content seam `transformStyleContents`. It allocates no atomic
+   * style IDs, mutates no `EngineStore` state, and fires no committed
+   * notifications — a rejection anywhere leaves the engine exactly as it was.
+   * Plans deliberately carry no IDs: reuse-vs-fresh decisions read live store
+   * state and are only valid inside `commitUse()` (#114).
    *
    * @example
    * ```ts
-   * engine.appendCssImport('@import url("https://fonts.googleapis.com/css2?family=Inter")')
+   * const plan = await engine.prepareUse({ color: 'red' })
+   * const ids = engine.commitUse(plan)
    * ```
    */
-  appendCssImport(cssImport: string): void;
+  prepareUse(...itemList: InternalStyleItem[]): Promise<StyleUsePlan>;
   /**
-   * Registers a new preflight that will be rendered before atomic styles.
+   * Commits a prepared plan: allocates/reuses atomic style IDs and registers new styles in the store.
    *
-   * @param preflight - A preflight definition: a function, a static string/object, or a wrapper with `layer`/`id` metadata.
+   * @param plan - A plan produced by `prepareUse()`.
+   * @returns An array containing any unresolved string references first, followed by atomic style IDs in resolution order.
    *
-   * @remarks The preflight is resolved into a `ResolvedPreflight` (extracting optional `layer` and `id`) and appended to `config.preflights`. Fires `preflightUpdated` so plugins and the integration layer know to re-render.
+   * @remarks
+   * This is the short, mutation-critical section and MUST stay synchronous:
+   * integration layers commit whole modules inside a revision/epoch-checked
+   * synchronous block, so an `await` here would reopen the stale-commit race
+   * (#114). `atomicStyleAdded` fires per newly registered style as a committed
+   * notification; a throwing observer is reported through the diagnostic
+   * context but never rolls back the already-committed registration.
    *
    * @example
    * ```ts
-   * engine.addPreflight({ layer: 'base', preflight: '*, *::before { box-sizing: border-box; }' })
+   * const ids = engine.commitUse(await engine.prepareUse({ color: 'red' }))
    * ```
    */
-  addPreflight(preflight: Preflight): void;
+  commitUse(plan: StyleUsePlan): string[];
   /**
    * Processes style items through the plugin pipeline and registers the resulting atomic styles in the store.
    *
    * @param itemList - Style items to process: string references (shortcuts) and/or style definition objects.
    * @returns An array containing any unresolved string references first, followed by atomic style IDs in resolution order.
    *
-   * @remarks Runs `transformStyleItems` and `extractStyleDefinition` hooks, resolves each extracted content into an atomic style, deduplicates by base key, and fires `atomicStyleAdded` for new entries.
+   * @remarks Equivalent to `commitUse(await prepareUse(...itemList))` — the convenience path for direct consumers. Integration layers that need whole-module transactionality call the two phases separately (#114).
    *
    * @example
    * ```ts
@@ -1529,12 +1224,11 @@ declare class Engine {
    * Renders atomic styles into a CSS string, optionally filtered by ID and grouped by layer.
    *
    * @param isFormatted - Whether to produce human-readable CSS with newlines and indentation.
-   * @param options - Optional filtering: `atomicStyleIds` to render a subset, `isPreview` to use placeholder IDs.
+   * @param options - Optional filtering: `atomicStyleIds` to render a subset.
    * @param options.atomicStyleIds - Specific atomic style IDs to render instead of the full store.
-   * @param options.isPreview - Whether to keep placeholder IDs instead of substituting real class names.
    * @returns The rendered atomic-style CSS.
    *
-   * @remarks Styles are sorted by rendering weight (selector specificity depth), grouped into configured `@layer` blocks, and rendered. When `isPreview` is true, atomic style IDs remain as placeholders for tooling previews.
+   * @remarks Styles are sorted by rendering weight (selector specificity depth), grouped into configured `@layer` blocks, and rendered.
    *
    * @example
    * ```ts
@@ -1543,7 +1237,6 @@ declare class Engine {
    */
   renderAtomicStyles(isFormatted: boolean, options?: {
     atomicStyleIds?: string[];
-    isPreview?: boolean;
   }): Promise<string>;
   /**
    * Renders the CSS `@layer` order declaration for all configured layers.
@@ -1575,6 +1268,23 @@ declare class Engine {
  * ```
  */
 declare function sortLayerNames(layers: Record<string, number>): string[];
+/**
+ * The provisional result of `engine.prepareUse()`: fully transformed, extracted,
+ * and normalized style contents plus unresolved string references, ready to be
+ * committed via `engine.commitUse()`.
+ *
+ * @remarks
+ * A plan deliberately carries no atomic style IDs and no base-key resolutions:
+ * reuse-vs-fresh-ID decisions read live `EngineStore` state and are only valid
+ * at the moment `commitUse()` runs. Discarding an uncommitted plan has no
+ * effect on the engine (#114).
+ */
+interface StyleUsePlan {
+  /** String references no plugin resolved; echoed back verbatim by `commitUse()`. */
+  unknown: Set<string>;
+  /** Deduplicated, normalized style contents in resolution order. */
+  contents: StyleContent[];
+}
 //#endregion
 //#region src/plugin.d.ts
 type DefineHooks<Hooks extends Record<string, [type: 'sync' | 'async', payload: unknown, returnValue?: unknown]>> = Hooks;
@@ -1586,35 +1296,86 @@ type EngineHooksDefinition = DefineHooks<{
   transformSelectors: ['async', selectors: string[]];
   transformStyleItems: ['async', styleItems: ResolvedStyleItem[]];
   transformStyleDefinitions: ['async', styleDefinitions: ResolvedStyleDefinition[]];
+  transformStyleContents: ['async', styleContents: StyleContent[]];
   preflightUpdated: ['sync', void];
   atomicStyleAdded: ['sync', AtomicStyle];
-  autocompleteConfigUpdated: ['sync', void];
 }>;
+/**
+ * Owner-bound facade supplied only while one plugin configures an Engine.
+ *
+ * @remarks
+ * The facade is scoped to one plugin definition and one awaited `configureEngine`
+ * invocation. `pika` and `typegen` capabilities close when that invocation
+ * settles. `runtime` is the underlying Engine for existing Engine APIs.
+ */
+interface EngineConfigurator<State = any> extends EnginePluginContext<State> {
+  /** Underlying Engine being configured. */
+  readonly runtime: Engine;
+  /** Owner-bound Pika registration capability for this configureEngine invocation. */
+  readonly pika: PikaRegistrationCapability;
+  /** Owner-bound Typegen registration capability for this configureEngine invocation. */
+  readonly typegen: TypegenRegistrationCapability;
+}
 type HookParams<H extends [type: 'sync' | 'async', payload: any, returnValue?: any]> = H[1] extends void ? [] : [payload: H[1]];
-type PluginHookParams<H extends [type: 'sync' | 'async', payload: any, returnValue?: any]> = H[1] extends void ? [context?: EnginePluginContext] : [payload: H[1], context?: EnginePluginContext];
+type PluginHookParams<H extends [type: 'sync' | 'async', payload: any, returnValue?: any], State = any> = H[1] extends void ? [context: EnginePluginContext<State>] : [payload: H[1], context: EnginePluginContext<State>];
 type HookReturnType<H extends [type: 'sync' | 'async', payload: any, returnValue?: any]> = H extends [any, any, infer R] ? H[0] extends 'async' ? Promise<R> : R : H[0] extends 'async' ? Promise<H[1]> : H[1];
 type EngineHooks = { [K in keyof EngineHooksDefinition]: (plugins: EnginePlugin[], ...params: HookParams<EngineHooksDefinition[K]>) => HookReturnType<EngineHooksDefinition[K]> };
 /**
  * Creates an engine-local hook dispatcher bound to one diagnostic context.
  *
  * @internal
+ * @remarks
+ * Each dispatcher instance owns one plugin-context store: every plugin
+ * definition gets exactly one `EnginePluginContext` (with `state` initialized
+ * lazily via `createState()`) per dispatcher — i.e. per engine, since
+ * `createEngine` creates one dispatcher per engine (#116). The same plugin
+ * definition used with another dispatcher/engine gets a distinct context and
+ * distinct state.
  */
-declare function createEngineHooks(context: EnginePluginContext): EngineHooks;
-type EnginePluginHooksOptions = { [K in keyof EngineHooksDefinition]?: EngineHooksDefinition[K][0] extends 'async' ? (...params: PluginHookParams<EngineHooksDefinition[K]>) => Awaitable<EngineHooksDefinition[K][1] | void> : (...params: PluginHookParams<EngineHooksDefinition[K]>) => EngineHooksDefinition[K][1] | void };
-/** Describes an engine plugin that can hook into the PikaCSS engine lifecycle. */
-interface EnginePlugin extends EnginePluginHooksOptions {
+declare function createEngineHooks(context: Pick<EnginePluginContext, 'onDiagnostic'> & Partial<Pick<EnginePluginContext, 'host'>>): EngineHooks;
+type EnginePluginHooksOptions<State = any> = { [K in keyof EngineHooksDefinition]?: K extends 'configureEngine' ? (configurator: EngineConfigurator<State>) => Awaitable<void> : EngineHooksDefinition[K][0] extends 'async' ? (...params: PluginHookParams<EngineHooksDefinition[K], State>) => Awaitable<EngineHooksDefinition[K][1] | void> : (...params: PluginHookParams<EngineHooksDefinition[K], State>) => EngineHooksDefinition[K][1] | void };
+/**
+ * Describes an engine plugin that can hook into the PikaCSS engine lifecycle.
+ *
+ * @remarks
+ * A plugin object is a reusable **definition**, not a single-engine resource
+ * (#116): the same object may be passed to any number of `createEngine()`
+ * calls, sequentially or concurrently. Mutable per-engine data therefore must
+ * never live in the plugin factory's closure — declare it via `createState`
+ * and read/write it through hook `context.state` or `EngineConfigurator.state`, which the engine keeps isolated
+ * per plugin/engine pair. Factory arguments that are never mutated may stay in
+ * the closure as immutable definition configuration.
+ */
+interface EnginePlugin<State = any> extends EnginePluginHooksOptions<State> {
   /** The unique human-readable name identifying this plugin in diagnostics. */
   name: string;
   /** Controls execution order relative to other plugins. */
   order?: 'pre' | 'post';
+  /**
+   * Initializes this plugin's engine-local state.
+   *
+   * @returns The fresh state for one engine.
+   *
+   * @remarks
+   * Invoked by the engine at most once per plugin definition **per engine**,
+   * before the first hook of this plugin runs for that engine; every hook
+   * invocation of that plugin/engine pair then receives the same object via
+   * `context.state`. Another engine reusing the same definition gets a
+   * distinct state object. Stateless plugins simply omit this.
+   */
+  createState?: () => State;
 }
 /**
  * Identity helper that provides type inference for an engine plugin definition.
  *
  * @param plugin - The plugin definition to return unchanged.
  * @returns The same plugin instance.
+ *
+ * @remarks
+ * When the plugin declares `createState`, the state type is inferred from its
+ * return value and every hook's `context.state` is typed accordingly.
  */
-declare function defineEnginePlugin(plugin: EnginePlugin): EnginePlugin;
+declare function defineEnginePlugin<State = void>(plugin: EnginePlugin<State>): EnginePlugin<State>;
 //#endregion
 //#region src/generated/csstype.d.ts
 type UnionString$1 = string & {};
@@ -19583,7 +19344,9 @@ type AtRules = AtRules.Regular | AtRules.Nested;
 type CSSPseudos$1 = "$::-moz-progress-bar" | "$::-moz-range-progress" | "$::-moz-range-thumb" | "$::-moz-range-track" | "$::-ms-browse" | "$::-ms-check" | "$::-ms-clear" | "$::-ms-expand" | "$::-ms-fill" | "$::-ms-fill-lower" | "$::-ms-fill-upper" | "$::-ms-reveal" | "$::-ms-thumb" | "$::-ms-ticks-after" | "$::-ms-ticks-before" | "$::-ms-tooltip" | "$::-ms-track" | "$::-ms-value" | "$::-webkit-progress-bar" | "$::-webkit-progress-inner-value" | "$::-webkit-progress-value" | "$::-webkit-slider-runnable-track" | "$::-webkit-slider-thumb" | "$::after" | "$::backdrop" | "$::before" | "$::checkmark" | "$::clear-icon" | "$::color-swatch" | "$::column" | "$::cue" | "$::cue()" | "$::cue-region" | "$::cue-region()" | "$::details-content" | "$::field-component" | "$::field-separator" | "$::field-text" | "$::file-selector-button" | "$::first-letter" | "$::first-line" | "$::grammar-error" | "$::highlight()" | "$::marker" | "$::nth-fragment()" | "$::part()" | "$::picker()" | "$::picker-icon" | "$::placeholder" | "$::reveal-icon" | "$::scroll-button()" | "$::scroll-marker" | "$::scroll-marker-group" | "$::search-text" | "$::selection" | "$::slider-fill" | "$::slider-thumb" | "$::slider-track" | "$::slotted()" | "$::spelling-error" | "$::step-control" | "$::step-down" | "$::step-up" | "$::target-text" | "$::view-transition" | "$::view-transition-group()" | "$::view-transition-group-children()" | "$::view-transition-image-pair()" | "$::view-transition-new()" | "$::view-transition-old()" | "$:active" | "$:active-view-transition" | "$:active-view-transition-type()" | "$:after" | "$:animated-image" | "$:any-link" | "$:autofill" | "$:before" | "$:blank" | "$:buffering" | "$:checked" | "$:current" | "$:current()" | "$:default" | "$:defined" | "$:dir()" | "$:disabled" | "$:empty" | "$:enabled" | "$:first" | "$:first-child" | "$:first-letter" | "$:first-line" | "$:first-of-page" | "$:first-of-type" | "$:focus" | "$:focus-visible" | "$:focus-within" | "$:fullscreen" | "$:future" | "$:has()" | "$:has-slotted" | "$:heading" | "$:heading()" | "$:high-value" | "$:host" | "$:host()" | "$:host-context()" | "$:hover" | "$:in-range" | "$:indeterminate" | "$:interest-source" | "$:interest-target" | "$:invalid" | "$:is()" | "$:lang()" | "$:last-child" | "$:last-of-page" | "$:last-of-type" | "$:left" | "$:link" | "$:link-to()" | "$:local-link" | "$:low-value" | "$:matches()" | "$:modal" | "$:muted" | "$:nav-source" | "$:not()" | "$:nth()" | "$:nth-child()" | "$:nth-col()" | "$:nth-last-child()" | "$:nth-last-col()" | "$:nth-last-of-type()" | "$:nth-of-page()" | "$:nth-of-type()" | "$:only-child" | "$:only-of-type" | "$:open" | "$:optimal-value" | "$:optional" | "$:out-of-range" | "$:past" | "$:paused" | "$:picture-in-picture" | "$:placeholder-shown" | "$:playing" | "$:popover-open" | "$:read-only" | "$:read-write" | "$:required" | "$:right" | "$:root" | "$:scope" | "$:seeking" | "$:snapped" | "$:snapped-block" | "$:snapped-inline" | "$:snapped-x" | "$:snapped-y" | "$:stalled" | "$:start-of-page" | "$:state()" | "$:target" | "$:target-after" | "$:target-before" | "$:target-current" | "$:target-within" | "$:unchecked" | "$:user-invalid" | "$:user-valid" | "$:valid" | "$:visited" | "$:volume-locked" | "$:where()" | "$:xr-overlay";
 type AutocompleteLookup<TValueMap, TRelatedKeys extends string> = [TValueMap] extends [never] ? never : TRelatedKeys extends keyof TValueMap ? TValueMap[TRelatedKeys] : never;
 type PropertyInputAtom<TValueMap, BaseValue, TRelatedKeys extends string> = UnionString$1 | BaseValue | AutocompleteLookup<TValueMap, TRelatedKeys | "*">;
+/** CSS property input value with optional Typegen autocomplete and fallback values. */
 type PropertyInputValue<TValueMap, BaseValue, TRelatedKeys extends string = never> = PropertyInputAtom<TValueMap, BaseValue, TRelatedKeys> | [value: PropertyInputAtom<TValueMap, BaseValue, TRelatedKeys>, fallback: Array<PropertyInputAtom<TValueMap, BaseValue, TRelatedKeys>>] | null | undefined;
+/** Camel-case CSS property inputs used by the generated Typegen style definition. */
 interface PropertiesInput<TValueMap = never, TLength = DefaultTLength, TTime = DefaultTTime> {
   /**
    * ❌ Baseline: Not widely available
@@ -27632,6 +27395,7 @@ interface PropertiesInput<TValueMap = never, TLength = DefaultTLength, TTime = D
    */
   zoom?: PropertyInputValue<TValueMap, Property.Zoom, PropertyRelatedNames["zoom"]> | undefined;
 }
+/** Kebab-case CSS property inputs used by the generated Typegen style definition. */
 interface PropertiesHyphenInput<TValueMap = never, TLength = DefaultTLength, TTime = DefaultTTime> {
   /**
    *
@@ -36675,6 +36439,189 @@ declare namespace DataType {
   type VisualBox = "border-box" | "content-box" | "padding-box";
 }
 //#endregion
+//#region src/types/utils.d.ts
+/**
+ * Represents `null` or `undefined`, used throughout the engine to express optional absence.
+ *
+ * @remarks Prefer this alias over inlining `null | undefined` for consistency across the codebase.
+ *
+ * @example
+ * ```ts
+ * function process(value: string | Nullish) {
+ *   if (value == null) return // handles both null and undefined
+ * }
+ * ```
+ */
+type Nullish = null | undefined;
+/**
+ * Branded string type that preserves literal union autocompletion while still accepting arbitrary strings.
+ *
+ * @remarks TypeScript narrows `string` to only known literals when a union is used. Intersecting with `{}` keeps the union suggestions in IDE autocomplete without rejecting unknown strings at the type level.
+ *
+ * @example
+ * ```ts
+ * type Color = 'red' | 'blue' | UnionString
+ * const c: Color = 'red'    // autocomplete suggests 'red' | 'blue'
+ * const d: Color = 'green'  // still valid
+ * ```
+ */
+type UnionString = string & {};
+/**
+ * A value that can be either a single item or an array of items.
+ *
+ * @typeParam T - The element type.
+ *
+ * @remarks Used pervasively in configuration surfaces so consumers can pass a single value or an array without explicit wrapping.
+ *
+ * @example
+ * ```ts
+ * function normalize<T>(input: Arrayable<T>): T[] {
+ *   return [input].flat() as T[]
+ * }
+ * normalize('a')     // ['a']
+ * normalize(['a','b']) // ['a','b']
+ * ```
+ */
+type Arrayable<T> = T | T[];
+/**
+ * A value that may be synchronous or wrapped in a `Promise`.
+ *
+ * @typeParam T - The resolved value type.
+ *
+ * @remarks Hook callbacks and plugin functions use this so authors can return either synchronously or asynchronously without the engine caring which.
+ *
+ * @example
+ * ```ts
+ * async function run(fn: () => Awaitable<string>) {
+ *   const result = await fn() // works whether fn is sync or async
+ * }
+ * ```
+ */
+type Awaitable<T> = T | Promise<T>;
+/**
+ * Converts a union type into an intersection of all its members.
+ *
+ * @typeParam U - The union type to intersect.
+ *
+ * @remarks Leverages contra-variant inference on function parameter positions. Useful internally for merging augmented module declarations into a single combined type.
+ *
+ * @example
+ * ```ts
+ * type U = { a: 1 } | { b: 2 }
+ * type I = UnionToIntersection<U> // { a: 1 } & { b: 2 }
+ * ```
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+/**
+ * Type-level strict equality check that resolves to `true` when `X` and `Y` are identical types.
+ *
+ * @typeParam X - First type to compare.
+ * @typeParam Y - Second type to compare.
+ *
+ * @remarks Uses the double-conditional-inference trick to detect structural and modifier differences that `extends` alone would miss (e.g. `readonly` vs mutable).
+ *
+ * @example
+ * ```ts
+ * type A = IsEqual<string, string>  // true
+ * type B = IsEqual<string, number>  // false
+ * ```
+ */
+type IsEqual<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+/**
+ * Evaluates to `true` when `T` is the `never` type, `false` otherwise.
+ *
+ * @typeParam T - The type to test.
+ *
+ * @remarks Wrapping `T` in a tuple prevents distributive conditional behavior that would otherwise collapse `never` before the check runs.
+ *
+ * @example
+ * ```ts
+ * type A = IsNever<never>  // true
+ * type B = IsNever<string> // false
+ * ```
+ */
+type IsNever<T> = [T] extends [never] ? true : false;
+/**
+ * Flattens an intersection type into a single object type for improved readability in IDE tooltips.
+ *
+ * @typeParam T - The intersection or object type to simplify.
+ *
+ * @remarks Mapped types re-enumerate all keys so the resulting hover preview shows a flat `{ ... }` shape instead of `A & B & C`.
+ *
+ * @example
+ * ```ts
+ * type Merged = Simplify<{ a: 1 } & { b: 2 }> // { a: 1; b: 2 }
+ * ```
+ */
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+/**
+ * Converts a camelCase or PascalCase string literal type to kebab-case at the type level.
+ *
+ * @typeParam T - The string literal type to convert. CSS custom properties (`--*`) are returned as-is.
+ *
+ * @remarks Used to map JavaScript-style property names to their CSS kebab-case equivalents during style extraction and rendering.
+ *
+ * @example
+ * ```ts
+ * type A = ToKebab<'backgroundColor'> // 'background-color'
+ * type B = ToKebab<'--my-var'>        // '--my-var'
+ * ```
+ */
+type ToKebab<T extends string> = T extends `--${string}` ? T : T extends `${infer A}${infer U}${infer Rest}` ? U extends Uppercase<U> ? U extends Lowercase<U> ? `${Lowercase<A>}${ToKebab<`${U}${Rest}`>}` : `${Lowercase<A>}-${ToKebab<`${Lowercase<U>}${Rest}`>}` : `${Lowercase<A>}${ToKebab<`${U}${Rest}`>}` : Lowercase<T>;
+/**
+ * Converts a kebab-case string literal type to camelCase at the type level.
+ *
+ * @typeParam T - The string literal type to convert. CSS custom properties (`--*`) are returned as-is.
+ *
+ * @remarks The inverse of `ToKebab`. Used to reconcile CSS-native property names back to their JavaScript equivalents during autocomplete resolution.
+ *
+ * @example
+ * ```ts
+ * type A = FromKebab<'background-color'> // 'backgroundColor'
+ * type B = FromKebab<'--my-var'>         // '--my-var'
+ * ```
+ */
+type FromKebab<T extends string> = T extends `--${string}` ? T : T extends `${infer Head}-${infer Tail}` ? `${Head}${FromKebab<Capitalize<Tail>>}` : T;
+/**
+ * Safely extracts the value type at key `K` from object type `Obj`, returning `never` when `Obj` is `never` or `K` is not a key of `Obj`.
+ *
+ * @typeParam Obj - The source object type.
+ * @typeParam K - The key to look up.
+ *
+ * @remarks Wrapping `Obj` in a tuple prevents distributive collapse when `Obj` is `never`.
+ *
+ * @example
+ * ```ts
+ * type V = GetValue<{ a: number }, 'a'> // number
+ * type N = GetValue<{ a: number }, 'b'> // never
+ * ```
+ */
+type GetValue<Obj, K extends string> = [Obj] extends [never] ? never : K extends keyof Obj ? Obj[K] : never;
+/**
+ * Distributively reads one key from every member of an object union.
+ *
+ * @remarks Unlike {@link GetValue}, this helper intentionally distributes over
+ * `Obj` so independent Typegen contributors add their values for the same key.
+ */
+type DistributiveGetValue<Obj, K extends PropertyKey> = Obj extends unknown ? K extends keyof Obj ? Obj[K] : never : never;
+/**
+ * Conditionally resolves `T[Key]` when the key exists and its value extends `I`; otherwise falls back to `Fallback`.
+ *
+ * @typeParam T - The source type to look up.
+ * @typeParam Key - The key to look up in `T`.
+ * @typeParam I - The constraint that `T[Key]` must satisfy.
+ * @typeParam Fallback - The default type returned when `Key` is missing or `T[Key]` does not extend `I`.
+ *
+ * @remarks Used extensively to resolve augmented types from `PikaAugment`, falling back to internal defaults when no augmentation is provided.
+ *
+ * @example
+ * ```ts
+ * type R = ResolveFrom<{ Foo: string }, 'Foo', string, 'default'> // string
+ * type D = ResolveFrom<{}, 'Foo', string, 'default'>              // 'default'
+ * ```
+ */
+type ResolveFrom<T, Key extends string, I, Fallback extends I> = Key extends keyof T ? T[Key] extends I ? T[Key] : Fallback : Fallback;
+//#endregion
 //#region src/types/public.d.ts
 /**
  * Mapping of CSS custom property names (starting with `--`) to their string values.
@@ -36728,29 +36675,15 @@ type CSSProperty = Extract<keyof CSSProperties, string>;
  * ```
  */
 type PropertyValue<T> = T | [value: T, fallback: T[]] | Nullish;
-type _CssPropertiesValue = ResolvedAutocompleteCSSPropertyValue;
-type _CssPropertiesValueWildcard = GetValue<_CssPropertiesValue, '*'>;
-type CSSPropertyInputValue<BaseValue, RelatedKey extends string> = PropertyValue<UnionString | BaseValue | GetValue<_CssPropertiesValue, RelatedKey> | _CssPropertiesValueWildcard>;
-type Properties_CSS_Camel = PropertiesInput<ResolvedAutocompleteCSSPropertyValue>;
-type Properties_CSS_Hyphen = PropertiesHyphenInput<ResolvedAutocompleteCSSPropertyValue>;
-type Properties_CSS_Vars = { [K in `--${string}` & {}]?: PropertyValue<UnionString | _CssPropertiesValueWildcard> };
-type Properties_ExtraCSS = { [Key in ResolvedExtraCSSProperty]?: CSSPropertyInputValue<GetValue<CSSProperties, Key>, Key | ToKebab<Key> | FromKebab<Key>> };
-type Properties_Extra = { [Key in ResolvedExtraProperty]?: GetValue<ResolvedAutocompletePropertyValue, Key> };
+type Properties_CSS_Camel = PropertiesInput;
+type Properties_CSS_Hyphen = PropertiesHyphenInput;
+type Properties_CSS_Vars = { [K in `--${string}` & {}]?: PropertyValue<UnionString> };
 /**
- * The full property map accepted in `pika()` style definitions, combining standard CSS (camelCase and hyphen-case), custom properties, plugin-injected CSS properties, and extra non-CSS properties.
- *
- * @remarks This interface merges five sub-property types: camelCase CSS, hyphen-case CSS, `--*` custom properties, extra CSS properties from plugins, and extra non-CSS properties (like `__shortcut`, `__layer`, `__important`). Each property value can be a plain string, a `[value, fallback[]]` tuple, or nullish.
- *
- * @example
- * ```ts
- * const props: Properties = {
- *   color: 'red',
- *   'font-size': '16px',
- *   '--my-color': 'blue',
- * }
- * ```
+ * The Core property map accepted before generated Typegen overlays domain/plugin
+ * contributions. Generated documents compose directives and extension-owned
+ * property/value surfaces on top of this baseline.
  */
-interface Properties extends Properties_CSS_Camel, Properties_CSS_Hyphen, Properties_CSS_Vars, Properties_ExtraCSS, Properties_Extra {}
+interface Properties extends Properties_CSS_Camel, Properties_CSS_Hyphen, Properties_CSS_Vars {}
 type CSSPseudos = CSSPseudos$1;
 /**
  * Union of valid CSS selector strings for nested style definitions, including CSS at-rules and pseudo-selectors (prefixed with `$`).
@@ -36768,7 +36701,7 @@ type CSSSelector = AtRules.Nested | CSSPseudos;
  * Union of all selector strings accepted in style definitions, including custom selectors from plugins, standard CSS selectors, and arbitrary strings.
  * @internal
  *
- * @remarks Combines `UnionString` (arbitrary strings), plugin-augmented `ResolvedAutocomplete['Selector']`, and built-in `CSSSelector` (at-rules + `$`-prefixed pseudos).
+ * @remarks Combines open-ended `UnionString` authoring with built-in `CSSSelector` (at-rules + `$`-prefixed pseudos). Generated configured-selector members are layered on by Typegen rather than global augmentation.
  *
  * @example
  * ```ts
@@ -36776,7 +36709,7 @@ type CSSSelector = AtRules.Nested | CSSPseudos;
  * const custom: Selector = 'dark' // plugin-defined selector
  * ```
  */
-type Selector$1 = UnionString | ResolvedAutocomplete['Selector'] | CSSSelector;
+type Selector$1 = UnionString | CSSSelector;
 /**
  * A nested style definition where keys are selector strings and values are property values, property maps, nested definitions, or arrays of style items.
  *
@@ -36816,34 +36749,27 @@ type StyleDefinition = Properties | StyleDefinitionMap;
  * const itemDef: StyleItem = { color: 'red' } // inline style
  * ```
  */
-type StyleItem = UnionString | ResolvedAutocomplete['Shortcut'] | StyleDefinition;
+type StyleItem = UnionString | StyleDefinition;
 //#endregion
 //#region src/types/shared.d.ts
 /**
- * Module augmentation interface that plugins extend to inject type-level information (autocomplete maps, property unions, selector unions) into the core type system.
+ * Legacy generated-file augmentation bridge retained temporarily while Integration migrates to finalized Typegen documents.
  *
- * @remarks Plugins declare `module '@pikacss/core' { interface PikaAugment { ... } }` to contribute types. At resolution time, the engine reads members such as `Autocomplete`, `Properties`, `Selector`, `StyleDefinition`, and `StyleItem` to narrow the public API type signatures.
+ * @remarks This is transitional plumbing, not a plugin authoring API. New authoring extensions use the Engine Typegen manager; the standalone Autocomplete dimension has been removed.
  *
- * @example
- * ```ts
- * declare module '@pikacss/core' {
- *   interface PikaAugment {
- *     Autocomplete: DefineAutocomplete<{ Selector: 'dark' | 'light', Shortcut: never, Layer: never, PropertyValue: never, CSSPropertyValue: never }>
- *   }
- * }
- * ```
  */
 interface PikaAugment {}
 /**
- * Internal alias for `PropertyValue<string | number>` used inside the engine.
+ * Runtime normalization input accepted inside the engine.
  * @internal
  *
- * @remarks Avoids repeatedly writing `PropertyValue<string | number>` in internal utility signatures. Represents a single CSS value, a `[value, fallback[]]` tuple, `null`, or `undefined`. Numbers are accepted because the csstype-based input types allow numeric values such as `0`; they are converted to strings during normalization.
+ * @remarks This type is deliberately broader than the public `Properties` authoring contract. The extractor tolerates arbitrary JavaScript numbers at runtime and normalizes them to strings so callers that bypass or erase the public types do not make the engine fragile. Do not infer `pika()` value support from this alias: generated public CSS types keep `<number>`, `<integer>`, percentages, custom properties, and other numeric grammars string-backed. A numeric `0` is admitted only through generated length-like positions where unitless zero is unambiguous.
  *
  * @example
  * ```ts
  * const val: InternalPropertyValue = ['red', ['blue', 'green']]
- * const zero: InternalPropertyValue = 0
+ * const runtimeZero: InternalPropertyValue = 0
+ * const runtimeNumber: InternalPropertyValue = 0.5 // tolerated internally; not a public pika() authoring value
  * ```
  */
 type InternalPropertyValue = PropertyValue<string | number>;
@@ -37000,79 +36926,6 @@ interface CSSStyleBlockBody {
 type CSSStyleBlocks = Map<string, CSSStyleBlockBody>;
 //#endregion
 //#region src/types/resolved.d.ts
-/**
- * The effective autocomplete map resolved from `PikaAugment.Autocomplete`, falling back to `EmptyAutocomplete` when no plugin augments it.
- * @internal
- *
- * @remarks This is the source-of-truth autocomplete shape that all downstream resolved types (`ResolvedAutocompletePropertyValue`, `ResolvedSelector`, etc.) derive from.
- *
- * @example
- * ```ts
- * // With augmentation: resolves to the plugin-provided map
- * // Without augmentation: resolves to EmptyAutocomplete
- * type AC = ResolvedAutocomplete
- * ```
- */
-type ResolvedAutocomplete = ResolveFrom<PikaAugment, 'Autocomplete', _Autocomplete, EmptyAutocomplete>;
-/**
- * The property-value record extracted from the resolved autocomplete map, mapping extra property names to their accepted value types.
- * @internal
- *
- * @remarks Used to derive the set of extra (non-CSS) properties and their value unions for type-safe `pika()` calls.
- *
- * @example
- * ```ts
- * type PV = ResolvedAutocompletePropertyValue // Record<string, unknown> or plugin-augmented map
- * ```
- */
-type ResolvedAutocompletePropertyValue = ResolvedAutocomplete['PropertyValue'];
-/**
- * The CSS property-value record extracted from the resolved autocomplete map, mapping CSS property names to their accepted value unions.
- * @internal
- *
- * @remarks Used to extend the standard `CSSProperties` value types with plugin-contributed suggestions (e.g. design token names for `color`).
- *
- * @example
- * ```ts
- * type CPV = ResolvedAutocompleteCSSPropertyValue // Record<string, UnionString> or plugin-augmented map
- * ```
- */
-type ResolvedAutocompleteCSSPropertyValue = ResolvedAutocomplete['CSSPropertyValue'];
-/**
- * Union of extra (non-CSS) property name strings derived from the resolved autocomplete property-value map.
- * @internal
- *
- * @remarks These property names (e.g. `__shortcut`, `__layer`, `__important`) are injected by core plugins into the `Properties` interface so they appear in `pika()` call autocomplete.
- *
- * @example
- * ```ts
- * type EP = ResolvedExtraProperty // '__shortcut' | '__layer' | ...
- * ```
- */
-type ResolvedExtraProperty = AutocompleteKeys<ResolvedAutocompletePropertyValue>;
-/**
- * Union of extra CSS property name strings derived from the resolved autocomplete CSS property-value map.
- * @internal
- *
- * @remarks Includes custom properties and vendor-specific properties registered by plugins (e.g. CSS variable names from the variables plugin).
- *
- * @example
- * ```ts
- * type ECP = ResolvedExtraCSSProperty // '--my-color' | '--spacing-sm' | ...
- * ```
- */
-type ResolvedExtraCSSProperty = AutocompleteKeys<ResolvedAutocompleteCSSPropertyValue>;
-/**
- * Union of known CSS `@layer` names, falling back to `UnionString` when no plugin augments the `Layer` dimension.
- *
- * @remarks When plugins define layer names via `DefineAutocomplete`, this type narrows to those names while still accepting arbitrary strings. Used in the `__layer` property autocomplete.
- *
- * @example
- * ```ts
- * type LN = ResolvedLayerName // 'base' | 'components' | ... or UnionString
- * ```
- */
-type ResolvedLayerName = IsNever<ResolvedAutocomplete['Layer']> extends true ? UnionString : ResolvedAutocomplete['Layer'];
 /**
  * The effective selector string type resolved from `PikaAugment.Selector`, falling back to plain `string`.
  * @internal
@@ -37101,14 +36954,14 @@ type ResolvedProperties = ResolveFrom<PikaAugment, 'Properties', any, InternalPr
  * The subset of `ResolvedProperties` that contains only standard CSS properties, computed by excluding extra (non-CSS) property keys.
  * @internal
  *
- * @remarks Omits keys that come from `ResolvedExtraProperty` (e.g. `__shortcut`, `__layer`), leaving only real CSS property names.
+ * @remarks Core extension/directive authoring no longer flows through global autocomplete augmentation; generated Typegen owns those overlays.
  *
  * @example
  * ```ts
- * type CP = ResolvedCSSProperties // Standard CSS properties minus __shortcut, __layer, etc.
+ * type CP = ResolvedCSSProperties // Effective CSS property surface
  * ```
  */
-type ResolvedCSSProperties = Omit<ResolvedProperties, ResolvedExtraProperty>;
+type ResolvedCSSProperties = ResolvedProperties;
 /**
  * The effective `StyleDefinition` type resolved from `PikaAugment.StyleDefinition`, falling back to the internal default.
  * @internal
@@ -37312,12 +37165,6 @@ interface EngineConfig {
    * @default `'utilities'`
    */
   defaultUtilitiesLayer?: string;
-  /**
-   * Autocomplete configuration for IDE integration and code generation type narrowing.
-   *
-   * @default `{}`
-   */
-  autocomplete?: AutocompleteConfig;
 }
 /**
  * Fully resolved engine configuration produced after plugin hooks have processed the raw config.
@@ -37344,8 +37191,6 @@ interface ResolvedEngineConfig {
   preflights: ResolvedPreflight[];
   /** Deduplicated and semicolon-terminated CSS `@import` statements. */
   cssImports: string[];
-  /** Resolved autocomplete configuration with `Set`/`Map` collections for efficient incremental appending. */
-  autocomplete: ResolvedAutocompleteConfig;
   /** CSS `@layer` name-to-order mapping used for ordering layer blocks in output. */
   layers: Record<string, number>;
   /** Name of the default `@layer` for preflight styles. */
@@ -37354,6 +37199,32 @@ interface ResolvedEngineConfig {
   defaultUtilitiesLayer: string;
 }
 //#endregion
+//#region src/typegen/render.d.ts
+/** Output shape of the configured base Pika callable. */
+type TransformedFormat = 'string' | 'array';
+/** Host/project binding for one isolated Engine Typegen snapshot. */
+interface TypegenRenderUnit {
+  /** Finalized semantic Typegen state to compose into the generated declaration namespace. */
+  readonly snapshot: TypegenSnapshot;
+  /** Globally visible configured Pika callable identifier. */
+  readonly fnName: string;
+  /** Runtime transform shape of the base callable. */
+  readonly transformedFormat: TransformedFormat;
+  /** Public package specifier from which Core authoring types are consumed. */
+  readonly publicModule: string;
+  /** Host-bound preview href resolution scoped to this isolated snapshot. */
+  readonly hostBindings?: TypegenJSDocRenderBindings;
+  /** Whether this host needs Vue template-instance globals for the callable. */
+  readonly vueTemplateGlobals?: boolean;
+}
+/**
+ * Renders one collision-safe TypeScript declaration document from isolated
+ * finalized Engine Typegen snapshots and explicit project/host bindings.
+ *
+ * @param units - Isolated finalized snapshots and host bindings to render as one declaration document.
+ */
+declare function renderTypegenDocument(units: readonly TypegenRenderUnit[]): string;
+//#endregion
 //#region src/utils.d.ts
 /**
  * Creates a scoped logger with configurable log-level functions and a toggleable debug mode.
@@ -37439,24 +37310,6 @@ declare function isPlainObjectRecord(value: unknown): value is Record<string, un
  * ```
  */
 declare function escapeRegExp(value: string): string;
-/**
- * Merges an `AutocompleteContribution` or `AutocompleteConfig` into the resolved autocomplete state, returning whether any entry changed.
- *
- * @param config - The resolved engine config (or a subset with the `autocomplete` field) to mutate.
- * @param contribution - The autocomplete entries to merge in.
- * @returns `true` if any selector, shortcut, property, CSS property, or pattern entry was added or extended.
- *
- * @remarks Called by `engine.appendAutocomplete()` and during initial config resolution. Each sub-field (selectors, shortcuts, etc.) is independently merged and the function returns `true` if any of them changed, which triggers an `autocompleteConfigUpdated` notification.
- *
- * @example
- * ```ts
- * const changed = appendAutocomplete(resolvedConfig, {
- *   selectors: 'dark',
- *   cssProperties: { color: 'primary' },
- * })
- * ```
- */
-declare function appendAutocomplete(config: Pick<ResolvedEngineConfig, 'autocomplete'>, contribution: AutocompleteContribution | AutocompleteConfig): boolean;
 /**
  * Serializes a `CSSStyleBlocks` tree into a CSS string, optionally formatted with indentation and newlines.
  *
@@ -37485,13 +37338,18 @@ declare function renderCSSStyleBlocks(blocks: CSSStyleBlocks, isFormatted: boole
  * @param config - The engine configuration object.
  * @returns The same configuration object, unchanged.
  *
- * @remarks A compile-time-only helper with no runtime effect. Useful in `pika.config.ts` files for IDE support.
+ * @remarks A compile-time-only helper with no runtime effect. Use it for low-level `EngineConfig` authoring or as a typed value nested under the canonical project `defineConfig({ engine: ... })` surface. It is not itself the default-export root for `pika.config.*`.
  *
  * @example
  * ```ts
- * export default defineEngineConfig({ prefix: 'pk-', plugins: [myPlugin()] })
+ * import { defineEngineConfig } from '@pikacss/core'
+ *
+ * const engineConfig = defineEngineConfig({
+ *   prefix: 'pk-',
+ *   plugins: [],
+ * })
  * ```
  */
 declare function defineEngineConfig<const T extends EngineConfig>(config: T): T;
 //#endregion
-export { Arrayable, type AutocompleteConfig, type AutocompleteContribution, type AutocompletePatternsConfig, Awaitable, type CSSProperty, type CSSSelector, type CSSStyleBlockBody, type CSSStyleBlocks, type CreateEngineOptions, type DefineAutocomplete, type Diagnostic, type DiagnosticHandler, type DiagnosticLevel, type Engine, type EngineConfig, type EnginePlugin, type EnginePluginContext, FromKebab, GetValue, ImportantConfig, IsEqual, IsNever, Keyframes, KeyframesConfig, KeyframesProgress, Nullish, type PikaAugment, type Preflight, type PreflightDefinition, type PreflightFn, type Properties, type PropertyValue, ResolveFrom, type ResolvedLayerName, type ResolvedPreflight, Selector, SelectorsConfig, Shortcut, ShortcutsConfig, Simplify, type StyleDefinition, type StyleDefinitionMap, type StyleItem, ToKebab, UnionString, UnionToIntersection, Variable, VariableAutocomplete, VariableObject, VariablesConfig, VariablesDefinition, appendAutocomplete, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, escapeRegExp, extractUsedVarNames, extractUsedVarNamesFromPreflightResult, important, isPlainObjectRecord, keyframes, log, normalizeVariableName, renderCSSStyleBlocks, resolveSelectorConfig, selectors$1 as selectors, shortcuts, sortLayerNames, variables };
+export { Arrayable, type AtomicStyleIdContext, type AtomicStyleIdStrategy, Awaitable, type CSSProperty, type CSSSelector, type CSSStyleBlockBody, type CSSStyleBlocks, type CreateEngineOptions, type Diagnostic, type DiagnosticHandler, type DiagnosticLevel, DistributiveGetValue, DynamicSelector, DynamicShortcut, type Engine, type EngineConfig, type EngineConfigDependency, type EngineConfigurator, type EngineHostContext, type EnginePlugin, type EnginePluginContext, ExternalKeyframesDefinition, ExternalVariable, FromKebab, GetValue, ImportantConfig, IsEqual, IsNever, Keyframes, KeyframesConfig, KeyframesProgress, LocalKeyframesDefinition, LocalVariable, Nullish, type PikaAugment, type PikaManager, type PikaRegistrationCapability, type Preflight, type PreflightDefinition, type PreflightFn, type Properties, type PropertyValue, ResolveFrom, type ResolvedPreflight, Selector, SelectorsConfig, Shortcut, ShortcutPreviewCollector, ShortcutPreviewImage, ShortcutResolutionContext, ShortcutsConfig, Simplify, StaticSelector, StaticShortcut, type StyleDefinition, type StyleDefinitionMap, type StyleItem, type StyleUsePlan, ToKebab, type TransformedFormat, type PropertiesHyphenInput as TypegenCSSPropertiesHyphenInput, type PropertiesInput as TypegenCSSPropertiesInput, type PropertyInputValue as TypegenCSSPropertyInputValue, type TypegenContribution, type TypegenJSDocRenderBindings, type TypegenManager, type TypegenRegistrationCapability, type TypegenRenderUnit, type TypegenSnapshot, type TypegenSnapshotContribution, UnionString, UnionToIntersection, Variable, VariableSuggest, VariablesConfig, VariablesDefinition, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, escapeRegExp, extractUsedVarNames, extractUsedVarNamesFromPreflightResult, important, isPlainObjectRecord, keyframes, log, normalizeVariableName, renderCSSStyleBlocks, renderTypegenDocument, renderTypegenJSDoc, resolveSelectorConfig, resolveShortcutConfig, selectors$1 as selectors, shortcuts, sortLayerNames, variables };