@blotch/rsbuild-plugin-angular-lynx 22.2.1 → 22.2.3

package/dist/client/hmr-protocol.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The messages the two hot update clients exchange (hmr-background.ts and
+ * hmr-main-thread.ts). They travel over Lynx's cross-thread event channel:
+ * the background thread dispatches on `lynx.getCoreContext()` and the main
+ * thread listens on `lynx.getJSContext()`, and the reverse. Each payload is a
+ * JSON string, as in the runtime's other relays.
+ */
+/** Main → background: fetch a hot update file the main thread needs. */
+export declare const HMR_FETCH = "AngularLynx.HmrFetch";
+/** Background → main: the fetched file, or why it couldn't be fetched. */
+export declare const HMR_FETCH_RESULT = "AngularLynx.HmrFetchResult";
+/** Background → main: check for and apply the update to `hash`. */
+export declare const HMR_CHECK = "AngularLynx.HmrCheck";
+/** Main → background: whether the main thread applied it. */
+export declare const HMR_CHECK_RESULT = "AngularLynx.HmrCheckResult";
+/**
+ * Main → background: an update the main thread took in can't be shown, so
+ * reload the page. Sent by the stylesheet updater (css-hot-update.ts), which
+ * runs after the update itself has already succeeded.
+ */
+export declare const HMR_RELOAD = "AngularLynx.HmrReload";
+export type FetchRequest = {
+    id: number;
+    url: string;
+};
+export type FetchResult = {
+    id: number;
+    status: number;
+    text: string;
+} | {
+    id: number;
+    error: string;
+};
+export type CheckRequest = {
+    id: number;
+    hash: string;
+};
+export type ReloadRequest = {
+    reason: string;
+};
+/** Whether the main thread applied an update, and if not, why. */
+export type CheckOutcome = {
+    ok: true;
+    updatedModules: number;
+} | {
+    ok: false;
+    reason: string;
+};
+export type CheckResult = {
+    id: number;
+} & CheckOutcome;
+/** A thread's end of the cross-thread event channel. */
+export type ThreadContext = {
+    addEventListener(type: string, listener: (event: {
+        data: string;
+    }) => void): void;
+    dispatchEvent(event: {
+        type: string;
+        data: string;
+    }): void;
+};
+/** The parts of webpack's `module.hot` API the clients use. */
+export type HotApi = {
+    check(autoApply: true): Promise<(string | number)[] | null>;
+    status(): string;
+};
+export declare const send: (context: ThreadContext, type: string, message: object) => void;
+export declare const listen: <T>(context: ThreadContext, type: string, listener: (message: T) => void) => void;
+/**
+ * An error as text for the logs, with its stack. PrimJS, which runs the main
+ * thread, leaves the name and message out of `error.stack`, so they're added
+ * when the stack doesn't start with them.
+ */
+export declare const formatError: (error: unknown) => string;

package/dist/client/main-thread-hot-updates.d.ts

@@ -0,0 +1,40 @@
+import { type HotApi, type ThreadContext } from './hmr-protocol.js';
+/** Lynx's `requireModuleAsync`, which the hot update runtime loads with. */
+type RequireModuleAsync = (url: string, callback: (error: (Error & {
+    code?: string;
+}) | null, exports?: unknown) => void) => void;
+export type MainThreadHotUpdatesOptions = {
+    /** The main thread's `import.meta.webpackHot`. */
+    hot: HotApi;
+    /** The main thread's `lynx` global. */
+    lynx: {
+        requireModuleAsync?: RequireModuleAsync;
+    };
+    /** Lynx's `getJSContext()`, which reaches the background thread. */
+    context: ThreadContext;
+    /**
+     * Where `bootstrapApplication()` leaves its latest promise. Read through a
+     * function because each call replaces it.
+     */
+    currentBootstrap: () => unknown;
+    /** Whether an app is running: the last bootstrap succeeded. */
+    appRunning: () => boolean;
+};
+/**
+ * Applies the main thread's half of each hot update, when the background
+ * thread asks (see background-hot-updates.ts).
+ *
+ * Webpack's hot update runtime is already in the main-thread bundle, with
+ * `module.hot` on every module, but nothing ever asked it to check, and it
+ * loads updates with `lynx.requireModuleAsync()`, which the main thread
+ * doesn't have. This gives the main thread one that has the background
+ * thread fetch the file (only it has network access) and runs it here, then
+ * runs the checks.
+ *
+ * After an update, it waits for the app to bootstrap again if the update
+ * re-ran the app's entry: the old app is gone by then, so a failure has to
+ * reload the page rather than leave it blank. It reports failure too when no
+ * app is running at all.
+ */
+export declare const startMainThreadHotUpdates: ({ hot, lynx, context, currentBootstrap, appRunning, }: MainThreadHotUpdatesOptions) => void;
+export {};

