@typeonce/ritmo 0.6.0 → 0.8.0

package/src/internal/order.ts

@@ -0,0 +1,144 @@
+/**
+ * The runtime form of the `Game.System.thisTick` check, for erased schedules
+ * (`tryTick`) and the `this-tick-order` lint. The compile-time form lives in
+ * `Schedule.ts` (`TickOrderErrors`) and produces the same messages.
+ */
+import type { Descriptor } from "../Descriptor.ts"
+import type * as Query from "../Query.ts"
+import * as Schedule from "../Schedule.ts"
+import type { SystemDefinition } from "../System.ts"
+
+type AnySystem = SystemDefinition<any, any, any, any, any>
+type OrderIssue = Schedule.OrderIssue
+type Access = { readonly mode: "read" | "changed" | "write"; readonly descriptor: Descriptor.Any; readonly thisTick?: true }
+type QueryAccess = {
+  readonly thisTick?: true
+  readonly selection: Record<string, { readonly mode?: string; readonly descriptor?: Descriptor.Any }>
+  readonly with: ReadonlyArray<Descriptor.Any>
+  readonly without: ReadonlyArray<Descriptor.Any>
+  readonly filters: ReadonlyArray<Query.Filter<any>>
+}
+/** Every component a filter names: the one of `added` / `changed`, or each member of `anyOf`. */
+const filterNames = (filter: Query.Filter<any>): ReadonlyArray<string> =>
+  filter.kind === "anyOf" ? filter.filters.map((member) => member.descriptor.name) : [filter.descriptor.name]
+type Permission = { readonly permission: string; readonly values: ReadonlyArray<{ readonly name: string }> }
+
+/** One position of a tick: a system, or a point where queued commands are applied. */
+type Item = { readonly kind: "system"; readonly system: AnySystem } | { readonly kind: "flush" }
+
+const accesses = (system: AnySystem): ReadonlyArray<Access> => [
+  ...Object.values(system.spec.events as Record<string, Access>),
+  ...Object.values(system.spec.resources as Record<string, Access>)
+]
+
+const sameData = (left: Descriptor.Any, right: Descriptor.Any): boolean =>
+  left.kind === right.kind && left.name === right.name
+
+const sameSystem = (left: AnySystem, right: AnySystem): boolean => (left.base ?? left) === (right.base ?? right)
+
+/**
+ * The positions of a tick, flattened: an `applyStateTransitions(...)` step
+ * applies queued commands, then runs every schedule of its bundle (as if
+ * each may run), markers inside them included.
+ */
+const flatten = (steps: ReadonlyArray<Schedule.ScheduleStep>): Array<Item> =>
+  steps.flatMap((step): Array<Item> => {
+    if (Schedule.isSystemStep(step)) return [{ kind: "system", system: step as AnySystem }]
+    if (step.kind === "applyDeferred") return [{ kind: "flush" }]
+    const bundle = step.bundle as { readonly entries: ReadonlyArray<{ readonly steps: ReadonlyArray<Schedule.ScheduleStep> }> } | undefined
+    return [{ kind: "flush" }, ...(bundle?.entries ?? []).flatMap((entry) => flatten(entry.steps))]
+  })
+
+const permissionNames = (system: AnySystem, kind: string): Set<string> => {
+  const commands = system.spec.commands as { readonly permissions: ReadonlyArray<Permission> } | undefined
+  return new Set((commands?.permissions ?? []).filter((p) => p.permission === kind).flatMap((p) => p.values.map((value) => value.name)))
+}
+
+/**
+ * Whether a system's declared commands can change what a query sees: spawns
+ * covering every component it requires, or inserts / removes of any
+ * component it names. Despawns never count.
+ */
+const changesQuery = (system: AnySystem, query: QueryAccess): boolean => {
+  const slots = Object.values(query.selection)
+  const required = [
+    ...slots.filter((slot) => slot.mode === "read" || slot.mode === "write").flatMap((slot) => slot.descriptor ? [slot.descriptor.name] : []),
+    ...query.with.map((d) => d.name)
+  ]
+  const named = new Set([
+    ...slots.flatMap((slot) => slot.descriptor ? [slot.descriptor.name] : []),
+    ...query.with.map((d) => d.name),
+    ...query.without.map((d) => d.name),
+    ...query.filters.flatMap((filter) => filterNames(filter))
+  ])
+  const changes = [...permissionNames(system, "inserts"), ...permissionNames(system, "removes")]
+  if (changes.some((name) => named.has(name))) return true
+  const spawns = permissionNames(system, "spawns")
+  return spawns.size > 0 && required.every((name) => spawns.has(name))
+}
+
+/**
+ * Checks the systems of one tick, in the order they run. A read with no
+ * writer in the tick is fine (a reused reader); `event-never-written` covers
+ * a writer missing everywhere.
+ */
+export const tickOrderIssues = (steps: ReadonlyArray<Schedule.ScheduleStep>): ReadonlyArray<OrderIssue> => {
+  // A schedule's steps never change, so `tryTick` checks each schedule once.
+  const cached = checked.get(steps)
+  if (cached !== undefined) return cached
+  const issues = computeIssues(steps)
+  checked.set(steps, issues)
+  return issues
+}
+
+const checked = new WeakMap<ReadonlyArray<Schedule.ScheduleStep>, ReadonlyArray<OrderIssue>>()
+
+const computeIssues = (steps: ReadonlyArray<Schedule.ScheduleStep>): ReadonlyArray<OrderIssue> => {
+  const items = flatten(steps)
+  const issues: Array<OrderIssue> = []
+  const systemsAt = items.flatMap((item, at) => item.kind === "system" ? [{ system: item.system, at }] : [])
+  for (const { system: reader, at: index } of systemsAt) {
+    for (const read of accesses(reader)) {
+      if ((read.mode !== "read" && read.mode !== "changed") || read.thisTick !== true) continue
+      const data = read.descriptor.name
+      for (const { system, at } of systemsAt) {
+        if (at <= index || sameSystem(system, reader)) continue
+        if (!accesses(system).some((access) => access.mode === "write" && sameData(access.descriptor, read.descriptor))) continue
+        issues.push({
+          kind: "lateWriter",
+          reader: reader.name,
+          data,
+          writer: system.name,
+          message: `${reader.name} needs ${data} from this tick, but its writer ${system.name} runs after it: move ${system.name} before ${reader.name}, or read ${data} without thisTick`
+        })
+      }
+    }
+    for (const [slot, query] of Object.entries(reader.spec.queries as Record<string, QueryAccess>)) {
+      if (query.thisTick !== true) continue
+      const data = `queries.${slot}`
+      let lastFlush = -1
+      for (let at = 0; at < index; at++) if (items[at]!.kind === "flush") lastFlush = at
+      for (const { system, at } of systemsAt) {
+        if (sameSystem(system, reader) || !changesQuery(system, query)) continue
+        if (at > index) {
+          issues.push({
+            kind: "lateWriter",
+            reader: reader.name,
+            data,
+            writer: system.name,
+            message: `${system.name} queues commands that ${reader.name} needs this tick (${data}), but it runs after ${reader.name}: move ${system.name} before the applyDeferred() that precedes ${reader.name}, or read ${data} without thisTick`
+          })
+        } else if (at > lastFlush && at < index) {
+          issues.push({
+            kind: "unflushedWriter",
+            reader: reader.name,
+            data,
+            writer: system.name,
+            message: `${reader.name} needs this tick's commands for ${data}, but ${system.name} queues them with no applyDeferred() in between: add Game.Schedule.applyDeferred() after ${system.name}`
+          })
+        }
+      }
+    }
+  }
+  return issues
+}

