framefields 2.0.2

package/dist/index-D2wJqSl5.d.mts

@@ -0,0 +1,114 @@
+import { wr as VirtualMediaData } from "./index-D2jDC7O5.mjs";
+import { n as NodeRendererPlugin } from "./index-BMVVmc4G.mjs";
+
+//#region ../compositions/dist/index.d.mts
+
+/**
+ * Recursively parses the VirtualMediaData tree and mixes all active audio tracks
+ * into a single unified stereo PCM stream (Float32Array channels).
+ */
+declare function mixAudioTracks(virtualMedia: VirtualMediaData, fps: number, targetSampleRate?: number, device?: GPUDevice, renderId?: string): Promise<{
+  channels: Float32Array[];
+  sampleRate: number;
+}>;
+//#endregion
+//#region src/utils/normalization.d.ts
+/**
+ * NormalizationContext carries the accumulated offsets and limits
+ * as we traverse down the virtual media tree.
+ */
+//#endregion
+//#region ../../nodes/node-audio-compressor/dist/renderer.d.mts
+//#region src/renderers/index.d.ts
+declare const _default$6: Readonly<NodeRendererPlugin>;
+//#endregion
+//#endregion
+//#region ../../nodes/node-audio-delay/dist/renderer.d.mts
+//#region src/renderers/index.d.ts
+declare const _default$5: Readonly<NodeRendererPlugin>;
+//#endregion
+//#endregion
+//#region ../../nodes/node-audio-fade/dist/renderer.d.mts
+//#region src/renderers/index.d.ts
+declare const _default$4: Readonly<NodeRendererPlugin>;
+//#endregion
+//#endregion
+//#region ../../nodes/node-audio-noise-gate/dist/renderer.d.mts
+//#region src/renderers/index.d.ts
+declare const _default$3: Readonly<NodeRendererPlugin>;
+//#endregion
+//#endregion
+//#region ../../nodes/node-audio-parametric-eq/dist/renderer.d.mts
+//#region src/renderers/index.d.ts
+declare const _default$2: Readonly<NodeRendererPlugin>;
+//#endregion
+//#endregion
+//#region ../../nodes/node-audio-reverb/dist/renderer.d.mts
+//#region src/renderers/index.d.ts
+declare const _default$1: Readonly<NodeRendererPlugin>;
+//#endregion
+//#endregion
+//#region ../../nodes/node-stereo-panning/dist/renderer.d.mts
+//#region src/renderers/index.d.ts
+declare const _default: Readonly<NodeRendererPlugin>;
+//#endregion
+
+//#endregion
+//#region src/audio/synth/sfx.d.ts
+/**
+ * @file packages/framefields/src/audio/synth/sfx.ts
+ * Deterministic procedural transition effects (whoosh, riser, impact, downshifter, glitch).
+ * Pure CPU DSP: the same trigger always renders the same samples.
+ */
+/**
+ * Procedural sound effect transition event, synthesized deterministically on the CPU.
+ * Default durations: whoosh 0.7s, riser 2s, impact 1.8s, downshifter 1.2s, glitch 0.35s.
+ */
+interface SfxTrigger {
+  type: "whoosh" | "riser" | "impact" | "downshifter" | "glitch";
+  /** Bar (fractional allowed) where the effect *starts*. A riser landing on a cut starts `durationSec` earlier. */
+  atBar: number;
+  durationSec?: number;
+  volume?: number;
+}
+type StereoBuffer = [Float32Array, Float32Array];
+interface RenderedSfx {
+  /** First sample of the effect on the score timeline. */
+  startSample: number;
+  channels: StereoBuffer;
+}
+interface SfxRenderContext {
+  sampleRate: number;
+  secondsPerBar: number;
+  /** Distinguishes otherwise identical triggers so noise differs between them. */
+  seed: number;
+}
+/**
+ * Renders one trigger to stereo PCM positioned at `atBar` on the score timeline.
+ * `atBar` is where the effect *starts*; a riser meant to land on a cut starts
+ * `durationSec / secondsPerBar` bars before it.
+ */
+declare function renderSfx(trigger: SfxTrigger, ctx: SfxRenderContext): RenderedSfx;
+/** Adds rendered effects into `target` in place, clipping to its length. */
+declare function mixSfxInto(target: StereoBuffer, effects: readonly RenderedSfx[]): void;
+/**
+ * Soft-knee limiter for sums that may exceed full scale (impacts stacked on a
+ * loud mix): transparent below the knee, asymptotically bounded by 1.0 above it.
+ */
+declare function softLimit(target: StereoBuffer, knee?: number, ceiling?: number): void;
+//#endregion
+//#region src/audio/synth/wav-encoder.d.ts
+/**
+ * @file packages/framefields/src/audio/synth/wav-encoder.ts
+ * High-performance 16-bit PCM RIFF/WAVE stereo audio encoder.
+ */
+interface EncodeWavOptions {
+  sampleRate?: number;
+}
+/**
+ * Encodes stereo Float32Array PCM channels (-1.0 to +1.0) into a standard 16-bit RIFF/WAVE Buffer.
+ */
+declare function encodeStereoWav(channels: [Float32Array, Float32Array], options?: EncodeWavOptions): Buffer;
+//#endregion
+export { SfxTrigger as a, softLimit as c, _default$2 as d, _default$3 as f, mixAudioTracks as g, _default$6 as h, SfxRenderContext as i, _default as l, _default$5 as m, encodeStereoWav as n, mixSfxInto as o, _default$4 as p, RenderedSfx as r, renderSfx as s, EncodeWavOptions as t, _default$1 as u };
+//# sourceMappingURL=index-D2wJqSl5.d.mts.map

