@appshell/webpack-plugin 1.0.0-alpha.23 → 1.0.0-alpha.25

package/dist/types/config/src/index.d.ts

@@ -11,6 +11,6 @@ export { default as outdated } from './outdated';
 export { activate, publish } from './publish';
 export type { PublishOptions, PublishResult } from './publish';
 export { default as sync } from './sync';
-export type { AppshellComposition, AppshellConfig, AppshellConfigRemote, AppshellIndex, AppshellManifest, AppshellRemote, AppshellTemplate, ComparisonResult, ComparisonResults, ComparisonTarget, Metadata, ModuleFederationPluginOptions, PackageSpec, ResolvedRemote, Schema, SharedConfig, SharedModuleSpec, } from './types';
+export type { AppshellComposition, AppshellConfig, AppshellConfigRemote, AppshellIndex, AppshellManifest, AppshellRemote, AppshellTemplate, AppshellTokenUsage, ComparisonResult, ComparisonResults, ComparisonTarget, Metadata, ModuleFederationPluginOptions, PackageSpec, ResolvedRemote, Schema, SharedConfig, SharedObject, SharedModuleSpec, } from './types';
 export * as utils from './utils';
 export * as validators from './validators';

package/dist/types/config/src/types.d.ts

@@ -1,4 +1,6 @@
+import type { AppshellIndex, AppshellRemote, Metadata } from '@appshell/runtime';
 import { JSONSchema4, JSONSchema6, JSONSchema7 } from 'json-schema';
