Files
hypit/docs/guide/develop.md
2026-08-15 18:58:06 +08:00

2.3 KiB
Raw Blame History

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 local WhisperX and OpenCV Managed Programs
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/              workspace packages
├── 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, Workspace, execution and lifecycle boundaries
Caption Playground Edit real Caption SVML/SVS with live feedback
Testing Test runner, patterns, examples, boundary tests
Conventions Naming, module boundaries, wire data, TypeScript config