package/dist/client/main-thread-hot-updates.js

@@ -0,0 +1,78 @@
+import { HMR_CHECK_RESULT, HMR_FETCH_RESULT, HMR_CHECK, send, listen, formatError, HMR_FETCH } from "../544.js";
+const evaluateChunk = (source, url)=>{
+    const module = {
+        exports: {}
+    };
+    new Function('module', 'exports', `${source}\n//# sourceURL=${url}`)(module, module.exports);
+    return module.exports;
+};
+const startMainThreadHotUpdates = ({ hot, lynx, context, currentBootstrap, appRunning })=>{
+    const fetches = new Map();
+    let nextFetchId = 0;
+    listen(context, HMR_FETCH_RESULT, (result)=>{
+        fetches.get(result.id)?.(result);
+        fetches.delete(result.id);
+    });
+    lynx.requireModuleAsync ??= (url, callback)=>{
+        const id = nextFetchId++;
+        fetches.set(id, (result)=>{
+            if ('error' in result) return void callback(new Error(`Loading ${url} failed: ${result.error}`));
+            if (404 === result.status) {
+                const error = new Error(`Cannot find module '${url}'`);
+                error.code = 'MODULE_NOT_FOUND';
+                callback(error);
+                return;
+            }
+            if (result.status >= 400) return void callback(new Error(`Loading ${url} failed with HTTP ${result.status}`));
+            let exports;
+            try {
+                exports = url.endsWith('.json') ? JSON.parse(result.text) : evaluateChunk(result.text, url);
+            } catch (error) {
+                callback(error);
+                return;
+            }
+            callback(null, exports);
+        });
+        send(context, HMR_FETCH, {
+            id,
+            url
+        });
+    };
+    const apply = async ()=>{
+        const status = hot.status();
+        if ('idle' !== status) return {
+            ok: false,
+            reason: `The hot update status is "${status}".`
+        };
+        const bootstrapBefore = currentBootstrap();
+        try {
+            const updatedModules = await hot.check(true);
+            if (!updatedModules) return {
+                ok: false,
+                reason: 'Cannot find update.'
+            };
+            const bootstrap = currentBootstrap();
+            if (bootstrap !== bootstrapBefore) await bootstrap;
+            if (!appRunning()) return {
+                ok: false,
+                reason: 'The app is not running.'
+            };
+            return {
+                ok: true,
+                updatedModules: updatedModules.length
+            };
+        } catch (error) {
+            return {
+                ok: false,
+                reason: formatError(error)
+            };
+        }
+    };
+    listen(context, HMR_CHECK, ({ id })=>{
+        apply().then((result)=>send(context, HMR_CHECK_RESULT, {
+                id,
+                ...result
+            }));
+    });
+};
+export { startMainThreadHotUpdates };

package/dist/client/main-thread-hot-updates.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client/testing/test-context.d.ts

@@ -0,0 +1,16 @@
+import type { ThreadContext } from '../hmr-protocol.js';
+/**
+ * One thread's end of the cross-thread channel, for the client tests. It
+ * records what the code under test sends, and `receive()` plays a message
+ * from the other thread.
+ */
+export declare const createTestContext: () => {
+    context: ThreadContext;
+    sent: {
+        type: string;
+        message: any;
+    }[];
+    /** The messages of one type, in order. */
+    sentOf: (type: string) => any[];
+    receive: (type: string, message: object) => void;
+};

package/dist/component-styles-cache.d.ts

@@ -1,43 +1,25 @@
+import type { ComponentStyleSize } from './utils/angular/budgets.js';
 /**
- * Per-component stylesheet bookkeeping. `imports` lists the on-disk scoped CSS
- * paths the loader will prepend as `import` statements; `inlineStyles` mirrors
- * Angular's inline-style handling surface; `processedFiles` deduplicates calls
- * that Angular's AOT compiler makes multiple times for the same stylesheet.
+ * Drops the recorded stylesheet sizes of a component whose file was deleted,
+ * so `anyComponentStyle` budgets stop reporting styles that no longer ship.
  */
