@loomcli/core 0.2.0 → 0.3.0

package/dist/application.d.ts

@@ -1,25 +1,23 @@
-import type { AfterAction, AfterArgument, AfterCommand, Command, CommandMethod, CommandState } from './command.js';
-import type { FailureRenderer } from './errors.js';
+import type { AfterAction, AttachmentConstraint, AfterArgument, AfterCommand, AfterResult, Command, CommandMethod, CommandState, ResultMethod } from './command.js';
+import type { ApplicationEnvironment, applicationEnvironment } from './environment.js';
 import type { ExtensionValue } from './extension.js';
-import type { GlobalOptions } from './globals.js';
+import type { GlobalsState } from './globals.js';
 import type { CommandGraph } from './inspect.js';
 import type { Plugin } from './plugin.js';
-import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, MultipleConstraint, NameConstraint, ExitCode, OptionConfig, OptionValue, RunOptions, ValidateOmittedConstraint } from './types.js';
+import type { RenderingPolicy } from './rendering.js';
+import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, MultipleConstraint, NameConstraint, ExitCode, OptionConfig, OptionValue, ResultViews, ResultViewsOf, RowViews, RunOptions, ValidateOmittedConstraint } from './types.js';
+import type { ViewOverride } from './view.js';
 /**
  * Every authoring call an Application can publish, beside `run()` and `name`, which always remain.
  * An Application's type state is a subset of these, and each call removes the names it invalidates.
  * The unnamed root declares what a named Command declares, except for `alias()`: the root answers
  * to no bare token, so it has no name to alias.
  */
