@wix/zero-config-implementation 1.5.0

package/dist/information-extractors/css/index.d.ts

@@ -0,0 +1,3 @@
+export { parseCss } from './parse';
+export { matchCssSelectors } from './selector-matcher';
+export type { CSSParserAPI } from './types';

package/dist/information-extractors/css/parse.d.ts

@@ -0,0 +1,7 @@
+import { CSSParserAPI } from './types';
+/**
+ * Factory function that parses CSS and returns an API to query the parsed result
+ * @param cssString - The CSS file content as a string
+ * @returns API object with methods to query the parsed CSS
+ */
+export declare function parseCss(cssString: string): CSSParserAPI;

package/dist/information-extractors/css/selector-matcher.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCssInfo } from '../../index';
+import { ExtractedElement } from '../react/extractors/core/tree-builder';
+export declare function matchCssSelectors(html: string, elements: ExtractedElement[], cssInfos: ExtractedCssInfo[]): ExtractedElement[];

package/dist/information-extractors/css/types.d.ts

@@ -0,0 +1,49 @@
+export interface CSSProperty {
+    name: string;
+    value: string;
+}
+export interface CssSelectorMatch {
+    selector: string;
+    properties: CSSProperty[];
+}
+export interface MatchedCssData {
+    matches: CssSelectorMatch[];
+    customProperties: Record<string, string>;
+}
+/**
+ * API returned by parseCss function for querying parsed CSS
+ */
+export interface CSSParserAPI {
+    /**
+     * Gets CSS properties for a specific selector
+     * @param selector - The selector to extract properties for
+     * @returns Array of CSS properties for the specified selector
+     */
+    getPropertiesForSelector: (selector: string) => CSSProperty[];
+    /**
+     * Gets all selectors and their properties from the CSS
+     * @returns Map from selector to its CSS properties
+     */
+    getAllProperties: () => Map<string, CSSProperty[]>;
+    /**
+     * Gets all CSS property names that use a specific CSS variable
+     * @param varName - The CSS variable name (with or without --)
+     * @returns Array of CSS property names that use this variable
+     */
+    getVarUsages: (varName: string) => string[];
+    /**
+     * Gets unique properties from multiple selectors with CSS cascade rules:
+     * - First selector wins (properties from earlier selectors take precedence)
+     * - Within a selector, last value wins (if property appears multiple times)
+     * @param selectors - Array of selectors to extract properties from
+     * @returns Map of property names to their values
+     */
+    getUniqueProperties: (selectors: string[]) => Map<string, string>;
+    /**
+     * Gets a DOM-matchable selector by stripping pseudo-classes.
+     * Returns null if the selector contains pseudo-elements (unmatchable against real DOM).
+     * @param selector - The original CSS selector string
+     * @returns DOM-matchable selector string or null
+     */
+    getDomSelector: (selector: string) => string | null;
+}

package/dist/information-extractors/react/extractors/core/index.d.ts

@@ -0,0 +1,6 @@
+export { ExtractorStore } from './store';
+export { runExtractors } from './runner';
+export type { ExtractionResult } from './runner';
+export { buildElementTree } from './tree-builder';
+export type { ExtractedElement } from './tree-builder';
+export type { ReactExtractor, RenderContext, CreateElementEvent, RenderCompleteEvent } from './types';

package/dist/information-extractors/react/extractors/core/runner.d.ts

@@ -0,0 +1,19 @@
+import { ComponentType } from 'react';
+import { ComponentInfo } from '../../../ts/types';
+import { ExtractorStore } from './store';
+import { ExtractedElement } from './tree-builder';
+import { ReactExtractor } from './types';
+export interface ExtractionResult {
+    html: string;
+    store: ExtractorStore;
+    elements: ExtractedElement[];
+}
+/**
+ * Runs extractors through the full lifecycle and returns extraction results.
+ *
+ * @param componentInfo - TypeScript-extracted component information
+ * @param component - The React component to render
+ * @param extractors - Array of extractors to run
+ * @returns Extraction results including HTML, store, and element tree
+ */
+export declare function runExtractors(componentInfo: ComponentInfo, component: ComponentType<unknown>, extractors: ReactExtractor[]): ExtractionResult;

