# @mwillbanks/tuil-core

Source: /tuil/docs/reference/packages/core
Locale: en

Core runtime, lifecycle, capability, command, semantic, and terminal contracts for tuil.



## Overview [#overview]

Core runtime, lifecycle, capability, command, semantic, and terminal contracts for tuil.

`@mwillbanks/tuil-core` is independently installable and also participates in the
umbrella `@mwillbanks/tuil` runtime where applicable.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @mwillbanks/tuil-core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @mwillbanks/tuil-core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @mwillbanks/tuil-core
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @mwillbanks/tuil-core
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## How it operates [#how-it-operates]

Core owns the framework-neutral contracts used by every adapter: lifecycle stages, services, commands, terminal capabilities, semantic metadata, disposables, and render-mode resolution.

<Mermaid
  chart="flowchart LR
  S0[&#x22;configuration&#x22;]
  S1[&#x22;initialization&#x22;]
  S2[&#x22;mount&#x22;]
  S3[&#x22;ready&#x22;]
  S4[&#x22;stop&#x22;]
  S5[&#x22;disposal&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3
  S3 --> S4
  S4 --> S5"
/>

## API [#api]

| API                                                                                                       | Signature                                  | Description                                      |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------ |
| [`AppLifecycleState`](/tuil/docs/reference/packages/core/api/app-lifecycle-state)                              | `type AppLifecycleState`                   | Public type AppLifecycleState.                   |
| [`ColorDepth`](/tuil/docs/reference/packages/core/api/color-depth)                                             | `type ColorDepth`                          | Public type ColorDepth.                          |
| [`Command`](/tuil/docs/reference/packages/core/api/command)                                                    | `interface Command`                        | Public interface Command.                        |
| [`CommandContext`](/tuil/docs/reference/packages/core/api/command-context)                                     | `interface CommandContext`                 | Public interface CommandContext.                 |
| [`CommandExecution`](/tuil/docs/reference/packages/core/api/command-execution)                                 | `interface CommandExecution`               | Public interface CommandExecution.               |
| [`CommandRegistry`](/tuil/docs/reference/packages/core/api/command-registry)                                   | `class CommandRegistry`                    | Public class CommandRegistry.                    |
| [`CommandRegistryChange`](/tuil/docs/reference/packages/core/api/command-registry-change)                      | `type CommandRegistryChange`               | Public type CommandRegistryChange.               |
| [`createGlobalSearchExpression`](/tuil/docs/reference/packages/core/api/create-global-search-expression)       | `function createGlobalSearchExpression`    | Public function createGlobalSearchExpression.    |
| [`defineCommand`](/tuil/docs/reference/packages/core/api/define-command)                                       | `function defineCommand`                   | Public function defineCommand.                   |
| [`defineService`](/tuil/docs/reference/packages/core/api/define-service)                                       | `function defineService`                   | Public function defineService.                   |
| [`deleteOnDispose`](/tuil/docs/reference/packages/core/api/delete-on-dispose)                                  | `function deleteOnDispose`                 | Public function deleteOnDispose.                 |
| [`detectTerminalCapabilities`](/tuil/docs/reference/packages/core/api/detect-terminal-capabilities)            | `function detectTerminalCapabilities`      | Public function detectTerminalCapabilities.      |
| [`Disposable`](/tuil/docs/reference/packages/core/api/disposable)                                              | `interface Disposable`                     | Public interface Disposable.                     |
| [`DisposableStack`](/tuil/docs/reference/packages/core/api/disposable-stack)                                   | `class DisposableStack`                    | Public class DisposableStack.                    |
| [`Disposer`](/tuil/docs/reference/packages/core/api/disposer)                                                  | `type Disposer`                            | Public type Disposer.                            |
| [`escapeTerminalControlCharacters`](/tuil/docs/reference/packages/core/api/escape-terminal-control-characters) | `function escapeTerminalControlCharacters` | Public function escapeTerminalControlCharacters. |
| [`hasTerminalControlCharacters`](/tuil/docs/reference/packages/core/api/has-terminal-control-characters)       | `function hasTerminalControlCharacters`    | Public function hasTerminalControlCharacters.    |
| [`isSafeRegularExpressionSource`](/tuil/docs/reference/packages/core/api/is-safe-regular-expression-source)    | `function isSafeRegularExpressionSource`   | Public function isSafeRegularExpressionSource.   |
| [`Lifecycle`](/tuil/docs/reference/packages/core/api/lifecycle)                                                | `class Lifecycle`                          | Public class Lifecycle.                          |
| [`RenderMode`](/tuil/docs/reference/packages/core/api/render-mode)                                             | `type RenderMode`                          | Public type RenderMode.                          |
| [`resolveRenderMode`](/tuil/docs/reference/packages/core/api/resolve-render-mode)                              | `function resolveRenderMode`               | Public function resolveRenderMode.               |
| [`resolveTerminalViewport`](/tuil/docs/reference/packages/core/api/resolve-terminal-viewport)                  | `function resolveTerminalViewport`         | Public function resolveTerminalViewport.         |
| [`SemanticMetadata`](/tuil/docs/reference/packages/core/api/semantic-metadata)                                 | `interface SemanticMetadata`               | Public interface SemanticMetadata.               |
| [`SemanticRole`](/tuil/docs/reference/packages/core/api/semantic-role)                                         | `type SemanticRole`                        | Public type SemanticRole.                        |
| [`ServiceContainer`](/tuil/docs/reference/packages/core/api/service-container)                                 | `class ServiceContainer`                   | Public class ServiceContainer.                   |
| [`ServiceDefinition`](/tuil/docs/reference/packages/core/api/service-definition)                               | `interface ServiceDefinition`              | Public interface ServiceDefinition.              |
| [`ServiceFactoryContext`](/tuil/docs/reference/packages/core/api/service-factory-context)                      | `interface ServiceFactoryContext`          | Public interface ServiceFactoryContext.          |
| [`ServiceMap`](/tuil/docs/reference/packages/core/api/service-map)                                             | `type ServiceMap`                          | Public type ServiceMap.                          |
| [`sliceTerminalText`](/tuil/docs/reference/packages/core/api/slice-terminal-text)                              | `function sliceTerminalText`               | Public function sliceTerminalText.               |
| [`TerminalBounds`](/tuil/docs/reference/packages/core/api/terminal-bounds)                                     | `interface TerminalBounds`                 | Public interface TerminalBounds.                 |
| [`TerminalCapabilities`](/tuil/docs/reference/packages/core/api/terminal-capabilities)                         | `interface TerminalCapabilities`           | Public interface TerminalCapabilities.           |
| [`TerminalCapabilityInput`](/tuil/docs/reference/packages/core/api/terminal-capability-input)                  | `interface TerminalCapabilityInput`        | Public interface TerminalCapabilityInput.        |
| [`TerminalInputProbe`](/tuil/docs/reference/packages/core/api/terminal-input-probe)                            | `interface TerminalInputProbe`             | Public interface TerminalInputProbe.             |
| [`TerminalOutputProbe`](/tuil/docs/reference/packages/core/api/terminal-output-probe)                          | `interface TerminalOutputProbe`            | Public interface TerminalOutputProbe.            |
| [`TerminalPlatform`](/tuil/docs/reference/packages/core/api/terminal-platform)                                 | `type TerminalPlatform`                    | Public type TerminalPlatform.                    |
| [`terminalTextWidth`](/tuil/docs/reference/packages/core/api/terminal-text-width)                              | `function terminalTextWidth`               | Public function terminalTextWidth.               |
| [`TerminalViewport`](/tuil/docs/reference/packages/core/api/terminal-viewport)                                 | `type TerminalViewport`                    | Public type TerminalViewport.                    |
| [`terminalViewportBreakpoints`](/tuil/docs/reference/packages/core/api/terminal-viewport-breakpoints)          | `constant terminalViewportBreakpoints`     | Public constant terminalViewportBreakpoints.     |
| [`toDisposable`](/tuil/docs/reference/packages/core/api/to-disposable)                                         | `function toDisposable`                    | Public function toDisposable.                    |
| [`truncateTerminalText`](/tuil/docs/reference/packages/core/api/truncate-terminal-text)                        | `function truncateTerminalText`            | Public function truncateTerminalText.            |
| [`wrapTerminalText`](/tuil/docs/reference/packages/core/api/wrap-terminal-text)                                | `function wrapTerminalText`                | Public function wrapTerminalText.                |

## Events and lifecycle [#events-and-lifecycle]

Core defines lifecycle state but does not own the event transport. The umbrella runtime projects lifecycle transitions onto `app:*` events.

All subscriptions and registrations return a disposer or belong to an owning
runtime that disposes them in reverse order.

## Example [#example]

```tsx
import { Lifecycle } from "@mwillbanks/tuil-core";

const lifecycle = new Lifecycle();
await lifecycle.transition("initializing");
```

## Related [#related]

* [Package architecture](/tuil/docs/concepts/packages)
* [Events](/tuil/docs/concepts/events)
* [Testing](/tuil/docs/guides/testing)