Files
hyperframes/packages/core/src/index.ts
T
Michael Wang 6f88be3941 fix(cli): escape control characters in project, page and registry text (#7913)
* fix(cli): text from projects, pages and registries prints control characters as visible escapes

catch-up, capture, figma component, timeline, keyframes, layout/inspect,
catalog and add printed strings that come from a project folder, a captured
web page or a registry manifest straight to the terminal. A crafted value
could move the cursor, rewrite earlier lines, set the window title or write
the clipboard. Those values now go through terminalText(), the same helper
lint, check and snapshot already use. The CLI's own colours stay, and --json
output is unchanged.

layout/inspect also keeps only well-formed issues with a known code from the
page, the way check already does, by reusing check's parseLayoutIssue. The
browser-script loader moves to its own module so layout and check can share
the parser without importing each other.

* test(cli): catch-up test names files with control characters only where the OS allows it

* fix(cli): import terminalText from core after main moved it

* fix(cli): escape layout banner and failure, top-level errors and installed paths; keep line breaks
2026-11-16 23:11:33 +00:00

499 lines
13 KiB
TypeScript

// Types
export type { PlaybackHeldBy, RuntimeTimelineClipIdentity } from "./runtime/types.js";
export type {
ExecutionMode,
Orientation,
Asset,
TimelineElement,
TimelineElementBase,
TimelineMediaElement,
TimelineTextElement,
TimelineCompositionElement,
TimelineElementType,
MediaElementType,
CanvasResolution,
Fps,
FpsInput,
FpsParseResult,
MediaFile,
CompositionAPI,
PlayerAPI,
AddElementData,
ValidationResult,
CompositionAsset,
Keyframe,
KeyframeProperties,
ElementKeyframes,
StageZoom,
StageZoomKeyframe,
CompositionVariableType,
CompositionVariableBase,
StringVariable,
NumberVariable,
ColorVariable,
BooleanVariable,
EnumVariable,
CompositionVariable,
CompositionSpec,
WaveformData,
OutputResolutionCompatibility,
OutputResolutionIssueKind,
} from "./core.types";
export type {
SlideshowManifest,
SlideRef,
SlideHotspot,
SlideSequence,
ResolvedSlide,
ResolvedSlideSequence,
ResolvedSlideshow,
} from "./slideshow/index.js";
export { parseSlideshowManifest, resolveSlideshow } from "./slideshow/index.js";
export type {
AuthoredTimingValue,
RawAuthoredTiming,
AuthoredTimingWindow,
} from "./runtime/authoredTiming.js";
export { resolveAuthoredTimingWindow } from "./runtime/authoredTiming.js";
export {
CANVAS_DIMENSIONS,
VALID_CANVAS_RESOLUTIONS,
normalizeResolutionFlag,
isAspectAgnosticResolutionAlias,
resolveResolutionFlagPair,
checkOutputResolutionCompatibility,
outputResolutionForSize,
suggestMatchingPreset,
parseFps,
parseFpsWithDefault,
toFps,
fpsToNumber,
fpsToFfmpegArg,
TIMELINE_COLORS,
DEFAULT_DURATIONS,
COMPOSITION_VARIABLE_TYPES,
isTextElement,
isMediaElement,
isCompositionElement,
getDefaultStageZoom,
} from "./core.types";
export { DISTRIBUTED_FPS, type DistributedFps, isDistributedFps } from "./distributedFps";
// 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 — GSAP helpers. The AST parser (parseGsapScriptAcorn and write ops)
// is browser-safe; mutation helpers are in gsapWriterAcorn.
export type { GsapAnimation, GsapMethod, ParsedGsap } from "@hyperframes/parsers";
export {
serializeGsapAnimations,
getAnimationsForElementId,
validateCompositionGsap,
keyframesToGsapAnimations,
gsapAnimationsToKeyframes,
} from "@hyperframes/parsers";
export type { ParsedHtml, CompositionMetadata } from "@hyperframes/parsers";
export {
parseHtml,
updateElementInHtml,
addElementToHtml,
removeElementFromHtml,
validateCompositionHtml,
extractCompositionMetadata,
} from "@hyperframes/parsers";
// 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";
// Timing resolver — shared pure resolver for word-anchored elastic timing (WS-C).
export type {
WordTiming,
ElementAnchor,
AuthoredTiming,
ResolvedTiming,
ResolveTimingsInput,
ResolveTimingsResult,
} from "./compiler/timingResolver";
export { resolveTimings } from "./compiler/timingResolver";
export {
compileTimingAttrs,
injectDurations,
extractResolvedMedia,
clampDurations,
shouldClampMediaDuration,
shouldClampResolvedMediaDuration,
MEDIA_DURATION_CLAMP_EPSILON_SECONDS,
} from "./compiler/timingCompiler";
export {
AUDIO_GROUP_RENDER_ID_ATTR,
MEDIA_RENDER_ID_ATTR,
assignMediaRenderIds,
} from "./compiler/mediaRenderIds";
export {
RENDER_FRAME_ID_PREFIX,
RENDER_FRAME_ID_SUFFIX,
renderFrameIdForRenderId,
} from "./runtime/renderFrameSibling";
// Lint moved to @hyperframes/lint. Import lint APIs from @hyperframes/lint
// directly, or via the back-compat stub at @hyperframes/core/lint. Not
// re-exported here — doing so would cycle core's main entry through the lint
// package (which imports core utilities back).
export {
rewriteAssetPaths,
rewriteAssetPath,
rewriteCssAssetUrls,
rewriteInlineStyleAssetUrls,
} from "./compiler/rewriteSubCompPaths";
export { CSS_URL_RE, isNonRelativeUrl, isPathInside } from "./compiler/assetPaths";
export { rewriteSrcsetUrls } from "./compiler/srcset";
export {
checkSubCompositionUsability,
type ParsableDocumentLike,
type SubCompositionValidity,
type SubCompositionValidityReason,
} from "./compiler/subCompositionValidity";
export { RUNTIME_BOOTSTRAP_ATTR, stripEmbeddedRuntimeScripts } from "./compiler/htmlDocument";
export { AUTHORED_SOURCE_BEGIN, AUTHORED_SOURCE_END } from "./compiler/compositionScoping";
export { COMPOSITION_SOURCE_URL } from "./compiler/scriptRuns";
export { queryByAttr } from "./utils/cssSelector";
export {
AUDIBLE_MEDIA_SELECTOR,
audibleVideoNeedsWebAudio,
isAudibleVideoElement,
} from "./audibleVideo";
export { decodeUrlPathVariants } from "./utils/urlPath";
export {
clearGifFramesBeforeNext,
gifClearsAfterLeavingFrameInPlace,
parseAnimatedGifMetadata,
type AnimatedGifMetadata,
} from "./media/gif";
export {
HF_COLOR_GRADING_ATTR,
HF_COLOR_GRADING_ADJUST_KEYS,
HF_COLOR_GRADING_ACTIVE_EFFECT_KEYS,
HF_COLOR_GRADING_ANIMATABLE_PROPERTIES,
HF_COLOR_GRADING_CANVAS_ID_PREFIX,
HF_COLOR_GRADING_COLOR_SPACE,
HF_COLOR_GRADING_CURVE_KEYS,
HF_COLOR_GRADING_DETAIL_KEYS,
HF_COLOR_GRADING_EFFECT_APPLY_DEFAULTS,
HF_COLOR_GRADING_EFFECT_KEYS,
HF_COLOR_GRADING_EFFECT_PRESETS,
HF_COLOR_GRADING_GRADE_PRESETS,
HF_COLOR_GRADING_HUE_CURVE_KEYS,
HF_COLOR_GRADING_LUT_KEYS,
HF_COLOR_GRADING_PALETTES,
HF_COLOR_GRADING_PRESETS,
HF_COLOR_GRADING_TOP_LEVEL_KEYS,
HF_COLOR_GRADING_WHEEL_KEYS,
getHfColorGradingCapabilities,
hasHfColorGradingAuthoredValues,
isHfColorGradingActive,
normalizeHfColorGrading,
normalizeHfColorGradingWithVariables,
resolveHfColorGradingVariables,
serializeHfColorGrading,
type HfColorGrading,
type HfColorGradingAdjust,
type HfColorGradingAdjustKey,
type HfColorGradingAnimatablePath,
type HfColorGradingActiveEffectKey,
type HfColorGradingDetailKey,
type HfColorGradingDetails,
type HfColorGradingEffectKey,
type HfColorGradingEffects,
type HfColorGradingLutRef,
type HfColorGradingPreset,
type HfColorGradingPresetId,
type HfColorGradingTarget,
type HfColorGradingVariableMap,
type HfColorGradingCapabilities,
type HfColorGradingCurveKey,
type HfColorGradingCurves,
type HfColorGradingHueCurveKey,
type HfColorGradingHueCurves,
type HfColorGradingHueRange,
type HfColorGradingSecondary,
type HfColorGradingSecondaryCorrection,
type HfColorGradingSoftRange,
type HfColorGradingTonalWheel,
type HfColorGradingWheelKey,
type HfColorGradingWheels,
type HfColorCurvePoint,
type HfHueCurvePoint,
type NormalizedHfColorGrading,
type NormalizedHfColorGradingCurves,
type NormalizedHfColorGradingHueCurves,
type NormalizedHfColorGradingSecondary,
type NormalizedHfColorGradingWheels,
type ResolvedHfColorGrading,
} from "./colorGrading";
export {
colorGroupOf,
effectiveColorGrading,
ensureColorGroupInertStyle,
HF_COLOR_GROUP_ATTR,
HF_COLOR_GROUP_TAG,
resolveColorGroupElement,
} from "./colorGroups";
export {
parseCubeLut,
CubeLutParseError,
type CubeLut3D,
type ParseCubeLutOptions,
} from "./colorLuts";
export { bakeHfColorGradingCube, type BakeHfColorGradingCubeOptions } from "./colorGradingBake";
export {
firstFrameColourArgs,
hdrToSdrToneMapFilter,
keyframeTransferArgs,
parseKeyframeTransfers,
readsKeyframeTransfers,
toneMapReferenceNits,
parseFirstFrameColour,
type ToneMapFrameColour,
type ToneMapSourceColour,
} from "./hdrToneMap";
export {
HEAVY_BITRATE,
HEAVY_PIXEL_SHARE,
PREVIEW_PROXY_BOX_PARAM,
PREVIEW_PROXY_LIGHT_PARAM,
PREVIEW_PROXY_PRIORITY_HEADER,
PREVIEW_PROXY_PROGRESS_HEADER,
PREVIEW_PROXY_RETRY_PARAM,
PREVIEW_PROXY_STILL_PARAM,
PREVIEW_QUALITY_LEVELS,
formatPreviewProxyBox,
isHeavyForPreview,
isPreviewQuality,
parsePreviewProxyBox,
quantizePreviewProxyBox,
scalePreviewProxyBox,
type PreviewProxyBox,
type PreviewQuality,
type PreviewSourceFacts,
} from "./previewProxyBox";
export type {
PausedVideoFrameProvider,
PausedVideoFrameRequest,
PausedVideoFrame,
} from "./runtime/pausedVideoFrames";
// 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 { getHyperframeRuntimeScript } from "./generated/runtime-inline";
export {
buildHyperframesRuntimeScript,
type HyperframesRuntimeBuildOptions,
} from "./inline-scripts/hyperframesRuntime.engine";
export {
MEDIA_VISUAL_STYLE_PROPERTIES,
copyMediaVisualStyles,
exportClipWindow,
quantizeSeekTime,
quantizeTimeToFrame,
type MediaVisualStyleProperty,
} from "./inline-scripts/parityContract";
export {
redactKnownPaths,
redactTelemetryString,
redactUrlQueryStrings,
} from "./telemetryRedaction";
export {
folderGone,
isProjectRootMissing,
isSafePath,
mkdirWithinProject,
ProjectRootMissingError,
realpath,
realProjectRoot,
resolveWithinProject,
} from "./safePath";
export { isCompositionFolder, isHyperframesProject, PROJECT_MARKER_FILES } from "./projectRule";
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";
export { formatRenderOutputTimestamp } from "./utils/renderOutputTimestamp.js";
// Runtime helpers (composition-side)
export { getVariables } from "./runtime/getVariables.js";
export { SCENE_CALLBACK_ERROR_PREFIX } from "./runtime/diagnostics.js";
export {
parseStartExpression,
parseNumeric,
type ReferenceExpression,
} from "./runtime/startExpression.js";
export {
COMPOSITION_CONTRACT_VERSION,
COMPOSITION_ATTRIBUTES,
CANONICAL_AUTHORED_TIMING_ATTRIBUTES,
DERIVED_TIMING_ATTRIBUTES,
LEGACY_TIMING_ATTRIBUTES,
readClipTiming,
writeClipTiming,
ClipTimingWriteError,
type ClipTiming,
type ClipTimingDiagnostic,
type ClipTimingDiagnosticCode,
type ClipTimingUpdate,
} from "./compositionContract.js";
// Also exposed via the ./runtime/start-resolver subpath. This root re-export
// additionally makes tsc EMIT dist/runtime/startResolver.js: src/runtime is
// excluded from the tsconfig include set, so runtime files only reach dist
// when an included module imports them — without this line the subpath's
// publishConfig entry points at a file the pack doesn't contain
// (verify:packed-manifests catches exactly that).
export { createRuntimeStartTimeResolver } from "./runtime/startResolver.js";
// Also exposed via the ./runtime/clip-window subpath; re-exported here for the same dist-emit reason.
export {
hasClipStarted,
isClipOnScreenAt,
isClipVisibleAt,
isInClipWindow,
} from "./runtime/clipWindow.js";
export { MEDIA_ELEMENT_LEAD_SECONDS, mediaElementTime } from "./runtime/mediaClock.js";
export {
normalizePlaybackRate,
normalizeRateSpec,
parseStrictFiniteTimingNumber,
readElementPlaybackRate,
readElementRateSpec,
readMediaStart,
resolveNaturalMediaTimelineDuration,
resolveNaturalMediaTimelineDurationFromValues,
} from "./runtime/playbackRate.js";
export { shiftRateLane, sourceTimeAt, timeAtSourceTime, type RateSpec } from "./speedRamp.js";
// Variable validation (CLI / tooling-side)
export {
validateVariables,
formatVariableValidationIssue,
type VariableValidationIssue,
} from "./runtime/validateVariables.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";
export {
canaryBucket,
evaluateCanary,
parseCanaryOverride,
type CanaryDecision,
type CanaryInput,
type CanaryReason,
} from "./canary.js";
export {
CANARIES,
canaryEnvVar,
findCanary,
overdueCanaries,
type CanaryDefinition,
} from "./canaryRegistry.js";
// VFX chain (data-vfx-chain) — defs, chain parse/serialize/normalize
export {
HF_VFX_ATTR,
HF_VFX_CHAIN_VERSION,
HF_VFX,
chainCapture,
getVfxDef,
parseVfxChain,
serializeVfxChain,
normalizeVfxParams,
type HfVfxCapture,
type HfVfxChain,
type HfVfxDef,
type HfVfxNode,
type HfVfxParam,
type HfVfxParamValues,
} from "./vfx.js";
export {
PAGE_DEVICE_SCALE_GLOBAL,
PAGE_MOTION_BLUR_OFF_GLOBAL,
acceleratedCanvasTrackerSource,
} from "./pageMotionBlur.js";
export {
MOTION_BLUR_FINGERPRINT_FIELDS,
type MotionBlurFingerprint,
type MotionBlurFingerprintField,
} from "./motionBlurFingerprint.js";
export { terminalLines, terminalText, terminalTextDeep } from "./terminalText.js";