-export type ApplicationMethod = Exclude<CommandMethod, 'alias'>;
-/**
- * Everything an application configures beside its declarations: the options every Command shares,
- * and the renderers that answer the failure classes core throws.
- */
-export interface ApplicationOptions<Globals = {}> {
-    globals?: GlobalOptions<Globals>;
-    failures?: readonly FailureRenderer[];
-    plugins?: readonly Plugin[];
+export type ApplicationMethod = Exclude<CommandMethod, 'alias'> | 'globalOption';
+export interface ApplicationOptions<Plugins extends readonly Plugin[] = readonly Plugin[]> {
+    rendering?: RenderingPolicy;
+    views?: readonly ViewOverride[];
+    plugins?: Plugins;
     extensions?: readonly ExtensionValue<'command'>[];
     description?: string;
     version?: string;
@@ -28,33 +26,63 @@ export interface ApplicationOptions<Globals = {}> {
  * The Application holds the unnamed root's declaration state and applies the same transitions a
  * Command does, so each declaration call has one typed implementation and no builder to recover.
  */
-declare class ApplicationBuilder<Args, Options, Globals, State extends ApplicationMethod = ApplicationMethod> {
+declare class ApplicationBuilder<Args, Options, Globals, State extends ApplicationMethod = ApplicationMethod, Plugins extends readonly Plugin[] = readonly [], Result = unknown> {
     #private;
-    readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals>;
+    readonly [applicationEnvironment]: ApplicationEnvironment<Globals, Plugins>;
+    readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals, Result>;
     constructor(name: string, root: CommandState<Args, Options, Globals>, config: {
         declared: DeclaredFacts;
-        failures: readonly FailureRenderer[];
+        views: unknown;
         options?: unknown;
-        plugins: readonly Plugin[];
+        plugins: Plugins | undefined;
+        globals: GlobalsState<Globals>;
     });
     get name(): string;
-    argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args & Record<Name, ArgumentValue<Config>>, Options, Globals, AfterArgument<State>>;
-    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<MultipleConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args, Options & Record<Name, OptionValue<Config>>, Globals, State>;
-    /** The action is the last call, so it returns `AfterAction`: only `run()` and `name` remain. */
-    action(handler: Action<Args, Globals & Options>): Application<Args, Options, Globals>;
+    argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args & Record<Name, ArgumentValue<Config>>, Options, Globals, AfterArgument<State>, Plugins, Result>;
+    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<MultipleConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args, Options & Record<Name, OptionValue<Config>>, Globals, State, Plugins, Result>;
+    globalOption<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & (Name extends keyof Options ? {
+        'This option name is already declared as a local option': Name;
+    } : unknown) & NoInfer<DefaultConstraint<Config>> & NoInfer<MultipleConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args, Options, Globals & Record<Name, OptionValue<Config>>, State, Plugins, Result>;
+    /** Registering the action closes input authoring; extension configuration remains available. */
+    action(handler: Action<Args, Globals & Options, Result>): Application<Args, Options, Globals, AfterAction, Plugins, Result>;
     /** A child arrives in any type state, because its own action is the call that finished it. */
-    command(child: Command<unknown, unknown, Globals>): Application<Args, Options, Globals, AfterCommand<State>>;
+    command<const Child extends Command<unknown, unknown, Globals>>(child: Child & NoInfer<AttachmentConstraint<Globals, Child>>): Application<Args, Options, Globals, AfterCommand<Exclude<State, 'globalOption'>>, Plugins, Result>;
+    /**
+     * The value the root action produces for its consumer. The type argument is stated by the
+     * author, as it is on a Command.
+     */
+    result<Value>(declaration: {
+        views: ResultViews<NoInfer<Value>>;
+    }): Application<Args, Options, Globals, AfterResult<State>, Plugins, {
+        kind: 'value';
+        value: Value;
+    }>;
+    /** The same declaration over a sequence, whose type argument is one row. */
+    rows<Row>(declaration: {
+        views: RowViews<NoInfer<Row>>;
+    }): Application<Args, Options, Globals, AfterResult<State>, Plugins, {
+        kind: 'rows';
+        row: Row;
+    }>;
+    /** Views after the fact, merged by key, as it is on a Command. */
+    views(replacements: ResultViewsOf<Result>, options?: {
+        default?: string;
+    }): Application<Args, Options, Globals, State, Plugins, Result>;
+    extend(...values: readonly ExtensionValue<'command'>[]): Application<Args, Options, Globals, State, Plugins, Result>;
     /**
-     * One wrapper for every declaration call, so the Application keeps its name. The next state
+     * Root declaration calls preserve the Application configuration. The next state
      * travels through this call: each method names its transition in its return type, and the
      * wrapper publishes the same runtime value in exactly that state.
      */
     private derive;
     /**
-     * Every rule that reads the declarations alone, in the order `run()` reads them: the options
-     * slot, the installed list, the application's failure registrations, each plugin's declarations,
-     * then the whole Command graph. The registry is published as soon as it is known, so a later
-     * declaration error still reaches the renderers the application registered for it.
+     * Every rule that reads the declarations alone, in the order `run()` reads them: the
+     * application's own view overrides, the options slot, the installed list, each plugin's
+     * declarations, then the whole Command graph. The application's overrides are read and published
+     * first, because they need core's identities and nothing else, so every later declaration error
+     * reaches them, while a fault in that list itself reports through core's own text. The merged
+     * registry is published once the whole build has succeeded, so a build-time fault never resolves
+     * through a plugin's overrides, which build has not yet validated.
      */
     private prepare;
     /**
@@ -74,19 +102,16 @@ declare class ApplicationBuilder<Args, Options, Globals, State extends Applicati
  * It defaults to the state after `action()`, which publishes the fewest calls, so
  * `Application<A, O, G>` accepts an application in any state, a finished one included.
  */
-export type Application<Args = {}, Options = {}, Globals = {}, State extends ApplicationMethod = AfterAction> = Pick<ApplicationBuilder<Args, Options, Globals, State>, typeof declaredTypes | 'inspect' | 'name' | 'run' | State>;
+export type Application<Args = {}, Options = {}, Globals = {}, State extends ApplicationMethod = AfterAction, Plugins extends readonly Plugin[] = readonly Plugin[], Result = unknown> = Pick<ApplicationBuilder<Args, Options, Globals, State, Plugins, Result>, typeof applicationEnvironment | typeof declaredTypes | 'extend' | 'inspect' | 'name' | 'run' | State | ResultMethod<Result>>;
 interface ApplicationConstructor {
-    new (name: string): Application<{}, {}, {}, ApplicationMethod>;
-    new <Globals = {}>(name: string, options: ApplicationOptions<Globals>): Application<{}, {}, Globals, ApplicationMethod>;
+    new (name: string): Application<{}, {}, {}, ApplicationMethod, readonly []>;
+    new <const Plugins extends readonly Plugin[] = readonly []>(name: string, options: ApplicationOptions<Plugins>): Application<{}, {}, {}, ApplicationMethod, Plugins>;
 }
 /** The same facts as the constructor captured them, before any rule has read them. */
 interface DeclaredFacts {
+    rendering: unknown;
     description: unknown;
     version: unknown;
 }
-/**
- * The public constructor takes a name and one options object. The globals type narrows to the
- * supplied value, and the failure renderers configure the application the way its commands do.
- */
 export declare const Application: ApplicationConstructor;
 export {};

package/dist/application.js

@@ -1,16 +1,19 @@
 import { runInvocation } from './chain.js';
-import { attachChild, buildGraph, collectInputs, declareAction, declareArgument, declareOption, freshState, } from './command.js';
-import { buildFailures, DeclarationError, describeFailure, InternalError, mergeFailures, reasonOf, toFailure, } from './errors.js';
+import { attachChild, buildGraph, collectInputs, declareAction, declareExtensions, declareArgument, declareOption, declareResult, declareResultViews, freshState, recordGlobalOption, } from './command.js';
+import { DeclarationError, InternalError, reasonOf, toFailure } from './errors.js';
 import { checkDescription, checkNoListingFacts, checkVersion, isPlainObject } from './facts.js';
-import { isGlobalOptions } from './globals.js';
+import { declareGlobalOption, emptyGlobals } from './globals.js';
 import { captureHost } from './host.js';
 import { inspectGraph } from './inspect.js';
+import { coreViews } from './lanes.js';
 import { Output, reportPlainly } from './output.js';
 import { buildPlugins, installPlugins, ownedSignals, pluginSentence } from './plugin.js';
+import { renderingPolicy } from './rendering.js';
 import { bracketRun, cancellationCode, isCancellationEcho } from './signals.js';
 import { captureConfig, checkDeclarations, prepareInputs } from './validation.js';
+import { buildViews, describeFailure, viewIdentities } from './view.js';
 /** The registry a failure is reported through when the application's own could not be built. */
-const noRegistrations = new Map();
+const noViews = [];
 /**
  * Whether one failure is the cancellation the run already reports, which core does not report a
  * second time. Any other failure after cancellation is rendered as usual.
@@ -18,6 +21,29 @@ const noRegistrations = new Map();
 function silenced(thrown, signal, cancelled) {
     return cancelled !== undefined && isCancellationEcho(thrown, signal.reason);
 }
+/**
+ * The stand-in for "this run has no primary failure", which is a value no thrown value can be.
+ * `undefined` is itself throwable, so the absence is spelled here rather than borrowed from it.
+ */
+const noPrimary = Symbol('no primary');
+/**
+ * Whether the primary outcome carries one recorded cause already: the value itself, or a failure
+ * that wraps it at any depth, which an action that caught a source failure and rethrew its own
+ * produces. Such a cause is reported once, through the primary outcome that carries it.
+ */
+function carried(primary, cause) {
+    const seen = new Set();
+    let value = primary;
+    while (value !== noPrimary && !seen.has(value)) {
+        if (value === cause) {
+            return true;
+        }
+        seen.add(value);
+        // A failure wraps its own cause under `cause`, and one that declares none ends the walk.
+        value = value instanceof Error && 'cause' in value ? value.cause : noPrimary;
+    }
+    return false;
+}
 /**
  * The caller's own signal, read where it enters. A JavaScript caller reaches the slot with any
  * value, and a value that is not an `AbortSignal` would otherwise escape as a raw TypeError.
@@ -38,8 +64,10 @@ function checkSignal(signal) {
 class ApplicationBuilder {
     #name;
     #root;
-    #failures;
+    // The override list the constructor read out of the options slot, unexamined until build.
+    #views;
     #plugins;
+    #globals;
     // The constructor's raw options argument, kept for the slot's own shape rules.
     // The options-slot rules answer at the same point every other authoring fault does:
     // `inspect()` and `run()`.
@@ -48,10 +76,11 @@ class ApplicationBuilder {
     #declared;
     constructor(name, root, config) {
         this.#declared = config.declared;
-        this.#failures = config.failures;
+        this.#views = config.views;
         this.#name = name;
         this.#options = config.options;
         this.#plugins = config.plugins;
+        this.#globals = config.globals;
         this.#root = root;
     }
     get name() {
@@ -73,7 +102,21 @@ class ApplicationBuilder {
         };
         return this.derive(declareOption(this.#root, input));
     }
-    /** The action is the last call, so it returns `AfterAction`: only `run()` and `name` remain. */
+    globalOption(name, config) {
+        const input = {
+            config: captureConfig(config),
+            kind: 'option',
+            name,
+        };
+        return new ApplicationBuilder(this.#name, recordGlobalOption(this.#root, name), {
+            declared: this.#declared,
+            globals: declareGlobalOption(this.#globals, input),
+            options: this.#options,
+            plugins: this.#plugins,
+            views: this.#views,
+        });
+    }
+    /** Registering the action closes input authoring; extension configuration remains available. */
     action(handler) {
         return this.derive(declareAction(this.#root, handler));
     }
@@ -82,37 +125,60 @@ class ApplicationBuilder {
         return this.derive(attachChild(this.#root, child));
     }
     /**
-     * One wrapper for every declaration call, so the Application keeps its name. The next state
+     * The value the root action produces for its consumer. The type argument is stated by the
+     * author, as it is on a Command.
+     */
+    result(declaration) {
+        return this.derive(declareResult(this.#root, 'value', declaration));
+    }
+    /** The same declaration over a sequence, whose type argument is one row. */
+    rows(declaration) {
+        return this.derive(declareResult(this.#root, 'rows', declaration));
+    }
+    /** Views after the fact, merged by key, as it is on a Command. */
+    views(replacements, options) {
+        return this.derive(declareResultViews(this.#root, replacements, options));
+    }
+    extend(...values) {
+        return this.derive(declareExtensions(this.#root, values));
+    }
+    /**
+     * Root declaration calls preserve the Application configuration. The next state
      * travels through this call: each method names its transition in its return type, and the
      * wrapper publishes the same runtime value in exactly that state.
      */
     derive(root) {
         return new ApplicationBuilder(this.#name, root, {
             declared: this.#declared,
-            failures: this.#failures,
+            globals: this.#globals,
             options: this.#options,
             plugins: this.#plugins,
+            views: this.#views,
         });
     }
     /**
-     * Every rule that reads the declarations alone, in the order `run()` reads them: the options
-     * slot, the installed list, the application's failure registrations, each plugin's declarations,
-     * then the whole Command graph. The registry is published as soon as it is known, so a later
-     * declaration error still reaches the renderers the application registered for it.
+     * Every rule that reads the declarations alone, in the order `run()` reads them: the
+     * application's own view overrides, the options slot, the installed list, each plugin's
+     * declarations, then the whole Command graph. The application's overrides are read and published
+     * first, because they need core's identities and nothing else, so every later declaration error
+     * reaches them, while a fault in that list itself reports through core's own text. The merged
+     * registry is published once the whole build has succeeded, so a build-time fault never resolves
+     * through a plugin's overrides, which build has not yet validated.
      */
-    prepare(register) {
+    prepare(stage) {
+        const identities = viewIdentities(coreViews);
+        const application = buildViews({ declares: false, sentence: 'The Application' }, this.#views, identities);
+        stage.views([application]);
+        stage.rendering(renderingPolicy(this.#declared.rendering));
         const facts = checkOptions(this.#options, this.#declared);
-        const installed = installPlugins(this.#plugins);
-        const application = buildFailures(this.#failures);
-        register(application);
+        const installed = installPlugins(this.#plugins ?? []);
         const install = { descriptors: new Map(), extensions: new Map() };
         const plugins = buildPlugins(installed, install);
-        register(mergeFailures([
-            application,
-            ...plugins.map((entry) => buildFailures(entry.failures, pluginSentence(entry.identity))),
-        ]));
-        const graph = buildGraph(this.#root, { ...install, plugins });
+        stage.plugins(plugins);
+        const contributors = plugins.map((entry) => buildViews({ declares: true, sentence: pluginSentence(entry.identity) }, entry.views, identities));
+        const graph = buildGraph(this.#root, this.#globals, { ...install, plugins });
         checkDeclarations([...graph.globals.inputs, ...collectInputs(graph.root)]);
+        stage.views([application, ...contributors]);
         return { facts, graph, plugins };
     }
     /**
@@ -122,7 +188,11 @@ class ApplicationBuilder {
      * Nothing is cached: each call builds the graph anew.
      */
     inspect() {
-        const built = this.prepare(() => undefined);
+        const built = this.prepare({
+            plugins: () => undefined,
+            rendering: () => undefined,
+            views: () => undefined,
+        });
         return inspectGraph(this.#name, built.graph, built.facts);
     }
     async run(options) {
@@ -134,6 +204,8 @@ class ApplicationBuilder {
         let registry = undefined;
         // Faults a plugin raised beside the primary outcome, reported after it and never before it.
         const faults = [];
+        // The failure this run reports as its primary outcome, so nothing reports it a second time.
+        let primary = noPrimary;
         // One private controller per run, subscribed to the caller's signal at run entry.
         const controller = new AbortController();
         /**
@@ -157,10 +229,24 @@ class ApplicationBuilder {
                 const overrides = options?.host;
                 stderr = overrides?.stderr ?? stderr;
                 const host = captureHost(overrides, stderr);
-                output = new Output(host);
+                const invocationOutput = new Output(host, controller.signal);
+                output = invocationOutput;
+                // The policy is read inside the build, after the application's own overrides are published.
+                // A faulty rendering declaration then reports through the view the application listed.
+                let policy = {};
                 signals = bracketRun(controller, checkSignal(options?.signal));
-                const built = this.prepare((value) => {
-                    registry = value;
+                const built = this.prepare({
+                    plugins: (plugins) => {
+                        invocationOutput.configure(policy, plugins.find((entry) => entry.theme !== undefined)?.theme ?? new Map());
+                    },
+                    rendering: (declared) => {
+                        policy = { ...declared, ...renderingPolicy(options?.rendering) };
+                        invocationOutput.configure(policy, new Map());
+                    },
+                    views: (value) => {
+                        registry = value;
+                        invocationOutput.useViews(value);
+                    },
                 });
                 const { graph } = built;
                 const inputs = { globals: graph.globals.inputs, locals: collectInputs(graph.root) };
@@ -173,6 +259,7 @@ class ApplicationBuilder {
                      */
                     signals.install(ownedSignals(built.plugins));
                     await runInvocation({
+                        channel: (binding) => invocationOutput.channel(binding),
                         defaults,
                         facts: built.facts,
                         graph,
@@ -181,7 +268,11 @@ class ApplicationBuilder {
                         out: output.out,
                         plugins: built.plugins,
                         report: (fault) => faults.push(fault),
+                        route: (path) => {
+                            invocationOutput.useRoute(path);
+                        },
                         signal: controller.signal,
+                        style: output.style,
                     });
                 }
                 // The fault check covers the same window the write accounting covers.
@@ -189,20 +280,21 @@ class ApplicationBuilder {
                 await output.settle();
                 const fault = output.fault;
                 if (fault) {
-                    // The action returned, so the renderer failure is this invocation's own failure.
+                    // The action returned, so the view failure is this invocation's own failure.
                     throw new InternalError(`Rendering output failed: ${reasonOf(fault.cause)}`, fault.cause);
                 }
             }
             catch (error) {
+                primary = error;
                 try {
                     const failure = toFailure(error);
                     code = failure.exitCode;
-                    output ??= new Output({ stderr, stdout: process.stdout });
+                    output ??= new Output(captureHost(undefined, stderr), controller.signal);
                     const writes = await output.settle();
                     if (writes.kind === 'ok' && !silenced(error, controller.signal, cancellation())) {
-                        const report = describeFailure(registry ?? noRegistrations, failure);
+                        const report = describeFailure(registry ?? noViews, failure, output.context('stderr'));
                         if (report.kind === 'rendered') {
-                            // The renderer already owns every byte, trailing newline included: pass it through.
+                            // The view owns the trailing newline; output resolves its marked text.
                             await output.report(report.text);
                         }
                         else {
@@ -217,14 +309,24 @@ class ApplicationBuilder {
                     reportingFailed = true;
                 }
             }
+            /**
+             * A sequence that stopped on its own source reports the same way: the call the action never
+             * awaited observed nothing, and a failure the action let propagate is the primary outcome
+             * already, so the one it raised is not reported twice.
+             */
+            for (const cause of output?.stopped ?? []) {
+                if (!carried(primary, cause)) {
+                    faults.push(toFailure(cause));
+                }
+            }
             // A plugin's own fault is reported after the primary outcome and turns a would-be 0 into 1.
-            // The primary outcome keeps its code, the way a renderer failure leaves it alone.
-            // It is reported the way the primary failure is, so a registered renderer answers its class.
+            // The primary outcome keeps its code, the way a view failure leaves it alone.
+            // It is reported the way the primary failure is, so an override answers its class.
             for (const fault of faults) {
                 if (!silenced(fault, controller.signal, cancellation())) {
                     code = code === 0 ? 1 : code;
                     try {
-                        const report = describeFailure(registry ?? noRegistrations, fault);
+                        const report = describeFailure(registry ?? noViews, fault, output?.context('stderr'));
                         if (report.kind === 'rendered') {
                             await output?.report(report.text);
                         }
@@ -251,7 +353,7 @@ class ApplicationBuilder {
             }
             /**
              * One rule orders every code: a cancelled run resolves its signal's code, and a broken
-             * failure renderer or destination in that run is reported as text without changing it. The
+             * failure view or destination in that run is reported as text without changing it. The
              * signal decides the code whatever the action did afterward, so this reading comes last.
              */
             code = cancellation() ?? code;
@@ -263,19 +365,17 @@ class ApplicationBuilder {
         }
     }
 }
-/**
- * The second argument, read where it is supplied. The retired positional form declares its globals
- * on a value that holds no `globals` key, so without this rule the globals vanish silently and the
- * operator, not the author, meets the consequence as an unknown-option error. The slot's own shape
- * settles first, because a slot that is not an options object carries no facts to report.
- */
+/** Reject obsolete wiring before silently losing options that invocations depend on. */
 function checkOptions(options, declared) {
-    if (isGlobalOptions(options)) {
-        throw new DeclarationError('The Application takes an options object. Supply { globals } instead of a positional GlobalOptions value.');
-    }
     if (options !== undefined) {
         if (!isPlainObject(options)) {
-            throw new DeclarationError('The Application options must be an object. Supply { globals, failures }.');
+            throw new DeclarationError('The Application options must be an object. Supply an Application options object.');
+        }
+        if ('globals' in options) {
+            throw new DeclarationError('The Application options contain globals. Declare them with globalOption(name, config).');
+        }
+        if ('failures' in options) {
+            throw new DeclarationError('The Application options contain failures. Declare view overrides under views with override(key, view).');
         }
         // The root is every page's entry point, so it carries neither listing fact.
         // A key that may not be there is a fault of the slot, so it answers with the slot's shape.
@@ -286,35 +386,38 @@ function checkOptions(options, declared) {
         version: checkVersion(declared.version),
     };
 }
-/**
- * The runtime class behind the public constructor. It is generic so that an instance's `Globals`
- * is the type of the value it holds, with `{}` standing in when there is none, which is what each
- * signature of the constructor interface publishes.
- */
+/** Constructor inference preserves the installed plugin tuple; globals start empty. */
 class ApplicationDeclaration extends ApplicationBuilder {
     constructor(name, options) {
-        // The options slot is read defensively, never inspected: an invalid value still yields
-        // `globals`, `failures`, and the facts of some kind, and `checkOptions` reports it at build.
+        // The options slot is read defensively, never inspected.
+        // An invalid value still yields `views` and the facts of some kind.
+        // `checkOptions` reports such a value at build.
         // The root's own slot and core facts stay empty, because the Application checks its own slot.
         // Its diagnostics name the Application rather than the root Command.
         super(name, freshState({
             deprecated: undefined,
             description: undefined,
             extensions: options?.extensions,
-            globals: options?.globals,
             hidden: undefined,
             name: null,
             options: undefined,
         }), {
-            declared: { description: options?.description, version: options?.version },
-            failures: options?.failures ?? [],
+            declared: {
+                description: options?.description,
+                rendering: isPlainObject(options?.rendering)
+                    ? { ...options.rendering }
+                    : options?.rendering,
+                version: options?.version,
+            },
+            globals: emptyGlobals(),
             options,
-            plugins: options?.plugins ?? [],
+            plugins: options?.plugins,
+            // The read is loose because the slot is reachable from JavaScript with any value at all.
+            // An Application value passed here answers `views` with its own authoring method.
+            // The public `ApplicationOptions.views` stays exactly `readonly ViewOverride[]`.
+            // An options slot that is no plain object carries no override list, and its own rule reports it.
+            views: isPlainObject(options) ? options.views : undefined,
         });
     }
 }
-/**
- * The public constructor takes a name and one options object. The globals type narrows to the
- * supplied value, and the failure renderers configure the application the way its commands do.
- */
 export const Application = ApplicationDeclaration;

package/dist/chain.d.ts

@@ -2,7 +2,8 @@ import type { BuiltGraph } from './command.js';
 import type { LoomError } from './errors.js';
 import type { CommandGraph, CommandNode } from './inspect.js';
 import type { BuiltPlugin, PluginOptions, PluginOptionValues } from './plugin.js';
-import type { Host, Out } from './types.js';
+import type { ContextualStyle } from './style.js';
+import type { ActionChannel, Host, OpenResult, Out, Request, ResultBinding } from './types.js';
 import type { DefaultValues } from './validation.js';
 /**
  * What the rest of one chain did: the action ran, a later middleware took over by returning without
@@ -12,12 +13,19 @@ type ChainOutcome = 'cancelled' | 'dispatched' | 'taken-over';
 /**
  * What one middleware receives. `graph` is the frozen graph `inspect()` returns, built once for the
  * run, and `command` is the routed node inside it. `options` holds this plugin's own option values
- * and never another plugin's or the application's globals.
+ * and never another plugin's or the application's globals. `request` is the routed Command's
+ * invocation, parsed and validated ahead of the chain, and `null` while core holds a fault and on a
+ * group. `view` names the view the result renders through: it reads as the declaration's default
+ * until a middleware assigns one, and as `null` on a Command that declares none. The last
+ * assignment before the dispatch boundary wins, and one made after it changes nothing.
  */
 interface MiddlewareContext<Options extends PluginOptions = PluginOptions> {
     readonly options: PluginOptionValues<Options>;
     readonly graph: CommandGraph;
     readonly command: CommandNode;
+    readonly request: Request | null;
+    get view(): string | null;
+    set view(name: string);
     readonly host: Host;
     readonly out: Out;
     readonly signal: AbortSignal;
@@ -25,6 +33,9 @@ interface MiddlewareContext<Options extends PluginOptions = PluginOptions> {
 }
 /** Everything one invocation needs after its graph is built and its defaults are validated. */
 interface Invocation {
+    style: ContextualStyle;
+    /** The action's own channel, built from the routed Command's declaration when it dispatches. */
+    channel: (binding: ResultBinding) => ActionChannel;
     defaults: DefaultValues;
     facts: {
         description: string | undefined;
@@ -33,16 +44,24 @@ interface Invocation {
     graph: BuiltGraph;
     host: Host;
     name: string;
-    out: Out;
+    /**
+     * The invocation's own channel. A middleware reads it as the neutral `Out`, and the action
+     * receives the channel the results lane builds for the Command that was routed.
+     */
+    out: Out<OpenResult>;
     plugins: readonly BuiltPlugin[];
     /** A fault reported after the primary outcome, which turns a would-be 0 into 1. */
     report: (fault: LoomError) => void;
+    /** The routed path, published where routing resolved it, which output names in its own line. */
+    route: (path: readonly string[]) => void;
     signal: AbortSignal;
 }
 /**
- * Runs one invocation: the global pre-scan, routing, the middleware chain, and the phases the chain
- * terminates in. A middleware that returns without calling `next()` has taken over, so the
- * remaining tokens are never parsed and nothing later in the chain runs.
+ * Runs one invocation: the global pre-scan, routing, the dispatch this invocation prepares, and the
+ * middleware chain it then runs. Local parsing and validation run ahead of the chain so that a
+ * middleware reads the request, and the fault they find is held until the dispatch boundary. A
+ * middleware that returns without calling `next()` has taken over, so the held fault is never
+ * raised and nothing later in the chain runs.
  */
 declare function runInvocation(invocation: Invocation): Promise<void>;
 export type { ChainOutcome, Invocation, MiddlewareContext };