@appshell/loader 1.0.0-alpha.9 → 1.0.0-alpha.91

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;

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

@@ -2,9 +2,6 @@ export { default as blur } from './blur';
 export { compareDependencies, compareDependency, compareSharedDependencies, compareSharedModules, extractDependencies, printResults, } from './compare';
 export { mergeConfigWithArgs, readConfig, writeConfig } from './config';
 export { default as copy } from './copy';
-export { default as isValidUrl } from './isValidUrl';
+export { default as dump } from './dump';
 export { default as list } from './list';
 export { default as load, loadAll } from './load';
-export { default as loadJson } from './loadJson';
-export { default as merge } from './merge';
-//# sourceMappingURL=index.d.ts.map

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

@@ -7,4 +7,3 @@
  */
 declare const list: (dirPath: string, depth?: number, target?: string | RegExp) => string[];
 export default list;
-//# sourceMappingURL=list.d.ts.map

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

@@ -11,4 +11,3 @@ declare const load: <TSchema>(configPath: string) => TSchema;
  */
 export declare const loadAll: <TSchema>(...paths: string[]) => TSchema[];
 export default load;
-//# sourceMappingURL=load.d.ts.map

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

@@ -1,4 +1,3 @@
 import { ConfigValidator } from '../types';
 declare const _default: ConfigValidator;
 export default _default;
-//# sourceMappingURL=AppshellTemplateValidator.d.ts.map

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

@@ -1,4 +1 @@
-export { default as AppshellGlobalConfigValidator } from './AppshellGlobalConfigValidator';
-export { default as AppshellManifestValidator } from './AppshellManifestValidator';
 export { default as AppshellTemplateValidator } from './AppshellTemplateValidator';
-//# sourceMappingURL=index.d.ts.map

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

@@ -3,4 +3,3 @@ export type { RemoteLoaderOptions } from './remoteLoader';
 export * from './resolvers';
 export * from './types';
 export default remoteLoader;
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,14 +1,13 @@
-import { ShareScope } from './types';
-declare global {
-    function __webpack_init_sharing__(id: string): Promise<void>;
-    const __webpack_share_scopes__: {
-        default: ShareScope;
-    };
-    interface Window {
-        [key: string]: unknown;
-        __webpack_share_scopes__: Record<string, ShareScope>;
-    }
-}
-declare const _default: <TComponent>(scope: string, module: string, shareScope?: string) => Promise<TComponent>;
-export default _default;
-//# sourceMappingURL=loadAppshellComponent.d.ts.map
+import type { RemoteLoader } from '@appshell/runtime';
+/**
+ * Dispatches on the loader's kind rather than assuming federation.
+ *
+ * There is one kind today. Naming it is what lets a second — single-spa, import maps —
+ * arrive without reinterpreting manifests already published, and what stops federation's
+ * vocabulary reading as though it were appshell's.
+ */
+export declare const load: <TComponent>(remote: {
+    loader: RemoteLoader;
+    remoteEntryUrl: string;
+}) => Promise<TComponent>;
+export default load;

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

