@loomcli/core 0.5.0 → 0.7.0

package/dist/prototypes.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Every prototype in one value's chain, most derived first, or `undefined` when the chain cannot
+ * be read: a proxy trap throws, a link repeats, or the chain runs past `maxChainLinks` links. A
+ * value with a `null` prototype has an empty chain. Override resolution and translator resolution
+ * both walk the chain this returns.
+ */
+export declare function prototypeChain(value: object): object[] | undefined;

package/dist/prototypes.js

@@ -0,0 +1,29 @@
+/** The most links a prototype chain holds before core reads it as a chain that never ends. */
+const maxChainLinks = 1024;
+/** The walk behind `prototypeChain`, which throws where a proxy trap throws. */
+function walkChain(value) {
+    const chain = [];
+    const seen = new Set([value]);
+    for (let link = Reflect.getPrototypeOf(value); link !== null; link = Reflect.getPrototypeOf(link)) {
+        if (seen.has(link) || chain.length >= maxChainLinks) {
+            return undefined;
+        }
+        seen.add(link);
+        chain.push(link);
+    }
+    return chain;
+}
+/**
+ * Every prototype in one value's chain, most derived first, or `undefined` when the chain cannot
+ * be read: a proxy trap throws, a link repeats, or the chain runs past `maxChainLinks` links. A
+ * value with a `null` prototype has an empty chain. Override resolution and translator resolution
+ * both walk the chain this returns.
+ */
+export function prototypeChain(value) {
+    try {
+        return walkChain(value);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/rendering.d.ts

@@ -1,3 +1,4 @@
+import type { FactSite } from './facts.js';
 import type { Host } from './types.js';
 type SwitchPolicy = 'auto' | 'always' | 'never';
 interface RenderingPolicy {
@@ -14,7 +15,11 @@ interface Capabilities {
     depth: 16 | 256 | 'truecolor';
     mainGlyphs: boolean;
 }
-declare function renderingPolicy(value: unknown): RenderingPolicy;
+/**
+ * One declared rendering policy, checked against its closed sets. `site` is where it was declared,
+ * the Application's `rendering` option or `run()`'s, which a fault marks.
+ */
+declare function renderingPolicy(value: unknown, site: FactSite): RenderingPolicy;
 /** A run owns captured facts; stdout and stderr each resolve this one policy independently. */
 declare function capabilities(host: Host, destination: 'stdout' | 'stderr', policy: RenderingPolicy): Capabilities;
 export type { Capabilities, RenderingPolicy };

package/dist/rendering.js

@@ -1,17 +1,31 @@
 import { DeclarationError } from './errors.js';
-import { isPlainObject } from './facts.js';
-function renderingPolicy(value) {
+import { partFinding } from './facts.js';
+import { isPlainObject } from './plain.js';
+import { renderingPolicyRule } from './plugin-rules.js';
+/**
+ * One declared rendering policy, checked against its closed sets. `site` is where it was declared,
+ * the Application's `rendering` option or `run()`'s, which a fault marks.
+ */
+function renderingPolicy(value, site) {
     if (value === undefined) {
         return {};
     }
     if (!isPlainObject(value)) {
-        throw new DeclarationError('The rendering policy must be an object.');
+        throw new DeclarationError(renderingPolicyRule, {
+            correction: 'Supply an object, or omit rendering.',
+            findings: [partFinding(site, [])],
+            sentence: 'The rendering policy is not an object.',
+        });
     }
     const result = {};
     for (const field of ['color', 'modifiers', 'hyperlinks']) {
         const policy = value[field];
         if (policy !== undefined && policy !== 'auto' && policy !== 'always' && policy !== 'never') {
-            throw new DeclarationError(`Rendering ${field} must be auto, always, or never.`);
+            throw new DeclarationError(renderingPolicyRule, {
+                correction: `Supply one of the three, or omit ${field}.`,
+                findings: [partFinding(site, [field])],
+                sentence: `Rendering ${field} is not auto, always, or never.`,
+            });
         }
         if (policy !== undefined) {
             result[field] = policy;
@@ -19,7 +33,11 @@ function renderingPolicy(value) {
     }
     const controls = value.terminalControls;
     if (controls !== undefined && controls !== 'strip' && controls !== 'preserve') {
-        throw new DeclarationError('Rendering terminalControls must be strip or preserve.');
+        throw new DeclarationError(renderingPolicyRule, {
+            correction: 'Supply strip or preserve, or omit terminalControls.',
+            findings: [partFinding(site, ['terminalControls'])],
+            sentence: 'Rendering terminalControls is not strip or preserve.',
+        });
     }
     if (controls !== undefined) {
         result.terminalControls = controls;

package/dist/rules.d.ts

@@ -0,0 +1,51 @@
+/** A value thrown from an action, a middleware, or a source that no translator answered. */
+declare const foreignThrow: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every foreign throw shares. */
+declare const foreignThrowCorrection = "Catch the error where it is thrown and throw a failure class, such as FatalError, with a sentence the operator can act on.";
+/** A thrown value that inherits from a failure class without having been constructed by one. */
+declare const unconstructedFailure: import("./diagnostic-text.js").DiagnosticRule;
+/** A translator that threw or answered with something other than a failure. */
+declare const brokenTranslator: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every broken translator shares. */
+declare const brokenTranslatorCorrection = "Return a failure, or undefined to pass, and throw nothing from the translator.";
+/** A failure view that threw or returned a value that is not a string. */
+declare const brokenFailureView: import("./diagnostic-text.js").DiagnosticRule;
+/** An output or lane view that threw or returned a value that is not a string. */
+declare const brokenOutputView: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix a broken failure view and a broken output view share. */
+declare const viewCorrection = "Return a string from the view's render function, and throw nothing from it.";
+/** An `onFailure` hook that threw or returned a value that is not hints. */
+declare const brokenFailureHook: import("./diagnostic-text.js").DiagnosticRule;
+/** A plugin's middleware or source loader that rejected or exported no default function. */
+declare const pluginLoaderFailed: import("./diagnostic-text.js").DiagnosticRule;
+/** A middleware that called `next()` twice, or after it returned. */
+declare const nextMisuse: import("./diagnostic-text.js").DiagnosticRule;
+/** An action or a plugin that broke the promise a declared result makes. */
+declare const resultContract: import("./diagnostic-text.js").DiagnosticRule;
+/** A validator that threw, rejected, or returned a malformed result. */
+declare const validatorFailed: import("./diagnostic-text.js").DiagnosticRule;
+/** A middleware that assigned `view` a name the routed Command's result cannot render. */
+declare const viewSelection: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every invalid view selection shares. */
+declare const viewSelectionCorrection = "Assign view one of the view names the routed Command's result declares, and only on a Command that declares a result.";
+/** A `run()` option that holds a value of the wrong kind. */
+declare const runOptions: import("./diagnostic-text.js").DiagnosticRule;
+/** A configuration source whose answers break the answers rule. */
+declare const sourceAnswers: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every source answers fault shares. */
+declare const sourceAnswersCorrection = "Return a record that maps each requested option's name to { value, label }, with a value of the option's raw type.";
+/** A graph that `inspect()` did not return, or whose nodes disagree with the build it came from. */
+declare const foreignGraph: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every foreign graph shares. */
+declare const foreignGraphCorrection = "Pass the graph inspect() returned, unchanged.";
+/** A host stream that failed a write the run owed it. */
+declare const brokenDestination: import("./diagnostic-text.js").DiagnosticRule;
+/** A failure class whose exit code is outside 1 through 125. */
+declare const failureExitCode: import("./diagnostic-text.js").DiagnosticRule;
+/** A diagnostic rule identity outside the `<package>[/<subpath>...]/<kebab-case-rule>` grammar. */
+declare const ruleIdentity: import("./diagnostic-text.js").DiagnosticRule;
+/** A diagnostic rule whose headline or explanation holds no prose. */
+declare const ruleProse: import("./diagnostic-text.js").DiagnosticRule;
+/** A diagnostic rule whose docs value is not a web address. */
+declare const ruleDocs: import("./diagnostic-text.js").DiagnosticRule;
+export { brokenDestination, brokenFailureHook, brokenFailureView, brokenOutputView, brokenTranslator, brokenTranslatorCorrection, failureExitCode, foreignGraph, foreignGraphCorrection, foreignThrow, foreignThrowCorrection, nextMisuse, pluginLoaderFailed, resultContract, ruleDocs, ruleIdentity, ruleProse, runOptions, sourceAnswers, sourceAnswersCorrection, unconstructedFailure, validatorFailed, viewCorrection, viewSelection, viewSelectionCorrection, };

package/dist/rules.js

@@ -0,0 +1,115 @@
+import { registerRule } from './diagnostic-text.js';
+/*
+ * Core's own rules for the defects it raises, the run-time declaration faults it finds, and the
+ * faults of the two things an author declares to describe a failure: a failure class's exit code
+ * and a diagnostic rule. Each is declared once here and shared by every site that raises it, as a
+ * plugin's rules are.
+ */
+/** A value thrown from an action, a middleware, or a source that no translator answered. */
+const foreignThrow = registerRule('@loomcli/core/foreign-throw', {
+    explanation: 'Core reports a value that an action, a middleware, or a configuration source threw, and that no translator answered, as a defect, because only the author knows what it means. A distributed build shows the operator one generic message in its place.',
+    headline: 'Unhandled exception',
+});
+/** The fix every foreign throw shares. */
+const foreignThrowCorrection = 'Catch the error where it is thrown and throw a failure class, such as FatalError, with a sentence the operator can act on.';
+/** A thrown value that inherits from a failure class without having been constructed by one. */
+const unconstructedFailure = registerRule('@loomcli/core/unconstructed-failure', {
+    explanation: 'A failure class records its exit code when a failure is constructed, so a value that only inherits from one, such as one made with Object.create(), carries no code core can trust.',
+    headline: 'Failure never constructed',
+});
+/** A translator that threw or answered with something other than a failure. */
+const brokenTranslator = registerRule('@loomcli/core/broken-translator', {
+    explanation: 'A translator turns a foreign throw into a failure synchronously. A throw, or any answer other than a failure or undefined, leaves core no failure to report, so it consults no later translator.',
+    headline: 'Broken translator',
+});
+/** The fix every broken translator shares. */
+const brokenTranslatorCorrection = 'Return a failure, or undefined to pass, and throw nothing from the translator.';
+/** A failure view that threw or returned a value that is not a string. */
+const brokenFailureView = registerRule('@loomcli/core/broken-failure-view', {
+    explanation: "A failure view turns a failure into the text the operator reads, synchronously and without throwing. Core wrote its own text for the failure in the view's place.",
+    headline: 'Broken failure view',
+});
+/** An output or lane view that threw or returned a value that is not a string. */
+const brokenOutputView = registerRule('@loomcli/core/broken-output-view', {
+    explanation: 'A view turns a value into text synchronously and without throwing. Core wrote nothing for the call whose view broke, and a run whose output is incomplete cannot succeed.',
+    headline: 'Broken output view',
+});
+/** The fix a broken failure view and a broken output view share. */
+const viewCorrection = "Return a string from the view's render function, and throw nothing from it.";
+/** An `onFailure` hook that threw or returned a value that is not hints. */
+const brokenFailureHook = registerRule('@loomcli/core/broken-failure-hook', {
+    explanation: "An onFailure hook adds hint lines under a failure, synchronously and without throwing. Core dropped this hook's hints and rendered the failure with every other plugin's.",
+    headline: 'Broken failure hook',
+});
+/** A plugin's middleware or source loader that rejected or exported no default function. */
+const pluginLoaderFailed = registerRule('@loomcli/core/plugin-loader-failed', {
+    explanation: "Core loads a plugin's middleware or source module the first time a run reaches it, and the module owes its function as its default export.",
+    headline: 'Plugin loader failed',
+});
+/** A middleware that called `next()` twice, or after it returned. */
+const nextMisuse = registerRule('@loomcli/core/next-misuse', {
+    explanation: 'next() continues the middleware chain once, while the middleware that received it runs. A second call, or a call after the middleware returned, has no chain left to continue.',
+    headline: 'next() misused',
+});
+/** An action or a plugin that broke the promise a declared result makes. */
+const resultContract = registerRule('@loomcli/core/result-contract', {
+    explanation: 'A Command that declares a result promises its consumer one value, or one sequence of rows, that its action emits once through out.results().',
+    headline: 'Result contract broken',
+});
+/** A validator that threw, rejected, or returned a malformed result. */
+const validatorFailed = registerRule('@loomcli/core/validator-failed', {
+    explanation: 'Only an issue a validator returns states a validation verdict. A validator that throws, rejects, or returns anything but a Standard Schema result leaves core no verdict to report, so validation stops and the action does not run.',
+    headline: 'Validator failed',
+});
+/** A middleware that assigned `view` a name the routed Command's result cannot render. */
+const viewSelection = registerRule('@loomcli/core/view-selection', {
+    explanation: "A middleware selects one of the views the routed Command's result declares, by name, before the action runs. A Command that declares no result has no view to select, and a name its result does not declare has no view to render.",
+    headline: 'Invalid view selection',
+});
+/** The fix every invalid view selection shares. */
+const viewSelectionCorrection = "Assign view one of the view names the routed Command's result declares, and only on a Command that declares a result.";
+/** A `run()` option that holds a value of the wrong kind. */
+const runOptions = registerRule('@loomcli/core/run-options', {
+    explanation: 'run() reads its options before it builds the graph. A caller that embeds the application, such as a test, passes them, and a value of the wrong kind leaves the run nothing to act on.',
+    headline: 'Invalid run options',
+});
+/** A configuration source whose answers break the answers rule. */
+const sourceAnswers = registerRule('@loomcli/core/source-answers', {
+    explanation: 'A configuration source answers with a record that maps each option core requested to { value, label }, where the value has the raw type the option takes and the label is one line of prose. Core fills no option from any other answer.',
+    headline: 'Invalid source answers',
+});
+/** The fix every source answers fault shares. */
+const sourceAnswersCorrection = "Return a record that maps each requested option's name to { value, label }, with a value of the option's raw type.";
+/** A graph that `inspect()` did not return, or whose nodes disagree with the build it came from. */
+const foreignGraph = registerRule('@loomcli/core/foreign-graph', {
+    explanation: 'Core reads a Command graph through the build inspect() rendered it from. A graph inspect() did not return, or one whose nodes do not match that build, leaves core no build to read, so the run stops rather than hand a plugin the wrong Command.',
+    headline: 'Graph not from inspect()',
+});
+/** The fix every foreign graph shares. */
+const foreignGraphCorrection = 'Pass the graph inspect() returned, unchanged.';
+/** A host stream that failed a write the run owed it. */
+const brokenDestination = registerRule('@loomcli/core/broken-destination', {
+    explanation: "Core writes the run's output and its failure reports to the host streams run() captured. A stream that fails a write loses whatever followed it, so the run cannot succeed.",
+    headline: 'Broken destination',
+});
+/** A failure class whose exit code is outside 1 through 125. */
+const failureExitCode = registerRule('@loomcli/core/failure-exit-code', {
+    explanation: "A failure's exit code tells the shell how the run ended: 0 means success, and 126 and above belong to the shell and to signals, so a failure exits with a code from 1 through 125. Core never clamps or replaces the code a failure class declares, so a code no failure may exit with is rejected where the class is first constructed.",
+    headline: 'Undeclarable exit code',
+});
+/** A diagnostic rule identity outside the `<package>[/<subpath>...]/<kebab-case-rule>` grammar. */
+const ruleIdentity = registerRule('@loomcli/core/rule-identity', {
+    explanation: "A rule's identity names the package that declares it and the rule inside it, so tooling keys on it and two packages never share one. It is an identity, a package name and any kebab-case subpath segments that name the part of the package that owns the rule, then a kebab-case rule name, joined by /.",
+    headline: 'Invalid rule identity',
+});
+/** A diagnostic rule whose headline or explanation holds no prose. */
+const ruleProse = registerRule('@loomcli/core/rule-prose', {
+    explanation: "A rule's banner prints its headline, and its explanation teaches why the rule exists, so each holds prose.",
+    headline: 'Empty rule text',
+});
+/** A diagnostic rule whose docs value is not a web address. */
+const ruleDocs = registerRule('@loomcli/core/rule-docs', {
+    explanation: "A diagnostic prints a rule's docs as a link the author follows, so it is an absolute http or https URL.",
+    headline: 'Invalid rule docs',
+});
+export { brokenDestination, brokenFailureHook, brokenFailureView, brokenOutputView, brokenTranslator, brokenTranslatorCorrection, failureExitCode, foreignGraph, foreignGraphCorrection, foreignThrow, foreignThrowCorrection, nextMisuse, pluginLoaderFailed, resultContract, ruleDocs, ruleIdentity, ruleProse, runOptions, sourceAnswers, sourceAnswersCorrection, unconstructedFailure, validatorFailed, viewCorrection, viewSelection, viewSelectionCorrection, };

package/dist/sequence.js

@@ -1,4 +1,5 @@
 import { InternalError, routedSubject } from './errors.js';
+import { resultContract } from './rules.js';
 /**
  * A failure the source raised, so the writer tells it apart from the view and write faults its own
  * pieces raise, which the output path has accounted for already.
@@ -44,7 +45,11 @@ function stepsOf(writer) {
         throw new SourceFault(error);
     }
     if (!steps) {
-        throw new SourceFault(new InternalError(`The result of ${routedSubject(writer.path)} is not iterable.`, undefined));
+        throw new SourceFault(new InternalError(resultContract, {
+            cause: undefined,
+            correction: 'Pass out.results() an iterable or an async iterable of rows.',
+            sentence: `The result of ${routedSubject(writer.path)} is not iterable.`,
+        }));
     }
     return steps;
 }

package/dist/sources.d.ts

@@ -1,4 +1,4 @@
-import { InputError, InternalError } from './errors.js';
+import { LoomError } from './errors.js';
 import type { ExtensionRecords } from './extension.js';
 import type { CommandGraph, OptionNode } from './inspect.js';
 import type { OptionValues } from './options.js';
@@ -25,6 +25,8 @@ interface SourceStage {
     inspected: () => CommandGraph;
     /** The routed Command's own options, or `undefined` while local parsing holds a fault. */
     locals: StageScope | undefined;
+    /** Offers the resolver's foreign throw to the translators, ahead of the plugin-fault wrap. */
+    offer: (thrown: unknown) => LoomError | undefined;
     /** The channel a source writes through, whose results call names the source. */
     out: Out;
     plugins: readonly BuiltPlugin[];
@@ -38,11 +40,11 @@ interface SourceStage {
  * What the stage found beside the values it filled. `labels` names where each filled option's value
  * came from, by option name, and `rejected` names the variable of each Boolean option whose value
  * is outside the grammar. Both are internal to core's failure messages. `fault` is a configuration
- * source's own fault, or the `InputError` its resolver threw, which stops the stage and takes the
- * place of every validation problem.
+ * source's own fault, or the failure its resolver threw, which stops the stage and takes the place
+ * of every validation problem.
  */
 interface SourceOutcome {
-    fault: InternalError | InputError | undefined;
+    fault: LoomError | undefined;
     labels: ReadonlyMap<string, string>;
     rejected: ReadonlyMap<string, string>;
 }

package/dist/sources.js

@@ -1,7 +1,9 @@
-import { asSentence, InputError, InternalError, reasonOf, ResultError } from './errors.js';
-import { isPlainObject, isProseLine } from './facts.js';
+import { asSentence, foreignFailure, InternalError, LoomError, quoted, reasonOf, } from './errors.js';
+import { isProseLine } from './facts.js';
 import { isSupplied } from './options.js';
+import { isPlainObject } from './plain.js';
 import { loadDefault, pluginSentence, pluginValues } from './plugin.js';
+import { foreignThrow, foreignThrowCorrection, sourceAnswers, sourceAnswersCorrection, } from './rules.js';
 /** The Boolean grammar a bound variable is read through: the whole value, case-insensitive. */
 const truths = new Map([
     ['0', false],
@@ -85,7 +87,11 @@ function rawValue(kind, value) {
 const ruleFaults = new WeakSet();
 /** A fault the answers rule names, recorded so that reading the answers rethrows it unframed. */
 function ruleFault(message) {
-    const fault = new InternalError(message, undefined);
+    const fault = new InternalError(sourceAnswers, {
+        cause: undefined,
+        correction: sourceAnswersCorrection,
+        sentence: message,
+    });
     ruleFaults.add(fault);
     return fault;
 }
@@ -94,12 +100,12 @@ function readAnswer(sentence, input, answer) {
     const shape = isPlainObject(answer) ? answer : undefined;
     const label = shape?.label;
     if (!shape || !isProseLine(label)) {
-        throw ruleFault(`${sentence} answered option "${input.name}" with an answer that is not { value, label }.`);
+        throw ruleFault(`${sentence} answered option ${quoted(input.name)} with an answer that is not { value, label }.`);
     }
     const kind = rawKind(input);
     const value = rawValue(kind, shape.value);
     if (value === undefined) {
-        throw ruleFault(`${sentence} answered option "${input.name}" with a value that is not ${owed[kind]}.`);
+        throw ruleFault(`${sentence} answered option ${quoted(input.name)} with a value that is not ${owed[kind]}.`);
     }
     return { label, value };
 }
@@ -115,7 +121,7 @@ function readAnswers(sentence, answers, requested) {
     return Object.entries(answers).map(([name, answer]) => {
         const target = byName.get(name);
         if (!target) {
-            throw ruleFault(`${sentence} answered option "${name}", which core did not request.`);
+            throw ruleFault(`${sentence} answered option ${quoted(name)}, which core did not request.`);
         }
         const { label, value } = readAnswer(sentence, target.input, answer);
         return { label, target, value };
@@ -130,7 +136,11 @@ function isResolverExport(value) {
 }
 /** The fault of a source that threw, while it ran or while core read what it returned. */
 function sourceFailure(sentence, error) {
-    return new InternalError(`${sentence} failed in its configuration source: ${asSentence(reasonOf(error))}`, error);
+    return new InternalError(foreignThrow, {
+        cause: error,
+        correction: foreignThrowCorrection,
+        sentence: `${sentence} failed in its configuration source: ${asSentence(reasonOf(error))}`,
+    });
 }
 /**
  * Asks the one configuration source about every requested option, and answers with what it said.
@@ -162,13 +172,14 @@ async function askSource(stage, call) {
         answers = await resolver(context);
     }
     catch (error) {
-        // The resolver's own InputError is a usage failure.
-        // Its out.results() call is the results fault that names it.
-        // Every other throw is the plugin's fault.
-        if (error instanceof InputError || (error instanceof ResultError && error.kind === 'source')) {
+        // The resolver's own failure reports with its class's code, as an action's does.
+        // That covers an InputError, the FatalError out.fatal() throws, and its out.results() fault.
+        // A foreign throw is offered to the translators.
+        // One that no translator answers is the plugin's fault.
+        if (error instanceof LoomError) {
             throw error;
         }
-        throw sourceFailure(sentence, error);
+        throw stage.offer(error) ?? sourceFailure(sentence, error);
     }
     try {
         return readAnswers(sentence, answers, requested);
@@ -238,11 +249,9 @@ async function fillInputs(stage) {
         return { fault: undefined, labels, rejected };
     }
     catch (error) {
-        // The resolver's InputError reports as a usage failure.
+        // The resolver's own failure keeps its class, and so its code.
         // Every other fault above is raised as an internal error, and anything else is wrapped the same way.
-        const fault = error instanceof InternalError || error instanceof InputError
-            ? error
-            : new InternalError(reasonOf(error), error);
+        const fault = error instanceof LoomError ? error : foreignFailure(error);
         return { fault, labels, rejected };
     }
 }

package/dist/style-layout.js

@@ -1,4 +1,4 @@
-import { graphemeWidths } from '@rockorager/uucode/width';
+import { graphemeWidths } from './style-width.js';
 const offsets = [0, 1, 2, 3, 4, 5, 6, 7];
 const empty = {
     advance: offsets.map(() => 0),
@@ -117,6 +117,7 @@ function padBlock(block, padding, attributes) {
     if (!block.tabs && block.minimum >= padding.width) {
         return block;
     }
+    const space = (count) => leaf({ attributes, kind: 'text', text: ' '.repeat(count) }, count);
     const lines = block.lines.map((line, index) => {
         // A terminal newline has no extra line to align; interior blank lines do.
         if (index > 0 && index === block.lines.length - 1 && !line.content.text) {
@@ -134,7 +135,6 @@ function padBlock(block, padding, attributes) {
         else if (padding.align === 'center') {
             before = Math.floor(missing / 2);
         }
-        const space = (count) => leaf({ attributes, kind: 'text', text: ' '.repeat(count) }, count);
         // Re-segment inserted spaces too: a trailing Unicode Prepend character can absorb one.
         const spaced = join([space(before), content, space(missing - before)]);
         const row = measured([{ content: spaced, ending: [] }]);

package/dist/style-width.d.ts

@@ -0,0 +1,13 @@
+/** One grapheme cluster of a string: where it starts and ends, and the columns it occupies. */
+interface GraphemeWidth {
+    start: number;
+    end: number;
+    width: number;
+}
+/**
+ * Each grapheme cluster of a string with the terminal columns it occupies. Printable ASCII that no
+ * non-ASCII character follows is its own one-column cluster. Any other run of clusters is read by
+ * one cursor, which starts at the run and carries the break state from cluster to cluster.
+ */
+export declare function graphemeWidths(text: string): Generator<GraphemeWidth>;
+export {};

package/dist/style-width.js

@@ -0,0 +1,170 @@
+/*!
+Ported from the grapheme width iterator of @rockorager/uucode 2.2.1, src/width.ts.
+Copyright (c) 2026 Tim Culverhouse. Licensed under the MIT License,
+in licenses/uucode-LICENSE.md of @loomcli/core.
+*/
+import { graphemeTable, widthTable } from './unicode.generated.js';
+/** The break state after a regional indicator, which pairs with the next one into a flag. */
+const regionalIndicatorState = 1;
+/** The break state inside an extended pictographic sequence, which a ZWJ continues. */
+const pictographicState = 2;
+// The table members, read once, so each lookup indexes the arrays directly.
+const { stage1, stage1Shift, stage2, stage2Mask, stage3, widthMask, zeroWidthFlag, emojiVSFlag } = widthTable;
+const { breakTable, graphemeBreakPropertyCount } = graphemeTable;
+/** A code point's packed row: its grapheme break property, width, and emoji flags. */
+function lookup(codePoint) {
+    const offset = stage1[codePoint >> stage1Shift] ?? 0;
+    return stage3[stage2[offset + (codePoint & stage2Mask)] ?? 0] ?? 0;
+}
+/** The row an empty string starts from: the Other break property at width one. */
+const defaultRow = 1 << 5;
+const graphemeBreak = (row) => row & 0x1f;
+const rowWidth = (row) => (row >> 5) & widthMask;
+const zeroInGrapheme = (row) => ((row >> 5) & zeroWidthFlag) !== 0;
+const emojiSelectorBase = (row) => ((row >> 8) & emojiVSFlag) !== 0;
+/** The next break state shifted left once, with whether a cluster boundary falls between. */
+function transition(before, after, state) {
+    const count = graphemeBreakPropertyCount;
+    return breakTable[(state * count + before) * count + after] ?? 0;
+}
+/** A cursor at the start of a run, with the run's first code point read ahead. */
+function cursor(text, start) {
+    const hasNext = start < text.length;
+    const codePoint = hasNext ? (text.codePointAt(start) ?? 0) : 0;
+    return {
+        codePoint: 0,
+        hasNext,
+        index: start,
+        isBreak: false,
+        nextCodePoint: codePoint,
+        nextIndex: hasNext ? start + (codePoint > 0xff_ff ? 2 : 1) : start,
+        nextRow: hasNext ? lookup(codePoint) : defaultRow,
+        row: defaultRow,
+        state: 0,
+        text,
+    };
+}
+/** Moves to the next code point and reads whether a cluster boundary follows it. */
+function advance(at) {
+    if (!at.hasNext) {
+        return false;
+    }
+    at.codePoint = at.nextCodePoint;
+    at.row = at.nextRow;
+    const index = at.nextIndex;
+    at.index = index;
+    if (index >= at.text.length) {
+        at.hasNext = false;
+        at.isBreak = true;
+        return true;
+    }
+    const first = at.text.charCodeAt(index);
+    let codePoint = first;
+    let nextIndex = index + 1;
+    if (first >= 0xd8_00 && first <= 0xdb_ff && nextIndex < at.text.length) {
+        const second = at.text.charCodeAt(nextIndex);
+        if (second >= 0xdc_00 && second <= 0xdf_ff) {
+            codePoint = ((first - 0xd8_00) << 10) + second - 0xdc_00 + 0x1_00_00;
+            nextIndex += 1;
+        }
+    }
+    const row = lookup(codePoint);
+    const packed = transition(graphemeBreak(at.row), graphemeBreak(row), at.state);
+    at.state = packed >> 1;
+    at.nextCodePoint = codePoint;
+    at.nextIndex = nextIndex;
+    at.nextRow = row;
+    at.isBreak = (packed & 1) !== 0;
+    return true;
+}
+/** The width of the next grapheme cluster, leaving the cursor at its end. */
+function clusterWidth(at) {
+    if (!advance(at)) {
+        return 0;
+    }
+    const standalone = rowWidth(at.row);
+    if (at.isBreak) {
+        return standalone;
+    }
+    let width = zeroInGrapheme(at.row) ? 0 : standalone;
+    let previousRow = at.row;
+    let previousState = at.state;
+    for (;;) {
+        if (!advance(at)) {
+            break;
+        }
+        switch (at.codePoint) {
+            case 0xfe_0f: {
+                if (emojiSelectorBase(previousRow)) {
+                    width = 2;
+                }
+                break;
+            }
+            case 0xfe_0e: {
+                if (emojiSelectorBase(previousRow)) {
+                    width = 1;
+                }
+                break;
+            }
+            case 0x20_0d: {
+                if (previousState === pictographicState && !at.isBreak) {
+                    if (!advance(at) || at.isBreak) {
+                        return width;
+                    }
+                    previousRow = at.row;
+                    previousState = at.state;
+                    continue;
+                }
+                break;
+            }
+            case 0x1_f3_fb:
+            case 0x1_f3_fc:
+            case 0x1_f3_fd:
+            case 0x1_f3_fe:
+            case 0x1_f3_ff: {
+                width = 2;
+                break;
+            }
+            default: {
+                if (previousState === regionalIndicatorState) {
+                    width = 2;
+                }
+                else if (!zeroInGrapheme(at.row)) {
+                    width += rowWidth(at.row);
+                }
+            }
+        }
+        if (at.isBreak) {
+            break;
+        }
+        previousRow = at.row;
+        previousState = at.state;
+    }
+    return width;
+}
+/** Whether the character at an index is printable ASCII that no non-ASCII character follows. */
+function asciiAlone(text, index) {
+    const code = text.charCodeAt(index);
+    return (code >= 0x20 && code < 0x7f && (index + 1 >= text.length || text.charCodeAt(index + 1) < 0x80));
+}
+/**
+ * Each grapheme cluster of a string with the terminal columns it occupies. Printable ASCII that no
+ * non-ASCII character follows is its own one-column cluster. Any other run of clusters is read by
+ * one cursor, which starts at the run and carries the break state from cluster to cluster.
+ */
+export function* graphemeWidths(text) {
+    let start = 0;
+    while (start < text.length) {
+        if (asciiAlone(text, start)) {
+            yield { end: start + 1, start, width: 1 };
+            start += 1;
+            continue;
+        }
+        const at = cursor(text, start);
+        do {
+            const width = clusterWidth(at);
+            yield { end: at.index, start, width };
+            start = at.index;
+        } while (start < text.length && !asciiAlone(text, start));
+    }
+}

package/dist/style-wire.js

@@ -1,5 +1,5 @@
-import { isPlainObject } from './facts.js';
 import { glyphForms } from './glyphs.generated.js';
+import { isPlainObject } from './plain.js';
 import { applyOperations, emptyAttributes } from './style-state.js';
 import { close, colorFallbacks, escape, headerEnd, isColorName, modifiers, open, tokens, } from './style.js';
 function isByte(value) {

package/dist/style.js

@@ -1,4 +1,4 @@
-import { isPlainObject } from './facts.js';
+import { isPlainObject } from './plain.js';
 /** Concrete terminal foregrounds; backgrounds use the same palette indices. */
 const colors = {
     black: 0,