@appshell/webpack-plugin 1.0.0-alpha.9 → 1.0.0-alpha.90

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

@@ -1,3 +1,2 @@
 declare const _default: import("axios").AxiosInstance;
 export default _default;
-//# sourceMappingURL=axios.d.ts.map

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

@@ -4,4 +4,3 @@ declare const _default: {
     create: (config: AppshellConfig) => Record<string, string>;
 };
 export default _default;
-//# sourceMappingURL=configmap.d.ts.map

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

@@ -1,12 +1,12 @@
 export type AppshellContext = {
     registry?: string;
     /** Activation target as `scope/name`. */
-    environment?: string;
+    application?: string;
     scopeId: string;
     token?: string;
 };
 /**
- * The registry, environment, and token a developer is working against, resolved
+ * The registry, application, and token a developer is working against, resolved
  * the way the CLI resolves them: env var, then `~/.appshell/config`, then a
  * default. This lets the webpack plugin defer to `appshell config set` and
  * `appshell login` instead of requiring per-project configuration.
@@ -18,6 +18,5 @@ export declare const resolveContext: () => AppshellContext;
  */
 export declare const persistedContext: () => {
     registry?: string;
-    environment?: string;
+    application?: string;
 };
-//# sourceMappingURL=context.d.ts.map

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

@@ -3,14 +3,46 @@ export type Credential = {
     refreshToken?: string;
     /** Epoch milliseconds. */
     expiresAt?: number;
+    /**
+     * Where this credential came from, so it can renew itself.
+     *
+     * A refresh token is useless without the issuer that minted it and the client it was
+     * minted for, and neither is derivable from the registry url — an operator is free to
+     * point several registries at one issuer, or one registry at an issuer that moves.
+     * Captured at login for that reason.
+     *
+     * Optional because a credential written before this existed has neither; such a
+     * credential simply cannot refresh, and the next login repairs it.
+     */
+    issuer?: string;
+    clientId?: string;
 };
 export declare const credentialsPath: () => string;
 export declare const saveCredential: (registry: string, credential: Credential) => void;
 export declare const clearCredential: (registry: string) => void;
 /**
+ * The stored access token, or nothing if it has expired.
+ *
  * APPSHELL_TOKEN wins so CI never depends on a writable home directory.
- * Expired tokens are treated as absent; refresh is the caller's concern.
+ *
+ * Deliberately synchronous and deliberately does not refresh: callers that can await
+ * should use `ensureToken`, which renews. This remains for the places that cannot —
+ * `resolveContext` among them, which the webpack plugin calls while building.
  */
 export declare const resolveToken: (registry: string) => string | undefined;
-export declare const requireToken: (registry: string) => string;
-//# sourceMappingURL=credentials.d.ts.map
+/**
+ * The stored access token, renewed first if it has expired.
+ *
+ * `appshell login` obtains a refresh token and, until this existed, nothing ever read it:
+ * every expiry meant a full device-authorization flow — open a browser, enter a code,
+ * approve — with the credential that would have avoided it sitting in the file.
+ *
+ * Renewal cannot widen what a caller may do. The issuer mints the new access token from
+ * the account as it stands now, so a revoked role or a disabled account produces a weaker
+ * token or none at all, never a stale stronger one.
+ *
+ * A failed renewal returns nothing rather than throwing. The caller's own 401 is the
+ * better place to explain what to do, and a network blip on the way to the issuer should
+ * not read as *you are logged out*.
+ */
+export declare const ensureToken: (registry: string) => Promise<string | undefined>;

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

