type

Knowledge Pack

title

CoreTS Framework

description

CoreTS — the TypeScript implementation of the Core framework for Lethean frontend applications

author

Mistral Vibe

version

1.0.0

created

2026-06-17 14:35:00 UTC

CoreTS knowledge pack

Official site: CoreTS documentation is part of the unified dappco.re site

CoreTS is the TypeScript implementation of the Core framework, running on Deno. It serves three roles in the polyglot ecosystem.

Overview

From the CoreTS RFC (plans/code/core/ts/RFC.md):

CoreTS is the TypeScript implementation of the Core framework, running on Deno. It serves three roles:

CoreDeno sidecar — sandboxed runtime managed by CoreGO, providing module loading, I/O fortress, and dev toolchain
Browser runtime — Web Components, WASM interop, and the client-side application shell
Standalone CLI — TypeScript-native commands and tools that don't need Go

Why Deno, not Node

Property	Node	Deno
Permissions	Everything allowed	Deny by default
Module loading	npm, node_modules	URL imports, import maps
TypeScript	Needs build step	Native
Security	Trust-based	Capability-based
Single binary	No	Yes

Key insight: Deno's permission model IS the I/O fortress. A module requesting access outside its declared paths is denied at the runtime level — no wrapper needed.

The polyglot stack

CoreGO  (Go)         — framework backbone, lifecycle, I/O, services
CoreTS  (TypeScript)  — browser runtime, module sandbox, dev toolchain
CorePHP (PHP)         — web platform, multi-tenant monolith

Each language gets first-class status. CoreGO is the host process. CoreTS runs as a sidecar or standalone. CorePHP runs as a web server. All share the same conventions, IPC patterns, and i18n format.

Repository details