package/dist/index-D2wJqSl5.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-D2wJqSl5.d.mts","names":["a","isStaticVisualMedia","c","RenderParams","i","calculateLayerTransform","l","computeRenderParams","n","framesToSeconds","o","resolveLayerDuration","r","secondsToFrames","s","CropRegion","t","formatTimecode","u","getFontUrl","VirtualMediaData","GPUCommandEncoder","GPUTexture","GPUTextureView","NodeRenderProps","RenderContextValue","drawCompositionTree","Promise","CompositionStateStore","compositionStateStore","SceneProps","AudioClip","decodeAudioSource","Float32Array","mixAudioTracks","GPUDevice","NormalizationContext","normalizeTimeline","_framefields_node_sdk_renderer0","_default","NodeRendererPlugin","Readonly","default","_framefields_node_sdk_renderer0","_default","NodeRendererPlugin","Readonly","default","_framefields_node_sdk_renderer0","_default","NodeRendererPlugin","Readonly","default","_framefields_node_sdk_renderer0","_default","NodeRendererPlugin","Readonly","default","_framefields_node_sdk_renderer0","_default","NodeRendererPlugin","Readonly","default","_framefields_node_sdk_renderer0","_default","NodeRendererPlugin","Readonly","default","_framefields_node_sdk_renderer0","_default","NodeRendererPlugin","Readonly","default"],"sources":["../../compositions/dist/index.d.mts","../../../nodes/node-audio-compressor/dist/renderer.d.mts","../../../nodes/node-audio-delay/dist/renderer.d.mts","../../../nodes/node-audio-fade/dist/renderer.d.mts","../../../nodes/node-audio-noise-gate/dist/renderer.d.mts","../../../nodes/node-audio-parametric-eq/dist/renderer.d.mts","../../../nodes/node-audio-reverb/dist/renderer.d.mts","../../../nodes/node-stereo-panning/dist/renderer.d.mts","../src/audio/synth/sfx.ts","../src/audio/synth/wav-encoder.ts"],"sourcesContent":["import { a as isStaticVisualMedia, c as RenderParams, i as calculateLayerTransform, l as computeRenderParams, n as framesToSeconds, o as resolveLayerDuration, r as secondsToFrames, s as CropRegion, t as formatTimecode, u as getFontUrl } from \"./timing-CHy-6wsp.mjs\";\nimport { VirtualMediaData } from \"@framefields/core\";\nimport { GPUCommandEncoder, GPUTexture, GPUTextureView, NodeRenderProps } from \"@framefields/node-sdk\";\nimport { RenderContextValue } from \"@framefields/webgpu-renderers\";\n\n//#region src/compositions/canvas-composition.d.ts\ndeclare function drawCompositionTree(ctx: RenderContextValue, encoder: GPUCommandEncoder, targetView: GPUTextureView, targetTexture: GPUTexture, targetWidth: number, targetHeight: number, virtualMedia: VirtualMediaData, props: NodeRenderProps, inheritedSeekOffset?: number, inheritedClockOffset?: number): Promise<void>;\n//#endregion\n//#region src/compositions/composition-state.d.ts\ndeclare class CompositionStateStore {\n  private states;\n  private listeners;\n  setState(key: string, frame: number, fps: number, isPlaying?: boolean): void;\n  getState(key: string): {\n    frame: number;\n    fps: number;\n    isPlaying: boolean;\n  };\n  subscribe(key: string, listener: () => void): () => void;\n  clearKey(key: string): void;\n  private notify;\n}\ndeclare const compositionStateStore: CompositionStateStore;\ninterface SceneProps {\n  viewportWidth: number;\n  viewportHeight: number;\n  containerWidth?: number;\n  containerHeight?: number;\n  virtualMedia?: VirtualMediaData;\n  backgroundColor?: string;\n  type?: \"Video\" | \"Audio\" | \"Image\";\n  volume?: number;\n  renderId?: string;\n  frame?: number;\n  fps?: number;\n  [key: string]: unknown;\n}\n//#endregion\n//#region src/utils/audio-extractor.d.ts\ninterface AudioClip {\n  sourceUrl: string;\n  destStartFrame: number;\n  trimStartSec: number;\n  durationFrames: number;\n  speed: number;\n  volume: number;\n}\n/**\n * Decodes all audio samples from a given source URL into raw Float32 mono/stereo channel buffers.\n */\ndeclare function decodeAudioSource(url: string): Promise<{\n  channels: Float32Array[];\n  sampleRate: number;\n} | null>;\n/**\n * Recursively parses the VirtualMediaData tree and mixes all active audio tracks\n * into a single unified stereo PCM stream (Float32Array channels).\n */\ndeclare function mixAudioTracks(virtualMedia: VirtualMediaData, fps: number, targetSampleRate?: number, device?: GPUDevice, renderId?: string): Promise<{\n  channels: Float32Array[];\n  sampleRate: number;\n}>;\n//#endregion\n//#region src/utils/normalization.d.ts\n/**\n * NormalizationContext carries the accumulated offsets and limits\n * as we traverse down the virtual media tree.\n */\ninterface NormalizationContext {\n  timeOffsetSec: number;\n  durationLimitMs?: number;\n}\n/**\n * normalizeTimeline recurses through the virtual media tree and \"absorbs\"\n * generic timeline-shifting operations into standard properties\n * of their children.\n */\ndeclare function normalizeTimeline(vv: VirtualMediaData, fps: number, context?: NormalizationContext): VirtualMediaData;\n//#endregion\nexport { AudioClip, CropRegion, RenderParams, SceneProps, calculateLayerTransform, compositionStateStore, computeRenderParams, decodeAudioSource, drawCompositionTree, formatTimecode, framesToSeconds, getFontUrl, isStaticVisualMedia, mixAudioTracks, normalizeTimeline, resolveLayerDuration, secondsToFrames };\n//# sourceMappingURL=index.d.mts.map","import * as _framefields_node_sdk_renderer0 from \"@framefields/node-sdk/renderer\";\n\n//#region src/renderers/index.d.ts\ndeclare const _default: Readonly<_framefields_node_sdk_renderer0.NodeRendererPlugin>;\n//#endregion\nexport { _default as default };\n//# sourceMappingURL=renderer.d.mts.map","import * as _framefields_node_sdk_renderer0 from \"@framefields/node-sdk/renderer\";\n\n//#region src/renderers/index.d.ts\ndeclare const _default: Readonly<_framefields_node_sdk_renderer0.NodeRendererPlugin>;\n//#endregion\nexport { _default as default };\n//# sourceMappingURL=renderer.d.mts.map","import * as _framefields_node_sdk_renderer0 from \"@framefields/node-sdk/renderer\";\n\n//#region src/renderers/index.d.ts\ndeclare const _default: Readonly<_framefields_node_sdk_renderer0.NodeRendererPlugin>;\n//#endregion\nexport { _default as default };\n//# sourceMappingURL=renderer.d.mts.map","import * as _framefields_node_sdk_renderer0 from \"@framefields/node-sdk/renderer\";\n\n//#region src/renderers/index.d.ts\ndeclare const _default: Readonly<_framefields_node_sdk_renderer0.NodeRendererPlugin>;\n//#endregion\nexport { _default as default };\n//# sourceMappingURL=renderer.d.mts.map","import * as _framefields_node_sdk_renderer0 from \"@framefields/node-sdk/renderer\";\n\n//#region src/renderers/index.d.ts\ndeclare const _default: Readonly<_framefields_node_sdk_renderer0.NodeRendererPlugin>;\n//#endregion\nexport { _default as default };\n//# sourceMappingURL=renderer.d.mts.map","import * as _framefields_node_sdk_renderer0 from \"@framefields/node-sdk/renderer\";\n\n//#region src/renderers/index.d.ts\ndeclare const _default: Readonly<_framefields_node_sdk_renderer0.NodeRendererPlugin>;\n//#endregion\nexport { _default as default };\n//# sourceMappingURL=renderer.d.mts.map","import * as _framefields_node_sdk_renderer0 from \"@framefields/node-sdk/renderer\";\n\n//#region src/renderers/index.d.ts\ndeclare const _default: Readonly<_framefields_node_sdk_renderer0.NodeRendererPlugin>;\n//#endregion\nexport { _default as default };\n//# sourceMappingURL=renderer.d.mts.map"],"mappings":";;;;;;ASKA;AAOA;;iBT8CiBkC,cAAAA,CS7CS,YAAA,ET6CoBd,gBS7CpB,EAAA,GAAA,EAAA,MAAA,EAAA,gBAAA,CAAA,EAAA,MAAA,EAAA,MAAA,CAAA,ET6CuFe,SS7CvF,EAAA,QAAA,CAAA,EAAA,MAAA,CAAA,ET6CsHR,OS7CtH,CAAA;EAChB,QAAA,ET6CEM,YS7CF,EAAA;EACP,UAAA,EAAA,MAAA;CAAM,CAAA;;;;;;;;;;cRZKM,YAAUE,SAASH;AD+CuB;;;;cE/C1CM,YAAUE,SAASH;AF+CuB;;;;cG/C1CM,YAAUE,SAASH;AH+CuB;;;;cI/C1CM,YAAUE,SAASH;AJ+CuB;;;;cK/C1CM,YAAUE,SAASH;AL+CuB;;;;cM/C1CM,YAAUE,SAASH;AN+CuB;;;;cO/C1CM,UAAUE,SAASH;AP+CuB;;;;;;;;AAAA;;;;;AAQ+F,UQhDtI,UAAA,CRgDsI;;;;ECvDzI7B,WAAAA,CAAAA,EAAsE,MAAA;;;KOexE,YAAA,IAAgB,cAAc;ANf5BK,UMiBG,WAAA,CNjBgBD;;;YMoBtB;ALvBuE;UK0BjE,gBAAA;;;EJvBHW;;;;ACHoE;;;;ACGpEU,iBEsLE,SAAA,CFtLiBD,OAAAA,EEuLvB,UFvLcG,EAAAA,GAAQ,EEwL1B,gBFxL0B,CAAA,EEyL7B,WFzL6B;;iBEiOhB,UAAA,SACP,gCACU;;ADtO+D;;;iBC6PlE,SAAA,SACP;;;;;;;ARpMQhC,USrDA,gBAAA,CTqDc;EAAed,UAAAA,CAAAA,EAAAA,MAAAA;;;;;iBS9C9B,eAAA,YACJ,cAAc,yBAChB,mBACP"}

