hypit/docs/guide/develop.md

title, description

title	description
Development Guide	Getting started with Narratage development.

Development Guide

Prerequisites

Tool	Version	Required for
Node.js	22+	everything
pnpm	10.33.x	workspace management; selected by the root packageManager field
Python	3.10–3.13	WhisperX and OpenCV local services
uv	latest	Python environment management
ffmpeg / ffprobe	recent stable	media processing
Chrome / Chromium	managed by HyperFrames	local HyperFrames rendering

Node.js and pnpm are the only hard requirements. The rest are needed only for live Builds.

Daily workflow

corepack enable
pnpm install --frozen-lockfile # after pulling or changing dependencies
pnpm check            # TypeScript type-check
pnpm test             # full test suite

Command	What it runs
pnpm check	tsc -p tsconfig.json --noEmit
pnpm test	package, service-adapter and repository-boundary tests through Node's test runner

See Testing for environment-gated tests and test patterns.

Repository layout

narratage/
├── packages/              86 workspace packages
├── spec/                  16 normative specification documents
├── docs/                  VitePress documentation site
├── examples/              runnable example sources
├── services/              Python services (whisperx, image-opencv)
├── tools/                 boundary tests and build scripts
├── package.json           root workspace manifest
├── pnpm-workspace.yaml    workspace: [packages/*]
└── tsconfig.json          TypeScript config

Guide contents

Guide	Topic
Package architecture	The five layers, dependency rules, package anatomy, facets
Adding an author package	Step-by-step: new component, Surface, activation
Adding a Provider	Step-by-step: new Endpoint adapter
Runtime Profile	JSON and TypeScript configuration, diagnostics, Build archive
Component playground	Previewing one visual component without a Build
Local services	WhisperX and OpenCV setup
Testing	Test runner, patterns, examples, boundary tests
Conventions	Naming, module boundaries, wire data, TypeScript config