package/dist/information-extractors/react/extractors/core/store.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ExtractorStore - Shared store for extractors with namespace support
+ *
+ * Extractors write to this store during render, namespaced by their name:
+ *   store.set(traceId, 'prop-tracker', { boundProps: ['label', 'onClick'] })
+ *   store.set(traceId, 'css-properties', { relevant: ['color', 'background'] })
+ *
+ * Store structure: Map<traceId, Map<extractorName, data>>
+ */
+export declare class ExtractorStore {
+    private data;
+    set<T>(traceId: string, extractorName: string, value: T): void;
+    get<T>(traceId: string, extractorName: string): T | undefined;
+    getAll(traceId: string): Map<string, unknown> | undefined;
+    entries(): IterableIterator<[string, Map<string, unknown>]>;
+    clear(): void;
+}

package/dist/information-extractors/react/extractors/core/tree-builder.d.ts

@@ -0,0 +1,15 @@
+import { ExtractorStore } from './store';
+export interface ExtractedElement {
+    traceId: string;
+    name: string;
+    tag: string;
+    attributes: Record<string, string>;
+    extractorData: Map<string, unknown>;
+    children: ExtractedElement[];
+    hasTextContent?: boolean;
+}
+/**
+ * Builds an element tree from HTML, merging with store data.
+ * Each element gets a semantic name from concatenated ancestor names.
+ */
+export declare function buildElementTree(html: string, store: ExtractorStore): ExtractedElement[];

package/dist/information-extractors/react/extractors/core/types.d.ts

@@ -0,0 +1,40 @@
+import { ComponentType } from 'react';
+import { ComponentInfo } from '../../../ts/types';
+import { ExtractorStore } from './store';
+/**
+ * Context available to extractors during the beforeRender phase.
+ * Props are mutable - extractors can modify them before render.
+ */
+export interface RenderContext {
+    componentInfo: ComponentInfo;
+    component: ComponentType<unknown>;
+    props: Record<string, unknown>;
+    store: ExtractorStore;
+}
+/**
+ * Event emitted for each DOM element created during render.
+ */
+export interface CreateElementEvent {
+    tag: string;
+    props: Record<string, unknown>;
+    traceId: string;
+    children: unknown[];
+    store: ExtractorStore;
+}
+/**
+ * Event emitted after render completes.
+ */
+export interface RenderCompleteEvent {
+    html: string;
+    context: RenderContext;
+}
+/**
+ * Interface for pluggable extractors.
+ * Extractors can hook into any combination of lifecycle events.
+ */
+export interface ReactExtractor {
+    name: string;
+    onBeforeRender?(context: RenderContext): void;
+    onCreateElement?(event: CreateElementEvent): void;
+    onRenderComplete?(event: RenderCompleteEvent): void;
+}

package/dist/information-extractors/react/extractors/css-properties.d.ts

@@ -0,0 +1,20 @@
+import { ReactExtractor } from './core/types';
+export interface CssPropertiesData {
+    relevant: string[];
+}
+/**
+ * Gets CSS properties relevant to an element based on tag and role.
+ * Note: hasTextContent determination is deferred to tree building since
+ * we can't know during createElement if a child will have text content.
+ */
+export declare function getCssPropertiesForTag(tag: string, role?: string): string[];
+/**
+ * Adds text CSS properties to an existing property list without duplicates.
+ * Called during tree building when we know an element has text content.
+ */
+export declare function addTextProperties(existing: string[]): string[];
+/**
+ * Creates a CSS properties extractor that determines relevant CSS properties
+ * for each element based on its tag and role.
+ */
+export declare function createCssPropertiesExtractor(): ReactExtractor;