package/dist/index-DKFGNyMB.d.mts

@@ -0,0 +1,309 @@
+import { wr as VirtualMediaData } from "./index-D2jDC7O5.mjs";
+import { VideoSampleSource } from "mediabunny";
+import { VideoFrame } from "@napi-rs/webcodecs";
+
+//#region ../renderer/dist/index.d.mts
+
+//#endregion
+//#region src/video-qa.d.ts
+/**
+ * Quality checks run on a video while it renders: frames are measured as
+ * they are read back for the encoder and audio as it is mixed, so the report
+ * describes exactly what was encoded without decoding the file again.
+ */
+interface VideoQaOptions {
+  /** Luma (0-1) at or below which a pixel counts as black. Default 0.1. */
+  readonly blackPixelThreshold?: number;
+  /** Share of black pixels that makes a frame black. Default 0.98. */
+  readonly blackFrameRatio?: number;
+  /** Shortest run of black frames reported. Default 0.5 s. */
+  readonly minBlackSec?: number;
+  /** Shortest run of unchanging frames reported. Default 2 s. */
+  readonly minFrozenSec?: number;
+  /** Level (dBFS, 100 ms windows) below which audio counts as silent. Default -60. */
+  readonly silenceDbfs?: number;
+  /** Shortest silent stretch reported. Default 2 s. */
+  readonly minSilenceSec?: number;
+  /** Integrated loudness to hit, e.g. -14 for most streaming platforms. Unchecked when unset. */
+  readonly targetLufs?: number;
+  /** Allowed distance from `targetLufs`, in LU. Default 1. */
+  readonly lufsTolerance?: number;
+}
+interface QaSegment {
+  readonly startSec: number;
+  readonly endSec: number;
+}
+interface QaIssue {
+  readonly severity: "error" | "warning" | "info";
+  /** Stable machine-readable kind, e.g. "black_frames", "audio_clipping" */
+  readonly code: string;
+  readonly message: string;
+  readonly startSec?: number;
+  readonly endSec?: number;
+  readonly layerId?: string;
+}
+interface VideoQaStats {
+  readonly expectedFrames: number;
+  readonly encodedFrames: number;
+  readonly fps: number;
+  readonly width: number;
+  readonly height: number;
+  /** Average luma over the whole video, 0-1 */
+  readonly meanLuma: number;
+  readonly blackSegments: readonly QaSegment[];
+  readonly frozenSegments: readonly QaSegment[];
+}
+interface AudioQaStats {
+  readonly sampleRate: number;
+  readonly channels: number;
+  readonly durationSec: number;
+  /** Highest sample, dBFS (sample peak, not true peak) */
+  readonly peakDbfs: number;
+  /** Mean level over the whole track, dBFS */
+  readonly rmsDbfs: number;
+  /** ITU-R BS.1770 integrated loudness; null when the track is silent */
+  readonly integratedLufs: number | null;
+  /** Samples at or beyond full scale */
+  readonly clippedSamples: number;
+  readonly silentSegments: readonly QaSegment[];
+}
+interface VideoQaReport {
+  /** No errors or warnings (info issues do not fail a render) */
+  readonly passed: boolean;
+  readonly video?: VideoQaStats;
+  readonly audio?: AudioQaStats;
+  readonly issues: readonly QaIssue[];
+}
+/** Measures frames handed to it in order, as RGBA bytes. */
+
+/** A short human- and agent-readable summary of a report. */
+declare function formatQaReport(report: VideoQaReport): string;
+//#endregion
+//#region src/headless-webgpu-renderer.d.ts
+
+declare class RenderSemaphore {
+  private _running;
+  private readonly _max;
+  private readonly _queue;
+  constructor(max: number);
+  acquire(timeoutMs?: number): Promise<void>;
+  release(): void;
+  get stats(): {
+    active: number;
+    queued: number;
+    max: number;
+  };
+}
+declare const renderSemaphore: RenderSemaphore;
+declare class HeadlessWebGPURenderer {
+  private static isInitialized;
+  private static initPromise;
+  private static initFailureCount;
+  private static readonly MAX_INIT_FAILURES;
+  private static nextRetryAt;
+  static initialize(): Promise<void>;
+  renderImage(virtualMedia: VirtualMediaData, frame?: number, fps?: number, options?: {
+    renderId?: string;
+    /** "rgba" skips PNG encoding and returns width*height*4 raw pixels. */
+    format?: "png" | "rgba";
+  }): Promise<Buffer>;
+  /**
+   * Renders a single frame to a PNG buffer at a specified timestamp in milliseconds or frame index.
+   */
+  renderFrame(source: VirtualMediaData | {
+    toVirtualMedia(): VirtualMediaData;
+  }, options?: {
+    atMs?: number;
+    frame?: number;
+    fps?: number;
+    /** Reuse compiled state across calls; see `renderImage`. */
+    renderId?: string;
+    /** "rgba" returns raw width*height*4 pixels instead of a PNG. */
+    format?: "png" | "rgba";
+  }): Promise<Buffer>;
+  /**
+   * Mixes the composition's full audio timeline (clips, effects, synthesized
+   * tracks) to stereo PCM, exactly as `renderVideo` muxes it.
+   */
+  renderAudio(virtualMedia: VirtualMediaData, options?: {
+    fps?: number;
+    sampleRate?: number;
+  }): Promise<{
+    channels: Float32Array[];
+    sampleRate: number;
+  }>;
+  renderLut(virtualMedia: VirtualMediaData, frame?: number, fps?: number): Promise<Buffer>;
+  private resolveMediaDuration;
+  renderVideo(virtualMedia: VirtualMediaData, options?: {
+    codec?: string;
+    audioCodec?: string;
+    quality?: string;
+    concurrency?: number;
+    /**
+     * Measure the output while it renders (black and frozen frames,
+     * dropped frames, loudness, clipping, silence, document warnings)
+     * and return the findings as `qa`. `true` uses default thresholds.
+     */
+    qa?: boolean | VideoQaOptions;
+  }): Promise<{
+    filePath: string;
+    cleanup: () => Promise<void>;
+    qa?: VideoQaReport;
+  }>;
+}
+declare const HeadlessMediaRenderer: typeof HeadlessWebGPURenderer;
+type HeadlessMediaRenderer = HeadlessWebGPURenderer;
+//#endregion
+//#region src/node-manifest.d.ts
+/**
+ * The `framefields` block of a node package's `package.json`.
+ *
+ * This is the single declaration of a node's op: renderer discovery, the
+ * effects generator (`scripts/generate-effects.ts`) and the skill catalog all
+ * read it from here. There is deliberately no fallback that derives an op from
+ * the package name. See `spec/sync-node.md` §5.1.
+ */
+//#endregion
+//#region src/renderer/framegrid.d.ts
+interface FrameSamplePoint {
+  frame: number;
+  timeMs: number;
+}
+interface FrameGridOptions {
+  /**
+   * Start frame index for sampling (inclusive). Defaults to 0.
+   */
+  startFrame?: number;
+  /**
+   * End frame index for sampling (inclusive). Defaults to startFrame + 30.
+   */
+  endFrame?: number;
+  /**
+   * Step interval between sampled frames. Must be >= 1. Defaults to 5.
+   */
+  stepFrames?: number;
+  /**
+   * Explicit list of frame indices to sample. Overrides startFrame/endFrame/stepFrames.
+   */
+  frames?: number[];
+  /**
+   * Start time in milliseconds (alternative to startFrame).
+   */
+  startMs?: number;
+  /**
+   * End time in milliseconds (alternative to endFrame).
+   */
+  endMs?: number;
+  /**
+   * Step interval in milliseconds (alternative to stepFrames).
+   */
+  stepMs?: number;
+  /**
+   * Explicit list of timestamps in milliseconds to sample.
+   */
+  timesMs?: number[];
+  /**
+   * Frames per second override. If omitted, reads from media/composition metadata or defaults to 24.
+   */
+  fps?: number;
+  /**
+   * Number of columns in the grid. If omitted, calculated automatically to preserve balance.
+   */
+  columns?: number;
+  /**
+   * Width in pixels for each individual thumbnail cell.
+   * Clamped to [120, 960]. Defaults to 320.
+   */
+  cellWidth?: number;
+  /**
+   * Explicit height for each cell. If omitted, computed from aspect ratio.
+   */
+  cellHeight?: number;
+  /**
+   * Gap in pixels between cells. Defaults to 12.
+   */
+  gap?: number;
+  /**
+   * Outer padding in pixels around the grid. Defaults to 16.
+   */
+  padding?: number;
+  /**
+   * Background color for the grid canvas. Defaults to "#090a0f".
+   */
+  backgroundColor?: string;
+  /**
+   * Whether to render frame number & millisecond badges on each cell. Defaults to true.
+   */
+  showLabels?: boolean;
+  /**
+   * Whether to render the metadata header banner at the top of the grid. Defaults to true.
+   */
+  showHeader?: boolean;
+  /**
+   * Custom header title text.
+   */
+  headerText?: string;
+  /**
+   * Optional file path to write the generated grid image directly to disk.
+   */
+  outputPath?: string;
+  /**
+   * Safety limit for total sampled frames to prevent memory exhaustion or oversized images.
+   * Defaults to 64. Hard maximum is 120.
+   */
+  maxFrames?: number;
+  /**
+   * Maximum allowed width for the generated image canvas. Defaults to 4096.
+   */
+  maxGridWidth?: number;
+  /**
+   * Maximum allowed height for the generated image canvas. Defaults to 4096.
+   */
+  maxGridHeight?: number;
+  /**
+   * Optional shared HeadlessMediaRenderer instance.
+   */
+  renderer?: HeadlessMediaRenderer;
+}
+/**
+ * Resolves and validates the list of sample points from the provided options.
+ */
+declare function resolveSamplePoints(options: FrameGridOptions, defaultFps?: number, durationMs?: number): {
+  samples: FrameSamplePoint[];
+  fps: number;
+};
+/**
+ * Computes grid layout dimensions, ensuring resulting canvas does not exceed size limits.
+ */
+declare function computeGridLayout(numSamples: number, aspectRatio: number, options: FrameGridOptions): {
+  columns: number;
+  rows: number;
+  cellWidth: number;
+  cellHeight: number;
+  totalWidth: number;
+  totalHeight: number;
+  headerHeight: number;
+  gap: number;
+  padding: number;
+};
+type FrameGridRenderable = {
+  toVirtualMedia(): VirtualMediaData;
+  renderFrame(options: {
+    frame?: number;
+    atMs?: number;
+    fps?: number;
+    renderer?: HeadlessMediaRenderer;
+  }): Promise<Buffer>;
+  fps?: number;
+  durationMs?: number;
+  width?: number;
+  height?: number;
+};
+/**
+ * Renders a sequence of frames from a Composition or Media pipeline into a unified image grid (contact sheet).
+ * Ideal for visual inspection of kinetic motion, transitions, easing, and layout stability.
+ */
+declare function renderFrameGrid(target: FrameGridRenderable, options?: FrameGridOptions): Promise<Buffer>;
+//#endregion
+export { renderFrameGrid as a, HeadlessMediaRenderer as c, QaSegment as d, VideoQaOptions as f, renderSemaphore as g, formatQaReport as h, computeGridLayout as i, HeadlessWebGPURenderer as l, VideoQaStats as m, FrameGridRenderable as n, resolveSamplePoints as o, VideoQaReport as p, FrameSamplePoint as r, AudioQaStats as s, FrameGridOptions as t, QaIssue as u };
+//# sourceMappingURL=index-DKFGNyMB.d.mts.map

