# @tempots/core

> Core types and utilities for multi-context Tempo framework

Latest version **3.4.0** (published 2026-11-19) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @tempots/core
pnpm add @tempots/core
yarn add @tempots/core
bun add @tempots/core
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.4.0 |
| Published | 2026-11-19 |
| First published | 2025-11-11 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 148.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 15 |
| Author | Franco Ponticelli |
| Maintainers | fponticelli |
| Keywords | tempo, tempots, framework, core, reactive, signals |

## Links

- npm: https://www.npmjs.com/package/@tempots/core
- Repository: https://github.com/fponticelli/tempots
- Issues: https://github.com/fponticelli/tempots/issues
- npm.io page: https://npm.io/package/@tempots/core

## Alternatives

- [@sveltejs/kit](https://npm.io/package/@sveltejs/kit.md) — 2.2M weekly downloads
- [@atlaskit/theme](https://npm.io/package/@atlaskit/theme.md) — 402.0K weekly downloads
- [@tangle-network/brand](https://npm.io/package/@tangle-network/brand.md) — 10.0K weekly downloads
- [seneca](https://npm.io/package/seneca.md) — 7.4K weekly downloads
- [@bsb/base](https://npm.io/package/@bsb/base.md) — 7.2K weekly downloads

## Recent versions

- 3.4.0 (latest) — 2026-11-19
- 3.3.0 — 2026-03-28
- 3.2.1 — 2026-03-22
- 3.2.0 — 2026-03-07
- 3.1.0 — 2026-03-04
- 3.0.1 — 2026-02-26
- 3.0.0 — 2026-02-19
- 2.1.1 — 2026-02-16
- 2.1.0 — 2026-02-16
- 2.0.5 — 2026-01-21
- 2.0.4 — 2026-01-21
- 2.0.3 — 2026-01-20
- 2.0.2 — 2026-01-20
- 2.0.0 — 2025-11-18
- 1.2.0 — 2025-11-18
- … 2 more at https://npm.io/package/@tempots/core/versions

## README

# @tempots/core

[![npm version](https://img.shields.io/npm/v/@tempots/core.svg)](https://www.npmjs.com/package/@tempots/core)
[![license](https://img.shields.io/npm/l/@tempots/core.svg)](https://github.com/fponticelli/tempots/blob/main/LICENSE)
[![codecov](https://codecov.io/gh/fponticelli/tempots/branch/main/graph/badge.svg)](https://codecov.io/gh/fponticelli/tempots)
[![CI](https://github.com/fponticelli/tempots/workflows/CI/badge.svg)](https://github.com/fponticelli/tempots/actions)

Core types and utilities for multi-context Tempo framework.

## Overview

`@tempots/core` provides the foundational types and utilities that are shared across all Tempo rendering contexts (DOM, ThreeJS, Konva, PixiJS, etc.). This package enables a consistent programming model across different rendering targets while maintaining strong type safety.

## Installation

```bash
pnpm add @tempots/core
```

## Core Concepts

### Renderable

A `Renderable` is an object that can be rendered into a specific context. It has two properties:

- `type`: A symbol for runtime type checking
- `render(ctx)`: A method that renders content and returns a cleanup function

```typescript
import { Renderable, RenderContext, Clear } from '@tempots/core'

const MY_TYPE = Symbol('MY_RENDERABLE')

const myRenderable: Renderable<RenderContext, typeof MY_TYPE> = {
  type: MY_TYPE,
  render: (ctx) => {
    // Render logic here
    return (removeTree) => {
      // Cleanup logic here
    }
  }
}
```

### RenderContext

The base interface for all rendering contexts. Context-specific implementations (DOM, ThreeJS, etc.) extend this interface with their own methods.

```typescript
interface RenderContext {
  clear(removeTree: boolean): void
}
```

### HierarchicalContext

Extended interface for contexts that support hierarchical rendering with ordered children. Provides the `makeRef()` method for creating reference markers that preserve insertion points.

```typescript
interface HierarchicalContext extends RenderContext {
  makeRef(): this
}
```

### Clear

A function that cleans up rendered content. The `removeTree` parameter indicates whether to remove the entire tree or just event listeners and subscriptions.

```typescript
type Clear = (removeTree: boolean) => void
```

### TNode

A flexible type representing any content that can be rendered:

```typescript
type TNode<CTX extends RenderContext, TType extends symbol> =
  | Renderable<CTX, TType>
  | Value<string>
  | Value<number>
  | Value<boolean>
  | Signal<string | Nil>
  | Signal<number | Nil>
  | Signal<boolean | Nil>
  | undefined
  | null
  | Renderable<CTX, TType>[]
```

Signals containing `null` or `undefined` values render as empty text (equivalent to `''`).

### Value

Represents a value that can be either static or reactive (a Signal):

```typescript
type Value<T> = T | Signal<T>
```

## API

### createRenderable

Creates a renderable object from a render function and type symbol.

```typescript
import { createRenderable } from '@tempots/core'

const MY_TYPE = Symbol('MY_RENDERABLE')

const myComponent = createRenderable(MY_TYPE, (ctx) => {
  // Render logic
  return (removeTree) => {
    // Cleanup logic
  }
})
```

### makeProviderMark

Creates a unique symbol for dependency injection.

```typescript
import { makeProviderMark } from '@tempots/core'

interface UserService {
  getUser(id: string): Promise<User>
}

const USER_SERVICE = makeProviderMark<UserService>('UserService')
```

## Usage with Context-Specific Packages

This package is typically used indirectly through context-specific packages like `@tempots/dom`, `@tempots/three`, etc. Those packages provide higher-level APIs built on these core types.

### Example: DOM Context

```typescript
// In @tempots/dom
import { createRenderable, type Renderable } from '@tempots/core'
import type { DOMContext } from './dom-context'

export const DOM_RENDERABLE_TYPE = Symbol('DOM_RENDERABLE')
export type DOMRenderable = Renderable<DOMContext, typeof DOM_RENDERABLE_TYPE>

export function domRenderable(
  renderFn: (ctx: DOMContext) => Clear
): DOMRenderable {
  return createRenderable(DOM_RENDERABLE_TYPE, renderFn)
}
```

### Example: ThreeJS Context

```typescript
// In @tempots/three
import { createRenderable, type Renderable } from '@tempots/core'
import type { ThreeContext } from './three-context'

export const THREE_RENDERABLE_TYPE = Symbol('THREE_RENDERABLE')
export type ThreeRenderable = Renderable<ThreeContext, typeof THREE_RENDERABLE_TYPE>

export function threeRenderable(
  renderFn: (ctx: ThreeContext) => Clear
): ThreeRenderable {
  return createRenderable(THREE_RENDERABLE_TYPE, renderFn)
}
```

## Type Safety

The symbol-based branding system ensures compile-time type safety:

```typescript
// ✅ Valid: DOM renderable in DOM context
html.div(html.span('Hello'))

// ❌ Invalid: ThreeJS renderable in DOM context
html.div(mesh.box({ width: 1, height: 1, depth: 1 }))
// Type error: ThreeRenderable is not assignable to DOMNode
```

## License

Apache-2.0

## Contributing

See the main [Tempo repository](https://github.com/fponticelli/tempots) for contribution guidelines.

---
_Source: https://npm.io/package/@tempots/core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