@@ -1,4 +1,4 @@
-import type { AppshellComposition, AppshellGlobalConfig } from '@appshell/config';
+import type { AppshellComposition } from '@appshell/config';
 import { type RemoteResolver } from './resolvers';
 declare global {
     interface Window {
@@ -10,6 +10,5 @@ export type RemoteLoaderOptions = {
     /** Replaces the resolver chain outright; a seam for tests and embedders. */
     resolver?: RemoteResolver;
 };
-declare const _default: (config: AppshellGlobalConfig, options?: RemoteLoaderOptions) => <TComponent>(key: string) => Promise<readonly [null, null] | readonly [Awaited<TComponent>, import("@appshell/config").AppshellManifest]>;
+declare const _default: (options?: RemoteLoaderOptions) => <TComponent>(key: string) => Promise<readonly [Awaited<TComponent>, import("@appshell/config").ResolvedRemote]>;
 export default _default;
-//# sourceMappingURL=remoteLoader.d.ts.map

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

@@ -1,20 +1,12 @@
-import type { AppshellComposition, AppshellGlobalConfig, AppshellManifest, ResolvedRemote } from '@appshell/config';
+import type { AppshellComposition, ResolvedRemote } from '@appshell/config';
 export type RemoteResolution = {
     remote: ResolvedRemote;
-    /** Already merged with the environment's overrides — nothing left for the browser to layer on. */
-    environment: Record<string, string | number | undefined>;
-    /** Back-compat payload for `ManifestProvider`; synthesized when the source was a composition. */
-    manifest: AppshellManifest;
+    /** Already merged with the application's overrides — nothing left for the browser to layer on. */
+    vars: Record<string, string | number | undefined>;
 };
 export type RemoteResolver = (key: string) => Promise<RemoteResolution | undefined>;
 /** The registry inlined the composition into the page, so no network call is needed. */
 export declare const inlineResolver: (composition?: AppshellComposition) => RemoteResolver;
-/** Fetch-on-miss: covers an app activated after this page was served. */
+/** Fetch-on-miss: covers a package activated after this page was served. */
 export declare const registryResolver: (composition?: AppshellComposition, origin?: string) => RemoteResolver;
-/**
- * Pre-registry hosts: follow `index[key]` to the app's own manifest. The override
- * merge stays here because in this mode no server has done it.
- */
-export declare const legacyManifestResolver: (config: AppshellGlobalConfig) => RemoteResolver;
 export declare const chainResolvers: (...resolvers: RemoteResolver[]) => RemoteResolver;
-//# sourceMappingURL=resolvers.d.ts.map

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

@@ -8,4 +8,3 @@ export interface ModuleContainer<TComponent> {
     init(shareScope: ShareScope<TComponent>): Promise<void>;
     get(module: string): Promise<() => Record<string, TComponent>>;
 }
-//# sourceMappingURL=types.d.ts.map

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/identity.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Who is looking at the page, as the registry was told by the gateway.
+ *
+ * Unlike vars this is not scope-specific — there is one visitor per page, not one
+ * per package — so it lives in the main entry rather than needing the subpath
+ * trick `@appshell/runtime/vars` uses to get a per-package scope substituted.
+ *
+ * It is also not delivered through the vars store, and that is a constraint rather
+ * than a preference: `setVars` freezes on first write and throws on replacement,
+ * which is what stops one package overwriting another's configuration. Identity
+ * changes — sign-in, sign-out, token refresh — so it cannot live behind a
+ * write-once door without either breaking that guarantee or never updating.
+ */
+/**
+ * A discriminated union rather than an optional user, so `username` cannot be read
+ * without the anonymous case having been handled. The compiler enforces what a
+ * convention would only ask for.
+ */
+export type Identity = {
+    authenticated: false;
+} | {
+    authenticated: true;
+    subject: string;
+    username: string;
+    roles: string[];
+};
+export declare const ANONYMOUS: Identity;
+declare global {
+    interface Window {
+        __appshell_identity__?: unknown;
+    }
+}
+/**
+ * The visitor, or the anonymous identity when there is none.
+ *
+ * Never throws and never returns undefined — an absent or malformed value is
+ * anonymous, which is a state every caller already has to handle. That is the
+ * opposite of `readVars`, which throws when a scope is missing, and the difference
+ * is deliberate: a package with no configuration cannot do its job, while a package
+ * with no signed-in user usually can and simply renders differently.
+ *
+ * This is a typed accessor, not a boundary. The value is inlined into the document
+ * and any script on the page can read it directly, exactly as with vars. Treat it
+ * as what the server said about the visitor, never as proof of anything: it carries
+ * no token and grants nothing. Anything that matters is re-checked server-side.
+ */
+export declare const getIdentity: () => Identity;

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

@@ -0,0 +1,6 @@
+export { MissingScopeError, MissingVarsError, VarsConflictError } from './errors';
+export { ANONYMOUS, getIdentity } from './identity';
+export type { Identity } from './identity';
+export { hasVars, readVars, resetVars, setVars } from './store';
+export type { Vars } from './types';
+export type { AppshellIndex, AppshellRemote, Metadata, ModuleFederationLoader, RemoteLoader, } 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,58 @@
+/**
+ * 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>;
+/**
+ * How a host loads a remote, named as one kind among possible kinds.
+ *
+ * scope, module and shareScope are Module Federation's vocabulary, and they used to sit
+ * at the top level of a remote where nothing said so — which is what would have made a
+ * second framework awkward, not the words themselves. Nested under a kind they are
+ * exactly correct, and something like single-spa slots beside them without reinterpreting
+ * anything already published.
+ *
+ * apiVersion follows the house style set by appshell.app.yaml, and the group is appshell's
+ * because appshell owns this schema: it decides which fields it stores, even though the
+ * fields describe federation concepts. If federation ever needs a different recipe that is
+ * a v2, and manifests published under v1 keep meaning what they meant — which matters,
+ * because they are immutable and hashed.
+ */
+export type ModuleFederationLoader = {
+    apiVersion: 'federation.appshell.org/v1';
+    kind: 'ModuleFederation';
+    scope: string;
+    module: string;
+    shareScope?: string;
+    /** The entry file the build emits, conventionally remoteEntry.js. */
+    filename: string;
+    /**
+     * What built this, recorded as a fact rather than a constraint.
+     *
+     * Deliberately not a version range. A range is a claim about the environment, and a
+     * package cannot make it: it knows what built it and not what will load it, and the
+     * host is what registers the remote. Freezing one into an immutable artifact is the
+     * same mistake as freezing its origin.
+     */
+    builtWith?: string;
+};
+export type RemoteLoader = ModuleFederationLoader;
+/** 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;
+    loader: RemoteLoader;
+    metadata: TMetadata;
+};
+/** Remote key to manifest url. */
+export type AppshellIndex = Record<string, string>;