@oasys/oecs 0.1.2 → 0.2.1

package/README.md

@@ -2,27 +2,49 @@
 
 A fast, minimal archetype-based Entity Component System written in TypeScript.
 
-- **Zero-copy archetype transitions** — component data is indexed by entity, not archetype row. Moving between archetypes copies only the relevant column data.
-- **Structure-of-Arrays (SoA)** — each component field is a contiguous `number[]` column, enabling tight inner loops.
-- **Phantom-typed components** — `ComponentDef<["x", "y"]>` is just a number at runtime, but enforces field names at compile time.
-- **Batch iteration** — `query.each()` calls your function once per archetype with column arrays and entity count. You write the inner loop.
+- **Structure-of-Arrays (SoA)** — each component field is a contiguous typed array column (`Float64Array`, `Int32Array`, etc.), enabling cache-friendly inner loops.
+- **Phantom-typed components** — `ComponentDef<{x:"f64",y:"f64"}>` is just a number at runtime, but enforces field names and types at compile time.
+- **Batch iteration** — `for..of` over a query yields non-empty archetypes. Access SoA columns via `get_column()` and write the inner loop.
+- **Single-entity refs** — `ctx.ref(Pos, entity)` gives you a cached accessor with prototype-backed getters/setters.
+- **Resources** — typed global singletons (time, input, config) with live readers.
+- **Events & signals** — fire-and-forget SoA channels, auto-cleared each frame.
 - **Deferred structural changes** — add/remove component and destroy entity are buffered during system execution and flushed between phases.
 - **Topological system ordering** — systems within a phase are sorted by before/after constraints using Kahn's algorithm.
+- **Fixed timestep** — configurable fixed update loop with accumulator and interpolation alpha.
+
+## Installation
+
+Using npm (or equivalent):
+
+```
+npm install @oasys/oecs
+```
 
 ## Quick start
 
 ```ts
-import { World, SCHEDULE } from "@oasys/oecs";
+import { ECS, SCHEDULE } from "@oasys/oecs";
+
+const world = new ECS();
 
-const world = new World();
+// Record syntax — per-field type control
+const Pos = world.register_component({ x: "f64", y: "f64" });
 
-// Define components as field-name arrays
-const Pos = world.register_component(["x", "y"] as const);
+// Array shorthand — uniform type, defaults to "f64"
 const Vel = world.register_component(["vx", "vy"] as const);
 
 // Tags have no fields
 const IsEnemy = world.register_tag();
 
+// Resources are global singletons
+const Time = world.register_resource(["delta", "elapsed"] as const, {
+  delta: 0,
+  elapsed: 0,
+});
+
+// Events are fire-and-forget messages
+const Damage = world.register_event(["target", "amount"] as const);
+
 // Create entities and attach components
 const e = world.create_entity();
 world.add_component(e, Pos, { x: 0, y: 0 });
@@ -32,12 +54,17 @@ world.add_component(e, IsEnemy);
 // Register a system with a typed query
 const moveSys = world.register_system(
   (q, _ctx, dt) => {
-    q.each((pos, vel, n) => {
+    for (const arch of q) {
+      const px = arch.get_column(Pos, "x");
+      const py = arch.get_column(Pos, "y");
+      const vx = arch.get_column(Vel, "vx");
+      const vy = arch.get_column(Vel, "vy");
+      const n = arch.entity_count;
       for (let i = 0; i < n; i++) {
-        pos.x[i] += vel.vx[i] * dt;
-        pos.y[i] += vel.vy[i] * dt;
+        px[i] += vx[i] * dt;
+        py[i] += vy[i] * dt;
       }
-    });
+    }
   },
   (qb) => qb.every(Pos, Vel),
 );
@@ -50,125 +77,105 @@ world.startup();
 
 // Game loop
 function frame(dt: number) {
+  world.set_resource(Time, { delta: dt, elapsed: performance.now() / 1000 });
   world.update(dt);
 }
 ```
 
-## Components
+## World Options
 
-Components are defined as readonly string arrays of field names. All field values are `number`.
+`ECS` accepts an optional configuration object:
 
 ```ts
-const Position = world.register_component(["x", "y"] as const);
-const Health   = world.register_component(["current", "max"] as const);
-const IsEnemy  = world.register_tag(); // no fields
+const world = new ECS({
+  initial_capacity: 4096,  // pre-allocate archetype storage (default: 1024, grows automatically)
+  fixed_timestep: 1 / 50,  // fixed update interval in seconds (default: 1/60)
+  max_fixed_steps: 4,       // cap fixed updates per frame to prevent spiral of death (default: 5)
+});
 ```
 