package/dist/information-extractors/react/extractors/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * React Extractors
+ *
+ * Core infrastructure and pluggable extractors for the React information extraction system.
+ */
+export { ExtractorStore, runExtractors, buildElementTree, } from './core';
+export type { ExtractionResult, ExtractedElement, ReactExtractor, RenderContext, CreateElementEvent, RenderCompleteEvent, } from './core';
+export { createPropTrackerExtractor } from './prop-tracker';
+export type { PropTrackerData, PropTrackerExtractorState } from './prop-tracker';
+export { createCssPropertiesExtractor } from './css-properties';
+export type { CssPropertiesData } from './css-properties';

package/dist/information-extractors/react/extractors/prop-tracker.d.ts

@@ -0,0 +1,24 @@
+import { PropSpyMeta, TrackingStores } from '../types';
+import { PropSpyContext } from '../utils/prop-spy';
+import { ReactExtractor } from './core/types';
+export type GetSpyMetadataFn = (id: string) => PropSpyMeta | null;
+export interface PropTrackerData {
+    tag: string;
+    role?: string;
+    boundProps: string[];
+    concatenatedAttrs: Map<string, string>;
+}
+export interface PropTrackerExtractorState {
+    stores: TrackingStores;
+    spyContext: PropSpyContext;
+}
+/**
+ * Creates a prop tracker extractor that:
+ * 1. Wraps props with spy proxies during beforeRender
+ * 2. Detects spy markers in element props during onCreateElement
+ * 3. Writes tracking data to the store namespaced by 'prop-tracker'
+ */
+export declare function createPropTrackerExtractor(): {
+    extractor: ReactExtractor;
+    state: PropTrackerExtractorState;
+};

package/dist/information-extractors/react/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * React Information Extraction
+ *
+ * API: runExtractors() with pluggable extractors
+ */
+export { ExtractorStore, runExtractors, buildElementTree, createPropTrackerExtractor, createCssPropertiesExtractor, } from './extractors';
+export type { ExtractionResult, ExtractedElement, ReactExtractor, RenderContext, CreateElementEvent, RenderCompleteEvent, PropTrackerData, PropTrackerExtractorState, CssPropertiesData, } from './extractors';
+export type { CoupledComponentInfo, CoupledProp, TrackingStores, DOMBinding, PropReadInfo, PropWriteInfo, PropSpyMeta, } from './types';
+export type { PropSpyContext } from './utils/prop-spy';

package/dist/information-extractors/react/types.d.ts

@@ -0,0 +1,51 @@
+import { PropInfo } from '../ts/types';
+import { ExtractedElement } from './extractors/core/tree-builder';
+export declare const PROP_SPY_SYMBOL: unique symbol;
+export interface PropSpyMeta {
+    path: string;
+    propName: string;
+    uniqueId: string;
+    originalValue: unknown;
+}
+export interface PropSpy<T = unknown> {
+    [PROP_SPY_SYMBOL]: true;
+    __meta: PropSpyMeta;
+    valueOf: () => T;
+    toString: () => string;
+    toJSON: () => T;
+    [Symbol.toPrimitive]?: (hint: string) => T | string | number;
+}
+export interface PropReadInfo {
+    components: Set<string>;
+    value: unknown;
+}
+export interface PropWriteInfo {
+    elements: Map<string, {
+        tag: string;
+        elementId: string;
+    }>;
+    attributes: Map<string, {
+        attr: string;
+        concatenated: boolean;
+    }>;
+}
+export interface TrackingStores {
+    reads: Map<string, PropReadInfo>;
+    writes: Map<string, PropWriteInfo>;
+}
+export interface DOMBinding {
+    element: string;
+    attribute: string;
+    concatenated: boolean;
+    elementId: string;
+}
+export interface CoupledProp extends PropInfo {
+    bindings: DOMBinding[];
+    logicOnly: boolean;
+}
+export interface CoupledComponentInfo {
+    componentName: string;
+    props: Record<string, CoupledProp>;
+    elements: ExtractedElement[];
+    innerElementProps?: Map<string, Record<string, CoupledProp>>;
+}

package/dist/information-extractors/react/utils/mock-generator.d.ts