package/dist/index-DKFGNyMB.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-DKFGNyMB.d.mts","names":["VideoColorPrimaries","VideoFrame","VideoMatrixCoefficients","VideoTransferCharacteristics","RenderDiagnostic","VirtualMediaData","VideoSampleSource","preloadFonts","GPUDevice","Promise","StagingSlotStatus","VideoColorSpaceConfig","DmaStagingRingOptions","GPUTextureFormat","StagingSlotInfo","DmaStagingRing","GPUCommandEncoder","GPUTexture","Uint8Array","findNodesDir","discoverAndRegisterNodeRenderers","VideoQaOptions","QaSegment","QaIssue","VideoQaStats","AudioQaStats","VideoQaReport","FrameInspector","analyzeAudio","Float32Array","integratedLoudness","buildQaReport","formatQaReport","WorkerInput","WorkerMessage","Array","RenderSemaphore","renderSemaphore","HeadlessWebGPURenderer","Buffer","HeadlessMediaRenderer","NODE_KINDS","NodeKind","NodeRendererExports","NodeManifest","NodeManifestError","Error","parseNodeManifest","loadNodeManifests","ZeroCopyWebCodecsPipelineOptions","WebCodecsPipelineStats","ZeroCopyWebCodecsPipeline"],"sources":["../../renderer/dist/index.d.mts","../src/renderer/framegrid.ts"],"sourcesContent":["import { VideoColorPrimaries, VideoFrame, VideoMatrixCoefficients, VideoTransferCharacteristics } from \"@napi-rs/webcodecs\";\nimport { RenderDiagnostic, VirtualMediaData } from \"@framefields/core\";\nimport { VideoSampleSource } from \"mediabunny\";\n\n//#region src/asset-preloader.d.ts\n/**\n * Recursively scans and preloads only the required font assets inside a VirtualMediaData tree.\n * This ensures typography renders correctly on Node.js without pre-loading or memory bloating from large media assets.\n */\ndeclare function preloadFonts(media: VirtualMediaData, device?: GPUDevice | null): Promise<void>;\n//#endregion\n//#region src/dma-staging-ring.d.ts\ntype StagingSlotStatus = \"idle\" | \"rendering\" | \"mapping\" | \"mapped\";\ninterface VideoColorSpaceConfig {\n  readonly primaries?: VideoColorPrimaries;\n  readonly transfer?: VideoTransferCharacteristics;\n  readonly matrix?: VideoMatrixCoefficients;\n  readonly fullRange?: boolean;\n}\ninterface DmaStagingRingOptions {\n  readonly width: number;\n  readonly height: number;\n  readonly capacity?: number;\n  readonly format?: GPUTextureFormat;\n}\ninterface StagingSlotInfo {\n  readonly index: number;\n  readonly status: StagingSlotStatus;\n  readonly inFlightFrame: number | null;\n}\n/**\n * Pipelined Asynchronous DMA Staging Ring for WebGPU.\n *\n * Implements double-buffered (or N-buffered) GPU staging buffers to overlap\n * GPU render passes with asynchronous DMA host transfers and WebCodecs hardware encoding.\n * Eliminates GPU stalls by allowing Frame i+1 to execute on the GPU while Frame i\n * is asynchronously mapped and consumed by the hardware video encoder.\n */\ndeclare class DmaStagingRing {\n  readonly width: number;\n  readonly height: number;\n  readonly capacity: number;\n  readonly bytesPerRow: number;\n  readonly unpaddedBytesPerRow: number;\n  readonly bufferSize: number;\n  readonly format: GPUTextureFormat;\n  readonly device: GPUDevice;\n  private readonly slots;\n  private isDestroyed;\n  constructor(device: GPUDevice, options: DmaStagingRingOptions);\n  /**\n   * Prepares the staging buffer slot for writing by ensuring any prior mapping\n   * from a previous cycle has been completed and unmapped.\n   */\n  prepareSlot(frameIndex: number): Promise<void>;\n  /**\n   * Records a GPU-to-buffer DMA copy command into the provided command encoder.\n   */\n  stageTexture(encoder: GPUCommandEncoder, texture: GPUTexture, frameIndex: number): void;\n  /**\n   * Initiates asynchronous DMA mapping on the slot for the specified frame.\n   * Must be called immediately after submitting the command encoder to the device queue.\n   */\n  scheduleMap(frameIndex: number): Promise<void>;\n  /**\n   * Awaits asynchronous mapping and extracts pixels into a tightly packed Uint8Array.\n   * The slot remains in the \"mapped\" state until releaseFrame() is called.\n   */\n  readFramePixels(frameIndex: number): Promise<Uint8Array>;\n  /**\n   * Awaits asynchronous mapping, extracts pixels, and immediately unmaps the staging buffer,\n   * returning the slot to \"idle\" state so it can be reused immediately.\n   */\n  readAndReleaseFrame(frameIndex: number): Promise<Uint8Array>;\n  /**\n   * Directly reads the mapped staging buffer into a WebCodecs VideoFrame,\n   * bypassing redundant intermediate JS allocations when row pitches align,\n   * and immediately unmaps the buffer.\n   */\n  readFrameToVideoFrame(frameIndex: number, timestampUs: number, colorSpace?: VideoColorSpaceConfig, /** Sees the tightly packed RGBA pixels while they are mapped; must not keep them. */\n  inspect?: (rgba: Uint8Array) => void): Promise<VideoFrame>;\n  /**\n   * Unmaps the staging buffer for the specified frame and marks the slot idle.\n   */\n  releaseFrame(frameIndex: number): void;\n  /**\n   * Returns current status info for each slot in the ring.\n   */\n  getSlotInfos(): readonly StagingSlotInfo[];\n  /**\n   * Destroys all staging buffers and releases resources.\n   */\n  destroy(): void;\n  private checkDestroyed;\n}\n//#endregion\n//#region src/dynamic-node-discovery.d.ts\n/** Locates the workspace `nodes/` directory by climbing up from this file. */\ndeclare function findNodesDir(startDir?: string): string | null;\n/**\n * Registers the built-in node renderers, then any extra nodes found in the\n * directory named by `FRAMEFIELDS_NODES_DIR` (local node development). A node in\n * that directory overrides the built-in renderer for the same op.\n */\ndeclare function discoverAndRegisterNodeRenderers(): Promise<void>;\n//#endregion\n//#region src/video-qa.d.ts\n/**\n * Quality checks run on a video while it renders: frames are measured as\n * they are read back for the encoder and audio as it is mixed, so the report\n * describes exactly what was encoded without decoding the file again.\n */\ninterface VideoQaOptions {\n  /** Luma (0-1) at or below which a pixel counts as black. Default 0.1. */\n  readonly blackPixelThreshold?: number;\n  /** Share of black pixels that makes a frame black. Default 0.98. */\n  readonly blackFrameRatio?: number;\n  /** Shortest run of black frames reported. Default 0.5 s. */\n  readonly minBlackSec?: number;\n  /** Shortest run of unchanging frames reported. Default 2 s. */\n  readonly minFrozenSec?: number;\n  /** Level (dBFS, 100 ms windows) below which audio counts as silent. Default -60. */\n  readonly silenceDbfs?: number;\n  /** Shortest silent stretch reported. Default 2 s. */\n  readonly minSilenceSec?: number;\n  /** Integrated loudness to hit, e.g. -14 for most streaming platforms. Unchecked when unset. */\n  readonly targetLufs?: number;\n  /** Allowed distance from `targetLufs`, in LU. Default 1. */\n  readonly lufsTolerance?: number;\n}\ninterface QaSegment {\n  readonly startSec: number;\n  readonly endSec: number;\n}\ninterface QaIssue {\n  readonly severity: \"error\" | \"warning\" | \"info\";\n  /** Stable machine-readable kind, e.g. \"black_frames\", \"audio_clipping\" */\n  readonly code: string;\n  readonly message: string;\n  readonly startSec?: number;\n  readonly endSec?: number;\n  readonly layerId?: string;\n}\ninterface VideoQaStats {\n  readonly expectedFrames: number;\n  readonly encodedFrames: number;\n  readonly fps: number;\n  readonly width: number;\n  readonly height: number;\n  /** Average luma over the whole video, 0-1 */\n  readonly meanLuma: number;\n  readonly blackSegments: readonly QaSegment[];\n  readonly frozenSegments: readonly QaSegment[];\n}\ninterface AudioQaStats {\n  readonly sampleRate: number;\n  readonly channels: number;\n  readonly durationSec: number;\n  /** Highest sample, dBFS (sample peak, not true peak) */\n  readonly peakDbfs: number;\n  /** Mean level over the whole track, dBFS */\n  readonly rmsDbfs: number;\n  /** ITU-R BS.1770 integrated loudness; null when the track is silent */\n  readonly integratedLufs: number | null;\n  /** Samples at or beyond full scale */\n  readonly clippedSamples: number;\n  readonly silentSegments: readonly QaSegment[];\n}\ninterface VideoQaReport {\n  /** No errors or warnings (info issues do not fail a render) */\n  readonly passed: boolean;\n  readonly video?: VideoQaStats;\n  readonly audio?: AudioQaStats;\n  readonly issues: readonly QaIssue[];\n}\n/** Measures frames handed to it in order, as RGBA bytes. */\ndeclare class FrameInspector {\n  private readonly blackLuma;\n  private readonly blackRatio;\n  private readonly black;\n  private readonly sameAsPrevious;\n  private lumaSum;\n  private previous;\n  constructor(options?: VideoQaOptions);\n  get frameCount(): number;\n  inspect(rgba: Uint8Array, width: number, height: number): void;\n  stats(expectedFrames: number, encodedFrames: number, fps: number, width: number, height: number, options?: VideoQaOptions): VideoQaStats;\n}\n/** Measures a mixed audio track (one Float32Array per channel). */\ndeclare function analyzeAudio(channels: readonly Float32Array[], sampleRate: number, options?: VideoQaOptions): AudioQaStats;\n/**\n * ITU-R BS.1770-4 integrated loudness (LUFS): K-weighted mean square in\n * 400 ms blocks with 75% overlap, gated at -70 LUFS and then at 10 LU below\n * the mean of what passed. Channels weigh 1 (stereo and mono layouts).\n */\ndeclare function integratedLoudness(channels: readonly Float32Array[], sampleRate: number): number | null;\n/** Turn measurements and document diagnostics into a report with issues. */\ndeclare function buildQaReport(parts: {\n  video?: VideoQaStats;\n  audio?: AudioQaStats;\n  diagnostics?: readonly RenderDiagnostic[];\n  options?: VideoQaOptions;\n}): VideoQaReport;\n/** A short human- and agent-readable summary of a report. */\ndeclare function formatQaReport(report: VideoQaReport): string;\n//#endregion\n//#region src/headless-webgpu-renderer.d.ts\ninterface WorkerInput {\n  virtualMedia: VirtualMediaData;\n  width: number;\n  height: number;\n  fps: number;\n  startFrame: number;\n  endFrame: number;\n  renderId: string;\n  outputFormat: \"png\" | \"pixels\";\n  workerIndex: number;\n}\ntype WorkerMessage = {\n  type: \"frame\";\n  renderId: string;\n  frameIndex: number;\n  pixels: Uint8Array;\n} | {\n  type: \"png\";\n  renderId: string;\n  data: Uint8Array;\n} | {\n  type: \"done\";\n  renderId: string;\n} | {\n  type: \"lut\";\n  renderId: string;\n  raw: {\n    points: Array<[number, number, number]>;\n    size: number;\n    type: \"1D\" | \"3D\";\n  };\n} | {\n  type: \"error\";\n  renderId?: string;\n  error: string;\n};\ndeclare class RenderSemaphore {\n  private _running;\n  private readonly _max;\n  private readonly _queue;\n  constructor(max: number);\n  acquire(timeoutMs?: number): Promise<void>;\n  release(): void;\n  get stats(): {\n    active: number;\n    queued: number;\n    max: number;\n  };\n}\ndeclare const renderSemaphore: RenderSemaphore;\ndeclare class HeadlessWebGPURenderer {\n  private static isInitialized;\n  private static initPromise;\n  private static initFailureCount;\n  private static readonly MAX_INIT_FAILURES;\n  private static nextRetryAt;\n  static initialize(): Promise<void>;\n  renderImage(virtualMedia: VirtualMediaData, frame?: number, fps?: number, options?: {\n    renderId?: string;\n    /** \"rgba\" skips PNG encoding and returns width*height*4 raw pixels. */\n    format?: \"png\" | \"rgba\";\n  }): Promise<Buffer>;\n  /**\n   * Renders a single frame to a PNG buffer at a specified timestamp in milliseconds or frame index.\n   */\n  renderFrame(source: VirtualMediaData | {\n    toVirtualMedia(): VirtualMediaData;\n  }, options?: {\n    atMs?: number;\n    frame?: number;\n    fps?: number;\n    /** Reuse compiled state across calls; see `renderImage`. */\n    renderId?: string;\n    /** \"rgba\" returns raw width*height*4 pixels instead of a PNG. */\n    format?: \"png\" | \"rgba\";\n  }): Promise<Buffer>;\n  /**\n   * Mixes the composition's full audio timeline (clips, effects, synthesized\n   * tracks) to stereo PCM, exactly as `renderVideo` muxes it.\n   */\n  renderAudio(virtualMedia: VirtualMediaData, options?: {\n    fps?: number;\n    sampleRate?: number;\n  }): Promise<{\n    channels: Float32Array[];\n    sampleRate: number;\n  }>;\n  renderLut(virtualMedia: VirtualMediaData, frame?: number, fps?: number): Promise<Buffer>;\n  private resolveMediaDuration;\n  renderVideo(virtualMedia: VirtualMediaData, options?: {\n    codec?: string;\n    audioCodec?: string;\n    quality?: string;\n    concurrency?: number;\n    /**\n     * Measure the output while it renders (black and frozen frames,\n     * dropped frames, loudness, clipping, silence, document warnings)\n     * and return the findings as `qa`. `true` uses default thresholds.\n     */\n    qa?: boolean | VideoQaOptions;\n  }): Promise<{\n    filePath: string;\n    cleanup: () => Promise<void>;\n    qa?: VideoQaReport;\n  }>;\n}\ndeclare const HeadlessMediaRenderer: typeof HeadlessWebGPURenderer;\ntype HeadlessMediaRenderer = HeadlessWebGPURenderer;\n//#endregion\n//#region src/node-manifest.d.ts\n/**\n * The `framefields` block of a node package's `package.json`.\n *\n * This is the single declaration of a node's op: renderer discovery, the\n * effects generator (`scripts/generate-effects.ts`) and the skill catalog all\n * read it from here. There is deliberately no fallback that derives an op from\n * the package name. See `spec/sync-node.md` §5.1.\n */\ndeclare const NODE_KINDS: readonly [\"effect\", \"audio\", \"source\", \"signal\", \"utility\"];\ntype NodeKind = (typeof NODE_KINDS)[number];\ninterface NodeRendererExports {\n  development?: string;\n  import?: string;\n  default?: string;\n}\ninterface NodeManifest {\n  /** Directory name under `nodes/`, e.g. `node-apply-lut`. */\n  dir: string;\n  /** Absolute path of the node package. */\n  path: string;\n  /** npm package name, e.g. `@framefields/node-lut`. */\n  packageName: string;\n  /** Canonical op literal used in the operation AST and the renderer registry. */\n  type: string;\n  kind: NodeKind;\n  /** Legacy ops that resolve to the same renderer. */\n  aliases: readonly string[];\n  /** Named zod schema export of `src/shared/config.ts`. */\n  schema?: string;\n  /** Authoring class name. Defaults to `type`. */\n  className?: string;\n  /** Key on `Effect.*`. Defaults to `className` with a lower-cased first letter. */\n  factory?: string;\n  /** A hand-written subclass exists under `effects/custom/`. */\n  custom: boolean;\n  /** `false` when the package opts out of discovery. */\n  enabled: boolean;\n  rendererExports?: NodeRendererExports;\n}\ndeclare class NodeManifestError extends Error {\n  readonly problems: readonly string[];\n  constructor(problems: readonly string[]);\n}\n/**\n * Validates one parsed `package.json`. Returns the manifest, or the list of\n * problems that make it unusable. Never throws.\n */\ndeclare function parseNodeManifest(pkg: unknown, dir: string, nodePath?: string): {\n  manifest?: NodeManifest;\n  problems: string[];\n};\n/**\n * Reads every `nodes/node-*` package and returns its manifest, sorted by\n * directory name. Throws a single {@link NodeManifestError} listing every\n * problem: a missing or malformed block, or an op/alias claimed twice.\n */\ndeclare function loadNodeManifests(nodesDir: string): NodeManifest[];\n//#endregion\n//#region src/zero-copy-webcodecs-pipeline.d.ts\ninterface ZeroCopyWebCodecsPipelineOptions {\n  readonly width: number;\n  readonly height: number;\n  readonly fps: number;\n  readonly videoSource: VideoSampleSource;\n  readonly ringCapacity?: number;\n  readonly colorSpace?: VideoColorSpaceConfig;\n  readonly directCanvasSource?: unknown;\n  /**\n   * Called with each frame's RGBA pixels, in frame order, just before it is\n   * encoded (staging-ring path only). The buffer is reused: read, don't keep.\n   */\n  readonly onFrame?: (rgba: Uint8Array, frameIndex: number) => void;\n}\ninterface WebCodecsPipelineStats {\n  readonly totalFramesEnqueued: number;\n  readonly totalFramesEncoded: number;\n  readonly averageGpuSubmitTimeMs: number;\n  readonly averageEncodeTimeMs: number;\n  readonly averageCycleTimeMs: number;\n  readonly maxCycleTimeMs: number;\n  readonly minCycleTimeMs: number;\n  readonly throughputFps: number;\n  readonly ringCapacity: number;\n  readonly isDirectZeroCopy: boolean;\n}\n/**\n * High-performance hardware video encoding pipeline integrating WebGPU textures with WebCodecs.\n *\n * Provides:\n * 1. Direct hardware acceleration when running with WebCodecs / OffscreenCanvas.\n * 2. Pipelined asynchronous double-buffered DMA staging ring for headless Node.js (Dawn native),\n *    allowing GPU Frame i+1 rendering to overlap concurrently with Frame i hardware encoding.\n */\ndeclare class ZeroCopyWebCodecsPipeline {\n  readonly width: number;\n  readonly height: number;\n  readonly fps: number;\n  readonly ringCapacity: number;\n  private readonly device;\n  private readonly videoSource;\n  private readonly stagingRing;\n  private readonly colorSpace?;\n  private readonly directCanvasSource?;\n  private readonly onFrame?;\n  private readonly inFlightFrames;\n  private readonly cycleStartTimes;\n  private totalFramesEnqueued;\n  private totalFramesEncoded;\n  private totalGpuSubmitTimeMs;\n  private totalEncodeTimeMs;\n  private totalCycleTimeMs;\n  private maxCycleTimeMs;\n  private minCycleTimeMs;\n  private pipelineStartTime;\n  constructor(device: GPUDevice, options: ZeroCopyWebCodecsPipelineOptions);\n  /**\n   * Returns true if direct zero-copy from an OffscreenCanvas or texture is active.\n   */\n  canDirectZeroCopy(): boolean;\n  /**\n   * Enqueues a rendered GPU texture frame into the pipeline.\n   *\n   * Uses double-buffered DMA staging: if the staging ring has reached capacity,\n   * the oldest in-flight frame is asynchronously consumed and added to the video encoder\n   * before staging the new frame, guaranteeing constant bounded VRAM usage and zero GPU stalls.\n   */\n  enqueueFrame(frameIndex: number, targetTexture: GPUTexture, encoder: GPUCommandEncoder): Promise<void>;\n  /**\n   * Drains all remaining in-flight frames in the pipeline, ensuring every enqueued\n   * frame has been encoded and added to the video sample source.\n   */\n  drain(): Promise<void>;\n  /**\n   * Returns runtime throughput, latency, and pipeline statistics.\n   */\n  getStats(): WebCodecsPipelineStats;\n  /**\n   * Destroys the pipeline and releases all staging buffers.\n   */\n  destroy(): void;\n  private consumeAndEncode;\n}\n//#endregion\nexport { AudioQaStats, DmaStagingRing, DmaStagingRingOptions, FrameInspector, HeadlessMediaRenderer, HeadlessWebGPURenderer, NODE_KINDS, NodeKind, NodeManifest, NodeManifestError, NodeRendererExports, QaIssue, QaSegment, StagingSlotInfo, StagingSlotStatus, VideoColorSpaceConfig, VideoQaOptions, VideoQaReport, VideoQaStats, WebCodecsPipelineStats, WorkerInput, WorkerMessage, ZeroCopyWebCodecsPipeline, ZeroCopyWebCodecsPipelineOptions, analyzeAudio, buildQaReport, discoverAndRegisterNodeRenderers, findNodesDir, formatQaReport, integratedLoudness, loadNodeManifests, parseNodeManifest, preloadFonts, renderSemaphore };\n//# sourceMappingURL=index.d.mts.map"],"mappings":";;;;;;;;;;;;;UAgHUqB,cAAAA;;;;;;;;;;;;;;;;;;UAkBAC,SAAAA;;;;UAIAC,OAAAA;;;;;;;;;UASAC,YAAAA;;;;;;;;mCAQyBF;oCACCA;;UAE1BG,YAAAA;;;;;;;;;;;;oCAY0BH;;UAE1BI,aAAAA;;;mBAGSF;mBACAC;4BACSF;;;;;iBA+BXS,cAAAA,SAAuBN;;;;cAuC1BU,eAAAA;;;;;+BAKiB3B;;;;;;;;cAQjB4B,iBAAiBD;cACjBE,sBAAAA;;;;;;uBAMS7B;4BACKJ;;;;MAItBI,QAAQ8B;;;;sBAIQlC;sBACAA;;;;;;;;;MAShBI,QAAQ8B;;;;;4BAKclC;;;MAGtBI;cACQoB;;;0BAGYxB,iDAAiDI,QAAQ8B;;4BAEvDlC;;;;;;;;;;mBAUTgB;MACbZ;;mBAEaA;SACViB;;;cAGKc,8BAA8BF;KACvCE,qBAAAA,GAAwBF;;;;;;;;;;;;;UCrTZ,gBAAA;;;ADmG2C;AA0BlDhB,UCxHO,gBAAA,CDwHE;EAITC;AAAO;AAkB4B;EAgBnCG,UAAAA,CAAAA,EAAAA,MAAa;EAGJF;;;EAEgB,QAAA,CAAA,EAAA,MAAA;EA+BlBQ;AA8BA;AAcqB;EASxBM,UAAAA,CAAAA,EAAAA,MAAAA;EAMS7B;;;EAKjBA,MAAAA,CAAAA,EAAAA,MAAAA,EAAAA;EAIgBJ;;;EAUhBI,OAAAA,CAAAA,EAAAA,MAAAA;EAKsBJ;;;EAOFA,KAAAA,CAAAA,EAAAA,MAAAA;EAAyDkC;;;EAYhElB,MAAAA,CAAAA,EAAAA,MAAAA;EAGAZ;;;EAFN,OAAA,CAAA,EAAA,MAAA,EAAA;EAMC+B;AAAoD;;;;ACpTlE;AAKA;EA0HgB,OAAA,CAAA,EAAA,MAAA;EAsGA;AAiFhB;;;EAOa,SAAA,CAAA,EAAA,MAAA;EAAR;;AAWL;EACS,UAAA,CAAA,EAAA,MAAA;EACC;;;EACA,GAAA,CAAA,EAAA,MAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAlNE;;;;;iBAMI,mBAAA,UACN;WAGI;;;;;;iBAkGE,iBAAA,mDAGN;;;;;;;;;;;KA8EE,mBAAA;oBACO;;;;;eAKN;MACR,QAAQ;;;;;;;;;;iBAWS,eAAA,SACb,+BACC,mBACP,QAAQ"}