-The `as const` is required so TypeScript infers the literal tuple type `["x", "y"]` instead of `string[]`. This enables type-safe field access throughout the API.
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `initial_capacity` | `number` | `1024` | Starting size for every archetype's backing typed arrays (entity IDs and all SoA component columns). Arrays double when exceeded — set this close to your expected entity count per archetype to avoid early re-allocations. |
+| `fixed_timestep` | `number` | `1/60` | Interval (seconds) for `FIXED_UPDATE` systems. |
+| `max_fixed_steps` | `number` | `5` | Maximum `FIXED_UPDATE` iterations per frame. |
+
+## Components
 
-### Adding components
+Components map field names to typed array tags. All field values are `number`, but storage uses the specified typed array (`Float64Array`, `Int32Array`, etc.) for cache-friendly iteration.
 
 ```ts
-const e = world.create_entity();
+// Record syntax — per-field type control
+const Position = world.register_component({ x: "f64", y: "f64" });
+const Health = world.register_component({ current: "i32", max: "i32" });
 
-// Data components require a values object
-world.add_component(e, Position, { x: 10, y: 20 });
-world.add_component(e, Health, { current: 100, max: 100 });
+// Array shorthand — all fields default to "f64"
+const Vel = world.register_component(["vx", "vy"] as const);
 
-// Tags require no values
-world.add_component(e, IsEnemy);
+// Tags — no fields
+const IsEnemy = world.register_tag();
+```
+
+Supported typed array tags: `"f32"`, `"f64"`, `"i8"`, `"i16"`, `"i32"`, `"u8"`, `"u16"`, `"u32"`.
+
+Add components individually or via `add_components` (single archetype transition):
 
-// Add multiple at once (single archetype transition)
+```ts
+world.add_component(e, Position, { x: 10, y: 20 });
 world.add_components(e, [
   { def: Position, values: { x: 10, y: 20 } },
   { def: Health, values: { current: 100, max: 100 } },
 ]);
 ```
 
-### Removing and checking components
-
-```ts
-world.remove_component(e, Health);
-world.has_component(e, IsEnemy); // true
-```
+See [docs/api/components.md](docs/api/components.md) for full API.
 
 ## Queries
 
-Queries are live views over all archetypes matching a component mask. They update automatically as new archetypes are created.
-
-### Batch iteration with `each()`
-
-`each()` calls your function once per matching archetype, passing column-group objects and the entity count. You write the inner loop.
+Queries are live views over all archetypes matching a component mask.
 
 ```ts
 const q = world.query(Position, Velocity);
 
-q.each((pos, vel, n) => {
-  // pos.x, pos.y, vel.vx, vel.vy are all number[]
-  // n is the entity count in this archetype
-  for (let i = 0; i < n; i++) {
-    pos.x[i] += vel.vx[i];
-    pos.y[i] += vel.vy[i];
-  }
-});
-```
-
-### Query chaining
-
-```ts
-// Extend required components
-const q = world.query(Position).and(Velocity);
-
-// Exclude archetypes that have a component
-const alive = world.query(Position).not(Dead);
-
-// Require at least one of these
-const damaged = world.query(Health).or(Poison, Fire);
-
-// Combine
-const targets = world.query(Position).and(Health).not(Shield).or(IsEnemy, IsBoss);
-```
-
-### Manual iteration
-
-For dynamic component access, iterate archetypes directly:
-
-```ts
-for (const arch of world.query(Position)) {
+// Iterate non-empty archetypes, access SoA columns, write the inner loop
+for (const arch of q) {
   const px = arch.get_column(Position, "x");
   const py = arch.get_column(Position, "y");
-  const count = arch.entity_count;
-
-  for (let i = 0; i < count; i++) {
-    px[i] += 1;
-    py[i] += 1;
+  const vx = arch.get_column(Velocity, "vx");
+  const vy = arch.get_column(Velocity, "vy");
+  const n = arch.entity_count;
+  for (let i = 0; i < n; i++) {
+    px[i] += vx[i];
+    py[i] += vy[i];
   }
 }
+
+// Chaining
+const targets = world
+  .query(Position)
+  .and(Health)
+  .not(Shield)
+  .any_of(IsEnemy, IsBoss);
 ```
 
+See [docs/api/queries.md](docs/api/queries.md) for full API.
+
 ## Systems
 
 Systems are plain functions registered with a query and scheduled into lifecycle phases.
 