-export type ComponentStylesEntry = {
-    imports: string[];
-    inlineStyles: string[];
-    scopeId: string;
-    processedFiles: Map<string, string>;
-};
-export type ComponentScopeInfo = {
-    className: string;
-    scopeId: string;
-};
+export declare const forgetComponentStyleSizes: (componentStyleSizes: Map<string, ComponentStyleSize>, containingFile: string) => void;
 /**
  * Builds the `transformStylesheet` callback that Angular's AOT compiler invokes
  * for every component stylesheet (inline `styles: []` and external `styleUrls`).
  *
- * The callback is a closure over the two shared caches the loader
- * (`api.transform` in angular.ts) later reads from:
- *   - `componentStylesCache` — maps component source file → its scoped CSS imports
- *   - `componentScopeIds` — maps component source file → { className, scopeId }
- *
- * Extracted from angular.ts so the dedup / scoped-path / write-if-changed logic
- * can be unit-tested directly by driving the returned callback, without standing
- * up a full Angular compilation.
+ * It returns the CSS unchanged, so the compiler embeds it in the component's
+ * definition and scopes it for the component's `encapsulation`, as on the web.
+ * extractComponentStyles() (component-styles.ts) then lifts it back out of the
+ * compiled code as Lynx CSS. The callback only records each stylesheet's size,
+ * for `anyComponentStyle` budgets.
  */
 export declare const createTransformStylesheet: (params: {
     basePath: string;
-    scopedCssCacheDir: string;
-    componentStylesCache: Map<string, ComponentStylesEntry>;
-    componentScopeIds: Map<string, ComponentScopeInfo>;
     /**
-     * Called with the path of each scoped CSS file whose contents were
-     * (re)written. On watch rebuilds the scoped files change after rspack's
-     * watcher has already collected the edit, so angular.ts passes them to
-     * rspack as modified. Otherwise the CSS change would only ship on the
-     * following rebuild.
+     * The compiled size of every component stylesheet, for `anyComponentStyle`
+     * budgets. Overwritten each time Angular compiles a stylesheet, so watch
+     * rebuilds check the current sizes.
      */
-    onStylesheetWritten?: (filePath: string) => void;
+    componentStyleSizes?: Map<string, ComponentStyleSize>;
 }) => ((data: string, containingFile: string, stylesheetFile: string | undefined, order: number, className: string | undefined) => Promise<string>);

package/dist/component-styles.d.ts

@@ -0,0 +1,73 @@
+import type { ModuleStylesheets } from './transform-module.js';
+/**
+ * One component's styles, lifted out of its compiled definition.
+ */
+export type ExtractedComponentStyles = {
+    className: string;
+    /**
+     * The ID the runtime builds the scope classes from. Only Emulated components
+     * need one, so it's `undefined` for the others.
+     */
+    scopeId: string | undefined;
+    /** The stylesheets, ready to be written as CSS files. */
+    stylesheets: string[];
+};
+export type ExtractComponentStylesResult = {
+    /** The module's code, without the `styles` the stylesheets came from. */
+    code: string;
+    components: ExtractedComponentStyles[];
+};
+/**
+ * Turns Angular's emulated-encapsulation CSS into CSS that Lynx can match.
+ *
+ * Angular's compiler scopes an Emulated component's styles with attribute
+ * selectors: `.title` becomes `.title[_ngcontent-%COMP%]`, `:host` becomes
+ * `[_nghost-%COMP%]`, and keyframe names gain a `_ngcontent-%COMP%_` prefix. On
+ * the web, the renderer puts those attributes on the elements. Lynx's selector
+ * matcher has no attribute selectors (`SelectorMatcher::MatchSimple` in Lynx
+ * core's css/ng/matcher only handles tag, class, id and pseudo-classes), so the
+ * attributes become classes here, and EmulatedLynxRenderer adds the same
+ * classes to the elements.
+ */
+export declare const toLynxScopedCss: (css: string, scopeId: string) => string;
+/**
+ * Fills the CSS variable namespace placeholder Angular's compiler puts in every
+ * component's styles: `var(--muted)` compiles to `var(--%NS%muted)`. Angular's
+ * renderer fills it with `CSS_VAR_NAMESPACE`, which is empty unless an app
+ * opts in with `provideCssVarNamespacing()`. Lynx CSS is compiled ahead of
+ * time, so it gets the default here, and the variables keep their own names,
+ * which global stylesheets such as the theme define.
+ */
+export declare const fillCssVarNamespace: (css: string) => string;
+/**
+ * Lifts each component's `styles` out of Angular's compiled output, so they
+ * can ship as Lynx CSS.
+ *
+ * Lynx can't add styles at runtime: CSS has to be compiled into the bundle.
+ * So the plugin lets Angular's compiler embed every component's styles in its
+ * definition, exactly as on the web (scoped for `ViewEncapsulation.Emulated`,
+ * left global for `None` and `ShadowDom`), then takes them back out here. That
+ * keeps each component's styles with its own encapsulation, even when two
+ * components share a stylesheet file, and removes the CSS strings from the
+ * JavaScript.
+ *
+ * Only `styles` arrays made of string literals are taken, which is what the
+ * compiler emits. Anything else is left in place.
+ */
+export declare const extractComponentStyles: (code: string, fileName: string) => ExtractComponentStylesResult;
+/**
+ * Writes the stylesheets extracted from one module as CSS files, so the
+ * module can import them and css-extract compiles them into the bundle.
+ *
+ * A file is only rewritten when its content changed, and each rewrite is
+ * reported through `onWritten`: on a watch rebuild the files change after
+ * rspack's watcher collected the edit, so the plugin reports them to rspack as
+ * changed, or the new CSS would only ship on the following rebuild.
+ */
+export declare const writeModuleStylesheets: (params: {
+    basePath: string;
+    cacheDir: string;
+    fileName: string;
+    components: readonly ExtractedComponentStyles[];
+    onWritten?: (filePath: string) => void;
+}) => ModuleStylesheets | undefined;