@@ -0,0 +1,9 @@
+import { ComponentInfo } from '../../ts/types';
+/**
+ * Reset faker's seed and internal state for reproducible results
+ */
+export declare function resetMockCounter(): void;
+/**
+ * Generate mock props object from ComponentInfo
+ */
+export declare function generateMockProps(componentInfo: ComponentInfo): Record<string, unknown>;

package/dist/information-extractors/react/utils/prop-spy.d.ts

@@ -0,0 +1,10 @@
+import { PropSpyMeta, TrackingStores } from '../types';
+export interface PropSpyContext {
+    createAuditedProps: <T extends object | null>(target: T, stores: TrackingStores, getComponent: () => string, basePath?: string) => T;
+    getSpyMetadataByUniqueId: (id: string) => PropSpyMeta | null;
+}
+/**
+ * Creates an encapsulated prop spy context.
+ * Each context has its own ID counter and metadata map, avoiding global state.
+ */
+export declare function createPropSpyContext(): PropSpyContext;

package/dist/information-extractors/ts/components.d.ts

@@ -0,0 +1,9 @@
+import { default as ts } from 'typescript';
+import { ComponentInfo } from './types';
+export declare function extractAllComponentInfo(program: ts.Program, filePath: string): ComponentInfo[];
+/**
+ * Extracts component info for only the default-exported component in a file.
+ * Returns `undefined` if the file has no default export or if the default export
+ * is not a recognized React component.
+ */
+export declare function extractDefaultComponentInfo(program: ts.Program, filePath: string): ComponentInfo | undefined;

package/dist/information-extractors/ts/css-imports.d.ts

@@ -0,0 +1,2 @@
+import { Program } from 'typescript';
+export declare function extractCssImports(program: Program): string[];

package/dist/information-extractors/ts/index.d.ts

@@ -0,0 +1,3 @@
+export { extractAllComponentInfo, extractDefaultComponentInfo } from './components';
+export { extractCssImports } from './css-imports';
+export type { ComponentInfo } from './types';

package/dist/information-extractors/ts/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * API to extract component props with full TypeScript type resolution
+ */
+export type ResolvedKind = 'primitive' | 'semantic' | 'array' | 'object' | 'union' | 'intersection' | 'enum' | 'literal' | 'function';
+export interface ResolvedType {
+    kind: ResolvedKind;
+    value?: unknown;
+    /** For semantic types, the package the symbol came from */
+    source?: string;
+    properties?: Record<string, PropInfo>;
+    elementType?: ResolvedType;
+    types?: ResolvedType[];
+}
+/**
+ * Resolved default value with its type.
+ * For literals (string, number, boolean, null), the value is the actual JavaScript value.
+ * For unresolvable values (references, expressions), we store the raw source text.
+ */
+export type DefaultValue = {
+    kind: 'string';
+    value: string;
+} | {
+    kind: 'number';
+    value: number;
+} | {
+    kind: 'boolean';
+    value: boolean;
+} | {
+    kind: 'null';
+    value: null;
+} | {
+    kind: 'unresolved';
+    value: string;
+};
+export interface PropInfo {
+    name: string;
+    type: string;
+    required: boolean;
+    defaultValue?: DefaultValue;
+    resolvedType: ResolvedType;
+    description?: string;
+    deprecated?: boolean;
+}
+export interface ComponentInfo {
+    componentName: string;
+    props: Record<string, PropInfo>;
+}

package/dist/information-extractors/ts/utils/semantic-type-resolver.d.ts

@@ -0,0 +1,3 @@
+import { default as ts } from 'typescript';
+import { ResolvedType } from '../types';
+export declare function resolveType(type: ts.Type, checker: ts.TypeChecker, depth?: number, typeString?: string, declaredSymbol?: ts.Symbol): ResolvedType;