-### Registration
-
-Two registration styles:
-
 ```ts
-// Style 1: Function + query builder (typed, preferred)
+// With a typed query
 const moveSys = world.register_system(
   (q, ctx, dt) => {
-    q.each((pos, vel, n) => {
-      for (let i = 0; i < n; i++) {
-        pos.x[i] += vel.vx[i] * dt;
-        pos.y[i] += vel.vy[i] * dt;
-      }
-    });
+    for (const arch of q) {
+      /* ... */
+    }
   },
   (qb) => qb.every(Pos, Vel),
 );
 
-// Style 2: Config object (for systems that don't need a query)
+// Without a query
 const logSys = world.register_system({
   fn(ctx, dt) {
     console.log("frame", dt);
@@ -176,119 +183,118 @@ const logSys = world.register_system({
 });
 ```
 
-### Deferred operations
-
-Inside systems, use `ctx` (SystemContext) for structural changes. These are buffered and applied between phases.
+Inside systems, use `ctx` for deferred structural changes and per-entity access:
 
 ```ts
-const spawnSys = world.register_system({
-  fn(ctx, _dt) {
-    const e = ctx.create_entity();
-    ctx.add_component(e, Position, { x: 0, y: 0 });
-    ctx.destroy_entity(someOtherEntity);
-    ctx.remove_component(anotherEntity, Health);
-    // Changes are applied after all systems in this phase complete
-  },
-});
+const e = ctx.create_entity();
+ctx.add_component(e, Pos, { x: 0, y: 0 });
+ctx.destroy_entity(someEntity);
+ctx.remove_component(entity, Health);
 ```
 
-### Per-entity field access
+See [docs/api/systems.md](docs/api/systems.md) for full API.
 
-For reading/writing individual entity fields (not batch):
+## Resources
+
+Resources are typed global singletons — time, input state, camera config.
 
 ```ts
-const damageSys = world.register_system({
-  fn(ctx, _dt) {
-    const hp = ctx.get_field(Health, targetEntity, "current");
-    ctx.set_field(Health, targetEntity, "current", hp - 10);
-  },
+const Time = world.register_resource(["delta", "elapsed"] as const, {
+  delta: 0,
+  elapsed: 0,
 });
+
+// Write
+world.set_resource(Time, { delta: dt, elapsed: total });
+
+// Read — scalar values, not arrays
+const time = world.resource(Time);
+time.delta; // number
+time.elapsed; // number
 ```
 
-## Schedule
+See [docs/api/resources.md](docs/api/resources.md) for full API.
+
+## Events & Signals
 
-Six lifecycle phases, executed in order:
+Events are fire-and-forget SoA channels, auto-cleared each frame.
 
-| Phase | When | Use case |
-|---|---|---|
-| `PRE_STARTUP` | Once, before startup | Resource loading, allocation |
-| `STARTUP` | Once | Initial entity spawning |
-| `POST_STARTUP` | Once, after startup | Validation, index building |
-| `PRE_UPDATE` | Every frame, first | Input handling, time management |
-| `UPDATE` | Every frame | Game logic, physics, AI |
-| `POST_UPDATE` | Every frame, last | Rendering, cleanup |
+```ts
+// Data events carry fields
+const Damage = world.register_event(["target", "amount"] as const);
+ctx.emit(Damage, { target: entityId, amount: 50 });
+
+const dmg = ctx.read(Damage);
+for (let i = 0; i < dmg.length; i++) {
+  dmg.target[i]; // number
+  dmg.amount[i]; // number
+}
+
+// Signals carry no data — just a count
+const OnReset = world.register_signal();
+ctx.emit(OnReset);
+if (ctx.read(OnReset).length > 0) {
+  /* fired */
+}
+```
+
+See [docs/api/events.md](docs/api/events.md) for full API.
 
-Deferred changes are flushed automatically after each phase.
+## Refs
+
+Refs provide cached single-entity field access — faster than `get_field`/`set_field` for repeated access.
 
 ```ts
-world.add_systems(SCHEDULE.UPDATE, moveSys, physicsSys);
-world.add_systems(SCHEDULE.POST_UPDATE, renderSys);
+const pos = ctx.ref(Pos, entity);
+const vel = ctx.ref(Vel, entity);
+pos.x += vel.vx * dt;
+pos.y += vel.vy * dt;
 ```
 