@@ -1,8 +1,36 @@
+import { AppshellTemplate } from './types';
+/**
+ * Substitutes a template into the manifest the registry stores.
+ *
+ * Split out from the file-reading half so a caller holding a template in memory — the
+ * webpack plugin, which just built one — does not have to write it to disk and read it
+ * back to get a manifest. One substitution pass, one place it can be wrong.
+ *
+ * Operates on a copy, because substitution writes in place. Reading a template off disk
+ * hid that: every call parsed its own fresh object, so nothing downstream could notice.
+ * A caller passing a template it still holds would get its `${VAR}` placeholders replaced
+ * underneath it — and the plugin is exactly that caller, building the manifest during
+ * `processAssets` and then writing the same template to disk at `afterEmit`.
+ */
+export declare const manifestFrom: <TMetadata extends Record<string, unknown>>(template: AppshellTemplate) => {
+    vars: Record<string, Record<string, string | number | undefined>>;
+    components: Record<string, import("./types").PublishedRemote<TMetadata>>;
+    remotes?: string[];
+    shared?: import("./types").SharedContract;
+    tokens?: Record<string, import("./types").AppshellTokenUsage>;
+    overrides?: import("./types").AppshellOverrides;
+};
 /**
  * Generates an appshell manifest
  * @param templatePath path of the appshell manifest template to compile into an appshell manifest
  * @returns an appshell manifest
  */
-declare const _default: <TMetadata extends Record<string, unknown>>(templatePath: string) => Promise<import("./types").AppshellManifest<TMetadata> | null>;
+declare const _default: <TMetadata extends Record<string, unknown>>(templatePath: string) => Promise<{
+    vars: Record<string, Record<string, string | number | undefined>>;
+    components: Record<string, import("./types").PublishedRemote<TMetadata>>;
+    remotes?: string[];
+    shared?: import("./types").SharedContract;
+    tokens?: Record<string, import("./types").AppshellTokenUsage>;
+    overrides?: import("./types").AppshellOverrides;
+} | null>;
 export default _default;
-//# sourceMappingURL=generate.manifest.d.ts.map

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

@@ -4,18 +4,17 @@
 export { default as configmap } from './configmap';
 export { persistedContext, resolveContext } from './context';
 export type { AppshellContext } from './context';
-export { clearCredential, credentialsPath, requireToken, resolveToken, saveCredential, } from './credentials';
+export { clearCredential, credentialsPath, ensureToken, resolveToken, saveCredential, } from './credentials';
 export type { Credential } from './credentials';
-export { default as deregister } from './deregister';
-export { default as generateEnv } from './generate.env';
-export { default as generateGlobalConfig } from './generate.global-config';
-export { default as generateManifest } from './generate.manifest';
+export { default as generateManifest, manifestFrom } from './generate.manifest';
+export { loaderOf } from './loader';
 export { default as outdated } from './outdated';
-export { activate, publish } from './publish';
-export type { PublishOptions, PublishResult } from './publish';
-export { default as register } from './register';
+export { parsePackageName } from './package-name';
+export type { PackageName } from './package-name';
+export { activate, openOverlay, publish } from './publish';
+export type { OpenedOverlay, OverlayRemotePatch, PublishOptions, PublishResult } from './publish';
 export { default as sync } from './sync';
-export type { AppshellComposition, AppshellConfig, AppshellConfigRemote, AppshellGlobalConfig, AppshellIndex, AppshellManifest, AppshellRemote, AppshellTemplate, ComparisonResult, ComparisonResults, ComparisonTarget, Metadata, ModuleFederationPluginOptions, PackageSpec, ResolvedRemote, Schema, SharedModuleSpec, } from './types';
+export { caFile, httpsAgent } from './tls';
+export type { AppshellComposition, AppshellConfig, AppshellConfigRemote, AppshellIndex, AppshellManifest, AppshellRemote, AppshellTemplate, AppshellTokenUsage, ComparisonResult, ComparisonResults, ComparisonTarget, Metadata, ModuleFederationPluginOptions, PackageSpec, ResolvedRemote, Schema, SharedConfig, SharedModuleSpec, SharedObject, } from './types';
 export * as utils from './utils';
 export * as validators from './validators';
-//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,18 @@
+import { ModuleFederationLoader } from './types';
+/**
+ * How to load one component, derived from the Module Federation config that emits it.
+ *
+ * One definition, used twice: the manifest a publish stores, and the patch an overlay
+ * sends. Those describe the same thing from either side of a publish, and two copies of
+ * the derivation would disagree the moment one of them changed — the drift being that an
+ * overlay addresses a dev server's bundle by a container name the build no longer uses,
+ * which surfaces as module federation failing to find a container rather than as anything
+ * naming the cause.
+ *
+ * The federation fields sit under a kind rather than at the top level, so they read as one
+ * framework's vocabulary rather than as something generic.
+ */
+export declare const loaderOf: (module: {
+    shareScope?: string;
+    filename?: string;
+}, federationKey: string) => ModuleFederationLoader;

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

