@loomcli/core 0.2.0 → 0.4.0

package/dist/style-wire.js

@@ -0,0 +1,201 @@
+import { isPlainObject } from './facts.js';
+import { glyphForms } from './glyphs.generated.js';
+import { applyOperations, emptyAttributes } from './style-state.js';
+import { close, colorFallbacks, escape, headerEnd, isColorName, modifiers, open, tokens, } from './style.js';
+function isByte(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 255;
+}
+function color(value) {
+    if (isColorName(value)) {
+        return value;
+    }
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    if ((value.length === 2 || value.length === 3) && value[0] === 'ansi256' && isByte(value[1])) {
+        if (value.length === 2) {
+            return ['ansi256', value[1]];
+        }
+        if (!isPlainObject(value[2])) {
+            return undefined;
+        }
+        try {
+            return ['ansi256', value[1], colorFallbacks(value[2], false)];
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if ((value.length === 4 || value.length === 5) &&
+        value[0] === 'rgb' &&
+        isByte(value[1]) &&
+        isByte(value[2]) &&
+        isByte(value[3])) {
+        if (value.length === 4) {
+            return ['rgb', value[1], value[2], value[3]];
+        }
+        if (!isPlainObject(value[4])) {
+            return undefined;
+        }
+        try {
+            return ['rgb', value[1], value[2], value[3], colorFallbacks(value[4], true)];
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function operation(value, names) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    if (value.length === 1 &&
+        (value[0] === 'reset' || value[0] === 'resetForeground' || value[0] === 'resetBackground')) {
+        return [value[0]];
+    }
+    if (value.length !== 2) {
+        return undefined;
+    }
+    if (value[0] === 'token' && typeof value[1] === 'string' && names.has(value[1])) {
+        return ['token', value[1]];
+    }
+    if (value[0] === 'modifier') {
+        const modifier = modifiers.find((name) => name === value[1]);
+        return modifier === undefined ? undefined : ['modifier', modifier];
+    }
+    if (value[0] === 'foreground' || value[0] === 'background') {
+        const parsed = color(value[1]);
+        return parsed === undefined ? undefined : [value[0], parsed];
+    }
+    return undefined;
+}
+function glyphName(value) {
+    return typeof value === 'string' && Object.hasOwn(glyphForms, value);
+}
+function parseHeader(text, names) {
+    let value = undefined;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    if (value.length === 2 && value[0] === 'glyph' && glyphName(value[1])) {
+        return { kind: 'glyph', name: value[1] };
+    }
+    if (value.length === 3 &&
+        value[0] === 'pad' &&
+        typeof value[1] === 'number' &&
+        Number.isSafeInteger(value[1]) &&
+        value[1] >= 0 &&
+        (value[2] === 'left' || value[2] === 'right' || value[2] === 'center')) {
+        return { kind: 'pad', padding: { align: value[2], width: value[1] } };
+    }
+    if (value.length !== 2 || value[0] !== 'style' || !Array.isArray(value[1])) {
+        return undefined;
+    }
+    const operations = [];
+    for (const item of value[1]) {
+        const parsed = operation(item, names);
+        if (parsed === undefined) {
+            return undefined;
+        }
+        operations.push(parsed);
+    }
+    return { kind: 'style', operations };
+}
+/** Decodes framing once. Rejected headers are opaque, and nesting uses an explicit stack. */
+function parseText(input, palette, mainGlyphs) {
+    const pieces = [];
+    const scopes = [];
+    const boundaries = new Map();
+    const stack = [];
+    const names = new Set([...tokens, ...palette.keys()]);
+    const root = { attributes: emptyAttributes, operations: [], parent: undefined };
+    let active = root;
+    function append(text) {
+        pieces.push(text);
+        // Positions are UTF-16 offsets, including both units of surrogate pairs.
+        // oxlint-disable-next-line typescript/prefer-for-of
+        for (let index = 0; index < text.length; index += 1) {
+            scopes.push(active);
+        }
+    }
+    function boundary(value) {
+        const at = scopes.length;
+        const current = boundaries.get(at);
+        if (current) {
+            current.push(value);
+        }
+        else {
+            boundaries.set(at, [value]);
+        }
+    }
+    function endFrame() {
+        const ended = stack.pop();
+        if (ended?.kind === 'style') {
+            active = ended.previous;
+        }
+        else if (ended?.kind === 'pad') {
+            boundary({ kind: 'close' });
+        }
+    }
+    for (let cursor = 0; cursor < input.length;) {
+        const character = input[cursor];
+        if (character === open) {
+            const end = input.indexOf(headerEnd, cursor + 1);
+            const candidate = end === -1 ? undefined : parseHeader(input.slice(cursor + 1, end), names);
+            if (candidate === undefined || (candidate.kind === 'glyph' && input[end + 1] !== close)) {
+                const until = end === -1 ? input.length : end + 1;
+                append(input.slice(cursor, until));
+                cursor = until;
+                continue;
+            }
+            cursor = end + 1;
+            if (candidate.kind === 'glyph') {
+                append(glyphForms[candidate.name][mainGlyphs ? 0 : 1]);
+                cursor += 1;
+            }
+            else if (candidate.kind === 'style') {
+                stack.push({ kind: 'style', previous: active });
+                active = {
+                    attributes: applyOperations(active.attributes, candidate.operations, palette),
+                    operations: candidate.operations,
+                    parent: active,
+                };
+            }
+            else {
+                stack.push({ kind: 'pad' });
+                boundary({
+                    attributes: active.attributes,
+                    kind: 'open',
+                    padding: candidate.padding,
+                    scope: active,
+                });
+            }
+            continue;
+        }
+        if (character === close && stack.length > 0) {
+            endFrame();
+            cursor += 1;
+            continue;
+        }
+        if (character === escape && /^E00[0-3]$/u.test(input.slice(cursor + 1, cursor + 5))) {
+            const digits = input.slice(cursor + 1, cursor + 5);
+            append(String.fromCharCode(Number.parseInt(digits, 16)));
+            cursor += 5;
+            continue;
+        }
+        append(character ?? '');
+        cursor += 1;
+    }
+    while (stack.length > 0) {
+        endFrame();
+    }
+    return { boundaries, palette, root, scopes, text: pieces.join('') };
+}
+export { parseText };

package/dist/style.d.ts

@@ -0,0 +1,86 @@
+import type { ApplicationEnvironment, RegisteredEnvironment } from './environment.js';
+import type { Plugin, ThemeOf } from './plugin.js';
+import type { Alignment } from './style-wire.js';
+/** Concrete terminal foregrounds; backgrounds use the same palette indices. */
+declare const colors: {
+    black: number;
+    blue: number;
+    brightBlack: number;
+    brightBlue: number;
+    brightCyan: number;
+    brightGreen: number;
+    brightMagenta: number;
+    brightRed: number;
+    brightWhite: number;
+    brightYellow: number;
+    cyan: number;
+    green: number;
+    magenta: number;
+    red: number;
+    white: number;
+    yellow: number;
+};
+type Ansi16Color = keyof typeof colors;
+type ColorName = Ansi16Color;
+interface ColorFallbacks {
+    readonly ansi256?: number | undefined;
+    readonly ansi16?: Ansi16Color | undefined;
+}
+type Ansi256Fallbacks = Pick<ColorFallbacks, 'ansi16'>;
+type RgbArguments = [
+    red: number,
+    green: number,
+    blue: number,
+    fallbacks?: ColorFallbacks | undefined
+];
+type Color = ColorName | readonly ['rgb', number, number, number, ColorFallbacks?] | readonly ['ansi256', number, Ansi256Fallbacks?];
+declare const modifiers: readonly ['bold', 'faint', 'italic', 'underline', 'inverse', 'hidden', 'strikethrough', 'overline'];
+type Modifier = (typeof modifiers)[number];
+declare const tokens: readonly ['dim', 'primary', 'highlight', 'success', 'warning', 'error', 'info'];
+type CoreToken = (typeof tokens)[number];
+type Reset = 'reset' | 'resetForeground' | 'resetBackground';
+type Operation = readonly ['foreground' | 'background', Color] | readonly ['modifier', Modifier] | readonly [Reset] | readonly ['token', string];
+declare const semanticStyle: unique symbol;
+type Style<Names extends string = CoreToken, Semantic extends boolean = false> = {
+    (text: string): string;
+    readonly [semanticStyle]: Semantic;
+    readonly escape: (text: string) => string;
+    readonly hex: (color: string, fallbacks?: ColorFallbacks) => Style<Names, Semantic>;
+    readonly bgHex: (color: string, fallbacks?: ColorFallbacks) => Style<Names, Semantic>;
+    readonly rgb: (...args: RgbArguments) => Style<Names, Semantic>;
+    readonly bgRgb: (...args: RgbArguments) => Style<Names, Semantic>;
+    readonly ansi256: (index: number, fallbacks?: Ansi256Fallbacks) => Style<Names, Semantic>;
+    readonly bgAnsi256: (index: number, fallbacks?: Ansi256Fallbacks) => Style<Names, Semantic>;
+} & {
+    readonly [Name in ColorName | `bg${Capitalize<ColorName>}` | Modifier | Reset]: Style<Names, Semantic>;
+} & {
+    readonly [Name in Names]: Style<Names, true>;
+};
+type ThemeNames<Contributor> = Contributor extends Plugin ? keyof ThemeOf<Contributor> & string : never;
+type EnvironmentStyle<Environment extends ApplicationEnvironment<unknown, readonly Plugin[]>> = Style<CoreToken | ThemeNames<Environment['plugins'][number]>>;
+type ContextualStyle = EnvironmentStyle<RegisteredEnvironment>;
+type ConcreteStyle = Style;
+type ThemeMapping = Readonly<Record<string, ConcreteStyle | undefined>>;
+type ThemeConstraint<Mapping> = {
+    readonly [Key in keyof Mapping]: Key extends Exclude<keyof Style, CoreToken> | (typeof reservedCallableNames)[number] ? never : Mapping[Key];
+};
+declare const open = "\uE000";
+declare const headerEnd = "\uE001";
+declare const close = "\uE002";
+declare const escape = "\uE003";
+declare const chains: WeakMap<object, readonly Operation[]>;
+declare const reservedCallableNames: readonly ['apply', 'arguments', 'bind', 'call', 'caller', 'constructor', 'length', 'name', 'prototype', 'toString', 'toLocaleString', 'valueOf', 'hasOwnProperty', 'isPrototypeOf', 'propertyIsEnumerable', '__proto__', '__defineGetter__', '__defineSetter__', '__lookupGetter__', '__lookupSetter__', 'then'];
+declare const reservedStyleNames: Set<string>;
+declare function frame(header: readonly unknown[], body: string): string;
+declare function escapeText(text: string): string;
+/** Copies options at the helper boundary; the wire parser uses the same value rules. */
+declare function colorFallbacks(value: unknown, allow256: boolean): ColorFallbacks;
+/** Properties are generated from the same catalogs the wire parser validates. */
+declare function createStyle(names?: ReadonlySet<string>): ContextualStyle;
+declare function isColorName(value: unknown): value is ColorName;
+declare function pad(text: string, minimumWidth: number, options?: {
+    align?: Alignment;
+}): string;
+declare const style: Style;
+export type { Ansi16Color, Ansi256Fallbacks, ColorFallbacks, ContextualStyle, Color, ColorName, ConcreteStyle, CoreToken, Modifier, Operation, Style, ThemeConstraint, ThemeMapping, };
+export { colorFallbacks, chains, close, colors, createStyle, escape, escapeText, frame, headerEnd, isColorName, modifiers, open, pad, reservedStyleNames, style, tokens, };

package/dist/style.js

@@ -0,0 +1,201 @@
+import { isPlainObject } from './facts.js';
+/** Concrete terminal foregrounds; backgrounds use the same palette indices. */
+const colors = {
+    black: 0,
+    blue: 4,
+    brightBlack: 8,
+    brightBlue: 12,
+    brightCyan: 14,
+    brightGreen: 10,
+    brightMagenta: 13,
+    brightRed: 9,
+    brightWhite: 15,
+    brightYellow: 11,
+    cyan: 6,
+    green: 2,
+    magenta: 5,
+    red: 1,
+    white: 7,
+    yellow: 3,
+};
+const modifiers = [
+    'bold',
+    'faint',
+    'italic',
+    'underline',
+    'inverse',
+    'hidden',
+    'strikethrough',
+    'overline',
+];
+const tokens = ['dim', 'primary', 'highlight', 'success', 'warning', 'error', 'info'];
+const open = '\uE000';
+const headerEnd = '\uE001';
+const close = '\uE002';
+const escape = '\uE003';
+const chains = new WeakMap();
+const reservedCallableNames = [
+    'apply',
+    'arguments',
+    'bind',
+    'call',
+    'caller',
+    'constructor',
+    'length',
+    'name',
+    'prototype',
+    'toString',
+    'toLocaleString',
+    'valueOf',
+    'hasOwnProperty',
+    'isPrototypeOf',
+    'propertyIsEnumerable',
+    '__proto__',
+    '__defineGetter__',
+    '__defineSetter__',
+    '__lookupGetter__',
+    '__lookupSetter__',
+    'then',
+];
+const reservedStyleNames = new Set([
+    ...Object.keys(colors),
+    ...Object.keys(colors).map((name) => `bg${name.charAt(0).toUpperCase()}${name.slice(1)}`),
+    ...modifiers,
+    'reset',
+    'resetForeground',
+    'resetBackground',
+    'hex',
+    'bgHex',
+    'rgb',
+    'bgRgb',
+    'ansi256',
+    'bgAnsi256',
+    'escape',
+    ...reservedCallableNames,
+]);
+function textOnly(text) {
+    if (typeof text !== 'string') {
+        throw new TypeError('Style helpers require a string.');
+    }
+    return text;
+}
+function frame(header, body) {
+    const encoded = JSON.stringify(header).replace(/[\uE000-\uE003]/gu, (character) => `\\u${character.charCodeAt(0).toString(16)}`);
+    return `${open}${encoded}${headerEnd}${body}${close}`;
+}
+function escapeText(text) {
+    return textOnly(text).replace(/[\uE000-\uE003]/gu, (character) => `${escape}${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function byte(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 255) {
+        throw new RangeError('Color channels and palette indices must be integers from 0 through 255.');
+    }
+    return value;
+}
+/** Copies options at the helper boundary; the wire parser uses the same value rules. */
+function colorFallbacks(value, allow256) {
+    if (value === undefined) {
+        return {};
+    }
+    if (!isPlainObject(value) ||
+        Reflect.ownKeys(value).some((key) => key !== 'ansi16' && !(allow256 && key === 'ansi256'))) {
+        throw new TypeError('Color fallbacks must be a plain object with supported depth names.');
+    }
+    const ansi16 = value.ansi16;
+    const ansi256 = value.ansi256;
+    if (ansi16 !== undefined && !isColorName(ansi16)) {
+        throw new TypeError('The ansi16 fallback must be a terminal foreground color name.');
+    }
+    if (ansi256 !== undefined &&
+        (typeof ansi256 !== 'number' || !Number.isInteger(ansi256) || ansi256 < 0 || ansi256 > 255)) {
+        throw new RangeError('The ansi256 fallback must be an integer from 0 through 255.');
+    }
+    return {
+        ...(ansi16 === undefined ? {} : { ansi16 }),
+        ...(ansi256 === undefined ? {} : { ansi256 }),
+    };
+}
+function rgbColor([red, green, blue, fallbacks]) {
+    const rgb = ['rgb', byte(red), byte(green), byte(blue)];
+    const copied = colorFallbacks(fallbacks, true);
+    return Object.keys(copied).length === 0 ? rgb : [...rgb, copied];
+}
+function indexedColor(index, fallbacks) {
+    const color = ['ansi256', byte(index)];
+    const copied = colorFallbacks(fallbacks, false);
+    return Object.keys(copied).length === 0 ? color : [...color, copied];
+}
+function hexColor(value, fallbacks) {
+    if (typeof value !== 'string' || !/^#(?:[\da-f]{3}|[\da-f]{6})$/iu.test(value)) {
+        throw new TypeError('Hex colors must use #RGB or #RRGGBB.');
+    }
+    const full = value.length === 4
+        ? value.slice(1).replace(/[\da-f]/giu, (digit) => digit + digit)
+        : value.slice(1);
+    return rgbColor([
+        Number.parseInt(full.slice(0, 2), 16),
+        Number.parseInt(full.slice(2, 4), 16),
+        Number.parseInt(full.slice(4, 6), 16),
+        fallbacks,
+    ]);
+}
+/** Properties are generated from the same catalogs the wire parser validates. */
+function createStyle(names = new Set(tokens)) {
+    function chain(operations) {
+        const callable = (text) => frame(['style', operations], textOnly(text));
+        const next = (operation) => chain([...operations, operation]);
+        const helpers = {
+            ansi256: (index, fallbacks) => next(['foreground', indexedColor(index, fallbacks)]),
+            bgAnsi256: (index, fallbacks) => next(['background', indexedColor(index, fallbacks)]),
+            bgHex: (value, fallbacks) => next(['background', hexColor(value, fallbacks)]),
+            bgRgb: (...args) => next(['background', rgbColor(args)]),
+            escape: escapeText,
+            hex: (value, fallbacks) => next(['foreground', hexColor(value, fallbacks)]),
+            rgb: (...args) => next(['foreground', rgbColor(args)]),
+        };
+        const properties = new Map(Object.entries(helpers).map(([name, helper]) => [name, () => helper]));
+        for (const name of Object.keys(colors)) {
+            if (isColorName(name)) {
+                properties.set(name, () => next(['foreground', name]));
+                properties.set(`bg${name.charAt(0).toUpperCase()}${name.slice(1)}`, () => next(['background', name]));
+            }
+        }
+        for (const name of modifiers) {
+            properties.set(name, () => next(['modifier', name]));
+        }
+        for (const name of ['reset', 'resetForeground', 'resetBackground']) {
+            properties.set(name, () => next([name]));
+        }
+        for (const name of names) {
+            properties.set(name, () => next(['token', name]));
+        }
+        const value = new Proxy(callable, {
+            get: (target, property, receiver) => typeof property === 'string' && properties.has(property)
+                ? properties.get(property)?.()
+                : Reflect.get(target, property, receiver),
+        });
+        chains.set(value, operations);
+        Object.freeze(value);
+        // Last resort: no typed path exists from runtime-generated callable properties to mapped keys.
+        // It holds because the catalogs above supply every declared helper and token; chains retain operations for validation.
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+        return value;
+    }
+    return chain([]);
+}
+function isColorName(value) {
+    return typeof value === 'string' && Object.hasOwn(colors, value);
+}
+function pad(text, minimumWidth, options) {
+    textOnly(text);
+    if (!Number.isSafeInteger(minimumWidth) || minimumWidth < 0) {
+        throw new RangeError('Padding width must be a nonnegative safe integer.');
+    }
+    const align = options?.align ?? 'left';
+    if (align !== 'left' && align !== 'right' && align !== 'center') {
+        throw new TypeError('Padding alignment must be left, right, or center.');
+    }
+    return frame(['pad', minimumWidth, align], text);
+}
+const style = createStyle();
+export { colorFallbacks, chains, close, colors, createStyle, escape, escapeText, frame, headerEnd, isColorName, modifiers, open, pad, reservedStyleNames, style, tokens, };

package/dist/theme.d.ts

@@ -0,0 +1,3 @@
+import type { Palette } from './style-state.js';
+declare function buildTheme(value: unknown, identity: string): Palette;
+export { buildTheme };

package/dist/theme.js

@@ -0,0 +1,22 @@
+import { DeclarationError } from './errors.js';
+import { isPlainObject } from './facts.js';
+import { chains, reservedStyleNames } from './style.js';
+function buildTheme(value, identity) {
+    if (!isPlainObject(value)) {
+        throw new DeclarationError(`Plugin "${identity}" must declare theme as a mapping of names to concrete style chains.`);
+    }
+    const palette = new Map();
+    for (const [name, chain] of Object.entries(value)) {
+        if (reservedStyleNames.has(name)) {
+            throw new DeclarationError(`Plugin "${identity}" theme name "${name}" shadows a built-in style member.`);
+        }
+        const operations = typeof chain === 'function' ? chains.get(chain) : undefined;
+        if (chain !== undefined &&
+            (operations === undefined || operations.some((entry) => entry[0] === 'token'))) {
+            throw new DeclarationError(`Plugin "${identity}" theme mapping "${name}" must be an unapplied concrete style chain without semantic tokens.`);
+        }
+        palette.set(name, operations ?? []);
+    }
+    return palette;
+}
+export { buildTheme };