mattebox 0.1.0

package/dist/types/facade.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=facade.js.map

package/dist/types/facade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.js","sourceRoot":"","sources":["../../src/types/facade.ts"],"names":[],"mappings":""}

package/dist/types/ir.d.ts

@@ -0,0 +1,238 @@
+/**
+ * The intermediate representation: the normalized timeline model every
+ * protocol adapter targets. Nothing above Layer 1 sees protocol-specific
+ * structures. This module imports nothing; it is the leaf of the type graph.
+ */
+/** Routed by the kernel to a registered sink. No registration: the track is enumerated but not selectable. */
+export type ContentType = 'video' | 'audio' | 'text' | 'metadata' | 'image';
+export type TrackId = string;
+export type RenditionId = string;
+/** Inclusive byte range for a partial fetch (HLS EXT-X-BYTERANGE, DASH @range). */
+export interface ByteRange {
+    readonly start: number;
+    readonly end: number;
+}
+/** A [start, end) window in presentation time, in seconds. */
+export interface TimeRange {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * A plain-data copy of the element's TimeRanges. TimeRanges itself is a live
+ * DOM object; snapshots keep messages and state serializable.
+ */
+export type TimeRangesSnapshot = readonly TimeRange[];
+/** Addresses one fetchable resource, such as an init segment. */
+export interface SegmentRef {
+    readonly url: string;
+    readonly byteRange?: ByteRange;
+}
+/** One media segment. `start` and `duration` are in seconds of presentation time. */
+/**
+ * Full-segment encryption (HLS EXT-X-KEY METHOD=AES-128): the whole segment
+ * is one AES-CBC message with PKCS7 padding. Not DRM: the key is a plain
+ * 16-byte fetch, so this rides on segments for a decrypt transform, never on
+ * a track's `protection`, which is the EME route.
+ */
+export interface SegmentKey {
+    readonly method: 'AES-128';
+    /** Absolute URL of the 16-byte key. */
+    readonly uri: string;
+    /** Explicit IV as 32 hex digits. Absent: the media sequence number, big-endian in 16 bytes (RFC 8216 §5.2). */
+    readonly iv?: string;
+}
+export interface Segment {
+    readonly seq: number;
+    readonly start: number;
+    readonly duration: number;
+    readonly url: string;
+    readonly byteRange?: ByteRange;
+    /** True when a timestamp discontinuity begins at this segment (HLS EXT-X-DISCONTINUITY). */
+    readonly discontinuity?: boolean;
+    /** Present while an AES-128 key applies; absent after METHOD=NONE or when never keyed. */
+    readonly key?: SegmentKey;
+}
+/**
+ * A run of consecutive segments with equal duration (DASH SegmentTimeline
+ * S@t/@d/@r). Long live windows compress to a handful of runs.
+ */
+export interface SegmentRun {
+    /** Start of the run in timescale units. */
+    readonly start: number;
+    /** Duration of each segment in the run, in timescale units. */
+    readonly duration: number;
+    /** Number of segments in the run. */
+    readonly count: number;
+}
+/**
+ * Indexed segment addressing (DASH SegmentTemplate, and any templated form).
+ * Segments are derived on demand from this data, so an adapter never
+ * materializes an array for a long live window.
+ */
+export interface IndexedSegments {
+    readonly kind: 'indexed';
+    /**
+     * URL template. `$Number$` expands to the sequence number and `$Time$` to
+     * the segment start in timescale units. ISO/IEC 23009-1 §5.3.9.4.4.
+     */
+    readonly urlTemplate: string;
+    readonly startSeq: number;
+    /** Null for a live window with no announced end. */
+    readonly endSeq: number | null;
+    /** Timescale units per second for `segmentDuration` and `timeline`. */
+    readonly timescale: number;
+    /** Constant segment duration in timescale units. Null when `timeline` is present. */
+    readonly segmentDuration: number | null;
+    /** Explicit timeline as compressed runs. Null when `segmentDuration` is constant. */
+    readonly timeline: readonly SegmentRun[] | null;
+    /** Offset subtracted from media time to map into period time, in timescale units. */
+    readonly presentationTimeOffset?: number;
+}
+/**
+ * On-demand addressing (DASH SegmentBase): one file per Representation whose
+ * segments are described by a `sidx` box at `indexRange`. The concrete
+ * segments are unknown until that box is fetched and parsed, at which point
+ * the adapter replaces this with an explicit `Segment[]` carrying byte ranges.
+ */
+export interface SidxSegments {
+    readonly kind: 'sidx';
+    /** The single media file (DASH BaseURL under the Representation). */
+    readonly url: string;
+    /** Byte range of the `sidx` box within the file (SegmentBase@indexRange). */
+    readonly indexRange: ByteRange;
+    /** SegmentBase@timescale; the sidx carries its own, this is the fallback. */
+    readonly timescale: number;
+    /** Offset subtracted from media time to map into period time, in seconds. */
+    readonly presentationTimeOffset?: number;
+}
+/** Explicit list, indexed template, or a to-be-fetched sidx index. */
+export type SegmentAddressing = readonly Segment[] | IndexedSegments | SidxSegments;
+/**
+ * One DRM signaling entry. Init data arrives by two routes (manifest and
+ * media); adapters emit whatever the manifest declares and `eme-core` dedupes
+ * by key ID.
+ */
+export interface ProtectionScheme {
+    /** DASH ContentProtection @schemeIdUri key-system UUID. Null for HLS METHOD-only signaling. */
+    readonly systemId: string | null;
+    /** Encryption scheme or method, such as 'cenc', 'cbcs', or an HLS EXT-X-KEY METHOD value. */
+    readonly scheme: string | null;
+    /** Default key ID, hex encoded. */
+    readonly keyId: string | null;
+    /** Key or license URI (HLS EXT-X-KEY URI). */
+    readonly licenseUrl: string | null;
+    /** Init data carried in the manifest, such as a pssh box. */
+    readonly initData: ArrayBuffer | null;
+    /** EME init data type for `initData`, such as 'cenc' or 'keyids'. */
+    readonly initDataType: string | null;
+}
+/** Track-level DRM signaling. */
+export interface ProtectionInfo {
+    readonly schemes: readonly ProtectionScheme[];
+}
+/**
+ * Content-steering data, normalized: HLS pathways are variant clones (the
+ * rendition carries its pathway id); DASH pathways are BaseURL choices
+ * (the bases map holds them). The steering stage consumes both shapes.
+ */
+export interface SteeringInfo {
+    /** The steering manifest URI, resolved absolute. */
+    readonly serverUri: string;
+    readonly defaultPathway?: string;
+    /** DASH: pathway id (serviceLocation) to absolute base URL. */
+    readonly bases?: Readonly<Record<string, string>>;
+}
+/** One quality level of a track. */
+export interface Rendition {
+    readonly id: RenditionId;
+    readonly bitrate: number;
+    readonly width?: number;
+    readonly height?: number;
+    readonly frameRate?: number;
+    /** RFC 6381 codec string. Null when the manifest does not declare one, common for text. */
+    readonly codecs: string | null;
+    readonly mimeType: string;
+    readonly init?: SegmentRef;
+    readonly segments: SegmentAddressing;
+    /**
+     * HLS only: the media playlist backing this rendition. Segments stay
+     * empty until the protocol stage fetches and merges it.
+     */
+    readonly playlistUrl?: string;
+    /** The content-steering pathway this rendition belongs to (HLS PATHWAY-ID). */
+    readonly pathway?: string;
+}
+/**
+ * A generic track descriptor. Parsers must never branch on content type to
+ * construct typed objects; the kernel routes on `contentType` and `mimeType`.
+ */
+export interface Track {
+    readonly id: TrackId;
+    readonly contentType: ContentType;
+    readonly mimeType: string;
+    readonly lang?: string;
+    /** Free-form role, such as 'main', 'alternate', 'subtitle', 'caption'. */
+    readonly role?: string;
+    /**
+     * Mandatory even when no DRM stage is loaded, so adding DRM later does not
+     * touch every adapter. Null means the track is clear.
+     */
+    readonly protection: ProtectionInfo | null;
+    readonly renditions: readonly Rendition[];
+}
+/**
+ * One HLS variant expressed as data: selecting `renditionId` requires the
+ * named companion tracks. DASH usually leaves the table empty because any
+ * composition is valid. Encoding this as data is what keeps `abr` from
+ * importing `alt-audio`.
+ */
+export interface Coupling {
+    readonly renditionId: RenditionId;
+    readonly requires: Partial<Record<ContentType, TrackId>>;
+}
+/** A continuous span of the presentation with a fixed track set. */
+export interface Period {
+    readonly id: string;
+    /** Start in presentation time, in seconds. */
+    readonly start: number;
+    /** Absent when the period runs to the next period boundary or the live edge. */
+    readonly duration?: number;
+    readonly tracks: readonly Track[];
+}
+/**
+ * Live delivery metadata, normalized from either manifest family. Absent
+ * for pure VOD. The kernel never computes with wall clocks; live stages
+ * turn these into LIVE_WINDOW_CHANGED facts.
+ */
+export interface LiveInfo {
+    /** availabilityStartTime as epoch seconds. */
+    readonly availabilityStart?: number;
+    /** Manifest refresh cadence in seconds (minimumUpdatePeriod, or the playlist target duration). */
+    readonly updatePeriod?: number;
+    /** DVR depth in seconds (timeShiftBufferDepth). */
+    readonly timeShiftDepth?: number;
+    /** Distance behind the availability end to hold playback, in seconds. */
+    readonly holdBack?: number;
+    /** A time server for clock skew (DASH UTCTiming). */
+    readonly timeServer?: {
+        readonly scheme: string;
+        readonly value: string;
+    };
+    /** A wall-clock anchor: `wallClock` epoch seconds corresponds to `presentationTime`. */
+    readonly dateAnchor?: {
+        readonly wallClock: number;
+        readonly presentationTime: number;
+    };
+}
+/** The root of the IR. One per loaded manifest. */
+export interface Presentation {
+    readonly id: string;
+    readonly isLive: boolean;
+    /** Absent for live presentations without an announced end. */
+    readonly duration?: number;
+    readonly periods: readonly Period[];
+    readonly couplings: readonly Coupling[];
+    readonly live?: LiveInfo;
+    readonly steering?: SteeringInfo;
+}
+//# sourceMappingURL=ir.d.ts.map

package/dist/types/ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.d.ts","sourceRoot":"","sources":["../../src/types/ir.ts"],"names":[],"mappings":"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"}

package/dist/types/ir.js

@@ -0,0 +1,7 @@
+/**
+ * The intermediate representation: the normalized timeline model every
+ * protocol adapter targets. Nothing above Layer 1 sees protocol-specific
+ * structures. This module imports nothing; it is the leaf of the type graph.
+ */
+export {};
+//# sourceMappingURL=ir.js.map

package/dist/types/ir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.js","sourceRoot":"","sources":["../../src/types/ir.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/types/kernel.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Kernel state, the reducer contract, and the diagnostic trace. The state
+ * shape is open to stage-contributed slices without `any`: named kernel
+ * fields are typed, and everything else reads as `unknown`.
+ */
+import type { MatteboxError } from './error.js';
+import type { ContentType, Presentation, RenditionId, TimeRange, TimeRangesSnapshot, TrackId } from './ir.js';
+import type { Command, Effect, Fact, Message } from './messages.js';
+import type { Constraint } from './quality.js';
+export type { TimeRangesSnapshot };
+/** Identifies one SourceBuffer for the lifetime of a MediaSource attachment. */
+export type SbId = string;
+/**
+ * Tunable kernel behavior. Every knob has a default; the facade will expose
+ * this through MatteboxOptions once the loader exists. Config is closure
+ * configuration like slices: a replay must rebuild the reducer with the
+ * same values.
+ */
+export interface KernelConfig {
+    /** Smoothing factor for the slow throughput EWMA, in (0, 1]. */
+    readonly ewmaAlpha: number;
+    /** Smoothing factor for the fast throughput EWMA, in (0, 1]. Reacts to collapse; abr uses the minimum of the two. */
+    readonly ewmaFastAlpha: number;
+    /** Transfers smaller than this many bytes are jitter-dominated and never enter the EWMAs. */
+    readonly ewmaMinSampleBytes: number;
+    /**
+     * Consecutive SourceBuffer failures on one buffer that halt its track
+     * with a fatal error. The circuit breaker: without it a failing append
+     * refetches the same segment forever.
+     */
+    readonly bufferErrorLimit: number;
+    /**
+     * Consecutive identical scheduler fetch decisions that halt playback
+     * with a fatal error. The safety net behind bufferErrorLimit: it also
+     * catches loops where every append reports success but buffered ranges
+     * never advance.
+     */
+    readonly repeatFetchLimit: number;
+    /** Seconds kept behind the playhead when quota pressure forces eviction. */
+    readonly backBufferSeconds: number;
+    /** Initial forward buffer goal in seconds, until SET_BUFFER_GOAL changes it. */
+    readonly bufferGoalSeconds: number;
+    /** Timeout for the manifest fetch effect, in milliseconds. */
+    readonly manifestTimeoutMs: number;
+    /** Capacity of the diagnostic ring buffer. */
+    readonly traceCapacity: number;
+    /** Backoff before a failed media fetch re-drives scheduling, in milliseconds. */
+    readonly baseRetryDelayMs: number;
+    /**
+     * True when a loaded transform rewrites every segment's decode time to its
+     * presentation start (ts-transmux, packed-audio, cmaf-timing). Media time
+     * then equals presentation time by construction and the scheduler applies a
+     * zero timestampOffset, instead of the epoch arithmetic that re-anchors the
+     * media clock at a discontinuity and would shift such a segment twice.
+     * The engine factory sets it from the composition's capabilities.
+     */
+    readonly mediaTimeNormalized: boolean;
+}
+export type LifecyclePhase = 'idle' | 'attaching' | 'loading' | 'ready' | 'ended' | 'error';
+/** One request the transport currently has in flight, keyed by its effect token. */
+export interface InflightRequest {
+    readonly token: string;
+    readonly trackId: TrackId;
+    readonly seq: number;
+    readonly url: string;
+    /** The SourceBuffer the bytes are destined for, when known at request time. */
+    readonly sbId?: SbId;
+    /**
+     * The timestampOffset this segment's append requires, computed by the
+     * scheduler from the timeline epochs. The reducer emits a
+     * setTimestampOffset effect before the append when it differs from the
+     * offset currently applied to the buffer.
+     */
+    readonly timestampOffset?: number;
+    /** The rendition the bytes belong to. Feeds the append log behind `quality.playing`. */
+    readonly renditionId?: RenditionId;
+    /** Segment window in presentation time, for the append log. */
+    readonly segmentStart?: number;
+    readonly segmentDuration?: number;
+    /**
+     * performance.now() at dispatch. Absent in state written by the reducer,
+     * which has no clock; the effect runner records it.
+     */
+    readonly startedAt?: number;
+}
+export interface BufferState {
+    readonly codecs: string;
+    readonly ranges: TimeRangesSnapshot;
+    readonly pendingAppends: number;
+    /**
+     * The rendition whose init segment this buffer last received. Media
+     * segments are never scheduled ahead of their init: the scheduler
+     * fetches the init first whenever this differs from the target.
+     */
+    readonly initFor?: RenditionId;
+}
+export interface QualityState {
+    /**
+     * Bumped by any constraint, pin, track, or presentation change. Derived
+     * reads (allowed, playing) memoize on it so TIME_UPDATE at 60 Hz never
+     * recomputes the constraint intersection.
+     */
+    readonly version: number;
+    readonly constraints: ReadonlyMap<string, Constraint>;
+    readonly pinned: RenditionId | null;
+    /** The rendition currently being appended. */
+    readonly active: RenditionId | null;
+    /**
+     * Which rendition occupies which buffered range. `quality.playing` is
+     * derived by looking up currentTime here. Pruned behind the eviction point.
+     */
+    readonly appendLog: ReadonlyArray<readonly [TimeRange, RenditionId]>;
+}
+export interface StatsState {
+    /** Slow exponentially weighted moving average of measured throughput, in bits per second. */
+    readonly throughputEwma: number;
+    /** Fast EWMA over the same samples; falls quickly when the network does. */
+    readonly throughputFastEwma: number;
+}
+/**
+ * The whole kernel state. Stages contribute additional slices under their
+ * own names via `StageContext.reduce`; those read as `unknown` here and are
+ * typed inside the owning stage.
+ */
+export interface KernelState {
+    readonly [sliceName: string]: unknown;
+    readonly lifecycle: {
+        readonly phase: LifecyclePhase;
+    };
+    readonly presentation: Presentation | null;
+    readonly timeline: {
+        readonly periodOffsets: ReadonlyMap<string, number>;
+        readonly discontinuitySeq: number;
+    };
+    readonly buffers: ReadonlyMap<SbId, BufferState>;
+    /** Consecutive SourceBuffer failures per buffer; a successful append clears the entry. */
+    readonly bufferErrors: ReadonlyMap<SbId, number>;
+    /**
+     * Coverage per cue track (text, metadata), in presentation time. The cue
+     * pipelines' analog of BufferState.ranges: merged from delivered segment
+     * spans, because the reducer cannot query sink instances.
+     */
+    readonly cues: ReadonlyMap<TrackId, TimeRangesSnapshot>;
+    /** The sliding availability window and the seek edge, from a live stage. Null until one reports. */
+    readonly live: {
+        readonly span: TimeRange;
+        readonly edge: number;
+    } | null;
+    readonly scheduling: {
+        readonly inflight: ReadonlyMap<string, InflightRequest>;
+        readonly bufferGoal: number;
+        /**
+         * Monotonic counter for effect tokens. Tokens come from state because
+         * the reducer is pure: no Math.random(), no clocks.
+         */
+        readonly tokenSeq: number;
+        /**
+         * The last fetch decision and how many consecutive times it repeated
+         * identically. The scheduling breaker: identical decisions past the
+         * configured limit mean the loop makes no progress and must halt.
+         */
+        readonly repeat?: {
+            readonly key: string;
+            readonly count: number;
+        };
+    };
+    readonly tracks: {
+        readonly active: ReadonlyMap<ContentType, TrackId>;
+        readonly available: readonly TrackId[];
+    };
+    readonly quality: QualityState;
+    readonly stats: StatsState;
+    /** Last known playhead position, written from TIME_UPDATE, SEEKING, and SEEKED facts. */
+    readonly playback: {
+        readonly currentTime: number;
+        readonly buffered: TimeRangesSnapshot;
+        readonly seeking: boolean;
+    };
+}
+/**
+ * The pure kernel reducer. No await, no DOM, no fetch, no Date.now(), no
+ * Math.random() inside it. Anything asynchronous is an effect.
+ */
+export type Reducer = (state: KernelState, msg: Message) => readonly [KernelState, readonly Effect[]];
+/**
+ * A stage-contributed reducer. It receives only its own slice, undefined on
+ * first run, plus a read-only view of kernel state.
+ */
+export type SliceReducer<S = unknown> = (slice: S | undefined, msg: Message, kernel: Readonly<KernelState>) => readonly [S, readonly Effect[]];
+/**
+ * The two entry points, kept distinct in the type system: the reducer may
+ * reject a command, it may never reject a fact. `absorb` must be callable
+ * from arbitrary event handlers without ordering guarantees.
+ */
+export interface Bus {
+    dispatch(cmd: Command): void;
+    absorb(fact: Fact): void;
+}
+/** One entry of the diagnostic ring buffer. Fixed capacity, overwriting, default 500. */
+export interface TraceEntry {
+    /** performance.now() when the message entered the loop. */
+    readonly t: number;
+    readonly msg: Message;
+    /** What the reducer emitted for this message. */
+    readonly effects: readonly Effect[];
+    /** Cheap hash of the relevant state slices, for divergence detection on replay. */
+    readonly digest: string;
+}
+/**
+ * A fatal error as surfaced on `engine.error`, with the ring buffer
+ * attached. MatteboxError types `trace` loosely to stay a leaf module; this
+ * is the precise shape.
+ */
+export type TracedError = MatteboxError & {
+    readonly trace?: readonly TraceEntry[];
+};
+//# sourceMappingURL=kernel.d.ts.map

package/dist/types/kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../../src/types/kernel.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,SAAS,EACT,kBAAkB,EAClB,OAAO,EACR,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,YAAY,EAAE,kBAAkB,EAAE,CAAC;AAEnC,gFAAgF;AAChF,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qHAAqH;IACrH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,6FAA6F;IAC7F,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,gFAAgF;IAChF,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,8CAA8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAE5F,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,wFAAwF;IACxF,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,UAAU;IACzB,6FAA6F;IAC7F,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;KAAE,CAAC;IACvD,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACpD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;KACnC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IACjD,0FAA0F;IAC1F,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;IACxD,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1E,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;QACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B;;;WAGG;QACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B;;;;WAIG;QACH,QAAQ,CAAC,MAAM,CAAC,EAAE;YAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;KACpE,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACnD,QAAQ,CAAC,SAAS,EAAE,SAAS,OAAO,EAAE,CAAC;KACxC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;QACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;KAC3B,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,CACpB,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,OAAO,KACT,SAAS,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI,CACtC,KAAK,EAAE,CAAC,GAAG,SAAS,EACpB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,KAC1B,SAAS,CAAC,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;AAErC;;;;GAIG;AACH,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;CAC1B;AAED,yFAAyF;AACzF,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC"}

package/dist/types/kernel.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=kernel.js.map

package/dist/types/kernel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel.js","sourceRoot":"","sources":["../../src/types/kernel.ts"],"names":[],"mappings":""}