package/dist/component-styles.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cross-thread-transform.d.ts

@@ -0,0 +1,38 @@
+export type CrossThreadTransformOptions = {
+    /** The directory the file keys are relative to, the same for both bundles. */
+    root: string;
+};
+/**
+ * Gives each module-level `backgroundFn(fn)`, `createMainThreadRef(value)` and
+ * `new MainThreadRef(value)` one more argument: an ID from the file and the
+ * call's position, such as `'3f9a1c2b7d:0'`.
+ *
+ * Angular runs on the main thread only, but the background thread runs the
+ * modules that make these calls too (see background-entry.ts), for the
+ * functions that main-thread code calls there. The main thread sends a handle
+ * or ref across by this ID, and the other thread finds its own copy by it.
+ * The runtime's fallback is a counter, which only matches if both threads run
+ * the same calls in the same order. They don't: the background thread runs
+ * only some of the app's modules, and in a different order, and Angular code
+ * (which also creates refs) runs on the main thread only.
+ *
+ * Calls inside a function or class are left alone, since one call site can run
+ * any number of times there.
+ *
+ * @param code - The module's JavaScript.
+ * @param filename - The module's path.
+ * @param options - See {@link CrossThreadTransformOptions}.
+ * @returns The transformed code, or `code` itself when nothing applies.
+ */
+export declare const transformCrossThread: (code: string, filename: string, options: CrossThreadTransformOptions) => string;
+/**
+ * Whether the module calls `backgroundFn()`, `createMainThreadRef()` or
+ * `new MainThreadRef()` at module level, so the background thread has to run
+ * it too. These are the calls {@link transformCrossThread} tags.
+ *
+ * @param code - The module's JavaScript.
+ * @param filename - The module's path.
+ * @returns `true` when the module defines a value the main thread can send
+ *   across by ID.
+ */
+export declare const definesCrossThreadValues: (code: string, filename: string) => boolean;

package/dist/cross-thread-transform.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/css.d.ts

@@ -1,7 +1,7 @@
 import type { RsbuildPluginAPI } from '@lynx-js/rspeedy';
 import type { CSSLoaderOptions } from '@rsbuild/core';