package/dist/index-DiSKzDGR.d.mts

@@ -0,0 +1,65 @@
+//#region src/fonts/manager.d.ts
+interface RegisterFontOptions {
+  family?: string;
+  source: string | Uint8Array;
+  weight?: number | string;
+  style?: "normal" | "italic" | "oblique";
+}
+interface RegisteredFont {
+  family: string;
+  source: string | Uint8Array;
+  filePath?: string;
+  format: "truetype" | "opentype";
+  postscriptName?: string;
+  unitsPerEm?: number;
+  weight?: number | string;
+  style?: string;
+}
+/**
+ * Central singleton manager for font registration, TTF validation, and compositor typography binding.
+ */
+declare class FontManager {
+  private static instance;
+  private readonly fonts;
+  private constructor();
+  /**
+   * Returns the singleton FontManager instance.
+   */
+  static getInstance(): FontManager;
+  /**
+   * Registers a TrueType/OpenType font into the Framefields engine with validation.
+   */
+  static register(optionsOrFamilyOrSource: RegisterFontOptions | string, source?: string | Uint8Array): Promise<RegisteredFont>;
+  /**
+   * Retrieves registered font metadata by family name.
+   */
+  static get(family: string): RegisteredFont | undefined;
+  /**
+   * Checks if a font family has been registered.
+   */
+  static has(family: string): boolean;
+  /**
+   * Returns all currently registered fonts.
+   */
+  static getAll(): RegisteredFont[];
+  /**
+   * Returns relative or absolute file paths of all registered fonts for composition spec serialization.
+   */
+  static getRegisteredFontPaths(): string[];
+  /**
+   * Clears all registered fonts from the manager.
+   */
+  static clear(): void;
+  /**
+   * Instance registration method with format validation and Slug WebGPU cache population.
+   */
+  register(optionsOrFamilyOrSource: RegisterFontOptions | string, source?: string | Uint8Array): Promise<RegisteredFont>;
+  get(family: string): RegisteredFont | undefined;
+  has(family: string): boolean;
+  getAll(): RegisteredFont[];
+  getRegisteredFontPaths(): string[];
+  clear(): void;
+}
+//#endregion
+export { RegisterFontOptions as n, RegisteredFont as r, FontManager as t };
+//# sourceMappingURL=index-DiSKzDGR.d.mts.map

