@fnndsc/brasa 0.16.1 → 0.17.0

package/dist/builtins/res/plugin.info.js

@@ -0,0 +1,167 @@
+/**
+ * @file One registered plugin, as data — and the manual as a projection of it.
+ *
+ * A plugin is the one-node case of the compute graph, and until now its
+ * substance existed only as a rendered manual: `cat /bin/<plugin>` scraped
+ * CUBE and printed a table, and that table was the whole of what any surface
+ * could have. Nothing downstream could use it — not a card, not a parameter
+ * list, not a form.
+ *
+ * This module builds the model first and renders from it, so the text a
+ * terminal prints and the data a graphical surface reads are the same facts
+ * said twice rather than two independent scrapes that can disagree.
+ *
+ * Parameters are drained to exhaustion. The `{ limit: 100 }` this replaces
+ * dropped the tail of any plugin declaring more and said nothing about it —
+ * and a parameter table that stops early is worse than no table, because it
+ * still looks complete.
+ *
+ * @module
+ */
+import chalk from 'chalk';
+import { errorStack, plugin_find, pluginParameters_drain, Ok, Err, } from '@fnndsc/cumin';
+import { session } from '../../session/index.js';
+/** How a `/bin` entry names a plugin: `<name>-v<version>`. */
+const BIN_VERSION_SEPARATOR = '-v';
+/**
+ * Splits a `/bin` entry name into the plugin identity it addresses.
+ *
+ * @param entry - A `/bin` basename or full path (`pl-dcm2niix-v1.0.0`).
+ * @returns The name and version, or null when the entry names no version.
+ */
+export function pluginSpecifier_parse(entry) {
+    const command = entry.replace(/^.*\//, '');
+    const cut = command.lastIndexOf(BIN_VERSION_SEPARATOR);
+    if (cut === -1)
+        return null;
+    const name = command.substring(0, cut);
+    const version = command.substring(cut + BIN_VERSION_SEPARATOR.length);
+    if (name === '' || version === '')
+        return null;
+    return { name, version, command };
+}
+/**
+ * Projects one wire parameter row onto the model's parameter shape.
+ *
+ * @param row - The parameter as CUBE serves it.
+ * @returns The typed parameter.
+ */
+function parameter_project(row) {
+    const name = row.name;
+    const declaredFlag = row.flag;
+    const flag = typeof declaredFlag === 'string' && declaredFlag !== ''
+        ? declaredFlag
+        : `--${name}`;
+    return {
+        name,
+        type: row.type ?? 'string',
+        optional: row.optional ?? false,
+        flag,
+        ...(row.default === undefined ? {} : { default: row.default }),
+        ...(row.help === undefined || row.help === '' ? {} : { help: row.help }),
+    };
+}
+/**
+ * Reads one registered plugin whole: its identity, its authoring facts, and
+ * every parameter it declares.
+ *
+ * @param specifier - The plugin's name, version and `/bin` command.
+ * @returns The model, or a failure with the reason on the error stack.
+ */
+export async function pluginInfo_build(specifier) {
+    const client = await session.connection.client_get();
+    if (!client) {
+        errorStack.stack_push('error', 'No active ChRIS connection to read a plugin.');
+        return Err();
+    }
+    const found = await plugin_find(client, specifier.name, specifier.version);
+    if (found === null) {
+        errorStack.stack_push('error', `Plugin not found on server: ${specifier.name} v${specifier.version}`);
+        return Err();
+    }
+    const rows = await pluginParameters_drain(found.handle);
+    const data = found.data;
+    return Ok({
+        ...(typeof data.id === 'number' ? { id: data.id } : {}),
+        name: data.name ?? specifier.name,
+        version: data.version ?? specifier.version,
+        type: data.type ?? 'ds',
+        ...(data.title === undefined || data.title === '' ? {} : { title: data.title }),
+        ...(data.description === undefined || data.description === '' ? {} : { description: data.description }),
+        ...(data.authors === undefined || data.authors === '' ? {} : { authors: data.authors }),
+        ...(data.documentation === undefined || data.documentation === '' ? {} : { documentation: data.documentation }),
+        ...(data.category === undefined || data.category === '' ? {} : { category: data.category }),
+        parameters: rows.map(parameter_project),
+        command: specifier.command,
+    });
+}
+/** Column widths of the rendered parameter table. */
+const FLAG_WIDTH = 22;
+const TYPE_WIDTH = 11;
+const REQUIRED_WIDTH = 11;
+const DEFAULT_WIDTH = 13;
+/** Width of the rules that bracket the manual's sections. */
+const RULE_WIDTH = 74;
+/**
+ * Renders a parameter's default the way an operator reads it: the value, an
+ * explicit pair of quotes for the empty string, and `None` for no default at
+ * all — an empty cell would read as the empty string.
+ *
+ * @param parameter - The declared parameter.
+ * @returns The cell text.
+ */
+function defaultCell_render(parameter) {
+    if (parameter.default === undefined || parameter.default === null)
+        return 'None';
+    const shown = String(parameter.default);
+    return shown === '' ? '""' : shown;
+}
+/**
+ * Renders the plugin manual — the same text `cat /bin/<plugin>` has always
+ * printed, now a projection of the model rather than the only thing there is.
+ *
+ * @param model - The plugin model.
+ * @returns The formatted manual.
+ */
+export function pluginInfoText_render(model) {
+    const command = model.command ?? `${model.name}${BIN_VERSION_SEPARATOR}${model.version}`;
+    const lines = [];
+    lines.push('');
+    lines.push(chalk.bold.magenta(`${model.name.toUpperCase()} (Version ${model.version})`));
+    lines.push(chalk.gray('─'.repeat(RULE_WIDTH)));
+    lines.push(`${chalk.bold.blue('Type:')}         ${model.type}`);
+    lines.push(`${chalk.bold.blue('Author:')}       ${model.authors ?? 'FNNDSC <dev@babymri.org>'}`);
+    if (model.documentation !== undefined) {
+        lines.push(`${chalk.bold.blue('Repository:')}   ${model.documentation}`);
+    }
+    lines.push('');
+    lines.push(chalk.bold.blue('DESCRIPTION'));
+    lines.push(`  ${model.description ?? 'No description provided.'}`);
+    lines.push('');
+    lines.push(chalk.bold.blue('PARAMETERS'));
+    lines.push(`  ${chalk.bold.white('Flag'.padEnd(FLAG_WIDTH))}${chalk.bold.white('Type'.padEnd(TYPE_WIDTH))}${chalk.bold.white('Required'.padEnd(REQUIRED_WIDTH))}${chalk.bold.white('Default'.padEnd(DEFAULT_WIDTH))}${chalk.bold.white('Description')}`);
+    lines.push(`  ${chalk.gray('─'.repeat(RULE_WIDTH))}`);
+    for (const parameter of model.parameters) {
+        const required = parameter.optional ? 'No' : 'Yes';
+        lines.push(`  ${chalk.yellow(parameter.flag.padEnd(FLAG_WIDTH))}${parameter.type.padEnd(TYPE_WIDTH)}${required.padEnd(REQUIRED_WIDTH)}${defaultCell_render(parameter).padEnd(DEFAULT_WIDTH)}${parameter.help ?? ''}`);
+    }
+    lines.push('');
+    lines.push(chalk.bold.blue('USAGE EXAMPLES'));
+    const required = model.parameters.filter((parameter) => !parameter.optional);
+    const optional = model.parameters.filter((parameter) => parameter.optional);
+    const requiredFlags = required
+        .map((parameter) => `${parameter.flag} "value"`)
+        .join(' ');
+    const basic = requiredFlags ? `${command} ${requiredFlags}` : command;
+    lines.push(`  ${chalk.white(basic)}                     ${chalk.gray('# Basic execution')}`);
+    const first = optional[0];
+    if (first !== undefined) {
+        const withOptional = requiredFlags
+            ? `${command} ${requiredFlags} ${first.flag} "value"`
+            : `${command} ${first.flag} "value"`;
+        lines.push(`  ${chalk.white(withOptional)}     ${chalk.gray('# With optional parameter')}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=plugin.info.js.map

package/dist/builtins/res/plugin.info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.info.js","sourceRoot":"","sources":["../../../src/builtins/res/plugin.info.ts"],"names":[],"mappings":"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"}

package/dist/builtins/res/plugin.js

@@ -22,6 +22,8 @@ import { table_render } from '@fnndsc/chili/screen/screen.js';
 import { spinner } from '../../lib/spinner.js';
 import { errorStack, envelope_ok, envelope_error } from '@fnndsc/cumin';
 import { chili_capture } from '@fnndsc/chili/screen/output.js';
+import { PLUGIN_INFO_MODEL_KIND } from '@fnndsc/menu';
+import { pluginInfo_build, pluginInfoText_render, pluginSpecifier_parse, } from './plugin.info.js';
 import { authorizationFailure_is, sudoHint_build } from '../../core/elevation.js';
 /**
  * Handles plugin commands.
@@ -67,12 +69,15 @@ export async function builtin_plugin(args) {
             }
             return envelope_ok(`${chalk.gray('No fields found.')}\n`);
         }
+        else if (subcommand === 'info') {
+            return await pluginInfo_show(parsed._.slice(1));
+        }
         else if (subcommand === 'search') {
             const query = parsed._[1] ?? '';
             return await builtin_plugin(['list', `--search`, query]);
         }
         process.exitCode = 1;
-        return envelope_error('', undefined, `${chalk.yellow(`Unknown subcommand: ${subcommand}. Usage: plugin <list|run|add|inspect|search>`)}\n`);
+        return envelope_error('', undefined, `${chalk.yellow(`Unknown subcommand: ${subcommand}. Usage: plugin <list|run|add|info|inspect|search>`)}\n`);
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
@@ -80,6 +85,41 @@ export async function builtin_plugin(args) {
         return envelope_error('', undefined, `${chalk.red(`Plugin error: ${msg}`)}\n`);
     }
 }
+/**
+ * Shows one registered plugin: the manual on the terminal, the whole plugin
+ * on the wire.
+ *
+ * Spelled the way `/bin` spells it — `plugin info pl-dcm2niix-v1.0.0`, or the
+ * path itself — with `<name> <version>` accepted for an operator who has the
+ * two halves and not the entry name.
+ *
+ * @param words - The specifier: one `/bin` entry, or a name and a version.
+ * @returns An envelope carrying the manual and the `plugin.info` model.
+ */
+async function pluginInfo_show(words) {
+    const entry = words[0];
+    if (entry === undefined) {
+        return envelope_ok(`${chalk.red('Usage: plugin info <name>-v<version> | <name> <version>')}\n`);
+    }
+    const version = words[1];
+    const specifier = version === undefined
+        ? pluginSpecifier_parse(entry)
+        : { name: entry.replace(/^.*\//, ''), version, command: `${entry.replace(/^.*\//, '')}-v${version}` };
+    if (specifier === null) {
+        process.exitCode = 1;
+        return envelope_error('', undefined, `${chalk.red(`Not a versioned plugin entry: ${entry}. Spell it '<name>-v<version>'.`)}\n`);
+    }
+    const built = await pluginInfo_build(specifier);
+    if (!built.ok) {
+        const problem = errorStack.stack_pop();
+        process.exitCode = 1;
+        return envelope_error('', undefined, `${chalk.red(problem?.message ?? 'Plugin not found.')}\n`);
+    }
+    return envelope_ok(pluginInfoText_render(built.value), {
+        kind: PLUGIN_INFO_MODEL_KIND,
+        data: built.value,
+    });
+}
 /**
  * Interactive plugin add command with spinner and colored output.
  *

package/dist/builtins/res/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../../src/builtins/res/plugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../../src/builtins/res/plugin.ts"],"names":[],"mappings":"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"}

package/dist/core/engine.d.ts

@@ -50,6 +50,16 @@ export interface BrasaEngine {
      * @returns The file's bytes.
      */
     file_read?(filePath: string): Promise<Buffer>;
+    /**
+     * Writes bytes to one ChRIS path, resolved against the session's working
+     * directory. The twin of {@link Engine.file_read}: a surface that cannot
+     * reach the machine's disk (a browser) hands its bytes to the daemon,
+     * which puts them in the store through the kernel like any other write.
+     *
+     * @param filePath - The destination path (absolute or cwd-relative).
+     * @param bytes - The content to write.
+     */
+    file_write?(filePath: string, bytes: Buffer): Promise<void>;
     /**
      * Notes a regard write from a surface: the addressable thing the operator
      * most recently indicated. The engine retains it as session truth (last
@@ -155,6 +165,17 @@ export declare function command_handle(line: string): Promise<void>;
  * @returns The engine facade.
  */
 export declare function engine_create(): Promise<BrasaEngine>;
+/**
+ * Writes bytes to one ChRIS path through the kernel's own create.
+ *
+ * A browser surface holds bytes the daemon's machine has never seen; this
+ * is how they reach the store without any surface talking to CUBE.
+ *
+ * @param filePath - The destination path (absolute or cwd-relative).
+ * @param bytes - The content to write.
+ * @throws {Error} When the store refused the write.
+ */
+export declare function file_write(filePath: string, bytes: Buffer): Promise<void>;
 /**
  * Reads one ChRIS file's raw bytes through ChILI, resolved against the
  * session's working directory.

package/dist/core/engine.js

@@ -253,6 +253,7 @@ export async function engine_create() {
         line_cancel,
         line_complete,
         file_read,
+        file_write,
         regard_note: (regard) => session.regard_set(regard),
         regard_get: () => session.regard_get(),
         watch_set: (subject, owner, on) => {
@@ -268,6 +269,32 @@ export async function engine_create() {
         ambient_listen,
     };
 }
+/**
+ * Writes bytes to one ChRIS path through the kernel's own create.
+ *
+ * A browser surface holds bytes the daemon's machine has never seen; this
+ * is how they reach the store without any surface talking to CUBE.
+ *
+ * @param filePath - The destination path (absolute or cwd-relative).
+ * @param bytes - The content to write.
+ * @throws {Error} When the store refused the write.
+ */
+export async function file_write(filePath, bytes) {
+    const { path_resolve } = await import('../builtins/utils.js');
+    const { files_create } = await import('@fnndsc/salsa');
+    const { listCache_get } = await import('@fnndsc/cumin');
+    const resolved = await path_resolve(filePath);
+    const written = await files_create(bytes, resolved);
+    if (!written) {
+        throw new Error(`cannot write ${filePath}`);
+    }
+    // A write invalidates the listing it changed, as every writing builtin
+    // does. Without this the browser that delivered the file asks for the
+    // folder again and is served the folder as it was before the delivery —
+    // which reads as an upload that silently did nothing.
+    const parent = resolved.replace(/\/[^/]*$/, '') || '/';
+    listCache_get().cache_invalidate(parent);
+}
 /**
  * Reads one ChRIS file's raw bytes through ChILI, resolved against the
  * session's working directory.

package/dist/core/engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/core/engine.ts"],"names":[],"mappings":"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"}

package/dist/core/promptContext.d.ts

@@ -34,7 +34,7 @@ export interface SessionPromptContext {
         jobs: number;
         feeds: number;
     };
-    /** The daemon's declared host-control tiers, when it acts on its own host. */
+    /** Calypso's declared host-control tiers, when it acts on its own host. */
     hostControl?: string[];
     /**
      * Warm-up steps that failed behind the prompt and have not since

package/dist/core/question.d.ts

@@ -11,6 +11,7 @@
  *
  * @module
  */
+import { type PromptPath } from './surface.js';
 /**
  * Asks a question through the active surface.
  *
@@ -25,3 +26,29 @@ export declare function repl_question(prompt: string): Promise<string>;
  * @returns The trimmed secret string.
  */
 export declare function repl_questionHidden(prompt: string): Promise<string>;
+/**
+ * Asks for a yes/no through the active surface.
+ *
+ * The kind travels so a surface can offer two capsules rather than make an
+ * operator type a letter; a terminal still reads `y`/`n`, and the answer is
+ * interpreted here so every caller agrees on what counts as yes.
+ *
+ * @param prompt - The question string to display.
+ * @returns True when the answer was yes.
+ */
+export declare function repl_confirm(prompt: string): Promise<boolean>;
+/**
+ * Asks for a location through the active surface.
+ *
+ * The anchor is a fact the kernel knows — the session's own cwd, the
+ * directory a command is already working in — never a directory invented
+ * for the occasion, since inventing one means creating it behind the
+ * operator's back.
+ *
+ * @param prompt - The question string to display.
+ * @param details - Where to start, whether a directory is wanted, and a
+ *   basename to offer.
+ * @param commit - The word the committing control should read.
+ * @returns The location the operator gave.
+ */
+export declare function repl_questionPath(prompt: string, details: PromptPath, commit?: string): Promise<string>;

package/dist/core/question.js

@@ -30,4 +30,42 @@ export function repl_question(prompt) {
 export function repl_questionHidden(prompt) {
     return surface_get().prompt({ message: prompt, hidden: true });
 }
+/**
+ * Asks for a yes/no through the active surface.
+ *
+ * The kind travels so a surface can offer two capsules rather than make an
+ * operator type a letter; a terminal still reads `y`/`n`, and the answer is
+ * interpreted here so every caller agrees on what counts as yes.
+ *
+ * @param prompt - The question string to display.
+ * @returns True when the answer was yes.
+ */
+export async function repl_confirm(prompt) {
+    const answer = await surface_get().prompt({ message: prompt, wants: 'confirm' });
+    const said = answer.trim().toLowerCase();
+    return said === 'y' || said === 'yes';
+}
+/**
+ * Asks for a location through the active surface.
+ *
+ * The anchor is a fact the kernel knows — the session's own cwd, the
+ * directory a command is already working in — never a directory invented
+ * for the occasion, since inventing one means creating it behind the
+ * operator's back.
+ *
+ * @param prompt - The question string to display.
+ * @param details - Where to start, whether a directory is wanted, and a
+ *   basename to offer.
+ * @param commit - The word the committing control should read.
+ * @returns The location the operator gave.
+ */
+export function repl_questionPath(prompt, details, commit) {
+    const wants = 'path';
+    return surface_get().prompt({
+        message: prompt,
+        wants,
+        path: details,
+        ...(commit === undefined ? {} : { commit }),
+    });
+}
 //# sourceMappingURL=question.js.map

package/dist/core/question.js.map

@@ -1 +1 @@
-{"version":3,"file":"question.js","sourceRoot":"","sources":["../../src/core/question.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,WAAW,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,OAAO,WAAW,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AACjE,CAAC"}
+{"version":3,"file":"question.js","sourceRoot":"","sources":["../../src/core/question.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAoC,MAAM,cAAc,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,WAAW,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,OAAO,WAAW,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAc;IAC/C,MAAM,MAAM,GAAW,MAAM,WAAW,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IACzF,MAAM,IAAI,GAAW,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACjD,OAAO,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,KAAK,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAc,EACd,OAAmB,EACnB,MAAe;IAEf,MAAM,KAAK,GAAe,MAAM,CAAC;IACjC,OAAO,WAAW,EAAE,CAAC,MAAM,CAAC;QAC1B,OAAO,EAAE,MAAM;QACf,KAAK;QACL,IAAI,EAAE,OAAO;QACb,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;KAC5C,CAAC,CAAC;AACL,CAAC"}

package/dist/core/surface.d.ts

@@ -68,13 +68,26 @@ export interface SurfaceCapabilities {
 /**
  * A request to prompt the user for a line of input.
  *
+ * `wants` is what the question is asking FOR, so a surface can choose the
+ * instrument that answers it — a browser to walk for a location, a masked
+ * field for a secret, two capsules for a yes/no — rather than reading the
+ * wording and guessing. A terminal ignores all of it and reads a line,
+ * which is why every field beyond `message` is optional.
+ *
  * @property message - The prompt text to display.
  * @property hidden - When true, the entered text is not echoed; requires the
- *   `hiddenInput` capability.
+ *   `hiddenInput` capability. Kept beside `wants` because it is what an
+ *   older surface reads.
+ * @property wants - The kind of value that answers this.
+ * @property path - Where browsing starts and what to compose, for a `path`.
+ * @property commit - The word the committing control should read.
  */
 export interface PromptRequest {
     message: string;
     hidden?: boolean;
+    wants?: PromptKind;
+    path?: PromptPath;
+    commit?: string;
 }
 /**
  * Content handed to a surface's local editor.
@@ -87,8 +100,8 @@ export interface LocalEditRequest {
     content: string;
     extension?: string;
 }
-export type { FileDeliverRequest, FileDeliverResult } from '@fnndsc/menu';
-import type { FileDeliverRequest, FileDeliverResult } from '@fnndsc/menu';
+export type { FileDeliverRequest, FileDeliverResult, PromptKind, PromptPath } from '@fnndsc/menu';
+import type { FileDeliverRequest, FileDeliverResult, PromptKind, PromptPath } from '@fnndsc/menu';
 /**
  * The outcome of a local edit.
  *

package/dist/core/surface.js.map

@@ -1 +1 @@
-{"version":3,"file":"surface.js","sourceRoot":"","sources":["../../src/core/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA+JH;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,mDAAmD;IACnC,UAAU,CAA4B;IAEtD;;;OAGG;IACH,YAAY,UAAqC,EAAE,OAAe;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAC1B,kBAAkB;IACF,YAAY,GAAwB;QAClD,WAAW,EAAE,KAAK;QAClB,SAAS,EAAE,KAAK;QAChB,GAAG,EAAE,KAAK;QACV,YAAY,EAAE,KAAK;QACnB,aAAa,EAAE,KAAK;QACpB,YAAY,EAAE,KAAK;QACnB,gBAAgB,EAAE,KAAK;QACvB,eAAe,EAAE,KAAK;KACvB,CAAC;IAEF,kBAAkB;IACX,MAAM,CAAC,QAAuB;QACnC,MAAM,IAAI,eAAe,CAAC,KAAK,EAAE,uCAAuC,CAAC,CAAC;IAC5E,CAAC;IAED,kBAAkB;IACX,WAAW,CAAC,QAAgB,EAAE,MAAc;QACjD,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,4CAA4C,CAAC,CAAC;IAC1F,CAAC;IAED,kBAAkB;IACX,YAAY,CAAC,QAAgB;QAClC,MAAM,IAAI,eAAe,CAAC,eAAe,EAAE,yCAAyC,CAAC,CAAC;IACxF,CAAC;IAED,kBAAkB;IACX,SAAS,CAAC,QAA0B;QACzC,MAAM,IAAI,eAAe,CAAC,WAAW,EAAE,0CAA0C,CAAC,CAAC;IACrF,CAAC;IAED,kBAAkB;IACX,WAAW,CAAC,QAA4B;QAC7C,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,qCAAqC,CAAC,CAAC;IACnF,CAAC;CACF;AAED,0EAA0E;AAC1E,IAAI,aAAa,GAAY,IAAI,eAAe,EAAE,CAAC;AAEnD;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,MAAM,QAAQ,GAAY,aAAa,CAAC;IACxC,aAAa,GAAG,OAAO,CAAC;IACxB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAqC,EACrC,OAAe;IAEf,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}
+{"version":3,"file":"surface.js","sourceRoot":"","sources":["../../src/core/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA4KH;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,mDAAmD;IACnC,UAAU,CAA4B;IAEtD;;;OAGG;IACH,YAAY,UAAqC,EAAE,OAAe;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAC1B,kBAAkB;IACF,YAAY,GAAwB;QAClD,WAAW,EAAE,KAAK;QAClB,SAAS,EAAE,KAAK;QAChB,GAAG,EAAE,KAAK;QACV,YAAY,EAAE,KAAK;QACnB,aAAa,EAAE,KAAK;QACpB,YAAY,EAAE,KAAK;QACnB,gBAAgB,EAAE,KAAK;QACvB,eAAe,EAAE,KAAK;KACvB,CAAC;IAEF,kBAAkB;IACX,MAAM,CAAC,QAAuB;QACnC,MAAM,IAAI,eAAe,CAAC,KAAK,EAAE,uCAAuC,CAAC,CAAC;IAC5E,CAAC;IAED,kBAAkB;IACX,WAAW,CAAC,QAAgB,EAAE,MAAc;QACjD,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,4CAA4C,CAAC,CAAC;IAC1F,CAAC;IAED,kBAAkB;IACX,YAAY,CAAC,QAAgB;QAClC,MAAM,IAAI,eAAe,CAAC,eAAe,EAAE,yCAAyC,CAAC,CAAC;IACxF,CAAC;IAED,kBAAkB;IACX,SAAS,CAAC,QAA0B;QACzC,MAAM,IAAI,eAAe,CAAC,WAAW,EAAE,0CAA0C,CAAC,CAAC;IACrF,CAAC;IAED,kBAAkB;IACX,WAAW,CAAC,QAA4B;QAC7C,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,qCAAqC,CAAC,CAAC;IACnF,CAAC;CACF;AAED,0EAA0E;AAC1E,IAAI,aAAa,GAAY,IAAI,eAAe,EAAE,CAAC;AAEnD;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,MAAM,QAAQ,GAAY,aAAa,CAAC;IACxC,aAAa,GAAG,OAAO,CAAC;IACxB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAqC,EACrC,OAAe;IAEf,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}