-import type { PluginAngularLynxOptions } from './utils/options.js';
-export declare const applyCSS: (api: RsbuildPluginAPI, options: Required<PluginAngularLynxOptions>) => void;
+import type { NormalizedPluginAngularLynxOptions } from './utils/options.js';
+export declare const applyCSS: (api: RsbuildPluginAPI, options: NormalizedPluginAngularLynxOptions) => void;
 /**
  * This is copied from https://github.com/web-infra-dev/rsbuild/blob/9f8be2d71ffeb7da969cda36fd9755db2cadaff5/packages/core/src/plugins/css.ts#L42
  *

package/dist/entry.d.ts

@@ -1,7 +1,33 @@
 import type { RsbuildPluginAPI, Rspack } from '@lynx-js/rspeedy';
 import type { UndefinedOnPartialDeep } from 'type-fest';
-import type { PluginAngularLynxOptions } from './utils/options.js';
-export declare const applyEntry: (api: RsbuildPluginAPI, options: Required<PluginAngularLynxOptions>) => void;
+import type { BackgroundEntries } from './background-entry.js';
+import type { NormalizedPluginAngularLynxOptions } from './utils/options.js';
+/**
+ * The key `pluginLynx` (the Lynx build engine, which Rspeedy registers) exposes
+ * its resolved config under. Mirrors `S_LYNX_CONFIG` in React Lynx's plugin.
+ */
+export declare const S_LYNX_CONFIG: unique symbol;
+/**
+ * The `blur-view` rule that approximates iOS's blur materials on Android,
+ * from variables the runtime sets (see the file). Only the native bundle gets
+ * it: web draws the materials itself, in the element's shadow root, and an
+ * app-level rule there would beat them. It goes before every other import, so
+ * the app's own stylesheets come later and win a tie.
+ */
+export declare const BLUR_VIEW_STYLESHEET: string;
+/**
+ * The hot update clients (see client/). The background one stands in for
+ * `@rspack/core/hot/dev-server`; the main-thread one gives the main thread its
+ * own hot updates. Together they apply each update on both threads, or reload.
+ */
+export declare const HMR_BACKGROUND_CLIENT: string;
+export declare const HMR_MAIN_THREAD_CLIENT: string;
+/**
+ * Applies stylesheet edits on the main thread, in place of css-extract's
+ * `runtime/hotModuleReplacement.cjs` (see client/css-hot-update.ts).
+ */
+export declare const CSS_HOT_UPDATE: string;
+export declare const applyEntry: (api: RsbuildPluginAPI, options: NormalizedPluginAngularLynxOptions, backgroundEntries: BackgroundEntries, appEntries: Set<string>) => void;
 /**
  * This is copied from https://github.com/web-infra-dev/rsbuild/blob/037da7b9d92e20c7136c8b2efa21eef539fa2f88/packages/core/src/plugins/html.ts#L168
  */

package/dist/hot-updates.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Whether a build environment takes hot updates, under the same conditions
+ * entry.ts adds the hot update clients: a development build of a Lynx
+ * environment (the web preview has none) without `dev.hmr: false`.
+ *
+ * @param environment - The environment, as Rsbuild passes it to a transform.
+ * @returns Whether modules should take hot updates.
+ */
+export declare const hotUpdatesEnabled: (environment: {
+    name: string;
+    config: {
+        mode?: string;
+        dev?: {
+            hmr?: boolean;
+        };
+    };
+}) => boolean;
+/**
+ * Hashes a component file's source without its components' templates and
+ * styles. Two versions of a file with the same signature differ only in what
+ * a hot update can apply in place (see `ɵhmrAccept` in the runtime). An
+ * external template or stylesheet isn't in the source at all, so editing one
+ * leaves the signature as it was.
+ *
+ * @param source - The file's TypeScript source.
+ * @param fileName - The file's path, for the parser.
+ * @returns The signature.
+ */
+export declare const hotUpdateSignature: (source: string, fileName: string) => string;
+/**
+ * Finds the components a module's compiled code defines, as the names of
+ * their classes. Only classes declared at the top of the module are listed,
+ * because the code {@link addHotAccept} appends assigns to them there.
+ *
+ * @param code - The module's code, as Angular's compiler emitted it.
+ * @param fileName - The module's path, for the parser.
+ * @returns The class names, in the order the module defines them.
+ */
+export declare const componentClassNames: (code: string, fileName: string) => string[];
+/**
+ * Makes a module that defines components take its own hot updates, through
+ * the runtime's `ɵhmrAccept`. The call reassigns the module's component
+ * classes to what it returns, so after an in-place update the module's
+ * exports are the classes the running app already uses.
+ *
+ * @param code - The module's code.
+ * @param options.components - The names of the module's component classes.
+ * @param options.signature - The source's {@link hotUpdateSignature}.
+ * @param options.compiled - The code Angular's compiler emitted for the
+ *   module, before the plugin's other transforms.
+ * @returns The code with the call appended.
+ */
+export declare const addHotAccept: (code: string, { components, signature, compiled, }: {
+    components: string[];
+    signature: string;
+    compiled: string;
+}) => string;
+/**
+ * Makes the app's entry module take every hot update its imports pass on.
+ * Re-running the entry calls `bootstrapApplication()` again, which replaces
+ * the running app with one built from the updated modules (on the main
+ * thread; the background thread runs no app).
+ *
+ * @param code - The entry module's code.
+ * @returns The code with the self-accept appended.
+ */
+export declare const addEntryHotAccept: (code: string) => string;

package/dist/hot-updates.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1 +1,3 @@
-export { pluginAngularLynx } from './plugin-angular-lynx';
+export { pluginAngularLynx } from './plugin-angular-lynx.js';
+export type { PluginAngularLynxOptions } from './utils/options.js';
+export { type AngularCliContext, pluginAngularCliContext, } from './angular-cli-context.js';