+export type { AppshellIndex, AppshellRemote, Metadata } from '@appshell/runtime';
 export type Schema = JSONSchema4 | JSONSchema6 | JSONSchema7;
 export type ConfigValidator = {
     validate: <T>(...config: T[]) => void;
@@ -68,29 +70,34 @@ export type AppshellTemplate<TMetadata = Metadata> = {
     remotes?: Record<string, AppshellConfigRemote<TMetadata>>;
     module: ModuleFederationPluginOptions;
     vars?: Record<string, unknown>;
+    tokens?: Record<string, AppshellTokenUsage>;
     overrides?: AppshellOverrides;
 };
 /** Appshell manifest types */
-export type AppshellRemote<TMetadata = Metadata> = {
-    id: string;
-    manifestUrl: string;
-    remoteEntryUrl: string;
-    scope: string;
-    module: string;
-    shareScope?: string;
-    metadata: TMetadata;
-};
 export type AppshellOverrides = {
     vars: Record<string, Record<string, string | number | undefined>>;
 };
+/**
+ * Which design tokens a package's own output reaches for. Observed from the emitted
+ * assets rather than declared: the CSS already says it, and a hand-kept list is a copy
+ * that drifts the first time someone adds a token and forgets the yaml.
+ *
+ * `required` is a reference with no fallback — the package has no plan B. `optional` is
+ * `var(--appshell-x, something)`, which degrades on its own. That split is read off what
+ * the author wrote rather than asked of them.
+ */
+export type AppshellTokenUsage = {
+    required: string[];
+    optional: string[];
+};
 export type AppshellManifest<TMetadata = Metadata> = {
     remotes: Record<string, AppshellRemote<TMetadata>>;
     modules: Record<string, ModuleFederationPluginOptions>;
     vars: Record<string, Record<string, string | number | undefined>>;
+    /** Keyed by federation scope, so a merged manifest still says which package needs what. */
+    tokens?: Record<string, AppshellTokenUsage>;
     overrides?: AppshellOverrides;
 };
-export type AppshellIndex = Record<string, string>;
-export type Metadata = Record<string, unknown>;
 /** An `AppshellRemote` the registry already resolved, so the browser needs no manifest fetch. */
 export type ResolvedRemote<TMetadata = Metadata> = AppshellRemote<TMetadata>;
 /**

package/dist/types/runtime/src/errors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A package asked for vars that were never delivered.
+ *
+ * Almost always one of three things: the package was loaded outside `remoteLoader`
+ * (a test, a storybook, a direct import), the host and the package resolved separate
+ * copies of `@appshell/runtime` because one of them failed to declare it as a
+ * singleton, or the scope compiled into the package is not the scope the registry
+ * knows it by.
+ */
+export declare class MissingVarsError extends Error {
+    readonly scope: string;
+    constructor(scope: string, known: string[]);
+}
+/**
+ * Something tried to replace vars that were already delivered for a scope.
+ *
+ * The first write wins and is final. Within one page load a scope has exactly one
+ * vars object — both resolvers read it from the same `composition.vars[scope]` — so a
+ * differing second write is a bug or a package reaching for a scope that is not its own,
+ * and neither should be applied quietly.
+ */
+export declare class VarsConflictError extends Error {
+    readonly scope: string;
+    constructor(scope: string);
+}
+/**
+ * The package was built without `AppshellPlugin`, so nothing substituted the scope the
+ * `@appshell/runtime/vars` accessor needs to know which vars are its own.
+ */
+export declare class MissingScopeError extends Error {
+    constructor();
+}

package/dist/types/runtime/src/index.d.ts

@@ -0,0 +1,4 @@
+export { MissingScopeError, MissingVarsError, VarsConflictError } from './errors';
+export { hasVars, readVars, resetVars, setVars } from './store';
+export type { Vars } from './types';
+export type { AppshellIndex, AppshellRemote, Metadata } from './wire';

package/dist/types/runtime/src/store.d.ts

@@ -0,0 +1,25 @@
+import type { Vars } from './types';
+/**
+ * Delivers a scope's vars. Called by `@appshell/loader` immediately before the remote
+ * is loaded, so they are in place before the package's modules evaluate.
+ *
+ * The first write for a scope wins and is frozen. Re-delivering the identical vars is a
+ * no-op — the same remote can be mounted more than once — but replacing them throws.
+ * That is what keeps one package from overwriting another's: by the time any package
+ * evaluates, the host has already written for it.
+ *
+ * It does not make a scope's vars *private*. Any code on the page can still read another
+ * scope by name, and nothing short of a separate realm would change that.
+ */
+export declare const setVars: (scope: string, vars: Vars) => void;
+/**
+ * Reads a scope's vars, throwing rather than handing back an empty object — a package
+ * that silently renders with no configuration is the failure this replaced.
+ *
+ * Prefer `getVars()` from `@appshell/runtime/vars`, which supplies the scope for you.
+ */
+export declare const readVars: <TVars extends Vars = Vars>(scope: string) => TVars;
+/** Whether a scope has been delivered, for callers that want to branch instead of catch. */
+export declare const hasVars: (scope: string) => boolean;
+/** Test seam. Not part of the contract a package should build on. */
+export declare const resetVars: () => void;

package/dist/types/runtime/src/types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A package's runtime configuration, already merged by the registry — a package's
+ * declared vars, then the application's `overrides.vars`.
+ *
+ * Structurally identical to `AppshellComposition['vars'][scope]` in `@appshell/config`,
+ * but declared here rather than imported. This package is a shared singleton loaded
+ * into every micro-frontend on the page, so it carries no dependencies at all.
+ */
+export type Vars = Record<string, string | number | undefined>;

package/dist/types/runtime/src/wire.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What the browser is told about a remote.
+ *
+ * These live here rather than in `@appshell/config` because config is build tooling — it
+ * carries yaml, lodash and axios — and a package that only wants to type a remote should
+ * not install a compiler to get it. This package is already the one every micro-frontend
+ * on the page shares, and it has no dependencies of its own to pass on.
+ *
+ * `AppshellManifest` deliberately stays in `@appshell/config`. It is a build artifact, and
+ * its `modules` field is Module Federation plugin options — build-time webpack
+ * configuration the browser never sees and this package should never drag in.
+ */
+/** Arbitrary, application-defined description of a remote. Appshell never reads it. */
+export type Metadata = Record<string, unknown>;
+/** A remote the registry has already resolved, so the browser needs no manifest fetch. */
+export type AppshellRemote<TMetadata = Metadata> = {
+    id: string;
+    manifestUrl: string;
+    remoteEntryUrl: string;
+    scope: string;
+    module: string;
+    shareScope?: string;
+    metadata: TMetadata;
+};
+/** Remote key to manifest url. */
+export type AppshellIndex = Record<string, string>;

package/dist/types/tokens/src/contract.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The token contract: the complete, fixed vocabulary a package may consume and an
+ * Application must supply.
+ *
+ * Small and stable is the property that matters. A package authors against these names
+ * with fallbacks (`var(--appshell-primary, #0af)`) and renders standalone; an Application
+ * supplies the values and every package it composes moves together.
+ */
+export type Mode = 'light' | 'dark';
+/** Colour roles an Application's *base* supplies — everything not tied to the accent. */
+export declare const BASE_COLOR_ROLES: readonly ["surface", "on-surface", "surface-raised", "on-surface-raised", "text-muted", "border", "danger", "on-danger", "warning", "on-warning", "success", "on-success"];
+/** Colour roles an Application's *accent* supplies. */
+export declare const ACCENT_COLOR_ROLES: readonly ["primary", "on-primary", "secondary", "on-secondary"];
+/**
+ * Derived rather than authored. Hover and active are computed from their accent with
+ * `color-mix`, and the focus ring is picked per base+accent so it stays visible. A theme
+ * may override any of them; none has to be supplied.
+ */
+export declare const DERIVED_COLOR_ROLES: readonly ["primary-hover", "primary-active", "secondary-hover", "secondary-active", "focus-ring"];
+/**
+ * Named for their role, not their size. A numeric scale would reintroduce exactly the
+ * divergence this contract exists to prevent — one author mapping `h1` to `2xl` and
+ * another to `xl` is how headings stop matching across a composed page.
+ */
+export declare const TYPE_ROLES: readonly ["font-body", "font-mono", "font-size-h1", "font-size-h2", "font-size-h3", "font-size-h4", "font-size-h5", "font-size-h6", "font-size-body", "font-size-small", "line-height-tight", "line-height-normal"];
+/** Genuinely a scale. Nobody wants `--appshell-space-card-padding`. */
+export declare const DIMENSION_ROLES: readonly ["space-xs", "space-sm", "space-md", "space-lg", "space-xl", "radius-sm", "radius-md", "radius-lg"];
+export type BaseColorRole = (typeof BASE_COLOR_ROLES)[number];
+export type AccentColorRole = (typeof ACCENT_COLOR_ROLES)[number];
+export type DerivedColorRole = (typeof DERIVED_COLOR_ROLES)[number];
+export type TypeRole = (typeof TYPE_ROLES)[number];
+export type DimensionRole = (typeof DIMENSION_ROLES)[number];
+export type TokenRole = BaseColorRole | AccentColorRole | DerivedColorRole | TypeRole | DimensionRole;
+export declare const TOKEN_ROLES: readonly TokenRole[];
+export type BaseTokens = Record<BaseColorRole, string>;
+export type AccentTokens = Record<AccentColorRole, string>;
+export type Theme = Record<TokenRole, string>;
+/** The custom property a role is published as. */
+export declare const cssVar: (role: TokenRole) => string;
+/**
+ * Pairs the registry checks for contrast. Because every role that carries text has an
+ * `on-` partner, a theme cannot express illegible text without failing this list — which
+ * is the failure that actually reaches users, and the one a CSS parser alone never catches.
+ */
+export declare const TEXT_PAIRS: readonly (readonly [TokenRole, TokenRole])[];
+/** Muted text has no `on-` partner; it is read against both surfaces. */
+export declare const MUTED_AGAINST: readonly TokenRole[];
+/** Non-text, so 3:1 rather than 4.5:1 — WCAG 1.4.11. */
+export declare const NON_TEXT_PAIRS: readonly (readonly [TokenRole, TokenRole])[];
+export declare const AA_TEXT = 4.5;
+export declare const AA_NON_TEXT = 3;

package/dist/types/tokens/src/contrast.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Contrast checking for a theme.
+ *
+ * Syntax validation on its own earns little: it catches `--appshell-primary: bananas` and
+ * misses `--appshell-on-primary: #fff` on `--appshell-primary: #fff`, which is valid CSS
+ * and invisible text. Checking the `on-` pairs catches the failure that reaches users, and
+ * subsumes syntax validation for free — a value that will not parse cannot be measured.
+ */
+import { type Theme, type TokenRole } from './contract';
+type Rgb = [number, number, number];
+/** Returns undefined rather than throwing — an unmeasurable value is reported, not fatal. */
+export declare const parseColor: (value: string) => Rgb | undefined;
+/** WCAG 2.1 contrast ratio, 1–21. */
+export declare const contrastRatio: (a: Rgb, b: Rgb) => number;
+/**
+ * A colour as `#rrggbb`.
+ *
+ * `<meta name="theme-color">` takes a CSS colour, but browser support for `oklch` there
+ * is not something to rely on for a hint the page cannot detect the failure of — a
+ * value the browser does not understand is simply ignored, silently.
+ */
+export declare const toHex: (value: string) => string | undefined;
+export type ContrastFinding = {
+    roles: [TokenRole, TokenRole];
+    ratio?: number;
+    required: number;
+    reason: 'below-threshold' | 'unparseable';
+};
+/**
+ * Every finding for a theme. Empty means it passes.
+ *
+ * `color-mix` values are skipped rather than failed: hover and active are derived from
+ * roles that are themselves checked, and resolving them needs a browser.
+ */
+export declare const validateTheme: (theme: Theme) => ContrastFinding[];
+export declare const describeFinding: ({ roles, ratio, required, reason }: ContrastFinding) => string;
+export {};

package/dist/types/tokens/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from './contract';
+export { contrastRatio, describeFinding, parseColor, toHex, validateTheme, type ContrastFinding, } from './contrast';
+export { ACCENTS, BASES, FOCUS_RINGS } from './presets';
+export { composeTheme, DEFAULT_TYPE_AND_DIMENSIONS, pinnedMode, toCss, type ColorScheme, type ThemeSelection, } from './theme';

package/dist/types/tokens/src/presets.d.ts

@@ -0,0 +1,4 @@
+import type { AccentTokens, BaseTokens, Mode } from './contract';
+export declare const BASES: Record<string, Record<Mode, BaseTokens>>;
+export declare const ACCENTS: Record<string, AccentTokens>;
+export declare const FOCUS_RINGS: Record<string, Record<string, Record<Mode, string>>>;

package/dist/types/tokens/src/theme.d.ts

@@ -0,0 +1,30 @@
+import { type AccentTokens, type BaseTokens, type Mode, type Theme } from './contract';
+/**
+ * `system` follows the viewer's preference. Pinning a scheme is for an application that
+ * ships one look on purpose, and it is honoured all the way down: the palette stops
+ * varying, the root is stamped so the tokens cannot be swapped underneath it, and the
+ * browser is told which scheme to render its own scrollbars and form controls in.
+ */
+export type ColorScheme = 'system' | 'light' | 'dark';
+export type ThemeSelection = {
+    /** A base preset name, or the base's own token values. */
+    base: string | Record<Mode, BaseTokens>;
+    /** An accent preset name, or the accent's own token values. */
+    accent: string | AccentTokens;
+    /** Defaults to `system`. */
+    colorScheme?: ColorScheme;
+    /** Overrides applied last, so an Application can adjust a preset without forking it. */
+    overrides?: Partial<Theme>;
+};
+/** The mode a pinned scheme resolves to, or undefined when it follows the viewer. */
+export declare const pinnedMode: (selection: ThemeSelection) => Mode | undefined;
+/** Type and dimensions do not vary by mode, and no preset currently changes them. */
+export declare const DEFAULT_TYPE_AND_DIMENSIONS: Record<string, string>;
+/** The full token map for one mode. */
+export declare const composeTheme: (selection: ThemeSelection, mode: Mode) => Theme;
+/**
+ * Three states, not two: an explicit choice in either direction, and the system default
+ * when nothing is stamped on the root. A theme that only handled `prefers-color-scheme`
+ * would give a viewer no way to override it.
+ */
+export declare const toCss: (selection: ThemeSelection) => string;

package/dist/types/webpack-plugin/src/AppshellPlugin.d.ts

@@ -24,6 +24,29 @@ export default class AppshellPlugin {
     static findModuleFederationPlugin(webpackConfig: WebpackOptionsNormalized): ModuleFederationPluginInstance | undefined;
     static createTemplate(config: AppshellConfig, plugin: ModuleFederationPluginInstance): AppshellTemplate;
     static validate(template: AppshellTemplate): boolean;
+    /**
+     * Which tokens this package's output actually reaches for.
+     *
+     * Read from the emitted assets rather than declared. The CSS already states it, and a
+     * hand-kept list is a second copy that goes stale the first time somebody adds a token
+     * and forgets to update it. This cannot drift, because it *is* the usage.
+     *
+     * A role referenced both with and without a fallback counts as required: one place in
+     * the package has nothing to fall back to.
+     *
+     * The blind spot is a reference built at runtime from a constructed string, which no
+     * static scan sees — the same limit Tailwind has with dynamic class names. It fails
+     * toward under-reporting, never toward inventing a requirement.
+     *
+     * Takes file contents rather than webpack assets: by `afterEmit` the compilation has
+     * swapped its sources for `SizeOnlySource`, which knows a length and nothing else.
+     * The files are on disk by then, which is what the hook means.
+     */
+    static tokenUsage(sources?: Record<string, string>): {
+        required: string[];
+        optional: string[];
+        unknown: string[];
+    };
     /**
      * Whether a request is shared, and shared as a singleton. `shared` has four shapes —
      * an object, an array of names, an array of objects, or a mix — and a bare name shares

package/dist/types/webpack-plugin/src/index.d.ts

@@ -5,3 +5,4 @@ export type { AppshellManifest } from '@appshell/config';
 export { default as AppshellPlugin } from './AppshellPlugin';
 export { DEV_HINT_FILE, DEV_HINT_VERSION, devServerOrigin, writeDevHint } from './devHint';
 export type { DevHint } from './devHint';
+export { appshellShared, type AppshellSharedOptions } from './shared';

package/dist/types/webpack-plugin/src/shared.d.ts

@@ -0,0 +1,36 @@
+import type { SharedObject } from '@appshell/config';
+export type AppshellSharedOptions = {
+    /** Include the React bindings and React itself. */
+    react?: boolean;
+    /**
+     * Usually your package.json `dependencies`. Anything named here is pinned to the range
+     * you depend on; anything absent is left for module federation to infer, which it does
+     * from the installed package.
+     */
+    dependencies?: Record<string, string>;
+    /** Merged last, so a package can still say something the preset does not. */
+    extra?: SharedObject;
+};
+/**
+ * The `shared` block an Appshell package needs, so it is not written out by hand in every
+ * webpack config and wrong in one of them.
+ *
+ * It exists because the alternative failed in practice: the examples in this repo declared
+ * `@appshell/react` as a singleton in three configs and omitted it in a fourth, which is
+ * silent until a root package calls `useRemote()` and gets `undefined`.
+ *
+ * `AppshellPlugin` cannot inject this itself — `ModuleFederationPlugin` reads its own
+ * options during its `apply`, which webpack has already run by the time it reaches ours.
+ * Spread into your own config, it sidesteps plugin ordering entirely:
+ *
+ * ```js
+ * const { appshellShared } = require('@appshell/webpack-plugin');
+ * const { dependencies } = require('./package.json');
+ *
+ * new ModuleFederationPlugin({
+ *   shared: appshellShared({ react: true, dependencies }),
+ * });
+ * ```
+ */
+export declare const appshellShared: ({ react, dependencies, extra, }?: AppshellSharedOptions) => SharedObject;
+export default appshellShared;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appshell/webpack-plugin",
-  "version": "1.0.0-alpha.23",
+  "version": "1.0.0-alpha.25",
   "description": "Webpack plugin used to generate a global Appshell configuration for micro-frontends built with Module Federation",
   "main": "dist/main.js",
   "types": "dist/types/webpack-plugin/src/index.d.ts",
@@ -32,5 +32,8 @@
     "plugin"
   ],
   "license": "MIT",
-  "gitHead": "c6a783bb4602f305b98b2cc618a5a20e74538fca"
+  "gitHead": "7d90eb91be3cb50aae5aaa680063878dfcaafea2",
+  "dependencies": {
+    "@appshell/tokens": "^1.0.0-alpha.25"
+  }
 }