-### Ordering constraints
+See [docs/api/refs.md](docs/api/refs.md) for full API.
+
+## Schedule
+
+Seven lifecycle phases, executed in order:
+
+| Phase          | When                  | Use case                |
+| -------------- | --------------------- | ----------------------- |
+| `PRE_STARTUP`  | Once, before startup  | Resource loading        |
+| `STARTUP`      | Once                  | Initial entity spawning |
+| `POST_STARTUP` | Once, after startup   | Validation              |
+| `FIXED_UPDATE` | Every tick (fixed dt) | Physics, simulation     |
+| `PRE_UPDATE`   | Every frame, first    | Input handling          |
+| `UPDATE`       | Every frame           | Game logic              |
+| `POST_UPDATE`  | Every frame, last     | Rendering, cleanup      |
 
 ```ts
+world.add_systems(SCHEDULE.UPDATE, moveSys, physicsSys);
+world.add_systems(SCHEDULE.POST_UPDATE, renderSys);
+
+// Ordering constraints
 world.add_systems(SCHEDULE.UPDATE, moveSys, {
   system: physicsSys,
   ordering: { after: [moveSys] },
 });
-
-world.add_systems(SCHEDULE.UPDATE, {
-  system: aiSys,
-  ordering: { before: [moveSys] },
-});
 ```
 
-Systems with ordering constraints are topologically sorted. Systems with no constraints run in registration order.
+See [docs/api/schedule.md](docs/api/schedule.md) for full API.
 
 ## Entity lifecycle
 
 ```ts
 const e = world.create_entity();
-
 world.is_alive(e); // true
-
-world.destroy_entity(e); // deferred
-world.flush();           // apply now
-
+world.destroy_entity_deferred(e); // deferred
+world.flush();
 world.is_alive(e); // false
 ```
 
-Entity IDs are generational: destroying an entity increments its slot's generation, so stale IDs are safely detected as dead.
-
-## Lifecycle hooks
-
-Systems can define lifecycle hooks:
-
-```ts
-const sys = world.register_system({
-  fn(ctx, dt) { /* runs every frame */ },
-
-  on_added(store) {
-    // Called once during world.startup()
-  },
-
-  on_removed() {
-    // Called when system is unregistered via world.remove_system()
-  },
-
-  dispose() {
-    // Called during world.dispose()
-  },
-});
-```
+Entity IDs are generational: destroying an entity increments its slot's generation, so stale IDs are detected as dead.
 
 ## Dev / Prod modes
 
-The codebase uses `__DEV__` compile-time flags. In development builds, you get:
-
-- Bounds checking on entity IDs
-- Validation on branded type construction
-- Duplicate system detection
-- Circular dependency detection
-- Helpful error messages with context
-
-All dev-only checks are tree-shaken in production builds.
+`__DEV__` compile-time flags enable bounds checking, dead entity detection, and duplicate system detection. Circular dependency detection is always active (not tree-shaken). All other dev checks are tree-shaken in production builds.
 
 ## Development
 