package/dist/jsx-runtime-interceptor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Interceptable JSX Runtime
+ *
+ * This module wraps React's jsx-runtime and allows dynamic interception
+ * of jsx/jsxs/jsxDEV calls. This is necessary because ESM imports are immutable,
+ * so we can't monkey-patch react/jsx-runtime directly.
+ *
+ * ## Usage contexts
+ *
+ * This module runs in two contexts that must share mutable state:
+ *
+ * 1. **Vite alias (tests)** — aliased to `react/jsx-runtime` in vite.config.ts
+ * 2. **Node.js ESM loader hook (CLI)** — redirected via `module.register()` in cli.ts
+ *
+ * In both cases the interceptor may be loaded as a separate module instance from
+ * the copy bundled into the main dist files. To ensure `setJsxInterceptors()`
+ * (called from component-renderer.ts) affects the `jsx`/`jsxs` that user
+ * components call, mutable state lives on `globalThis` via `Symbol.for()`.
+ */
+declare const originalRuntime: typeof import("react/jsx-runtime");
+declare const originalDevRuntime: typeof import("react/jsx-dev-runtime");
+export declare const Fragment: import('react').ExoticComponent<{
+    children?: import('react').ReactNode | undefined;
+}>;
+type JsxDevFn = typeof originalDevRuntime.jsxDEV;
+/**
+ * Sets custom jsx/jsxs/jsxDEV implementations for interception.
+ * Call with no arguments to restore originals.
+ */
+export declare function setJsxInterceptors(jsx?: typeof originalRuntime.jsx, jsxs?: typeof originalRuntime.jsxs, jsxDEV?: JsxDevFn): void;
+/**
+ * Gets the original jsx/jsxs/jsxDEV functions.
+ */
+export declare function getOriginals(): {
+    jsx: typeof import('./jsx-runtime-interceptor.ts').jsx;
+    jsxs: typeof import('./jsx-runtime-interceptor.ts').jsxs;
+    jsxDEV: typeof import('./jsx-runtime-interceptor.ts').jsxDEV;
+};
+export declare function jsx(type: Parameters<typeof originalRuntime.jsx>[0], props: Parameters<typeof originalRuntime.jsx>[1], key?: Parameters<typeof originalRuntime.jsx>[2]): import('react').ReactElement<any, string | import('react').JSXElementConstructor<any>>;
+export declare function jsxs(type: Parameters<typeof originalRuntime.jsxs>[0], props: Parameters<typeof originalRuntime.jsxs>[1], key?: Parameters<typeof originalRuntime.jsxs>[2]): import('react').ReactElement<any, string | import('react').JSXElementConstructor<any>>;
+export declare function jsxDEV(type: Parameters<JsxDevFn>[0], props: Parameters<JsxDevFn>[1], key: Parameters<JsxDevFn>[2], isStaticChildren: Parameters<JsxDevFn>[3], source: Parameters<JsxDevFn>[4], self: Parameters<JsxDevFn>[5]): import('react').ReactElement<any, string | import('react').JSXElementConstructor<any>>;
+export {};

package/dist/jsx-runtime-interceptor.js