package/dist/index-DiSKzDGR.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-DiSKzDGR.d.mts","names":[],"sources":["../src/fonts/manager.ts"],"sourcesContent":[],"mappings":";UAQiB,mBAAA;EAAA,MAAA,CAAA,EAAA,MAAA;EAOA,MAAA,EAAA,MAAA,GALC,UAKa;EAmJlB,MAAA,CAAA,EAAA,MAAW,GAAA,MAAA;EASM,KAAA,CAAA,EAAA,QAAA,GAAA,QAAA,GAAA,SAAA;;AAYV,UAxKH,cAAA,CAwKG;EACR,MAAA,EAAA,MAAA;EAAR,MAAA,EAAA,MAAA,GAvKc,UAuKd;EAOgC,QAAA,CAAA,EAAA,MAAA;EAcX,MAAA,EAAA,UAAA,GAAA,UAAA;EAsBE,cAAA,CAAA,EAAA,MAAA;EACP,UAAA,CAAA,EAAA,MAAA;EACR,MAAA,CAAA,EAAA,MAAA,GAAA,MAAA;EAAR,KAAA,CAAA,EAAA,MAAA;;;;;cAnES,WAAA;;;;;;;wBASiB;;;;2CAWH,gDACP,aAChB,QAAQ;;;;8BAOwB;;;;;;;;mBAcX;;;;;;;;;;;;oCAsBE,gDACP,aAChB,QAAQ;uBAgFiB;;YAQX"}