@@ -300,6 +306,8 @@ pnpm build         # vite library build
 pnpm tsc --noEmit  # type check
 ```
 
-## Architecture
+## Guides
 
-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for a thorough explanation of the internal design.
+- [Getting Started](docs/GETTING_STARTED.md) — step-by-step tutorial
+- [Best Practices](docs/BEST_PRACTICES.md) — performance tips and patterns
+- [Architecture](docs/ARCHITECTURE.md) — internal design details

package/dist/archetype.d.ts

@@ -1,41 +1,52 @@
-import { Brand, BitSet } from './type_primitives';
-import { ComponentID, ComponentFields, ComponentDef, ColumnsForSchema } from './component';
+import { Brand, GrowableTypedArray, AnyTypedArray, TypedArrayTag, BitSet } from './type_primitives';
+import { ComponentID, ComponentDef, ComponentSchema, TagToTypedArray } from './component';
 import { EntityID } from './entity';
 export type ArchetypeID = Brand<number, "archetype_id">;
 export declare const as_archetype_id: (value: number) => ArchetypeID;
 export interface ArchetypeEdge {
     add: ArchetypeID | null;
     remove: ArchetypeID | null;
+    /** Pre-computed column mapping for add direction: this → add target. */
+    add_map: Int16Array | null;
+    /** Pre-computed column mapping for remove direction: this → remove target. */
+    remove_map: Int16Array | null;
 }
 export interface ArchetypeColumnLayout {
     component_id: ComponentID;
     field_names: string[];
     field_index: Record<string, number>;
+    field_types: TypedArrayTag[];
 }
 interface ArchetypeColumnGroup {
     layout: ArchetypeColumnLayout;
-    columns: number[][];
-    record: Record<string, number[]>;
+    columns: GrowableTypedArray<AnyTypedArray>[];
 }
 export declare class Archetype {
     readonly id: ArchetypeID;
     readonly mask: BitSet;
     readonly has_columns: boolean;
-    entity_ids: EntityID[];
+    private readonly _entity_ids;
     length: number;
-    private edges;
+    private readonly edges;
+    readonly _flat_columns: GrowableTypedArray<AnyTypedArray>[];
+    readonly _col_offset: number[];
+    readonly _field_count: number[];
+    private readonly _field_index;
+    private readonly _field_names;
     readonly column_groups: (ArchetypeColumnGroup | undefined)[];
-    private _column_ids;
-    constructor(id: ArchetypeID, mask: BitSet, layouts?: ArchetypeColumnLayout[]);
+    readonly _column_ids: number[];
+    constructor(id: ArchetypeID, mask: BitSet, layouts?: ArchetypeColumnLayout[], initial_capacity?: number);
     get entity_count(): number;
-    get entity_list(): readonly EntityID[];
+    /** Raw entity ID buffer. Valid data at indices 0..entity_count-1. */
+    get entity_ids(): Uint32Array;
+    get entity_list(): Uint32Array;
     has_component(id: ComponentID): boolean;
     matches(required: BitSet): boolean;
     /** Get a single field's column. Valid data: indices 0..entity_count-1. */
-    get_column<F extends ComponentFields, Field extends F[number]>(def: ComponentDef<F>, field: Field): number[];
-    /** Get all columns for a component as { fieldName: number[] }. */
-    get_column_group<F extends ComponentFields>(def: ComponentDef<F>): ColumnsForSchema<F>;
+    get_column<S extends ComponentSchema, K extends string & keyof S>(def: ComponentDef<S>, field: K): TagToTypedArray[S[K]];
     write_fields(row: number, component_id: ComponentID, values: Record<string, number>): void;
+    /** Fast positional write: values[i] → field[i] in declaration order. No string lookup. */
+    write_fields_positional(row: number, component_id: ComponentID, values: ArrayLike<number>): void;
     read_field(row: number, component_id: ComponentID, field: string): number;
     /** Copy all shared component columns from source archetype at src_row into dst_row. */
     copy_shared_from(source: Archetype, src_row: number, dst_row: number): void;
@@ -47,15 +58,41 @@ export declare class Archetype {
     /**
      * Remove entity at row via swap-and-pop. Swaps the last entity into the
      * vacated row to keep data dense. Returns the entity_index of the swapped
-     * entity (so Store can update its row), or -1 if no swap was needed.
+     * entity (so Store can update its row), or NO_SWAP if no swap was needed.
      */
     remove_entity(row: number): number;
     /** Tag-optimized add: skip column push entirely (no data to store). */
     add_entity_tag(entity_id: EntityID): number;
     /** Tag-optimized remove via swap-and-pop: skip column swap/pop entirely. */
     remove_entity_tag(row: number): number;
+    /**
+     * Move an entity from src archetype into this archetype in a single pass.
+     * Combines add_entity + copy_shared_from + remove_entity(src).
+     * Uses a pre-computed transition map for branchless column copy.
+     * Writes dst_row to _move_result[0], swapped entity index to _move_result[1].
+     */
+    move_entity_from(src: Archetype, src_row: number, entity_id: EntityID, transition_map: Int16Array): void;
+    /**
+     * Move an entity from src into this archetype (tag-only: no columns to copy).
+     * Writes dst_row to _move_result[0], swapped entity index to _move_result[1].
+     */
+    move_entity_from_tag(src: Archetype, src_row: number, entity_id: EntityID): void;
+    /**
+     * Bulk-move ALL entities from src into this archetype using TypedArray.set().
+     * Much faster than per-entity move_entity_from when the entire source is moving.
+     * After this call, src is empty. Returns the starting dst_row for the batch.
+     */
+    bulk_move_all_from(src: Archetype, transition_map: Int16Array): number;
     get_edge(component_id: ComponentID): ArchetypeEdge | undefined;
     set_edge(component_id: ComponentID, edge: ArchetypeEdge): void;
 }
+/** Reusable result buffer for move_entity_from/move_entity_from_tag. [dst_row, swapped_index] */
+export declare const _move_result: [number, number];
+/**
+ * Build a transition map from src archetype to dst archetype.
+ * For each column in dst, stores the index of the corresponding column in src,
+ * or -1 if the column is new (no source).
+ */
+export declare function build_transition_map(src: Archetype, dst: Archetype): Int16Array;
 export {};
 //# sourceMappingURL=archetype.d.ts.map

package/dist/archetype.d.ts.map

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

package/dist/component.d.ts

@@ -1,18 +1,35 @@
-import { Brand } from './type_primitives';
+import { Brand, TypedArrayTag } from './type_primitives';
 export type ComponentID = Brand<number, "component_id">;
 export declare const as_component_id: (value: number) => ComponentID;
-export type ComponentFields = readonly string[];
-/** Maps component fields to their value object: { x: number, y: number }. */
-export type FieldValues<F extends ComponentFields> = {
-    readonly [K in F[number]]: number;
+/** Core schema type: maps field names to typed array tags. */
+export type ComponentSchema = Readonly<Record<string, TypedArrayTag>>;
+/** Compile-time tag → TypedArray mapping. */
+export type TagToTypedArray = {
+    f32: Float32Array;
+    f64: Float64Array;
+    i8: Int8Array;
+    i16: Int16Array;
+    i32: Int32Array;
+    u8: Uint8Array;
+    u16: Uint16Array;
+    u32: Uint32Array;
+};
+/** Maps schema fields to their value object: { x: number, y: number }. */
+export type FieldValues<S extends ComponentSchema> = {
+    readonly [K in keyof S]: number;
 };
-/** Maps component fields to column arrays: { x: number[], y: number[] }. */
-export type ColumnsForSchema<F extends ComponentFields> = {
-    readonly [K in F[number]]: number[];
+/** Maps schema fields to their specific typed array columns. */
+export type ColumnsForSchema<S extends ComponentSchema> = {
+    readonly [K in keyof S]: TagToTypedArray[S[K]];
+};
+export type ComponentFields = readonly string[];
+/** Maps component fields to column arrays (used by events — always Float64Array). */
+export type ColumnsForFields<F extends ComponentFields> = {
+    readonly [K in F[number]]: Float64Array;
 };
 declare const __schema: unique symbol;
-export type ComponentDef<F extends ComponentFields = ComponentFields> = ComponentID & {
-    readonly [__schema]: F;
+export type ComponentDef<S extends ComponentSchema = ComponentSchema> = ComponentID & {
+    readonly [__schema]: S;
 };
 export {};
 //# sourceMappingURL=component.d.ts.map

package/dist/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;KAkBK;AAEL,OAAO,EACL,KAAK,EAGN,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACxD,eAAO,MAAM,eAAe,UAAW,MAAM,gBAK1C,CAAC;AAEJ,MAAM,MAAM,eAAe,GAAG,SAAS,MAAM,EAAE,CAAC;AAEhD,6EAA6E;AAC7E,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,eAAe,IAAI;IACnD,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,MAAM;CAClC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,eAAe,IAAI;IACxD,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE;CACpC,CAAC;AAKF,OAAO,CAAC,MAAM,QAAQ,EAAE,OAAO,MAAM,CAAC;AAEtC,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAClE,WAAW,GAAG;IAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;KAuBK;AAEL,OAAO,EACL,KAAK,EAGL,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACxD,eAAO,MAAM,eAAe,UAAW,MAAM,gBAK1C,CAAC;AAEJ,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;AAEtE,6CAA6C;AAC7C,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,YAAY,CAAC;IAClB,GAAG,EAAE,YAAY,CAAC;IAClB,EAAE,EAAE,SAAS,CAAC;IACd,GAAG,EAAE,UAAU,CAAC;IAChB,GAAG,EAAE,UAAU,CAAC;IAChB,EAAE,EAAE,UAAU,CAAC;IACf,GAAG,EAAE,WAAW,CAAC;IACjB,GAAG,EAAE,WAAW,CAAC;CAClB,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,eAAe,IAAI;IACnD,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM;CAChC,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,eAAe,IAAI;IACxD,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/C,CAAC;AAGF,MAAM,MAAM,eAAe,GAAG,SAAS,MAAM,EAAE,CAAC;AAEhD,qFAAqF;AACrF,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,eAAe,IAAI;IACxD,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,YAAY;CACxC,CAAC;AAMF,OAAO,CAAC,MAAM,QAAQ,EAAE,OAAO,MAAM,CAAC;AAEtC,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAClE,WAAW,GAAG;IAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC"}