package/src/internal/queries.ts

@@ -33,7 +33,7 @@ type SlotPlan =
       readonly mode: "write"
       readonly ordinal: number
       readonly constructor: DescriptorModule.ResultConstructor<unknown, unknown, unknown> | undefined
-      readonly state: string | undefined
+      readonly entityState: string | undefined
     }
   | {
       readonly slot: string
@@ -46,6 +46,9 @@ interface LifecycleFilterPlan {
   readonly ordinal: number
 }
 
+/** A query filter: one lifecycle filter, or `anyOf` several (passes when one does). */
+type FilterPlan = ReadonlyArray<LifecycleFilterPlan>
+
 interface QueryState {
   readonly ordinal: number
   readonly required: ReadonlyArray<number>
@@ -54,7 +57,7 @@ interface QueryState {
   readonly withoutRelations: ReadonlyArray<Relation.Relation.Any>
   readonly withRelated: ReadonlyArray<Relation.Relation.Any>
   readonly withoutRelated: ReadonlyArray<Relation.Relation.Any>
-  readonly filters: ReadonlyArray<LifecycleFilterPlan>
+  readonly filters: ReadonlyArray<FilterPlan>
   readonly slots: ReadonlyArray<SlotPlan>
   readonly proofSlots: ReadonlyArray<readonly [string, number]>
   readonly writeSlots: ReadonlyArray<readonly [string, number]>
@@ -143,7 +146,7 @@ export const makeQueryEngine = (world: World) => {
               mode: "write",
               ordinal,
               constructor: DescriptorModule.constructorOf(access.descriptor),
-              state: DescriptorModule.isState(access.descriptor) ? access.descriptor.name : undefined
+              entityState: DescriptorModule.isEntityState(access.descriptor) ? access.descriptor.name : undefined
             })
           } else {
             slots.push({ slot, mode: "read", ordinal })
@@ -185,11 +188,13 @@ export const makeQueryEngine = (world: World) => {
       withoutRelations: query.withoutRelations,
       withRelated: unique(withRelated),
       withoutRelated: query.withoutRelated,
-      filters: query.filters.map((filter) => {
-        const ordinal = world.ordinalOf(filter.descriptor)
-        world.trackChanges(ordinal)
-        return { kind: filter.kind, ordinal }
-      }),
+      filters: query.filters.map((filter) =>
+        (filter.kind === "anyOf" ? filter.filters : [filter]).map((member) => {
+          const ordinal = world.ordinalOf(member.descriptor)
+          world.trackChanges(ordinal)
+          return { kind: member.kind, ordinal }
+        })
+      ),
       slots,
       proofSlots,
       writeSlots,
@@ -239,14 +244,33 @@ export const makeQueryEngine = (world: World) => {
 
   const matchesFilters = (state: QueryState, record: EntityRecord, since: number): boolean => {
     for (const filter of state.filters) {
-      const matched = filter.kind === "added"
-        ? world.addedSince(record, filter.ordinal, since)
-        : world.changedSince(record, filter.ordinal, since)
+      let matched = false
+      for (const member of filter) {
+        matched = member.kind === "added"
+          ? world.addedSince(record, member.ordinal, since)
+          : world.changedSince(record, member.ordinal, since)
+        if (matched) break
+      }
       if (!matched) return false
     }
     return true
   }
 
+  /**
+   * Ids that may pass one filter (may repeat), or `undefined` when a change
+   * log no longer covers `since`. An `anyOf` is the union of its members' logs.
+   */
+  const filterCandidates = (filter: FilterPlan, since: number): ReadonlyArray<number> | undefined => {
+    if (filter.length === 1) return world.changedCandidates(filter[0]!.ordinal, since)
+    const union: Array<number> = []
+    for (const member of filter) {
+      const logged = world.changedCandidates(member.ordinal, since)
+      if (logged === undefined) return undefined
+      for (const id of logged) union.push(id)
+    }
+    return union
+  }
+
   const relatedIds = (relation: Relation.Relation.Any, id: number): ReadonlyArray<Entity.EntityId<any, any>> =>
     world.relatedSourceIds(relation, id).map(world.entityIdOf)
 
@@ -255,7 +279,7 @@ export const makeQueryEngine = (world: World) => {
       case "read":
         return Cells.componentRead(record, plan.ordinal)
       case "write":
-        return Cells.componentWrite(record, plan.ordinal, world, plan.constructor, plan.state)
+        return Cells.componentWrite(record, plan.ordinal, world, plan.constructor, plan.entityState)
       case "optional":
         return Cells.componentOptional(record, plan.ordinal)
       case "readRelation":
@@ -426,7 +450,7 @@ export const makeQueryEngine = (world: World) => {
     // bounds the candidates for either filter.
     let candidates: ReadonlyArray<number> | undefined
     for (const filter of state.filters) {
-      const logged = world.changedCandidates(filter.ordinal, since)
+      const logged = filterCandidates(filter, since)
       if (logged === undefined) continue
       if (logged.length === 0) return []
       if (candidates === undefined || logged.length < candidates.length) candidates = logged

package/src/internal/requirements.ts

@@ -0,0 +1,71 @@
+/**
+ * Runtime side of `Schema.requires`: the requirement index built once per
+ * bound schema, used to expand `Game.System.spawns(...)`, to check commands
+ * when they are applied, and to check restored entities.
+ *
+ * The compile-time counterpart lives in `Command.ts` (spawn, insert, remove)
+ * and `Schema.ts` (`ValidateRequires`).
+ */
+import type { Descriptor } from "../Descriptor.ts"
+import type { Schema } from "../Schema.ts"
+
+type ComponentDescriptor = Descriptor<"component", string, any>
+
+export interface RequirementIndex {
+  /** Whether the schema declares any requirement. */
+  readonly empty: boolean
+  /** Component name to the components it directly requires. */
+  readonly requires: ReadonlyMap<string, ReadonlyArray<ComponentDescriptor>>
+  /** Component name to the components that directly require it. */
+  readonly requiredBy: ReadonlyMap<string, ReadonlyArray<ComponentDescriptor>>
+}
+
+const push = (map: Map<string, Array<ComponentDescriptor>>, key: string, value: ComponentDescriptor): void => {
+  const list = map.get(key)
+  if (list === undefined) map.set(key, [value])
+  else if (!list.some((entry) => entry.name === value.name)) list.push(value)
+}
+
+export const requirementIndex = (schema: Schema.Any): RequirementIndex => {
+  const requires = new Map<string, Array<ComponentDescriptor>>()
+  const requiredBy = new Map<string, Array<ComponentDescriptor>>()
+  for (const requirement of schema.requires) {
+    for (const required of requirement.required) {
+      push(requires, requirement.component.name, required)
+      push(requiredBy, required.name, requirement.component)
+    }
+  }
+  return { empty: requires.size === 0, requires, requiredBy }
+}
+
+/** `components` and everything they require, transitively, without duplicates. */
+export const withRequired = (
+  index: RequirementIndex,
+  components: ReadonlyArray<ComponentDescriptor>
+): ReadonlyArray<ComponentDescriptor> => {
+  if (index.empty) return components
+  const result: Array<ComponentDescriptor> = []
+  const seen = new Set<string>()
+  const visit = (descriptor: ComponentDescriptor): void => {
+    if (seen.has(descriptor.name)) return
+    seen.add(descriptor.name)
+    result.push(descriptor)
+    for (const required of index.requires.get(descriptor.name) ?? []) visit(required)
+  }
+  components.forEach(visit)
+  return result
+}
+
+/** The first requirement `held` breaks, as `[requirer, missing]`, or `undefined`. */
+export const firstMissing = (
+  index: RequirementIndex,
+  held: (name: string) => boolean,
+  names: Iterable<string>
+): readonly [string, string] | undefined => {
+  for (const name of names) {
+    for (const required of index.requires.get(name) ?? []) {
+      if (!held(required.name)) return [name, required.name]
+    }
+  }
+  return undefined
+}

package/dist/Definition.d.ts

@@ -1,99 +0,0 @@
-/**
- * Helpers for validating reusable authored values once and reusing them later.
- *
- * `Definition` is intended for static or rarely changing authored data such as
- * spawn points, collider sizes, arena bounds, or other constants that should
- * cross the validation boundary once and then remain branded afterward.
- *
- * In game code this is the "content setup" companion to runtime/world setup:
- * validate authored constants early, keep them in carried form, and then reuse
- * them from setup systems, reset systems, or content modules without
- * revalidating on every frame.
- *
- * @example
- * ```ts
- * // Validate authored constants once when defining the content bundle.
- * const player = Definition.all({
- *   spawn: Definition.entry(Vector2, { x: 32, y: 48 }),
- *   size: Definition.entry(Size2, { width: 16, height: 16 })
- * })
- * ```
- *
- * @module Definition
- * @docGroup core
- *
- * @categoryDescription Definition Types
- * Named reusable shapes used to validate and retain authored values.
- *
- * @categoryDescription Definition Builders
- * Helpers that validate one or several authored values through existing constructors.
- */
-import * as internal from "./internal/definition.ts";
-import type * as Result from "./Result.ts";
-/**
- * One reusable validated definition entry.
- *
- * @category Definition Types
- */
-export type Entry<Value, Error> = internal.Entry<Value, Error>;
-/**
- * Record of named definition entries accepted by {@link all}.
- *
- * @category Definition Types
- */
-export type Entries = internal.Entries;
-/**
- * Minimal constructor contract accepted by {@link entry}.
- *
- * @category Definition Types
- */
-export type ResultConstructor<Value, Raw, Error> = internal.ResultConstructor<Value, Raw, Error>;
-/**
- * Success shape produced by {@link all}.
- *
- * @category Definition Types
- */
-export type SuccessOf<Input extends Entries> = internal.SuccessOf<Input>;
-/**
- * Error shape produced by {@link all}.
- *
- * @category Definition Types
- */
-export type ErrorOf<Input extends Entries> = internal.ErrorOf<Input>;
-/**
- * Validates one reusable authored value through an existing constructor.
- *
- * Use this for one named authored constant that should cross a constructor
- * boundary now and remain in carried form afterward.
- *
- * @example
- * ```ts
- * // Validate a single authored position once during content setup.
- * const playerSpawn = Definition.entry(Vector2, { x: 32, y: 48 })
- * ```
- *
- * @category Definition Builders
- */
-export declare const entry: <Value, Raw, Error>(constructor: ResultConstructor<Value, Raw, Error>, raw: Raw) => Entry<Value, Error>;
-/**
- * Validates a named record of reusable authored values at once.
- *
- * Successful entries are returned under the same keys. Failed entries remain
- * keyed so authored-data setup can report exactly which constant was invalid.
- *
- * Use this when one content bundle or level definition should either validate
- * as a whole or report a structured set of authoring failures.
- *
- * @example
- * ```ts
- * // Validate one authored content bundle and keep failures keyed by field.
- * const definitions = Definition.all({
- *   spawn: Definition.entry(Vector2, { x: 32, y: 48 }),
- *   collider: Definition.entry(Size2, { width: 16, height: 16 })
- * })
- * ```
- *
- * @category Definition Builders
- */
-export declare const all: <Input extends Entries>(input: Input) => Result.Result<SuccessOf<Input>, ErrorOf<Input>>;
-//# sourceMappingURL=Definition.d.ts.map

package/dist/Definition.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Definition.d.ts","sourceRoot":"","sources":["../src/Definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,QAAQ,MAAM,0BAA0B,CAAA;AACpD,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAA;AAE1C;;;;GAIG;AACH,MAAM,MAAM,KAAK,CAAC,KAAK,EAAE,KAAK,IAAI,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;AAC9D;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAA;AACtC;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,IAAI,QAAQ,CAAC,iBAAiB,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;AAChG;;;;GAIG;AACH,MAAM,MAAM,SAAS,CAAC,KAAK,SAAS,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;AACxE;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,KAAK,SAAS,OAAO,IAAI,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAEpE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,KAAK,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,EACpC,WAAW,EAAE,iBAAiB,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,EACjD,GAAG,EAAE,GAAG,KACL,KAAK,CAAC,KAAK,EAAE,KAAK,CAAkB,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,GAAG,EAAE,CAAC,KAAK,SAAS,OAAO,EACtC,KAAK,EAAE,KAAK,KACT,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAgB,CAAA"}

package/dist/Definition.js

@@ -1,68 +0,0 @@
-/**
- * Helpers for validating reusable authored values once and reusing them later.
- *
- * `Definition` is intended for static or rarely changing authored data such as
- * spawn points, collider sizes, arena bounds, or other constants that should
- * cross the validation boundary once and then remain branded afterward.
- *
- * In game code this is the "content setup" companion to runtime/world setup:
- * validate authored constants early, keep them in carried form, and then reuse
- * them from setup systems, reset systems, or content modules without
- * revalidating on every frame.
- *
- * @example
- * ```ts
- * // Validate authored constants once when defining the content bundle.
- * const player = Definition.all({
- *   spawn: Definition.entry(Vector2, { x: 32, y: 48 }),
- *   size: Definition.entry(Size2, { width: 16, height: 16 })
- * })
- * ```
- *
- * @module Definition
- * @docGroup core
- *
- * @categoryDescription Definition Types
- * Named reusable shapes used to validate and retain authored values.
- *
- * @categoryDescription Definition Builders
- * Helpers that validate one or several authored values through existing constructors.
- */
-import * as internal from "./internal/definition.js";
-/**
- * Validates one reusable authored value through an existing constructor.
- *
- * Use this for one named authored constant that should cross a constructor
- * boundary now and remain in carried form afterward.
- *
- * @example
- * ```ts
- * // Validate a single authored position once during content setup.
- * const playerSpawn = Definition.entry(Vector2, { x: 32, y: 48 })
- * ```
- *
- * @category Definition Builders
- */
-export const entry = internal.entry;
-/**
- * Validates a named record of reusable authored values at once.
- *
- * Successful entries are returned under the same keys. Failed entries remain
- * keyed so authored-data setup can report exactly which constant was invalid.
- *
- * Use this when one content bundle or level definition should either validate
- * as a whole or report a structured set of authoring failures.
- *
- * @example
- * ```ts
- * // Validate one authored content bundle and keep failures keyed by field.
- * const definitions = Definition.all({
- *   spawn: Definition.entry(Vector2, { x: 32, y: 48 }),
- *   collider: Definition.entry(Size2, { width: 16, height: 16 })
- * })
- * ```
- *
- * @category Definition Builders
- */
-export const all = internal.all;
-//# sourceMappingURL=Definition.js.map

package/dist/Definition.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Definition.js","sourceRoot":"","sources":["../src/Definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,QAAQ,MAAM,0BAA0B,CAAA;AAkCpD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,KAAK,GAGS,QAAQ,CAAC,KAAK,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,GAAG,GAEuC,QAAQ,CAAC,GAAG,CAAA"}

package/dist/Feature.d.ts

@@ -1,106 +0,0 @@
-import type * as Schedule from "./Schedule.ts";
-import type { MergeSchemaDefinitions, Schema, SchemaDefinition, ValidateFragments } from "./Schema.ts";
-type EmptySchema = SchemaDefinition<{}, {}, {}, {}>;
-type AnyFeature = {
-    readonly kind: "feature";
-    readonly name: string;
-    readonly schema: Schema.Any;
-    readonly requires: ReadonlyArray<AnyFeature>;
-    readonly build: unknown;
-    readonly output: FeatureBuildOutput;
-};
-type AnySchedule = Schedule.ScheduleDefinition<any, any, any, any, any>;
-/**
- * What a feature builder returns: bootstrap and update schedules, plus any
- * other values the feature wants to expose on the composed project.
- */
-export type FeatureBuildOutput = {
-    readonly bootstrap?: ReadonlyArray<AnySchedule>;
-    readonly update?: ReadonlyArray<AnySchedule>;
-};
-/**
- * The bound authoring surface a feature builder receives. It is the normal
- * `Game` API restricted to the descriptors the feature can see; runtimes are
- * built from the composed project instead.
- */
-export type FeatureBuildGame<Accessible extends Schema.Any, Root = unknown> = Omit<Schema.Game<Accessible, Root>, "Runtime">;
-type FeatureBuildFunction<Accessible extends Schema.Any, Output extends FeatureBuildOutput = FeatureBuildOutput> = (Game: FeatureBuildGame<Accessible>) => Output;
-export interface FeatureDefinition<Name extends string = string, FeatureSchema extends Schema.Any = Schema.Any, Requires extends ReadonlyArray<AnyFeature> = ReadonlyArray<AnyFeature>, Output extends FeatureBuildOutput = FeatureBuildOutput> {
-    readonly kind: "feature";
-    readonly name: Name;
-    readonly schema: FeatureSchema;
-    readonly requires: Requires;
-    readonly build: FeatureBuildFunction<MergeSchemaDefinitions<FeatureSchema, MergeFeatureSchemas<Requires>>, Output>;
-    readonly output: Output;
-}
-type MergeFeatureSchemas<Features extends ReadonlyArray<AnyFeature>> = Features extends readonly [infer Head extends AnyFeature, ...infer Tail extends Array<AnyFeature>] ? MergeSchemaDefinitions<FeatureClosureSchema<Head>, MergeFeatureSchemas<Tail>> : EmptySchema;
-type FeatureClosureSchema<F extends AnyFeature> = F extends FeatureDefinition<any, infer FeatureSchema extends Schema.Any, infer Requires extends ReadonlyArray<AnyFeature>, any> ? MergeSchemaDefinitions<FeatureSchema, MergeFeatureSchemas<Requires>> : EmptySchema;
-type FeatureNames<Features extends ReadonlyArray<AnyFeature>> = Features[number]["name"];
-type DuplicateFeatureNames<Features extends ReadonlyArray<AnyFeature>, Seen extends string = never> = Features extends readonly [infer Head extends AnyFeature, ...infer Tail extends Array<AnyFeature>] ? Head["name"] extends Seen ? Head["name"] | DuplicateFeatureNames<Tail, Seen> : DuplicateFeatureNames<Tail, Seen | Head["name"]> : never;
-type MissingFeatureDependencies<Features extends ReadonlyArray<AnyFeature>> = Exclude<Features[number]["requires"][number]["name"], FeatureNames<Features>>;
-type FeatureSchemas<Features extends ReadonlyArray<AnyFeature>> = {
-    readonly [K in keyof Features]: Features[K]["schema"];
-};
-/**
- * Rejects duplicate feature names, missing required features, and schema
- * fragments whose keys or descriptor names collide.
- */
-type ValidateFeatureSelection<Features extends ReadonlyArray<AnyFeature>> = [
-    DuplicateFeatureNames<Features>
-] extends [never] ? [MissingFeatureDependencies<Features>] extends [never] ? ValidateFragments<FeatureSchemas<Features>> : {
-    readonly __fixFeatureDependencies__: MissingFeatureDependencies<Features>;
-} : {
-    readonly __fixFeatureSelection__: DuplicateFeatureNames<Features>;
-};
-type RebindFeatureSchedule<ScheduleValue, S extends Schema.Any, Root> = ScheduleValue extends Schedule.ScheduleDefinition<any, infer Requirements, any, infer Carried, infer Failure> ? Schedule.ScheduleDefinition<S, Requirements, Root, Carried, Failure> : never;
-type FeatureScheduleArray<Output, Key extends "bootstrap" | "update"> = Key extends keyof Output ? Extract<Output[Key], ReadonlyArray<AnySchedule>> : readonly [];
-type NormalizeFeatureOutput<Output extends object, S extends Schema.Any, Root> = {
-    readonly [K in Exclude<keyof Output, "bootstrap" | "update">]: Output[K];
-} & {
-    readonly bootstrap: ReadonlyArray<RebindFeatureSchedule<FeatureScheduleArray<Output, "bootstrap">[number], S, Root>>;
-    readonly update: ReadonlyArray<RebindFeatureSchedule<FeatureScheduleArray<Output, "update">[number], S, Root>>;
-};
-type FeatureOutputRecord<Features extends ReadonlyArray<AnyFeature>, S extends Schema.Any, Root> = {
-    readonly [K in FeatureNames<Features>]: NormalizeFeatureOutput<Extract<Features[number], {
-        readonly name: K;
-    }>["output"], S, Root>;
-};
-/**
- * The result of composing features: the merged schema, the bound `Game`,
- * each feature's normalized output, and the aggregated schedules in feature
- * order.
- */
-export interface ComposedFeatureProject<Features extends ReadonlyArray<AnyFeature>, Root = unknown, S extends Schema.Any = MergeFeatureSchemas<Features>> {
-    readonly schema: S;
-    readonly Game: Schema.Game<S, Root>;
-    readonly features: FeatureOutputRecord<Features, S, Root>;
-    readonly schedules: {
-        readonly bootstrap: ReadonlyArray<FeatureOutputRecord<Features, S, Root>[FeatureNames<Features>]["bootstrap"][number]>;
-        readonly update: ReadonlyArray<FeatureOutputRecord<Features, S, Root>[FeatureNames<Features>]["update"][number]>;
-    };
-}
-/**
- * Defines one pre-bind feature.
- */
-export declare const define: <const Name extends string, FeatureSchema extends Schema.Any, const Requires extends ReadonlyArray<AnyFeature> = [], Output extends FeatureBuildOutput = FeatureBuildOutput>(name: Name, options: {
-    readonly schema: FeatureSchema;
-    readonly requires?: Requires;
-    readonly build: FeatureBuildFunction<MergeSchemaDefinitions<FeatureSchema, MergeFeatureSchemas<Requires>>, Output>;
-}) => FeatureDefinition<Name, FeatureSchema, Requires, Output>;
-/**
- * Composes features into one merged schema and one bound `Game`, then builds
- * every feature against it.
- *
- * Aggregated schedule order is the selected feature order, not dependency
- * order. Run them with `runtime.tick(...project.schedules.update)`.
- */
-export declare const compose: <Root, const Features extends readonly [AnyFeature, ...Array<AnyFeature>]>(options: {
-    readonly root: Root;
-    readonly features: Features;
-} & ValidateFeatureSelection<Features>) => ComposedFeatureProject<Features, Root>;
-export declare const Feature: {
-    define: typeof define;
-    compose: typeof compose;
-};
-export {};
-//# sourceMappingURL=Feature.d.ts.map

package/dist/Feature.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Feature.d.ts","sourceRoot":"","sources":["../src/Feature.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,KAAK,QAAQ,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEtG,KAAK,WAAW,GAAG,gBAAgB,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;AAEnD,KAAK,UAAU,GAAG;IAChB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,UAAU,CAAC,CAAA;IAC5C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CACpC,CAAA;AAED,KAAK,WAAW,GAAG,QAAQ,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAEvE;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;CAC7C,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,UAAU,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,IACxE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC,CAAA;AAEhD,KAAK,oBAAoB,CACvB,UAAU,SAAS,MAAM,CAAC,GAAG,EAC7B,MAAM,SAAS,kBAAkB,GAAG,kBAAkB,IACpD,CAAC,IAAI,EAAE,gBAAgB,CAAC,UAAU,CAAC,KAAK,MAAM,CAAA;AAElD,MAAM,WAAW,iBAAiB,CAChC,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,aAAa,SAAS,MAAM,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,EAC7C,QAAQ,SAAS,aAAa,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,EACtE,MAAM,SAAS,kBAAkB,GAAG,kBAAkB;IAEtD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC,sBAAsB,CAAC,aAAa,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;IAClH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,KAAK,mBAAmB,CAAC,QAAQ,SAAS,aAAa,CAAC,UAAU,CAAC,IACjE,QAAQ,SAAS,SAAS,CAAC,MAAM,IAAI,SAAS,UAAU,EAAE,GAAG,MAAM,IAAI,SAAS,KAAK,CAAC,UAAU,CAAC,CAAC,GAC9F,sBAAsB,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE,mBAAmB,CAAC,IAAI,CAAC,CAAC,GAC7E,WAAW,CAAA;AAEjB,KAAK,oBAAoB,CAAC,CAAC,SAAS,UAAU,IAC5C,CAAC,SAAS,iBAAiB,CAAC,GAAG,EAAE,MAAM,aAAa,SAAS,MAAM,CAAC,GAAG,EAAE,MAAM,QAAQ,SAAS,aAAa,CAAC,UAAU,CAAC,EAAE,GAAG,CAAC,GAC3H,sBAAsB,CAAC,aAAa,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC,GACpE,WAAW,CAAA;AAEjB,KAAK,YAAY,CAAC,QAAQ,SAAS,aAAa,CAAC,UAAU,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAA;AAExF,KAAK,qBAAqB,CACxB,QAAQ,SAAS,aAAa,CAAC,UAAU,CAAC,EAC1C,IAAI,SAAS,MAAM,GAAG,KAAK,IACzB,QAAQ,SAAS,SAAS,CAAC,MAAM,IAAI,SAAS,UAAU,EAAE,GAAG,MAAM,IAAI,SAAS,KAAK,CAAC,UAAU,CAAC,CAAC,GAClG,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,GACvB,IAAI,CAAC,MAAM,CAAC,GAAG,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,GAChD,qBAAqB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAClD,KAAK,CAAA;AAET,KAAK,0BAA0B,CAAC,QAAQ,SAAS,aAAa,CAAC,UAAU,CAAC,IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAA;AAE/E,KAAK,cAAc,CAAC,QAAQ,SAAS,aAAa,CAAC,UAAU,CAAC,IAAI;IAChE,QAAQ,EAAE,CAAC,IAAI,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;CACtD,CAAA;AAED;;;GAGG;AACH,KAAK,wBAAwB,CAAC,QAAQ,SAAS,aAAa,CAAC,UAAU,CAAC,IACtE;IAAC,qBAAqB,CAAC,QAAQ,CAAC;CAAC,SAAS,CAAC,KAAK,CAAC,GAC7C,CAAC,0BAA0B,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACpD,iBAAiB,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,GAC3C;IAAE,QAAQ,CAAC,0BAA0B,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAA;CAAE,GAC/E;IAAE,QAAQ,CAAC,uBAAuB,EAAE,qBAAqB,CAAC,QAAQ,CAAC,CAAA;CAAE,CAAA;AAE3E,KAAK,qBAAqB,CAAC,aAAa,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI,IAClE,aAAa,SAAS,QAAQ,CAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM,YAAY,EAAE,GAAG,EAAE,MAAM,OAAO,EAAE,MAAM,OAAO,CAAC,GACzG,QAAQ,CAAC,kBAAkB,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,GACpE,KAAK,CAAA;AAEX,KAAK,oBAAoB,CAAC,MAAM,EAAE,GAAG,SAAS,WAAW,GAAG,QAAQ,IAClE,GAAG,SAAS,MAAM,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC,GAChD,SAAS,EAAE,CAAA;AAEjB,KAAK,sBAAsB,CAAC,MAAM,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI,IAAI;IAC/E,QAAQ,EAAE,CAAC,IAAI,OAAO,CAAC,MAAM,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;CACzE,GAAG;IACF,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,qBAAqB,CAAC,oBAAoB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAA;IACpH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,qBAAqB,CAAC,oBAAoB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAA;CAC/G,CAAA;AAED,KAAK,mBAAmB,CAAC,QAAQ,SAAS,aAAa,CAAC,UAAU,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI,IAAI;IACjG,QAAQ,EAAE,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,GACnC,sBAAsB,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC;CAC7F,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB,CACrC,QAAQ,SAAS,aAAa,CAAC,UAAU,CAAC,EAC1C,IAAI,GAAG,OAAO,EACd,CAAC,SAAS,MAAM,CAAC,GAAG,GAAG,mBAAmB,CAAC,QAAQ,CAAC;IAEpD,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;IACnC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC,QAAQ,EAAE,CAAC,EAAE,IAAI,CAAC,CAAA;IACzD,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,mBAAmB,CAAC,QAAQ,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;QACtH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,mBAAmB,CAAC,QAAQ,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;KACjH,CAAA;CACF;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,GACjB,KAAK,CAAC,IAAI,SAAS,MAAM,EACzB,aAAa,SAAS,MAAM,CAAC,GAAG,EAChC,KAAK,CAAC,QAAQ,SAAS,aAAa,CAAC,UAAU,CAAC,GAAG,EAAE,EACrD,MAAM,SAAS,kBAAkB,GAAG,kBAAkB,QAEhD,IAAI,WACD;IACP,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC,sBAAsB,CAAC,aAAa,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;CACnH,KACA,iBAAiB,CAAC,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,CAOxD,CAAA;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,GAClB,IAAI,EACJ,KAAK,CAAC,QAAQ,SAAS,SAAS,CAAC,UAAU,EAAE,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,WACzD;IACT,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAC5B,GAAG,wBAAwB,CAAC,QAAQ,CAAC,KAAG,sBAAsB,CAAC,QAAQ,EAAE,IAAI,CAwC7E,CAAA;AAED,eAAO,MAAM,OAAO;;;CAGnB,CAAA"}