Files
hypit/docs/guide/develop.md
kashorin 80bcd3d8e1 feat: isolate caption authoring and close package dependencies
Replace the generic playground with a file-backed Caption Playground, separate source workspaces from installed package roots, and derive exact transitive Module providers in Node package locks.
2026-08-10 22:33:02 +08:00

64 lines
2.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: Development Guide
description: 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](./services.md) |
| 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
```bash
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](./testing.md) for environment-gated tests and test patterns.
## Repository layout
```text
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](./packages.md) | The five layers, dependency rules, package anatomy, facets |
| [Adding an author package](./author-packages.md) | Step-by-step: new component, Surface, activation |
| [Adding a Provider](./providers.md) | Step-by-step: new Endpoint adapter |
| [Runtime Profile](./runtime-profile.md) | JSON and TypeScript configuration, diagnostics, Build archive |
| [Caption Playground](./caption-playground.md) | Edit real Caption SVML/SVS with live feedback |
| [Local services](./services.md) | WhisperX and OpenCV setup |
| [Testing](./testing.md) | Test runner, patterns, examples, boundary tests |
| [Conventions](./conventions.md) | Naming, module boundaries, wire data, TypeScript config |