mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
## What PR 3/17 of the catalog system rollout. Introduces the registry resolver/installer abstraction. No UX change — `init --template` still works identically. Stacks on #253. **New module: `packages/cli/src/registry/`** - `remote.ts` — fetches manifests (`registry.json`, `registry-item.json`) and item files from a GitHub-hosted registry. 24h cache on manifests; item files stream straight to `destDir` - `resolver.ts` — `listRegistryItems`, `loadAllItems` (parallel fetch for picker UX), `resolveItem` (single-item fetch with `Available:` error) - `installer.ts` — `assertSafeTarget` (runtime path-traversal guard) + `installItem` (parallel file download with up-front validation; all-or-nothing semantics) - `index.ts` — barrel **Registry content:** - `registry/registry.json` — top-level manifest in PR 1's `RegistryManifest` shape. 8 examples - `registry/examples/<id>/registry-item.json` — per-item manifest for each existing example, generated from legacy `templates.json` + HTML data-attribute probing - `registry/examples/templates.json` — **deleted**, replaced by the above **Compat layer:** - `packages/cli/src/templates/{remote,generators}.ts` — thin shims that delegate to `../registry/`, keeping `init.ts`'s existing imports stable. `init.ts` doesn't move to the new API until PR 5 where it's part of a larger UX pass **Tooling:** - `scripts/generate-registry-items.ts` — idempotent one-off generator for this PR, kept in-repo for future example additions (`--only <name>` flag) Design doc: [Hyperframes Catalog System](https://www.notion.so/heygen/Hyperframes-Catalog-System-Design-Plan-341449792c69813f899dcd53b4c0383a). Tracker entry in local `hyperframes-catalog-plan.md`. ## Why Every future PR (`hyperframes add`, seed blocks, seed components, custom registries) otherwise has to keep piling onto the ad-hoc fetch + `cpSync` pattern in the old `fetchRemoteTemplate`. The new module is the single place that understands the registry wire format and file layout. **This is also where PR 1's schema comes alive.** ## How ### Scope-trimmed from the plan - **No transitive dependency resolution yet.** Examples have no deps today. `resolveItem` doesn't walk `registryDependencies`; PR 5 adds that when blocks/components need it. - **No ajv schema validation yet.** TS types + runtime path-traversal guard are the only safety nets. Full JSON-Schema validation lands when the registry starts accepting third-party content (PR 14 / custom registries). - **init.ts refactor deferred to PR 5.** Compat shims keep this PR small and reviewable. PR 5 rewrites init alongside adding the `add` command. ### Safety - `assertSafeTarget` rejects absolute paths, `..` segments, Windows drive letters, and any target that `path.resolve` shows to escape `destDir`. Mirrors the PR 1 schema `pattern`/`not.anyOf` on `target`, but runs at install-time so a registry that bypasses schema validation still can't write outside the project - Up-front validation in `installItem` means a malformed item fails **before** any file is written. Atomic-ish semantics: all files land or none do ### Caching - 24h manifest cache lives at `~/.hyperframes/cache/` per existing convention, but now keyed by `<baseUrl>__<kind>__<name>.json` so PR 14 custom registries can coexist ## Test plan - [x] `bun run test` in `packages/cli`: **70 passed** (was 57 on #253, +13). Same 4 pre-existing failures (SRT/VTT whisper normalizer + `lintProject` clean-project test) — identical to main. No regressions - [x] **Resolver unit tests (8):** filter by type, parallel load with fail-safe, resolve-by-name with `Available:` error message, unreachable-registry handling - [x] **Installer unit tests (5):** accepts simple relative paths, rejects `..` segments, rejects Unix absolute paths, rejects Windows drive letters, permits `.` and dotfile-like names - [x] **Smoke test**: `hyperframes init /tmp/x --template blank` (bundled code path, unchanged) works end-to-end - [x] `bunx oxfmt --check` + `bunx oxlint`: clean - [x] Pre-commit typecheck (core + studio): clean. CLI typecheck has 2 pre-existing errors (`render.ts`, `studioServer.ts` — unrelated `"mov"` format issue on main) - [ ] **Smoke test remote fetch (`--template warm-grain`)** — verifiable only post-merge; registry paths live on `main` after this PR lands ## Breaking / migration **No end-user-visible UX change.** `init --template <name>` still works the same way. Internally, `templates.json` is gone and the CLI now reads `registry.json` + `registry-item.json` per example. Installed CLIs on old versions (`hyperframes@0.1.0`–`0.3.0`) already broke at PR 2 merge (see #253 rollout note). The next CLI release after this lands (`0.3.1`+) is the full fix. ## Commits 1. `generate-registry-items.ts` + generated manifests + deleted `templates.json` 2. Resolver + installer + compat shims 3. Unit tests (All squashed into one commit on this branch; see `git log feat/registry-resolver ^refactor/registry-examples-dir`.) ## Stacks on #253 — base branch. When #253 merges, this rebases onto `main`. ## Next in stack PR 4 — `feat(cli)!: rename --template to --example`. Single clean cut, no alias. Tiny PR (~150 lines) that mostly updates `init.ts`'s argument schema, help text, and docs. Depends on this PR so the new flag name can be applied against the refactored code path. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
190 lines
4.2 KiB
TypeScript
190 lines
4.2 KiB
TypeScript
// Types
|
|
export type {
|
|
ExecutionMode,
|
|
Orientation,
|
|
Asset,
|
|
TimelineElement,
|
|
TimelineElementBase,
|
|
TimelineMediaElement,
|
|
TimelineTextElement,
|
|
TimelineCompositionElement,
|
|
TimelineElementType,
|
|
MediaElementType,
|
|
CanvasResolution,
|
|
MediaFile,
|
|
CompositionAPI,
|
|
PlayerAPI,
|
|
AddElementData,
|
|
ValidationResult,
|
|
CompositionAsset,
|
|
Keyframe,
|
|
KeyframeProperties,
|
|
ElementKeyframes,
|
|
StageZoom,
|
|
StageZoomKeyframe,
|
|
CompositionVariableType,
|
|
CompositionVariableBase,
|
|
StringVariable,
|
|
NumberVariable,
|
|
ColorVariable,
|
|
BooleanVariable,
|
|
EnumVariable,
|
|
CompositionVariable,
|
|
CompositionSpec,
|
|
WaveformData,
|
|
} from "./core.types";
|
|
|
|
export {
|
|
CANVAS_DIMENSIONS,
|
|
TIMELINE_COLORS,
|
|
DEFAULT_DURATIONS,
|
|
isTextElement,
|
|
isMediaElement,
|
|
isCompositionElement,
|
|
getDefaultStageZoom,
|
|
isStringVariable,
|
|
isNumberVariable,
|
|
isColorVariable,
|
|
isBooleanVariable,
|
|
isEnumVariable,
|
|
} from "./core.types";
|
|
|
|
// Templates
|
|
export { generateBaseHtml, getStageStyles } from "./templates/base";
|
|
export {
|
|
GSAP_CDN,
|
|
BASE_STYLES,
|
|
ELEMENT_BASE_STYLES,
|
|
MEDIA_STYLES,
|
|
TEXT_STYLES,
|
|
ZOOM_CONTAINER_STYLES,
|
|
} from "./templates/constants";
|
|
|
|
// Parsers
|
|
export type { GsapAnimation, GsapMethod, ParsedGsap } from "./parsers/gsapParser";
|
|
|
|
export {
|
|
parseGsapScript,
|
|
serializeGsapAnimations,
|
|
updateAnimationInScript,
|
|
addAnimationToScript,
|
|
removeAnimationFromScript,
|
|
getAnimationsForElement,
|
|
validateCompositionGsap,
|
|
keyframesToGsapAnimations,
|
|
gsapAnimationsToKeyframes,
|
|
SUPPORTED_PROPS,
|
|
SUPPORTED_EASES,
|
|
} from "./parsers/gsapParser";
|
|
|
|
export type { ParsedHtml, CompositionMetadata } from "./parsers/htmlParser";
|
|
|
|
export {
|
|
parseHtml,
|
|
updateElementInHtml,
|
|
addElementToHtml,
|
|
removeElementFromHtml,
|
|
validateCompositionHtml,
|
|
extractCompositionMetadata,
|
|
} from "./parsers/htmlParser";
|
|
|
|
// Generators
|
|
export type { SerializeOptions } from "./generators/hyperframes";
|
|
|
|
export {
|
|
generateHyperframesHtml,
|
|
generateGsapTimelineScript,
|
|
generateHyperframesStyles,
|
|
} from "./generators/hyperframes";
|
|
|
|
// Compiler (timing only — browser-safe, no linkedom/esbuild)
|
|
export type {
|
|
UnresolvedElement,
|
|
ResolvedDuration,
|
|
ResolvedMediaElement,
|
|
CompilationResult,
|
|
} from "./compiler/timingCompiler";
|
|
|
|
export {
|
|
compileTimingAttrs,
|
|
injectDurations,
|
|
extractResolvedMedia,
|
|
clampDurations,
|
|
} from "./compiler/timingCompiler";
|
|
|
|
// Lint
|
|
export type {
|
|
HyperframeLintSeverity,
|
|
HyperframeLintFinding,
|
|
HyperframeLintResult,
|
|
HyperframeLinterOptions,
|
|
} from "./lint/types";
|
|
export { lintHyperframeHtml } from "./lint/hyperframeLinter";
|
|
export {
|
|
rewriteAssetPaths,
|
|
rewriteAssetPath,
|
|
rewriteCssAssetUrls,
|
|
} from "./compiler/rewriteSubCompPaths";
|
|
|
|
// Inline scripts
|
|
export {
|
|
HYPERFRAME_RUNTIME_ARTIFACTS,
|
|
HYPERFRAME_RUNTIME_CONTRACT,
|
|
loadHyperframeRuntimeSource,
|
|
type HyperframeRuntimeContract,
|
|
} from "./inline-scripts/hyperframe";
|
|
export {
|
|
HYPERFRAME_RUNTIME_GLOBALS,
|
|
HYPERFRAME_BRIDGE_SOURCES,
|
|
HYPERFRAME_CONTROL_ACTIONS,
|
|
type HyperframeControlAction,
|
|
} from "./inline-scripts/runtimeContract";
|
|
export {
|
|
buildHyperframesRuntimeScript,
|
|
type HyperframesRuntimeBuildOptions,
|
|
} from "./inline-scripts/hyperframesRuntime.engine";
|
|
export {
|
|
MEDIA_VISUAL_STYLE_PROPERTIES,
|
|
copyMediaVisualStyles,
|
|
quantizeTimeToFrame,
|
|
type MediaVisualStyleProperty,
|
|
} from "./inline-scripts/parityContract";
|
|
export type {
|
|
HyperframePickerApi,
|
|
HyperframePickerBoundingBox,
|
|
HyperframePickerElementInfo,
|
|
} from "./inline-scripts/pickerApi";
|
|
|
|
// Frame adapters
|
|
export type { FrameAdapter, FrameAdapterContext } from "./adapters/types";
|
|
export type { GSAPTimelineLike, CreateGSAPFrameAdapterOptions } from "./adapters/gsap";
|
|
export { createGSAPFrameAdapter } from "./adapters/gsap";
|
|
|
|
// Text measurement
|
|
export { fitTextFontSize } from "./text/index.js";
|
|
export type { FitTextOptions, FitTextResult } from "./text/index.js";
|
|
|
|
// Registry
|
|
export type {
|
|
ItemType,
|
|
FileType,
|
|
FileTarget,
|
|
RegistryItemDimensions,
|
|
RegistryItemPreview,
|
|
RegistryItem,
|
|
ExampleItem,
|
|
BlockItem,
|
|
ComponentItem,
|
|
RegistryManifestEntry,
|
|
RegistryManifest,
|
|
} from "./registry/index.js";
|
|
|
|
export {
|
|
ITEM_TYPES,
|
|
FILE_TYPES,
|
|
ITEM_TYPE_DIRS,
|
|
isExampleItem,
|
|
isBlockItem,
|
|
isComponentItem,
|
|
} from "./registry/index.js";
|