@typeonce/ritmo 0.6.0 → 0.7.0

package/src/internal/debug.ts

@@ -11,6 +11,7 @@ import type * as Machine from "../Machine.ts"
 import type * as Query from "../Query.ts"
 import type * as Relation from "../Relation.ts"
 import * as Schedule from "../Schedule.ts"
+import * as OrderInternal from "./order.ts"
 import type { Schema } from "../Schema.ts"
 import type { SystemDefinition } from "../System.ts"
 
@@ -114,6 +115,30 @@ const describeQuery = (slot: string, query: Query.Query.Any<any>): Debug.QueryDe
 }
 
 type Mode = { readonly mode: "read" | "write"; readonly descriptor: Descriptor.Any }
+type CommandAccess = { readonly permissions: ReadonlyArray<{ readonly permission: keyof Debug.CommandPermissions; readonly values: ReadonlyArray<{ readonly name: string }> }> }
+
+const permissionsOf = (access: CommandAccess | undefined): Debug.CommandPermissions => {
+  const of = (kind: keyof Debug.CommandPermissions) =>
+    [...new Set((access?.permissions ?? []).filter((p) => p.permission === kind).flatMap((p) => p.values.map((value) => value.name)))]
+  return {
+    spawns: of("spawns"),
+    inserts: of("inserts"),
+    removes: of("removes"),
+    despawns: of("despawns"),
+    despawnsScope: of("despawnsScope"),
+    relates: of("relates")
+  }
+}
+
+const permissionVerb: Record<keyof Debug.CommandPermissions, string> = {
+  spawns: "spawn",
+  inserts: "insert",
+  removes: "remove",
+  despawns: "despawn",
+  despawnsScope: "despawn the scope",
+  relates: "relate"
+}
+type ThisTickAccess = Mode & { readonly thisTick?: true }
 
 export const describeSystem = (system: AnySystem, placements: ReadonlyArray<string>): Debug.SystemDescription => {
   const spec = system.spec
@@ -148,7 +173,16 @@ export const describeSystem = (system: AnySystem, placements: ReadonlyArray<stri
     removed: names(spec.removed as Record<string, { readonly descriptor: Descriptor.Any }>, (access) => access.descriptor.name),
     despawned: Object.keys(spec.despawned).length > 0,
     relationFailures: names(spec.relationFailures as Record<string, { readonly relation: Relation.Relation.Any }>, (access) => access.relation.name),
+    thisTick: [
+      ...[...Object.values(spec.events as Record<string, ThisTickAccess>), ...Object.values(spec.resources as Record<string, ThisTickAccess>)]
+        .filter((access) => access.thisTick === true)
+        .map((access) => access.descriptor.name),
+      ...Object.entries(spec.queries as Record<string, { readonly thisTick?: true }>)
+        .filter(([, query]) => query.thisTick === true)
+        .map(([slot]) => `queries.${slot}`)
+    ],
     services: names(spec.services as Record<string, { readonly descriptor: Descriptor.Any }>, (access) => access.descriptor.name),
+    commands: permissionsOf(spec.commands as CommandAccess | undefined),
     when: (spec.when as ReadonlyArray<Machine.Condition>).map(renderCondition),
     pauseWhen: (spec.pauseWhen as ReadonlyArray<Machine.Condition>).map(renderCondition),
     local: spec.local !== undefined
@@ -228,6 +262,12 @@ export interface DescribeInput {
   readonly currentMachine: (machine: Machine.StateMachine.Any) => Machine.StateValue | undefined
   readonly providedServices: ReadonlyArray<string>
   readonly externallyWrittenEvents: ReadonlySet<string>
+  /** Relations commands have tried to relate or reorder, by the queuing systems. */
+  readonly relationMutations: ReadonlyMap<string, ReadonlySet<string>>
+  /** What each system's applied commands did, as `kind:name`; see `Runtime`. */
+  readonly commandUses: ReadonlyMap<string, ReadonlySet<string>>
+  /** Systems that ran in this session. */
+  readonly ranSystems: ReadonlySet<string>
   readonly hasResource: (descriptor: Descriptor.Any) => boolean
   readonly schedules: ReadonlyArray<readonly [string, AnySchedule]>
 }
@@ -269,6 +309,7 @@ export const describe = (input: DescribeInput): Debug.Description => {
       }
     }
     for (const name of system.removed) components.read(name, system.name)
+    for (const name of [...system.commands.spawns, ...system.commands.inserts, ...system.commands.removes]) components.write(name, system.name)
     for (const name of system.resources.reads) resources.read(name, system.name)
     for (const name of system.resources.writes) resources.write(name, system.name)
     for (const name of system.events.reads) events.read(name, system.name)
@@ -283,7 +324,7 @@ export const describe = (input: DescribeInput): Debug.Description => {
   const appliesTransitions = schedules.some(([, schedule]) =>
     schedule.steps.some((step) => !Schedule.isSystemStep(step) && step.kind === "applyStateTransitions"))
 
-  const lints: Array<Debug.Lint> = []
+  const lints: Array<Omit<Debug.Lint, "fix">> = []
   if (schedules.length > 0) {
     for (const entry of events.list()) {
       if (entry.writers.length > 0 && entry.readers.length === 0) {
@@ -313,7 +354,44 @@ export const describe = (input: DescribeInput): Debug.Description => {
         })
       }
     }
+    const failureReaders = new Set(systems.flatMap((system) => system.relationFailures))
+    // Declared `relates` permissions, and relations that commands were seen to relate (drafts relate without one).
+    const relaters = new Map<string, Set<string>>()
+    for (const system of systems) {
+      for (const name of system.commands.relates) relaters.set(name, new Set([...(relaters.get(name) ?? []), system.name]))
+    }
+    for (const [name, queuers] of input.relationMutations) relaters.set(name, new Set([...(relaters.get(name) ?? []), ...queuers]))
+    for (const [name, queuers] of relaters) {
+      if (failureReaders.has(name)) continue
+      lints.push({
+        severity: "warning",
+        code: "relation-failure-never-read",
+        subject: name,
+        message: `${name} is related by commands from ${[...queuers].sort().join(", ")}, but no described system reads its failures (Game.System.readRelationFailures(${name})), so a failed relate or reorder is dropped silently`
+      })
+    }
     lints.push(...readBeforeWriteLints(schedules, described, input.externallyWrittenEvents))
+    // Each named schedule is checked as one tick; `tick` checks this at compile time.
+    for (const [name, schedule] of input.schedules) {
+      for (const issue of OrderInternal.tickOrderIssues(schedule.steps)) {
+        lints.push({ severity: "warning", code: "this-tick-order", subject: issue.data, message: `in ${name}, ${issue.message}` })
+      }
+    }
+    // Observed with debug: only systems that ran, so an unplayed session reports nothing.
+    for (const system of systems) {
+      if (!input.ranSystems.has(system.name)) continue
+      const uses = input.commandUses.get(system.name) ?? new Set<string>()
+      for (const kind of Object.keys(permissionVerb) as Array<keyof Debug.CommandPermissions>) {
+        const unused = system.commands[kind].filter((name) => !uses.has(`${kind}:${name}`))
+        if (unused.length === 0) continue
+        lints.push({
+          severity: "info",
+          code: "command-permission-unused",
+          subject: system.name,
+          message: `${system.name} may ${permissionVerb[kind]} ${unused.join(", ")} but never did in this session`
+        })
+      }
+    }
     for (const entry of components.list()) {
       if (entry.writers.length > 0 && entry.readers.every((reader) => entry.writers.includes(reader))) {
         lints.push({
@@ -355,7 +433,29 @@ export const describe = (input: DescribeInput): Debug.Description => {
       resources: resources.list(),
       events: events.list()
     },
-    lints
+    lints: lints.map((lint) => ({ ...lint, fix: fixFor(lint.code, lint.subject) }))
+  }
+}
+
+/** The fix each lint names, by code. */
+const fixFor = (code: Debug.Lint["code"], subject: string): string => {
+  switch (code) {
+    case "event-never-read":
+      return `read ${subject} in a system with Game.System.readEvent, or stop emitting it; if only a render schedule reads it, pass that schedule as describe-only`
+    case "event-never-written":
+      return `emit ${subject} from a system with Game.System.writeEvent, or stop reading it; if the host sends it with runtime.send, declare it (debug.declareHostEvents, or hostEvents in a Session or lint target)`
+    case "next-state-never-applied":
+      return `add Game.Schedule.applyStateTransitions(...) to a schedule that runs after the system that queues ${subject}`
+    case "relation-failure-never-read":
+      return `read the failures with Game.System.readRelationFailures(${subject}) in a system and handle them`
+    case "this-tick-order":
+      return "move the writer before the reader in the schedule (the message names both), or read without Game.System.thisTick"
+    case "component-never-read":
+      return `fine if ${subject} is read outside the described schedules (rendering, inspectors); otherwise stop writing it`
+    case "command-permission-unused":
+      return `fine if the session did not reach the case where ${subject} uses it; otherwise drop the permission from its Game.System.commands(...)`
+    case "read-before-write":
+      return "fine when a one-run lag is intended (input before movement); otherwise move the reader after the writer, or read with Game.System.thisTick to make it an error"
   }
 }
 
@@ -380,8 +480,8 @@ const readBeforeWriteLints = (
   schedules: ReadonlyArray<readonly [string, AnySchedule]>,
   described: ReadonlyMap<AnySystem, Debug.SystemDescription>,
   externallyWrittenEvents: ReadonlySet<string>
-): Array<Debug.Lint> => {
-  const lints: Array<Debug.Lint> = []
+): Array<Omit<Debug.Lint, "fix">> => {
+  const lints: Array<Omit<Debug.Lint, "fix">> = []
   for (const [name, schedule] of schedules) {
     const steps = schedule.steps.flatMap((step) =>
       Schedule.isSystemStep(step) ? [{ system: described.get(step as AnySystem)!, accesses: accessesOf(described.get(step as AnySystem)!) }] : [])

package/src/internal/game.ts

@@ -5,6 +5,7 @@
  * module functions; the precise public types live on `Schema.Game`.
  */
 import * as Command from "../Command.ts"
+import type * as Debug from "../Debug.ts"
 import * as Condition from "../Condition.ts"
 import * as Entity from "../Entity.ts"
 import * as EntityScope from "../EntityScope.ts"
@@ -57,9 +58,8 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
     }),
     Command: {
       spawn: Command.spawn,
-      insert: Command.insert,
+      extend: Command.extend,
       entry: Command.entry,
-      entryResult: Command.entryResult,
       entryRaw: Command.entryRaw,
       relate: Command.relate
     },
@@ -81,6 +81,14 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
         writeResource: System.writeResource,
         readEvent: System.readEvent,
         writeEvent: System.writeEvent,
+        thisTick: System.thisTick,
+        commands: Command.commands,
+        spawns: Command.spawns,
+        inserts: Command.inserts,
+        removes: Command.removes,
+        despawns: Command.despawns,
+        despawnsScope: Command.despawnsScope,
+        relates: Command.relates,
         service: System.service,
         machine: System.machine,
         nextState: System.nextState,
@@ -117,7 +125,7 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
         readonly services: Runtime.RuntimeServices<any>
         readonly resources?: object
         readonly machines?: Runtime.RuntimeMachines<any>
-        readonly debug?: true
+        readonly debug?: Debug.Option
       }) => Runtime.make({ schema, ...options, machineDefinitions: definedMachines } as never),
       service: Runtime.service,
       services: Runtime.services,

package/src/internal/order.ts

@@ -0,0 +1,140 @@
+/**
+ * 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 * 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" | "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<{ readonly descriptor?: Descriptor.Any }>
+}
+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) => filter.descriptor ? [filter.descriptor.name] : [])
+  ])
+  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.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
@@ -143,7 +143,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 })
@@ -255,7 +255,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":

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