@@ -1,3 +1,9 @@
-import { AppshellManifest, AppshellTemplate, ConfigMap } from '../types';
-export declare const toAppshellManifest: <TMetadata extends Record<string, unknown>>(template: AppshellTemplate, args: ConfigMap) => AppshellManifest<TMetadata>;
-//# sourceMappingURL=appshell.config.d.ts.map
+import { AppshellTemplate, ConfigMap, PublishedRemote, SharedContract } from '../types';
+export declare const toAppshellManifest: <TMetadata extends Record<string, unknown>>(template: AppshellTemplate, args: ConfigMap) => {
+    vars: Record<string, Record<string, string | number | undefined>>;
+    components: Record<string, PublishedRemote<TMetadata>>;
+    remotes?: string[];
+    shared?: SharedContract;
+    tokens?: Record<string, import("../types").AppshellTokenUsage>;
+    overrides?: import("../types").AppshellOverrides;
+};

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

@@ -1,4 +1,3 @@
 import { PackageSpec, SharedModuleSpec } from './types';
 declare const _default: (packageSpec: PackageSpec, sharedModuleSpec: SharedModuleSpec) => Promise<import("./types").ComparisonResults>;
 export default _default;
-//# sourceMappingURL=outdated.d.ts.map

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

@@ -0,0 +1,20 @@
+/**
+ * An npm package name split into where it belongs and what it is called.
+ *
+ * `@acme/checkout` is scope `acme`, name `checkout`. A bare `checkout` declares no scope
+ * and belongs wherever the publisher does.
+ *
+ * One definition because three places used to strip the scope with their own copy of the
+ * same regular expression — the cli's `identify`, its workspace scan, and the webpack
+ * plugin. Three copies of a rule about identity is three chances for a package to publish
+ * to a different place than the tooling thinks it does.
+ *
+ * Scope is worth declaring for the reason it is worth checking in: `@acme/checkout` says
+ * where it belongs in a file under review, identically for everyone, rather than landing
+ * in whichever namespace the person running the publish happens to carry.
+ */
+export type PackageName = {
+    scopeId?: string;
+    name: string;
+};
+export declare const parsePackageName: (raw: string) => PackageName;

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