@@ -0,0 +1,63 @@
+import { createRequire as j } from "node:module";
+const o = j(import.meta.url), t = o("react/jsx-runtime"), u = o("react/jsx-dev-runtime"), f = t.Fragment, a = /* @__PURE__ */ Symbol.for("zero-config:jsx-interceptor");
+function x() {
+  const n = globalThis;
+  return n[a] || (n[a] = {
+    currentJsx: t.jsx,
+    currentJsxs: t.jsxs,
+    currentJsxDEV: u.jsxDEV,
+    isInsideOriginal: !1
+  }), n[a];
+}
+function m(n, r, i) {
+  const s = x();
+  s.currentJsx = n ?? t.jsx, s.currentJsxs = r ?? t.jsxs, s.currentJsxDEV = i ?? u.jsxDEV;
+}
+function E() {
+  return {
+    jsx: t.jsx,
+    jsxs: t.jsxs,
+    jsxDEV: u.jsxDEV
+  };
+}
+function I(n, r, i) {
+  const s = x();
+  if (s.isInsideOriginal)
+    return t.jsx(n, r, i);
+  s.isInsideOriginal = !0;
+  try {
+    return s.currentJsx(n, r, i);
+  } finally {
+    s.isInsideOriginal = !1;
+  }
+}
+function O(n, r, i) {
+  const s = x();
+  if (s.isInsideOriginal)
+    return t.jsxs(n, r, i);
+  s.isInsideOriginal = !0;
+  try {
+    return s.currentJsxs(n, r, i);
+  } finally {
+    s.isInsideOriginal = !1;
+  }
+}
+function d(n, r, i, s, c, l) {
+  const e = x();
+  if (e.isInsideOriginal)
+    return u.jsxDEV(n, r, i, s, c, l);
+  e.isInsideOriginal = !0;
+  try {
+    return e.currentJsxDEV(n, r, i, s, c, l);
+  } finally {
+    e.isInsideOriginal = !1;
+  }
+}
+export {
+  f as Fragment,
+  E as getOriginals,
+  I as jsx,
+  d as jsxDEV,
+  O as jsxs,
+  m as setJsxInterceptors
+};

package/dist/jsx-runtime-loader.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Node.js ESM Customization Hook
+ *
+ * Redirects ESM `import 'react/jsx-runtime'` and `import 'react/jsx-dev-runtime'`
+ * to the interceptable jsx-runtime-interceptor module.
+ *
+ * Registered via `module.register()` in the CLI before loading user components.
+ * This ensures that dynamically imported user components use the interceptable
+ * jsx-runtime, enabling prop tracking and element tracing.
+ *
+ * CJS `require()` calls are not affected by this hook — the interceptor uses
+ * `createRequire` internally, so it always loads the real React runtime.
+ */
+interface ResolveResult {
+    url: string;
+    shortCircuit?: boolean;
+}
+interface ResolveContext {
+    parentURL?: string;
+}
+type NextResolve = (specifier: string, context: ResolveContext) => Promise<ResolveResult>;
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<ResolveResult>;
+export {};

package/dist/jsx-runtime-loader.js

@@ -0,0 +1,7 @@
+const n = import.meta.url.replace(/jsx-runtime-loader\.js$/, "jsx-runtime-interceptor.js");
+async function u(r, t, e) {
+  return r === "react/jsx-runtime" || r === "react/jsx-dev-runtime" ? { shortCircuit: !0, url: n } : e(r, t);
+}
+export {
+  u as resolve
+};

package/dist/manifest-pipeline.d.ts

@@ -0,0 +1,33 @@
+import { ComponentInfo } from './information-extractors/ts';
+import { CoupledComponentInfo } from './information-extractors/react';
+import { CSSParserAPI } from './information-extractors/css';
+import { ComponentType } from 'react';
+/** A non-fatal issue encountered during component processing. */
+export interface ExtractionWarning {
+    componentName: string;
+    phase: 'render' | 'coupling' | 'css' | 'loader' | 'conversion';
+    error: string;
+}
+export interface ExtractedCssInfo {
+    filePath: string;
+    api: CSSParserAPI;
+    properties: Map<string, string>;
+    customProperties: Map<string, string>;
+}
+export interface ComponentInfoWithCss extends CoupledComponentInfo {
+    css: ExtractedCssInfo[];
+}
+/** The result of processing a single component through the manifest pipeline. */
+export interface ProcessComponentResult {
+    component: ComponentInfoWithCss;
+    warnings: ExtractionWarning[];
+}
+/**
+ * Processes a single component through the full manifest pipeline:
+ * loading, rendering with prop tracking, CSS extraction, and selector matching.
+ *
+ * Returns the enriched component info alongside any non-fatal warnings
+ * encountered during processing. Always returns a component, falling back
+ * to minimal info (without DOM coupling) when rendering fails.
+ */
+export declare function processComponent(componentInfo: ComponentInfo, loadComponent: (componentName: string) => ComponentType<unknown> | null, cssImportPaths: string[], loaderHasError?: boolean): ProcessComponentResult;