Repository: github.com/dappcore/ts (also dappco.re/ts)
Runtime: Deno (nodeModulesDir: none; the only npm imports are @grpc/grpc-js and @grpc/proto-loader)
Components: native custom elements — no React, no Lit (see src/components.ts)
Module system: ES Modules
Build step: none — TypeScript runs natively in Deno
Sidecar: CoreDeno (managed by CoreGO)
Go shim: dappco.re/go/ts in go/ (covered by this pack's CATALOG.md)

Source of truth

Primary spec: plans/code/core/ts/RFC.md
In-repo spec: RFC.md
Implementation: core/ts/
Agent guide: core/ts/AGENTS.md
Catalog: plans/code/core/ts/RFC.catalog.md
Pack index: INDEX.md — areas: library/, sidecar/, proto/, go-shim/

Architecture

CoreDeno sidecar (managed by CoreGO)

┌─────────────────────────────────────────────┐
│              WebView2 (Browser)             │
│  ┌───────────┐  ┌──────────┐  ┌──────────┐ │
│  │  App Shell │  │ Web Comp │  │ go-html  │ │
│  │  (CoreTS)  │  │ (modules)│  │  WASM    │ │
│  └─────┬─────┘  └────┬─────┘  └────┬─────┘ │
│        └──────┬───────┘             │       │
│               │ fetch/WS            │       │
└───────────────┼─────────────────────┼───────┘
                │                     │
┌───────────────┼─────────────────────┼───────┐
│         CoreDeno (Deno sidecar)     │       │
│  ┌────────────┴──────────┐    ┌─────┴─────┐ │
│  │  Module Loader        │    │ WC        │ │
│  │  + Permission Gates   │    │ Codegen   │ │
│  └────────────┬──────────┘    └─────┬─────┘ │
│                │                     │       │
│  ┌──────────────┴─────────────────────┴───────┐
│  │                 Deno Runtime                 │
│  │  (single binary, sandboxed permissions)        │
│  └─────────────────────────────────────────────┘
└─────────────────────────────────────────────────┘

The sidecar runs with a minimal permission set: {"--allow-env", "--allow-net=..."}. All other access is explicitly denied.

Lifecycle

Go spawns Deno as a managed child process at app startup:

Auto-restart on crash
SIGTERM on app shutdown
Health monitoring via gRPC ping

Communication

Channel: Unix domain socket at $XDG_RUNTIME_DIR/core/deno.sock
Protocol: gRPC (proto definitions shared between Go and TS)
Direction: Bidirectional
- Deno → Go: I/O requests gated by permissions
- Go → Deno: Module lifecycle events, re-render triggers

Both sockets are owner-only. The Go listener creates its socket directory with 0700 and its Unix socket with 0600; the Deno sidecar mirrors those permissions for its JSON-RPC socket.

JSON-RPC frames on the Deno socket are newline-delimited and capped to a bounded size to prevent untrusted peers from forcing unbounded buffering.

Three roles

1. Module loader + sandbox

Reads .core/view.yaml manifests, loads modules with per-module permission flags:

# .core/view.yaml
permissions:
  read: ["./photos/"]
  net: []
  run: []

Module identity is mandatory at the Deno boundary. Blank or whitespace-only module codes and entry points are rejected before a Worker is created.

Local module isolation checks walk the imported module graph and reject any local specifier that resolves outside the entry-point directory, including new URL("...", import.meta.url) patterns used for dynamic local imports.

CoreDeno translates to Deno flags:

deno run --allow-read=./photos/ --deny-net --deny-run module.ts

Each module runs in a Deno isolate. Cross-module communication goes through the IPC layer, not direct imports.

2. I/O fortress gateway

All file/network/process I/O from modules routes through Deno's permission gates before reaching Go via gRPC:

Module requests fs.read("/etc/passwd")
  → Deno permission check: "/etc/passwd" not in allowed paths
  → DENIED — Go never sees the request

This is the same SASE containment model as go-io's sandbox — the CWD at launch becomes the immutable root boundary.

Process ownership is also enforced at the gRPC layer: ProcessStop must be called with the owning module_code, and the server rejects anonymous stop requests.

3. Build/dev toolchain

TypeScript compilation — native in Deno, no build step
Module resolution — import maps, URL imports
Dev server — HMR (Hot Module Replacement) for live development
Asset serving — serves compiled bundles in production
Replaces Node/npm entirely

Browser runtime

Web Components

CoreTS provides client-side Web Component registration and lifecycle with native custom elements (src/components.ts):

class PhotoGrid extends HTMLElement {
  #shadow: ShadowRoot;

  constructor() {
    super();
    // Component initialization
  }

  connectedCallback() {
    // Component mounted to DOM
  }
}

customElements.define('photo-grid', PhotoGrid);

The component base binds to the platform's HTMLElement when present and falls back to a minimal base class otherwise, so the same module loads in Deno tests and in the browser. Registration is guarded — a tag already defined is not redefined.

Core components

1. Runtime (Deno)

No Node.js — Pure Deno runtime
ES Modules — Native ES module support
TypeScript — First-class TypeScript support
Permissions — Fine-grained permission system

2. Library (`src/`)

Module	Purpose
`components.ts`	Custom-element base + registration (no framework)
`layout.ts`	`<core-layout>` — HLCRF-style layout element, slots `H`/`L`/`C`/`R`/`F`, default variant `HCF`
`result.ts`	`CoreOk`/`CoreErr` — the TS mirror of `core.Result`
`i18n.ts`, `router.ts`, `storage.ts`, `events.ts`	Translations, routing, store bridge, event bridge
`crypto.ts`, `wasm.ts`, `openapi.ts`, `electron.ts`, `nat.ts`, `p2p.ts`	Shared-secret bridge, WASM interop, OpenAPI client types, Electron shim, peer plumbing

Full module map: library/.

3. Go integration

Protobuf — contracts in proto/ (CoreService, DenoService, GoService)
gRPC — Deno loads the .proto at runtime via @grpc/proto-loader; Go uses generated stubs
Go shim — dappco.re/go/ts manages the sidecar process and serves CoreService (go-shim/)

How-tos

1. Creating a module

Create a .core/view.yaml manifest:

# .core/view.yaml
module: photo-gallery
entry: ./src/photo-gallery.ts
permissions:
  read: ["./photos/"]
  net: []
  run: []

2. Importing modules

Use URL imports or import maps:

// Direct URL import
import { PhotoGrid } from "https://dappco.re/ts/photo-gallery/src/photo-grid.ts";

// Or via import map
import { PhotoGrid } from "photo-grid";

3. Running with permissions

# Deno runs with explicit permissions
deno run --allow-read=./photos/ --deny-net --deny-run module.ts

# CoreDeno manages these automatically from .core/view.yaml

4. Creating Web Components

class MyElement extends HTMLElement {
  connectedCallback() {
    this.textContent = "Hello, CoreTS!";
  }
}

if (!customElements.get("my-element")) {
  customElements.define("my-element", MyElement);
}

Getting started

For agents

Read the RFC: plans/code/core/ts/RFC.md
Browse catalog: plans/code/core/ts/RFC.catalog.md
Explore code: ls core/ts/

For developers

Clone the repo: git clone github.com/dappcore/ts
Install Deno: curl -fsSL https://deno.land/x/install/install.sh | sh
Run the TS tests: deno test (root and runtime/ have their own deno.json)
Build/test the Go shim: cd go && go test ./... -count=1

Quick reference

Module permissions

Permission	Deno Flag	Purpose
`read`	`--allow-read=./path/`	File system read access
`write`	`--allow-write=./path/`	File system write access
`net`	`--allow-net=host:port`	Network access
`run`	`--allow-run`	Process execution
`env`	`--allow-env`	Environment variables

CoreDeno communication

Aspect	Details
Socket	`$XDG_RUNTIME_DIR/core/deno.sock`
Protocol	gRPC
Direction	Bidirectional
Permissions	`0700` (directory), `0600` (socket)

Web Component lifecycle

Method	When called	Purpose
`constructor()`	Element created	Initialise component
`connectedCallback()`	Added to DOM	Setup DOM, start rendering
`disconnectedCallback()`	Removed from DOM	Clean up resources
`attributeChangedCallback()`	Attribute changed	React to attribute changes

Use cases

When to use CoreTS

Frontend applications — web-based UIs
Desktop app frontends — use with CoreGUI for Wails apps
Type-safe APIs — protobuf/gRPC with Go backends
Sandboxed modules — use CoreDeno for secure module loading
Modern web apps — Deno + TypeScript + Web Components

When not to use CoreTS

Node.js environments — use Deno, not Node
Server-only applications — use CoreGO for backend services
jQuery legacy code — CoreTS uses modern Web Components
Backend services — use CoreGo instead
CLI tools — use CoreCLI instead

Agent tips

Always check the RFC — plans/code/core/ts/RFC.md is the source of truth
Deno, not Node — CoreTS uses Deno runtime with capability-based security
Native custom elements — no React, no Lit; extend HTMLElement via src/components.ts
Permissions are explicit — every module must declare its permissions in .core/view.yaml
URL imports — use direct URL imports or import maps, not npm (grpc-js is the one exception)
TypeScript native — no build step needed for TypeScript
Sandboxed by default — all modules run in Workers with explicit permissions
gRPC communication — all I/O goes through the CoreDeno sidecar
Module identity is mandatory — blank module codes are rejected before a Worker starts

Learning resources

CoreTS RFC (plans/code/core/ts/RFC.md) — Primary specification
CoreTS Catalog (plans/code/core/ts/RFC.catalog.md) — Package catalog
Deno Documentation — Runtime documentation
MDN: Web Components — Custom elements reference

Related knowledge packs

CoreGo — Core Go framework (backend)
CoreGUI — GUI framework (Wails integration)
CorePlay — STIM software-preservation runtime
CoreCLI — CLI framework
CorePHP — PHP framework

Maintenance

This knowledge pack is maintained by Mistral Vibe. Updates triggered by:

Changes to plans/code/core/ts/
Changes to core/ts/ repository
New frontend patterns
Deno version updates

Knowledge Pack v1.0.0 Created: 2026-06-17T14:35:00Z Author: Mistral Vibe Source: Lethean CoreTS Framework

FilesExpand file tree

README.md

Latest commit

History