@@ -1,7 +1,15 @@
-import { AppshellManifest, Metadata } from './types';
+import { AppshellManifest, Metadata, ModuleFederationLoader } from './types';
 export type PublishOptions = {
     registry: string;
     token?: string;
+    /**
+     * Where this package belongs, when the package name declares it.
+     *
+     * Omitted means the publisher's own namespace, which is how every publish worked before
+     * this existed. The registry refuses a scope the caller does not own, so declaring one
+     * is a statement of fact rather than a request.
+     */
+    scopeId?: string;
     name: string;
     version: string;
     manifest: AppshellManifest;
@@ -11,19 +19,93 @@ export type PublishOptions = {
     force?: boolean;
 };
 export type PublishResult = {
-    /** `scope/name@version`. The scope comes from the token, not the caller. */
+    /** `scope/name@version`. From the package name where it declares one, else the token. */
     id: string;
     created: boolean;
+    /** Empty unless a shared block was sent. See `openOverlay`. */
+    divergence: SharedDivergence[];
 };
 /**
  * Publishing the same content twice is a no-op; publishing different content
  * under a version that already exists is rejected by the registry, unless
  * `force` is set and the registry is configured to honor it (dev registries).
  */
-export declare const publish: ({ registry, token, name, version, manifest, visibility, metadata, force, }: PublishOptions) => Promise<PublishResult>;
+export declare const publish: ({ registry, token, scopeId, name, version, manifest, visibility, metadata, force, }: PublishOptions) => Promise<PublishResult>;
 /**
- * Activating a newer version of an already active app upgrades it in place.
- * @param environment `scope/name`
+ * Activating a newer version of an already active package upgrades it in place.
+ * @param application `scope/name`
  */
-export declare const activate: (registry: string, environment: string, appId: string, token?: string) => Promise<void>;
-//# sourceMappingURL=publish.d.ts.map
+export declare const activate: (registry: string, application: string, packageId: string, token?: string) => Promise<void>;
+/** What an overlay redirects a single remote to, or introduces one as. */
+export type OverlayRemotePatch = {
+    remoteEntryUrl: string;
+    manifestUrl?: string;
+    /**
+     * How to load this build's copy, from the Module Federation config that emits it.
+     *
+     * Sent because the loader describes the code being loaded, and an overlay points at
+     * this build rather than the published one. Without it a redirect addresses a dev
+     * server's bundle by whatever container name the last publish happened to have, so
+     * renaming the container locally resolves to a container the browser cannot find.
+     *
+     * It is also what lets an overlay introduce a component that is not published yet: a
+     * redirect inherits the published loader, an addition has no published anything.
+     */
+    loader?: ModuleFederationLoader;
+    /**
+     * The remote's `metadata` as this build declares it.
+     *
+     * Sent because a developer iterating on `appshell.config.yaml` is editing metadata as
+     * much as code; without it an overlay serves their new bundle beside the published
+     * route, displayName and icon. The registry replaces rather than merges, so a key
+     * removed from the yaml disappears rather than standing.
+     */
+    metadata?: Metadata;
+};
+/** One shared dependency where a local build and the published version disagree. */
+export type SharedDivergence = {
+    packageId: string;
+    shareScope: string;
+    packageName: string;
+    published?: string;
+    local?: string;
+    singleton: {
+        published: boolean;
+        local: boolean;
+    };
+};
+export type OpenedOverlay = {
+    id: string;
+    confirmUrl: string;
+    url: string;
+    remotes: string[];
+    expiresAt: string;
+    /**
+     * False when an overlay was already open for this developer and this one extended it.
+     * A browser carries a single overlay id, so an extended overlay is one some browser has
+     * already confirmed — nothing needs sending back to the confirmation page.
+     */
+    created: boolean;
+    /**
+     * What this build declares that the published version does not. Empty unless a shared
+     * block was sent — see `openOverlay`.
+     */
+    divergence: SharedDivergence[];
+};
+/**
+ * Points some of an application's remotes at a developer's own machine, for that
+ * developer only.
+ *
+ * This is what a local dev loop does instead of republishing. A published version is
+ * immutable and content-addressed; overwriting one on every rebuild makes the digest
+ * describe whoever built last, and two developers sharing a registry overwrite each
+ * other. An overlay is per-developer, per-browser and expiring, so neither happens.
+ *
+ * Extending is the normal case rather than the exception: the registry merges remotes
+ * into whatever overlay this developer already holds, so serving two micro-frontends
+ * locally redirects both without minting a second overlay or asking for confirmation
+ * twice.
+ *
+ * @param application `scope/name`
+ */
+export declare const openOverlay: (registry: string, application: string, remotes: Record<string, OverlayRemotePatch>, token?: string, shared?: Record<string, unknown>, shellFlavor?: "prod" | "dev") => Promise<OpenedOverlay>;

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

@@ -18,4 +18,3 @@ export declare const groupByBaselineModule: (conflicts: Record<string, Compariso
  */
 declare const _default: (workingDir: string, registry: string, conflicts: Record<string, ComparisonResult>, resolutionStrategy?: ResolutionStrategy, packageManager?: PackageManager, dryRun?: boolean) => Promise<void>;
 export default _default;
-//# sourceMappingURL=sync.d.ts.map

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

@@ -0,0 +1,23 @@
+import https from 'https';
+/**
+ * An extra CA bundle to trust, from `ca-file` in the cli config or `APPSHELL_CA_FILE`.
+ *
+ * A registry behind a private CA — a corporate root, a TLS-inspecting proxy, or a local
+ * cluster using mkcert — fails with "unable to verify the first certificate", which says
+ * nothing about which host or what to do. Node can be told through `NODE_EXTRA_CA_CERTS`
+ * or `--use-system-ca`, but both are environment variables a user has to remember in
+ * every new terminal, and neither travels with the registry they apply to.
+ *
+ * npm draws the same conclusion with `cafile` in .npmrc: trust is configuration of the
+ * registry you talk to, not of the shell you happen to be in.
+ */
+export declare const caFile: () => string | undefined;
+/**
+ * The agent to use for registry and issuer requests, or undefined when no CA is
+ * configured and Node's defaults apply.
+ *
+ * A configured file that does not exist throws rather than being skipped: falling back
+ * silently would reproduce the original certificate error, having been told exactly how
+ * to avoid it.
+ */
+export declare const httpsAgent: () => https.Agent | undefined;

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

@@ -1,4 +1,6 @@
+import type { AppshellIndex, AppshellRemote, Metadata, RemoteLoader } from '@appshell/runtime';
 import { JSONSchema4, JSONSchema6, JSONSchema7 } from 'json-schema';
+export type { AppshellIndex, AppshellRemote, Metadata, ModuleFederationLoader, RemoteLoader, } from '@appshell/runtime';
 export type Schema = JSONSchema4 | JSONSchema6 | JSONSchema7;
 export type ConfigValidator = {
     validate: <T>(...config: T[]) => void;
@@ -43,58 +45,165 @@ export type ComparisonTarget = {
     name: string;
     dependencies: Record<string, string | undefined>;
 };
+/**
+ * Every key `appshell config set` accepts, kept adjacent to the type it must agree with.
+ *
+ * It used to live in the set handler, and adding `caFile` to CliConfig without touching it
+ * produced a setting the cli could read and refuse to write.
+ */
+export declare const CLI_SETTINGS: readonly ["registry", "application", "scopeId", "authIssuer", "clientId", "apiKey", "apiKeyHeader", "caFile"];
+export type CliSetting = (typeof CLI_SETTINGS)[number];
 export type CliConfig = Record<string, string> & {
     apiKey: string;
+    /**
+     * PEM bundle to trust in addition to Node's built-ins, for a registry behind a private
+     * CA. Optional, and absent from `config init` output: an empty path is not a default
+     * worth writing, and its absence means "use Node's defaults".
+     */
+    caFile?: string;
     registry: string;
-    environment: string;
+    application: string;
     scopeId: string;
     authIssuer: string;
     clientId: string;
 };
+/**
+ * Neither `url` nor `filename`.
+ *
+ * `url` is an origin, and an origin belongs to a deployment: a package is published once
+ * and deployed many times, so a url here would freeze one environment's answer into an
+ * immutable version and make the artifact's digest depend on where it was built.
+ *
+ * `filename` was a hand-written copy of the Module Federation `filename`, which is what
+ * actually decides the file webpack emits. Two statements of one fact, and only one of
+ * them is enforced by anything.
+ */
 export type AppshellConfigRemote<TMetadata = Metadata> = {
     id: string;
-    url: string;
-    filename: string;
     metadata: TMetadata;
 };
 export type AppshellConfig<TMetadata = Metadata> = {
     name?: string;
-    remotes?: Record<string, AppshellConfigRemote<TMetadata>>;
-    environment?: Record<string, unknown>;
+    /**
+     * What the registry should publish this package as. `--visibility` overrides it.
+     *
+     * Declared here but deliberately absent from the manifest, as `name` already is: the
+     * manifest is hashed into the package digest, and visibility is not a property of the
+     * artifact. Keeping it out is what lets a package be made public later without its
+     * content changing identity.
+     */
+    visibility?: 'public' | 'private';
+    /**
+     * What this package publishes, keyed by federation entrypoint.
+     *
+     * Appshell's own word rather than a framework's. It was `remotes`, which is MF's word
+     * for the opposite — what a package consumes — so the file read inverted to anyone who
+     * knew the framework. `exposes` would fix that and put MF's vocabulary at the top level
+     * of appshell's model, which is what the loader recipe exists to prevent.
+     */
+    components?: Record<string, AppshellConfigRemote<TMetadata>>;
+    /**
+     * What this package consumes, by the name it refers to them by.
+     *
+     * A flat list because a referenced remote is required by definition: unbound, the region
+     * renders an error. `RemoteSlot`'s `fallback` is a loading placeholder — it shows while
+     * the remote arrives, not when it is absent — so unlike a design token's `var()`
+     * fallback it describes no degraded-but-working state.
+     *
+     * The application binds each name to a registry address, so a package never states the
+     * scope its siblings were published into — which it cannot know, since scope is assigned
+     * by whoever publishes.
+     */
+    remotes?: string[];
+    vars?: Record<string, unknown>;
     overrides?: AppshellOverrides;
 };
 export type AppshellTemplate<TMetadata = Metadata> = {
     name?: string;
-    remotes?: Record<string, AppshellConfigRemote<TMetadata>>;
+    /** Carried from the yaml for publish to read; never mapped into the manifest. */
+    visibility?: 'public' | 'private';
+    components?: Record<string, AppshellConfigRemote<TMetadata>>;
+    remotes?: string[];
     module: ModuleFederationPluginOptions;
-    environment?: Record<string, unknown>;
+    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;
+/** The parts of a remote an application may point somewhere else. */
+export type RemoteOverride = {
+    remoteEntryUrl?: string;
+    manifestUrl?: string;
 };
 export type AppshellOverrides = {
-    environment: Record<string, Record<string, string | number | undefined>>;
+    vars: Record<string, Record<string, string | number | undefined>>;
+    /**
+     * Where an application loads a remote from, keyed by registry address.
+     *
+     * A package is published once; an application is deployed many times, per environment.
+     * The origin a bundle is served from is a property of a deployment, so it belongs to
+     * whoever deploys rather than being frozen into an immutable artifact at publish — which
+     * is also what makes adopting someone else's package and serving it yourself a spec edit
+     * rather than a republish.
+     *
+     * `filename` stays in the manifest: `remoteEntry.js` is genuinely build output. Only the
+     * origin varies by environment.
+     */
+    remotes?: Record<string, RemoteOverride>;
+};
+/**
+ * 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[];
+};
+/** A shared-dependency contract, named as one framework's model among possible models. */
+export type SharedContract = {
+    apiVersion: 'federation.appshell.org/v1';
+    kind: 'ModuleFederation';
+    /** Keyed by share scope, as Module Federation groups them. */
+    scopes: Record<string, SharedObject>;
 };
 export type AppshellManifest<TMetadata = Metadata> = {
-    remotes: Record<string, AppshellRemote<TMetadata>>;
-    modules: Record<string, ModuleFederationPluginOptions>;
-    environment: Record<string, Record<string, string | number | undefined>>;
+    /** What this package publishes, keyed by federation entrypoint. */
+    components: Record<string, PublishedRemote<TMetadata>>;
+    /** What it consumes, by local name; the application binds each to an address. */
+    remotes?: string[];
+    /**
+     * The shared-dependency contract this package was built against.
+     *
+     * Tagged like the loader recipe, and for the same reason: share scopes, singletons and
+     * version ranges are Module Federation's model of the problem, which single-spa and
+     * import maps solve differently. This replaced `modules`, which stored MF's plugin
+     * options verbatim — one reader took two fields from it, while its source paths and
+     * type-generation flags sat inside the package digest.
+     */
+    shared?: SharedContract;
+    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>;
-export type AppshellGlobalConfig<TMetadata = Metadata> = {
-    index: AppshellIndex;
-    metadata?: Record<string, TMetadata>;
-    overrides?: AppshellOverrides;
+/**
+ * A remote as a package publishes it: what the build knows about itself, and nothing
+ * about where it ends up.
+ *
+ * Distinct from `AppshellRemote`, which is the same remote after the registry has
+ * resolved it for the browser. They were one type, which is why the origin ended up in
+ * the artifact: the browser genuinely needs a url, so the published form appeared to as
+ * well. The registry supplies it at composition, from the address and its serving plane.
+ */
+export type PublishedRemote<TMetadata = Metadata> = {
+    id: string;
+    loader: RemoteLoader;
+    metadata: TMetadata;
 };
 /** An `AppshellRemote` the registry already resolved, so the browser needs no manifest fetch. */
 export type ResolvedRemote<TMetadata = Metadata> = AppshellRemote<TMetadata>;
@@ -102,19 +211,45 @@ export type ResolvedRemote<TMetadata = Metadata> = AppshellRemote<TMetadata>;
  * The wire contract for `window.__appshell_config__`. Deliberately not an
  * `AppshellManifest`: that is a build artifact, and reusing it left it unclear
  * which fields the browser actually needs. `modules` is build-time webpack
- * config and never crosses the wire; `environment` arrives already merged with
- * the environment's overrides, leaving the browser only local overrides to apply.
+ * config and never crosses the wire; `vars` arrives already merged with the
+ * application's overrides, leaving the browser only local overrides to apply.
  */
 export type AppshellComposition<TMetadata = Metadata> = {
     /** `scope/name` — makes the payload self-describing for fetch-on-miss and for `env diff`. */
-    environmentId: string;
+    applicationId: string;
     revision: number;
     /** The remote key the host mounts at the root, and the props it is given. */
     root: string;
     rootProps: Record<string, unknown>;
     index: AppshellIndex;
     remotes: Record<string, ResolvedRemote<TMetadata>>;
-    environment: Record<string, Record<string, string | number | undefined>>;
+    vars: Record<string, Record<string, string | number | undefined>>;
+    /**
+     * Present whenever a per-developer overlay changed anything about this render — a
+     * redirected remote, a different shell bundle, a substituted theme, or any combination.
+     * The shell is expected to surface it: a page that quietly runs code from somewhere
+     * else is the one thing this feature must never be, and swapping the shell or the theme
+     * out counts.
+     *
+     * `shellFlavor` is what was actually served, not what was asked for. `theme` is the ref
+     * the overlay substituted, present only when it substituted one.
+     */
+    overlay?: {
+        id: string;
+        remotes: string[];
+        /**
+         * Those of `remotes` the overlay introduced rather than redirected — components the
+         * application does not publish, running for this developer and nobody else.
+         *
+         * Separate from `remotes` because the two are not the same claim. A redirected
+         * component exists for everyone and this browser runs a different copy of it; an
+         * added one does not exist outside this overlay at all, so a feature built on top of
+         * one works here and is absent everywhere else.
+         */
+        added?: string[];
+        shellFlavor: 'prod' | 'dev';
+        theme?: string;
+    };
 };
 /**
  * Advanced configuration for modules that should be exposed by this container.
@@ -293,4 +428,3 @@ export interface ModuleFederationPluginOptions {
      */
     shared?: (string | SharedObject)[] | SharedObject;
 }
-//# sourceMappingURL=types.d.ts.map

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

@@ -1,3 +1,2 @@
 declare const _default: (token?: string, chars?: number) => string;
 export default _default;
-//# sourceMappingURL=blur.d.ts.map

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

@@ -5,4 +5,3 @@ export declare const compareDependencies: (sample: ComparisonTarget, baseline: C
 export declare const compareSharedDependencies: (packageSpec: PackageSpec, sharedModule: SharedModuleSpec) => ComparisonResults;
 export declare const compareSharedModules: (sampleSpec: SharedModuleSpec, baselineSpec: SharedModuleSpec) => ComparisonResults;
 export declare const printResults: (results: ComparisonResults) => void;
-//# sourceMappingURL=compare.d.ts.map

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

@@ -3,4 +3,3 @@ import { CliConfig } from '../types';
 export declare const readConfig: (configPath: string) => CliConfig;
 export declare const writeConfig: (configPath: string, config: CliConfig) => void;
 export declare const mergeConfigWithArgs: (config: CliConfig, argv: yargs.ArgumentsCamelCase<unknown>) => void;
-//# sourceMappingURL=config.d.ts.map

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

@@ -8,4 +8,3 @@ declare const _default: (pattern: {
     to: string;
 }) => void;
 export default _default;
-//# sourceMappingURL=copy.d.ts.map

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

@@ -0,0 +1,10 @@
+/**
+ * Serialises a value to YAML.
+ *
+ * The counterpart to `load`, and here rather than at each call site so the YAML library
+ * stays in one package. `appshell theme init` writes a file an author then edits, so the
+ * output is line-wrapped generously — a colour value broken across lines is technically
+ * valid and horrible to read.
+ */
+declare const dump: (value: unknown) => string;
+export default dump;